介绍 OpenCode，一款运行在终端的开源 AI 编程助手。支持 75+ 模型切换，具备 Skills 插件系统，可精准理解项目结构并执行代码修改。内容涵盖安装配置（脚本/NPM）、全局规则设置、核心使用技巧（斜杠命令、快捷键、文件引用、Plan/Build 模式）、常见问题排查及实战案例。旨在帮助用户在命令行环境中高效利用 AI 辅助开发。
OpenCode 是一款运行在终端的开源 AI 编程助手，能够精准理解项目结构、灵活修改代码、执行命令操作，支持 75+ 模型切换，对中文友好。本文将带你从零开始，全面掌握 OpenCode 的安装、配置、使用和高级技巧。
OpenCode 是一款运行在终端的开源 AI 编程助手，它不是另一个 ChatGPT 网页版，而是真正集成到开发工作流中的 AI 助手。
curl -fsSL https://opencode.ai/install | bash
npm install -g opencode
opencode --version
输出示例：
1.1.35
opencode models
输出示例：
opencode/big-pickle opencode/gpt-5-nano
在项目根目录创建 AGENTS.md 文件，定义 AI 的行为规则：
# OpenCode 全局规则
## 语言规则
- 始终使用中文回复用户的所有问题
- 代码注释也使用中文编写
## 行为规则
- 在执行任何操作前，先向用户说明将要做什么
- 对于复杂的任务，先制定计划，再执行
## 代码风格
- 使用 2 空格缩进
- 函数名使用驼峰命名法
- 变量名使用下划线命名法
## 技能使用指南
- 处理文档时，优先使用相关 Skills
- 生成代码时，遵循项目现有的代码风格
## 安全规则
- 不要删除或修改重要的配置文件
- 在执行危险操作前，先询问用户确认
# 设置默认模型
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 "你的问题"
如果输入框文字看不清楚，可以调整终端和 OpenCode 主题：
# 设置 OpenCode 为浅色主题
export OPENCODE_THEME=light
echo 'export OPENCODE_THEME=light' >> ~/.zshrc
source ~/.zshrc
推荐配置：
Skills 是 OpenCode 的插件系统，可以为 AI 添加特定领域的知识和能力。比如：
# 克隆 Anthropic 官方 Skills 仓库
git -c http.version=HTTP/1.1 clone https://github.com/anthropics/skills.git
# 将 Skills 复制到 OpenCode 目录
cp -r skills/skills/* ~/.opencode/skills/
# 使用 PDF Skill
opencode run "读取 document.pdf 的内容"
# 使用 XLSX Skill
opencode run "分析 data.xlsx 的数据"
# 使用自定义 Skill
opencode run "整理会议记录，生成会议纪要"
meeting-summary/
├── SKILL.md # 必需：Skill 定义文件
├── scripts/ # 可选：脚本文件
└── resources/ # 可选：资源文件
---
name: meeting-summary
description: 整理会议记录，生成结构化的会议纪要
version: 1.0.0
author: Your Name
---
# Meeting Summary Skill
## 功能说明
本 Skill 用于整理会议记录，生成结构化的会议纪要，包括：
- 会议基本信息
- 参会人员
- 讨论要点
- 决策事项
- 待办事项
- 下次会议安排
## 使用方法
在 OpenCode 中输入：
整理会议记录，生成会议纪要
## 输出格式
生成的会议纪要将包含以下部分：
1. 会议标题
2. 会议时间
3. 参会人员
4. 讨论要点
5. 决策事项
6. 待办事项
7. 下次会议安排
在 OpenCode 中输入 / 可以触发命令：
| 命令 | 说明 |
|---|---|
/models | 查看可用模型列表 |
/connect | 连接到模型提供商 |
/auth | 管理认证信息 |
/help | 显示帮助信息 |
/settings | 打开设置 |
/clear | 清除当前会话 |
/exit | 退出 OpenCode |
| 命令 | 说明 |
|---|---|
/init | 初始化项目，创建 AGENTS.md |
/review | 审查代码变更 |
/test | 运行测试 |
/build | 构建项目 |
| 快捷键 | 说明 |
|---|---|
Ctrl + x | Leader 键（可自定义） |
Tab | 切换 Plan/Build 模式 |
Ctrl + c | 取消当前操作 |
Ctrl + d | 退出 OpenCode |
↑ / ↓ | 浏览历史消息 |
| 快捷键 | 说明 |
|---|---|
Ctrl + p | 上一条消息 |
Ctrl + n | 下一条消息 |
Ctrl + u | 清除当前输入 |
Ctrl + a | 移动到行首 |
Ctrl + e | 移动到行尾 |
使用 @ 可以快速引用项目文件，支持模糊搜索：
# 引用单个文件
@api.ts
# 引用多个文件
@api.ts @utils.ts @config.json
# 模糊搜索
@api # 会匹配所有包含 api 的文件
# 让 AI 解释文件作用
@api.ts 解释这个文件的作用
# 让 AI 修改文件
@utils.ts 添加一个错误处理函数
# 让 AI 比较文件
@file1.ts 和 @file2.ts 有什么区别
以 ! 开头可以直接执行 Shell 命令：
# 列出文件
!ls -la
# 查看 Git 状态
!git status
# 安装依赖
!npm install
# 运行测试
!npm test
# 一键获取项目代码
!find . -name "*.ts" -o -name "*.js" | head -n 100
# 查看目录结构
!tree -L 2
Tab 键切换到 Plan 模式# Plan 模式示例
[Plan] 帮我分析这个项目的结构
[Plan] 这个 Bug 可能是什么原因？
[Plan] 如何实现这个功能？
Tab 键切换到 Build 模式# Build 模式示例
[Build] 修复这个 Bug
[Build] 添加一个用户认证功能
[Build] 重构这个模块
# 1. 先用 Plan 模式分析
[Plan] 帮我分析这个项目的结构
# 2. 确认无误后，切换到 Build 模式执行
[Tab]
# 切换到 Build 模式
[Build] 帮我添加一个用户认证功能
# 同时处理多个文件
@file1.ts @file2.ts @file3.ts 统一修改错误处理方式
# 批量重命名
@*.ts 将所有函数名改为驼峰命名法
# 保持上下文，多轮对话
[Plan] 分析这个项目的架构
[Build] 添加一个新的 API 接口
[Build] 为这个接口编写单元测试
# 组合使用文件引用和 Shell 命令
@package.json 查看依赖，然后 !npm install 安装缺失的依赖
# 组合使用 Skills 和文件引用
@meeting.md 使用 meeting-summary Skill 生成会议纪要
Bad Request: Failed to parse request body as JSON: messages[23].content: unexpected end of hex escape
rm -rf ~/.local/share/opencode/storage
rm -rf ~/.local/state/opencode
# 只处理文件的一部分
opencode run "读取文件的前 100 行：@filename.md"
# 先询问文件结构
opencode run "列出 @filename.md 的主要章节"
# 先用 Plan 模式分析，不实际处理文件
[Plan] 帮我分析 @filename.md 的内容和结构
# 确认无误后再用 Build 模式
[Tab]
# 切换到 Build 模式
[Build] 处理 @filename.md
Error: Failed to connect to model
Error: API key invalid
# 查看可用模型
opencode models
# 查看认证状态
opencode auth list
# 重新配置模型
opencode auth logout
opencode auth login <provider_url>
终端颜色设置不当，导致文字和背景颜色对比度不足。
macOS - Terminal
macOS - iTerm2（推荐）
export OPENCODE_THEME=light
echo 'export OPENCODE_THEME=light' >> ~/.zshrc
source ~/.zshrc
# 1. 查看详细日志
opencode --print-logs
# 2. 检查版本
opencode --version
# 3. 更新到最新版本
opencode upgrade
# 4. 测试基本功能
opencode run "hello"
# 启动 OpenCode
opencode
# 获取项目代码
!find . -name "*.ts" -o -name "*.js" | head -n 100
# 分析项目结构
[Plan] 帮我分析这个项目的结构
# 查看主要文件
@package.json @README.md 解释这个项目
# 1. 先分析问题
[Plan] 分析这个 Bug 的可能原因
# 2. 查看相关代码
@buggy-file.ts 这段代码有什么问题？
# 3. 修复 Bug
[Build] 修复这个 Bug
# 4. 验证修复
!npm test
# 1. 先规划功能
[Plan] 如何实现用户认证功能？
# 2. 确认方案后实现
[Tab]
# 切换到 Build 模式
[Build] 添加用户认证功能
# 3. 编写测试
[Build] 为用户认证功能编写单元测试
# 4. 运行测试
!npm test
# 1. 查看变更
!git diff
# 2. 审查代码
[Plan] 审查这些代码变更
# 3. 提出改进建议
@changed-files.ts 有什么可以改进的地方？
# 1. 读取 PDF 文件
opencode run "读取 document.pdf 的内容"
# 2. 生成会议纪要
opencode run "整理会议记录，生成会议纪要"
# 3. 处理 Excel 数据
opencode run "分析 data.xlsx 的数据"
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online