Metadata-Version: 2.4
Name: codex-api-proxy
Version: 0.1.2
Summary: Local OpenAI-compatible HTTP proxy backed by Codex/OpenAI credentials
Author: codex-api-proxy contributors
License-Expression: MIT
Keywords: codex,openai,proxy,api,local
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx<1,>=0.27
Requires-Dist: uvicorn[standard]<1,>=0.30
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"

# 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

```bash
pip3 install codex-api-proxy
```

For local development from this checkout:

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

## Credentials

The proxy reads Codex credentials from:

```text
~/.codex/auth.json
```

or, when `CODEX_HOME` is set:

```text
$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:

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

## Run

Start in the background:

```bash
codex-api-proxy start
```

Run in the foreground with debug logs:

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

Bind to all interfaces with local bearer auth:

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

Start with an explicit upstream proxy:

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

Restart using the last saved start settings:

```bash
codex-api-proxy restart
```

Stop:

```bash
codex-api-proxy stop
```

Status:

```bash
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_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:

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

Models:

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

Chat completion:

```bash
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:

```bash
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:

```bash
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"}'
```

When `--api-key` is configured:

```bash
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`.
