From ba776a61e52d647ab35e65c163fa005eee0dfe60 Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Fri, 12 Jun 2026 12:39:16 -0500 Subject: [PATCH] docs(docs/ai-coder/ai-gateway): document ChatGPT provider setup for Codex BYOK (#26348) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/ai-coder/ai-gateway/clients/codex.md | 46 ++++++++++++++++++++++- docs/ai-coder/ai-gateway/providers.md | 21 +++++++++++ 2 files changed, 65 insertions(+), 2 deletions(-) diff --git a/docs/ai-coder/ai-gateway/clients/codex.md b/docs/ai-coder/ai-gateway/clients/codex.md index bc005ae3a0..81a494ce06 100644 --- a/docs/ai-coder/ai-gateway/clients/codex.md +++ b/docs/ai-coder/ai-gateway/clients/codex.md @@ -56,6 +56,11 @@ export CODER_API_TOKEN="" ## BYOK (ChatGPT Subscription) +> [!IMPORTANT] +> This flow requires a [ChatGPT provider](../providers.md#chatgpt) 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`): ```toml @@ -87,16 +92,53 @@ 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](https://registry.coder.com/modules/coder-labs/codex) module: +[Codex CLI](https://registry.coder.com/modules/coder-labs/codex) module. + +For the centralized API key flow, set `enable_ai_gateway`: ```tf module "codex" { source = "registry.coder.com/coder-labs/codex/coder" - version = "~> 4.1" + 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: + +```tf +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](https://developers.openai.com/codex/config-advanced) diff --git a/docs/ai-coder/ai-gateway/providers.md b/docs/ai-coder/ai-gateway/providers.md index 084a3227db..d93d942293 100644 --- a/docs/ai-coder/ai-gateway/providers.md +++ b/docs/ai-coder/ai-gateway/providers.md @@ -123,6 +123,27 @@ OAuth token, so do not attach API keys. For client-side setup (proxy, certificates, IDE configuration), see [GitHub Copilot client configuration](./clients/copilot.md). +### ChatGPT + +ChatGPT subscriptions (Plus, Pro, Business) are supported through a +provider of type `openai` with a specific name and base URL: + +| Field | Value | +|----------|-----------------------------------------| +| Type | `openai` | +| Name | `chatgpt` | +| Base URL | `https://chatgpt.com/backend-api/codex` | + +The name must be exactly `chatgpt`. It determines the route clients use +to reach the provider: `/api/v2/aibridge/chatgpt/v1`. If no provider +with this name exists, requests to that route fail with +`404 route not supported`. + +Do not attach API keys. ChatGPT providers authenticate with each user's +ChatGPT OAuth token through [BYOK](./auth.md#bring-your-own-key-byok), +so BYOK must remain enabled. For client-side setup, see the +[Codex CLI ChatGPT subscription configuration](./clients/codex.md#byok-chatgpt-subscription). + ### OpenAI-compatible providers Azure-hosted OpenAI, Google, OpenRouter, Vercel, and any other