OpenCode API 设置

当前版本：OpenCode v2

OpenCode v2 需要配置大模型 API 才能正常工作。你可以使用官方 OpenCode 模型，也可以接入 OpenAI、Anthropic 等第三方服务商的 API。本章讲解 API 密钥配置、切换模型、排查连接报错。

一、进入 API 配置界面

打开终端，输入命令启动 OpenCode TUI

opencode

在 OpenCode 交互窗口内输入斜杠命令：

/connect

回车后会进入模型服务商选择菜单。

二、选择模型服务商

/connect 会列出支持的服务商，常用选项：

opencode：OpenCode 官方模型（OpenCode Zen / OpenCode Go，新手推荐）
openai：OpenAI 官方接口，兼容 OpenAI 格式的中转API
anthropic：Claude 系列模型

提示：选择服务商后，按提示跳转网页或者直接在终端填写 API Key。

三、配置 OpenCode 官方模型（推荐新手）

在 /connect 列表选择 opencode
根据提示访问认证页面：opencode.ai/auth
登录账号，充值/开通套餐，复制生成的 API Key
返回 OpenCode 终端，粘贴密钥完成绑定

配置完成后，查看可用模型列表验证：

/models

能看到 OpenCode Zen / OpenCode Go 代表配置成功。

四、接入第三方 API（OpenAI 兼容接口示例）

适合想用 GPT 系列或者兼容 OpenAI 协议的中转接口。

执行 /connect，选择 openai
填写 API Key
可选：自定义 API 接口地址（自定义 Base URL，中转服务需要填）
保存配置

示例：自定义 OpenAI 兼容接口的 base_url

API Key: sk-xxxxxx
Base URL: https://xxx.example.com/v1

注意：第三方服务商需要确认模型支持工具调用（tool call），Agent 功能依赖工具调用能力，不支持的模型无法正常使用 OpenCode 的文件读写能力。

五、切换已配置模型

进入 OpenCode TUI
执行

/models

使用方向键选择目标模型，回车切换。
所有后续对话都会使用选中的模型。

六、多服务商密钥管理

OpenCode v2 支持保存多个服务商密钥，随时切换：

再次执行 /connect，可以新增另一个服务商的密钥，不会覆盖已有配置
/models 列表会把所有已配置服务商的模型全部展示出来，一键切换

七、AGENTS.md 中指定模型（项目级别）

你可以在项目 AGENTS.md 为项目固定使用模型，每次打开项目自动生效。
示例片段：

# AGENTS.md
model: opencode/zen
agents:
  - name: reviewer
    model: opencode/zen
    permissions: [read]
  - name: developer
    model: opencode/go
    permissions: [read, write, shell]

read：仅读取代码，不能修改文件
write：允许修改本地源码
shell：允许执行终端命令（谨慎开启）

项目内 AGENTS.md 的模型优先级高于全局默认配置。

八、常见问题排查

1. 提示 API key 无效

检查密钥复制是否带多余空格、换行
确认该服务商账号余额/额度充足
如果是中转接口，核对 Base URL 是否正确，接口是否支持工具调用

2. 模型可以对话，但不能修改文件

大概率是模型不支持工具调用，更换支持 function call 的模型（OpenCode Zen、OpenCode Go、GPT-4o、Claude 3.5 Sonnet）。

3. 网络连接超时

官方 opencode 模型：检查本地网络能否访问 opencode.ai
OpenAI 接口：确认网络可以连通对应接口地址，或者更换可用中转地址

4. 想清除旧 API Key

重新执行 /connect，选中对应服务商，选择重置/删除密钥；或者删除 OpenCode 全局配置文件。

九、安全提示

不要把 API Key 提交到 Git，密钥属于敏感凭证，一旦泄露会被盗刷额度。
项目 AGENTS.md 只写模型名称，不要把 API Key 写进 AGENTS.md。
给 Agent 最小权限：代码评审 Agent 只给 read 权限，避免误操作。