@pikoloo/codex-proxy 1.0.6

package/docs/API.md

@@ -0,0 +1,289 @@
+# API Reference
+
+## Main Endpoints
+
+### Kilo Routing Settings
+
+The explicit `kilo` model route can be configured to use an alternate provider target such as **MiniMax M2.5** or **Kimi K2.5** when `CODEX_CLAUDE_PROXY_ENABLE_KILO=true` is set. Claude Haiku aliases use OpenAI by default.
+
+```bash
+GET /settings/haiku-model
+
+# Response
+{
+  "success": true,
+  "haikuKiloModel": "minimax/minimax-m2.5:free",
+  "kiloEnabled": false
+}
+```
+
+```bash
+POST /settings/haiku-model
+Content-Type: application/json
+
+{
+  "haikuKiloModel": "minimax-2.5"
+}
+
+# Response
+{
+  "success": true,
+  "haikuKiloModel": "minimax-2.5",
+  "kiloEnabled": true
+}
+```
+
+### Chat Completions (OpenAI-compatible)
+
+```bash
+POST /v1/chat/completions
+Content-Type: application/json
+
+{
+  "model": "gpt-5.5",
+  "messages": [{"role": "user", "content": "Hello"}],
+  "tools": [...],
+  "stream": true
+}
+```
+
+### Messages (Anthropic-compatible)
+
+```bash
+POST /v1/messages
+Content-Type: application/json
+
+{
+  "model": "claude-sonnet-4-5",
+  "max_tokens": 1024,
+  "system": "You are helpful.",
+  "messages": [{"role": "user", "content": "Hello"}],
+  "tools": [...],
+  "stream": true
+}
+```
+
+### Models
+
+```bash
+GET /v1/models
+```
+
+### Token Counting
+
+```bash
+POST /v1/messages/count_tokens
+Content-Type: application/json
+
+{
+  "messages": [...],
+  "tools": [...]
+}
+```
+
+## Account Management
+
+Common endpoints:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/accounts` | GET | List all accounts |
+| `/accounts/status` | GET | Get account status summary |
+| `/accounts/add` | POST | Start OAuth flow (returns URL) |
+| `/accounts/switch` | POST | Switch active account |
+| `/accounts/models` | GET | Get models for account |
+| `/accounts/quota` | GET | Get quota info |
+| `/accounts/quota/all` | GET | Refresh all quotas |
+| `/accounts/usage` | GET | Get usage stats |
+
+(Additional maintenance endpoints exist for token refresh/import/removal; see the source if you need them.)
+
+### Add Account
+
+```bash
+POST /accounts/add
+Content-Type: application/json
+
+# Optional: specify callback port
+{"port": 1455}
+
+# Response
+{
+  "status": "oauth_url",
+  "oauth_url": "https://auth.openai.com/oauth/authorize?...",
+  "callback_port": 1455
+}
+```
+
+### Account Selection Strategy
+
+Requests use the active account only by default. Account rotation settings are inert unless `CODEX_CLAUDE_PROXY_ENABLE_MULTI_ACCOUNT_ROTATION=true` is set.
+
+```bash
+GET /settings/account-strategy
+
+# Response
+{
+  "success": true,
+  "accountStrategy": "sticky",
+  "rotationEnabled": false
+}
+```
+
+### Switch Account
+
+```bash
+POST /accounts/switch
+Content-Type: application/json
+
+{"email": "user@gmail.com"}
+
+# Response
+{"success": true, "message": "Switched to account: user@gmail.com"}
+```
+
+### OAuth Callback
+
+```bash
+GET /auth/callback?code=...&state=...
+```
+
+## Claude CLI Configuration
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/claude/config` | GET | View current config |
+| `/claude/config/proxy` | POST | Configure for proxy |
+| `/claude/config/direct` | POST | Configure for direct API |
+
+### Configure Proxy Mode
+
+```bash
+POST /claude/config/proxy
+
+# Response
+{
+  "success": true,
+  "message": "Claude CLI configured to use proxy at http://localhost:8081",
+  "config": {...}
+}
+```
+
+## Health
+
+```bash
+GET /health
+
+# Response
+{
+  "status": "ok",
+  "total": 2,
+  "active": "active@example.com",
+  "accounts": [...]
+}
+```
+
+## Error Responses
+
+### Authentication Error
+
+```json
+{
+  "type": "error",
+  "error": {
+    "type": "authentication_error",
+    "message": "No active account with valid credentials"
+  }
+}
+```
+
+### Rate Limit Error
+
+```json
+{
+  "type": "error",
+  "error": {
+    "type": "rate_limit_error",
+    "message": "Rate limited: ..."
+  }
+}
+```
+
+## Streaming Events
+
+Anthropic SSE format:
+
+```
+event: message_start
+data: {"type":"message_start","message":{...}}
+
+event: content_block_start
+data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
+
+event: content_block_stop
+data: {"type":"content_block_stop","index":0}
+
+event: message_delta
+data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{...}}
+
+event: message_stop
+data: {"type":"message_stop"}
+
+data: [DONE]
+```
+
+## Tool Calling
+
+### Request with Tools
+
+```json
+{
+  "model": "claude-sonnet-4-5",
+  "messages": [
+    {"role": "user", "content": "What's the weather in Tokyo?"}
+  ],
+  "tools": [{
+    "name": "get_weather",
+    "description": "Get weather for a location",
+    "input_schema": {
+      "type": "object",
+      "properties": {
+        "location": {"type": "string"}
+      },
+      "required": ["location"]
+    }
+  }]
+}
+```
+
+### Response with Tool Use
+
+```json
+{
+  "id": "msg_...",
+  "type": "message",
+  "role": "assistant",
+  "content": [{
+    "type": "tool_use",
+    "id": "toolu_...",
+    "name": "get_weather",
+    "input": {"location": "Tokyo"}
+  }],
+  "stop_reason": "tool_use"
+}
+```
+
+### Tool Result
+
+```json
+{
+  "messages": [
+    {"role": "user", "content": "What's the weather?"},
+    {"role": "assistant", "content": [{"type": "tool_use", "id": "toolu_123", "name": "get_weather", "input": {"location": "Tokyo"}}]},
+    {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_123", "content": "Sunny, 22°C"}]}
+  ]
+}
+```

package/docs/ARCHITECTURE.md

@@ -0,0 +1,129 @@
+# Architecture
+
+## Overview
+
+```
+┌──────────────────┐     ┌─────────────────────┐     ┌────────────────────────────┐
+│   Claude Code    │────▶│  This Proxy Server  │────▶│  ChatGPT Codex backend      │
+│   (Anthropic     │     │  (Anthropic format) │     │  (internal API)             │
+│    API format)   │     │                     │     │                             │
+└──────────────────┘     └─────────────────────┘     └────────────────────────────┘
+                                   │
+                                   ▼
+                         ┌─────────────────────┐
+                         │  Account Manager    │
+                         │  (local storage)    │
+                         │                     │
+                         └─────────────────────┘
+```
+
+## Key Discovery
+
+This proxy forwards requests from Anthropic-compatible clients (like Claude Code) to the ChatGPT Codex backend, handling authentication, format conversion, and streaming.
+
+## Project Structure
+
+```
+codex-proxy/
+├── package.json
+├── README.md
+├── docs/
+│   ├── ARCHITECTURE.md
+│   ├── API.md
+│   ├── OAUTH.md
+│   ├── ACCOUNTS.md
+│   └── CLAUDE_INTEGRATION.md
+├── public/
+│   ├── index.html
+│   ├── css/style.css
+│   └── js/app.js              # Web UI logic
+└── src/
+    ├── index.js               # App entrypoint
+    ├── server.js              # Express server setup
+    ├── routes/api-routes.js   # API route registrations
+    └── ...                    # OAuth, accounts, converters, upstream clients
+```
+
+(See the `src/` directory for the full implementation; this doc focuses on the high-level shape.)
+
+## Module Responsibilities
+
+| File | Purpose |
+|------|---------|
+| `index.js` | Entry point (starts server) |
+| `server.js` | Express server, routes, request handling (CORS restricted) |
+| `routes/api-routes.js` | API route registrations (mounted by server) |
+| `oauth.js` | OAuth 2.0 PKCE flow, token exchange |
+| `account-manager.js` | Account persistence, switching, token refresh |
+| `format-converter.js` | Convert between Anthropic and OpenAI Responses API formats |
+| `response-streamer.js` | Parse SSE events, convert to Anthropic streaming format |
+| `direct-api.js` | HTTP client for ChatGPT backend |
+| `kilo-api.js` | Alternate upstream client |
+| `kilo-format-converter.js` | Anthropic ↔ OpenAI Chat conversion |
+| `kilo-streamer.js` | Streaming adapter |
+| `server-settings.js` | Server-wide settings persistence |
+| `model-api.js` | Fetch models, usage, quota |
+| `claude-config.js` | Read/write Claude Code settings |
+
+## Data Flow
+
+### Request Flow
+
+1. Claude Code sends Anthropic-format request to `/v1/messages`
+2. The proxy maps the requested model to an upstream target
+3. If the mapped path requires ChatGPT auth, the account manager loads/refreshes credentials
+4. Request is converted and sent upstream
+5. Response is streamed back as Anthropic SSE events
+
+### Web UI Account/Quota Flow
+
+1. Web UI loads account list from `/accounts`
+2. Web UI fetches quota snapshots from `/accounts/quota/all`
+3. Quota values are merged into account rows for table + modal views
+4. Remaining quota is rendered from normalized usage percentages
+5. On mobile/tablet, sidebar navigation auto-closes after tab change and account table uses horizontal scrolling
+
+### Format Conversion
+
+**Anthropic → OpenAI Responses API:**
+- `messages` → `input` array with `type: 'message'`
+- `system` → `instructions`
+- `tools` → OpenAI function format
+- `tool_use` → `function_call` input item
+- `tool_result` → `function_call_output` input item
+
+**OpenAI → Anthropic:**
+- `output_text` → `{ type: 'text', text: ... }`
+- `function_call` → `{ type: 'tool_use', id, name, input }`
+- SSE events converted to Anthropic streaming format
+
+## Available Models
+
+| Model | Description |
+|-------|-------------|
+| `gpt-5.5` | Current OpenAI flagship model |
+| `gpt-5.4` | Current lower-cost frontier model |
+| `gpt-5.4-mini` | Current small OpenAI model |
+| `gpt-5.3-codex` | Latest Codex-optimized model |
+| `gpt-5.2` | Older general-purpose frontier model |
+
+## Model Mapping
+
+Claude model names are automatically mapped:
+
+| Claude Model | Codex Model |
+|--------------|-------------|
+| `claude-opus-4-5` | `gpt-5.5` |
+| `claude-sonnet-4-5` | `gpt-5.5` |
+| `claude-haiku-4` | `gpt-5.4-mini` |
+| `kilo` | selected Kilo target, disabled by default |
+
+Kilo routing is explicit and disabled unless `CODEX_CLAUDE_PROXY_ENABLE_KILO=true` is set. The `/settings/haiku-model` endpoints choose the Kilo target used when the requested model is `kilo`.
+
+## Account Selection
+
+The default execution mode is personal local use: `/v1/messages` uses the active account only and does not rotate across configured accounts. Multi-account rotation is disabled unless `CODEX_CLAUDE_PROXY_ENABLE_MULTI_ACCOUNT_ROTATION=true` is set.
+
+## Data Storage
+
+Account and configuration files are stored under your home directory (platform-specific). See `docs/ACCOUNTS.md` and `docs/CLAUDE_INTEGRATION.md` for details.

package/docs/CLAUDE_INTEGRATION.md

@@ -0,0 +1,163 @@
+# Claude Code Integration
+
+## Setup
+
+### Automatic Configuration
+
+```bash
+curl -X POST http://localhost:8081/claude/config/proxy
+```
+
+Updates `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://localhost:8081",
+    "ANTHROPIC_API_KEY": "any-key",
+    "ANTHROPIC_MODEL": "claude-sonnet-4-5",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-5",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4"
+  }
+}
+```
+
+### Manual Configuration
+
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:8081
+export ANTHROPIC_API_KEY=any-key
+claude
+```
+
+## Using Claude Code
+
+When prompted about API key:
+
+```
+Detected a custom API key in your environment
+ANTHROPIC_API_KEY: any-key
+Do you want to use this API key?
+❯ 1. Yes          <-- Choose this
+   2. No (recommended)
+```
+
+## How It Works
+
+### Request Flow
+
+```
+Claude Code (Anthropic format)
+         ↓
+    Proxy Server
+         ↓
+  Format Conversion
+         ↓
+ChatGPT Backend API
+         ↓
+   Response Stream
+         ↓
+  Format Conversion
+         ↓
+Claude Code (Anthropic format)
+```
+
+### Format Conversion
+
+**Anthropic → OpenAI Responses API:**
+
+```javascript
+// Anthropic request
+{
+  "model": "claude-sonnet-4-5",
+  "system": "You are helpful.",
+  "messages": [
+    {"role": "user", "content": "Hello"},
+    {"role": "assistant", "content": [{"type": "tool_use", "id": "t1", "name": "fn", "input": {}}]},
+    {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "t1", "content": "result"}]}
+  ],
+  "tools": [...]
+}
+
+// Converted to OpenAI Responses API
+{
+  "model": "gpt-5.5",
+  "instructions": "You are helpful.",
+  "input": [
+    {"type": "message", "role": "user", "content": "Hello"},
+    {"type": "function_call", "id": "fc_t1", "call_id": "fc_t1", "name": "fn", "arguments": "{}"},
+    {"type": "function_call_output", "call_id": "fc_t1", "output": "result"}
+  ],
+  "tools": [...],
+  "store": false,
+  "stream": true
+}
+```
+
+**Key Conversions:**
+- `system` → `instructions`
+- `messages` → `input` array
+- `tool_use` → `function_call` + `function_call_output` items
+- Tool IDs prefixed with `fc_` for API compatibility
+
+### Streaming Events
+
+OpenAI Responses API → Anthropic SSE:
+
+| OpenAI Event | Anthropic Event |
+|--------------|-----------------|
+| `response.output_item.added` | `message_start`, `content_block_start` |
+| `response.output_text.delta` | `content_block_delta` (text_delta) |
+| `response.function_call_arguments.delta` | `content_block_delta` (input_json_delta) |
+| `response.completed` | `message_delta`, `message_stop` |
+
+## Tool Calling
+
+Works natively via OpenAI Responses API:
+
+1. Claude Code sends tools in Anthropic format
+2. Proxy converts to OpenAI function format
+3. ChatGPT executes and returns function calls
+4. Proxy converts back to Anthropic `tool_use` blocks
+5. Claude Code processes and returns tool results
+
+## View Configuration
+
+```bash
+curl http://localhost:8081/claude/config
+```
+
+## Revert to Direct API
+
+```bash
+curl -X POST http://localhost:8081/claude/config/direct \
+  -H "Content-Type: application/json" \
+  -d '{"apiKey":"sk-ant-..."}'
+```
+
+## Troubleshooting
+
+### Claude Code hangs
+
+1. Check proxy health: `curl http://localhost:8081/health`
+2. Verify config: `cat ~/.claude/settings.json`
+3. Re-configure: `curl -X POST http://localhost:8081/claude/config/proxy`
+
+### "No active account" error
+
+Add an account first:
+
+```bash
+curl -X POST http://localhost:8081/accounts/import
+# or use WebUI
+```
+
+### Tool calls not working
+
+Ensure you're using the direct API mode (not CLI subprocess). Check:
+
+```bash
+curl http://localhost:8081/health
+# Should show accounts with valid tokens
+```

package/docs/OAUTH.md

@@ -0,0 +1,85 @@
+# OAuth Implementation
+
+This proxy uses **OAuth 2.0 with PKCE** for secure authentication with ChatGPT.
+
+## Quick Start
+
+### Desktop (Browser)
+```bash
+codex-proxy accounts add
+```
+
+### Headless/VM (No Browser)
+```bash
+codex-proxy accounts add --no-browser
+```
+
+The legacy `codex-claude-proxy` command remains supported as an alias.
+
+## Headless/VM Workflow
+
+When running on a server without a browser (VM, Docker, SSH):
+
+1. Run the command with `--no-browser`:
+   ```bash
+   codex-proxy accounts add --no-browser
+   ```
+
+2. It prints a URL like:
+   ```
+   https://auth.openai.com/oauth/authorize?response_type=code&...
+   ```
+
+3. Copy the URL and open it in a browser on **any other device** (your laptop, phone, etc.)
+
+4. Complete the ChatGPT login
+
+5. After successful login, you'll be redirected to a localhost URL that looks like:
+   ```
+   http://localhost:1455/auth/callback?code=ABC123...
+   ```
+
+6. Copy that entire URL (or just the `code` parameter) and paste it back in the terminal
+
+7. The proxy exchanges the code for tokens and saves your account
+
+## OAuth Config
+
+- **Client ID**: `app_EMoamEEZ73f0CkXaXp7hrann`
+- **Auth URL**: `https://auth.openai.com/oauth/authorize`
+- **Token URL**: `https://auth.openai.com/oauth/token`
+- **Callback Port**: `1455`
+
+## Features
+
+- **PKCE**: Secure code exchange with SHA256 challenge
+- **Auto-Refresh**: Tokens refresh automatically before expiry
+- **Account Selection**: Uses `prompt=login` so you can choose the account to add
+- **Headless Support**: Works on servers without browsers
+
+## Managing Accounts
+
+```bash
+# List accounts
+codex-proxy accounts list
+
+# Add account (browser)
+codex-proxy accounts add
+
+# Add account (headless)
+codex-proxy accounts add --no-browser
+
+# Clear all accounts
+codex-proxy accounts clear
+```
+
+## Troubleshooting
+
+### "Port already in use"
+The `--no-browser` mode works independently of the server - you can add accounts even while the proxy is running.
+
+### "Invalid state" error
+This happens if you use a code from an old session. Generate a fresh URL and try again.
+
+### Same account keeps getting selected
+Clear cookies at `auth.openai.com` or use a private/incognito window.

package/docs/OPENCLAW.md

@@ -0,0 +1,34 @@
+# Using with OpenClaw
+
+[OpenClaw](https://docs.openclaw.ai/) is an AI agent gateway. This proxy provides the Anthropic-compatible API it needs.
+
+## Quick Integration
+
+1.  **Add Provider** to `~/.openclaw/openclaw.json`:
+    ```json
+    {
+      "codex-proxy": {
+        "baseUrl": "http://127.0.0.1:8081",
+        "apiKey": "test",
+        "api": "anthropic-messages",
+        "models": [
+          { "id": "claude-sonnet-4-5", "name": "GPT-5.5" },
+          { "id": "claude-opus-4-5", "name": "GPT-5.5" },
+          { "id": "gpt-5.3-codex", "name": "GPT-5.3 Codex" }
+        ]
+      }
+    }
+    ```
+2.  **Set Primary Model**:
+    ```bash
+    openclaw models set codex-proxy/claude-sonnet-4-5
+    ```
+
+## Key Benefits
+- **Personal Account Mode**: Proxy uses the active local ChatGPT account by default.
+- **SSE Streaming**: Full real-time response support.
+- **Tool Calling**: Native support for agentic workflows.
+
+## Troubleshooting
+- Use `127.0.0.1` instead of `localhost`.
+- Verify proxy health: `curl http://127.0.0.1:8081/health`.

package/docs/legal.md

@@ -0,0 +1,11 @@
+# Legal
+
+- **Not affiliated with OpenAI or Anthropic.** This is an independent open-source project and is not endorsed by, sponsored by, or affiliated with OpenAI or Anthropic.
+
+- "ChatGPT", "OpenAI", and "Codex" are trademarks of OpenAI.
+
+- "Claude" and "Anthropic" are trademarks of Anthropic PBC.
+
+- "Kilo" and "Kilo Search" are trademarks of their respective owners.
+
+- Software is provided "as is", without warranty. You are responsible for complying with all applicable Terms of Service and Acceptable Use Policies.