LowHow 文档

中文

English

中文

English

深色模式

OpenCode AI 模型配置实战教程：从零设置 API 密钥与模型分配 ​

📚 分类: AI 开发工具配置 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解 OpenCode 支持的 AI 模型提供商及其特点
  • [ ] 掌握通过环境变量和配置文件两种方式设置 API 密钥
  • [ ] 根据任务类型（编码、搜索、标题）为不同代理分配最优模型
  • [ ] 创建针对预算或性能优化的个性化配置

最终效果 ​

你将能够通过编辑 ~/.opencode.json 文件或设置环境变量，让 OpenCode 使用你指定的 AI 模型进行代码生成、代码搜索和聊天标题命名，并理解不同配置带来的成本与性能差异。

前置准备 ​

在开始前，请确认你已经安装了 OpenCode。如果尚未安装，请参考 官方安装指南。

1. 创建 OpenCode 配置文件 ​

OpenCode 会读取你的个人配置文件。请确认文件存在：

bash
$ touch ~/.opencode.json    // 如果文件不存在，则创建它

✅ 验证： 执行后，文件 ~/.opencode.json 应该存在。你可以用以下命令查看：

bash
$ ls -la ~/ | grep opencode

如果看到 -rw-r--r-- 1 user staff 0 Jan 1 12:00 .opencode.json，说明文件已创建成功。

第 1 步：选择并配置 AI 模型提供商 ​

🎯 目标：选择一个 AI 提供商（如 Anthropic 或 OpenAI），并通过环境变量或配置文件设置 API 密钥。

OpenCode 支持多种 AI 提供商。我们将以最常用的 Anthropic (Claude) 和 OpenAI 为例进行配置。

📝 操作：

方法 A：使用环境变量（推荐）

这种方式更安全，密钥不会写入配置文件中，避免意外泄露。

bash
# 在 ~/.bashrc 或 ~/.zshrc 文件中添加以下行
export ANTHROPIC_API_KEY="sk-ant-你的ClaudeAPI密钥"  // 替换为你的实际密钥
export OPENAI_API_KEY="sk-你的OpenAI API密钥"       // 替换为你的实际密钥

# 然后执行以下命令使配置生效
$ source ~/.bashrc  # 如果使用 bash
# 或
$ source ~/.zshrc   # 如果使用 zsh

方法 B：使用 OpenCode 配置文件

如果你偏好将所有配置集中在一个地方，可以编辑 ~/.opencode.json 文件。

json
{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-你的ClaudeAPI密钥"
    },
    "openai": {
      "apiKey": "sk-你的OpenAI API密钥"
    }
  }
}

🤔 为什么要这样做？

providers 对象告诉 OpenCode 你有哪些 AI 账户可用。OpenCode 会根据这些配置，在需要调用 API 时自动使用对应的密钥进行身份验证。

✅ 验证：

bash
$ echo $ANTHROPIC_API_KEY
# 预期输出：sk-ant-你的ClaudeAPI密钥（你设置的值）

如果看到你设置的密钥值，说明环境变量配置成功。

⚠️ 常见错误：

  • 密钥泄露：千万不要将 API 密钥提交到公开的 Git 仓库中。使用环境变量是更安全的选择。如果你必须使用配置文件，请确保 .opencode.json 已加入 .gitignore 文件。
  • JSON 格式错误：确保 JSON 文件格式正确，特别是逗号和引号。可以使用在线的 JSON 校验工具（如 jsonlint.com）检查。
  • 环境变量未生效：如果执行 echo 后没有输出，说明环境变量未正确加载。请确认你已执行 source ~/.bashrc 或 source ~/.zshrc。

第 2 步：为不同任务分配模型 ​

🎯 目标：在配置文件中指定哪个模型用于编码、代码搜索和生成标题。

上一步我们配置了 API 密钥，现在需要告诉 OpenCode 每个任务应该使用哪个模型。

📝 操作：

编辑 ~/.opencode.json 文件，添加 agents 配置：

json
{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-你的ClaudeAPI密钥"
    },
    "openai": {
      "apiKey": "sk-你的OpenAI API密钥"
    }
  },
  "agents": {
    "coder": {
      "model": "claude-4-sonnet",       // 编码任务使用 Claude 4 Sonnet
      "maxTokens": 50000                // 最大输出 token 数
    },
    "task": {
      "model": "gpt-4o-mini",           // 搜索任务使用 GPT-4o Mini
      "maxTokens": 3000                 // 搜索任务不需要太多输出
    },
    "title": {
      "model": "gpt-4o-mini"            // 标题任务使用 GPT-4o Mini
    }
  }
}

🤔 为什么要这样做？

  • coder（编码代理）：负责生成代码，需要强大的推理能力，所以分配了性能最佳的模型（如 claude-4-sonnet）。编码任务通常需要处理复杂逻辑，因此 maxTokens 设置较高。
  • task（任务代理）：负责搜索文件、理解上下文，需要快速且成本低，所以分配了性价比高的模型（如 gpt-4o-mini）。搜索任务通常只需返回简短的结果，因此 maxTokens 设置较低。
  • title（标题代理）：负责为聊天对话生成标题，任务简单，任何快速模型都行。

✅ 验证：

配置文件保存后，重新启动 OpenCode。当你执行以下操作时，OpenCode 将使用你指定的模型：

  • 编码：输入 "请帮我写一个 Python 排序函数"
  • 搜索：输入 "搜索项目中的用户登录相关文件"
  • 标题：开始一个新对话，OpenCode 会自动生成标题

💡 提示：

  • 模型 ID 必须与提供商提供的 ID 完全一致。例如，Claude 模型通常以 claude- 开头，OpenAI 模型以 gpt- 或 o 开头。
  • maxTokens 控制模型单次输出的最大长度，合理设置可以控制成本。编码任务建议 50000-100000，搜索任务建议 2000-5000。

第 3 步：启用高级功能（推理与文件附件） ​

🎯 目标：为支持推理的模型启用“推理模式”，让模型进行深度思考。

📝 操作：

在 coder 配置中添加 reasoningEffort 参数：

json
{
  "agents": {
    "coder": {
      "model": "o1",                     // 使用 OpenAI 的 o1 推理模型
      "reasoningEffort": "high",         // 启用高推理努力
      "maxTokens": 50000
    }
  }
}

🤔 为什么要这样做？

  • reasoningEffort：对于支持推理的模型（如 OpenAI 的 o 系列、Anthropic 的 Claude 4 Sonnet），设置 high 可以让模型在回答前进行更深入的思考。这适合解决复杂的算法问题或需要多步推理的任务，但会消耗更多 token（成本更高）。
  • 可选值：low（低推理努力，快速响应）、medium（中等推理努力）、high（高推理努力，深度思考）。
  • 文件附件：大多数现代模型都支持附加文件（如图片、PDF）作为上下文的一部分。OpenCode 会自动处理，你无需额外配置。

✅ 验证：

配置后，向 OpenCode 提出一个复杂的编程问题：

bash
$ opencode "请用 Python 实现一个支持 LRU 缓存的装饰器"

如果模型回答中包含了“思考过程”或“推理步骤”，说明推理模式已生效。对于 o1 模型，你可能会看到模型在回答前显示“思考中...”的状态。

⚠️ 常见错误：

  • 模型不支持推理：如果为不支持推理的模型（如 gpt-4o-mini）设置 reasoningEffort，该参数将被忽略，不会报错但也不会生效。
  • 成本飙升：reasoningEffort: "high" 会显著增加 token 消耗，尤其是对于长回答。请留意你的 API 使用成本，建议先在测试环境中试用。
  • 响应变慢：启用推理模式后，模型响应时间会增加，这是正常现象。

第 4 步：配置其他提供商（可选） ​

🎯 目标：了解如何配置 GitHub Copilot、Google Gemini 和 AWS Bedrock 等其他提供商。

除了 Anthropic 和 OpenAI，OpenCode 还支持多种提供商。以下是一些常见配置示例：

GitHub Copilot（免费，需订阅） ​

如果你有 GitHub Copilot 订阅，无需设置 API 密钥，OpenCode 会自动检测并配置。

json
{
  "agents": {
    "coder": {
      "model": "copilot.gpt-4.1"   // 使用 Copilot 的 GPT-4.1 模型
    }
  }
}

💡 提示：GitHub Copilot 的模型 ID 格式为 copilot.模型名，如 copilot.gpt-4.1、copilot.claude-3.5-sonnet。

Google Gemini ​

bash
# 在 ~/.bashrc 或 ~/.zshrc 中添加
export GEMINI_API_KEY="你的Gemini API密钥"  // 从 Google AI Studio 获取
json
// .opencode.json
{
  "providers": {
    "gemini": {
      "apiKey": "你的Gemini API密钥"
    }
  },
  "agents": {
    "coder": {
      "model": "gemini-2.5-flash"  // 使用 Gemini 2.5 Flash，拥有 1M 上下文窗口
    }
  }
}

AWS Bedrock ​

bash
# 在 ~/.bashrc 或 ~/.zshrc 中添加
export AWS_ACCESS_KEY_ID="你的AWS访问密钥ID"
export AWS_SECRET_ACCESS_KEY="你的AWS秘密访问密钥"
export AWS_REGION="us-east-1"
json
{
  "agents": {
    "coder": {
      "model": "bedrock.claude-3.7-sonnet" // 通过 AWS 使用 Claude 3.7 Sonnet
    }
  }
}

💡 提示：AWS Bedrock 的模型 ID 格式为 bedrock.模型名，如 bedrock.claude-3.7-sonnet、bedrock.llama-3-70b。

✅ 验证：

配置新的提供商后，在 agents 中引用其模型 ID。启动 OpenCode 并执行一个简单的任务：

bash
$ opencode "你好，请回复'配置成功'"

如果 OpenCode 返回了“配置成功”，说明新提供商配置正确。

进阶技巧（可选） ​

掌握基础后，你可以尝试以下配置优化：

1. 成本优化配置（适合日常使用） ​

json
{
  "agents": {
    "coder": { "model": "gpt-4.1-mini", "maxTokens": 5000 },
    "task": { "model": "gpt-4o-mini", "maxTokens": 3000 },
    "title": { "model": "gpt-4o-mini", "maxTokens": 1000 }
  }
}

这个配置非常适合日常使用，成本极低。gpt-4.1-mini 和 gpt-4o-mini 都是性价比很高的模型。

2. 性能最大化配置（适合复杂项目） ​

json
{
  "agents": {
    "coder": { "model": "claude-4-sonnet", "maxTokens": 50000, "reasoningEffort": "high" },
    "task": { "model": "gpt-4.1-mini", "maxTokens": 5000 },
    "title": { "model": "gpt-4.1-mini", "maxTokens": 1000 }
  }
}

这个配置适合处理复杂项目，编码任务使用最强的模型进行深度推理，其他任务使用快速模型节省成本。

3. 混合提供商配置（灵活切换） ​

json
{
  "agents": {
    "coder": { "model": "gemini-2.5-pro", "maxTokens": 100000 },
    "task": { "model": "copilot.gpt-4.1", "maxTokens": 5000 }
  }
}

利用不同提供商的优势：Gemini 拥有超长上下文窗口（1M token），适合处理大型代码库；Copilot 的模型与 GitHub 深度集成，搜索效率更高。

常见问题 (FAQ) ​

Q1: 我配置了 API 密钥，但 OpenCode 报错“unauthorized”怎么办？

A: 常见原因及解决方法：

  1. 密钥无效或已过期：请到 AI 提供商的控制台重新生成密钥。Anthropic 密钥在 console.anthropic.com，OpenAI 密钥在 platform.openai.com/api-keys。
  2. 环境变量未正确加载：请尝试重启终端或执行 source ~/.bashrc（或 source ~/.zshrc）。
  3. 配置文件中的 JSON 格式错误：仔细检查引号和逗号。一个常见的错误是对象之间缺少逗号。

Q2: 如何查看当前使用的模型？

A: 在 OpenCode 的界面中，通常会显示当前正在使用的模型名称。你也可以查看配置文件 ~/.opencode.json 中 agents 下的设置。如果 OpenCode 没有显示模型名称，可以尝试运行一个简单查询，根据响应速度和质量推断使用的模型。

Q3: 我想使用一个官方文档中没有列出的模型，可以吗？

A: 可以，只要该模型被提供商支持，并且你知道其准确的模型 ID，就可以配置。例如，OpenAI 发布新模型后，你可以直接用它的 ID 替换。模型 ID 通常可以在提供商的官方文档中找到。

Q4: 配置了多个提供商，如何切换使用哪个？

A: 你不需要手动切换。OpenCode 会根据 agents 中每个任务指定的 model 自动调用对应的提供商。如果你想临时切换，只需修改配置文件中对应任务的 model 值即可。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 配置提供商：通过环境变量或 .opencode.json 文件设置 API 密钥，推荐使用环境变量以保障安全。
  2. 分配模型：在 agents 中为 coder、task、title 指定不同的模型，以平衡性能与成本。
  3. 高级功能：启用 reasoningEffort 让模型进行深度思考，适用于复杂编码任务。
  4. 灵活配置：支持 GitHub Copilot、Google Gemini、AWS Bedrock 等多种提供商，可根据需求自由组合。

© 2026 LowHow