OpenCode + oh-my-opencode 最佳实践指南
面向有 AI 编程助手使用经验的开发者，聚焦实战，基于官方最新文档（2026-04）整理。
一、OpenCode 是什么
OpenCode 是运行在终端里的开源 AI 编程 Agent，支持 Claude、GPT、Gemini 等 75+ 模型，提供 TUI / IDE 插件 / 桌面应用三种形态。
与 Claude Code 最大区别：不锁定模型，完全开源，Agent 体系可深度扩展。
二、安装与配置
# 方式一：官方安装脚本（推荐）
curl -fsSL <https://opencode.ai/install> | bash
# 方式二：Homebrew（最新版本）
brew install anomalyco/tap/opencode
# 方式三：Node.js
npm install -g opencode-ai配置 API Key：
export ANTHROPIC_API_KEY="sk-ant-..."
# 或在 TUI 里运行 /connect，按提示授权三、OpenCode 核心概念：Agent 体系
这是理解 OpenCode 的关键，与 Claude Code 的单一 Agent 模式不同。
3.1 两类 Agent
OpenCode 的 Agent 分两种：
Primary Agent（主 Agent）：你直接对话的对象，用 Tab 键在它们之间切换。
Subagent（子 Agent）：主 Agent 自动调度，或你手动 @mention 调用的专用助手。
安装 oh-my-opencode 后，主 Agent 和子 Agent 均大幅扩展，见第五节。
3.2 @ 的两种用法
@ 是 TUI 里最重要的输入符号，有两种完全不同的用途：
① 引用文件（模糊搜索）
这段鉴权逻辑有没有问题？@src/middleware/auth.ts触发模糊文件搜索，选中后文件内容自动注入上下文。
② @mention 子 Agent（直接调用）
@explore 找出所有调用了 sendEmail 的地方
@general 帮我并行处理这三个模块的文档生成主 Agent 也可以在执行过程中自动 @mention 子 Agent 完成专项任务。
两者可以在同一条消息里混用：
@explore 分析 @src/api/ 目录下所有接口的结构3.3 Tab 键：切换主 Agent
Tab 键在所有主 Agent（Primary Agent） 之间轮换，Shift+Tab 反向切换。
Tab # 切换主 Agent（Build → Plan → 自定义 Agent → ...）
Shift+Tab # 反向切换⚠️ 常见误解：Tab 不是”切换 Plan/Build 模式”，而是切换两个独立的主 Agent。
Plan Agent 的本质是”文件写入和 bash 命令默认要求人工确认”的受限 Agent。
典型用法：
# 先切到 Plan Agent 规划，只提方案不改代码
Tab → 描述需求，拿到方案后审查
# 方案确认后切回 Build Agent 执行
Tab → 好，按计划执行。3.4 快捷键速查
Leader 键默认是
Ctrl+X，可在tui.json中修改。
四、TUI 常用操作
4.1 初始化项目
cd /path/to/project
opencodeTUI 内运行：
/init分析项目结构，在根目录生成 AGENTS.md——务必提交到 Git，这是 Agent 的项目记忆。
4.2 执行 Shell 命令
消息以 ! 开头，直接运行 shell 命令，输出作为工具结果注入上下文：
!git log --oneline -20
!npm test -- --coverage
!cat package.json4.3 撤销 / 重做
/undo # 撤销最近一次修改（含文件变更），可多次执行
/redo # 重新应用已撤销的修改依赖 Git 管理文件变更，项目必须是 Git 仓库。
4.4 上下文管理
/compact # 压缩当前会话，保留关键上下文，释放 token（alias: /summarize）
/new # 开启新会话（alias: /clear）
/sessions # 查看并切换历史会话（alias: /resume）4.5 其他常用命令
/share # 生成会话分享链接（复制到剪贴板）
/unshare # 取消分享
/export # 导出会话为 Markdown，用外部编辑器打开
/thinking # 切换是否显示 Extended Thinking 内容
/models # 列出可用模型
/themes # 切换主题五、AGENTS.md 与自定义扩展
5.1 三个生效位置
OpenCode 还兼容 Claude Code 的 CLAUDE.md 格式（迁移时开箱即用）。
5.2 AGENTS.md 写什么
# 项目名称
## 技术栈
- 后端：Java 21 + Spring Boot 3.x
- 数据库：PostgreSQL（ORM 用 jOOQ，禁止使用 Hibernate）
- API 风格：RESTful，响应统一用 Result<T> 包装
## 构建与测试
- 构建：`mvn clean package`
- 单元测试：`mvn test`
- 集成测试：`mvn verify -P integration`
## 代码规范
- 所有 public 方法必须有 Javadoc
- 禁止在循环内执行数据库查询
- 异常统一通过 GlobalExceptionHandler 处理
## 架构说明
- 请求链路：Controller → Service → Repository → DB
- 跨模块只能通过 service 层调用，不能跨层调用 repository5.3 自定义 Agent
在 .opencode/agents/ 或 ~/.config/opencode/agents/ 创建 .md 文件：
---
description: 安全审计，检查代码安全漏洞
mode: subagent
model: anthropic/claude-opus-4-6
temperature: 0.1
tools:
write: false
edit: false
bash: false
---
你是一名安全专家，专注以下方面的代码审计：
- SQL 注入、XSS、CSRF 漏洞
- 不安全的反序列化
- 硬编码的密钥或密码
- 权限校验缺失
只提供分析报告，不直接修改代码。文件名即为 Agent 名（如 security-auditor.md → @security-auditor），mode: subagent 表示可被 @mention 调用。
5.4 自定义命令
在 .opencode/commands/ 或 ~/.config/opencode/commands/ 创建命令文件：
---
description: Code Review，重点关注安全和性能
agent: build
---
请对以下代码进行 Code Review，重点关注：
1. 安全漏洞（注入、权限、加密）
2. 性能问题（N+1 查询、内存泄漏）
3. 边界条件和异常处理
4. 命名和可读性
文件：$ARGUMENTS使用：/code-review src/api/OrderController.java
命令支持 $ARGUMENTS（所有参数）或 $1、$2（位置参数），frontmatter 中可指定 agent、model。
六、oh-my-opencode：把 OpenCode 变成开发团队
oh-my-opencode（现更名为 oh-my-openagent，npm 包名仍为 oh-my-opencode）是目前最强的 OpenCode 插件。
核心能力：11 个专业 Agent + 并行子 Agent + ulw 一键全自动 + LSP/AST-Grep 工具 + 自动上下文管理。
6.1 安装
bunx oh-my-opencode install验证安装：
cat ~/.config/opencode/opencode.json
# plugins 数组中应包含 "oh-my-opencode"6.2 ulw：最重要的一个词
ulw（ultrawork 的缩写）是 oh-my-opencode 的核心关键词。
提示词里只要包含 ulw 或 ultrawork，插件自动触发”最强模式”：
-
• 自主探索代码库，研究实现模式 -
• 调度多个专业 Agent 并行工作 -
• 持续执行直到完成，中途不停下来等确认 -
• 自动诊断验证结果
用法极简：
ulw 给 /api/orders 接口增加分页功能，参考 /api/products 的实现方式ulw 找出所有 N+1 查询问题并修复ulw 将整个项目的错误处理统一改为 Result 模式ulw 重构 src/payment/ 为策略模式，现有支付方式三种，对外接口不变原则：遇到大型任务、不知从哪下手时，直接
ulw，让系统自己决策。
关键词触发的其他模式：
6.3 11 个专业 Agent
安装后，Tab 键在这些主 Agent 间切换（按优先级）：
主 Agent（Tab 切换）：
子 Agent（@mention 调用）：
大多数场景不需要手动选 Agent，ulw 会自动调度。
6.4 /start-work：大型功能开发工作流
适用于跨模块、有架构决策的大型功能。流程如下：
第一步：Tab 切换到 Prometheus，描述需求
Prometheus 像真实工程师一样反问细节。回答完后：
好，生成计划。计划文件保存在 .sisyphus/plans/*.md，可以预览和修改。
第二步：确认计划后运行
/start-workAtlas 接管，按计划自动执行，中途断开也能自动恢复（状态存在 boulder.json）。
⚠️ Prometheus 和 Atlas 必须配对使用，勿直接切换到 Atlas 执行。
何时用 ulw，何时用 /start-work？
七、典型场景实战
场景一：快速理解陌生代码库
@explore 找出所有 API 入口点，列出路由和对应的 Handlerulw 分析这个项目的整体架构，重点是请求的完整链路，
输出一份给新人的 onboarding 文档场景二：新功能开发
小功能（1-2 个文件）：直接 Build Agent
在 @src/user/UserService.java 增加手机号登录方法，
参考邮箱登录 @src/user/EmailLoginStrategy.java中等功能（多文件联动）：Plan → Build
Tab（切换到 Plan Agent）
给删除订单功能加软删除：deleted_at 标记删除时间，
新增回收站页面支持恢复和彻底删除
（审查方案）
Tab（切回 Build Agent）
好，按计划执行。大型功能（跨模块）：ulw 或 /start-work
ulw 实现完整的优惠券系统：
固定金额/百分比两种折扣，限制使用次数和有效期，与购物车集成场景三：代码审查（不修改代码）
@explore 全量扫描 src/api/ 目录，找出所有没有做权限校验的接口@oracle 对 @src/payment/PaymentService.java 做架构审查，
重点：并发安全、幂等性、异常边界场景四：调试复杂 Bug
ulw 追踪这个 NPE 的根本原因，从堆栈顶部到数据来源全链路分析，
找到根因后给出修复方案。堆栈：
java.lang.NullPointerException
at com.example.OrderService.process(OrderService.java:142)
...场景五：大范围重构
ulw 将 src/payment/ 模块重构为策略模式，
现有支付方式：支付宝、微信、信用卡，
要求：对外接口不变，所有现有测试继续通过场景六：UI 还原（设计稿）
拖拽截图到终端后：
@multimodal-looker 分析这张设计稿的布局和样式
按照图中的设计实现 @src/components/Dashboard.tsx场景七：生成文档
ulw 为 src/api/ 下所有公开接口生成 OpenAPI 3.0 规范，
输出到 docs/openapi.yaml，参考 @docs/openapi-sample.yaml 的格式八、配置速查
8.1 opencode.json
{
"$schema": "<https://opencode.ai/config.json>",
"model": "anthropic/claude-opus-4-6",
"autoshare": false,
"plugins": ["oh-my-opencode"]
}8.2 oh-my-opencode Agent 配置
~/.config/opencode/oh-my-opencode.json：
{
"agents": {
"sisyphus": {
"model": "anthropic/claude-opus-4-6"
},
"oracle": {
"thinking": {
"type": "enabled",
"budgetTokens": 200000
}
},
"explore": {
"textVerbosity": "low"
}
}
}8.3 内置 Skills（oh-my-opencode）
自定义 Skill 路径：
.opencode/skills/my-skill/SKILL.md
~/.config/opencode/skills/my-skill/SKILL.md九、常见问题
Q：@ 引用文件和 @mention Agent 如何区分？
两者共用 @ 符号，区分逻辑：输入 @ 后如果匹配的是文件路径则注入文件内容；如果输入的是已注册的 Agent 名（如 @explore），则触发子 Agent 调用。
Q：Tab 切换 Agent 和 Ctrl+T 切换模型变体有什么区别？
Tab 切换主 Agent（角色切换，连带切换该 Agent 的专属模型和工具权限）；Ctrl+T 切换当前 Agent 的模型变体（如同一模型的标准版 vs Extended Thinking 版）。
Q：ulw 和直接描述需求有什么区别？
直接描述时，Sisyphus 单线程执行，遇到不确定的地方可能停下来问。加 ulw 后触发全自动并行模式：多个子 Agent 同时工作，自主探索代码库，不中途等确认，完成后持续验证直到彻底完成。
Q：/start-work 中断了怎么办？
重新运行 /start-work，系统从 boulder.json 恢复进度，继续未完成的任务。
Q：上下文快满了怎么办？
运行 /compact 压缩当前会话，关键上下文会被保留。大型任务优先使用 /start-work 工作流，子 Agent 分散上下文压力。
参考资料
-
• OpenCode 官方文档 -
• OpenCode Agents 文档 -
• OpenCode Keybinds 文档 -
• oh-my-opencode GitHub -
• awesome-opencode 插件合集
本篇文章来源于微信公众号: 玄熵智能
