OpenCode 开源 AI 编程助手实战指南

!npm test

Plan 与 Build 模式

OpenCode 提供了两种工作模式，通过 Tab 键切换：

• Build 模式：拥有完整权限，可以修改文件，适合实际开发。
• Plan 模式：只读模式，仅分析不修改，适合代码审查或方案规划。

推荐的工作流是先切换到 Plan 模式让 AI 制定计划，确认无误后再切回 Build 模式执行。这种分步策略能有效减少错误修改。

配置文件详解

OpenCode 使用 JSON 或 JSONC 格式进行配置，优先级从低到高依次为：项目根目录 opencode.json > 全局用户配置 ~/.config/opencode/opencode.json > 环境变量覆盖。

一个典型的配置示例如下：

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "tokyonight",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "tui": {
    "scroll_speed": 3,
    "diff_style": "auto"
  },
  "permission": {
    "edit": "allow",
    "bash": "ask"
  }
}

这里特别要注意 permission 字段，它可以精细控制 AI 对文件的编辑权限和 Shell 命令的执行权限，保障安全。

Provider 配置

OpenCode 支持 75+ 个模型提供商。除了官方推荐的 OpenCode Zen，你还可以配置本地模型如 Ollama 或 LM Studio。

配置本地 Ollama 时，需要指定 Base URL 和模型名称：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {"name": "Llama 2"}
      }
    }
  }
}

如果工具调用不生效，尝试在 Ollama 中增加 num_ctx 参数至 16k-32k。

TUI 终端界面使用

启动后，你会进入全屏终端界面。基本操作包括直接输入消息发送，或使用 Shift+Enter 换行。内置命令非常丰富，例如 /undo 撤销上一步操作，/sessions 查看历史会话。

导航方面，PageUp/PageDown 翻页，Ctrl+g 跳转顶部。快捷键大多以 Leader 键（默认 Ctrl+x）组合，例如 <leader>n 新建会话。q 退出程序。

Agent 系统

Agent 是 OpenCode 的核心逻辑单元。主 Agent 分为 Build 和 Plan，子 Agent 则可以通过 @ 提及调用，如 @general 处理复杂任务，@explore 快速探索代码库。

自定义 Agent 支持 JSON 配置或 Markdown 文件。创建 .opencode/agents/reviewer.md 可以定义一个专门的代码审查专家，限制其只能读取不能修改，专注于安全性检查。

MCP 服务器扩展

Model Context Protocol (MCP) 允许 OpenCode 集成外部工具。你可以连接数据库、API 或第三方服务来增强 AI 能力。

配置本地 MCP 服务器只需在配置文件中添加命令：

{
  "mcp": {
    "my-local-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true
    }
  }
}

常用的集成包括 Sentry 错误监控、Context7 文档搜索以及 Vercel Grep 代码搜索。认证类 MCP 服务器需先运行 opencode mcp auth 完成 OAuth 流程。

LSP 语言服务器

OpenCode 内置了多种语言的 LSP 支持，如 TypeScript、Python、Rust 等。当打开文件时，它会自动启动对应的语言服务器获取诊断信息并反馈给 LLM。

如需禁用所有 LSP，可在配置中设置 "lsp": false。若需禁用特定语言，可单独配置，例如 "typescript": {"disabled": true}。

主题与个性化

为了获得最佳视觉效果，请确保终端支持 Truecolor（24 位色）。内置主题包括 Tokyo Night、Catppuccin、Gruvbox 等。切换主题可使用 /theme 命令或在配置文件中指定 "theme": "tokyonight"。

自定义主题时，只需定义颜色变量映射，支持 Hex 颜色、ANSI 颜色及深浅变体。

Rules 自定义指令

AGENTS.md 类似于 Cursor 的 rules 文件，用于向 LLM 灌输项目特定的编码规范和结构信息。运行 /init 可自动生成，也可手动编写。

例如，在 monorepo 项目中，你可以在 AGENTS.md 中说明工作区包的导入约定，这样 AI 生成的代码就能符合团队规范。

最佳实践与进阶技巧

1. 先规划后执行：利用 Plan 模式梳理思路，避免盲目修改。
2. 善用 @ 引用：明确指定上下文文件，提高回答准确度。
3. 性能优化：为轻量任务配置便宜的 small_model，启用自动压缩保持上下文精简。
4. 安全控制：对敏感命令如 rm * 或 git push 设置 ask 权限，防止误操作。

常见问题解答

Q: 如何更换模型？ 运行 /models 或在配置文件中修改 model 字段。

Q: Shift+Enter 不工作怎么办？ 部分终端需特殊配置，Windows Terminal 用户需在 settings.json 中添加对应的 keybindings。

Q: 撤销操作无效？ 确保项目已初始化为 Git 仓库，撤销功能依赖 Git 快照。

Q: 如何重置 OpenCode？ 删除 ~/.config/opencode 和 ~/.local/share/opencode 目录即可。

更多资源

• GitHub 仓库：https://github.com/anomalyco/opencode
• 官方文档：https://opencode.ai/docs