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.
6.0 KiB
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
(by @EvanZhouDev), a local reverse proxy
that speaks the same authenticated Codex API as OpenAI's
@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):
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.jsonlike 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.jsoninto\\<host>\share\, or - SSH / Terminal — e.g.
scp ~/.codex/auth.json root@<ha-host>:/share/auth.json
Step 3 — install and start
- Add this repository in Home Assistant
(Settings → Add-ons → Add-on Store → ⋮ → Repositories):
https://git.i3omb.com/gronod/ha-gronod-addons - Install OpenAI Codex Proxy and start it
- Open the add-on Log — it prints the generated local API key:
[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:
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:
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-proxyfrom other add-ons/Home Assistant. /share/auth.jsonis visible to anything with Samba/SSH access to thesharefolder.
Credits
- openai-oauth by @EvanZhouDev (Apache-2.0) — the proxy and Codex OAuth session handling.
- @openai/codex (Apache-2.0) — OpenAI's
Codex CLI, used to produce
auth.jsonand for model discovery.