OpenCode 开源 AI 编程助手使用指南

模式切换

OpenCode 提供两种主要模式，按 Tab 键切换：

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

建议先用 Plan 模式确认方案，再切回 Build 模式执行。撤销操作依赖 Git 仓库，使用 /undo 和 /redo 命令。

配置文件详解

OpenCode 支持 JSON 和 JSONC 格式的配置。优先级顺序为：远程组织配置 > 全局用户配置 > 环境变量 > 项目专属配置。

典型配置示例如下：

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

变量替换功能允许你通过环境变量或文件内容注入敏感信息，例如：

{"model":"{env:OPENCODE_MODEL}"}

Provider 配置

OpenCode 支持 75+ 个 LLM 提供商。常用配置包括：

• Anthropic/OpenAI：支持订阅认证或手动输入 API Key。
• 本地模型：配置 Ollama 或 LM Studio，需设置正确的 baseURL。
• 云厂商：Amazon Bedrock、Google Vertex AI 等。

禁用或启用特定 Provider 可在配置文件中设置 disabled_providers 或 enabled_providers。

TUI 终端界面

启动后，你可以通过快捷键高效操作：

• 发送消息：Enter 键。
• 换行：Shift+Enter。
• 引用文件：输入 @ 搜索。
• 内置命令：如 /models 切换模型，/new 新建会话，/share 分享会话。

导航方面，PageUp/PageDown 翻页，Ctrl+g 跳转顶部。编辑器设置可通过 EDITOR 环境变量指定，VS Code 需加上 --wait 参数。

Agent 系统

Agent 分为主 Agent 和子 Agent。主 Agent 默认为 Build 和 Plan 模式，通过 Tab 切换。子 Agent 如 General 或 Explore 可通过 @ 提及调用。

自定义 Agent 支持 JSON 配置或 Markdown 文件定义。你可以限制其工具权限，例如禁止写入文件但允许读取，打造专用的代码审查专家。

自定义命令

通过创建 .opencode/commands/ 下的文件或直接在配置中定义快捷命令。模板语法支持 $ARGUMENTS 占位符和 Shell 命令输出插入，方便封装常用工作流。

MCP 服务器

Model Context Protocol (MCP) 允许 OpenCode 集成外部工具，如数据库、API 或第三方服务。

配置本地 MCP 服务器时，指定 command 即可；远程服务器则需提供 url。常用示例包括 Sentry 错误监控、Context7 文档搜索等。注意管理好 MCP 权限，避免不必要的上下文开销。

LSP 语言服务器

OpenCode 内置多种语言的 LSP 支持，包括 TypeScript、Python、Rust、Go 等。当打开文件时，它会自动启动对应的语言服务器并提供诊断反馈。

若需禁用自动下载或特定语言支持，可在配置中设置 lsp 选项或环境变量 OPENCODE_DISABLE_LSP_DOWNLOAD。

主题与个性化

终端需支持 Truecolor 才能正确显示主题。内置主题包括 Tokyo Night、Catppuccin、Gruvbox 等。自定义主题需遵循特定的 JSON Schema 定义颜色变量。

Rules 自定义指令

AGENTS.md 文件用于向 LLM 提供项目特定的编码规范和上下文。它支持引用外部文件，甚至兼容 Claude Code 的 CLAUDE.md 约定。合理维护此文件能显著提升 AI 输出的质量。

最佳实践

1. 先规划后执行：利用 Plan 模式梳理思路，减少试错成本。
2. 上下文管理：合理使用 @ 引用关键文件，避免无关信息干扰。
3. 性能优化：为轻量任务配置 small_model，启用自动压缩上下文。
4. 安全控制：对敏感命令（如 rm, git push）设置为 ask 权限。

常见问题

• 更换模型：使用 /models 命令或在配置中指定。
• 本地模型：配置 Ollama 或 LM Studio 的兼容接口。
• 撤销失败：确保项目已初始化为 Git 仓库。
• 重置数据：删除 ~/.config/opencode 和 ~/.local/share/opencode 目录。

更多资源请参考官方文档和 GitHub 仓库。