从单兵到军团：oh-my-openagent 构建你的AI开发流水线

功能介绍

oh-my-openagent 是一个强大的 AI 代理编排系统，为 OpenCode 提供了 11 个专业化 AI 代理、分类系统、技能系统、命令系统以及丰富的钩子和 MCP 集成。

核心代理（Core Agents）

系统提供了多个具有不同专长的 AI 代理：

代理	模型	用途
Sisyphus	`claude-opus-4-6`	默认编排器，负责任务规划、委派和执行
Hephaestus	`gpt-5.4`	深度工作者，端到端完成任务
Oracle	`gpt-5.4`	架构决策、代码审查、调试（只读）
Librarian	`minimax-m2.7`	多仓库分析、文档查找
Explore	`grok-code-fast-1`	快速代码库探索和搜索
Multimodal-Looker	`gpt-5.4`	视觉内容分析（PDF、图片、图表）

规划代理（Planning Agents）

代理	用途
Prometheus	战略规划器，支持访谈模式，创建详细工作计划
Metis	规划顾问，识别隐藏意图和潜在失败点
Momus	规划审查员，验证计划的清晰度和完整性

编排代理（Orchestration Agents）

代理	用途
Atlas	待办列表编排器，系统化执行计划任务
Sisyphus-Junior	分类生成的执行器，根据任务类别自动选择模型

分类系统（Category System）

分类系统允许根据任务类型自动选择最优的模型和配置：

分类	默认模型	适用场景
`visual-engineering`	`google/gemini-3.1-pro`	前端、UI/UX、设计、动画
`ultrabrain`	`openai/gpt-5.4` (xhigh)	深度逻辑推理、复杂架构决策
`deep`	`openai/gpt-5.4` (medium)	自主问题解决，深入理解
`artistry`	`google/gemini-3.1-pro` (high)	创意/艺术任务
`quick`	`openai/gpt-5.4-mini`	简单任务，单文件修改
`writing`	`google/gemini-3-flash`	文档、技术写作

技能系统（Skills）

技能是注入专业知识和工具的工作流：

技能	触发场景	描述
git-master	commit、rebase、“谁写的”	Git 专家，提交策略、历史分析
playwright	浏览器任务、测试	通过 Playwright MCP 进行浏览器自动化
frontend-ui-ux	UI/UX 任务	设计师兼开发者，打造精美界面

内置命令

命令	描述
`/init-deep`	初始化分层 AGENTS.md 知识库
`/ralph-loop`	启动自引用开发循环直到完成
`/refactor`	智能重构，支持 LSP、AST-grep
`/start-work`	从 Prometheus 计划开始执行
`/handoff`	创建上下文摘要以便在新会话中继续工作

工具集

系统提供了丰富的工具：

代码搜索：grep、glob
编辑工具：基于哈希锚点的 edit 工具
LSP 工具：诊断、重命名、跳转定义、查找引用
AST-grep 工具：AST 感知的代码模式搜索和替换（支持 25 种语言）
委派工具：call_omo_agent、task、background_output
会话管理：session_list、session_read、session_search
任务管理：task_create、task_get、task_list、task_update
交互式终端：基于 tmux 的 interactive_bash

钩子系统（Hooks）

钩子系统在代理生命周期的关键节点拦截和修改行为，包括：

上下文注入：自动注入 AGENTS.md、README.md、规则文件
生产力控制：关键词检测、思考模式、自动命令执行
质量与安全：注释检查、编辑错误恢复、写入保护
恢复与稳定性：会话恢复、上下文窗口限制处理、模型回退
通知：后台任务完成通知、版本更新检查

MCP 集成

内置 MCP 服务器：

MCP	描述
websearch	实时网络搜索（Exa AI）
context7	官方文档查询
grep_app	公共 GitHub 仓库代码搜索

安装准备

前置条件

已安装 OpenCode（版本 ≥ 1.0.150）
操作系统支持：macOS (ARM64/x64)、Linux (x64/ARM64/Alpine)、Windows (x64)
推荐运行时：Bun（备选：Node.js）

订阅服务确认

安装前需明确团队已订阅的服务，这将决定 CLI 参数配置：

GitHub Copilot：提供 GPT-5.4、Claude Sonnet/Opus、Grok Code Fast 等模型
MiniMax（通过 OpenCode Go）：提供 M2.7、Kimi K2.5 等高性价比模型
其他可选：Claude Pro/Max、ChatGPT Plus、Gemini、Z.ai Coding Plan

安装

手动安装命令

# 使用 Bun（推荐）
bunx oh-my-opencode install

# 或使用 Node.js
npx oh-my-opencode install

安装器将自动完成：

在 ~/.config/opencode/opencode.json 中注册插件
根据订阅参数配置对应 Agent 的模型路由
提示需要认证的提供商

验证安装

# 检查版本
opencode --version

# 验证配置文件
cat ~/.config/opencode/opencode.json

# 运行诊断工具
bunx oh-my-opencode doctor

认证配置

对于需要 OAuth 的提供商，执行：

opencode auth login

按提示选择 Provider 并完成浏览器授权。注意：GitHub Copilot 的 provider 前缀必须使用 github-copilot/。

模型配置策略

配置原则

系统按以下优先级解析模型：显式配置 > Provider 回退链 > 系统默认。建议遵循”角色 - 模型”匹配原则，即根据 Agent 的职责选择最合适的模型。

成本优化建议

分层路由：高价值任务（架构设计）使用 Copilot 高端模型，低价值任务（文档检索）使用 MiniMax
Variant 控制：通过 variant: medium/high/xhigh 调节推理强度，避免过度消耗
高速模式：对延迟敏感的任务使用 minimax-m2.7-highspeed 或 grok-code-fast-1

配置

基础配置

在项目根目录创建 oh-my-openagent.jsonc 配置文件（或通过 ~/.config/opencode/oh-my-openagent.jsonc 进行全局配置）：

{
  // 自定义代理模型
  "agents": {
    "sisyphus": {
      "fallback_models": [
        "opencode/glm-5",
        { "model": "openai/gpt-5.4", "variant": "high" }
      ]
    }
  },

  // 自定义分类
  "categories": {
    "korean-writer": {
      "model": "google/gemini-3-flash",
      "temperature": 0.5,
      "prompt_append": "You are a Korean technical writer."
    }
  },

  // 浏览器自动化引擎
  "browser_automation_engine": {
    "provider": "agent-browser" // 或 "playwright"（默认）
  },

  // tmux 可视化
  "tmux": {
    "enabled": true,
    "layout": "main-vertical"
  },

  // Ralph Loop 配置
  "ralph_loop": {
    "enabled": true,
    "default_max_iterations": 100
  },

  // 模型能力配置
  "model_capabilities": {
    "enabled": true,
    "auto_refresh_on_start": true
  },

  // Claude Code 兼容性开关
  "claude_code": {
    "mcp": true,
    "commands": true,
    "skills": true,
    "agents": true,
    "hooks": true,
    "plugins": true
  },

  // 禁用的技能
  "disabled_skills": [],

  // 禁用的钩子
  "disabled_hooks": []
}

文件化 Prompt

支持从外部文件加载代理的系统提示：

{
  "agents": {
    "sisyphus": {
      "prompt": "file:///path/to/custom-prompt.md"
    },
    "oracle": {
      "prompt_append": "file:///path/to/additional-context.md"
    }
  }
}

支持 ~ 展开和相对路径。适用于：

版本控制提示文件
跨项目共享提示
保持配置文件简洁
添加分类特定上下文

自定义技能

在 .opencode/skills/ 目录下创建自定义技能：

---
name: my-skill
description: My special custom skill
mcp:
  my-mcp:
    command: npx
    args: ["-y", "my-mcp-server"]
---

# My Skill Prompt

This content will be injected into the agent's system prompt.

技能加载位置（优先级从高到低）：

.opencode/skills/*/SKILL.md（项目级，OpenCode 原生）
~/.config/opencode/skills/*/SKILL.md（用户级，OpenCode 原生）
.claude/skills/*/SKILL.md（项目级，Claude Code 兼容）
.agents/skills/*/SKILL.md（项目级，Agents 约定）
~/.agents/skills/*/SKILL.md（用户级，Agents 约定）

同名技能在高优先级位置会覆盖低优先级位置的技能。

自定义命令

在 .opencode/command/ 目录下创建自定义命令。命令加载位置：

.opencode/command/*.md（项目级，OpenCode 原生）
~/.config/opencode/command/*.md（用户级，OpenCode 原生）
.claude/commands/*.md（项目级，Claude Code 兼容）

任务系统

在配置中启用任务系统：

{
  "experimental": {
    "task_system": true
  }
}

任务存储在 .sisyphus/tasks/ 目录下，支持依赖关系和并行执行。

任务 Schema：

interface Task {
  id: string; // T-{uuid}
  subject: string; // 命令式："运行测试"
  description: string;
  status: "pending" | "in_progress" | "completed" | "deleted";
  activeForm?: string; // 进行时："正在运行测试"
  blocks: string[]; // 被此任务阻塞的任务
  blockedBy: string[]; // 阻塞此任务的任务
  owner?: string; // 代理名称
  metadata?: Record<string, unknown>;
  threadID: string; // 会话 ID（自动设置）
}

依赖与并行执行：

[构建前端]    ──┐
                ├──→ [集成测试] ──→ [部署]
[构建后端]    ──┘

blockedBy 为空的任务并行运行
依赖任务等待阻塞任务完成后执行

与 TodoWrite 的区别：

特性	TodoWrite	任务系统
存储	会话内存	文件系统
持久化	关闭后丢失	重启后保留
依赖	无	完整支持（`blockedBy`）
并行执行	手动	自动优化

运维与监控

配置验证

# 检查模型可用性
opencode models | grep -E "(copilot|minimax)"

# 测试特定代理
opencode /ask "测试查询" --agent librarian

用量监控

# 查看会话统计
opencode /stats

# 分析模型调用分布
cat ~/.config/opencode/sessions/*.json | grep -o '"model":"[^"]*"' | sort | uniq -c

模型能力刷新

更新本地模型能力缓存：

bunx oh-my-opencode refresh-model-capabilities

配置启动时自动刷新：

{
  "model_capabilities": {
    "enabled": true,
    "auto_refresh_on_start": true,
    "refresh_timeout_ms": 5000,
    "source_url": "https://models.dev/api.json"
  }
}

常见问题排查

模型无效：检查 provider 前缀是否正确（github-copilot/ 而非 copilot/）
认证失败：清除冲突的环境变量（如 ANTHROPIC_AUTH_TOKEN）后重新执行 opencode auth login
响应延迟：确认是否误用非高速版本模型

使用示例

调用特定代理

Ask @oracle to review this design and propose an architecture
Ask @librarian how this is implemented
Ask @explore for the policy on this feature

使用分类委派任务

task({
  category: "visual-engineering",
  prompt: "Add a responsive chart component to the dashboard page",
});

后台运行代理

task({
  subagent_type: "explore",
  load_skills: [],
  prompt: "Find auth implementations",
  run_in_background: true,
});

// 继续工作...
// 系统会在完成时通知

// 获取结果
background_output(task_id: "bg_abc123");

启用 tmux 可视化后，后台代理会在独立的 tmux 窗格中运行，可以实时观察多个代理的工作状态。

组合分类和技能

// UI 实现者
task({
  category: "visual-engineering",
  load_skills: ["frontend-ui-ux", "playwright"],
  prompt: "Implement the new landing page design",
});

// 架构师
task({
  category: "ultrabrain",
  load_skills: [],
  prompt: "Analyze the current architecture and propose improvements",
});

// 维护者
task({
  category: "quick",
  load_skills: ["git-master"],
  prompt: "Fix the typo in the login form",
});

委派任务 Prompt 指南

委派任务时，清晰且具体的提示至关重要。应包含以下 7 个要素：

TASK：需要做什么？（单一目标）
EXPECTED OUTCOME：交付物是什么？
REQUIRED SKILLS：应加载哪些技能？
REQUIRED TOOLS：必须使用哪些工具？（白名单）
MUST DO：必须做什么（约束条件）
MUST NOT DO：绝不能做什么
CONTEXT：文件路径、现有模式、参考资料

好的示例：

TASK: 修复 LoginButton.tsx 中移动端布局断裂问题
CONTEXT: src/components/LoginButton.tsx，使用 Tailwind CSS
MUST DO: 在 md: 断点处修改 flex-direction
MUST NOT DO: 修改现有桌面端布局
EXPECTED: 按钮在移动端垂直对齐

使用命令

/init-deep                          # 初始化知识库
/ralph-loop "Build a REST API"      # 启动开发循环
/refactor src/auth                  # 智能重构
/start-work                         # 从计划开始执行
/handoff                            # 创建交接文档

最佳实践总结

最小权限配置：仅启用团队实际使用的 Agent 和模型，减少攻击面
配置版本管理：将 opencode.json 和 oh-my-openagent.jsonc 纳入 Git 管理，确保环境一致性
渐进式优化：先使用默认配置上线，再根据实际用量数据微调模型路由
文档化决策：记录每个 Agent 的模型选择理由，便于后续审计和交接
利用回退链：为关键代理配置合理的回退模型链，确保服务高可用
善用钩子：利用内置钩子实现自动上下文注入、错误恢复和质量检查

总结

oh-my-openagent 通过灵活的模型路由机制和细粒度的 Agent 配置，为团队提供了构建高效、可控、成本优化的 AI 开发工作流的能力。作为架构工程师，建议在生产环境中采用”核心任务用高端模型、辅助任务用性价比模型”的分层策略，并建立持续的用量监控机制。随着团队需求演进，可进一步探索多账号负载均衡、本地缓存加速等进阶特性，持续优化智能体系统的整体效能。