gronod
58cf62a41f
The models option passed an allowlist to openai-oauth --models but was unrequested and of uncertain upstream effect; remove it entirely. Add translations/en.yaml so the Configuration tab explains that an empty api_key auto-generates a persisted key printed in the log, and that a custom key can be pasted instead. Document a key-generation command in DOCS.md.
155 lines
6.0 KiB
Markdown
155 lines
6.0 KiB
Markdown
# OpenAI Codex Proxy — documentation
|
|
|
|
Full setup, configuration, and troubleshooting for the **OpenAI Codex Proxy**
|
|
Home Assistant add-on.
|
|
|
|
## How it works
|
|
|
|
The add-on runs [openai-oauth](https://github.com/EvanZhouDev/openai-oauth)
|
|
(by [@EvanZhouDev](https://github.com/EvanZhouDev)), a local reverse proxy
|
|
that speaks the same authenticated Codex API as OpenAI's
|
|
[@openai/codex](https://github.com/openai/codex) CLI
|
|
(`chatgpt.com/backend-api/codex`). It exposes an OpenAI-compatible `/v1` API
|
|
backed by your ChatGPT account instead of API credits.
|
|
|
|
Because `openai-oauth` itself has no client authentication, this add-on binds
|
|
it to loopback and publishes a small token-protected proxy on port `10531`.
|
|
Every request must send `Authorization: Bearer <key>` (or `x-api-key`).
|
|
|
|
## Step 1 — generate `auth.json`
|
|
|
|
On a desktop machine with Node.js installed (macOS, Linux, or Windows):
|
|
|
|
```sh
|
|
npx @openai/codex login
|
|
```
|
|
|
|
A browser opens for the ChatGPT sign-in. Afterwards your credentials are at:
|
|
|
|
| OS | Path |
|
|
|---|---|
|
|
| macOS / Linux | `~/.codex/auth.json` |
|
|
| Windows | `%USERPROFILE%\.codex\auth.json` |
|
|
|
|
> Treat `auth.json` like a password — it grants access to your ChatGPT
|
|
> account. Don't commit it, post it, or leave it world-readable.
|
|
|
|
## Step 2 — copy `auth.json` to Home Assistant
|
|
|
|
The add-on reads `/share/auth.json`. Copy the file into the `share` folder on
|
|
your Home Assistant machine using either:
|
|
|
|
* the **Samba share** add-on — drop `auth.json` into `\\<host>\share\`, or
|
|
* **SSH / Terminal** — e.g. `scp ~/.codex/auth.json root@<ha-host>:/share/auth.json`
|
|
|
|
## Step 3 — install and start
|
|
|
|
1. Add this repository in Home Assistant
|
|
(**Settings → Add-ons → Add-on Store → ⋮ → Repositories**):
|
|
`https://git.i3omb.com/gronod/ha-gronod-addons`
|
|
2. Install **OpenAI Codex Proxy** and start it
|
|
3. Open the add-on **Log** — it prints the generated local API key:
|
|
|
|
```text
|
|
[INFO] Generated a new local API key (stored at /config/.api_key)
|
|
[INFO] Local API key: <your-key>
|
|
```
|
|
|
|
If `/share/auth.json` is missing the add-on logs instructions and retries
|
|
every 60 seconds — just copy the file and wait for the restart.
|
|
|
|
## Step 4 — connect an integration
|
|
|
|
Configure your OpenAI-compatible integration with:
|
|
|
|
| Setting | Value |
|
|
|---|---|
|
|
| Base URL | `http://<home-assistant-host>:10531/v1` |
|
|
| API key | the key from the add-on log (or your `api_key` option) |
|
|
|
|
From another add-on or a supervised Home Assistant container you can also use
|
|
the internal DNS name `http://8e663231-openai-codex-proxy:10531/v1`.
|
|
|
|
Quick check from a shell:
|
|
|
|
```sh
|
|
curl http://<ha-host>:10531/v1/models \
|
|
-H "Authorization: Bearer <your-key>"
|
|
```
|
|
|
|
## Options
|
|
|
|
| Option | Default | Description |
|
|
|---|---|---|
|
|
| `api_key` | _(empty)_ | Local API key clients must send. Leave empty and a random key is generated on first start, saved to `/config/.api_key` (it survives restarts), and printed in the add-on log. Paste your own key here if you want to use a fixed value — the saved/generated key is ignored while this option is set. |
|
|
| `log_level` | `INFO` | `DEBUG`, `INFO`, or `WARN` — verbosity of the add-on wrapper. `DEBUG` also enables upstream request logging. |
|
|
| `log_requests` | `false` | Set upstream `CODEX_OPENAI_SERVER_LOG_REQUESTS=1`: emits one JSON line per request (path, status, duration, token usage). |
|
|
|
|
To generate a suitable key yourself, run any of these on a desktop:
|
|
|
|
```sh
|
|
openssl rand -hex 32
|
|
# or, matching the add-on's own generator:
|
|
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
|
|
```
|
|
|
|
then paste the output into the `api_key` option and restart the add-on.
|
|
|
|
The host-side port mapping (`10531`) can be changed or disabled in the
|
|
add-on's **Network** section; the container-internal port stays `10531`.
|
|
|
|
## Endpoints
|
|
|
|
| Path | Method | Purpose |
|
|
|---|---|---|
|
|
| `/v1/responses` | POST | OpenAI Responses API |
|
|
| `/v1/chat/completions` | POST | Chat Completions API |
|
|
| `/v1/models` | GET | Models available to your account |
|
|
| `/v1/images/generations`, `/v1/images/edits` | POST | Image generation/editing |
|
|
| `/health` | GET | Unauthenticated liveness check |
|
|
|
|
All `/v1/*` routes require `Authorization: Bearer <key>`.
|
|
|
|
## Troubleshooting
|
|
|
|
**Log shows `ERROR: /share/auth.json not found!`**
|
|
The file isn't in the `share` folder yet, or has a different name. Copy it as
|
|
described in Step 2 and wait for the automatic restart (60 s).
|
|
|
|
**Requests return `401 authentication_error`**
|
|
Wrong or missing API key. Use the key printed in the add-on log, or set the
|
|
`api_key` option explicitly and restart.
|
|
|
|
**Requests return `502 Upstream not ready`**
|
|
`openai-oauth` is still starting (it resolves your account's model list from
|
|
ChatGPT) or crashed — check the add-on log above the proxy messages.
|
|
|
|
**Responses fail with auth errors after weeks/months**
|
|
OAuth tokens normally refresh automatically and are written back to
|
|
`/share/auth.json`. If the refresh token itself has expired (or you replaced
|
|
`auth.json` with an older copy), re-run `npx @openai/codex login` on your
|
|
desktop and copy the fresh file to `/share` again.
|
|
|
|
**Rate limits / missing models**
|
|
Only models your ChatGPT plan supports appear, and Codex account rate limits
|
|
apply. `openai-oauth` is an unofficial community project; OpenAI may change
|
|
the underlying endpoints at any time.
|
|
|
|
## Security notes
|
|
|
|
* The published port is protected by the local API key — anyone on your LAN
|
|
still needs it to use your ChatGPT account. Keep it secret like a password.
|
|
* To restrict access further, disable the host port mapping and reach the
|
|
add-on only via its internal hostname `8e663231-openai-codex-proxy` from
|
|
other add-ons/Home Assistant.
|
|
* `/share/auth.json` is visible to anything with Samba/SSH access to the
|
|
`share` folder.
|
|
|
|
## Credits
|
|
|
|
* [openai-oauth](https://github.com/EvanZhouDev/openai-oauth) by
|
|
[@EvanZhouDev](https://github.com/EvanZhouDev) (Apache-2.0) — the proxy and
|
|
Codex OAuth session handling.
|
|
* [@openai/codex](https://github.com/openai/codex) (Apache-2.0) — OpenAI's
|
|
Codex CLI, used to produce `auth.json` and for model discovery.
|