OpenCode Go Proxy

Use your OpenCode Go subscription in the Codex app.

Codex expects a Responses API (/v1/responses). OpenCode Go exposes an OpenAI-compatible
Chat Completions API (/v1/chat/completions). This proxy bridges that gap in one local process:

Codex app
    │
    │  POST /v1/responses (Responses API)
    ▼
opencode-go-proxy  ←── localhost:8787, zero deps, stdlib only
    │
    │  POST /v1/chat/completions (Chat Completions API)
    ▼
OpenCode Go  ────── 13 models: DeepSeek, GLM, Kimi, MiMo, MiniMax, Qwen

Why

OpenCode Go is $5 for the first month, then $10/month. You get access to 13 open coding models
hosted in the US, EU, and Singapore. Codex is a great agent but doesn't speak Chat Completions
natively — it requires Responses-shaped providers. This proxy fixes that.

Quick start

# Install and run
uvx --from git+https://github.com/kartikkabadi/opencode-go-proxy \
  opencode-go-proxy \
  --bind 127.0.0.1 \
  --port 8787

# Point Codex at it (~/.codex/config.toml)

[model_providers.opencode-go]
name = "OpenCode Go"
base_url = "http://127.0.0.1:8787/v1"
experimental_bearer_token = "any-string-here"
wire_api = "responses"

[profiles.deepseek-v4-flash]
model_provider = "opencode-go"
model = "deepseek-v4-flash"
model_context_window = 1000000
approval_policy = "untrusted"
sandbox_mode = "workspace-write"
features = { memories = false }

# Start Codex with a profile
codex -p deepseek-v4-flash

Available models

All 13 OpenCode Go models work through this proxy. The defaults are DeepSeek V4 Flash
(cheapest general-purpose) and MiMo V2.5 (cheapest vision, used for image captioning).
Switch to whatever you want — just change the model in your Codex profile.

Request counts are estimates from OpenCode Go docs based on
typical usage patterns. Cheaper models = more requests per month.

Switching models

Just create another profile and use codex -p <profile-name>:

[profiles.deepseek-v4-pro]
model_provider = "opencode-go"
model = "deepseek-v4-pro"
model_context_window = 1000000
approval_policy = "untrusted"
sandbox_mode = "workspace-write"
features = { memories = false }

[profiles.glm-5.2]
model_provider = "opencode-go"
model = "glm-5.2"
model_context_window = 272000
approval_policy = "untrusted"
sandbox_mode = "workspace-write"
features = { memories = false }

[profiles.kimi-k2.7-code]
model_provider = "opencode-go"
model = "kimi-k2.7-code"
model_context_window = 272000
approval_policy = "untrusted"
sandbox_mode = "workspace-write"
features = { memories = false }

codex -p deepseek-v4-pro
codex -p glm-5.2
codex -p kimi-k2.7-code

How the default model is chosen

The proxy picks the upstream model based on what Codex sends:

1. If the model slug is in the alias map, it's mapped
   (e.g. gpt-5.5 → deepseek-v4-pro).
2. If the model slug is a known OpenCode Go model (from the catalog), it's used as-is.
3. Otherwise, it falls back to deepseek-v4-flash.

When images are present in a turn with tools, the proxy routes to MiMo V2.5 for image
captioning (it's the cheapest vision model on Go), then routes the main turn to your
configured model. Override the vision model with CODEX_IMAGE_MODEL.

API key

The proxy resolves your OpenCode Go API key in this order:

1. $OPENCODE_GO_API_KEY environment variable
2. macOS keychain entry opencode-go-api-key (override with CODEX_KEYCHAIN_SERVICE; macOS only)

# Option 1: env var (works everywhere)
export OPENCODE_GO_API_KEY="your-key-here"

# Option 2: macOS keychain (macOS only)
security add-generic-password -a "$USER" -s opencode-go-api-key -w

Get your API key from OpenCode Zen after subscribing to Go.

Recommended: lazycodex

lazycodex is a Codex plugin that adds
multi-model orchestration, parallel background agents, and LSP/AST-aware tools. It pairs
naturally with this proxy — you get OpenCode Go's models as the backend and lazycodex's
agent harness on top.

npm install -g lazycodex-ai

See the lazycodex docs for setup.

Features

• Responses input to chat messages translation
• instructions and developer roles mapped to system messages
• Function tool schema passthrough
• Custom/freeform tool adaptation (Codex apply_patch works)
• Reasoning content replay across tool-call turns
• Real-time SSE streaming (not synthesized)
• Image captioning via MiMo V2.5 when tools are present (override with CODEX_IMAGE_MODEL)
• SSRF protection on image URLs (data:image/ and https:// only)
• Configurable body cap, bind address guard, keychain credential resolution
• Local health and model-list endpoints

Install

From source (no package manager)

uvx --from git+https://github.com/kartikkabadi/opencode-go-proxy opencode-go-proxy --help

From a development checkout

uv sync
uv run opencode-go-proxy --help

macOS (launchd)

A launchd plist is included at contrib/launchd/com.opencode-go.proxy.plist.
Copy it to ~/Library/LaunchAgents/ and load:

mkdir -p ~/Library/LaunchAgents ~/.codex/logs
cp contrib/launchd/com.opencode-go.proxy.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.opencode-go.proxy.plist

The proxy is designed for launchd's KeepAlive — it restarts on crash and
starts at login. Logs go to ~/.codex/logs/opencode-go-proxy.{log,err}.

Configuration

All flags have environment variable defaults:

The proxy accepts both /responses and /v1/responses.

Model catalog

Without a catalog entry, Codex prints a model metadata warning every turn. A reference catalog
with all OpenCode Go models is included at contrib/opencode-go-catalog.json. Copy it to the
proxy's default catalog path so /models works out of the box:

mkdir -p ~/.codex/model-catalogs
cp contrib/opencode-go-catalog.json ~/.codex/model-catalogs/opencode-go.json

model_catalog_json = "/home/you/.codex/model-catalogs/opencode-go.json"

The catalog ships with the ModelsCache wrapper (fetched_at/etag/client_version/models).
Codex 0.142+ desktop app requires all four top-level fields — a bare {"models": [...]} catalog
causes the model picker to fall back to "Custom" instead of showing the full list. The CLI
(codex debug models) tolerates the bare format, so this only surfaces in the desktop app.

If you want Codex's full base_instructions for each model, copy your Codex installation's
bundled models.json and append the OpenCode Go entries from the reference catalog (keep the
ModelsCache wrapper).

Trace

Every request emits compact JSON lines on stderr. Important events:

• server.start
• request.received
• request.converted
• credential.source
• upstream.start
• upstream.done
• response.converted
• request.failed

Troubleshooting

Model metadata warning every turn
Set model_catalog_json in Codex config and copy the reference catalog:
cp contrib/opencode-go-catalog.json ~/.codex/model-catalogs/opencode-go.json

Connection refused on localhost:8787
Proxy isn't running. Start it: opencode-go-proxy or check launchctl list | grep opencode.

API key not found
Set OPENCODE_GO_API_KEY env var or add to macOS keychain:
security add-generic-password -a "$USER" -s opencode-go-api-key -w

Upstream rate limited (429)
OpenCode Go has 5-hour/weekly/monthly usage limits. Switch to a cheaper model (DeepSeek V4 Flash or MiMo V2.5) to stretch your quota. See usage limits.

Streaming not working
Codex sends stream: true — the proxy handles this. If you see no SSE events, check stderr trace for upstream.error or upstream.network_error.

Codex says "model is not supported when using ChatGPT account"
You used codex -m deepseek-v4-flash instead of codex -p deepseek-v4-flash. The -m flag only changes the model name, not the provider. Use -p to select a profile.

Development

uv run python -m pytest tests -v
uvx ruff check
uv build

See CONTRIBUTING.md for guidelines.

License

MIT. See LICENSE.