OpenCode 完全使用指南：开源 AI 编程助手入门到精通

OpenCode 完全使用指南：开源 AI 编程助手入门到精通

本教程基于 OpenCode 官方文档（https://opencode.ai/docs）和 GitHub 仓库（https://github.com/anomalyco/opencode）编写，适合零基础新手入门。

📚 目录

1. 什么是 OpenCode
2. 安装指南
3. 快速开始
4. 配置文件详解
5. Provider 配置
6. TUI 终端界面使用
7. Agent 系统
8. 自定义命令
9. 快捷键配置
10. MCP 服务器
11. LSP 语言服务器
12. 主题与个性化
13. Rules 自定义指令
14. 最佳实践与进阶技巧
15. 常见问题解答

1. 什么是 OpenCode

1.1 概述

OpenCode 是一个 100% 开源的 AI 编程代理（Coding Agent），提供终端界面（TUI）、桌面应用和 IDE 扩展多种使用方式。它可以帮助开发者：

• 🤖 与 AI 对话编写代码
• 📝 分析和理解代码库
• 🔧 自动修改和重构代码
• 🐛 调试和修复问题
• 📚 生成文档和测试

1.2 核心特点

1.3 与 Claude Code 的区别

2. 安装指南

2.1 前置要求

1. 现代终端模拟器（推荐）：
   • WezTerm - 跨平台
   • Alacritty - 跨平台
   • Ghostty - Linux/macOS
   • Kitty - Linux/macOS
   • Windows Terminal - Windows
2. LLM Provider 的 API 密钥（至少需要一个）

2.2 通用安装（推荐）

最简单的安装方式，适用于 macOS 和 Linux：

curl -fsSL https://opencode.ai/install |bash

2.3 macOS 安装

使用 Homebrew（推荐）

# 官方 tap（更新更快） brew install anomalyco/tap/opencode # 或者使用官方 formula（更新较慢） brew install opencode 

2.4 Linux 安装

Debian/Ubuntu

# 使用 npmnpminstall -g opencode-ai # 或使用安装脚本curl -fsSL https://opencode.ai/install |bash

Arch Linux

paru -S opencode-bin 

2.5 Windows 安装

使用 Chocolatey

choco install opencode 

使用 Scoop

scoop install opencode 

使用 npm

npm install -g opencode-ai 

2.6 使用包管理器

npm / Bun / pnpm / Yarn

# npmnpminstall -g opencode-ai # Bun bun install -g opencode-ai # pnpmpnpminstall -g opencode-ai # Yarnyarn global add opencode-ai 

2.7 使用 Docker

docker run -it --rm ghcr.io/anomalyco/opencode 

2.8 使用 Nix

# 使用 nixpkgs nix run nixpkgs#opencode# 使用最新开发版 nix run github:anomalyco/opencode 

2.9 桌面应用（Beta）

OpenCode 还提供桌面应用程序，可从 Releases 页面 或 opencode.ai/download 下载。

# macOS 使用 Homebrew brew install --cask opencode-desktop # Windows 使用 Scoop scoop bucket add extras scoop install extras/opencode-desktop 

2.10 自定义安装目录

安装脚本支持以下优先级顺序的安装路径：

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

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

3. 快速开始

3.1 首次配置 Provider

1. 进入你的项目目录：

cd /path/to/your/project 

2. 启动 OpenCode：

opencode 

3. 配置 Provider（以 OpenCode Zen 为例）：

/connect 

4. 选择 opencode，然后访问 opencode.ai/auth 获取 API 密钥
5. 粘贴你的 API 密钥

3.2 初始化项目

运行初始化命令，让 OpenCode 分析你的项目：

/init 

这会创建一个 AGENTS.md 文件，帮助 OpenCode 更好地理解你的项目结构。

💡 提示：建议将 AGENTS.md 提交到 Git 仓库

3.3 基础使用示例

询问代码问题

给我简单介绍一下这个代码库 

引用文件

使用 @ 符号引用项目中的文件：

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

添加新功能

请在 @src/api/auth.ts 中添加用户登录功能 

执行 Shell 命令

使用 ! 前缀执行命令：

!npm test 

3.4 Plan 与 Build 模式

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

# 先用 Plan 模式规划 <Tab 切换到 Plan> 实现一个用户删除功能，要求软删除，并提供恢复界面 # 确认方案后切换到 Build 模式执行 <Tab 切换到 Build> 按照刚才的计划开始实现 

3.5 撤销与重做

/undo # 撤销上一个操作（包括文件修改） /redo # 重做已撤销的操作 

⚠️ 注意：撤销/重做功能需要项目是 Git 仓库

4. 配置文件详解

4.1 配置文件格式

OpenCode 支持 JSON 和 JSONC（带注释的 JSON）格式：

{ "$schema": "https://opencode.ai/config.json", // 主题配置 "theme": "opencode", "model": "anthropic/claude-sonnet-4-5", "autoupdate": true } 

4.2 配置文件位置

配置文件按以下优先级加载（后面的覆盖前面的）：

4.3 完整配置示例

{ "$schema": "https://opencode.ai/config.json", // 主题设置 "theme": "tokyonight", // 模型设置 "model": "anthropic/claude-sonnet-4-5", "small_model": "anthropic/claude-haiku-4-5", // 自动更新 "autoupdate": true, // TUI 设置 "tui": { "scroll_speed": 3, "scroll_acceleration": { "enabled": true }, "diff_style": "auto" }, // 服务器设置 "server": { "port": 4096, "hostname": "0.0.0.0", "mdns": true }, // 工具权限 "permission": { "edit": "allow", "bash": "ask" }, // 自动压缩 "compaction": { "auto": true, "prune": true }, // 指令文件 "instructions": [ "CONTRIBUTING.md", "docs/guidelines.md" ] } 

4.4 变量替换

环境变量

{"model":"{env:OPENCODE_MODEL}","provider":{"anthropic":{"options":{"apiKey":"{env:ANTHROPIC_API_KEY}"}}}}

文件内容

{"provider":{"openai":{"options":{"apiKey":"{file:~/.secrets/openai-key}"}}}}

5. Provider 配置

5.1 支持的 Provider

OpenCode 支持 75+ LLM 提供商，以下是常用的：

5.2 配置 Anthropic

使用 Claude Pro/Max 订阅

/connect 

选择 Anthropic → Claude Pro/Max，浏览器会自动打开进行认证。

使用 API 密钥

/connect 

选择 Anthropic → Manually enter API Key，然后输入密钥。

5.3 配置 OpenAI

使用 ChatGPT Plus/Pro 订阅

/connect 

选择 OpenAI → ChatGPT Plus/Pro，浏览器会自动打开进行认证。

5.4 配置 OpenCode Zen（推荐新手）

OpenCode Zen 是官方提供的经过测试验证的模型列表：

1. 访问 opencode.ai/auth 创建 API 密钥
2. 运行 /connect，选择 opencode
3. 粘贴 API 密钥
4. 运行 /models 查看可用模型

5.5 配置本地模型（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

5.6 配置 LM Studio

{"$schema":"https://opencode.ai/config.json","provider":{"lmstudio":{"npm":"@ai-sdk/openai-compatible","name":"LM Studio (local)","options":{"baseURL":"http://127.0.0.1:1234/v1"},"models":{"google/gemma-3n-e4b":{"name":"Gemma 3n-e4b (local)"}}}}}

5.7 配置 Amazon Bedrock

{"$schema":"https://opencode.ai/config.json","provider":{"amazon-bedrock":{"options":{"region":"us-east-1","profile":"my-aws-profile"}}}}

或使用环境变量：

# 使用 AWS 访问密钥AWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY opencode # 使用命名配置文件AWS_PROFILE=my-profile opencode 

5.8 配置 OpenRouter

{"$schema":"https://opencode.ai/config.json","provider":{"openrouter":{"models":{"moonshotai/kimi-k2":{"options":{"provider":{"order":["baseten"],"allow_fallbacks":false}}}}}}}

5.9 禁用/启用特定 Provider

{"$schema":"https://opencode.ai/config.json",// 禁用特定 provider"disabled_providers":["openai","gemini"],// 或只启用特定 provider"enabled_providers":["anthropic","opencode"]}

6. TUI 终端界面使用

6.1 启动 TUI

# 当前目录 opencode # 指定目录 opencode /path/to/project 

6.2 基本操作

发送消息

直接输入文字后按 Enter 发送。

换行输入

• Shift+Enter - 插入换行
• Ctrl+Enter - 插入换行
• Alt+Enter - 插入换行

引用文件

输入 @ 然后模糊搜索文件名：

@src/api/ → 选择文件 

执行 Shell 命令

以 ! 开头：

!git status !npm run build 

6.3 内置命令

6.4 导航操作

6.5 编辑器设置

配置 EDITOR 环境变量以使用 /editor 和 /export 命令：

# Linux/macOS - 添加到 ~/.bashrc 或 ~/.zshrcexportEDITOR="code --wait"# VS CodeexportEDITOR=vim # VimexportEDITOR=nvim # Neovim

# Windows PowerShell$env:EDITOR = "code --wait"

⚠️ 注意：VS Code 等 GUI 编辑器需要 --wait 参数

7. Agent 系统

7.1 Agent 类型

主 Agent（Primary）

直接交互的主要 Agent，使用 Tab 键切换：

子 Agent（Subagent）

由主 Agent 调用或使用 @ 手动调用：

7.2 使用 Agent

切换主 Agent

按 Tab 键在 Build 和 Plan 之间切换。

调用子 Agent

使用 @ 提及：

@general 帮我搜索这个函数的所有调用位置 @explore 分析一下项目结构 

7.3 自定义 Agent

JSON 配置方式

{"$schema":"https://opencode.ai/config.json","agent":{"code-reviewer":{"description":"代码审查专家","mode":"subagent","model":"anthropic/claude-sonnet-4-5","prompt":"你是一个代码审查专家，专注于安全性、性能和可维护性。","tools":{"write":false,"edit":false}}}}

Markdown 文件方式

创建 .opencode/agents/reviewer.md 或 ~/.config/opencode/agents/reviewer.md：

--- description: 代码审查专家 mode: subagent model: anthropic/claude-sonnet-4-5 temperature: 0.1 tools: write: false edit: false bash: false --- 你是一个代码审查专家。请关注： - 代码质量和最佳实践 - 潜在的 bug 和边界情况 - 性能影响 - 安全考虑 提供建设性的反馈，不要直接修改代码。 

7.4 Agent 配置选项

7.5 Agent 权限配置

{"agent":{"safe-build":{"mode":"primary","permission":{"edit":"ask","bash":{"*":"ask","git status *":"allow","git diff *":"allow"}}}}}

8. 自定义命令

8.1 创建命令

JSON 配置方式

{"$schema":"https://opencode.ai/config.json","command":{"test":{"template":"运行完整的测试套件并显示覆盖率报告。\n关注失败的测试并提供修复建议。","description":"运行测试并分析结果","agent":"build","model":"anthropic/claude-haiku-4-5"},"component":{"template":"创建一个名为 $ARGUMENTS 的 React 组件。\n包含 TypeScript 类型定义和基本结构。","description":"创建新组件"}}}

Markdown 文件方式

创建 .opencode/commands/test.md：

--- description: 运行测试并分析覆盖率 agent: build model: anthropic/claude-haiku-4-5 --- 运行完整的测试套件并显示覆盖率报告。 关注失败的测试并提供修复建议。 

8.2 使用命令

/test /component Button 

8.3 命令模板语法

参数替换

• $ARGUMENTS - 所有参数
• $1, $2, $3 - 位置参数

--- description: 创建文件 --- 在目录 $2 中创建名为 $1 的文件，内容为：$3 

使用：

/create-file config.json src "{ \"key\": \"value\" }" 

Shell 命令输出

使用 !`command` 语法：

--- description: 分析测试覆盖率 --- 当前测试结果： !`npm test` 基于这些结果，建议如何提高覆盖率。 

文件引用

--- description: 审查组件 --- 审查 @src/components/Button.tsx 组件，检查性能问题并提供改进建议。 

8.4 命令选项

9. 快捷键配置

9.1 Leader 键

OpenCode 使用 Leader 键避免与终端快捷键冲突。默认 Leader 键是 Ctrl+x。

例如，新建会话：先按 Ctrl+x，再按 n。

9.2 自定义快捷键

{"$schema":"https://opencode.ai/config.json","keybinds":{"leader":"ctrl+x","app_exit":"ctrl+c,ctrl+d,<leader>q","session_new":"<leader>n","session_list":"<leader>l","model_list":"<leader>m","agent_cycle":"tab","input_submit":"return","input_newline":"shift+return,ctrl+return","session_interrupt":"escape"}}

9.3 禁用快捷键

设置为 "none" 禁用：

{"keybinds":{"session_compact":"none"}}

9.4 完整快捷键列表

10. MCP 服务器

10.1 什么是 MCP

Model Context Protocol (MCP) 是一种协议，允许 OpenCode 集成外部工具和服务。通过 MCP，你可以：

• 连接数据库
• 集成 API
• 使用第三方服务
• 扩展 AI 能力

10.2 配置本地 MCP 服务器

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

10.3 配置远程 MCP 服务器

{"$schema":"https://opencode.ai/config.json","mcp":{"my-remote-mcp":{"type":"remote","url":"https://my-mcp-server.com","enabled":true,"headers":{"Authorization":"Bearer MY_API_KEY"}}}}

10.4 常用 MCP 示例

Sentry（错误监控）

{"mcp":{"sentry":{"type":"remote","url":"https://mcp.sentry.dev/mcp","oauth":{}}}}

然后运行认证：

opencode mcp auth sentry 

使用：

显示我项目中最新的未解决问题。use sentry 

Context7（文档搜索）

{"mcp":{"context7":{"type":"remote","url":"https://mcp.context7.com/mcp"}}}

使用：

如何配置 Cloudflare Worker 来缓存 JSON API 响应？use context7 

Grep by Vercel（代码搜索）

{"mcp":{"gh_grep":{"type":"remote","url":"https://mcp.grep.app"}}}

使用：

搜索 React hooks 的最佳实践示例。use the gh_grep tool 

10.5 OAuth 认证

对于需要认证的 MCP 服务器：

# 认证 opencode mcp auth my-oauth-server # 查看状态 opencode mcp list # 登出 opencode mcp logout my-oauth-server 

10.6 MCP 权限管理

全局禁用

{"tools":{"my-mcp*":false}}

按 Agent 启用

{"mcp":{"my-mcp":{"type":"local","command":["bun","x","my-mcp-command"],"enabled":true}},"tools":{"my-mcp*":false},"agent":{"my-agent":{"tools":{"my-mcp*":true}}}}

11. LSP 语言服务器

11.1 内置 LSP 支持

OpenCode 内置多种语言的 LSP 服务器支持：

11.2 LSP 如何工作

当 OpenCode 打开文件时：

1. 检查文件扩展名
2. 启动对应的 LSP 服务器
3. 获取诊断信息（错误、警告）
4. 将诊断反馈给 LLM

11.3 自定义 LSP 配置

{"$schema":"https://opencode.ai/config.json","lsp":{"custom-lsp":{"command":["custom-lsp-server","--stdio"],"extensions":[".custom"]}}}

11.4 禁用 LSP

禁用所有 LSP

{"lsp":false}

禁用特定 LSP

{"lsp":{"typescript":{"disabled":true}}}

11.5 禁用自动下载

exportOPENCODE_DISABLE_LSP_DOWNLOAD=true 

12. 主题与个性化

12.1 终端要求

为了正确显示主题，你的终端需要支持 truecolor（24位色）：

# 检查支持echo$COLORTERM# 应输出 truecolor 或 24bit# 启用 truecolorexportCOLORTERM=truecolor 

12.2 内置主题

12.3 切换主题

使用命令

/theme 

配置文件

{"theme":"tokyonight"}

12.4 自定义主题

创建 ~/.config/opencode/themes/my-theme.json 或 .opencode/themes/my-theme.json：

{"$schema":"https://opencode.ai/theme.json","defs":{"bg":"#1a1b26","fg":"#c0caf5","accent":"#7aa2f7","error":"#f7768e","warning":"#e0af68","success":"#9ece6a"},"theme":{"primary":{"dark":"accent","light":"accent"},"text":{"dark":"fg","light":"#1a1b26"},"background":{"dark":"bg","light":"#ffffff"},"error":{"dark":"error","light":"error"},"warning":{"dark":"warning","light":"warning"},"success":{"dark":"success","light":"success"}}}

12.5 颜色格式

• Hex 颜色: "#ffffff"
• ANSI 颜色: 3（0-255）
• 引用定义: "primary"
• 深浅变体: {"dark": "#000", "light": "#fff"}
• 无颜色: "none"（使用终端默认）

13. Rules 自定义指令

13.1 什么是 AGENTS.md

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

13.2 创建 AGENTS.md

自动生成

/init 

这会扫描项目并自动生成 AGENTS.md。

手动创建

# 我的 TypeScript 项目 这是一个使用 bun workspaces 的 SST v3 monorepo 项目。 ## 项目结构 - `packages/` - 所有工作区包（functions, core, web 等） - `infra/` - 基础设施定义（storage.ts, api.ts, web.ts） - `sst.config.ts` - 主 SST 配置 ## 代码规范 - 使用 TypeScript 严格模式 - 共享代码放在 `packages/core/` - 函数代码放在 `packages/functions/` - 基础设施按逻辑拆分到 `infra/` 目录 ## Monorepo 约定 - 使用工作区名称导入共享模块：`@my-app/core/example` 

13.3 文件位置

13.4 Claude Code 兼容性

OpenCode 支持 Claude Code 的文件约定作为回退：

• CLAUDE.md → 用作 AGENTS.md
• ~/.claude/CLAUDE.md → 用作全局指令

禁用兼容性：

exportOPENCODE_DISABLE_CLAUDE_CODE=1

13.5 引用外部文件

使用配置文件

{"instructions":["CONTRIBUTING.md","docs/guidelines.md",".cursor/rules/*.md","https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]}

在 AGENTS.md 中引用

# 项目规则 ## 外部文件加载 重要：当遇到文件引用（如 @rules/general.md）时，使用 Read 工具按需加载。 ## 开发指南 TypeScript 代码风格：@docs/typescript-guidelines.md React 组件架构：@docs/react-patterns.md API 设计规范：@docs/api-standards.md 

14. 最佳实践与进阶技巧

14.1 高效工作流

1. 先规划后执行

<Tab 切换到 Plan 模式> 我需要实现用户认证功能，包括登录、注册、密码重置 <分析完成后> <Tab 切换到 Build 模式> 按照计划开始实现 

2. 使用 @ 引用上下文

参考 @src/auth/login.ts 的实现方式，在 @src/auth/register.ts 中添加注册功能 

3. 拖放图片

在终端中拖放图片，可以让 LLM 参考设计稿：

按照这个设计稿实现登录界面 [拖入设计稿图片] 

14.2 项目设置建议

创建项目专属配置

// opencode.json（放在项目根目录）{"$schema":"https://opencode.ai/config.json","model":"anthropic/claude-sonnet-4-5","instructions":["CONTRIBUTING.md","docs/DEVELOPMENT.md"],"formatter":{"prettier":{"command":["npx","prettier","--write","$FILE"]}}}

设置完善的 AGENTS.md

# 项目名称 ## 技术栈 - 前端：React + TypeScript + Tailwind - 后端：Node.js + Express - 数据库：PostgreSQL ## 目录结构 ... ## 编码规范 ... ## 常见任务 - 创建新组件：使用 `packages/ui` 目录 - 添加 API：在 `packages/api/src/routes` 创建 

14.3 性能优化

1. 使用 small_model

为轻量任务（如生成标题）配置更便宜的模型：

{"model":"anthropic/claude-sonnet-4-5","small_model":"anthropic/claude-haiku-4-5"}

2. 启用自动压缩

{"compaction":{"auto":true,"prune":true}}

3. 合理配置 MCP

避免添加太多 MCP 服务器，每个都会增加上下文：

{"tools":{"heavy-mcp*":false}}

14.4 团队协作

1. 共享配置

将以下文件提交到 Git：

• opencode.json
• AGENTS.md
• .opencode/ 目录

2. 分享会话

/share 

获取可分享的链接。

14.5 安全最佳实践

1. 使用权限控制

{"permission":{"bash":"ask","edit":"allow"}}

2. 敏感命令需要确认

{"agent":{"build":{"permission":{"bash":{"*":"allow","rm *":"ask","git push*":"ask","npm publish":"ask"}}}}}

14.6 调试技巧

1. 查看工具执行详情

/details 

2. 查看思考过程

/thinking 

3. 导出会话进行分析

/export 

15. 常见问题解答

Q1: 如何更换模型？

/models 

或在配置文件中设置：

{"model":"openai/gpt-4o"}

Q2: Shift+Enter 不工作怎么办？

某些终端需要特殊配置。Windows Terminal 用户需在 settings.json 中添加：

{"actions":[{"command":{"action":"sendInput","input":"\u001b[13;2u"},"id":"User.sendInput.ShiftEnterCustom"}],"keybindings":[{"keys":"shift+enter","id":"User.sendInput.ShiftEnterCustom"}]}

Q3: 如何使用本地模型？

配置 Ollama 或 LM Studio：

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

Q4: 撤销操作不工作？

确保项目是 Git 仓库。撤销功能依赖 Git 来恢复文件更改。

Q5: 如何禁用自动更新？

{"autoupdate":false}

或只通知不更新：

{"autoupdate":"notify"}

Q6: API 密钥存储在哪里？

~/.local/share/opencode/auth.json

Q7: 如何完全重置 OpenCode？

# 删除配置rm -rf ~/.config/opencode # 删除数据rm -rf ~/.local/share/opencode 

Q8: 遇到 “content filter” 错误（Azure）？

将 Azure 资源的内容过滤器从 DefaultV2 改为 Default。

Q9: 如何查看可用的 Provider？

/connect 

然后搜索或滚动查看所有可用的 Provider。

Q10: 如何使用代理？

设置环境变量：

exportHTTPS_PROXY=http://proxy.example.com:8080 exportHTTP_PROXY=http://proxy.example.com:8080 

📖 更多资源

• 官方文档: https://opencode.ai/docs
• GitHub 仓库: https://github.com/anomalyco/opencode

本教程由 Sisyphus AI 助手编写，人工审核，参考 OpenCode 官方文档。如有问题或建议，欢迎反馈！