大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



 
  
    
    

      本教程基于 OpenCode 官方文档（https://opencode.ai/docs）和 GitHub 仓库（https://github.com/anomalyco/opencode）编写，适合零基础新手入门。 
    
 
  
    
    
 
     
 
      
什么是 OpenCode
 
      
安装指南
 
      
快速开始
 
      
配置文件详解
 
      
Provider 配置
 
      
TUI 终端界面使用
 
      
Agent 系统
 
      
自定义命令
 
      
快捷键配置
 
      
MCP 服务器
 
      
LSP 语言服务器
 
      
主题与个性化
 
      
Rules 自定义指令
 
      
**实践与进阶技巧
 
      
常见问题解答
 
     
 
     
 
      
1.1 概述
 
      
OpenCode 是一个 100% 开源的 AI 编程代理（Coding Agent），提供终端界面（TUI）、桌面应用和 IDE 扩展多种使用方式。它可以帮助开发者：
 
      
 
       
🤖 与 AI 对话编写代码
 
       
📝 分析和理解代码库
 
       
🔧 自动修改和重构代码
 
       
🐛 调试和修复问题
 
       
📚 生成文档和测试
 
      
 
      
1.2 核心特点
 
     
    

1.3 与 Claude Code 的区别

---

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

3.5 撤销与重做

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

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

---

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.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

}}}}}}

5.9 禁用/启用特定 Provider

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

---

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.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 权限配置

}}}}

---

8.1 创建命令

JSON 配置方式

{"$schema":"https://opencode.ai/config.json","command":{"test":{"template":"运行完整的测试套件并显示覆盖率报告。 关注失败的测试并提供修复建议。","description":"运行测试并分析结果","agent":"build","model":"anthropic/claude-haiku-4-5"},"component":{"template":"创建一个名为 $ARGUMENTS 的 React 组件。 包含 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.1 Leader 键

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

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

9.2 自定义快捷键

}

9.3 禁用快捷键

设置为 “none” 禁用：

{“keybinds”:{“session_compact”:“none”}}

9.4 完整快捷键列表

---

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.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.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.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.1 高效工作流

1. 先规划后执行

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

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 

---

Q1: 如何更换模型？

/models 

或在配置文件中设置：

{“model”:“openai/gpt-4o”}

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

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

{“actions”:[{“command”:{“action”:“sendInput”,“input”:“”},“id”:“User.sendInput.ShiftEnterCustom”}],“keybindings”:[]}

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}

或只通知不更新：

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 官方文档。如有问题或建议，欢迎反馈！