OpenCode ↗ 是一个开源编码智能体,支持自定义提供商配置。将其内置提供商指向 AI Gateway,即可观察和控制来自 OpenCode 的模型请求。
开始之前,你需要:
- 一个 AI Gateway 及其 gateway slug。
- 足够的 Unified Billing 积分,或为每个提供商存储带
default别名的提供商密钥。 - 已安装 OpenCode ↗。
要使用此方法,还需要一个已认证的 gateway 及其 gateway 令牌。该令牌必须具有 Run 权限。你还需要 Cloudflare 账户 ID。查找方法请参阅查找账户和 zone ID。
-
将 gateway 令牌设为
CF_AIG_TOKEN环境变量。以下命令为当前会话设置该变量。若要持久化,请将其添加到 shell 配置文件。将
<CF_AIG_TOKEN>替换为你的 gateway 令牌。export CF_AIG_TOKEN="<CF_AIG_TOKEN>"$env:CF_AIG_TOKEN = "<CF_AIG_TOKEN>" -
在项目根目录创建
opencode.json文件。将<ACCOUNT_ID>和<GATEWAY_ID>替换为你的账户 ID 和 gateway slug:opencode.jsonjson { "$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}" } } } } }将每个
apiKey值留空。AI Gateway 会通过 Unified Billing 或已存储的提供商密钥提供凭据。要使用没有default别名的已存储密钥,请将该提供商headers对象中加入cf-aig-byok-alias标头。移除你不使用的提供商。更多配置选项请参阅 OpenCode providers ↗。 -
启动 OpenCode,并选择已配置的提供商和模型:
opencode
要确认流量已到达 AI Gateway,请参阅验证是否生效。
如果 gateway 受 Cloudflare Access 保护,OpenCode 可以使用短期 Access 令牌进行身份验证,而无需 gateway 令牌。你也可以将配置集中托管,让用户通过一条登录命令完成连接。
此设置需要 AI Gateway 自定义域、每位用户设备上的 cloudflared,以及两个配置文件的公开 HTTPS 位置。你可以使用带自定义域的 R2 存储桶。
这些文件包含配置,但不包含凭据。Single Redirect 会将 AI Gateway 自定义域上的 /.well-known/opencode 请求发送到发现文件。
用户可以在全局或项目配置中覆盖远程配置。要强制实施组织范围的设置,请参阅 OpenCode managed settings ↗。
以下示例使用 ai.example.com 作为 AI Gateway 域,使用 config.example.com 作为配置主机。请将这两个主机名替换为你自己的值。
-
在任何 OpenCode 项目之外,复制使用 gateway 令牌连接 中的
opencode.json。将每个提供商的baseURL替换为对应值:提供商 Base URL Anthropic https://ai.example.com/anthropic/v1OpenAI https://ai.example.com/openaiGoogle https://ai.example.com/google-ai-studio/v1betaxAI https://ai.example.com/grok/v1将每个提供商的
headers对象替换为以下值:{ "cf-access-token": "{env:TOKEN}", "X-Requested-With": "XMLHttpRequest" } -
将
opencode.json上传到你的公开 HTTPS 主机。确认其 URL 无需身份验证即可返回预期的 JSON。如果使用 R2,请将该对象上传到存储桶并连接自定义域。示例文件应可在
https://config.example.com/opencode.json访问。不要在项目或全局 OpenCode 配置中保留另一份副本。本地配置优先于远程配置,会阻止后续托管更新生效。
-
创建一个
opencode发现文件。将remote_config.url设为opencode.json的公开 URL:opencodejson { "auth": { "command": [ "cloudflared", "access", "login", "--no-verbose", "-app=https://ai.example.com/" ], "env": "TOKEN" }, "remote_config": { "url": "https://config.example.com/opencode.json" } }OpenCode 会运行身份验证命令,并将其输出作为
{env:TOKEN}提供,然后将该值替换到远程提供商配置中。 -
将
opencode上传到你的公开 HTTPS 主机。确认https://config.example.com/opencode无需身份验证即可返回发现 JSON。 -
在 AI Gateway 自定义域所在的 zone 中,创建 Single Redirect,使用以下设置:
- 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
- Rule name:
-
在没有活动 Access 会话的浏览器中打开
https://ai.example.com/.well-known/opencode。确认请求返回发现 JSON,且不会出现 Access 提示。 -
要连接 OpenCode,请运行:
opencode auth login https://ai.example.com出现提示时完成 Access 登录流程。OpenCode 会在本地存储生成的凭据并加载远程配置。Access 会话过期后再次运行该命令。
-
启动 OpenCode,并选择已配置的提供商和模型:
opencode