OpenCode 配置实战教程：从零开始定制你的 AI 编码助手

📚 分类: 工具配置 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode CLI 或桌面应用

---

你将学到什么

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

• [ ] 理解 OpenCode 配置文件的加载优先级，知道在哪里放置你的设置
• [ ] 独立创建一个 opencode.json 文件，配置模型、主题和端口
• [ ] 掌握如何使用环境变量和文件引用来安全地管理 API 密钥
• [ ] 搭建一个符合你个人偏好的、安全且高效的 OpenCode 工作环境

最终效果

你将拥有一个位于项目根目录下的 opencode.json 文件。当你启动 OpenCode 时，它会自动读取此文件，并使用你指定的模型（如 Claude）、主题和端口号，而不是使用默认设置。你的 API 密钥将通过环境变量安全加载，不会明文保存在配置文件中。

---

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求	验证命令
OpenCode	已安装	opencode --version
代码编辑器	任意 (推荐 VS Code)	-

1. 确认 OpenCode 已安装

打开你的终端（Terminal），运行以下命令：

$ opencode --version    // 检查 OpenCode 版本

✅ 验证：如果看到类似 v0.x.x 的输出，说明安装成功。

💡 提示：如果未安装，请先访问 OpenCode 官网下载并安装最新版本。

---

第 1 步：理解配置文件的“权力”层级

🎯 目标：理解 OpenCode 配置文件的加载顺序，知道哪个配置说了算。

OpenCode 的配置是合并的，而不是替换。这意味着，你可以在不同层级设置不同的选项，它们会最终合并成一个完整的配置。当出现冲突时，后加载的配置会覆盖先加载的。

优先级顺序（从低到高，后面的覆盖前面的）：

1. 远程配置：由你的组织通过 .well-known/opencode 提供。这是基础层。
2. 全局配置：位于 ~/.config/opencode/opencode.json。用于设置你的个人偏好，如主题、默认模型。
3. 自定义配置：由 OPENCODE_CONFIG 环境变量指定的文件路径。
4. 项目配置：位于项目根目录下的 opencode.json。这是最常用的，用于设置项目特定的模型和工具。

🤔 为什么要这样设计？ 这种分层设计非常灵活。组织可以强制规定一些安全策略（远程配置），你可以在全局设置自己喜欢的主题（全局配置），而每个项目又可以独立选择最合适的 AI 模型（项目配置），互不干扰。

✅ 验证：请记住这个优先级顺序。在后面的步骤中，我们将重点使用项目配置，因为它最常用，也最容易理解。

---

第 2 步：创建你的第一个项目配置文件

🎯 目标：在你的项目根目录下，创建一个 opencode.json 文件，并配置模型和端口。

📝 操作：

1. 打开终端，进入你的项目目录。
2. 创建一个名为 opencode.json 的文件。
3. 将以下内容复制进去：

{
  "$schema": "https://opencode.ai/config.json",  // 启用编辑器的自动补全和校验
  "model": "anthropic/claude-sonnet-4-5",        // 设置主要使用的模型
  "server": {
    "port": 4096                                 // 设置服务器端口
  }
}

🤔 为什么要这样写？

• $schema 是一个“说明书”，它告诉 VS Code 等编辑器这个 JSON 文件的结构是什么，从而提供代码补全和错误提示。
• model 字段指定了你想要使用的 AI 模型。格式是 提供商/模型名。
• server.port 设置了 opencode serve 命令启动的 HTTP 服务器端口。

✅ 验证：

1. 在你的项目目录下启动 OpenCode TUI：opencode。
2. 观察启动日志，确认它加载了你的配置文件（通常会有提示信息）。
3. 在 OpenCode 中，尝试发送一条消息，它应该会使用你配置的 Claude 模型进行回复。

⚠️ 常见错误： 如果你看到 Error: listen EADDRINUSE :::4096，说明 4096 端口被占用。解决：

$ lsof -i :4096          // 查看占用进程
$ kill -9 [PID]          // 结束进程后重试

或者，在配置文件中将 port 改为其他值，如 3000。

---

第 3 步：安全地管理你的 API 密钥

🎯 目标：学习如何使用环境变量引用 API 密钥，避免将密钥硬编码在配置文件中。

📝 操作：

1. 打开你的终端配置文件（如 ~/.bashrc, ~/.zshrc 或 Windows 的环境变量设置）。
2. 添加你的 API 密钥作为环境变量：

   # 以 Anthropic 为例，将 'your-api-key-here' 替换为你的真实密钥
   export ANTHROPIC_API_KEY="your-api-key-here"

3. 保存文件并执行 source ~/.bashrc（或重启终端）以使更改生效。
4. 修改你的 opencode.json 文件，使用 {env:VARIABLE_NAME} 语法来引用环境变量：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"   // 从环境变量读取 API 密钥
      }
    }
  }
}

🤔 为什么要这样做？ 将 API 密钥直接写在 opencode.json 里，如果这个文件被上传到 GitHub（比如你的项目是公开的），你的密钥就泄露了，可能导致经济损失。通过环境变量引用，密钥只存在于你的系统环境中，配置文件本身是安全的。

✅ 验证：

1. 运行 echo $ANTHROPIC_API_KEY，确认环境变量已正确设置。
2. 再次启动 OpenCode，它应该能正常连接并使用 API。如果报错，请检查环境变量名是否拼写正确。

💡 进阶技巧：你也可以使用 {file:path/to/file} 语法从一个文件中读取密钥，这在某些场景下更灵活。

"apiKey": "{file:~/.secrets/anthropic-key}"

这个文件应包含密钥文本，并且最好设置权限为仅你自己可读（chmod 600 ~/.secrets/anthropic-key）。

---

第 4 步：个性化你的体验（主题与自动更新）

🎯 目标：配置主题和自动更新行为，让 OpenCode 的外观和更新策略符合你的喜好。

📝 操作：

修改你的 opencode.json，添加 theme 和 autoupdate 选项：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  },
  "server": {
    "port": 4096
  },
  // 新增：设置主题
  "theme": "catppuccin-mocha",      // 可选，设置一个你喜欢的主题
  // 新增：禁用自动更新，改为手动通知
  "autoupdate": "notify"            // 可选值：true, false, "notify"
}

🤔 为什么要这样设置？

• theme：OpenCode 支持多种主题，你可以根据自己的视觉偏好选择一个。如果不设置，会使用默认主题。
• autoupdate：默认情况下，OpenCode 会自动更新到最新版。如果你不喜欢频繁的更新打断工作流，可以将其设置为 "notify"，这样它只会通知你有新版本，你可以选择在方便的时候手动更新。设置为 false 则完全禁用更新检查。

✅ 验证：

1. 保存文件，重新启动 OpenCode。
2. 观察界面，主题是否发生了变化。
3. 如果有新版本可用，你应该会收到一个通知，而不是被强制更新。

---

进阶技巧（可选）

掌握基础后，你可以尝试：

1. 自定义命令：在配置文件中添加 command 字段，将重复性任务（如“运行测试”、“创建组件”）定义为快捷命令，只需在聊天中输入 /test 即可触发。

   "command": {
     "test": {
       "template": "Run the full test suite with coverage report and show any failures.",
       "description": "Run tests with coverage"
     }
   }

2. 配置权限：通过 permission 字段，让 OpenCode 在执行敏感操作（如编辑文件、运行 bash 命令）前征求你的同意，增加安全性。

   "permission": {
     "edit": "ask",
     "bash": "ask"
   }

---

常见问题 (FAQ)

Q1: 我修改了 opencode.json，为什么没有生效？A: 请检查以下几点：

1. 文件是否保存在项目根目录下。
2. JSON 格式是否正确（可以使用 jsonlint 或在线工具校验）。
3. 你是否重新启动了 OpenCode？修改配置文件后，需要重启才能生效。

Q2: 报错 Provider "xxx" not found 或 Model "xxx" not found 怎么办？A: 说明你指定的提供商或模型名称不正确。请检查：

1. 提供商 ID 是否正确（如 anthropic, openai）。
2. 模型名称是否是该提供商支持的最新版本。访问 OpenCode 文档或提供商的官网确认模型 ID。

Q3: disabled_providers 和 enabled_providers 有什么区别？A:

• disabled_providers 是一个黑名单。你列出不想用的提供商，其他所有提供商都可以用。
• enabled_providers 是一个白名单。你只列出想用的提供商，其他所有提供商都不能用。
• 注意：disabled_providers 的优先级更高。如果一个提供商同时出现在两个列表中，它会被禁用。

---

总结

恭喜你完成了本教程！🎉

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

1. 配置层级：理解了远程、全局、项目配置的优先级，知道在哪里放什么设置。
2. 项目配置：学会了创建 opencode.json 文件，并配置模型和服务器端口。
3. 安全管理：掌握了使用 {env:...} 和 {file:...} 语法安全地管理 API 密钥。
4. 个性化设置：尝试了配置主题和自动更新策略。

你现在已经可以独立定制一个基础且安全的 OpenCode 工作环境了。

---

下一步

如果你想继续深入，建议学习：

• 📖 OpenCode 工具系统：学习如何启用/禁用 LLM 可以调用的工具，如文件读写和 Bash 命令。
• 📖 OpenCode 代理 (Agent)：学习如何为代码审查、架构规划等特定任务创建专用代理。
• 📖 OpenCode MCP 服务器：学习如何集成外部工具和服务（如 Jira, GitHub）来增强 AI 的能力。

💡 练习任务：尝试在你的项目配置中，使用 small_model 字段为“生成标题”等轻量级任务指定一个更便宜、更快的模型（如 anthropic/claude-haiku-4-5）。这是巩固知识的最佳方式。

## 相关文档

- [OpenCode 个性化配置实战教程](/docs/she-zhi-tiao-you/opencode-ge-xing-hua-pei-zhi-shi-zhan-jiao-cheng.html)