codex-api-proxy 0.1.4

Local OpenAI-compatible HTTP proxy backed by Codex/OpenAI credentials

codex-api-proxy

Local OpenAI-compatible HTTP proxy backed by Codex/OpenAI credentials.

The proxy has one runtime path: it reads credentials from ~/.codex/auth.json or CODEX_HOME/auth.json, then forwards requests to the upstream OpenAI/Codex API. It no longer runs local codex exec, starts codex app-server, manages workspaces, or exposes sandbox/agent/fast engine settings.

Product Scope

This package is intentionally narrow:

• expose OpenAI-compatible local endpoints for clients such as OpenClaw;
• reuse the user's existing Codex/OpenAI login credentials;
• support /v1/chat/completions, /v1/responses, and /v1/models;
• convert Chat Completions to Responses API when using ChatGPT Codex credentials;
• otherwise transparently forward OpenAI API-key requests to OpenAI's native /chat/completions.

Out of scope:

• local command execution;
• workspace read/write control;
• Codex sandbox configuration;
• app-server workers;
• simulated tool-call wrapping;
• custom model execution engines.

Tool calls and function calls are handled by the upstream OpenAI-compatible API response, not by local prompt wrapping.

Install

pip3 install codex-api-proxy

For local development from this checkout:

python3 -m pip install -e '.[dev]'

Credentials

The proxy reads Codex credentials from:

~/.codex/auth.json

or, when CODEX_HOME is set:

$CODEX_HOME/auth.json

Supported auth shapes:

• OPENAI_API_KEY: forwarded to https://api.openai.com/v1;
• Codex/ChatGPT tokens.access_token: forwarded to https://chatgpt.com/backend-api/codex.

For Codex/ChatGPT token auth, the proxy refreshes tokens automatically:

• before a request when the access token JWT expires within 5 minutes;
• before a request when last_refresh is older than 8 days and the access token has no parseable expiry;
• after an upstream 401, then it retries the original request once.

Refreshed tokens are written back to auth.json with 0600 permissions when supported by the platform.

Outbound upstream proxy settings are controlled by environment variables:

• CODEX_API_PROXY_HTTPS_PROXY
• HTTPS_PROXY
• https_proxy

When none are set, the proxy defaults to http://127.0.0.1:8118.

You can also set the upstream proxy explicitly at startup:

codex-api-proxy start --proxy=http://127.0.0.1:8118

If the upstream connection passes through a corporate TLS proxy or another endpoint using a private/self-signed certificate chain, point the proxy at a CA bundle that trusts that chain:

• CODEX_API_PROXY_CA_BUNDLE
• REQUESTS_CA_BUNDLE
• SSL_CERT_FILE

For example:

CODEX_API_PROXY_CA_BUNDLE=/path/to/internal-ca-bundle.pem codex-api-proxy start

Run

Start in the background:

codex-api-proxy start

Run in the foreground with debug logs:

codex-api-proxy start --foreground --log-level debug

Bind to all interfaces with local bearer auth:

codex-api-proxy start --host 0.0.0.0 --api-key local-secret

Start with an explicit upstream proxy:

codex-api-proxy start --proxy=http://127.0.0.1:8118

Restart using the last saved start settings:

codex-api-proxy restart

Stop:

codex-api-proxy stop

Status:

codex-api-proxy status --verbose

CLI Options

• --host: bind host, default 127.0.0.1
• --port: bind port, default 8765
• --api-key: require client requests to send Authorization: Bearer <key>
• --proxy: upstream HTTP(S) proxy URL for OpenAI/Codex API calls
• --log-level: debug, info, warning, or error
• --pid-file: daemon pid file, default ~/.codex-api-proxy/codex-api-proxy.pid
• --log-file: daemon log file, default ~/.codex-api-proxy/codex-api-proxy.log
• --state-file: daemon state file, default ~/.codex-api-proxy/codex-api-proxy.state.json
• --foreground: run without daemonizing

Environment variables for the local server:

• CODEX_PROXY_HOST
• CODEX_PROXY_PORT
• CODEX_PROXY_API_KEY
• CODEX_API_PROXY_HTTPS_PROXY
• CODEX_API_PROXY_CA_BUNDLE
• CODEX_PROXY_LOG_LEVEL

Token refresh compatibility variables:

• CODEX_REFRESH_TOKEN_URL_OVERRIDE: override the OAuth refresh endpoint
• CODEX_APP_SERVER_LOGIN_CLIENT_ID: override the OAuth client id

API

Health:

curl -sS http://127.0.0.1:8765/health

Models:

curl -sS http://127.0.0.1:8765/v1/models

Chat completion:

curl -sS http://127.0.0.1:8765/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Reply with exactly: pong"}]}'

Streaming chat completion:

curl -N http://127.0.0.1:8765/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-5.5","stream":true,"messages":[{"role":"user","content":"Reply with exactly: pong"}]}'

Responses API passthrough:

curl -sS http://127.0.0.1:8765/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-5.5","input":"Reply with exactly: pong"}'

Image input through Chat Completions:

BASE64_IMAGE=$(base64 < image.jpg)
curl -sS http://127.0.0.1:8765/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.5",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,'"$BASE64_IMAGE"'",
            "detail": "high"
          }
        }
      ]
    }]
  }'

When using ChatGPT Codex credentials, Chat Completions image parts are converted to Responses API input_image parts. /v1/responses requests are passed through unchanged.

When --api-key is configured:

curl -sS http://127.0.0.1:8765/v1/chat/completions \
  -H 'Authorization: Bearer local-secret' \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Reply with exactly: pong"}]}'

Operations

/health checks that credentials can be loaded and shows the upstream mode without exposing secrets.

/ready is an alias of /health.

/metrics returns local request counters:

• requests_total
• requests_ok
• requests_error
• errors_by_status
• uptime_seconds

When --log-level debug is set, chat completions log input messages and output messages through codex_api_proxy.messages and the daemon's uvicorn.error log stream. Streaming output is logged after the stream finishes. These logs can contain prompt and response data; use debug logging only in trusted environments.

Latency summaries are logged through codex_api_proxy.latency.