- 一个可登录的 CodeAPI 控制台账号
- 一个有效的 API Key
- 本地已安装 OpenCode
Prepare
开始前需要准备什么
先把账号、密钥和客户端准备好，再写配置会更顺。
Platform & Tools
支持平台与常见使用方式
OpenCode 支持全局配置、项目配置和自定义路径，大多数用户直接使用全局配置就够用。
支持平台
- Windows：适合本地开发机、PowerShell 和日常项目工作流
- macOS：适合个人开发和多项目切换
- Linux：适合远程主机、服务器和自动化环境
常见搭配方式
- 终端：直接运行 opencode 进入交互界面
- VS Code / JetBrains：在内置终端复用同一套配置
- 项目级配置：需要团队统一配置时，可在仓库根目录放 opencode.json
适合的工作流
更适合代码生成、终端协作和项目级代理工作流。如果你只是替换提供方地址，通常不需要改动原有开发习惯。
opencode.json
先写配置文件
根据 OpenCode 官方文档，默认可直接使用全局配置。Windows 用户通常写到用户目录下的 .config\opencode\opencode.json。
常见路径
- Windows：C:\Users\<你的用户名>\.config\opencode\opencode.json
- macOS：/Users/<你的用户名>/.config/opencode/opencode.json
- Linux：~/.config/opencode/opencode.json
opencode.json 示例
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"codeapi": {
"npm": "@ai-sdk/anthropic",
"name": "CodeAPI",
"options": {
"baseURL": "https://api.codeapi.work/v1"
},
"models": {
"claude-haiku-4-5-20251001": {
"name": "haiku 4.5"
},
"claude-opus-4-5-20251101": {
"name": "opus 4.5"
},
"claude-opus-4-6": {
"name": "opus 4.6"
},
"claude-sonnet-4-5-20250929": {
"name": "sonnet 4.5"
},
"claude-sonnet-4-6": {
"name": "sonnet 4.6"
}
}
}
}
}自定义路径时再配环境变量
$env:OPENCODE_CONFIG = "C:\Users\<你的用户名>\opencode.json"Auth
再保存 API Key
如果你不想把 API Key 直接写进 JSON，推荐通过 opencode auth login 保存凭证。
登录命令
opencode auth login填写顺序
- 运行 opencode auth login
- 选择 Other
- Provider ID 输入 codeapi
- 输入你的 CodeAPI Key（sk- 开头）
特别注意
Provider ID 必须和 opencode.json 里的 provider 节点名称保持一致。上面的示例使用的是 codeapi，所以登录时也必须填 codeapi。
Verify
如何验证配置成功
完成配置后，先确认凭证已保存，再进入 OpenCode 查看模型列表。
先检查凭证
opencode auth list再检查模型
opencode
/models成功标志
如果你能看到 codeapi 下的模型列表，例如 claude-sonnet-4-5-20250929，通常说明配置已经生效。
Troubleshoot
常见问题排查
OpenCode 最容易出错的点通常不是模型本身，而是 provider id、配置路径和旧教程格式。
模型列表没有出现
优先检查 provider 是否写在 opencode.json 的 provider 节点下，以及 models 是否嵌套在 codeapi 下。
auth login 后还是不可用
通常是 Provider ID 不匹配。确认 auth login 里填的是 codeapi，而不是其它旧教程里的名字。
改了配置但没有生效
优先检查配置是否写到了默认全局路径；如果你用了自定义路径，再确认 OPENCODE_CONFIG 是否指向正确文件。
下一步建议
如果 OpenCode 已接入成功，建议继续查看价格页和 FAQ，确认计费方式、额度管理和常见问题处理方式。