第13章 AI提供商配置与管理指南
Providers
OpenCode 内置了一个来自 models.dev 的 provider 和模型目录。对于大多数 provider,你通常先连接账号,然后再选择模型。
运行 `/connect`,选择一个 provider 并输入其凭据。然后运行 `/models` 以选择其中一个模型。 /connect /models
OpenCode Go 是一项订阅服务,使用 OpenCode 团队测试过的编码模型。你只需在控制台完成订阅,复制你的 API key,然后以 OpenCode Go 的身份连接即可。 /connect # 选择 OpenCode Go,然后粘贴 API key。 /models 有关使用限制、端点和隐私详情,请参阅 Go 指南。
你可以通过 ChatGPT Plus 或 Pro 计划替代 OpenAI API key。先连接 OpenAI,然后选择 Sign in with ChatGPT 或其中一种较旧的 Codex 登录方法。这些使用量会消耗你计划内的配额,因此这些模型不会额外计费。 /connect /models
默认情况下,OpenCode 会为这些登录方式设置上下文窗口上限,低于模型的实际上限。这些上限与 Codex 的默认值一致,以确保你计划内的使用速率与在其他 OpenAI 产品中相似。 模型 | 输入限制 GPT-6.1 Sol 及更新的版本 | 500,000 旧版模型 | 272,000 如果不想使用这个上限,请在配置中关闭相应的 plugin。`-` 前缀表示关闭一个内置 plugin;其他所有 plugin 保持启用。 opencode.jsonc { "plugins": ["-opencode.provider.openai-context-caps"], }
当目录中尚无其 API 时,添加一个 provider。例如,以下兼容 OpenAI 的示例同时定义了凭据、运行时 package、endpoint 以及第一个模型。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "acme": { "name": "Acme", "env": ["ACME_API_KEY"], "package": "@opencode/ai/providers/openai-compatible", "settings": { "baseURL": "https://llm.acme.example/v1", }, "models": { "qwen3-coder": { "name": "Qwen 3 Coder", }, }, }, }, } `providers` 对象以 provider ID(`acme/qwen3-coder` 中引用的形式)作为键。
字段 | 用途 name | 显示名。 env | 可以用作凭据的有序环境变量名。 package | 运行时 provider package。 canonical | 要继承目录默认值的内置 provider ID。 compatibility | 该 provider 所有模型共享的 API 特性。详见 Compatibility。 settings | 传给运行时 package 的带类型 OpenCode 控件和 JSON 选项。 headers | 附加在 HTTP 请求上的字符串值 header。 body | 合并到每个请求体中的 JSON 字段。 models | 以 OpenCode 模型 ID 为键添加或覆盖的模型。
覆盖 `settings.baseURL` 以通过代理或兼容 endpoint 发送某个 catalog provider 的请求。它仍然会应用该 provider 现有的 package、model 及连接设置。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "anthropic": { "settings": { "baseURL": "https://llm-proxy.example.com/anthropic", }, }, }, } `settings` 是针对 package 的,只有当所选 package 支持某个字段时,该字段才会产生作用。
使用 `headers` 附加 HTTP 请求头;使用 `body` 合并需要出现在所有请求体中的 JSON 字段。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "openai": { "headers": { "X-Gateway-Tenant": "engineering", }, "body": { "metadata": { "application": "opencode", }, }, }, }, } 这两个字段也可以在 model 或 variant 级别进行设置——如果只需要覆盖该 provider 流量的一部分场景。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "openai": { "models": { "gpt-6.1-sol": { "headers": { "X-Model-Tier": "coding" }, "variants": [ { "id": "batch", "body": { "service_tier": "flex" }, }, ], }, }, }, }, }
HTTP 请求最多等待 5 分钟以获取响应 header,两个 streaming 响应包之间最多等待 15 分钟。将 provider 的 `settings.headerTimeout` 或 `settings.chunkTimeout` 设为一个表示毫秒的数值,可以调整对应上限;设为 `false` 可以禁用它们。`settings.timeout` 还会限制整个请求从发送到响应完成之间的总时长;默认无上限。这些配置项在 provider 范围内全局生效,而不会针对 model 或 variant。在 WebSocket 传输中,`chunkTimeout` 会限定帧与帧之间的间隔,默认值为 30 分钟。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "anthropic": { "settings": { "headerTimeout": 600000, "chunkTimeout": false, }, }, }, } 当请求超过以上任一限制时,会以传输层错误的方式失败。OpenCode 会重试超时的请求,最多尝试 3 次。
`settings.encoding` 以 `"zstd"` 或 `"gzip"` 压缩 HTTP 请求体;使用 `"none"` 则发送普通 JSON。你可以将 `encoding` 设置在 provider、model 或 variant 上;最具体的配置项优先生效。只能启用 endpoint 能够解码的编码方式——大多数 provider 和网关都会拒绝压缩的请求体。当你通过 ChatGPT 登录且没有自定义 `baseURL` 时,OpenAI 默认使用 `"zstd"`;API key 请求发送普通 JSON。WebSocket 消息不受影响。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "openai": { "settings": { "encoding": "none" }, }, }, }
`package` 字段决定与 provider 通信的运行时。对于实现了 OpenAI 请求格式(但并非原生 OpenAI 服务)的 API,请使用兼容 runtime。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "acme": { "package": "@opencode/ai/providers/openai-compatible", "settings": { "baseURL": "https://llm.acme.example/v1", }, "models": { "qwen3-coder": {}, }, }, }, } 原生 package 选项包括:
@opencode/ai/providers/openai @opencode/ai/providers/openai/chat @opencode/ai/providers/openai/responses @opencode/ai/providers/openai-compatible @opencode/ai/providers/openai-compatible/responses @opencode/ai/providers/anthropic @opencode/ai/providers/anthropic-compatible @opencode/ai/providers/google @opencode/ai/providers/google-vertex @opencode/ai/providers/google-vertex/gemini @opencode/ai/providers/google-vertex/chat @opencode/ai/providers/google-vertex/responses @opencode/ai/providers/google-vertex/messages @opencode/ai/providers/azure @opencode/ai/providers/azure/chat @opencode/ai/providers/azure/responses @opencode/ai/providers/amazon-bedrock @opencode/ai/providers/amazon-bedrock/mantle @opencode/ai/providers/amazon-bedrock/mantle/chat @opencode/ai/providers/amazon-bedrock/mantle/messages @opencode/ai/providers/amazon-bedrock/mantle/responses @opencode/ai/providers/openrouter @opencode/ai/providers/xai
你还可以使用诸如 `@acme/opencode-provider` 之类的 npm package,或者使用 `file://` 绝对路径指向本地 package。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "acme": { "package": "@acme/opencode-provider", "models": { "acme-coder": {} }, }, }, }
在 provider 的 `models` 映射中添加或覆盖模型。键是 OpenCode 使用的模型 ID;`modelID` 则是发给 provider 的 ID。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "model": "openai/coding", "providers": { "openai": { "models": { "coding": { "modelID": "gpt-6.1-sol", "name": "GPT-6.1 Sol Coding", }, }, }, }, } 字段 | 用途 modelID | 发给 provider 的模型或部署 ID。 name | 显示名。 family | 用于将相关模型分组。 type | 模型输出的内容类型,例如 `chat`、`image` 或 `decision`;默认为 `chat`,仅 `chat` 模型可用于会话。 releaseDate | 发布日期,格式为 `YYYY-MM-DD` 或 `YYYY-MM`。 package | 该模型级别的运行时覆盖。 settings | 模型级别的 OpenCode 控件与 package 特有的 JSON 设置。 headers | 附加的字符串值请求头。 body | 附加到请求体的 JSON 字段。 capabilities | 工具支持、接受的输入与输出媒体类型、temperature 支持,以及推理控制。 compatibility | 该模型特有的 API 特性,优先级高于 provider 级别。详见 Compatibility。 variants | 带有自身 settings、headers 与 body 的命名变体。 cost | 输入、输出及可选的缓存定价(以百万 token 为单位)。 limit | 上下文、输入及输出的 token 上限。 disabled | 设为 `true` 时,从模型选择列表中移除。
有关选择、默认值、能力、限制、费用与变体的说明,请参阅 Models。
Azure 的标准 catalog endpoint 在凭据之外还需要一个 resource name。只需在 settings 中一次配置 `resourceName`,然后连接一个 API key,或者使用 Azure CLI 中的 Microsoft Entra ID 会话,详情请参见 Provider accounts。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "azure": { "settings": { "resourceName": "my-models", }, }, }, } 你可以在 Azure 门户或 Microsoft Foundry 中找到 Resource name。它也是诸如 `https://my-models.openai.azure.com/` 或 `https://my-models.services.ai.azure.com/` 这些 endpoint 的第一部分。 Terminal az cognitiveservices account list \ --query "[].{name:name,resourceGroup:resourceGroup}" \ --output table
如要使用 Entra ID,请先安装 Azure CLI 并登录,随后在连接 Azure 时选择 Microsoft Entra ID (Azure CLI)。 Terminal az login
如果配置或环境中尚未指定 resource name,请在连接时输入。一旦 resource name 与连接保存在一起,它优先于配置;再次连接可以修改它。
使用 Azure CLI 时,OpenCode 默认使用 CLI 当前所选的账号;如需访问其他 tenant 或 subscription 中的资源,请显式指定二者。 Terminal az login --tenant TENANT_ID az account set --subscription NAME_OR_ID
作为配置项的替代方案,`AZURE_RESOURCE_NAME` 可以直接将 resource name 提供给 OpenCode server。旧版本的 `AZURE_COGNITIVE_SERVICES_RESOURCE_NAME` 变量也同样有效。
由于 Azure 只能通过 deployment 提供模型,OpenCode 会将你资源的 deployment 列表显示出来,而非展示整个 Azure catalog。该列表会在启动后、连接后以及切换账号后在后台重新加载。如果你后来又添加了 deployment,只需重启 OpenCode 或重新连接即可。
在某个连接的部署列表加载完成之前,或者如果加载失败,则整个 catalog 保持可用。
若在同一连接上重新加载失败,则保留上一次的完整 inventory。切换账号时,永远不显示上一个账号的 inventory;新账号从整个 catalog 开始。
Deployment 从其所属的 catalog model 继承限制、费用和能力。
Deployment 名称即模型 ID,且统一使用小写——因为 Azure 在命名时不区分大小写——例如 `azure/gpt-production`。若 deployment 以它所属的 model 命名(如 `gpt-6-luna`),则保留 catalog ID。这些 ID 在增删 deployment 时保持稳定。
OpenCode 通过 deployment 所部署的 model,或在 Azure 的拼写与 catalog 不同(例如 `gpt-4` 对应 GPT-4 Turbo)时通过名称匹配,将 deployment 与 catalog 关联。若一个 deployment 以另一个 model 命名(例如将 `gpt-6-luna` 部署为 `gpt-6.1-sol`),则 UI 显示该 model 的名称、限制与费用。
使用 Azure CLI 时,OpenCode 通过 Azure management API 列出 deployment,这需要对该资源具有读取权限。若调用失败,或者在使用 API key 的场景下,则回退到资源对应的传统 deployment inventory。Discovery 过程会读完所有页后才输出列表。若自定义了 `settings.baseURL`,则 catalog 保持可用。
当某个 model 不在 catalog 中(例如微调模型)时,或需要手动将某个模型 ID 映射到某个 deployment,请显式配置该 deployment。OpenCode 会对这种 deployment 记录警告日志。显式配置的模型始终保留。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "azure": { "models": { "gpt-6-luna": { "modelID": "gpt-production", }, }, }, }, } 你的身份需要以下角色之一:
- 对于 Azure OpenAI 模型:Cognitive Services OpenAI User。 - 对于其他 Foundry 模型:Cognitive Services User。
若请求使用了错误 tenant 的 token,请以所需 tenant 重新登录。 Terminal az login --tenant TENANT_ID
Amazon Bedrock 使用 AWS 默认 credential chain。最简单、最持久的配置方式是使用命名 AWS profile;OpenCode 同时识别 access-key 环境变量、web identity token 及容器 credentials。 Terminal aws configure sso --profile work aws sso login --profile work
在 provider 的 settings 中指定 profile 和 region。只要配置了 profile、`AWS_PROFILE`、`AWS_ACCESS_KEY_ID`、web identity token 文件,或容器 credentials URI 中的任意一种,provider 即可被激活;仅指定 region 不够。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "amazon-bedrock": { "settings": { "profile": "work", "region": "us-west-2", }, }, }, } 若未显式指定 region,OpenCode 按顺序使用 `AWS_REGION`、`AWS_DEFAULT_REGION`,最终默认 `us-east-1`。若使用私有或 VPC endpoint,只需保持同一 profile 和 region,并设置 `baseURL` 即可。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "amazon-bedrock": { "settings": { "profile": "work", "region": "us-west-2", "baseURL": "https://bedrock-runtime.vpce.example.com", }, }, }, } Bedrock API key 使用环境变量 `AWS_BEARER_TOKEN_BEDROCK`。其他 AWS 变量仅作为 SigV4 的输入,不会被存储为 OpenCode API key 账号。
Google Vertex 使用 Application Default Credentials(ADC),且模型在使用前必须指定 project。创建本地 ADC,然后在 provider settings 中指定 project 与 location。 Terminal gcloud auth application-default login opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "google-vertex": { "settings": { "project": "my-project", "location": "us-central1", }, }, }, } OpenCode 也会按顺序解析环境变量中的 project:`GOOGLE_VERTEX_PROJECT`、`GOOGLE_CLOUD_PROJECT`、`GCP_PROJECT`,`GCLOUD_PROJECT`。location 的解析顺序为:`GOOGLE_VERTEX_LOCATION`、`GOOGLE_CLOUD_LOCATION`、`VERTEX_LOCATION`;默认 `us-central1`。 Terminal GOOGLE_CLOUD_PROJECT=my-project GOOGLE_VERTEX_LOCATION=europe-west4 opencode --standalone
Service accounts 走同样的 ADC 流程。将 `GOOGLE_APPLICATION_CREDENTIALS` 指向 service-account JSON 文件,同时通过 settings 或上述任意一个 project 变量提供 project。 Terminal GOOGLE_APPLICATION_CREDENTIALS=/secure/vertex.json \ GOOGLE_CLOUD_PROJECT=my-project \ opencode --standalone
Gemini、Anthropic 及兼容 OpenAI 的 Vertex catalog 模型,均使用同一个 `google-vertex` provider ID。V2 中已弃用旧版的 `google-vertex-anthropic` provider ID。
GitHub Copilot 使用 device OAuth 流程,而非手动输入 API key。连接 GitHub Copilot,选择 GitHub.com 或 GitHub Enterprise,完成设备流程,然后打开 `/models`。 /connect # 选择 GitHub Copilot,然后选择 Login with GitHub Copilot。 /models
连接 GitHub Enterprise 时,若系统提示,请输入部署 URL 或域名。若 GitHub 返回对应的 Copilot API endpoint,OpenCode 会使用它;否则从企业域名推导。 company.ghe.com
连接的账号需要具有 Copilot Chat 访问权限。若 GitHub 报告你无权限,请注册 Copilot Free,或请组织方为你分配一个 Copilot 席位,然后重新连接。OpenCode 会在登录后以及当前活跃的 Copilot 账号变化时拉取该账号的模型列表。
启动 Ollama 并拉取模型。OpenCode 会探测 `http://127.0.0.1:11434`,发现可用的 completion 模型,并将其加入 `/models`——整个过程无需建立账号连接。 Terminal ollama serve ollama pull qwen3:8b
通过 `settings.baseURL` 指向远程或代理的 Ollama server。路径中需包含 `/v1`,OpenCode 将据此推导原生的 `/api/tags` 与 `/api/show` discovery 路径。`apiKey` 为可选字段;设置后会作为 bearer token 加入 discovery 和 model 请求。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "ollama": { "settings": { "baseURL": "https://ollama.example.com/v1", "apiKey": "{env:OLLAMA_API_KEY}", }, }, }, } Discovery 会周期性刷新;若出现临时故障,系统保留上一次成功获取的 inventory。OpenCode 仅添加其 Ollama metadata 中包含 completion 能力的模型;因此仅支持 embedding 的模型不会显示。
LM Studio 与 vLLM 也内置了本地发现功能。它们的默认 endpoint 分别为 `http://127.0.0.1:1234/v1` 与 `http://127.0.0.1:8000/v1`。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "lmstudio": { "settings": { "baseURL": "http://gpu-host:1234/v1" }, }, "vllm": { "settings": { "baseURL": "http://gpu-host:8000/v1" }, }, }, } LM Studio 通过 `/api/v1/models` 发现语言模型;vLLM 先检查 `/health`,然后再读取 `/v1/models`。由于 vLLM 的 discovery 无法推断工具支持,所以已发现的 vLLM 模型默认关闭 tools。若要接入其他兼容 OpenAI 的 runtime,请采用自定义 provider 的方式,并显式列出其模型。
OpenRouter 使用自身的原生 runtime 与 catalog。将 `OPENROUTER_API_KEY` 提供给 OpenCode server,或连接一个 OpenRouter 账号,然后在 provider 前缀后使用完整的 OpenRouter 模型 ID 引用模型。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "model": "openrouter/anthropic/claude-sonnet-5.5", }
若需覆盖 endpoint 或通过兼容 OpenRouter 的网关路由,请保留原生的 OpenRouter package。这样可保持 OpenRouter 的请求与 reasoning 行为。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "openrouter": { "settings": { "baseURL": "https://openrouter-gateway.example.com/api/v1", }, "headers": { "X-Gateway-Tenant": "engineering", }, }, }, } 若网关暴露兼容 OpenAI 的 API,但有自己独立的模型 inventory,请定义一个自定义 provider。此时配置 key 成为 provider 前缀,`models` 的每个 key 成为可选模型 ID。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "model": "company/coder", "providers": { "company": { "env": ["COMPANY_GATEWAY_KEY"], "package": "@opencode/ai/providers/openai-compatible", "settings": { "baseURL": "https://gateway.example.com/v1", }, "models": { "coder": { "modelID": "upstream/coder-v2" }, }, }, }, }
Provider 或模型出现错误时,通常会指明失败的阶段。在切换 package 之前,先检查 server 进程的环境变量与具体模型 ID。
错误/症状 | 排查 当前没有可用模型用于会话 … | 目前不存在可选的启用模型。完成该 provider 的专属配置后,在 `/models` 中选择一个模型。 模型不可用:provider/model | Provider 未激活;该模型 ID 不存在或已禁用;动态 discovery 不再返回该模型。对于自定义别名,请检查 `models` 映射中的 key,而非 `modelID`。 无法初始化 provider/model:NAME 用于解析 provider endpoint | `baseURL` 中仍留有 `${NAME}` 占位符。请在 OpenCode server 中设置该环境变量,或将模板替换为完整 endpoint。 Azure resource name 缺失 | 请设置 `providers.azure.settings.resourceName`、`AZURE_RESOURCE_NAME`,或一个完整的 `settings.baseURL`。 Vertex 没有出现在列表中 | 请在 provider settings 中设置可解析的 project,或使用受支持的 project 变量。仅配置 ADC 不足以激活 provider。 Bedrock 没有出现在列表中 | 请提供 profile,或受支持的其他 AWS credential chain 输入方式。仅设置 `AWS_REGION` 只能选择 region,无法激活 provider。 Ollama 无模型 | 请确认 server 在由 `baseURL` 推导出的路径下暴露了 `/api/tags` 与 `/api/show`,并且 `/api/show` 报告了 completion 能力。 Copilot 无模型 | 请确认当前 OAuth 账号具有 Copilot Chat 访问权限。若模型同步失败,日志会记录 "failed to sync GitHub Copilot models"。
V2 会拒绝使用已退役的 provider ID,并同时提供直接替代:请改用 `azure/
OpenAI、xAI,以及受支持的 Azure Responses 模型,允许每个会话保留一条常驻的 WebSocket 连接。连续的步骤可以复用不变的请求前缀,仅发送自上次响应以来新增的内容,从而在长会话中减少上传量。 opencode.jsonc { "$schema": "https://opencode.ai/config.json", "providers": { "openai": { "settings": { "transport": "http" }, }, }, } WebSocket 行为遵循以下规则:
- 内置 provider 根据各自策略决定是否对受支持的路由启用 WebSocket。 - Provider 的 `settings.transport` 设为 `"websocket"` 可以启用;设为 `"http"` 则禁用。 - 若在没有 WebSocket 通道的路由上启用了 `"websocket"`,系统会记录一条警告并回退到 HTTP。 - OpenAI provider 的 compaction 使用同一条连接。 - xAI 仅基于已存储的响应进行续接;在其默认 `store: false` 模式下,每一步都会在复用连接上完整发送。 - 已关闭的 socket 会在下一步自动重连;若无法建立连接,会话则继续走 HTTP。 - 带有 `http.request` 或 `http.response` 钩子的 provider plugin 保留 HTTP 行为,确保每次请求均可被观测。