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

基础交互

• 询问代码：直接输入自然语言问题。
• 引用文件：使用 @ 符号模糊搜索文件名，如 @src/components/Button.tsx。
• 执行命令：以 ! 开头，例如 !npm test。

Plan 与 Build 模式

按 Tab 键切换模式：

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

示例流程：先用 Plan 模式规划功能，确认方案后切换到 Build 模式执行。

配置文件详解

OpenCode 支持 JSON 和 JSONC 格式。配置加载优先级如下：

1. .well-known/opencode (远程组织)
2. ~/.config/opencode/opencode.json (全局用户)
3. OPENCODE_CONFIG 环境变量
4. 项目根目录 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"
  }
}

变量替换支持环境变量 {env:KEY} 或文件内容 {file:path}。

Provider 配置

OpenCode 支持 75+ LLM 提供商，常用包括 OpenCode Zen、Anthropic、OpenAI、Ollama 等。

配置 Anthropic

通过 /connect 选择 Anthropic，浏览器认证或手动输入 API Key。

配置本地模型 (Ollama)

在配置文件中指定 baseURL：

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {"baseURL": "http://localhost:11434/v1"},
      "models": {
        "llama2": {"name": "Llama 2"}
      }
    }
  }
}

提示：若工具调用不工作，尝试增加 Ollama 的 num_ctx 至 16k-32k。

TUI 终端界面使用

基本操作

• 发送消息：输入文字按 Enter。
• 换行：Shift+Enter 或 Ctrl+Enter。
• 引用文件：输入 @ 搜索。
• Shell 命令：以 ! 开头。

内置命令

导航与编辑器

• 滚动：PageUp/PageDown 或 Ctrl+Alt+b/f。
• 中断响应：Escape。
• 设置 EDITOR 环境变量以使用 /editor 命令（如 VS Code 需加 --wait 参数）。

Agent 系统

主 Agent 与子 Agent

• 主 Agent：Build（默认）和 Plan（只读），通过 Tab 切换。
• 子 Agent：General（通用）、Explore（探索），通过 @ 提及调用。

自定义 Agent

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

---
description: 代码审查专家
mode: subagent
model: anthropic/claude-sonnet-4-5
tools:
  write: false
  edit: false
---
你是一个代码审查专家。请关注代码质量、潜在 bug 和安全考虑。

自定义命令

创建命令

支持 JSON 或 Markdown 格式。Markdown 更直观：

---
description: 运行测试
agent: build
---
运行完整的测试套件并显示覆盖率报告。关注失败的测试并提供修复建议。

使用 /test 即可触发。

模板语法

• $ARGUMENTS：所有参数。
• $1, $2：位置参数。
• !`command`：执行 Shell 命令并获取输出。

MCP 服务器

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

配置示例

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

常用集成包括 Sentry（错误监控）、Context7（文档搜索）和 Vercel Grep（代码搜索）。

LSP 语言服务器

OpenCode 内置多种语言的 LSP 支持，如 TypeScript、Python、Rust、Go 等。打开文件时会自动检测扩展名并启动对应服务器，将诊断信息反馈给 LLM。

可在配置中禁用特定 LSP 或全局关闭：

{"lsp": false}

主题与个性化

终端需支持 Truecolor（24 位色）。内置主题包括 tokyonight、catppuccin、gruvbox 等。

切换主题：

/theme

或在配置中设置 "theme": "tokyonight"。

Rules 自定义指令

AGENTS.md 是特殊文件，包含给 LLM 的自定义指令，帮助 OpenCode 理解项目结构和规范。类似 Cursor 的 rules。

创建 AGENTS.md

运行 /init 自动生成，或手动编写：

# 项目规则
## 技术栈
- 前端：React + TypeScript
- 后端：Node.js

## 编码规范
- 使用严格模式
- 共享代码放在 packages/core/

支持引用外部文件，如 CONTRIBUTING.md。

最佳实践与进阶技巧

1. 先规划后执行：利用 Plan 模式梳理逻辑，再切 Build 模式实现。
2. 上下文引用：多用 @ 引用关键文件，减少幻觉。
3. 性能优化：为轻量任务配置 small_model，启用自动压缩上下文。
4. 安全控制：敏感命令（如 rm *）建议设置为 ask 权限。
5. 团队协作：将 opencode.json、AGENTS.md 提交 Git 共享配置。

常见问题解答

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

Q: Shift+Enter 不工作？ A: 部分终端（如 Windows Terminal）需在 settings.json 中映射按键。

Q: 撤销操作无效？ A: 确保项目是 Git 仓库，依赖 Git 恢复文件。

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

Q: 遇到 content filter 错误？ A: Azure 资源需将过滤器从 DefaultV2 改为 Default。

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