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

使用 @ 符号可以精准引用项目中的文件：

@src/components/Button.tsx 这个组件是如何工作的？

执行 Shell 命令

在对话中使用 ! 前缀可以执行本地命令：

!npm test

Plan 与 Build 模式

OpenCode 提供两种核心工作流，通过 Tab 键切换：

建议先用 Plan 模式让 AI 思考方案，确认无误后再切回 Build 模式执行。如果操作失误，可以使用 /undo 撤销上一步更改（需确保项目为 Git 仓库）。

配置文件详解

OpenCode 支持 JSON 和 JSONC 格式的配置，优先级从高到低依次为：远程组织配置、全局用户配置、环境变量、项目专属配置。

常见配置项

你可以在项目根目录创建 opencode.json 来定制行为：

{
  "$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"
  }
}

变量替换

敏感信息建议使用环境变量或文件引用，避免硬编码：

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

模型与 Provider 配置

OpenCode 支持 75+ 个 LLM 提供商，包括 Anthropic、OpenAI、Google Vertex AI 以及本地运行的 Ollama 或 LM Studio。

配置本地模型

如果你使用 Ollama，可以在配置文件中指定本地地址：

{
  "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 终端界面使用

基本操作

• 发送消息：直接输入文字按 Enter。
• 换行输入：Shift+Enter 或 Ctrl+Enter。
• 引用文件：输入 @ 后模糊搜索文件名。
• 中断响应：按 Escape 键。

常用快捷键

编辑器设置

为了配合 /editor 命令，建议配置 EDITOR 环境变量。例如在 VS Code 中：

export EDITOR="code --wait"

Agent 系统与自定义

主 Agent 与子 Agent

默认情况下，你可以切换 Build（构建）和 Plan（规划）两个主 Agent。此外，还可以手动调用子 Agent，如 @general 用于复杂任务搜索，或 @explore 用于快速浏览代码结构。

自定义 Agent

你可以通过 JSON 或 Markdown 文件定义专用 Agent。例如创建一个代码审查专家：

---
description: 代码审查专家
mode: subagent
model: anthropic/claude-sonnet-4-5
tools:
  write: false
  edit: false
---
你是一个代码审查专家。请关注代码质量、潜在 Bug 及安全考虑，提供建设性反馈。

MCP 服务器扩展

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

配置本地 MCP

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

常用集成

• Sentry：用于错误监控。
• Context7：用于文档搜索。
• Grep by Vercel：用于代码搜索。

认证通常通过 opencode mcp auth <server> 完成。

LSP 语言服务器

OpenCode 内置了强大的 LSP 支持，能够自动诊断 TypeScript、Python、Rust 等多种语言的代码问题。当打开文件时，它会自动启动对应的语言服务器并将诊断信息反馈给 LLM。

如需禁用自动下载，可设置环境变量：

export OPENCODE_DISABLE_LSP_DOWNLOAD=true

主题与个性化

为了获得最佳视觉效果，请确保终端支持 Truecolor（24 位色）。内置主题包括 Tokyo Night、Catppuccin、Gruvbox 等。

切换主题非常简单：

/theme

或在配置文件中指定：

{"theme": "tokyonight"}

Rules 自定义指令

AGENTS.md 类似于 Cursor 的 rules 文件，用于向 LLM 灌输项目特定的规范和结构。你可以手动编写，或通过 /init 自动生成。

引用外部规则

在配置中加载外部文档：

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md"
  ]
}

最佳实践与进阶技巧

高效工作流

1. 先规划后执行：利用 Plan 模式梳理逻辑，再切换到 Build 模式落地。
2. 善用引用：通过 @ 符号提供具体上下文，减少 AI 幻觉。
3. 拖放图片：在终端中拖入设计图，让 AI 参考 UI 实现。

性能优化

• 为轻量任务配置 small_model 以降低成本。
• 启用自动压缩 (compaction) 管理上下文长度。
• 按需开启 MCP 服务器，避免不必要的上下文膨胀。

安全建议

• 对敏感命令（如 rm, git push）设置为 ask 权限。
• 定期审查 auth.json 中的密钥存储位置。

常见问题解答

Q: 如何更换模型？ A: 使用 /models 命令或在配置文件中修改 model 字段。

Q: Shift+Enter 不工作怎么办？ A: 某些终端需要特殊配置，Windows Terminal 用户需在 settings.json 中添加按键映射。

Q: 撤销操作无效？ A: 确保项目已初始化为 Git 仓库，撤销依赖 Git 历史。

Q: 遇到 content filter 错误？ A: Azure 用户可能需要将内容过滤器从 DefaultV2 改为 Default。

更多资源请访问官方文档或 GitHub 仓库。