OpenCode 使用教程

OpenCode 是终端编程助手，使用自己的 Provider 配置和认证信息，不读取 Codex 的 .codex 目录。

1. 安装并检查

按照 OpenCode 官方文档 安装，然后运行：

opencode --version

2. 准备信息

配置项	内容
Provider ID	duckmans
Base URL	https://duckmans.com/v1
API Key	YOUR_API_KEY
Model	DuckMans 后台当前可用模型 ID

请先创建专用 Key，参见创建 API Key。

3. 创建 Provider 配置

创建配置目录：

mkdir -p ~/.config/opencode

创建或合并 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "duckmans/YOUR_MODEL_ID",
  "provider": {
    "duckmans": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "DuckMans",
      "options": {
        "baseURL": "https://duckmans.com/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID"
        }
      }
    }
  }
}

把三处 YOUR_MODEL_ID 替换为同一个后台当前可用模型 ID。如果已有配置，只合并 provider.duckmans，不要覆盖其他 Provider。

4. 保存 API Key

OpenCode 1.17.20 的当前主命令是：

opencode providers login

选择或输入 duckmans，然后粘贴自己的 API Key。opencode auth login 仍是兼容别名，但新文档和新手操作优先使用 providers login。这样可避免把真实 Key 直接写入可能被复制或备份的配置片段。

保存后可先做不发起模型请求的配置检查：

opencode debug config
opencode models duckmans

运行检查后，应看到模型为 duckmans/后台模型ID、Provider 为 DuckMans、适配包为 @ai-sdk/openai-compatible、Base URL 为 https://duckmans.com/v1。

确认 Provider 为 `DuckMans`、Base URL 为 `https://duckmans.com/v1`，并能列出 `duckmans/后台模型ID`。

5. 启动测试

opencode

选择 duckmans / 后台当前可用模型 ID，发送：

请只读取当前目录并列出顶层文件，不要修改。

常见问题

• Provider 不存在：检查 JSON 的逗号、引号和花括号，并确认 ID 都是 duckmans。
• 401：重新执行 opencode providers login，确认选中 duckmans。
• 403：检查 Key 分组和模型权限。
• 404：baseURL 必须是 https://duckmans.com/v1，且不能重复 /v1。
• 模型不可用：配置中的三处模型 ID 必须相同，并与后台当前可用模型 ID 完全一致。

恢复原配置

修改已有 opencode.json 前先备份。失败时恢复备份，并运行 opencode providers logout duckmans 清理本次保存的凭据；不要删除其他 Provider 的配置或认证。