mirror of https://github.com/coder/coder.git synced 2026-11-07 21:29:37 +08:00

Files

T

Ben Potter ba776a61e5 docs(docs/ai-coder/ai-gateway): document ChatGPT provider setup for Codex BYOK (#26348 )

Following the BYOK (ChatGPT Subscription) instructions in `codex.md` on
a deployment without a ChatGPT provider fails with `404 route not
supported: POST /chatgpt/v1/responses`. The
`/api/v2/aibridge/chatgpt/v1` route only exists when an admin has
created a provider named `chatgpt`, and that requirement wasn't
documented anywhere.

## Changes

- `providers.md`: new **ChatGPT** subsection alongside the other
per-provider sections: type `openai`, name must be exactly `chatgpt`,
base URL `https://chatgpt.com/backend-api/codex`, no API keys (auth
comes from each user's ChatGPT OAuth token via BYOK)
- `codex.md`:
- prerequisite admonition in the ChatGPT Subscription section linking to
the provider setup, with the 404 symptom for troubleshooting
- template recipe for the ChatGPT subscription flow (`base_config_toml`
+ `coder_env` injecting `CODER_API_TOKEN`), since the existing recipe
only covers the centralized API key flow
  - bump the codex module pin from `~> 4.1` to `~> 5.0` (latest is 5.1)

## Verification

- All three gaps were hit and the documented configuration verified
end-to-end on a live deployment: provider created via the AI Providers
API, Codex CLI 0.139.0 authenticated with ChatGPT login, sessions
visible in the AI Sessions UI
- `pnpm run format-docs` and `pnpm run lint-docs` clean (0 errors),
`pre-commit-light` hooks passed

Linear: [DOCS-354](https://linear.app/codercom/issue/DOCS-354)

🤖 Generated with Coder Agents on behalf of @bpmct

2026-06-12 12:39:16 -05:00

4.3 KiB

Raw Blame History

Codex CLI

Note

AI Gateway requires the AI Governance Add-On. As of Coder v2.32, deployments without the add-on will not be able to access AI Gateway.

Codex CLI can be configured to use AI Gateway by setting up a custom model provider.

Centralized API Key

To configure Codex CLI to use AI Gateway, set the following configuration options in your Codex configuration file (e.g., ~/.codex/config.toml):

model_provider = "ai_gateway"

[model_providers.ai_gateway]
name = "AI Gateway"
base_url = "<your-deployment-url>/api/v2/aibridge/openai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

To authenticate with AI Gateway, get your Coder API token and set it in your environment:

export OPENAI_API_KEY="<your-coder-api-token>"

Run Codex as usual. It will automatically use the ai_gateway model provider from your configuration.

BYOK (Personal API Key)

Add the following to your Codex configuration file (e.g., ~/.codex/config.toml):

model_provider = "ai_gateway"

[model_providers.ai_gateway]
name = "AI Gateway"
base_url = "<your-deployment-url>/api/v2/aibridge/openai/v1"
wire_api = "responses"
requires_openai_auth = true
env_http_headers = { "X-Coder-AI-Governance-Token" = "CODER_API_TOKEN" }

Set both environment variables:

# Your personal OpenAI API key, forwarded to OpenAI.
export OPENAI_API_KEY="<your-openai-api-key>"

# Your Coder API token, used for authentication with AI Gateway.
export CODER_API_TOKEN="<your-coder-api-token>"

BYOK (ChatGPT Subscription)

Important

This flow requires a ChatGPT provider on the deployment. Without it, Codex requests fail with 404 route not supported: POST /chatgpt/v1/responses.

Add the following to your Codex configuration file (e.g., ~/.codex/config.toml):

model_provider = "ai_gateway"

[model_providers.ai_gateway]
name = "AI Gateway"
base_url = "<your-deployment-url>/api/v2/aibridge/chatgpt/v1"
wire_api = "responses"
requires_openai_auth = true
env_http_headers = { "X-Coder-AI-Governance-Token" = "CODER_API_TOKEN" }

Note

The base_url uses /aibridge/chatgpt/v1 instead of /aibridge/openai/v1 to route requests through the ChatGPT provider.

Set your Coder API token and ensure OPENAI_API_KEY is not set:

# Your Coder API token, used for authentication with AI Gateway.
export CODER_API_TOKEN="<your-coder-api-token>"

# Ensure no OpenAI API key is set so Codex uses ChatGPT login instead.
unset OPENAI_API_KEY

When you run Codex, it will prompt you to log in with your ChatGPT account.

Pre-configuring in Templates

If configuring within a Coder workspace, you can use the Codex CLI module.

For the centralized API key flow, set enable_ai_gateway:

module "codex" {
  source            = "registry.coder.com/coder-labs/codex/coder"
  version           = "~> 5.0"
  agent_id          = coder_agent.main.id
  workdir           = "/path/to/project"  # Set to your project directory
  enable_ai_gateway = true
}

For the ChatGPT subscription flow, pass the provider configuration through base_config_toml and inject the Coder API token with a coder_env resource. Users authenticate by running codex login with their ChatGPT account:

resource "coder_env" "coder_api_token" {
  agent_id = coder_agent.main.id
  name     = "CODER_API_TOKEN"
  value    = data.coder_workspace_owner.me.session_token
}

module "codex" {
  source   = "registry.coder.com/coder-labs/codex/coder"
  version  = "~> 5.0"
  agent_id = coder_agent.main.id
  workdir  = "/path/to/project" # Set to your project directory

  base_config_toml = <<-TOML
    model_provider = "ai_gateway"

    [model_providers.ai_gateway]
    name = "AI Gateway"
    base_url = "${data.coder_workspace.me.access_url}/api/v2/aibridge/chatgpt/v1"
    wire_api = "responses"
    requires_openai_auth = true
    env_http_headers = { "X-Coder-AI-Governance-Token" = "CODER_API_TOKEN" }
  TOML
}

Do not set OPENAI_API_KEY in the workspace when using the ChatGPT subscription flow, or Codex authenticates with the API key instead of the ChatGPT login.

References: Codex CLI Configuration

4.3 KiB Raw Blame History