nexus/openclaw/yunce/oh-my-opencode-使用指南.md

---
title: oh-my-opencode 使用指南
source:
author: shenwei
published:
created:
description:
tags: []
---

# oh-my-opencode 使用指南

> 多模型 Agent 编排框架 for OpenCode

---

## 一、概述

**oh-my-opencode** 是一个强大的多模型 Agent 编排框架，专为 OpenCode 设计。它通过多个专业化 Agent 的协作，实现复杂任务的自动化处理。

### 核心理念

- **多 Agent 协作**：不同 Agent 承担不同角色，各司其职
- **意图分类**：自动识别任务类型并路由到合适的 Agent
- **计划与执行分离**：战略规划与具体执行解耦

---

## 二、安装

### 方法一：npm 全局安装

```bash
npm install -g oh-my-opencode
```

### 方法二：OpenClaw 内置

如果已安装 OpenClaw，oh-my-opencode 通常已集成：

```bash
# 检查是否可用
oh-my-opencode --version
# 或
opencode --version
```

---

## 三、核心命令

| 命令 | 说明 |
|------|------|
| `oh-my-opencode run <任务>` | 自动执行指定任务 |
| `opencode run <任务>` | 同上，快捷命令 |
| `Ctrl+P` | 进入 **Prometheus 模式**（计划模式） |
| `Ctrl+E` | 启动 **Atlas** 执行计划 |

### 命令行选项

```bash
# 指定模型
oh-my-opencode run <任务> --model opencode/claude-opus-4-6

# 指定 Agent
oh-my-opencode run <任务> --agent sisyphus

# dry-run 预览
oh-my-opencode run <任务> --dry-run

# 输出 JSON 格式
oh-my-opencode run <任务> --json
```

---

## 四、Agent 介绍

oh-my-opencode 包含多个专业化 Agent，形成完整的任务处理生态系统。

| Agent | 角色 | 主要职责 |
|-------|------|----------|
| **Sisyphus** | 主编排器 | 分类意图、委派任务、结果汇总 |
| **Prometheus** | 战略规划师 | 访谈式计划、深入分析需求 |
| **Atlas** | 执行者 | 执行 Prometheus 制定的计划 |
| **Oracle** | 架构顾问 | 技术架构咨询、最佳实践建议 |
| **Hephaestus** | 深度编码 Agent | GPT 原生深度代码生成 |
| **Explore** | 代码搜索 | 快速定位代码库中的内容 |
| **Librarian** | 文档搜索 | 文档和知识库检索 |
| **Metis** | 计划漏洞分析 | 识别计划中的潜在问题 |
| **Momus** | 严格审查 | 代码审查、质量把关 |

### Agent 详细说明

#### Sisyphus（西西弗斯）- 主编排器

```
角色：团队 leader
特点：智能路由、任务分解
```

Sisyphus 是整个系统的核心，负责：
- 接收用户任务输入
- 识别任务意图和类型
- 决定调用哪个 Agent
- 汇总各 Agent 的结果
- 返回最终响应

#### Prometheus（普罗米修斯）- 战略规划师

```
角色：策略顾问
特点：访谈式、深入分析
```

Prometheus 专注于长期规划：
- 与用户进行问答式对话
- 深入理解需求和约束
- 制定详细的执行计划
- 识别潜在风险

**激活方式**：按 `Ctrl+P` 进入计划模式

#### Atlas（阿特拉斯）- 执行者

```
角色：执行者
特点：高效执行、结果导向
```

Atlas 负责执行：
- 读取 Prometheus 的计划
- 逐步执行任务
- 报告执行进度
- 处理执行中的问题

**激活方式**：按 `Ctrl+E` 启动执行

#### Oracle（甲骨文）- 架构顾问

```
角色：技术顾问
特点：全局视角、最佳实践
```

提供架构层面的指导：
- 系统设计建议
- 技术选型咨询
- 性能优化方案
- 代码规范

#### Hephaestus（赫菲斯托斯）- 深度编码

```
角色：高级工程师
特点：深度思考、复杂代码
```

专注于高质量代码生成：
- 复杂业务逻辑实现
- 算法设计与优化
- 代码重构
- 测试用例编写

#### Explore（探索者）- 代码搜索

```
角色：搜索专家
特点：快速定位、精准匹配
```

快速找到目标代码：
- 函数定义查找
- 代码片段搜索
- 依赖关系追踪
- 文件结构分析

#### Librarian（图书管理员）- 文档搜索

```
角色：知识管家
特点：信息检索、知识整合
```

文档和知识检索：
- API 文档查找
- 技术文章搜索
- 示例代码定位
- 问题解决方案

#### Metis（弥涅尔瓦）- 计划漏洞分析

```
角色：审计员
特点：批判性思维、风险识别
```

分析计划的问题：
- 逻辑漏洞检测
- 边界条件分析
- 依赖关系审查
- 风险点标注

#### Momus（摩墨斯）- 严格审查

```
角色：质量守门人
特点：严格标准、一丝不苟
```

代码审查：
- 代码质量评估
- 安全漏洞检测
- 风格一致性检查
- 最佳实践验证

---

## 五、工作流程

### 标准流程

```
┌─────────────────────────────────────────────────────────┐
│                     用户输入任务                         │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│              Sisyphus 分类意图 & 委派                    │
│  (判断任务类型 → 选择合适 Agent)                          │
└─────────────────────┬───────────────────────────────────┘
                      ▼
         ┌────────────┼────────────┐
         ▼            ▼            ▼
    ┌─────────┐  ┌─────────┐  ┌─────────┐
    │ Oracle  │  │ Hephaestus│ │ Explore │
    │ (架构)  │  │ (编码)   │  │ (搜索)  │
    └─────────┘  └─────────┘  └─────────┘
         │            │            │
         └────────────┼────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│              Sisyphus 结果汇总                          │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│                     返回结果                            │
└─────────────────────────────────────────────────────────┘
```

### 计划模式流程（Prometheus + Atlas）

```
┌─────────────────────────────────────────────────────────┐
│  按 Ctrl+P → 进入 Prometheus 模式                       │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│           Prometheus 访谈式计划                         │
│  - 询问需求细节                                         │
│  - 分析约束条件                                         │
│  - 制定执行计划                                         │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│              可选：Metis 漏洞分析                       │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│  按 Ctrl+E → 启动 Atlas 执行计划                        │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│              Atlas 逐步执行 & 报告                      │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│           可选：Momus 代码审查                          │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│                     完成                                │
└─────────────────────────────────────────────────────────┘
```

---

## 六、常见用例

### 用例 1：快速代码搜索

```bash
# 使用 Explore 查找函数定义
oh-my-opencode run "查找 auth.py 中的 login 函数"

# 使用 Librarian 查找文档
oh-my-opencode run "查找 React Hooks 文档"
```

### 用例 2：架构咨询

```bash
# 询问 Oracle 架构建议
oh-my-opencode run "如何设计微服务架构"
```

### 用例 3：复杂编码任务

```bash
# 使用 Hephaestus 进行深度开发
oh-my-opencode run "实现一个 JWT 认证模块"
```

### 用例 4：计划 + 执行

```
1. 按 Ctrl+P 进入 Prometheus 模式
2. 对话式描述需求：
   > 我需要一个用户权限系统
3. Prometheus 分析并制定计划
4. 确认计划后，按 Ctrl+E
5. Atlas 执行计划
6. Momus 审查代码
```

### 用例 5：代码审查

```bash
# 使用 Momus 审查代码
oh-my-opencode run "审查 src/auth 模块的代码"
```

---

## 七、配置

### 基本配置

`~/.oh-my-opencode/config.json`:

```json
{
  "defaultAgent": "sisyphus",
  "model": "opencode/claude-opus-4-6",
  "timeout": 300,
  "agents": {
    "sisyphus": {
      "enabled": true
    },
    "prometheus": {
      "enabled": true,
      "questions": ["需求详情", "约束条件", "时间要求"]
    },
    "atlas": {
      "enabled": true,
      "stepDelay": 1000
    }
  }
}
```

### Agent 别名

```json
{
  "aliases": {
    "p": "prometheus",
    "a": "atlas",
    "o": "oracle",
    "h": "hephaestus",
    "e": "explore",
    "l": "librarian",
    "m": "metis",
    "mo": "momus"
  }
}
```

---

## 八、快捷键参考

| 快捷键 | 功能 |
|--------|------|
| `Ctrl+P` | 进入 Prometheus 计划模式 |
| `Ctrl+E` | 启动 Atlas 执行 |
| `Ctrl+C` | 中断当前任务 |
| `Ctrl+L` | 清除输出 |
| `Tab` | 自动补全 |

---

## 九、故障排除

### Agent 无响应

```bash
# 查看 Agent 状态
oh-my-opencode status

# 重置 Agent
oh-my-opencode reset --agent <agent-name>
```

### 模型调用失败

```bash
# 检查 API 配置
oh-my-opencode config --show

# 切换模型
oh-my-opencode run <task> --model <alternative-model>
```

### 执行中断恢复

```bash
# 查看执行历史
oh-my-opencode history

# 恢复执行
oh-my-opencode resume --task-id <id>
```

---

## 十、进阶技巧

### 1. Agent 组合使用

```bash
# 先搜索，再编码
oh-my-opencode run "查找现有用户认证代码并优化"
```

### 2. 上下文继承

在对话中连续使用，保持上下文：

```
> 设计一个 API
(Plan with Prometheus)
> 按这个计划实现
(Atlas executes)
> 添加单元测试
(Hephaestus)
```

### 3. 输出格式

```bash
# JSON 输出
oh-my-opencode run <task> --json

# Markdown 报告
oh-my-opencode run <task> --report

# 仅显示差异
oh-my-opencode run <task> --diff
```

---

## 附录：Agent 选择指南

| 任务类型 | 推荐 Agent |
|----------|------------|
| 日常任务、简单咨询 | Sisyphus |
| 复杂需求、长期规划 | Prometheus |
| 执行既定计划 | Atlas |
| 架构设计、技术选型 | Oracle |
| 深度编码、复杂逻辑 | Hephaestus |
| 代码搜索、定位 | Explore |
| 文档查找、知识检索 | Librarian |
| 计划审查、漏洞分析 | Metis |
| 代码审查、质量把关 | Momus |

---

*文档版本：1.0*  
*最后更新：2026-03-16*