OpenCode 使用文档OpenCode 是一个开源的终端 AI 编程代理（AI Coding Agent），专为开发

OpenCode 使用文档

1. 详细介绍

1.1 什么是 OpenCode？

OpenCode 是一个开源的终端 AI 编程代理（AI Coding Agent），专为开发者在终端环境中与 AI 协作而设计。它能够理解你的代码库、执行代码修改、运行命令、创建新功能，就像一位随时待命的结对编程伙伴。

1.2 核心架构

┌─────────────────────────────────┐
│         OpenCode TUI            │
│  ┌─────────────────────────┐   │
│  │  Terminal User Interface│   │
│  │  • 实时对话交互         │   │
│  │  • 代码高亮/补全        │   │
│  │  • 多会话管理           │   │
│  └─────────────────────────┘   │
└─────────┬───────────────────────┘
          │ Client/Server 架构
          ▼
┌─────────────────────────────────┐
│         OpenCode Server         │
│  ┌─────────────────────────┐   │
│  │  • 代码库索引与理解     │   │
│  │  • LSP 语言服务器支持   │   │
│  │  • 工具调用编排         │   │
│  │  • 会话状态管理         │   │
│  └─────────────────────────┘   │
└─────────┬───────────────────────┘
          │ 可连接任意 LLM Provider
          ▼
┌─────────────────────────────────┐
│      LLM Providers (可选)       │
│  • OpenCode Zen (官方优化模型)  │
│  • Anthropic Claude 系列        │
│  • OpenAI GPT 系列              │
│  • Google Gemini 系列           │
│  • 本地模型 (Ollama/LM Studio)  │
└─────────────────────────────────┘

1.3 核心特性

特性	说明
🔓 100% 开源	代码完全开源，可审计、可修改、可自托管
🔌 多模型支持	不绑定任何提供商，支持任意 LLM API 或本地模型
🖥️ 终端优先	专为 neovim/终端用户设计，支持 ANSI 颜色、键盘快捷键
🔄 Client/Server 架构	可远程驱动，支持未来移动端/网页端客户端
🛠️ LSP 原生支持	开箱即用的语言服务器协议支持，精准代码理解
🤖 多 Agent 系统	内置 Build/Plan 主代理 + General/Explore 子代理
🔐 权限控制	精细的文件编辑/命令执行权限管理
📦 跨平台	macOS / Windows / Linux 全平台支持

2. 安装指南

2.1 系统要求

操作系统: macOS / Windows 10+ / Linux
终端: 支持 ANSI 颜色的现代终端（iTerm2, Windows Terminal, Alacritty 等）
网络: 能访问配置的 LLM 提供商 API
Node.js: v18.0 或更高版本（使用 npm 安装时）

2.2 安装方法

🔥 推荐：一键安装脚本

# YOLO 模式（自动检测系统并安装）
curl -fsSL https://opencode.ai/install | bash

📦 包管理器安装

平台	命令
npm	`npm install -g opencode-ai`
Bun	`bun install -g opencode-ai`
pnpm	`pnpm install -g opencode-ai`
Yarn	`yarn global add opencode-ai`
Homebrew (macOS/Linux)	`brew install anomalyco/tap/opencode` ⭐推荐
Homebrew (官方公式)	`brew install opencode`
Arch Linux (Stable)	`sudo pacman -S opencode`
Arch Linux (AUR)	`paru -S opencode-bin`
Windows (Chocolatey)	`choco install opencode`
Windows (Scoop)	`scoop install opencode`
Mise (多版本管理)	`mise use -g github:anomalyco/opencode`
Nix	`nix run nixpkgs#opencode`
Docker	`docker run -it --rm ghcr.io/anomalyco/opencode`

⚠️ 注意: 如果之前安装过 0.1.x 版本，请先卸载再安装新版。

💻 桌面应用 (Beta)

OpenCode 也提供桌面客户端，适合偏好图形界面的用户：

平台	下载文件
macOS (Apple Silicon)	`opencode-desktop-darwin-aarch64.dmg`
macOS (Intel)	`opencode-desktop-darwin-x64.dmg`
Windows	`opencode-desktop-windows-x64.exe`
Linux	`.deb` / `.rpm` / `AppImage`

# macOS 使用 Homebrew 安装桌面版
brew install --cask opencode-desktop

# Windows 使用 Scoop 安装桌面版
scoop bucket add extras
scoop install extras/opencode-desktop

下载地址：opencode.ai/download

2.3 安装路径配置

安装脚本按以下优先级确定安装位置：

$OPENCODE_INSTALL_DIR - 自定义安装目录
$XDG_BIN_DIR - XDG 规范路径
$HOME/bin - 标准用户二进制目录
$HOME/.opencode/bin - 默认回退路径

# 示例：自定义安装到 /usr/local/bin
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

# 示例：使用 XDG 规范路径
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

2.4 验证安装

# 检查版本
opencode --version

# 查看帮助
opencode --help

3. 命令大全

3.1 内置命令（以 `/` 开头）

命令	功能	示例
`/init`	初始化项目，分析代码结构并生成 `AGENTS.md`	`/init`
`/undo`	撤销上一次 AI 执行的代码修改	`/undo`
`/redo`	重做被撤销的修改	`/redo`
`/share`	生成当前对话的分享链接	`/share`
`/help`	显示帮助信息	`/help`
`/connect`	连接并配置 LLM 提供商 API Key	`/connect`
`/clear`	清空当前会话历史	`/clear`
`/exit`	退出 OpenCode	`/exit`

3.2 Agent 切换快捷键

快捷键	功能
`Tab`	在主代理 (Build ↔ Plan) 之间切换
`@agent_name`	手动调用子代理，如 `@general`、`@explore`
`<Leader>+Down`	进入子代理创建的子会话
`←` / `→`	在子会话间切换
`↑`	返回父会话

3.3 自定义命令

在 .opencode/commands/ 或 ~/.config/opencode/commands/ 创建 .md 文件：

---
description: 运行测试并生成覆盖率报告
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

运行完整测试套件并生成覆盖率报告：
!`npm test -- --coverage`

重点关注失败的测试并提供修复建议。

使用方式：在 TUI 中输入 /test 即可执行。

自定义命令高级语法

---
description: 创建新 React 组件
---

创建一个名为 $ARGUMENTS 的 TypeScript React 组件，包含：
- 正确的类型定义
- 基础组件结构
- 默认导出

相关文件参考：@src/components/Template.tsx

占位符	说明	示例
`$ARGUMENTS`	所有参数拼接	`/component Button` → `Button`
`$1`, `$2`, `$3`	位置参数	`/cmd a b c` → `$1=a, $2=b, $3=c`
`!`command``	执行 shell 命令并注入输出	`!`git status``
`@filename`	自动包含文件内容	`@src/main.ts`

3.4 配置文件选项

全局配置：~/.config/opencode/config.json
项目配置：./.opencode/config.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "temperature": 0.2,
  "agent": {
    "build": {
      "mode": "primary",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "tools": {
        "write": false,
        "edit": false,
        "bash": "ask"
      }
    }
  },
  "permissions": {
    "edit": "ask",
    "bash": "allow",
    "webfetch": "deny"
  }
}

4. 核心功能

4.1 双主代理系统

🔨 Build Agent（默认）

模式: primary
权限: 全工具访问（文件读写、命令执行、网络请求）
用途: 日常开发、功能实现、代码重构

📋 Plan Agent（只读分析）

模式: primary
权限: 默认所有操作设为 ask（需确认）
用途: 代码审查、架构分析、变更规划

# 使用 Tab 键切换代理
# 右下角会显示当前代理: [BUILD] 或 [PLAN]

4.2 子代理系统

子代理	模式	用途	调用方式
`@general`	subagent	复杂任务研究、多步骤执行	`@general 帮我分析这个模块`
`@explore`	subagent	快速代码库探索、只读搜索	`@explore 查找所有使用 auth 的文件`

4.3 工具能力

工具	功能	权限控制
`write`	创建新文件	allow/ask/deny
`edit`	修改现有文件	allow/ask/deny
`patch`	应用代码补丁	allow/ask/deny
`bash`	执行 shell 命令	allow/ask/deny
`webfetch`	获取网页内容	allow/ask/deny
`lsp`	语言服务器查询	内置启用

4.4 核心能力清单

✅ 代码理解

自动索引项目结构
理解模块依赖关系
识别代码模式和最佳实践

✅ 智能编辑

精准代码修改（基于 AST）
批量重构支持
自动格式化集成

✅ 任务执行

运行测试/构建命令
自动修复失败测试
依赖安装与升级

✅ 知识增强

拖拽图片到终端进行视觉分析
引用外部文档/规范
团队对话分享 (/share)

✅ 安全控制

所有修改可撤销 (/undo)
敏感操作需确认
完整的操作日志

5. 项目使用教程

5.1 快速开始

# 1. 进入项目目录
cd /path/to/your/project

# 2. 启动 OpenCode
opencode

# 3. 首次使用：连接模型提供商
# 在 TUI 中输入：
/connect
# 按指引完成认证（推荐 OpenCode Zen 或配置自有 API Key）

# 4. 初始化项目分析
# 在 TUI 中输入：
/init
# 等待生成 AGENTS.md（帮助 AI 理解项目规范）

5.2 典型工作流

🎯 场景1：理解陌生代码库

# 切换到 Plan 模式 (按 Tab)
[PLAN] 这个项目的认证流程是如何实现的？

# 引用具体文件深入询问
[PLAN] 请分析 @src/auth/middleware.ts 的权限校验逻辑

# 切换到 Build 模式执行修改
[<TAB>]
[BUILD] 基于分析结果，添加日志记录到认证失败场景

🎯 场景2：开发新功能（推荐分步法）

# 第一步：规划（Plan 模式）
[TAB] → [PLAN]
[PLAN] 我需要添加用户头像上传功能，要求：
       - 支持 JPG/PNG，最大 5MB
       - 上传后生成缩略图
       - 存储到 S3
       请先给出实现方案

# 第二步：迭代方案
[PLAN] 方案不错，但缩略图用 sharp 库代替 canvas，
       并添加上传进度回调

# 第三步：执行（Build 模式）
[<TAB>] → [BUILD]
[BUILD] 方案确认，请开始实现

🎯 场景3：修复 Bug

# 直接描述问题
[BUILD] @src/api/users.ts 的 getUser 函数在处理
        空值时会抛出异常，请修复并添加测试

# 如果需要回退
/undo  # 撤销上次修改
/redo  # 重做修改

# 确认无误后提交
# OpenCode 会自动生成 git commit 建议

5.3 高级技巧

🔍 精准引用文件

# 使用 @ 符号引用文件，内容自动注入上下文
请优化 @src/components/Button.tsx 的点击处理逻辑

# 引用多个文件
对比 @src/v1/api.ts 和 @src/v2/api.ts 的差异

🖼️ 视觉辅助

# 拖拽设计稿/截图到终端
[图片自动分析] 请根据这个 UI 设计实现 React 组件

🔄 会话管理

# 分享对话给团队成员
/share  # 生成可分享链接

# 清理上下文（节省 Token）
/clear  # 清空历史，保留当前项目状态

⚙️ 自定义工作流

# 创建项目专用命令
mkdir -p .opencode/commands
cat > .opencode/commands/deploy.md << 'EOF'
---
description: 执行预发布检查并部署
agent: build
---
1. 运行类型检查: !`npm run typecheck`
2. 运行测试: !`npm test`
3. 构建生产版本: !`npm run build`
4. 如果全部通过，执行部署脚本
5. 输出部署结果和回滚方案
EOF

# 使用时输入 /deploy

5.4 配置最佳实践

// .opencode/config.json
{
  "model": "anthropic/claude-sonnet-4-20250514",
  "temperature": 0.1,
  "max_steps": 50,
  "agent": {
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "tools": { "write": true, "edit": true, "bash": "ask" }
    },
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": { "write": false, "edit": false, "bash": false }
    }
  },
  "permissions": {
    "edit": "ask",
    "bash": {
      "allow": ["npm", "git", "docker"],
      "deny": ["rm -rf", "sudo", "curl | bash"]
    }
  }
}

6. 与 Codex / Claude Code 对比

6.1 核心差异总览

维度	OpenCode (anomalyco)	OpenAI Codex	Claude Code (Anthropic)
开源状态	✅ 100% 开源 (MIT)	❌ 闭源 API	❌ 闭源 CLI 工具
模型绑定	🔓 任意 Provider / 本地模型	🔒 仅 OpenAI 模型	🔒 仅 Claude 模型
部署方式	🖥️ 终端 / 桌面 / 远程	☁️ API 调用	🖥️ 官方 CLI
数据隐私	🔐 可完全本地运行	⚠️ 代码发送至 OpenAI	⚠️ 代码发送至 Anthropic
LSP 支持	✅ 开箱即用	⚠️ 依赖 Copilot 集成	⚠️ 基础支持
TUI 体验	⭐ 专为终端优化	❌ 无终端界面	✅ 良好终端体验
架构扩展	🔄 Client/Server 支持远程	❌ 仅本地调用	❌ 仅本地调用
成本	💰 免费 + 自选 API / 本地	💸 按 Token 计费	💸 按 Token + 订阅
自定义	🔧 完全可配置 Agent/命令/Prompt	🔧 有限 System Prompt	🔧 可配置 System Prompt

6.2 详细对比分析

🔹 OpenCode 优势

真正的开源自由
- 代码可审计，无黑盒逻辑
- 可 Fork 定制，适配企业内网需求
- 社区驱动，快速响应新模型/新需求

模型无关架构

# 今天用 Claude，明天换 Gemini，后天用本地模型
# 只需修改 config.json，无需重写工作流
{
  "model": "google/gemini-2.0-flash",  // 随时切换
  "fallback_models": ["ollama/qwen2.5-coder"]
}

终端原生体验
- 为 neovim 用户设计，键盘操作优先
- 支持鼠标、快捷键、主题定制
- 低资源占用，适合远程服务器开发
企业级可控性
- 精细权限系统（文件/命令粒度控制）
- 完整操作审计日志
- 支持私有模型部署 + 内网隔离

🔹 Codex 现状

已整合: Codex 技术已融入 GitHub Copilot，不再作为独立产品
适用场景: GitHub 生态深度集成项目
局限: 无法脱离 OpenAI 生态，定制性弱

🔹 Claude Code 优势

模型能力: Claude 3.5 Sonnet 当前代码理解能力业界领先
开箱即用: 安装简单，默认配置即可高效工作
规划能力: 内置 Chain-of-Thought，复杂任务规划更可靠

🔹 Claude Code 局限

厂商锁定: 必须使用 Anthropic 模型，无法切换
成本较高: 高级模型 Token 价格显著高于开源方案
隐私顾虑: 代码需发送至 Anthropic 服务器

6.3 选型建议

✅ 选择 OpenCode 如果：
   • 注重代码隐私/数据主权
   • 需要多模型切换或本地部署
   • 偏好终端工作流/可定制性
   • 企业环境需要审计/权限控制
   • 预算敏感，希望控制 API 成本

✅ 选择 Claude Code 如果：
   • 追求最强单模型代码能力
   • 快速启动，不愿配置复杂环境
   • 项目不涉密，可接受云端处理
   • 预算充足，重视开发效率

✅ 选择 GitHub Copilot (Codex) 如果：
   • 深度使用 GitHub 生态
   • 需要 IDE 内无缝集成
   • 团队已采购 GitHub Enterprise

6.4 混合使用策略（推荐）

# config.json 示例：按任务分配模型
{
  "agent": {
    "build": {
      // 复杂实现用 Claude
      "model": "anthropic/claude-sonnet-4-20250514"
    },
    "plan": {
      // 规划分析用性价比模型
      "model": "google/gemini-2.0-flash"
    },
    "explore": {
      // 快速搜索用本地模型
      "model": "ollama/qwen2.5-coder:7b"
    }
  }
}

7. 最佳实践与技巧

7.1 提示词工程

✅ 好的 Prompt:
"在 @src/auth 目录下添加 JWT 刷新令牌功能，
参考 @src/auth/login.ts 的实现风格，
要求：
- 令牌有效期 7 天
- 支持黑名单机制
- 添加单元测试"

❌ 模糊的 Prompt:
"加个刷新令牌"

7.2 上下文管理

精准引用: 用 @文件 代替"这个文件"，避免歧义
分步任务: 复杂需求拆分为规划→确认→执行三步
及时清理: 长对话用 /clear 避免上下文膨胀

7.3 安全实践

// 生产环境推荐权限配置
{
  "permissions": {
    "edit": "ask",           // 所有文件修改需确认
    "bash": {
      "allow": ["npm", "git", "pnpm"],  // 白名单命令
      "deny": ["rm", "sudo", "curl"]    // 黑名单命令
    },
    "webfetch": "deny"       // 禁止外部请求
  }
}

7.4 性能优化

优化项	方法	效果
减少 Token	用 `@file` 引用代替粘贴大段代码	节省 70%+ 上下文
本地模型	简单任务用 Ollama + Qwen-Coder	零 API 成本
缓存策略	重复查询启用 `cache: true`	加速 3-5 倍
并行子任务	用 `@general` 并行处理独立模块	缩短 40% 等待

8. 常见问题

8.1 OpenCode 需要付费吗？

工具本身: 完全免费开源
模型成本:
- 使用本地模型 (Ollama): 免费，仅需硬件
- 使用云端 API: 按提供商计费 (可自选廉价模型)
- OpenCode Zen: 官方优化模型，按需付费

8.2 支持中文吗？

✅ 完全支持。推荐模型：

云端: qwen/qwen2.5-coder-32b (通义千问)
本地: ollama/qwen2.5-coder:7b
配置示例: "model": "qwen/qwen2.5-coder-32b"

8.3 如何保证 AI 不写 Bug？

权限控制: 敏感操作设为 ask 需人工确认
可撤销: 所有修改支持 /undo 回退
测试先行: 要求 AI 先写测试再实现功能
Code Review: AI 生成的代码仍需人工审查
CI 集成: 配合 GitHub Actions 自动验证

8.4 能离线使用吗？

✅ 可以，需配置本地模型：

# 1. 安装 Ollama
brew install ollama  # macOS
# 或 https://ollama.ai

# 2. 拉取代码模型
ollama pull qwen2.5-coder:7b

# 3. 配置 OpenCode
{
  "model": "ollama/qwen2.5-coder:7b",
  "api_base": "http://localhost:11434"
}

8.5 如何团队协作？

# 1. 共享配置
git add .opencode/config.json

# 2. 分享对话
/share  # 生成链接发给同事

# 3. 统一命令
# 在 .opencode/commands/ 创建团队标准命令
# 如 /lint, /test-all, /deploy-staging

# 4. Agent 规范
# 在 AGENTS.md 中定义团队编码规范

8.6 与 Cursor / Windsurf 区别？

工具	核心定位	开源	终端支持
OpenCode	终端 AI Agent	✅	⭐ 原生优化
Cursor	IDE 集成编辑器	❌	❌
Windsurf	IDE 插件	❌	❌

OpenCode 更适合：终端重度用户、远程开发、自动化脚本、企业定制场景

OpenCode 使用文档

OpenCode 使用文档

目录

1. 详细介绍

1.1 什么是 OpenCode？

1.2 核心架构

1.3 核心特性

2. 安装指南

2.1 系统要求

2.2 安装方法

🔥 推荐：一键安装脚本

📦 包管理器安装

💻 桌面应用 (Beta)

2.3 安装路径配置

2.4 验证安装

3. 命令大全

3.1 内置命令（以 / 开头）

3.2 Agent 切换快捷键

3.3 自定义命令

自定义命令高级语法

3.4 配置文件选项

4. 核心功能

4.1 双主代理系统

🔨 Build Agent（默认）

📋 Plan Agent（只读分析）

4.2 子代理系统

4.3 工具能力

4.4 核心能力清单

5. 项目使用教程

5.1 快速开始

5.2 典型工作流

🎯 场景1：理解陌生代码库

🎯 场景2：开发新功能（推荐分步法）

🎯 场景3：修复 Bug

5.3 高级技巧

🔍 精准引用文件

🖼️ 视觉辅助

🔄 会话管理

⚙️ 自定义工作流

5.4 配置最佳实践

6. 与 Codex / Claude Code 对比

6.1 核心差异总览

6.2 详细对比分析

🔹 OpenCode 优势

🔹 Codex 现状

🔹 Claude Code 优势

🔹 Claude Code 局限

6.3 选型建议

6.4 混合使用策略（推荐）

7. 最佳实践与技巧

7.1 提示词工程

7.2 上下文管理

7.3 安全实践

7.4 性能优化

8. 常见问题

8.1 OpenCode 需要付费吗？

8.2 支持中文吗？

8.3 如何保证 AI 不写 Bug？

8.4 能离线使用吗？

8.5 如何团队协作？

8.6 与 Cursor / Windsurf 区别？

9. 实战截图

链接地址：github.com/tanghong199…

3.1 内置命令（以 `/` 开头）