OpenCode 完全指南：终端中的 AI 编程助手，让开发效率提升 10 倍
OpenCode 是一款运行在终端的开源 AI 编程助手，能够精准理解项目结构、灵活修改代码、执行命令操作，支持 75+ 模型切换，对中文友好。本文将带你从零开始，全面掌握 OpenCode 的安装、配置、使用和高级技巧。
一、OpenCode 简介
1.1 什么是 OpenCode？
OpenCode 是一款运行在终端的开源 AI 编程助手，它不是另一个 ChatGPT 网页版，而是真正集成到开发工作流中的 AI 助手。
1.2 核心特性
- 终端原生集成：无需离开命令行，直接在终端中使用
- 多模型支持：支持 75+ AI 模型，包括 GLM-4.7、GPT-5 等
- Skills 系统：可扩展的插件系统，增强 AI 能力
- 项目级配置：支持全局和项目级规则配置
- 免费开源：隐私优先，完全开源
1.3 适用场景
- 快速理解项目结构
- 自动生成代码
- 代码审查和重构
- 文档编写
- 调试和问题排查
二、安装与配置
2.1 安装 OpenCode
方法一：一键脚本安装（推荐）
curl -fsSL https://opencode.ai/install | bash
方法二：使用 npm 安装
npm install -g opencode
验证安装
opencode --version
输出示例：
1.1.35
2.2 查看可用模型
opencode models
输出示例：
opencode/big-pickle opencode/gpt-5-nano
2.3 配置全局规则
在项目根目录创建 AGENTS.md 文件，定义 AI 的行为规则：
# OpenCode 全局规则
## 语言规则
- 始终使用中文回复用户的所有问题
- 代码注释也使用中文编写
## 行为规则
- 在执行任何操作前，先向用户说明将要做什么
- 对于复杂的任务，先制定计划，再执行
## 代码风格
- 使用 2 空格缩进
- 函数名使用驼峰命名法
- 变量名使用下划线命名法
## 技能使用指南
- 处理文档时，优先使用相关 Skills
- 生成代码时，遵循项目现有的代码风格
## 安全规则
- 不要删除或修改重要的配置文件
- 在执行危险操作前，先询问用户确认
2.4 设置默认模型
方法一：使用环境变量（推荐）
# 设置默认模型
export OPENCODE_MODEL=opencode/gpt-5-nano
# 添加到配置文件
echo 'export OPENCODE_MODEL=opencode/gpt-5-nano' >> ~/.zshrc
source ~/.zshrc
方法二：使用命令行参数
# 指定模型启动 opencode -m opencode/gpt-5-nano run "你的问题"
2.5 配置主题
如果输入框文字看不清楚，可以调整终端和 OpenCode 主题：
# 设置 OpenCode 为浅色主题
export OPENCODE_THEME=light
echo 'export OPENCODE_THEME=light' >> ~/.zshrc
source ~/.zshrc
推荐配置：
- 终端：浅色主题（Solarized Light）
- OpenCode：浅色主题（light）
三、Skills 系统：扩展 AI 能力
3.1 什么是 Skills？
Skills 是 OpenCode 的插件系统，可以为 AI 添加特定领域的知识和能力。比如：
- PDF Skill：读取和处理 PDF 文件
- XLSX Skill：处理 Excel 文件
- Meeting Summary Skill：自动生成会议纪要
3.2 安装官方 Skills
# 克隆 Anthropic 官方 Skills 仓库
git -c http.version=HTTP/1.1 clone https://github.com/anthropics/skills.git
# 将 Skills 复制到 OpenCode 目录
cp -r skills/skills/* ~/.opencode/skills/
3.3 使用 Skills
# 使用 PDF Skill
opencode run "读取 document.pdf 的内容"
# 使用 XLSX Skill
opencode run "分析 data.xlsx 的数据"
# 使用自定义 Skill
opencode run "整理会议记录，生成会议纪要"
3.4 创建自定义 Skill
Skill 目录结构
meeting-summary/
├── SKILL.md # 必需：Skill 定义文件
├── scripts/ # 可选：脚本文件
└── resources/ # 可选：资源文件
SKILL.md 示例
---
name: meeting-summary
description: 整理会议记录，生成结构化的会议纪要
version: 1.0.0
author: Your Name
---
# Meeting Summary Skill
## 功能说明
本 Skill 用于整理会议记录，生成结构化的会议纪要，包括：
- 会议基本信息
- 参会人员
- 讨论要点
- 决策事项
- 待办事项
- 下次会议安排
## 使用方法
在 OpenCode 中输入：
整理会议记录，生成会议纪要
## 输出格式
生成的会议纪要将包含以下部分：
1. 会议标题
2. 会议时间
3. 参会人员
4. 讨论要点
5. 决策事项
6. 待办事项
7. 下次会议安排
四、核心使用技巧
4.1 斜杠命令（/commands）
在 OpenCode 中输入 / 可以触发命令：
基础命令
| 命令 | 说明 |
|---|---|
/models | 查看可用模型列表 |
/connect | 连接到模型提供商 |
/auth | 管理认证信息 |
/help | 显示帮助信息 |
/settings | 打开设置 |
/clear | 清除当前会话 |
/exit | 退出 OpenCode |
项目命令
| 命令 | 说明 |
|---|---|
/init | 初始化项目，创建 AGENTS.md |
/review | 审查代码变更 |
/test | 运行测试 |
/build | 构建项目 |
4.2 快捷键大全
基础操作
| 快捷键 | 说明 |
|---|---|
Ctrl + x | Leader 键（可自定义） |
Tab | 切换 Plan/Build 模式 |
Ctrl + c | 取消当前操作 |
Ctrl + d | 退出 OpenCode |
↑ / ↓ | 浏览历史消息 |
消息浏览
| 快捷键 | 说明 |
|---|---|
Ctrl + p | 上一条消息 |
Ctrl + n | 下一条消息 |
Ctrl + u | 清除当前输入 |
Ctrl + a | 移动到行首 |
Ctrl + e | 移动到行尾 |
4.3 文件引用（@ 符号）
使用 @ 可以快速引用项目文件，支持模糊搜索：
# 引用单个文件
@api.ts
# 引用多个文件
@api.ts @utils.ts @config.json
# 模糊搜索
@api # 会匹配所有包含 api 的文件
# 让 AI 解释文件作用
@api.ts 解释这个文件的作用
# 让 AI 修改文件
@utils.ts 添加一个错误处理函数
# 让 AI 比较文件
@file1.ts 和 @file2.ts 有什么区别
4.4 Shell 命令（! 前缀）
以 ! 开头可以直接执行 Shell 命令：
# 列出文件
!ls -la
# 查看 Git 状态
!git status
# 安装依赖
!npm install
# 运行测试
!npm test
# 一键获取项目代码
!find . -name "*.ts" -o -name "*.js" | head -n 100
# 查看目录结构
!tree -L 2
4.5 Plan 模式 vs Build 模式
Plan 模式（规划模式）
- 功能：只分析和规划，不修改文件
- 适用场景：理解项目、分析问题、制定计划
- 切换方法：按
Tab键切换到 Plan 模式
# Plan 模式示例
[Plan] 帮我分析这个项目的结构
[Plan] 这个 Bug 可能是什么原因？
[Plan] 如何实现这个功能？
Build 模式（执行模式）
- 功能：直接执行任务，会修改文件
- 适用场景：修复 Bug、添加功能、重构代码
- 切换方法：按
Tab键切换到 Build 模式
# Build 模式示例
[Build] 修复这个 Bug
[Build] 添加一个用户认证功能
[Build] 重构这个模块
推荐工作流
# 1. 先用 Plan 模式分析
[Plan] 帮我分析这个项目的结构
# 2. 确认无误后，切换到 Build 模式执行
[Tab]
# 切换到 Build 模式
[Build] 帮我添加一个用户认证功能
4.6 高级使用技巧
多文件操作
# 同时处理多个文件
@file1.ts @file2.ts @file3.ts 统一修改错误处理方式
# 批量重命名
@*.ts 将所有函数名改为驼峰命名法
上下文保持
# 保持上下文，多轮对话
[Plan] 分析这个项目的架构
[Build] 添加一个新的 API 接口
[Build] 为这个接口编写单元测试
命令组合
# 组合使用文件引用和 Shell 命令
@package.json 查看依赖，然后 !npm install 安装缺失的依赖
# 组合使用 Skills 和文件引用
@meeting.md 使用 meeting-summary Skill 生成会议纪要
五、常见问题与故障排除
5.1 JSON 解析错误
错误信息
Bad Request: Failed to parse request body as JSON: messages[23].content: unexpected end of hex escape
解决方法
方法 1：清理缓存
rm -rf ~/.local/share/opencode/storage
rm -rf ~/.local/state/opencode
方法 2：分段处理文件
# 只处理文件的一部分
opencode run "读取文件的前 100 行：@filename.md"
# 先询问文件结构
opencode run "列出 @filename.md 的主要章节"
方法 3：使用 Plan 模式先分析
# 先用 Plan 模式分析，不实际处理文件
[Plan] 帮我分析 @filename.md 的内容和结构
# 确认无误后再用 Build 模式
[Tab]
# 切换到 Build 模式
[Build] 处理 @filename.md
5.2 模型连接错误
错误信息
Error: Failed to connect to model
Error: API key invalid
解决方法
# 查看可用模型
opencode models
# 查看认证状态
opencode auth list
# 重新配置模型
opencode auth logout
opencode auth login <provider_url>
5.3 输入框文字看不清楚
问题原因
终端颜色设置不当，导致文字和背景颜色对比度不足。
解决方法
方法 1：调整终端颜色
macOS - Terminal
- 打开 Terminal 应用
- 点击菜单：终端 > 偏好设置
- 点击"描述文件"标签
- 调整以下设置：
- 文本颜色：设置为黑色（#000000）
- 背景颜色：设置为白色（#FFFFFF）
macOS - iTerm2（推荐）
- 打开 iTerm2
- 点击菜单：Preferences > Profiles > Colors
- 选择预设主题：Solarized Light
方法 2：设置 OpenCode 主题
export OPENCODE_THEME=light
echo 'export OPENCODE_THEME=light' >> ~/.zshrc
source ~/.zshrc
5.4 通用故障排除步骤
# 1. 查看详细日志
opencode --print-logs
# 2. 检查版本
opencode --version
# 3. 更新到最新版本
opencode upgrade
# 4. 测试基本功能
opencode run "hello"
六、实战案例
6.1 快速了解项目
# 启动 OpenCode
opencode
# 获取项目代码
!find . -name "*.ts" -o -name "*.js" | head -n 100
# 分析项目结构
[Plan] 帮我分析这个项目的结构
# 查看主要文件
@package.json @README.md 解释这个项目
6.2 修复 Bug
# 1. 先分析问题
[Plan] 分析这个 Bug 的可能原因
# 2. 查看相关代码
@buggy-file.ts 这段代码有什么问题？
# 3. 修复 Bug
[Build] 修复这个 Bug
# 4. 验证修复
!npm test
6.3 添加新功能
# 1. 先规划功能
[Plan] 如何实现用户认证功能？
# 2. 确认方案后实现
[Tab]
# 切换到 Build 模式
[Build] 添加用户认证功能
# 3. 编写测试
[Build] 为用户认证功能编写单元测试
# 4. 运行测试
!npm test
6.4 代码审查
# 1. 查看变更
!git diff
# 2. 审查代码
[Plan] 审查这些代码变更
# 3. 提出改进建议
@changed-files.ts 有什么可以改进的地方？
6.5 使用 Skills 处理文档
# 1. 读取 PDF 文件
opencode run "读取 document.pdf 的内容"
# 2. 生成会议纪要
opencode run "整理会议记录，生成会议纪要"
# 3. 处理 Excel 数据
opencode run "分析 data.xlsx 的数据"
七、总结
7.1 OpenCode 的优势
- 终端原生集成：无需离开命令行，工作流更顺畅
- 多模型支持：灵活切换不同 AI 模型，适应不同场景
- Skills 系统：可扩展性强，满足特定需求
- 项目级配置：支持全局和项目级规则，更贴合实际需求
- 免费开源：隐私优先，完全开源
7.2 最佳实践
- 设置默认模型：使用环境变量设置默认模型，提高效率
- 配置全局规则：在 AGENTS.md 中定义 AI 行为规则，保持一致性
- 善用 Skills：安装和使用相关 Skills，增强 AI 能力
- 合理使用模式：Plan 模式用于分析，Build 模式用于执行
- 保持上下文：多轮对话中保持上下文，提高理解准确性
7.3 学习路径
- 入门：安装 OpenCode，配置基本设置
- 进阶：学习使用 Skills，创建自定义 Skill
- 精通：掌握所有命令和快捷键，了解高级技巧
- 实战：在实际项目中使用，积累经验
7.4 参考资源
- OpenCode 官网：https://opencode.ai
- GitHub 仓库：https://github.com/anomalyco/opencode
- Anthropic Skills：https://github.com/anthropics/skills
- 官方文档：https://opencode.ai/docs
