Codex OpenAI API

OpenAI-compatible local API gateway powered by Codex CLI and built with Hono.

Prerequisites

• bun (runtime and package manager)
• codex CLI installed and available in your PATH, or configured via CODEX_BIN

Quick Start

1. Install dependencies.

bun install

2. Create your environment file.

cp .env.example .env

3. Start the API server.

bun run start

Default server address: http://127.0.0.1:8787

Endpoints

• GET /health
• GET /v1/models
• GET /v1/models/:model
• POST /v1/chat/completions

Environment Variables

• OPENAI_COMPAT_HOST: Server bind host (default: 127.0.0.1).
• OPENAI_COMPAT_PORT: Server bind port (default: 8787).
• OPENAI_COMPAT_TOKEN: Optional bearer token for /v1/* routes.
• CODEX_BIN: Codex CLI binary name or absolute path (default: codex).
• CODEX_DEFAULT_MODEL: Fallback model when the request does not include model (default: gpt-5-codex).
• CODEX_MODELS: Comma-separated list of models exposed by /v1/models.
• CODEX_REASONING_EFFORT: Reasoning effort for Codex (default: medium; options: none, minimal, low, medium, high, xhigh).
• CODEX_SYSTEM_PROMPT: Default system prompt prepended to each request. You can override it per request with system_prompt.
• CODEX_EXEC_TIMEOUT_MS: Codex execution timeout in milliseconds (default: 180000).
• CODEX_SANDBOX: Codex sandbox mode (default: read-only).

Basic cURL Examples

curl -s http://127.0.0.1:8787/health

curl -s http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-codex",
    "system_prompt": "you are a chatbot. answer directly with code, no tool or filesystem notes.",
    "messages": [
      {"role":"user","content":"write hello world in go"}
    ]
  }'

Inspiration / Sources

• Repository: dorangao/article-scripts/local-routers
• Article: Solo Devs: Build a Local AI Router (OpenAI Compatible) that Uses OpenClaw and Codex OAuth Instead

Contributing

Issues and pull requests are welcome. Please keep changes focused, follow the existing project style, and include clear reproduction steps for bug fixes.

License

This project is licensed under the MIT License. See LICENSE.