Opencode 使用指南
约 2011 字大约 7 分钟
opencodeaiclicoding-agent
2026-02-26
Opencode 是一款基于 AI 的命令行编程助手,能够理解自然语言指令并执行代码任务。
什么是 Opencode
Opencode 是一个智能编程代理(Agentic Coding Assistant),它不仅仅是代码补全工具,而是能够:
- 理解复杂任务并自主拆解执行
- 读取、编辑、创建项目文件
- 执行 Shell 命令
- 与 Git 集成
- 调用预定义技能(Skills)完成标准化任务
与其他 AI 编程助手的区别
| 工具 | 定位 | 交互方式 | 执行能力 |
|---|---|---|---|
| GitHub Copilot | 代码补全 | IDE 插件 | 建议代码 |
| Cursor | 对话式编程 | IDE 集成 | 编辑文件 |
| Opencode | 编程代理 | CLI + Skills | 完整任务执行 |
安装与配置
环境要求
- Node.js 18.x 或更高版本
- npm 或 yarn 包管理器
- macOS / Linux / Windows
安装步骤
1. 安装 Node.js
# macOS (使用 Homebrew)
brew install node@20
# Linux (使用 nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
# 验证安装
node --version
npm --version2. 安装 Opencode
# 使用 npm 全局安装
npm install -g opencode
# 或使用 yarn
yarn global add opencode3. 验证安装
opencode --version配置 API Key
Opencode 需要配置 LLM API 才能工作:
# 创建配置目录
mkdir -p ~/.opencode
# 创建配置文件
cat > ~/.opencode/config.json << EOF
{
"apiProvider": "openai",
"apiKey": "your-api-key-here",
"model": "gpt-4",
"baseUrl": "https://api.openai.com/v1"
}
EOF或使用环境变量:
export OPENCODE_API_KEY="your-api-key-here"
export OPENCODE_MODEL="gpt-4"
export OPENCODE_BASE_URL="https://api.openai.com/v1"支持的模型提供商
| 提供商 | 环境变量 | 推荐模型 |
|---|---|---|
| OpenAI | OPENAI_API_KEY | gpt-4, gpt-4-turbo |
| Anthropic | ANTHROPIC_API_KEY | claude-3-opus |
| Azure OpenAI | AZURE_API_KEY | gpt-4 |
| 自定义 | OPENCODE_BASE_URL | 任意兼容模型 |
核心功能
文件操作
Opencode 可以读取、写入、编辑项目中的任何文件:
# 读取文件
opencode "读取 src/main.ts 的内容"
# 创建新文件
opencode "在 components 目录下创建一个 Button 组件"
# 修改现有文件
opencode "给 UserService 添加一个 deleteUser 方法"代码搜索与理解
# 搜索特定模式的代码
opencode "找到所有使用 fetch 的地方"
# 理解代码结构
opencode "解释这个项目的架构"
# 查找 Bug
opencode "分析这个函数的潜在问题"任务执行
# 运行命令
opencode "运行测试并确保所有测试通过"
# 构建项目
opencode "执行构建并输出产物"
# Git 操作
opencode "查看最近的提交历史"技能系统(Skills)
Skills 是 Opencode 的核心功能,它将复杂任务标准化、模块化:
# 列出可用技能
opencode skills list
# 安装新技能
opencode skills install <skill-name>
# 使用技能
opencode "使用 frontend-design 技能创建一个 landing page"使用技巧
有效提示词编写
❌ 不好的提示词
帮我写点代码✅ 好的提示词
创建一个 React 函数组件,接收 name 和 age 两个 props,
使用 TypeScript 定义类型,包含基本样式,
文件保存到 src/components/UserInfo.tsx任务拆解方法
复杂任务应该拆分为小步骤:
# 第一步:分析需求
opencode "分析这个需求需要修改哪些文件"
# 第二步:执行修改
opencode "按照分析结果修改代码"
# 第三步:验证
opencode "运行测试验证修改是否正确"上下文管理
Opencode 会记住对话历史,但需要注意:
- 长对话会消耗更多 tokens
- 关键信息应该明确说明
- 可以引用具体文件路径
# 引用文件
opencode "参考 @src/utils/helpers.ts 的风格,创建一个新的工具函数"文件引用方式
# 引用单个文件
opencode "查看 @package.json 的依赖"
# 引用多个文件
opencode "对比 @file1.ts 和 @file2.ts 的差异"
# 引用目录
opencode "分析 @src/components/ 目录结构"实战案例
案例 1:创建新功能
需求:添加用户登录功能
# 1. 创建登录组件
opencode "创建 LoginForm 组件,包含用户名、密码输入框和登录按钮,使用 TypeScript,保存到 src/components/LoginForm.tsx"
# 2. 创建服务
opencode "创建 AuthService,包含 login、logout、getToken 方法,使用 fetch 调用 API,保存到 src/services/auth.ts"
# 3. 更新路由
opencode "在路由配置中添加登录页面路由 /login"
# 4. 添加类型定义
opencode "在 src/types/auth.ts 中添加 User 和 LoginRequest 类型定义"案例 2:Bug 修复流程
# 1. 描述问题
opencode "用户反馈点击登录按钮没有反应,帮我排查问题"
# 2. 分析日志
opencode "查看控制台日志,定位错误发生位置"
# 3. 修复代码
opencode "修复这个空指针异常,添加null检查"
# 4. 验证修复
opencode "运行相关测试用例验证修复"案例 3:代码重构
# 1. 分析代码质量
opencode "分析 src/utils/ 目录的代码,找出可以优化的地方"
# 2. 提取公共函数
opencode "将这些重复的逻辑提取为公共工具函数"
# 3. 更新调用
opencode "更新所有引用这些逻辑的文件"
# 4. 删除冗余代码
opencode "删除被替换的旧代码"案例 4:文档生成
# 生成 API 文档
opencode "根据 src/api/ 目录的代码生成 API 文档,输出为 Markdown 格式"
# 生成 README
opencode "分析项目结构,生成一个完整的 README.md"
# 生成变更日志
opencode "根据 git 提交历史生成 CHANGELOG.md"最佳实践
AGENTS.md 配置
在项目根目录创建 AGENTS.md 文件,定义项目规范和偏好:
# AGENTS.md - 开发指南
## 项目结构
- src/components/ - React 组件
- src/services/ - API 服务
- src/types/ - TypeScript 类型定义
## 代码规范
- 使用 TypeScript 严格模式
- 组件使用函数式写法
- 使用 ES Modules 导入导出
## 测试规范
- 测试文件放在 __tests__ 目录
- 使用 Jest 作为测试框架
- 测试覆盖率要求 80% 以上
## 提交规范
- feat: 新功能
- fix: Bug 修复
- docs: 文档更新
- refactor: 代码重构项目规范设定
- 明确技术栈:在 AGENTS.md 中说明使用的框架、库
- 定义目录结构:让 AI 了解文件组织方式
- 代码风格:命名约定、格式化规则
- 安全注意:哪些文件不应提交、密钥管理
安全注意事项
⚠️ 重要:
- 永远不要在代码中硬编码 API Key 或密码
- 不要让 AI 修改
.env、credentials.json等敏感文件 - 谨慎执行 rm、rm -rf 等危险命令
- 检查 AI 生成的代码再提交
# ❌ 错误做法
opencode "把数据库密码写到配置文件"
# ✅ 正确做法
opencode "使用环境变量读取数据库配置"性能优化建议
- 批量操作:一次性描述完整需求,减少来回对话
- 明确范围:指定要修改的文件或目录
- 增量验证:复杂任务分步骤验证
- 清理上下文:定期开始新对话避免上下文过长
常见问题
Q1: 安装后提示找不到命令
解决方案:
# 检查 npm 全局目录是否在 PATH 中
npm config get prefix
# 将全局目录添加到 PATH
export PATH=$(npm config get prefix)/bin:$PATHQ2: API Key 配置后仍然报错
排查步骤:
# 1. 验证环境变量是否设置
echo $OPENCODE_API_KEY
# 2. 检查配置文件格式
cat ~/.opencode/config.json
# 3. 测试 API 连接
curl -H "Authorization: Bearer $OPENCODE_API_KEY" \
https://api.openai.com/v1/modelsQ3: 执行速度慢怎么办
优化方法:
- 使用更快的模型(如 GPT-4 Turbo)
- 减少不必要的上下文
- 网络问题考虑使用国内镜像
Q4: 如何自定义 Skills
创建自定义 Skill:
- 创建技能目录:
mkdir -p ~/.opencode/skills/my-skill- 定义技能描述(skill.json):
{
"name": "my-skill",
"description": "我的自定义技能",
"version": "1.0.0"
}- 编写执行逻辑(index.md):
# My Skill
## 执行步骤
1. 第一步...
2. 第二步...Q5: Git 操作失败
常见原因:
- Git 未安装或未配置
- 没有提交权限
- 工作区有未提交的更改
解决方案:
# 检查 Git 状态
git status
# 配置 Git 用户信息
git config --global user.name "Your Name"
git config --global user.email "your@email.com"资源链接
持续更新:Opencode 仍在快速发展中,本文档会持续更新最新用法。

