OpenCode

Set your gateway token as the CF_AIG_TOKEN environment variable. The following commands set it for the current session. To persist it, add it to your shell profile.

Replace <CF_AIG_TOKEN> with your gateway token.

export CF_AIG_TOKEN="<CF_AIG_TOKEN>"

$env:CF_AIG_TOKEN = "<CF_AIG_TOKEN>"

In your project root, create an opencode.json file. Replace <ACCOUNT_ID> and <GATEWAY_ID> with your account ID and gateway slug:

{
  "$schema": "https://opencode.ai/config.json",
  "share": "disabled",
  "disabled_providers": ["opencode"],
  "enabled_providers": ["anthropic", "openai", "google", "xai"],
  "provider": {
    "anthropic": {
      "name": "Anthropic through Cloudflare AI Gateway",
      "options": {
        "baseURL": "https://gateway.ai.cloudflare.com/v1/<ACCOUNT_ID>/<GATEWAY_ID>/anthropic/v1",
        "apiKey": "",
        "headers": {
          "cf-aig-authorization": "Bearer {env:CF_AIG_TOKEN}"
        }
      }
    },
    "openai": {
      "name": "OpenAI through Cloudflare AI Gateway",
      "options": {
        "baseURL": "https://gateway.ai.cloudflare.com/v1/<ACCOUNT_ID>/<GATEWAY_ID>/openai",
        "apiKey": "",
        "headers": {
          "cf-aig-authorization": "Bearer {env:CF_AIG_TOKEN}"
        }
      }
    },
    "google": {
      "name": "Google AI Studio through Cloudflare AI Gateway",
      "options": {
        "baseURL": "https://gateway.ai.cloudflare.com/v1/<ACCOUNT_ID>/<GATEWAY_ID>/google-ai-studio/v1beta",
        "apiKey": "",
        "headers": {
          "cf-aig-authorization": "Bearer {env:CF_AIG_TOKEN}"
        }
      }
    },
    "xai": {
      "name": "xAI through Cloudflare AI Gateway",
      "options": {
        "baseURL": "https://gateway.ai.cloudflare.com/v1/<ACCOUNT_ID>/<GATEWAY_ID>/grok/v1",
        "apiKey": "",
        "headers": {
          "cf-aig-authorization": "Bearer {env:CF_AIG_TOKEN}"
        }
      }
    }
  }
}

Leave each apiKey value empty. AI Gateway supplies provider credentials through Unified Billing or your stored provider keys. To use a stored key without the default alias, add the cf-aig-byok-alias header to that provider's headers object. Remove providers that you do not use. For more configuration options, refer to OpenCode providers ↗.

Start OpenCode and select a configured provider and model:

opencode

Outside any OpenCode project, create a copy of the opencode.json file from Connect with a gateway token. Replace each provider baseURL with the corresponding value:

Replace each provider's headers object with the following value:

{
  "cf-access-token": "{env:TOKEN}",
  "X-Requested-With": "XMLHttpRequest"
}

Upload opencode.json to your public HTTPS host. Confirm that its URL returns the expected JSON without authentication.

If you use R2, upload the object to the bucket and connect a custom domain. The example file should be available at https://config.example.com/opencode.json.

Do not keep another copy in a project or global OpenCode configuration. Local configuration takes precedence over remote configuration and would prevent later hosted updates from applying.

Create an opencode discovery file. Set remote_config.url to the public URL of the opencode.json file:

{
  "auth": {
    "command": [
      "cloudflared",
      "access",
      "login",
      "--no-verbose",
      "-app=https://ai.example.com/"
    ],
    "env": "TOKEN"
  },
  "remote_config": {
    "url": "https://config.example.com/opencode.json"
  }
}

OpenCode runs the authentication command and makes its output available as {env:TOKEN}. It then substitutes that value into the remote provider configuration.

Upload opencode to your public HTTPS host. Confirm that https://config.example.com/opencode returns the discovery JSON without authentication.

In the zone for your AI Gateway custom domain, create a Single Redirect with these settings:

• Rule name: OpenCode discovery
• Custom filter expression: (http.host eq "ai.example.com" and http.request.uri.path eq "/.well-known/opencode")
• Target URL: https://config.example.com/opencode
• Status code: 302
• Preserve query string: Off

In a browser without an active Access session, open https://ai.example.com/.well-known/opencode. Confirm that the request returns the discovery JSON without an Access prompt.

To connect OpenCode, run:

opencode auth login https://ai.example.com

Complete the Access login flow when prompted. OpenCode stores the resulting credential locally and loads the remote configuration. Run the command again when the Access session expires.

Start OpenCode and select a configured provider and model:

opencode