OpenCode 工具链配置教程：从零配置你的 AI 编程助手

📚 分类: OpenCode 配置教程 ⏱️ 预计耗时: 45 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode 并连接至 AI 模型（参见本系列教程第 02 篇）

---

你将学到什么

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

• [ ] 理解 OpenCode 内置工具（读、写、搜索、运行命令）的用途和权限设置
• [ ] 独立配置 LSP（语言服务器协议），让 AI 助手理解你的代码
• [ ] 配置 Formatter，确保代码风格统一
• [ ] 判断何时需要引入 MCP（模型上下文协议）或自定义工具

最终效果

你将拥有一份经过精心配置的 opencode.json 配置文件。当你再次使用 OpenCode 时，AI 助手将：

1. 能够智能地阅读、搜索和修改你的代码文件。
2. 在你编写 TypeScript 或 Python 等语言时，提供代码诊断、跳转定义等 IDE 级功能。
3. 在保存文件时自动格式化代码，保持风格一致。
4. 只在必要时，向你请求权限去访问外部系统（如 GitHub）。

---

前置准备

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

检查项	要求	验证命令
OpenCode	已安装并可用	opencode --version
项目目录	一个包含代码（如 .ts, .py 文件）的文件夹	确保你有一个项目

1. 确认 OpenCode 配置文件位置

OpenCode 的配置文件名为 opencode.json，它通常位于你的项目根目录下。

# 进入你的项目目录
$ cd my-awesome-project

# 检查是否已存在配置文件
$ ls opencode.json

✅ 验证：

• 如果没有这个文件，不用担心，我们下一步会创建它。
• 如果已有文件，建议先备份：cp opencode.json opencode.json.backup。

---

第 1 步：理解并配置内置工具权限

🎯 目标：创建一个基础的 opencode.json 配置文件，并设置内置工具（如读文件、写文件、运行命令）的权限策略，确保 AI 助手的行为在可控范围内。

📝 操作：

1. 在你的项目根目录下创建一个名为 opencode.json 的文件。
2. 将以下内容复制进去：

{
  "$schema": "https://opencode.ai/config.json", // 注释：提供代码补全和校验
  "permission": {
    // 注释：定义 AI 助手使用工具的权限
    "read": "allow",     // 允许读取文件，无需询问
    "grep": "allow",     // 允许搜索文件内容，无需询问
    "glob": "allow",     // 允许查找文件路径，无需询问
    "edit": "ask",       // 修改文件前需要询问你
    "bash": "ask",       // 运行终端命令前需要询问你
    "webfetch": "ask"    // 抓取网页内容前需要询问你
  }
}

🤔 为什么要这样做？

• allow 和 ask 是两种核心权限策略。allow 让 AI 助手可以自由操作，适合风险低的动作（如读文件）；ask 则会在执行前征求你的同意，适合有潜在风险的动作（如修改代码、运行命令）。
• 这比在对话中反复说“请小心操作”要可靠得多。配置是规则，对话是意图。

✅ 验证：

1. 保存 opencode.json 文件。
2. 在项目根目录下运行 OpenCode，并给它一个任务：“帮我看看当前目录下有哪些文件”。
3. AI 助手应该能直接执行，而不会询问你。

---

第 2 步：启用 LSP，让 AI 理解你的代码

🎯 目标：配置 LSP（语言服务器协议），让 AI 助手能像 VS Code 一样理解你的代码结构、提供诊断信息、跳转到定义等。

📝 操作：

1. 打开你的 opencode.json 文件。
2. 在 permission 对象下方，添加一个 lsp 对象来配置语言服务器。以下是一个针对 TypeScript 的示例：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "bash": "ask",
    "webfetch": "ask"
  },
  // 新增：LSP 配置
  "lsp": {
    "typescript": {
      "enabled": true, // 注释：启用 TypeScript 语言服务器
      "initialization": {
        "preferences": {
          "importModuleSpecifierPreference": "relative" // 注释：偏好使用相对路径导入
        }
      }
    }
  }
}

💡 提示：OpenCode 会自动检测你项目中的文件类型，并尝试启动对应的 LSP。对于 Python，你通常需要确保安装了 pyright 或 pylsp 等语言服务器。

✅ 验证：

1. 保存文件。
2. 给 AI 助手一个需要理解代码结构的任务，例如：“请找到 src/utils.ts 文件中 formatDate 函数的定义，并告诉我它接收什么参数”。
3. AI 助手应该能准确找到定义并给出参数类型，而不是通过全文搜索去猜测。

---

第 3 步：配置 Formatter，保持代码风格

🎯 目标：启用代码格式化器，让 AI 助手在修改代码后自动将代码格式化为统一风格，避免格式混乱。

📝 操作：

1. 打开你的 opencode.json 文件。
2. 在 lsp 对象下方，添加一个 formatter 配置。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "bash": "ask",
    "webfetch": "ask"
  },
  "lsp": {
    "typescript": {
      "enabled": true,
      "initialization": {
        "preferences": {
          "importModuleSpecifierPreference": "relative"
        }
      }
    }
  },
  // 新增：启用所有内置格式化器
  "formatter": true
}

🤔 为什么要这样做？

• formatter: true 是一个快捷方式，它会启用 OpenCode 内置的所有格式化器（如 Prettier 用于前端代码，Black 用于 Python 代码）。
• 你也可以更精细地控制，例如禁用某个特定的格式化器："formatter": { "prettier": { "disabled": true } }。

⚠️ 重要原则：Formatter 只应该做机械格式化（如缩进、空格、分号），不应该改变代码逻辑。在审查 AI 的代码改动时，请留意 diff（差异对比），确保 formatter 没有掩盖真正的逻辑变更。

✅ 验证：

1. 保存文件。
2. 给 AI 助手一个任务，让它修改一段格式混乱的代码。
3. 检查修改后的文件，代码格式应该变得整洁一致。

---

第 4 步：了解何时引入 MCP（模型上下文协议）

🎯 目标：理解 MCP 的作用，并学会判断何时才需要引入它，避免过度配置。

📝 操作：

1. 理解 MCP 的定位：MCP 是一个标准协议，用于让 AI 助手连接到外部系统。例如：GitHub、Jira、数据库、内部 API 等。它提供的是“项目外部上下文”。
2. 遵循判断顺序：
   • 第一步：问自己，这个任务能否用内置工具（读文件、搜代码）解决？
   • 第二步：如果不行，再考虑是否需要 LSP 或 Formatter。
   • 第三步：只有当需要访问外部系统时，才考虑引入 MCP。
3. 最小化配置：如果你确实需要连接 GitHub，可以在 opencode.json 中添加 MCP 配置。

{
  // ... 之前的配置
  // 新增：MCP 配置示例
  "mcp": {
    "github-server": {
      "type": "remote",                        // 注释：远程 MCP 服务
      "url": "https://mcp.your-github-proxy.com/mcp", // 注释：你的 MCP 服务地址
      "enabled": true                          // 注释：启用
    }
  }
}

💡 核心原则：

• 能用内置，不用 MCP：不要用 MCP 来解决本地 grep 就能解决的问题。
• 先只读，后写入：对于新接入的 MCP 工具，先以只读方式验证其功能，再考虑开放写入权限。
• 工具越少越好：每多一个工具，都会增加 AI 的上下文负担和潜在风险。

---

进阶技巧（可选）

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

1. 创建自定义工具（Custom Tool）：如果你有一个反复使用的 shell 命令（例如查询内部服务状态），可以将其封装成一个自定义工具，让 AI 助手可以稳定调用。

   • 在项目根目录下创建 .opencode/tools/ 文件夹。
   • 创建一个 .ts 文件，例如 check-service-status.ts。
   • 使用 @opencode-ai/plugin 提供的 tool() 函数来定义它。

2. 精细化的 MCP 权限控制：你可以为特定 MCP 服务器下的所有工具设置统一的权限。

"permission": {
  // ... 其他权限
  "github_*": "ask" // 注释：所有以 "github_" 开头的工具，使用前都需要询问
}

---

常见问题 (FAQ)

Q1: 我配置了 LSP，但 AI 助手似乎没有使用它，怎么办？A: 首先确认你的项目依赖是否已安装（例如 npm install）。其次，检查 OpenCode 的日志，看是否有 LSP 启动失败的错误。最后，尝试重启 OpenCode 会话。

Q2: Formatter 把我的代码改得乱七八糟，怎么关掉它？A: 在 opencode.json 中，将 "formatter": true 改为 "formatter": false 即可完全禁用。或者，你可以只禁用特定的格式化器，如 "formatter": { "prettier": { "disabled": true } }。

Q3: 我应该添加多少个 MCP 服务器？A: 遵循“最小够用”原则。只添加你当前项目高频使用的 1-3 个 MCP 服务器。工具多了会很快占用 AI 的上下文窗口（Context Window），影响其性能。

Q4: 如何检查当前连接了哪些 MCP 服务器？A: 在终端中运行以下命令：

$ opencode mcp list

---

总结

恭喜你完成了本教程！🎉

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

1. 工具分层：OpenCode 的工具从内置工具到 MCP 逐层扩展，每增加一层都意味着更高的能力和风险。
2. 权限先行：通过 permission 配置，为不同风险等级的工具设置 allow 或 ask 策略，这是安全使用 AI 编程助手的基石。
3. 按需启用：LSP 提升代码理解能力，Formatter 保证代码风格，MCP 连接外部世界。只在需要时才启用它们。
4. 最小化原则：工具不是越多越好。能用内置工具解决，就不接 MCP；能用一个工具，就不用两个。

---