OMO 上手指南:安装、配置、核心玩法一篇搞定

上一篇我讲了 OMO 是什么、为什么需要它。评论区有人问："道理我都懂，但具体怎么装？配置文件怎么写？装完之后怎么用？"

这些问题问得好。因为 OMO 的文档确实有点散——GitHub 上有安装指南，知乎上有保姆级教程，但没有一篇把"安装→配置→核心玩法"串起来讲清楚的。

所以我来写这一篇。

从安装到配置，从基础用法到进阶玩法，看完你就能上手。

一、安装：5 分钟搞定

1.1 前置条件

装 OMO 之前，确保你已经有：

• OpenCode CLI（npm install -g opencode-ai）
• Node.js 18+（运行 node -v 检查）
• 至少一个模型订阅（Claude / Gemini / OpenAI / Copilot，任选其一）

如果还没装 OpenCode，先看我之前写的入门指南。

1.2 安装 OMO

打开终端，运行：

npm install -g oh-my-openagent

或者用 bun：

bun add -g oh-my-openagent

安装完成后验证：

oh-my-openagent --version

看到版本号就说明装好了（当前最新版 v4.19.1，总下载量 340 万+）。

1.3 初始化配置

推荐让 AI 帮你初始化——因为 OMO 有 11 个代理，手动配容易出错。

在 OpenCode 里粘贴这段话：

Install and configure oh-my-openagent by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

AI 会自动帮你：
• 检测你有哪些模型订阅
• 为每个代理匹配最合适的模型
• 生成配置文件 ~/.config/opencode/oh-my-openagent.jsonc

完成后重启 OpenCode，OMO 就生效了。

二、配置文件详解

配置文件在 ~/.config/opencode/oh-my-openagent.jsonc，JSONC 格式（支持注释）。

2.1 基础结构

{
// 主代理（处理简单任务）
"main_model": "claude-sonnet-4-20250514",

// 重型代理（处理复杂任务）
"heavy_model": "claude-opus-4-20250514",

// 轻量代理（处理简单查询）
"small_model": "gemini-2.0-flash",

// 代理路由配置
"agents": {
"sisyphus": { "model": "claude-sonnet-4-20250514" },
"oracle": { "model": "claude-opus-4-20250514" },
"explore": { "model": "gemini-2.0-flash" },
"librarian": { "model": "gemini-2.0-flash" }
}
}

2.2 三类模型的角色

模型类型	用途	推荐配置
main_model	主协调、日常编码	Claude Sonnet / GPT-4.1
heavy_model	架构决策、深度分析	Claude Opus / Gemini Pro
small_model	快速查询、文档搜索	Gemini Flash / GPT-4.1 Mini

关键点：不是每个代理都要单独配模型。大多数情况下，配好这三个就够用了——OMO 会自动分配。

2.3 省钱配置

如果你只有免费额度或预算有限：

{
"main_model": "gemini-2.5-flash",
"heavy_model": "gemini-2.5-flash",
"small_model": "gemini-2.0-flash",
"agents": {
"oracle": { "model": "gemini-2.5-flash" }
}
}

这样所有代理都走 Gemini Flash，完全免费。

2.4 模型回退链（Model Fallback Chain）

OMO 支持三级回退：主模型 → 备用模型 → 免费模型。当主模型挂了或没额度时，自动切换到下一级。

{
"model_fallback": {
"primary": "claude-sonnet-4-20250514",
"secondary": "gemini-2.5-flash",
"tertiary": "big-pickle" // OpenCode 内置免费模型
}
}

这样即使 Claude 额度用完，OMO 会自动降级到 Gemini Flash，再不行就用免费模型。不会因为一个模型挂了就整个停摆。

2.5 混合配置（推荐）

如果你想让架构决策用最好的模型，日常编码用性价比高的：

{
"main_model": "claude-sonnet-4-20250514",
"heavy_model": "claude-opus-4-20250514",
"small_model": "gemini-2.0-flash"
}

Oracle 会自动用 heavy_model（Opus），日常任务用 main_model（Sonnet），查询用 small_model（Flash）。

三、核心玩法

安装配置搞定后，OMO 的真正价值在于工作流。

3.1 普通模式：Tab 切换代理

启动 OpenCode 后，按 Tab 键可以在不同代理之间切换。

每个代理有自己的专长：
• Sisyphus：默认入口，拆解任务、分配工作
• Hephaestus：写代码、实现功能
• Oracle：架构审查、提建议
• Librarian：查文档、找开源实现
• Explore：扫描代码库、理解结构

但你不需要手动切换——OMO 会根据任务自动选择。

3.2 关键词触发：搜索和分析

在 OpenCode 里输入包含特定关键词的消息，OMO 会自动切换模式：

关键词	模式	用途
`ultrawork` 或 `ulw`	超级工作	并行代理、后台任务、持续执行直到验证通过
`search`	搜索优先	先让 Explore/Librarian 搜资料，再动手
`analyze`	深度分析	路由到深度分析类别，扩展推理
`team`	团队模式	启用团队协作（需配置）

比如你说"ultrawork 帮我重构认证模块"，OMO 会自动启动多代理协作，持续工作直到任务完成。

3.3 Team Mode（v4.0+ 新增）

Team Mode 是 OMO 最新的多代理协作模式。启用后，Sisyphus 会自动分配任务给专业代理，每个代理在独立的 tmux 窗口里工作，互不干扰。

# 启用 Team Mode
# 在 OpenCode 里输入：
team 帮我实现用户认证系统

OMO 会自动：
1. Sisyphus 拆解任务
2. 分配给 Hephaestus（写代码）、Oracle（审查）、Librarian（查文档）
3. 每个代理并行工作
4. Sisyphus 汇总结果

注意：Team Mode 需要 tmux 支持。Windows 用户可以用 WSL 或 Git Bash。

3.4 Hashline 编辑（10x 编辑成功率）

OMO v4.0+ 引入了 Hashline 编辑技术，通过精确的行号定位和哈希校验，编辑成功率从 6.7% 提升到 68.3%（10 倍提升）。

这意味着什么？当你让 AI 修改代码时，它不会乱改一气，而是精确定位到要改的行，改完后还会校验确保没改错。

你不需要手动启用这个功能——OMO 默认开启。

3.5 斜杠命令：预设工作流

OMO 内置了几个斜杠命令，一键触发复杂工作流：

`/init-deep` — 生成项目知识库

第一次接手新项目时，让 AI 先理解代码结构：

/init-deep 帮我梳理这个项目的架构

OMO 会启动 Explore 代理扫描代码库，然后用 Oracle 分析架构，最后生成层级化的 AGENTS.md 文件。以后每个代理都能快速理解项目。

`/ralph-loop` — 持续工作循环

让 AI 持续工作直到完成，自动检测完成标记：

/ralph-loop "实现用户注册功能"

AI 会循环执行：写代码 → 跑测试 → 修 bug → 再跑测试，直到所有测试通过。

`/ulw-loop` — 超级工作循环

和 /ralph-loop 类似，但激活所有专业代理（并行执行）：

/ulw-loop "重构整个认证系统"

适合复杂任务，需要多个代理协作的场景。

`/start-work` — 执行计划

先用 Prometheus 制定计划，再用这个命令执行：

/start-work "auth-api-plan"

`/refactor` — 智能重构

用 LSP + AST-Grep + 测试验证的安全重构：

/refactor src/auth/ --scope=module

`/cancel-ralph` — 取消循环

任务方向错了？一键停止：

/cancel-ralph

3.4 工作流组合

实际使用中，这些命令可以组合：

/init-deep → /ulw-loop

先理解项目，再持续工作。

或者简单任务直接：

ultrawork 直接干

用关键词触发，不需要斜杠命令。

四、项目级配置：AGENTS.md

如果你想让 OMO 更好地理解你的项目，可以在项目根目录创建 AGENTS.md。

4.1 AGENTS.md 是什么

AGENTS.md 是项目级的上下文文件，告诉 AI：
• 这个项目是做什么的
• 技术栈是什么
• 有哪些约束和偏好
• 遇到问题时怎么处理

4.2 基础模板

# 项目名称

## 概述
这是一个 XXX 项目，用于 XXX。

## 技术栈
- 前端：React + TypeScript
- 后端：Node.js + Express
- 数据库：PostgreSQL

## 约束
- 遵循 ESLint 规则
- 测试覆盖率 > 80%
- 不使用 any 类型

## 偏好
- 优先使用函数式组件
- 状态管理用 Zustand
- API 设计遵循 RESTful 规范

4.3 进阶：写入代理指令

你还可以在 AGENTS.md 里写入具体的代理指令：

## 代理配置

### 代码审查
当审查代码时，重点关注：
1. 类型安全（不用 any）
2. 错误处理（不吞异常）
3. 性能问题（避免不必要的重渲染）

### 测试要求
- 每个新功能必须有单元测试
- 每个 bug 修复必须有回归测试
- 测试文件放在 __tests__/ 目录下

这样每次 AI 执行任务时，都会读取这些指令，行为更符合你的预期。

五、踩坑总结

坑 1：配置文件路径不对

OMO 的配置文件在 ~/.config/opencode/oh-my-openagent.jsonc，不是项目目录下的 .opencode/。

解决：确认路径正确，或者让 AI 帮你初始化。

坑 2：模型配错了导致代理不工作

如果你把 Oracle 配成了一个很弱的模型，它可能无法给出有用的建议。

解决：确保 heavy_model 是你最好的模型（Claude Opus / Gemini Pro）。

坑 3：项目太小用 OMO 反而慢

如果你的项目就一个文件，OMO 的多代理协作反而显得臃肿。

解决：小任务用单代理，复杂任务才用 OMO。

坑 4：AGENTS.md 写得太详细

有些人把 AGENTS.md 写了几千字，结果 AI 每次对话都要读一大堆，变慢了。

解决：AGENTS.md 控制在 500 字以内，只写核心约束和偏好。

坑 5：Team Mode 没装 tmux

Windows 用户直接用 team 命令会报错，因为 OMO 需要 tmux 来隔离代理。

解决：Windows 用户用 WSL 或 Git Bash，或者用普通模式（不启用 Team Mode）。

六、总结

阶段	工具	输出
理解项目	`/init-deep`	AGENTS.md 知识库
持续执行	`/ralph-loop` 或 `/ulw-loop`	自动循环直到完成
执行计划	`/start-work`	按 Prometheus 计划执行
安全重构	`/refactor`	LSP + 测试验证的重构
项目上下文	AGENTS.md	告诉 AI 你的项目规矩

OMO 的核心价值不是"让 AI 变快"，而是"让 AI 变聪明"。

安装只是开始，真正的价值在于用好这些工作流。

功能	命令/关键词	说明
超级工作	`ultrawork` / `ulw`	多代理并行，持续执行
团队模式	`team`	tmux 隔离，独立窗口
知识库	`/init-deep`	扫描项目，生成 AGENTS.md
持续循环	`/ralph-loop`	自动执行直到完成
超级循环	`/ulw-loop`	并行代理，更强力
取消循环	`/cancel-ralph`	停止当前循环
上下文交接	`/handoff`	会话断了自动续

工具只是工具，怎么用才是关键。

💬 你装好 OMO 了吗？用得最多的功能是什么？评论区聊聊。

如果觉得这篇文章有用，欢迎关注「AI 阿砚」，一个科研爱好者的 AI 探索笔记。