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

桌面应用

OpenCode 还提供 Beta 版桌面应用，支持 macOS (Apple Silicon/Intel)、Windows 和 Linux。可通过 Releases 页面下载，或使用包管理器安装（如 brew install --cask opencode-desktop）。

快速开始

首次配置 Provider

进入项目目录后启动 OpenCode：

cd /path/to/your/project
opencode

运行 /connect 命令，选择 opencode 或其他支持的 Provider，访问授权页面获取 API 密钥并粘贴。

初始化项目

运行 /init 让 OpenCode 分析项目结构，这会创建一个 AGENTS.md 文件。建议将其提交到 Git 仓库，以便团队共享上下文。

基础交互

• 询问代码：直接输入自然语言，例如'给我简单介绍一下这个代码库'。
• 引用文件：使用 @ 符号引用具体文件，如 @src/components/Button.tsx 这个组件是如何工作的？。
• 执行命令：以 ! 前缀执行 Shell 命令，如 !npm test。

Plan 与 Build 模式

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

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

💡 提示：建议先用 Plan 模式确认方案，再切换到 Build 模式执行。

撤销与重做功能依赖 Git 仓库，使用 /undo 和 /redo 命令。

配置文件详解

OpenCode 支持 JSON 和 JSONC 格式的配置。

配置位置

优先级从高到低依次为：

1. .well-known/opencode（远程组织配置）
2. ~/.config/opencode/opencode.json（全局用户配置）
3. OPENCODE_CONFIG 环境变量
4. 项目根目录 opencode.json（项目专属）
5. .opencode 目录

常用配置项

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

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

Provider 配置

OpenCode 支持 75+ 个 LLM 提供商。常用的包括 OpenCode Zen、Anthropic、OpenAI、Google Vertex AI、Ollama 和 LM Studio。

配置本地模型（Ollama）

{
  "$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"},
        "codellama": {"name": "Code Llama"}
      }
    }
  }
}

💡 提示：如果工具调用不工作，尝试在 Ollama 中增加 num_ctx 到 16k-32k。

TUI 终端界面使用

基本操作

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

内置命令

导航与编辑器

• 滚动：PageUp/PageDown 或 Ctrl+Alt+b/f。
• 跳转：Ctrl+g 到顶部，Ctrl+Alt+g 到底部。
• 外部编辑：设置 EDITOR 环境变量（如 code --wait）后可使用 /editor 命令。

Agent 系统

Agent 类型

• 主 Agent：通过 Tab 键在 Build 和 Plan 之间切换。
• 子 Agent：使用 @ 提及，如 @general 或 @explore。

自定义 Agent

可以通过 JSON 配置或 Markdown 文件定义新 Agent。Markdown 文件需放在 .opencode/agents/ 目录下。

示例：

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

自定义命令

创建 .opencode/commands/ 下的文件或直接在配置中定义。

{
  "command": {
    "test": {
      "template": "运行完整的测试套件并显示覆盖率报告。\n关注失败的测试并提供修复建议。",
      "description": "运行测试并分析结果"
    }
  }
}

使用 $ARGUMENTS 或 $1, $2 进行参数替换，支持 Shell 命令输出 !`command`。

MCP 服务器

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

配置示例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true
    }
  }
}

常用集成包括 Sentry（错误监控）、Context7（文档搜索）和 Vercel Grep（代码搜索）。对于需要认证的服务器，可使用 opencode mcp auth 命令。

LSP 语言服务器

OpenCode 内置多种语言的 LSP 支持，包括 TypeScript、Python、Rust、Go、Java 等。当打开文件时，会自动启动对应的 LSP 服务器获取诊断信息。

可在配置中禁用特定 LSP 或全局关闭：{"lsp": false}。

主题与个性化

为了正确显示主题，终端需支持 Truecolor（24 位色）。

内置主题包括 opencode、tokyonight、catppuccin、gruvbox 等。可通过 /theme 命令切换或在配置文件中指定：{"theme": "tokyonight"}。

Rules 自定义指令

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

运行 /init 可自动生成。也可手动创建，支持引用外部文件（如 CONTRIBUTING.md）。

最佳实践与进阶技巧

1. 先规划后执行：利用 Plan 模式确认方案，避免无效修改。
2. 善用 @ 引用：明确指定上下文文件，提高回答准确率。
3. 性能优化：为轻量任务配置 small_model，启用自动压缩上下文。
4. 安全控制：敏感命令（如 rm *）建议设置为 ask 权限。
5. 团队协作：将 opencode.json、AGENTS.md 提交到 Git 仓库共享配置。

常见问题解答

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

Q2: Shift+Enter 不工作怎么办？ 部分终端需特殊配置。Windows Terminal 用户需在 settings.json 中添加相关按键映射。

Q3: 撤销操作不工作？ 确保项目是 Git 仓库，撤销功能依赖 Git 恢复文件更改。

Q4: 如何重置 OpenCode？ 删除配置和数据目录：

rm -rf ~/.config/opencode
rm -rf ~/.local/share/opencode

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