oh-my-openagent 完全指南

OpenCode 最佳 Agent 编排框架，让单个 AI 变成真正的开发团队

第一章：引言 — 打破 AI 编码的单打独斗

1.1 从孤军奋战到团队协作

你有没有过这种感觉：用 AI 写代码的时候，它像一个特别勤快的实习生——你说什么它就做什么，但你不说的事它绝不会主动想。有时候问它"这段逻辑能不能优化"，它能给你洋洋洒洒分析一大篇；有时候你丢给它一个复杂的重构任务，它吭哧吭哧改了一堆文件，结果跑不起来，还得你一点点去核对哪里出了问题。

这不是 AI 的问题，是协作模式的问题。传统的 AI 编程工具本质上是"指令—执行"的单循环：你给一条指令，AI 执行，返回结果，再给下一条指令。这个模式在处理简单、边界清晰的任务时效率很高，但一旦任务规模变大、涉及多个模块、需要跨领域的判断，这种来回往复的方式就开始显现出瓶颈。你得像项目经理一样自己拆解任务、跟踪进度、发现错误、判断质量——AI 成了你的执行器，而你却成了 AI 的项目经理。

oh-my-openagent 想做的事很简单：把 AI 从执行器变成团队成员。它不是简单地在 Prompt 里加一句"你是一个资深工程师"，而是真正引入了一套多角色的协作架构。框架里有负责规划的、有负责执行的、有负责审查的、有负责架构把关的。它们各司其职，互相配合，而你只需要描述目标，理解这背后的复杂度由框架来处理。

1.2 oh-my-openagent 是什么

oh-my-openagent 是 OpenCode 的 Agent 编排框架。OpenCode 本身是一个 AI 编程环境，提供了和代码库交互的基础能力；而 oh-my-openagent 则是在这层基础上构建的多模型、多角色协作层。

你可以把它类比为一套开发团队的运作机制。一个真实团队里有架构师、有开发者、有测试工程师、有代码审查者，每个人都有自己的职责边界和协作流程。oh-my-openagent 把这个角色体系映射到了 AI 模型上，不同的 Agent 承担不同的角色，通过结构化的消息传递来协调工作。

这个框架有几个核心设计原则。第一是不绑定模型。Claude、GPT、Gemini，国产的 Kimi、GLM 等都可以接入，框架会自动根据任务类型选择最合适的模型。不会出现"你用这个工具就必须用我们的模型"这种绑定关系。第二是模型路由自动化。框架内置了意图分类机制，能根据你输入的内容判断应该用哪个模型、走哪种工作流程，不需要你手动指定。第三是并行执行能力。多个 Agent 可以同时工作，分别处理不同的子任务，最后汇总结果。这种并行能力在处理大型项目时效果尤为明显。

1.3 它解决什么问题

最直接的回答是：减少你在 AI 协作中的认知负担。

举一个具体的场景。你接手了一个陌生的代码库，要对它做一次模块化改造。这个任务涉及多个方面：理解现有架构、规划拆分方案、处理依赖关系、确保改造后接口兼容、补充测试用例。传统的做法是反复和 AI 对话，每个方面逐一探索，遇到错误再回头调整。一趟下来可能需要几十轮对话，你自己要记住整个过程中说过的约束、排除过的方案、做过的修改。这对你的记忆力和管理能力要求很高，而且很容易在长对话中遗漏之前提到的某个关键限制。

在 oh-my-openagent 中，这个任务会被分解给不同的 Agent 处理。Prometheus Agent 负责在动手之前把需求问清楚、规划好分几步走；Atlas Agent 负责把任务分配给具体的执行者；Hephaestus Agent 负责深度执行每个子任务；最后还有个审查环节确保质量。整个过程有记录、有结构、有检查点，你不需要在脑子里同时维护所有上下文。

另一个常见的痛点是 AI 的输出不稳定。同一段 Prompt 跑两遍可能得到两个略有不同的结果，代码风格不一致、接口命名不规范、遗漏了某些边界情况。框架通过 Skill 系统和配置体系把团队规范固化成 Agent 的默认行为，确保每次交互都在统一的框架内运行，而不是依赖 Prompt 的随机发挥。

1.4 核心理念：不绑定模型

很多 AI 编程工具在模型选择上做绑定——要么只能用 Claude，要么只能用 GPT。这对厂商来说是好生意，但对用户来说限制了灵活性。不同模型在不同任务上各有优势：Claude 系列在代码理解和架构分析上通常更稳，GPT 在某些特定场景（比如深度代码生成）上表现突出，国产模型在中文上下文和本地化场景上有天然优势。

oh-my-openagent 的模型路由机制解决了这个问题。框架内置了一套优先级策略，Native 模型优先，然后是 Kimi、Copilot、Venice、OpenCode Zen、Z.ai 等。这个优先级不是固定不变的，你可以根据自己手头的订阅情况调整配置。

更重要的是，框架支持按任务类型指定模型。你可以配置"代码审查用 Sonnet，重构规划用 Opus，翻译任务用 GPT-4o"。这种细粒度的控制让你把好钢用在刀刃上——用更强的模型处理复杂任务，用更快的模型处理简单任务，节省成本的同时保证质量。

1.5 ultrawork 命令：一句话启动全流程

框架的核心入口是 ultrawork 命令，简写为 ulw。这个命令的设计哲学是：你描述目标，框架搞定剩下的。

# 基本用法
ultrawork 帮我把这个 monolith 应用拆成微服务

# 简写
ulw 添加 JWT 认证模块

# 更具体一些
ulw 在 orders 表里加一个 soft_delete 字段，并更新所有引用这个表的地方

你不需要指定用哪个模型、调用哪些 Agent、按照什么顺序执行。框架会自动分析你的需求，路由到合适的模型，启动必要的 Agent 协作流程。你只需要确认最终结果是否符合预期。

这个命令适合的场景是你已经想清楚要做什么。如果你的描述足够清晰，ultrawork 可以说是目前最省力的 AI 编程方式——比对着文档配置各种参数然后自己编排要快得多。

1.6 适合人群

oh-my-openagent 不是给所有人的。如果你只是偶尔需要 AI 帮你写个小脚本、补个函数注释，现有的 Copilot 或 Claude Code 完全够用，装 oh-my-openagent 属于杀鸡用牛刀。

但如果你符合以下某个场景，这套框架就值得认真研究。

第一，你正在维护一个中大型代码库，经常需要做跨模块的改造或者重构。单 Agent 工具在这种规模的任务上容易迷失方向，你需要多角色协作来保持对全局的掌控。

第二，你的团队有统一的开发规范，希望 AI 自动遵守这些规范，而不是每次都要在 Prompt 里重复提醒。通过项目级配置把规范固化下来，新成员加入后 clone 配置就能用，省心很多。

第三，你想提高 AI 编程的效率上限。现有的 AI 工具让你和单个 Agent 配合，已经比不用工具强很多；但当你需要处理真正复杂的任务时，你会发现瓶颈不在 AI 的能力，而在协作模式上。oh-my-openagent 就是来解决这个瓶颈的。

第四，你对多模型协作感兴趣，想体验不同模型在不同任务上的差异化表现，同时又不想自己维护多套配置。这套框架的模型路由机制让你在不动脑子的情况下用上最合适的模型。

第二章：核心概念 — Agent 编排体系

2.1 为什么需要多 Agent 架构

在进入具体的 Agent 介绍之前，先聊一下为什么需要多 Agent 这个设计。

单 Agent 模式下，AI 要同时扮演需求理解者、方案规划者、代码实现者、质量审查者等多个角色。这有点像让一个人同时做产品经理、开发工程师和测试工程师三份工作——他当然可以做到，但每个角色的思维模式切换本身就是消耗，而且当某个角色的专业度不够时，整个输出质量都会受影响。

多 Agent 架构的核心思想是把角色分离。让擅长战略思考的 Agent 负责规划，让擅长深度执行的 Agent 负责实现，让擅长代码理解的 Agent 负责审查。每个 Agent 在自己的领域内做到最专，而不是在所有领域都浅尝辄止。

更重要的是，不同的 Agent 可以并行工作。当你下达一个大的任务时，框架可以同时启动多个 Agent 分别处理不同的子任务，最后汇总结果。这不是简单的"让多个 AI 同时回答"，而是真正有角色分工、有信息传递、有结果整合的协作流程。

oh-my-openagent 目前内置了 11 个核心 Agent，下面逐一介绍它们各自的定位和能力边界。

2.2 Sisyphus — 主编排器

Sisyphus 是希腊神话里那个永无止境推石头上山的国王。框架用它来命名主编排器，是取其"不停歇、直到任务完成"的精神。

Sisyphus 是整个编排体系的中心枢纽。当你启动 ultrawork 或进入 Prometheus 规划流程时，Sisyphus 是第一个激活的 Agent。它的职责不是直接写代码，而是协调整个工作流程——决定接下来调用哪些 Agent、以什么顺序、传递什么上下文、什么时候进入下一阶段。

你可以把 Sisyphus 理解为整个虚拟团队的项目经理。它不写代码，但它知道代码应该怎么写；它不审查代码，但它知道审查标准是什么。它的工作质量决定了整个协作流程的效率。一个好的项目经理能让一团队人配合顺畅，一个差的项目经理会把所有人带进坑里。Sisyphus 的作用是一样的。

Sisyphus 基于 Claude 系列模型构建，这是因为 Claude 在复杂推理和多步骤规划上表现最为稳定。在实际使用中，你基本不需要和 Sisyphus 直接交互，它在幕后运行，你感知到的是最终汇总的结果。但如果你发现整个流程跑偏了（比如 Agent 做了很多不相关的操作），问题大概率出在 Sisyphus 的规划不够精确。

2.3 Hephaestus — 深度自主工作者

Hephaestus 是希腊神话中的火神和锻造者，巧匠的代名词。在框架中，它代表的是深度自主执行的能力。

Hephaestus 基于 GPT-5.3 Codex 模型，定位是"给目标不给步骤"。你告诉它要实现什么，它自己推导出实现路径，然后埋头干活，中途不需要你过多干预。这和 Sisyphus 的协调角色形成互补——Sisyphus 负责"做什么、按什么顺序做"，Hephaestus 负责"怎么做"。

使用 Hephaestus 的典型场景是你已经知道目标但不确定实现路径的任务。比如"我想在这个服务里加一个缓存层"，你描述了缓存层应该做什么，但具体怎么加、加在哪里、用什么缓存库、怎么处理缓存穿透——这些实现细节由 Hephaestus 来推导。它有足够的自主性，会在遇到关键决策点时停下来问你，但不会每一步都停下来确认。

有一点值得注意：Hephaestus 的自主性既是优势也是风险。自主性强意味着它行动快，但也意味着如果你给的目标不够精确，它可能推导出你并不期望的实现路径。所以使用 Hephaestus 时，建议先在 Prometheus 模式把目标澄清，再交给 Hephaestus 执行——规划阶段搞清楚做什么，执行阶段让 Hephaestus 全力冲。

2.4 Prometheus — 战略规划者

普罗米修斯为人类盗取火种，是主动出击、帮助人类理解未知事物的象征。这个 Agent 的核心能力正是在动手之前搞清楚要做什么。

Prometheus 是框架中最独特的存在，因为它的工作方式不是写代码，而是提问。当你进入 Prometheus 模式时，Agent 会切换到面试官姿态，主动向你抛出问题。这些问题围绕几个核心维度展开：需求的具体边界在哪里、有没有特殊情况需要处理、有哪些现有约束必须遵守、如何验证实现是否正确。

很多人在实际使用中发现这个模式"有点奇怪"——AI 居然不直接干活，而是在那问来问去。但当你真正用它规划过一个复杂任务之后，你会理解这种设计的价值。很多时候我们脑子里有一个模糊的想法，但从来没有把它清晰地表述出来。Prometheus 的提问过程实际上是在帮你把模糊的想法变成可以执行的具体方案，而这个过程本身就能发现很多之前没考虑到的问题。

Prometheus 模式的触发方式很有意思：不是敲一个命令，而是在对话中按 Tab 键。这种交互设计背后有一个心理暗示——按 Tab 是一个"暂停"，你要停下来重新审视你要做的事，而不是顺着当前的对话流继续往下走。

等你回答完 Prometheus 的问题，它会生成一个结构化的执行计划。你确认或修改之后，可以输入 /start-work 启动 Atlas 按计划执行。Prometheus 和 Atlas 的配合构成了框架中最有特色的工作流：先规划后执行，决策和执行分离。

2.5 Atlas — 任务执行者

Atlas 是希腊神话中撑起天空的泰坦。在框架中，它是负责分布式任务分发和结果汇总的执行者。

当 Prometheus 规划好执行计划后，Atlas 接手后续的工作。它把计划分解成具体的子任务，分配给相应的 Agent 执行，监控每个子任务的进度，处理任务间的依赖关系，最后把各路结果汇总成一个完整的输出。

Atlas 的核心价值在于规模化。在没有 Atlas 的情况下，你要手动管理多个 Agent 的调用顺序和数据传递，自己判断什么时候可以并行、什么时候必须串行，自己监控进度、自己处理异常。这在大任务上很快就会变成一场噩梦。Atlas 把这些协调工作接了过去，让你只需要关注最终结果的正确性。

Atlas 特别擅长处理可并行的子任务。比如你有一个大重构涉及五个模块，这五个模块之间没有依赖关系，Atlas 可以同时启动五个 Agent 分别处理，然后在所有 Agent 都完成后汇总结果。这种并行度在手动协调时几乎不可能实现，但 Atlas 可以轻松做到。

2.6 Oracle — 架构顾问

Oracle（神谕者）是古希腊传达神意的角色。在框架中，它是一个只读架构顾问，专门处理架构决策和复杂调试。

这个 Agent 的定位很有意思：它不是来写代码的，而是来回答问题的。当你面临架构层面的决策困惑时——比如"这个服务拆分是不是合理"、“为什么要用这种设计模式”、“这个性能瓶颈的根本原因是什么”——Oracle 登场。

Oracle 只读不写，这是有意为之的设计约束。给它提供代码上下文，它会分析、会推理、会给建议，但不会主动修改任何文件。这种约束保证了它的客观性——它不是在急着证明自己的方案，而是真正在帮你分析问题。如果你想让它提出的方案落地，需要你自己触发另一个 Agent 来执行。

典型的使用场景包括：接手遗留代码库时的架构评估、性能问题的根因分析、技术选型时的利弊权衡。Oracle 的输出通常是结构化的分析报告，包含现状描述、问题诊断、方案建议和风险提示。

2.7 其他 Agent 简介

除了上面五个核心 Agent，框架还内置了六个辅助 Agent，分别处理特定领域的任务。

Explore 是快速代码库搜索 Agent。当你需要了解某个模块的结构、找到某个函数的调用链、或者定位某个关键词出现的所有位置时，Explore 比自己用 grep 更快。它基于代码库的语义理解做搜索，而不是简单的文本匹配。

Librarian 专注于文档和代码搜索。和 Explore 的代码库内搜索不同，Librarian 可以搜索外部的文档资源，比如框架的官方文档、最佳实践文章、开源项目的 README 等。相当于在你的团队里放了一个随时待命的技术文档查找员。

Metis 是代码理解与逻辑分析 Agent。当你对某段代码的行为感到困惑、需要理解复杂的业务逻辑链、或者要追溯某个 bug 的根本原因时，Metis 能帮你深入分析代码的执行路径和依赖关系。它的强项是把看似复杂的代码拆解成清晰的结构。

Momus 是任务审查与质量把关 Agent。它不负责写代码，而是在其他 Agent 完成工作后进行检查——验证实现是否符合需求、是否有遗漏的边界情况、代码风格是否一致。相当于团队里的质检员角色。

Multimodal-Looker 处理视觉和截图分析。当你需要 AI 看一张 UI 截图来分析布局问题、或者从架构图里提取组件关系时，这个 Agent 就派上用场了。它不是写代码的 Agent，而是帮你把视觉信息转化成结构化理解的 Agent。

Sisyphus-Junior 是 Sisyphus 的轻量版本，适合处理简单任务或作为学习辅助。当你需要一个快速的协调者来处理简单串行任务，而不需要完整的 Atlas 编排开销时，Sisyphus-Junior 是一个更低成本的选择。

2.8 Agent 协作的底层逻辑

这么多 Agent 在一起工作，它们之间是怎么传递信息的？

核心机制是结构化上下文传递。当 Prometheus 完成了规划，它的输出不是一段自然语言描述，而是一个结构化的执行计划——包含任务分解、依赖关系、验收标准等信息。这些结构化数据直接传给 Atlas，Atlas 再分发给具体的执行 Agent。每个 Agent 收到的上下文都是经过整理的、高质量的、包含所有必要信息的。

这种机制解决了单 Agent 模式下最常见的一个问题：长对话中的上下文丢失。在传统模式里，你需要反复告诉 AI"我们之前约定了要用这个规范"、“这个问题之前讨论过，结论是……”。在多 Agent 协作中，规划阶段产生的所有结论都会以结构化形式保存，并在后续执行阶段被自动注入到对应的上下文中，不需要你手动重复。

第三章：安装配置 — 五分钟上手

3.1 前置要求

在安装 oh-my-openagent 之前，你需要确认系统已经安装了 OpenCode。OpenCode 是这套框架的底层环境，oh-my-openagent 是运行在它之上的编排层。

OpenCode 的安装方式取决于你的操作系统。具体步骤可以在 OpenCode 官方文档中查看，通常是通过 npm 或 pip 安装：

# npm 安装方式
npm install -g opencode

# 或者 pip 安装方式
pip install opencode

安装完成后，在终端中运行 opencode --version 确认安装成功。如果能看到版本号，说明环境已经准备好了，可以进入下一步。

另外需要注意的是，oh-my-openagent 的部分功能依赖 bun 运行时。框架推荐使用 bun 来执行安装脚本，这主要是出于安装速度的考虑。如果你的系统上没有 bun，需要先安装：

# macOS / Linux 安装 bun
curl -fsSL https://bun.sh/install | bash

# 安装完成后确认
bun --version

Windows 用户可以考虑使用 WSL（Windows Subsystem for Linux）来获得完整的 oh-my-openagent 体验，或者参考官方文档了解 Windows 原生支持的安装方式。

3.2 安装方式

OpenCode 就位后，安装 oh-my-openagent 本身非常直接。框架提供了 install 命令来一键安装：

bunx oh-my-opencode install

这条命令会做几件事：下载框架的核心代码、创建必要的配置文件目录、初始化默认的 Agent 配置文件。如果安装过程中没有报错，说明一切顺利。

安装完成后，你可以通过 opencode agents list 来验证 Agent 列表是否正确加载。如果能看到类似 “Sisyphus”、“Hephaestus”、“Prometheus” 这样的 Agent 名称，说明框架已经正确安装并识别了各个 Agent。

有一点需要提醒：bunx 是 bun 的包执行命令，类似于 npx。如果你没有 bun，也可以尝试用 npx oh-my-opencode install，但官方测试环境主要是 bun，一些边缘功能可能在 npx 下表现不一致。

如果你使用的是中国网络环境，安装过程中可能会遇到下载慢的问题。可以在安装前设置代理，或者使用国内镜像源。框架本身是开源的，如果下载确实有问题，可以考虑先 clone 源码再本地安装：

git clone https://github.com/code-yeongyu/oh-my-openagent.git
cd oh-my-openagent
bun install
bun run setup

3.3 订阅配置

框架本身免费，但使用 AI 模型需要对应的 API 订阅。oh-my-openagent 支持多个模型订阅渠道，你可以根据手头已有的订阅来配置，不需要额外付费购买框架本身。

支持的订阅渠道包括以下几种，按优先级排列：

Native 是指框架内置的默认订阅，通常开箱即用，不需要额外配置。如果你刚安装完就想试试，第一步可以先看框架默认支持哪些模型。

Kimi 是月之暗面的大模型服务，在中文理解和长上下文处理上表现不错。配置方式是在 OpenCode 的认证配置中添加 Kimi 的 API Key。配置路径通常是 ~/.config/opencode/auth.json，不同操作系统可能略有差异。

GitHub Copilot 如果你已经订阅了 Copilot，可以直接复用。框架会优先查找 Copilot 的认证信息，不需要重复配置。

Venice 是一个相对小众但性价比不错的模型服务，适合对成本敏感的场景。

OpenCode Zen 和 Z.ai 是 OpenCode 生态内的订阅选项，如果你已经在 OpenCode 平台上消费过，可以直接使用对应的认证。

配置模型订阅的核心是 API Key 的设置。具体操作是在 OpenCode 的认证配置中添加对应平台的 Key。配置格式通常是一个 JSON 文件，包含平台名称和 API Key：

{
  "providers": {
    "kimi": {
      "api_key": "your-kimi-api-key-here"
    },
    "openai": {
      "api_key": "your-openai-api-key-here"
    }
  }
}

3.4 认证步骤

配置好订阅之后，需要在 OpenCode 中完成认证登录，才能让框架正常使用这些模型。这个步骤通过 opencode auth login 命令完成：

opencode auth login

执行这条命令后，会启动一个交互式登录流程。不同订阅渠道的认证方式可能略有差异——有些需要输入 API Key，有些需要浏览器授权 OAuth。根据你配置的订阅类型，按提示完成操作即可。

如果你的认证信息已经以配置文件的方式提供（比如上面的 JSON 文件），opencode auth login 通常会自动检测到这些配置，不需要额外的手动输入。

有一点值得注意：认证信息是敏感数据。API Key 不要明文写在公共可见的配置文件中，最好放在用户目录的配置里而不是项目目录中，并确保这些文件不要提交到 Git 仓库。如果你不确定配置文件是否被正确忽略，可以检查 .gitignore 中是否包含相应的配置路径。

认证完成后，可以运行一个快速测试来验证认证是否生效：

opencode auth status

这条命令会显示当前认证的账户信息和可用额度。如果看到订阅状态正常，说明认证环节已经搞定，可以开始使用框架了。

3.5 配置验证

安装和认证都完成后，最后一步是验证整个环境是否正常工作。框架提供了一个验证命令，可以检查各个组件的连接状态：

opencode doctor

doctor 命令会依次检查 OpenCode 环境、oh-my-openagent 框架、各个订阅的可用性，最后给出一个汇总报告。如果所有检查项都是绿色的（passed），说明环境完全就绪。如果有失败项，根据报错信息定位问题——通常是认证 Key 填错、网络不通、或者某个订阅过期了。

另一个实用的验证方式是直接启动 ultrawork 模式：

opencode ultrawork hello world

如果框架正常启动并输出了结果，说明 Agent 编排链路是通的。这里用 “hello world” 这种简单任务是为了排除业务逻辑的干扰——如果连这个最简单的任务都跑不通，说明环境有基础性问题，需要先解决。

3.6 快速上手路线图

安装完成后的第一个小时，推荐按这个顺序来熟悉框架：

第一步，用 ultrawork 处理一个真实但简单的任务。比如"帮我在这个项目里加一个 .gitignore 文件"或者"给我解释一下 src/ 目录下每个文件的用途"。这一步的目的是让你感受框架的基本交互方式——你说什么，Agent 做什么。

第二步，切换到 Prometheus 模式规划一个小任务。按 Tab 进入规划模式，回答 Agent 提出的几个问题，观察它是如何把一个模糊的需求逐步澄清的。规划完成后，用 /start-work 启动执行，感受规划与执行分离带来的质量差异。

第三步，如果你的项目有一定规模（比如有多个模块），尝试触发 Atlas 的并行执行能力。看 Agent 如何同时处理多个子任务，最后汇总结果。这个体验最能体现多 Agent 架构和单 Agent 模式的本质区别。

完成这三步，你应该对框架的能力边界和交互风格有了基本认知。接下来的使用中遇到问题，可以回到这一章的配置部分来调整和优化。

第四章：模型体系 — 各有所长

4.1 为什么需要了解模型差异

很多人觉得："AI 就是 AI，调用一个就够了吧？"但实际上，不同模型在代码理解、推理能力、生成速度、成本控制等方面的差异比你想象的更大。用错了模型，轻则响应慢、费用高，重则代码质量不达标还得返工。

oh-my-openagent 的优势之一是把这些差异封装成了透明的路由机制——你不需要手动记住"这个任务用哪个模型"，框架会自动判断。但如果你想理解框架的行为逻辑、或者在某些场景下手动干预模型选择，就需要了解每个模型系列的特点。

本章按系列介绍框架支持的主要模型，说明它们各自的强项和使用场景。不涉及任何厂商宣传，所有判断基于实际使用经验。

4.2 Claude 系列 — 代码理解的强者

Claude 系列是 Anthropic 推出的模型，在代码相关任务上口碑一直不错。框架支持多个 Claude 版本，按能力从高到低排列：

Claude Opus 4.6 是整个系列中综合能力最强的模型。它在复杂推理、长上下文分析、架构设计判断上的表现最为稳定。当你需要一个 Agent 做高层次的规划、架构评审、或者处理特别复杂的跨文件重构时，Opus 是首选。但它的响应速度相对较慢，费用也是最高的，所以不适合处理简单任务。

Claude Sonnet 4.6 是性价比最优的选择。它在大多数代码任务上的表现和 Opus 差距不大，但响应速度明显更快、费用更低。对于日常的代码编写、bug 修复、功能实现这类任务，Sonnet 通常是最佳选择——不需要动用 Opus 的全部能力，用 Sonnet 绑绑有余。

Claude Haiku 4.6 是轻量级选手，速度最快、成本最低。它的推理能力相对弱一些，适合处理简单、明确、不需要深度思考的任务——比如代码格式化、注释生成、简单翻译等。把 Haiku 和 Opus 分工使用，是控制成本的有效策略。

在国产 Claude 系模型中，Kimi K2.5（anthropic/kimi-k2.5）和 GLM 5（zhipuai/glm-5）也值得一说。Kimi 系列在中文理解和长上下文处理上有独特优势，特别适合需要处理中文注释、中文文档的代码库。GLM 系列则是智谱的旗舰模型，在通用推理上表现稳定，而且国内访问延迟更低。

使用 Claude 系列时有一个经验：模型对 Prompt 格式的敏感度比 GPT 系列低。你不需要特别讲究 Prompt 的措辞和结构，Claude 通常能理解你的意图。但这也意味着它更容易"自己发挥"——如果你给的指示不够具体，它可能按自己理解的方式去做，而不是停下来问清楚。所以用 Claude 时，描述要尽量精确，而不是用大量修饰词来引导它。

4.3 GPT 系列 — 深度编码的首选

GPT 系列在代码生成领域有着深厚的积累。框架支持以下几个主要版本：

GPT-5.3-codex（openai/gpt-5.3-codex）是专为深度编码设计的模型。它在复杂代码生成、算法实现、长文件处理上表现突出，是 Hephaestus Agent 的底层模型。当你需要"给我实现这个功能，具体怎么做你自己推"的场景，GPT-5.3-codex 通常能给出一个完整、连贯、可直接运行的实现。

但需要注意 Codex 版本在自然语言理解上相对弱一些，有时候对模糊描述的理解不如 Claude 精确。这不是 bug，而是模型设计取向的差异——Codex 把更多参数用在了代码处理上，语言理解的份额就相对少了。所以如果你不确定要实现什么，先在 Prometheus 模式把需求澄清，再用 Codex 来执行，是更稳妥的组合。

GPT-5.4（openai/gpt-5.4）是通用性最强的版本，智能水平高，适用面广。它的代码能力虽然不如 Codex 专精，但在大多数场景下已经足够好了，而且自然语言理解更准确。如果你不想费心选择，用 GPT-5.4 通常不会出错。

GPT-5.4-mini（openai/gpt-5.4-mini）是轻量版本，速度快、成本低，适合处理批量化的简单任务。比如你需要 AI 帮你在 50 个文件里统一添加 copyright 头，这种机械性的任务用 mini 就够了，不需要动用 full 版本浪费预算。

选择 GPT 系列时有个坑需要避开：不要假设 GPT-5.4 比 GPT-4 更好。在某些特定任务上，经过长时间调优的 GPT-4 版本可能比初代 GPT-5.4 表现更稳定。新版本不一定在所有维度都全面超越旧版本，按任务实际测试才是靠谱的做法。

4.4 差异化模型 — 各有绝活

除了 Claude 和 GPT，框架还支持一些在特定领域有独特优势的模型：

Gemini 3.1 Pro（google/gemini-3.1-pro）是 Google 的模型，在视觉处理和前端开发任务上有明显优势。如果你的任务涉及 UI 截图分析、CSS 布局问题诊断、或者需要同时处理图片和代码的场景，Gemini 3.1 Pro 是值得尝试的选择。另外 Gemini 系列的多模态能力通常比同期其他模型更成熟。

MiniMax M2.5 的核心优势是速度。如果你在做需要快速反馈的场景——比如实时代码补全、IDE 内联建议——MiniMax 的低延迟能带来更好的交互体验。它在代码质量上可能不如 Claude 和 GPT，但在响应速度上绝对领先。

国产模型方面，Kimi K2.5（anthropic/kimi-k2.5）的长上下文窗口是一个亮点。如果你需要处理超长文件（几千行以上的单个文件）或者需要在分析时同时参考多个大文件，Kimi 的上下文窗口能减少分段处理带来的信息损失。GLM 5（zhipuai/glm-5）则胜在稳定性和通用性，适合作为日常主力模型。

4.5 为什么不同模型需要不同提示词

同一个任务，让 Claude 理解和让 GPT 理解，Prompt 的写法可能需要调整。这不是因为哪个模型更"聪明"，而是因为它们的训练方式和对齐策略不同。

Claude 系列更擅长从模糊描述中推断意图。你不需要把每一步都写得很清楚，Claude 能根据上下文补充缺失的信息。这种特性让 Claude 在复杂推理任务上表现好，但也意味着如果你的意图本身就有歧义，Claude 可能会按它自己推断的方向去做，结果未必是你想要的。

GPT 系列（尤其是 Codex）对输入格式更敏感。清晰的步骤分解、明确的边界说明、具体的约束条件——这些对 GPT 的输出质量影响更大。在 Codex 上，一个结构良好的 Prompt 可能比一个内容丰富但结构混乱的 Prompt 效果更好。

这种差异对使用的影响是：如果你的团队混用多个模型，不能简单地复制粘贴 Prompt，需要针对不同的模型做适配。但 oh-my-openagent 的模型路由机制在一定程度上缓解了这个问题——框架在调用不同模型时会自动注入相应的提示词模板，保证每次调用的 Prompt 都是针对目标模型优化过的。你不需要手工维护这些模板，框架已经帮你做了。

4.6 模型选择的实战建议

给一个实用的决策框架：

简单重复性任务：用 Haiku 或 MiniMax。代码格式化、注释批量生成、文件重命名这类操作不需要深度推理，速度优先。

日常开发任务：用 Sonnet（anthropic/claude-sonnet-4-6）或 GPT-5.4（openai/gpt-5.4）。功能实现、bug 修复、小规模重构，这类任务占据了你日常的大部分时间，选择性价比高的模型。

复杂架构任务：用 Opus（anthropic/claude-opus-4-6）或 GPT-5.3-codex（openai/gpt-5.3-codex）。跨模块重构、架构设计、技术方案评审，这些任务的质量影响深远，不要在模型上省钱。

中文场景：优先 Kimi K2.5（anthropic/kimi-k2.5）或 GLM 5（zhipuai/glm-5）。中文注释处理、中文文档理解、国产框架适配，本地模型的优势是客观存在的。

多模态任务：用 Gemini 3.1 Pro（google/gemini-3.1-pro）。UI 分析、截图解读、图片相关的代码任务，Gemini 的多模态能力更有保障。

框架的默认路由策略已经覆盖了这些场景的基本分配，但如果某个任务你觉得路由不够精确，可以通过配置手动覆盖具体 Agent 使用的模型型号。配置方法在第七章会详细介绍。

第五章：核心功能 — 让 Agent 真正能干活

5.1 三个痛点与三个解法

评价一个 AI 编程工具是否真的"能用"，不是看它能回答多少问题，而是看它能不能在真实项目中落地。很多人用 AI 写代码时遇到过这几个经典问题：

问题一，AI 改的代码跑不起来。原因是代码库在你发起对话之后又有了新的提交，AI 看到的文件和实际文件内容不一致，导致它基于旧上下文做的修改和当前代码对不上。业界把这个问题叫 stale-line（过期行）问题，非常普遍但一直没有很好的解法。

问题二，复杂任务需要来回沟通。你描述了一个需求，AI 给了一个方案，你发现方案有遗漏，再描述，再给……一个中型任务可能要几十轮对话才能完成，你花在"管理 AI"上的精力比自己写还多。

问题三，AI 输出质量不稳定。同一个任务跑两遍得到两个不同的结果，代码风格不一致，接口规范不统一，你想让 AI 遵守团队规范，但它每次都有自己的"想法"。

本章介绍的这些核心功能，就是针对这三个痛点给出的工程化解法。

5.2 Hashline 编辑器 — 解决 stale-line 的杀手锏

Hashline 是 oh-my-openagent 最具创新性的功能之一，专门解决 stale-line 问题。这个问题的本质是：AI 在生成修改时是基于某个特定时间点的代码上下文，但代码在这之后可能被其他人修改了，导致 AI 给出的修改指令指向的行号和当前文件内容对不上。

传统的解法是让 AI 在每次操作前重新读取文件。道理是对的，但实践中 AI 往往会"自作聪明"地省略这一步，或者在长对话中逐渐忘记要重新读取。

Hashline 的解法是用内容哈希而非行号来定位代码位置。框架在读取文件时给每一行计算一个哈希值，生成类似 LINE#abc123 的标识符。当 AI 给出修改指令时，指令里不是"第 37 行"，而是"包含 function auth() { 这一行的哈希是 abc123"。即使文件被修改过导致行号发生变化，只要那一行内容本身没变，哈希值就还在，AI 就能精确找到要修改的位置。

这个设计的效果是实实在在的。根据框架的测试数据，Grok Code Fast 1 的成功率从 6.7% 提升到了 68.3%。不要小看这个数字——在真实项目中，AI 修改代码后跑不起来是让人最沮丧的事，每提高一点成功率都直接反映在开发效率上。

Hashline 的另一个好处是对并发编辑更友好。如果两个人同时用 AI 修改同一个文件，传统模式下后提交的那个人的修改可能会覆盖前一个人的改动（因为它读取的是旧的行号信息）。Hashline 基于内容定位，即使后提交的人先完成，他的修改也不会覆盖未修改部分的内容——精确到了每一行的粒度。

在配置中，Hashline 功能默认是开启的。如果你想手动控制它的行为，可以通过 hashline 配置项来调整：

# 配置示例
hashline:
  # 是否启用内容哈希定位
  enabled: true
  # 哈希算法：md5 / sha256，默认 sha256
  algorithm: sha256
  # 哈希前缀长度，默认 8
  prefix_length: 8

5.3 并行 Agent 系统 — 规模化执行

在第二章介绍了 Atlas 这个任务编排 Agent，它的核心能力之一就是并行执行。但"并行执行"这四个字在不同工具有不同的实现深度，这里展开说一下 oh-my-openagent 的并行机制到底做了什么。

首先，并行不是"同时启动多个 Agent，然后把结果简单拼接"。真正的并行需要处理几个复杂的问题：子任务之间有没有依赖关系？依赖的话谁先谁后？谁的结果作为谁的输入？某个子任务失败了其他任务要不要继续？结果之间有没有冲突需要解决？

Atlas 的编排引擎处理了这些问题的全部。一个典型的并行执行场景是这样的：你要对一个包含用户认证、订单管理、支付处理三个模块的代码库做统一升级。Atlas 分析出这三个模块可以并行处理，因为它识别出它们之间的依赖都在各自内部，没有跨模块依赖。于是它同时启动三个 Hephaestus 实例分别处理三个模块的升级，每个实例独立执行、独立思考、独立报错。三个实例都完成后，Atlas 汇总结果，检查有没有冲突（比如两个模块都对同一个配置文件做了修改），如果有冲突则触发冲突解决流程，最终输出一个整合好的完整结果。

这种并行度在手动协调时几乎不可能实现。即使你用上了 Copilot 的多个会话，你也需要自己管理每个会话的上下文、自己判断依赖关系、自己处理结果冲突。Atlas 把这些管理工作接了过去，你只需要看最终结果。

并行 Agent 的一个实际注意事项是资源消耗。同时运行 5 个以上的 Agent 实例对内存和 API 调用量都有要求。框架默认设置了合理的并发上限，但如果你在资源紧张的环境下（比如内存较小的开发机）使用，可以适当降低 defaultConcurrency 配置。配置方法在第七章有详细说明。

5.4 内置 MCP 集成 — 扩展 Agent 的能力边界

MCP（Model Context Protocol）是 Anthropic 推出的模型上下文协议，用来扩展 AI 模型获取外部信息的能力。oh-my-openagent 内置了三个实用的 MCP 服务，让框架的 Agent 在执行任务时能访问更丰富的信息源。

Exa MCP 是一个联网搜索服务。当 Agent 需要查证某些技术细节、了解某个框架的最新版本、或者搜索 Stack Overflow 上的类似问题时，Exa MCP 可以让 Agent 直接发起搜索而不是依赖训练数据的截止日期。这解决了 AI 编程工具普遍存在的一个问题：模型的知识有截止日期，用它来处理最新的技术栈时要打折扣。

Context7 MCP 是专门针对框架文档的检索服务。框架作者通常会用 Context7 来索引自己框架的文档，当 Agent 在使用某个框架时遇到不确定的 API 用法，它可以直接通过 Context7 查询官方文档的准确描述，而不是靠记忆中的模糊印象。这个功能对不熟悉的框架尤其有用——你不需要自己去找文档，Agent 会帮你查。

Grep.app MCP 是 GitHub 代码搜索服务。有时候你想知道"某个功能在开源社区通常是怎么实现的"或者"某个 API 的最佳实践是什么"，Grep.app 可以搜索 GitHub 上真实项目中的代码示例。Agent 调用这个服务时，等于有了一个实时的大型代码参考库。

这三个 MCP 服务是框架内置的，不需要额外安装。Agent 在需要时会自动调用它们。你也可以在配置中添加自己的 MCP 服务，把团队内部的 Wiki、知识库或者其他工具接入进来——这部分在第七章的配置章节有详细说明。

5.5 生产力工具 — 让工作流更顺畅

除了核心的 Agent 编排能力，框架还内置了几个实用的生产力工具，它们不是 Agent，但能在特定场景下显著提升效率。

Ralph Loop 是一个自我迭代工具。传统的 AI 编程流程是"生成—审查—修改"的手动循环，你发现输出有问题，要自己描述哪里不对、让 AI 修改。Ralph Loop 加入了自动化层：Agent 生成结果后，会自动进行一轮自我审查，识别明显的问题（如逻辑错误、边界条件遗漏、风格不一致），然后自动尝试修复。这个循环可以重复多次，直到 Agent 认为当前结果已经足够好。效果是把"审查—修改"的手动循环变成了自动化的闭环。

Todo Enforcer 是一个待办事项强制执行工具。在 Prometheus 规划流程中，规划的结果会生成一个待办列表，包含每个子任务的目标和验收标准。Todo Enforcer 的作用是在执行阶段强制遵循这个待办列表——Agent 不能随意增加任务、不能跳过某个步骤、不能在没有完成验收的情况下声称任务完成。这个约束在复杂项目中非常重要，它防止 Agent 为了"尽快完成"而跳过了某些必要但麻烦的步骤。

Comment Checker 是一个注释质量检查工具。它不检查代码逻辑，只检查注释的质量——注释是否和代码实际行为一致、是否过时、是否太简略或太冗长、是否符合团队的注释规范。这个工具的价值在于它把注释质量从"靠个人习惯"变成了"可自动化检查的指标"。

这些工具默认是启用的，但都可以通过配置来调整行为。如果你不习惯某些工具的工作方式（比如觉得 Ralph Loop 的自动迭代太多了），可以在配置中降低迭代次数或者完全禁用特定工具。配置项在第七章有完整说明。

5.6 Tmux 集成 — 完整交互式终端体验

框架和 Tmux 深度集成，提供了完整的交互式终端体验。这意味着即使你需要长时间运行 Agent、执行复杂的多步骤任务、或者需要在 Agent 执行过程中查看和操作终端，框架都能无缝支持。

Tmux 集成的核心好处有三个。第一，会话持久化。如果你的终端意外断开连接，Tmux 会话不会丢失，Agent 的执行状态会被保留，你重新连接后可以从断点继续。这对于需要数小时的大型重构任务尤其重要。

第二，多会话并行。你可以在不同的 Tmux 窗口中同时运行多个 ultrawork 任务，每个任务有独立的上下文，互不干扰。比如你有一个任务正在运行，你又想起另一个问题需要问，不需要等当前任务完成，在新窗口里直接开另一个 ultrawork 就好。

第三，命令透传。你可以随时在 Tmux 会话中输入命令来干预 Agent 的执行——比如查看当前文件状态、手动运行测试、修改配置然后让 Agent 重新分析。这种灵活性是纯 API 调用的方案很难提供的。

使用 Tmux 集成不需要额外安装任何东西，框架会自动检测系统上是否安装了 Tmux，如果检测到就会自动使用它。如果你的系统没有 Tmux，框架会回退到普通的后台进程模式，但部分依赖会话持久化的功能会受限。

第六章：使用指南 — 两种工作模式

6.1 为什么需要两种模式

大多数 AI 编程工具只提供一种交互路径：要么你给指令，它执行；要么你完全不插手。这种二元对立在真实开发中显得很粗糙——你不可能用同样的方式处理"顺手修个拼写错误"和"重构整个认证模块"。oh-my-openagent 设计的核心理念是：交互粒度应该由任务复杂度决定，而不是工具强制你选择的。于是它提供了两套并行的入口，分别对应两种截然不同的心智模型。

理解这一点很重要。Ultrawork 和 Prometheus 不是功能上的区别，而是哲学上的区别。前者假设你知道自己要什么，只需要一个执行力强的助手；后者假设你知道自己有大问题，但需要和 AI 一起把问题定义清楚。这两种假设在日常开发中各有其适用场景，选对了能省大量时间，选错了要么浪费 AI 算力，要么把时间花在来回沟通上。

6.2 Ultrawork 模式：懒人首选

Ultrawork 的设计目标非常明确：把"说需求"这件事压缩到最少。你只需要敲出 ultrawork 或其简写 ulw，后面跟一段自然语言描述，剩下的全部交给 Agent 自动处理。

框架会经历三个阶段来完成这个过程。首先是代码库分析阶段，Agent 自动扫描当前项目的结构、依赖关系和代码风格，这个阶段不需要你做任何干预，它像一个经验丰富的开发者接手一个陌生项目时做的那样——先读目录结构、配置文件、关键入口文件。其次是模式识别阶段，Agent 在分析结果基础上识别项目的设计模式、架构约定和编码规范，这是真正拉开差距的环节，很多低质量的 AI 编程工具跳过了这一步，导致生成的代码和项目已有风格格格不入。最后是功能实现阶段，Agent 基于前两个阶段的输出编写代码、修改文件、执行必要的测试或构建步骤。

# 基本用法：描述任务，让 Agent 自己搞定
ultrawork 为这个 React 项目添加深色模式切换功能

# 简写形式，同样有效
ulw 修复登录页面的 XSS 漏洞

Ultrawork 适合的场景有几类。日常维护类任务是最明显的——比如修复 bug、添加小功能、更新依赖版本，这类任务通常边界清晰但琐碎，用 Prometheus 模式显得杀鸡用牛刀。另一个典型场景是快速原型验证，当你脑海中有一个想法想立刻验证可行性时，Ultrawork 可以在最短路径上帮你搭出一个能跑的东西出来。还有一种用法被很多人忽略：代码探索。你可以用 Ultrawork 询问"这个模块的职责是什么"、“哪些地方调用了这个函数”，Agent 会自动分析代码库后给出结构化的回答，比自己一点点 grep 效率高得多。

但 Ultrawork 不是万能的。它有一个隐性前提：你给的描述足够让 Agent 推断出正确的实现方向。如果你说"帮我优化性能"，Agent 大概率会从它认为合理的角度去优化，可能是缓存、可能是索引、可能是算法改进——但未必是你真正需要改的那个地方。这种情况下你花的时间可能比不用工具还多，因为还得回滚它做的错误改动。所以使用 Ultrawork 的一个经验法则是：描述要尽量具体，至少说清楚"在哪里"、“做什么”、“做到什么程度”。

6.3 Prometheus 模式：精准控制

如果说 Ultrawork 是自动驾驶，Prometheus 就是手动挡赛车。这个名字本身就透露了设计意图——普罗米修斯为人类盗取火种，是一种主动出击而非被动等待的姿态。

进入 Prometheus 模式的触发方式很特别：在对话中按 Tab 键。这个设计很有意思，它不是在命令行里敲一个命令，而是通过 UI 交互来切换状态。这种设计背后的逻辑是：Prometheus 模式本身就是一种"暂停"，你需要停下来重新审视你要做的事，而不是顺着当前的对话流继续往下走。

进入该模式后，Agent 不会再直接执行任何代码操作，而是切换到面试式规划对话。它会主动向你提问，问题的方向通常包括：需求的具体边界是什么、预期的行为是什么、有没有特殊情况需要处理、有什么现有的约束（比如不能改某个模块、必须兼容某个旧版本 API）、如何验证实现是否正确。这些问题不是走过场，而是真正在帮你把模糊的想法变成可以执行的具体方案。

等你回答完这些问题，Agent 会生成一个结构化的执行计划，然后等待你确认或修改。只有当你对计划满意后，才执行 /start-work 命令启动 Atlas 编排，按计划逐步完成任务。

Prometheus 模式的价值在于把错误成本降到最低。代码写错再回滚是有代价的，尤其是在涉及多个文件、数据库迁移或者生产环境部署时。面试式规划帮你在上游就把需求澄清了，减少了中途推翻重来的概率。对于关键路径上的变更——比如支付模块、安全相关的逻辑、数据模型的迁移——这种投入是值得的。

有一点需要特别注意：Prometheus 模式不会自动保存你的规划对话。如果你在规划中途离开，回来后对话上下文可能已经丢失。所以如果一个复杂的规划对话被意外中断，可以考虑先把关键结论手动复制出来，或者在新对话中引用之前的结论继续推进。

6.4 两种模式如何选用

这里给一个实用的决策框架，不是硬性规则，而是经验之谈。

用 Ultrawork 的情况：任务目标明确、影响范围可控、你对这个模块已经有足够的掌控感。比如"给这个函数加个参数默认值"、“升级到 React 18”、“在 CI 里加一个 lint 检查”。这类任务的特点是：你知道要改哪几个文件、大概怎么改、预期结果是什么。Ultrawork 的快速执行正好匹配这种确定性。

用 Prometheus 的情况：目标模糊或者影响范围不确定。比如"我们系统是不是应该上微服务"、“这个订单模块为什么这么慢”、“能不能把数据层抽象出来方便后面换数据库”。这类任务的特点是：你自己也不完全确定要怎么做，需要在规划过程中把思路理清楚。

组合使用的场景也很常见。一个典型流程是这样的：你用 Prometheus 规划了一个大的重构方向，确认了分几个步骤来做，然后其中某个步骤是"删除旧代码并迁移到新实现"这种可以独立验证的操作，你就可以切换到 Ultrawork 来快速执行这个子任务。关键是把决策和执行分开，Prometheus 负责决策，Ultrawork 负责执行。

还有一种用法值得推荐：先用 Ultrawork 快速探索，再用 Prometheus 精准规划。比如你有一个模糊的想法，先用 Ultrawork 问 Agent"这个项目目前是怎么处理缓存的"，它会快速分析给你一个概览，然后你基于这个概览再决定要不要进入 Prometheus 模式做更系统的改造。这种方式兼顾了效率和信息充分度。

6.5 小结

Ultrawork 和 Prometheus 代表了两种截然不同的 AI 协作哲学：前者追求最短路径，后者追求最小风险。在真实的开发过程中，这两者不是互斥的，而是互补的。掌握什么时候用哪个，比记住怎么用更重要。建议你在接下来一周的工作中刻意练习这个判断：每次动手之前先想一下，这个任务用哪种模式更合适，坚持几天后就会有直觉了。

第七章：配置参考 — 按需定制

7.1 配置文件的基础认知

oh-my-openagent 的配置体系建立在两个层级上：项目级配置和用户级配置。理解这个分层模型是玩转配置的第一步。

项目级配置文件的查找路径有两个优先级。先在项目根目录的 .opencode/oh-my-openagent.json 中查找，如果这个文件不存在，则回退到 ~/.config/opencode/ 下的同名文件。第二个路径就是用户级配置，它会作用在你所有的 opencode 项目上。项目级配置的优先级高于用户级配置，这意味着一旦项目里有了配置文件，用户级的默认设置就被覆盖了。

这种设计有几个实际好处。团队协作时可以把项目级配置文件提交到 Git 仓库，确保团队成员使用统一的 Agent 行为规范——比如统一使用某个模型、统一禁用某些 Hook、统一配置特定的 Category 路径。对于个人而言，用户级配置文件可以作为"我的默认偏好"，新项目不需要每次都配置一遍，直接继承就好。

配置文件格式支持 JSONC（带注释的 JSON），这在开发工具配置中相当常见。JSONC 就是在标准 JSON 的基础上允许单行注释（//）和块注释（/* */）。这个扩展非常实用，因为配置项往往不是自解释的，加上注释可以极大提升可维护性。特别是团队项目里，不同的 Agent 配置参数背后可能有特定的历史原因，没有注释的话后人只能靠试错来理解。

{
  // 项目级配置示例：团队统一规范
  // 此文件提交到 Git，确保团队行为一致
  "agents": {
    // 统一使用 anthropic/claude-sonnet-4-6，避免模型切换导致输出不一致
    "default": {
      "model": "anthropic/claude-sonnet-4-6"
    },
  },
  // 分类路径：指向团队维护的 skills 仓库
  "categories": [
    "./.opencode/categories",
    "/opt/team-opencode/categories"
  ]
}

7.2 常用配置项详解

Agent 模型覆盖

agents 配置项允许你指定默认模型或者给特定任务类型指定模型。这个配置的价值在于：不同模型在不同任务上表现差异很大，Claude 系列模型在代码理解上通常更强，GPT 系列在某些语言翻译或文案生成上可能更顺，而国产模型在中文上下文理解和本地化场景上有独特优势。

{
  "agents": {
    // 全局默认模型
    "default": {
      "model": "anthropic/claude-sonnet-4-6"
    },

    // 按 Agent 名称覆盖模型
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "variant": "high"
    },
    "oracle": {
      "model": "openai/gpt-4o"
    },
    "atlas": {
      "model": "anthropic/claude-sonnet-4-6"
    },

    // 特定 Agent 名称覆盖（如果你的编排中有命名过的 Agent）
    "security-auditor": {
      "model": "anthropic/claude-opus-4-6",
      "variant": "high"
    }
  }
}

注意这里有一个常见误区：不是模型越强越好。Opus 级别的模型在复杂推理上确实更强，但响应速度更慢、费用更高。对于简单的代码格式化或者注释生成，用 Sonnet 级别就绑绑有余了，把 Opus 留给真正需要深度分析的架构设计或安全审计才是合理的资源分配。

Category 分类配置

categories 定义了 Agent 可用的技能分类路径。每个路径对应一个目录，目录中存放各个技能的配置文件。配置多个路径时，Agent 会按顺序搜索，优先使用先找到的同名技能。

这个机制支持一种巧妙的技能覆盖策略：你在项目级配置中定义一个优先级最高的本地路径，放一个同名技能的定制版本，剩余技能回退到用户级或团队级路径。这比 fork 整个技能库然后替换所有路径要优雅得多。

{
  "categories": [
    // 项目私有技能（最高优先级）
    "./.opencode/categories",
    // 团队共享技能
    "/opt/team-opencode/categories",
    // 个人技能（最低优先级，作为兜底）
    "~/.config/opencode/categories"
  ]
}

Hook 配置

Hook 是 oh-my-openagent 架构中非常强大的扩展机制。它允许你在 Agent 执行的各个阶段注入自定义逻辑——比如在每条消息发送前做内容审查、在代码生成后自动运行 linter、在任务完成后发送通知到钉钉或飞书。

但在实际项目中，有些默认 Hook 可能不适合你的场景。最常见的情况是团队有自己的 CI/CD 流程，不希望 Agent 自动提交代码或者推送分支；或者你不想让 Agent 自动执行 npm install 或 pip install（担心引入未审核的依赖）。这时候就可以在配置中精确禁用指定的 Hook。

{
  "disabled_hooks": [
    // 禁用自动提交 Hook，避免 Agent 未经审核直接提交
    "auto_commit",
    // 禁用自动安装依赖 Hook，强制人工审核
    "post_install"
  ]
}

注意： oh-my-openagent 的 Hook 禁用机制使用的是 disabled_hooks 数组，而非 hooks 对象下嵌套 { "enabled": false }。hooks 字段在配置中另有用途（如绑定自定义 Hook 脚本），不能用来禁用内置 Hook。可用的内置 Hook 名包括：auto_commit、background_notification、comment_checker、ralph_loop、rules_injector 等。

后台任务与并发配置

background 配置项控制后台任务的运行方式。对于资源有限的环境（比如内存较小的开发机），降低并发数可以避免 Agent 和其他开发工具抢资源。对于追求效率的场景（比如批量处理多个独立任务），适当提高并发可以缩短总执行时间。

{
  "background": {
    // 默认并发任务数，默认通常为 2
    "defaultConcurrency": 3,

    // 任务超时时间（毫秒），超时后自动终止
    "staleTimeoutMs": 600000,

    // 是否在任务失败时发送通知
    "notifyOnFailure": true,

    // 日志级别：error | warn | info | debug
    "logLevel": "info"
  }
}

7.3 完整配置示例

下面是一个功能完整的配置文件，包含了所有主要配置项。实际使用时不需要全部配置，缺失的项会使用框架默认值。这里列出完整项的目的是让你了解整个配置空间，而不是每次都要写这么多内容。

{
  // === agents 配置 ===
  "agents": {
    "default": {
      "model": "anthropic/claude-sonnet-4-6"
    },
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "variant": "high"
    },
    "oracle": {
      "model": "anthropic/claude-sonnet-4-6"
    }
  },

  // === categories 路径配置 ===
  "categories": [
    "./.opencode/categories",
    "~/.config/opencode/categories"
  ],

  // === 禁用内置 Hook ===
  "disabled_hooks": [
    // 禁用自动提交，CI 环境中建议加入此列表
    "auto_commit",
    // 禁用评论检查器
    "comment_checker"
  ],

  // === 后台任务配置 ===
  "background": {
    "defaultConcurrency": 2,
    "staleTimeoutMs": 300000,
    "notifyOnFailure": true,
    "logLevel": "info"
  },

  // === 高级配置 ===
  "advanced": {
    // 是否启用 Prometheus 模式的详细日志
    "prometheusVerbose": false,
    
    // Ultrawork 模式的超时时间（秒）
    "ultraworkTimeout": 120,
    
    // Agent 之间的消息传递超时（秒）
    "agentCommTimeout": 30,
    
    // 是否允许 Agent 修改配置文件本身
    "allowConfigMutation": false
  }
}

7.4 调试配置问题

配置出错是新手最容易遇到的问题之一。常见的两类错误是：路径不存在和JSON 格式错误。

路径问题相对好排查，配置文件里的路径如果是相对路径，基准是项目根目录而非配置文件所在目录。如果你在 CI 环境中运行尤其要注意——工作目录可能和本地开发时不一样，相对路径就会失效。推荐在 CI 环境中统一使用绝对路径，或者确保工作目录设置正确。

JSON 格式问题要注意几个细节：最后一项后面可以有逗号（JSONC 允许），但键名必须用双引号包裹，布尔值用 true/false（全小写），不能使用 True 或 FALSE。一个实用的技巧是：写完配置后用 python3 -m json.tool your-config.json 验证格式是否合法，这比在 opencode 里运行出错再回头改要高效得多。

# 验证配置文件格式
python3 -m json.tool .opencode/oh-my-openagent.json > /dev/null && echo "配置格式正确" || echo "JSON 格式错误"

7.5 小结

配置体系是 oh-my-openagent 的"控制面板"，掌握它就掌握了定制框架行为的钥匙。核心建议是：从小处开始，逐步扩展。不要一开始就写一个完整的配置文件，而是从最基本的 agents.default 开始，觉得某个行为不符合预期时再去添加对应的配置项。这样既能理解每个配置项的实际效果，又不会陷入"配置地狱"——见过太多项目花了一整天调配置，结果发现默认行为就已经够用了。

第八章：总结与资源

8.1 oh-my-openagent 的核心优势

回顾一下这套框架到底解决了什么问题。传统的 AI 编程工具——无论是 GitHub Copilot、Claude Code 还是 Cursor——本质上都是单 Agent 协作模式：你发出一段指令，AI 执行，返回结果，循环往复。这个模式有几个天然的瓶颈：当任务涉及多个领域时，单个 Agent 的能力边界很快就会显现；当任务规模变大时，缺少架构层面的规划导致 AI 在执行中迷失方向；当团队有统一规范时，没有机制确保 AI 遵守这些规范。

oh-my-openagent 的回答是 Atlas 编排。它不再把 AI 当成一个响应式的执行器，而是把它当成一个有多角色分工的虚拟团队。规划者负责理解需求和制定路线，执行者负责具体实现，审查者负责质量把关。每个角色的职责清晰，协作有序。这不是简单的"加几个 Prompt"能实现的效果，而是架构层面的重新设计。

具体来说，这套架构带来了三个实质性的改变。第一个改变是上下文质量的提升。在传统模式下，你需要手动管理对话上下文，告诉 AI 你的项目用什么框架、有哪些约束、关注哪些风险。Atlas 编排中这些信息在角色间自动流转，规划者的输出直接作为执行者的输入，不需要你反复复述。第二个改变是错误路径的早期发现。Prometheus 模式通过面试式提问在动手之前就把需求澄清了，这在复杂项目中意义重大——越早发现问题，修复成本越低。第三个改变是可预测的行为规范。通过配置体系，你可以把团队的编码规范、质量标准、安全要求固化成 Agent 的默认行为，确保每次交互都在这个框架内运行，而不是每次都依赖 Prompt 的随机发挥。

8.2 与 Claude Code、Cursor 的横向对比

做技术选型时人们总喜欢问"哪个更好"，但这个问题本身预设了一个错误的框架。工具之间不是简单的优劣之分，而是能力边界的差异。以下对比基于实际使用体验，不涉及厂商宣传。

Claude Code 的强项在于模型本身对代码的理解深度。当你需要它分析一个复杂代码库的架构、解释某个设计决策的原因、或者在多个文件之间建立关联时，Claude 的表现通常更稳。弱点是它的交互模式相对单一，基本上是"指令-执行"的循环，缺少系统化的任务编排能力。如果你的项目规模不大、任务边界清晰，Claude Code 完全可以胜任，不需要额外的框架。

Cursor 的优势在于 IDE 集成。它的聊天、自动补全、代码生成都和编辑器深度绑定，切换成本很低。弱点是它的 Agent 能力相对基础，对于需要跨文件协调或者分阶段规划的任务，Cursor 的表现会逐渐吃力。另外 Cursor 的配置体系不如 oh-my-openagent 灵活，定制成本较高。

oh-my-openagent 的差异化定位是任务编排与协作框架。它不替换 Claude Code 或 Cursor，而是在它们之上加了一层结构。如果你的需求是"在某个 Claude 模型上实现多角色协作和系统化规划"，那 oh-my-openagent 就是答案。如果你只是需要一个随时能问的代码助手，Claude Code 更轻量。

一个更直观的选型建议：如果你发现自己经常需要在一个大型项目里做跨模块的改造或者重构，而且 AI 经常在长对话中"忘记"之前说过的约束——这种情况下 oh-my-openagent 的 Atlas 编排和 Prometheus 规划模式能显著改善体验。如果你平时的工作以单文件修改、函数级别的问题解答为主，现有的工具已经绑绑有余了。

8.3 适用场景分析

oh-my-openagent 最适合以下几类场景。

大型代码库的结构化改造。当你要做跨模块的重构、或者需要在不熟悉的代码库中实施变更时，Atlas 编排的多角色协作能帮你把复杂的任务分解成可管理的步骤。每个步骤有规划、有执行、有检查，形成完整的闭环。

需要严格质量把控的生产环境变更。Prometheus 模式的面试式规划确保在动手之前你对变更的影响范围、风险点、验证方式都有清晰的认知。这不是过度工程，而是对生产环境的合理敬畏。

团队统一开发规范的落地。通过项目级配置文件和统一的 Categories 路径，团队可以把编码规范、代码审查标准、安全要求固化为 Agent 的默认行为。新成员加入时不需要学习繁琐的规则，只需要 clone 项目配置，Agent 就会自动遵守团队约定。

快速原型与迭代验证。Ultrawork 模式在你想快速验证一个想法时提供了最短路径。不需要精细规划，只需要描述目标，Agent 自动完成分析到实现的全流程。这对于 hackathon 或者技术调研场景尤其有价值。

不太适合的场景：简单的一次性脚本、极小的个人项目（配置成本超过收益）、以及需要实时交互的调试工作（AI 重启对话的延迟在这种场景下难以接受）。

8.4 相关资源

如果你想进一步了解或者参与这个项目，以下是主要的资源入口。

项目源代码托管在 GitHub，地址是 https://github.com/code-yeongyu/oh-my-openagent。仓库中包含了完整的源代码、安装脚本和示例配置，推荐直接阅读 README 和 examples/ 目录，那里通常有最新的用法演示。

官方文档站点是 https://ohmyopenagent.com/zh/docs，提供了分章节的详细文档。如果你更习惯阅读文档而不是看代码，这个站点是更好的起点。文档目前覆盖了安装、快速开始、配置参考和使用模式等核心内容。

如果你在使用过程中遇到问题或者有功能建议，GitHub Issues 是最合适的反馈渠道。项目的维护者对社区反馈响应积极，特别是在 bug 报告和用法咨询方面。另外如果你发现某些场景文档没有覆盖，欢迎提交 issue——这本身就是对社区的贡献。

对于想深入了解内部实现的开发者，可以关注项目的源码目录结构，特别是 atlas/ 目录下的编排逻辑和 hooks/ 目录下的 Hook 实现。框架的设计并不复杂，理解清楚 Atlas 的角色定义和消息传递机制，就基本掌握了整个系统的核心思想。

8.5 写在最后

工具的价值最终体现在它能否改变你的工作方式上。oh-my-openagent 不是那种装上之后立刻就有感的工具——它的 Ultrawork 模式随便试试就能上手，但 Prometheus 和 Atlas 的真正威力需要你把它放到真实的大型项目中去体验。

建议的上手路径是：先用 Ultrawork 处理一周的日常任务，培养对这个工具的信任感；然后选一个中等复杂度的重构任务，用 Prometheus 模式完整走一遍规划流程，感受面试式提问如何改变你的思考方式；最后如果你的团队有多人协作需求，把项目级配置和 Categories 路径用起来，体验团队规范落地的实际效果。完成这三步之后，你大概会有自己的判断：这个工具值不值得成为你日常开发的核心助手。