OpenCode：终端 AI 编程助手使用指南

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 中输入 / 可以触发命令：

基础命令

项目命令

4.2 快捷键大全

基础操作

消息浏览

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

1. 打开 Terminal 应用
2. 点击菜单：终端 > 偏好设置
3. 点击"描述文件"标签
4. 调整以下设置：
   • 文本颜色：设置为黑色（#000000）
   • 背景颜色：设置为白色（#FFFFFF）

macOS - iTerm2（推荐）

1. 打开 iTerm2
2. 点击菜单：Preferences > Profiles > Colors
3. 选择预设主题：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 的优势

1. 终端原生集成：无需离开命令行，工作流更顺畅
2. 多模型支持：灵活切换不同 AI 模型，适应不同场景
3. Skills 系统：可扩展性强，满足特定需求
4. 项目级配置：支持全局和项目级规则，更贴合实际需求
5. 免费开源：隐私优先，完全开源

7.2 最佳实践

1. 设置默认模型：使用环境变量设置默认模型，提高效率
2. 配置全局规则：在 AGENTS.md 中定义 AI 行为规则，保持一致性
3. 善用 Skills：安装和使用相关 Skills，增强 AI 能力
4. 合理使用模式：Plan 模式用于分析，Build 模式用于执行
5. 保持上下文：多轮对话中保持上下文，提高理解准确性

7.3 学习路径

1. 入门：安装 OpenCode，配置基本设置
2. 进阶：学习使用 Skills，创建自定义 Skill
3. 精通：掌握所有命令和快捷键，了解高级技巧
4. 实战：在实际项目中使用，积累经验

7.4 参考资源

• OpenCode 官网：https://opencode.ai
• GitHub 仓库：https://github.com/anomalyco/opencode
• Anthropic Skills：https://github.com/anthropics/skills
• 官方文档：https://opencode.ai/docs