什么是 OpenCode?
注： 本篇来自claude总结、介意请忽略！
OpenCode 是一个开源 AI 编码助手,专为终端环境设计。它不仅仅是一个聊天机器人,而是一个可以执行命令、搜索代码、调试错误和修改文件的智能编程伙伴。
核心特性
- 🖥️ 原生终端界面 (TUI) : 响应式、可主题化的终端用户界面
- 🔌 LSP 集成: 自动加载正确的语言服务器协议支持
- 🤖 多模型支持: 支持 75+ LLM 提供商(Claude、GPT、Gemini、本地模型等)
- 🔀 多会话管理: 可同时在同一项目上运行多个 Agent
- 🔗 会话分享: 可分享会话链接用于参考或调试
- 🔒 隐私优先: 不存储任何代码或上下文数据
- 📱 多平台: 终端、桌面应用、IDE 扩展
快速开始
1. 安装 OpenCode
推荐方式 - 安装脚本:
curl -fsSL https://opencode.ai/install | bash
其他安装方式:
# 使用 npm
npm install -g opencode
# 使用 Homebrew (推荐使用 tap 获取最新版本)
brew tap opencode-ai/opencode
brew install opencode
# 或使用官方 formula (更新较慢)
brew install opencode
# 使用 Bun (Windows 支持进行中)
bun install -g opencode
# 使用 Arch Linux 的 paru
paru -S opencode
2. 配置 AI 模型
OpenCode 需要配置 LLM 提供商才能使用。对于新手,推荐使用 OpenCode Zen。
方式 A: 使用 OpenCode Zen (推荐)
Zen 是 OpenCode 团队精选并测试过的模型列表,专为编码 Agent 优化。
# 运行连接命令
opencode auth login
# 选择 opencode
# 访问 opencode.ai/auth
# 登录并添加账单信息
# 复制 API 密钥并粘贴
方式 B: 使用其他 LLM 提供商
OpenCode 支持多种提供商,包括:
- Anthropic (Claude)
- OpenAI (GPT)
- Google (Gemini)
- AWS Bedrock
- Groq
- Azure OpenAI
- 本地模型 (通过 Models.dev)
配置方法:
opencode auth login
# 选择你的提供商
# 输入 API 密钥
3. 初始化项目
# 进入你的项目目录
cd /path/to/your/project
# 启动 OpenCode
opencode
# 初始化项目 (推荐)
/init
初始化会:
- 分析项目结构
- 在项目根目录创建
AGENTS.md文件 - 帮助 OpenCode 理解项目结构和编码模式
重要: 将 AGENTS.md 提交到 Git 仓库中。
核心功能详解
Agent 系统
OpenCode 有两种类型的 Agent:
1. 主 Agent (Primary Agents)
可以用 Tab 键在它们之间切换:
-
build (默认)
- 完整权限的开发工作 Agent
- 可以编辑文件、运行命令
- 适合日常开发
-
plan (规划模式)
- 只读分析 Agent
- 默认拒绝文件编辑
- 运行 bash 命令前会请求权限
- 适合探索陌生代码库或规划变更
2. 子 Agent (Subagents)
专门化的辅助 Agent,可以被主 Agent 调用:
- @general: 用于复杂搜索和多步骤任务
- @search: 快速探索代码库,查找文件和关键词
调用方式:
@general 帮我找出所有使用了 Redis 的地方
@search 查找所有 API 端点定义
交互模式
1. 交互式模式 (默认)
# 启动交互式 TUI
opencode
# 在 TUI 中你可以:
# - 输入自然语言指令
# - 使用 Tab 切换 Agent
# - 使用 @ 搜索文件
# - 查看和批准建议的更改
2. 单次命令模式
适合脚本和自动化:
# 基本用法
opencode -p "解释 Go 中的 context 用法"
# JSON 格式输出
opencode -p "分析这个函数" -f json
# 静默模式 (无 spinner)
opencode -p "运行测试" -q
在此模式下:
- 所有权限自动批准
- 处理完成后自动退出
- 支持多种输出格式
工具和能力
OpenCode 可以使用的工具包括:
-
文件操作
- 读取、编辑、创建文件
- 搜索文件内容
- 查看目录结构
-
命令执行
- 运行 bash 命令
- 执行测试
- 运行构建脚本
-
代码智能
- LSP 支持(代码补全、跳转定义等)
- 代码分析和重构建议
- 错误诊断
-
Web 获取
- 查询文档
- 获取外部信息
实用技巧和最佳实践
1. 文件引用快捷方式
# 在消息中引用文件
@filename.py
# 引用特定行
@filename.py#L37-42
# 在 IDE 中使用快捷键
# Mac: Cmd+Option+K
# Windows/Linux: Alt+Ctrl+K
2. 自定义命令
创建可重用的命令提示:
# 创建命令文件
~/.config/opencode/commands/your-command.md
命令文件示例:
---
description: 代码审查命令
---
你处于代码审查模式。专注于:
- 代码质量和可读性
- 潜在的 bug
- 性能优化机会
- 安全问题
提供建设性反馈,但不直接修改代码。
使用命令参数:
# 获取 Issue $ISSUE_NUMBER 的上下文
RUN gh issue view $ISSUE_NUMBER --json title,body,comments
RUN git grep --author="$AUTHOR_NAME" -n .
3. 自定义 Agent
创建专门的 Agent:
# 创建 Agent 配置
~/.config/opencode/agents/review.md
Agent 配置示例:
---
description: "代码审查专家"
model: "opencode/claude-sonnet-4"
temperature: 0.2
max_iterations: 5
tools:
edit: false
bash: ask
permissions:
edit: deny
bash: ask
---
你是一个经验丰富的代码审查专家...
4. Agent Skills
创建可重用的指令集:
# 项目级别
.opencode/skill/release/SKILL.md
# 全局级别
~/.config/opencode/skill/release/SKILL.md
Skills 文件示例:
---
name: release
description: 准备版本发布
---
准备标记发布时使用此技能。
如果目标版本方案不清楚,请提问。
步骤:
1. 检查当前版本
2. 更新版本号
3. 更新 CHANGELOG
4. 创建 git tag
5. IDE 集成
VS Code / Cursor / Windsurf 扩展
安装后可使用:
快捷键:
Cmd+Esc(Mac) /Ctrl+Esc(Windows/Linux): 在分屏终端中打开 OpenCodeCmd+Shift+Esc(Mac) /Ctrl+Shift+Esc(Windows/Linux): 启动新会话Cmd+Option+K(Mac) /Alt+Ctrl+K(Linux/Windows): 插入文件引用
功能:
- 自动共享当前选择或标签页
- 上下文感知
- 点击 UI 中的 OpenCode 按钮
6. GitHub 集成
在 GitHub 工作流中使用 OpenCode:
# 设置 GitHub 集成
opencode github setup
使用场景:
-
问题分类
/opencode 解释这个 issue -
修复和实现
/oc 修复 #123 中描述的 bugOpenCode 会:
- 创建新分支
- 实现更改
- 提交 PR
-
PR 审查
/opencode 重构这个函数以提高可读性
配置优化
基础配置
配置文件位置: ~/.config/opencode/config.yaml
# 模型配置
model: opencode/claude-sonnet-4
# 温度设置 (0-1)
temperature: 0
# 最大迭代次数
max_iterations: 10
# 工具权限
tools:
edit: true
bash: ask
webfetch: true
# 权限设置
permissions:
edit: ask
bash: ask
webfetch: allow
主题定制
# 查看可用主题
opencode themes list
# 设置主题
opencode themes set <theme-name>
键位绑定
自定义快捷键以适应你的工作流程。
实战场景
场景 1: 探索陌生代码库
# 1. 启动 OpenCode
opencode
# 2. 切换到 plan 模式
# 按 Tab 键切换到 plan agent
# 3. 提问
"解释这个项目的整体架构"
"这个代码库使用了哪些主要的设计模式?"
# 4. 搜索特定功能
"@找到所有的 API 路由定义"
场景 2: 实现新功能
# 使用 build agent (默认)
# 1. 描述需求
"我需要添加一个用户认证中间件,要求:
- 验证 JWT token
- 支持角色权限
- 记录审计日志"
# 2. 让 OpenCode 规划
"先给我一个实现计划,不要修改代码"
# 3. 批准后实现
"好的,开始实现"
# 4. 审查更改
OpenCode 会显示将要做的更改,逐个确认或批准全部
场景 3: 调试问题
# 1. 描述问题
"运行测试时出现了 panic,帮我找出原因"
# 2. 让 OpenCode 调查
# OpenCode 会:
# - 查看测试输出
# - 分析相关代码
# - 定位问题根源
# 3. 修复
"请修复这个问题"
# 4. 验证
"运行测试确认修复"
场景 4: 代码审查
# 切换到 plan 模式
# 按 Tab 键
# 执行审查
"审查 src/handlers/user.go 中的代码,关注:
- 安全性
- 性能
- 错误处理
- 代码风格"
场景 5: 重构代码
"重构 processData 函数,使其:
- 更易读
- 减少圈复杂度
- 提高可测试性
- 保持相同的功能"
常见问题解决
问题 1: LSP 无法工作
# 检查 LSP 服务器安装
which pylsp
which typescript-language-server
# 测试 LSP 连接
opencode --test-lsp
# 重新安装语言服务器
pip install --upgrade python-lsp-server
npm install -g typescript-language-server
问题 2: API 配额限制
解决方案:
- 使用 OpenCode Zen 设置月度消费限制
- 切换到成本更低的模型
- 使用本地模型
问题 3: 响应太慢
优化建议:
- 使用更快的模型(如 GPT-4 Turbo)
- 减少上下文窗口大小
- 限制文件扫描范围
- 使用 plan agent 进行只读操作
进阶技巧
1. 多会话工作流
# 终端 1: 功能开发
opencode
# 终端 2: 测试和调试
opencode
# 终端 3: 文档更新
opencode
每个会话独立运行,可以并行工作。
2. 会话分享和协作
# OpenCode 会为每个会话生成一个链接
# 你可以分享这个链接给团队成员
# 用于代码审查、问题讨论或调试
3. 与 CI/CD 集成
# 在 CI 脚本中使用
opencode -p "运行所有测试并生成覆盖率报告" -q -f json
4. 性能监控
# 启用详细日志
opencode --verbose
# 查看会话历史
opencode sessions list
# 重放会话
opencode sessions replay <session-id>
最佳实践总结
✅ DO
- 明确的指令: 提供清晰、具体的需求和约束
- 渐进式工作: 从规划开始,然后逐步实现
- 审查更改: 始终审查 OpenCode 建议的更改
- 提交 AGENTS.md: 帮助 OpenCode 理解项目上下文
- 使用合适的 Agent: build 用于开发,plan 用于探索
- 善用子 Agent: 利用 @general 和 @search 提高效率
- 创建自定义命令: 为重复任务创建可重用命令
- 设置权限: 根据任务类型配置合适的工具权限
❌ DON'T
- 盲目批准: 不要不审查就批准所有更改
- 模糊指令: 避免含糊不清的请求
- 过度依赖: 保持对代码的理解和控制
- 忽略安全: 谨慎处理敏感信息和凭证
- 跳过初始化: 不初始化项目会影响 OpenCode 的理解
- 混用模式: 不要在需要精确控制时使用 -q 模式
学习资源
- 官方文档: opencode.ai/docs
- GitHub 仓库: github.com/anomalyco/o…
- Discord 社区: opencode.ai/discord
- 示例项目: 查看 GitHub 上的 opencode-examples
总结
OpenCode 是一个强大的 AI 编码助手,它能显著提升开发效率。关键是:
- 理解 Agent 系统: 知道何时使用 build 和 plan
- 掌握交互方式: 熟练使用快捷键和命令
- 优化配置: 根据需求定制 Agent 和工具权限
- 循序渐进: 从简单任务开始,逐步探索高级功能
