OpenCode + OhMyOpenCode 使用文档

原文连接:https://www.rendering.me/blog/opencode-ohmyopencode-guide

版本信息:OpenCode v1.14.28 / OhMyOpenAgent v3.17.6(npm 包名:oh-my-opencode

核心理念:不是给一个模型打类固醇,而是运营一个 AI 联合体——Claude 做编排,GPT 做推理,Kimi 提速度,Gemini 处理视觉。各司其职,并行运转。


目录


一、基础环境搭建

1.1 安装 OpenCode

# 推荐方式:官方安装脚本
curl -fsSL https://opencode.ai/install | bash

# 或通过 npm
npm install -g opencode-ai

# 或通过 Homebrew(macOS)
brew install anomalyco/tap/opencode

1.2 安装 OhMyOpenCode

# 前提:OpenCode 已安装

# 方式一:npx 安装(推荐)
bunx oh-my-opencode install

# 方式二:npm 全局安装
npm install -g oh-my-opencode

安装过程中会引导你配置 AI 模型提供商(API Key)。

1.3 配置目录结构

安装后自动生成的目录结构:

~/.config/opencode/
├── opencode.json                    # OpenCode 主配置(加载 oh-my-openagent 插件)
├── opencode.json.backup-*           # 配置自动备份
├── oh-my-openagent.json             # OhMyOpenCode 代理编排配置
├── oh-my-openagent.json.bak.*       # 旧配置备份
└── oh-my-openagent.json.migrations.json  # 迁移记录

~/.local/share/opencode/
├── auth.json                        # API 密钥存储
├── opencode.db                      # 会话数据库
├── log/                             # 会话日志
└── storage/                         # 持久化状态

~/.cache/oh-my-opencode/
├── connected-providers.json         # 已连接提供商
├── model-capabilities.json          # 模型能力数据(890KB)
└── provider-models.json             # 提供商模型列表(5.6MB)

~/.opencode/
└── skills/                          # 用户自定义技能(可选)
    └── my-skill/
        └── SKILL.md

1.4 验证安装

# 查看版本
opencode --version

# 启动 TUI
opencode

二、新项目使用指南

场景:从头开始一个全新项目,没有任何现有代码。

2.1 第一步:进入项目目录并启动 OpenCode

mkdir my-new-project
cd my-new-project
opencode

OpenCode 会自动检测当前目录,启动交互式 TUI 界面。

2.2 第二步:生成项目上下文文件(AGENTS.md)

在 TUI 中输入以下命令:

/init-deep

这会自动扫描项目目录结构,在整个项目层级中生成 AGENTS.md 文件:

my-new-project/
├── AGENTS.md                       # 全局架构与约定
├── src/
│   ├── AGENTS.md                   # src 级规范
│   └── components/
│       └── AGENTS.md               # 组件级详细说明
├── backend/
│   └── AGENTS.md                   # 后端规范
└── docs/
    └── AGENTS.md                   # 文档规范

为什么需要 AGENTS.md?

AGENTS.md 是一个跨工具标准(由 Linux Foundation Agentic AI Foundation 管理),被 20+ 主流 AI 编码工具支持。它告诉 AI:

  • 项目的技术栈和架构
  • 编码规范和约定
  • 构建、测试、lint 命令
  • 禁止触碰的文件和目录

2.3 第三步:使用 ultrawork 开始开发

在 TUI 中输入:

ultrawork

或简写:

ulw

ultrawork 会触发一整套自律智能体军团(Sisyphus + Hephaestus + Oracle + Librarian + Explore),它们会:

  1. Sisyphus(主编排器)分析你的需求,制定执行计划
  2. 将任务分解成独立的工作单元,并行分发给专家代理
  3. Hephaestus 负责代码实现,Oracle 负责架构审查
  4. 持续自我循环(Ralph Loop),直到任务 100% 完成才停止

推荐用法

# 在 TUI 中用自然语言描述需求
我想做一个 React + TypeScript 的任务管理应用,
包含登录注册、看板视图、拖拽排序功能。

然后 Sisyphus 会开始规划、提问,最终启动 ultrawork 全自动开发。

2.4 第四步:配置项目级配置(可选)

在项目根目录创建 opencode.json 进行项目级定制:

{
  "$schema": "https://opencode.ai/config.json",
  // 项目级别的 AGENTS.md 会自动加载,也可手动指定额外指令文件
  "instructions": [
    "CONTRIBUTING.md",
    "docs/coding-style.md"
  ],
  "permission": {
    "edit": "ask",    // 编辑前询问
    "bash": "ask"     // 执行命令前询问
  }
}

如需覆盖 OhMyOpenCode 的代理配置,创建 .opencode/oh-my-openagent.jsonc

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",
  "agents": {
    "sisyphus": { "model": "deepseek/deepseek-v4-pro" }
  },
  "categories": {
    "quick": { "model": "deepseek/deepseek-v4-flash" }
  }
}

2.5 推荐:新项目完整工作流

1. 进入空目录 → opencode 启动
2. /init-deep           ← 自动生成 AGENTS.md 上下文
3. 用自然语言描述项目需求(越详细越好)
4. ultrawok(或 ulw)   ← 一键全自动开发
5. 阶段性检查 → 继续 ulw 修正
6. 项目完成

三、现有项目使用指南

场景:你已有一个正在开发中的项目,希望接入 OpenCode + OhMyOpenCode。

3.1 第一步:进入项目目录

cd /path/to/existing-project
opencode

OpenCode 会自动向上遍历目录树,发现以下配置文件(按优先级从低到高合并):

优先级 来源 说明
1 .well-known/opencode(远程) 组织级默认配置
2 ~/.config/opencode/opencode.json 用户全局偏好
3 opencode.json(项目根目录) 项目特定设置
4 .opencode/ 目录 代理、命令、插件、技能

配置是合并而非替换——只有冲突的键才会被覆盖。

3.2 第二步:让 AI 理解你的项目

方式 A:项目中已有 AGENTS.md(推荐)

如果你的项目已经有 AGENTS.md,OpenCode 会自动加载它。你可以追加更多细节:

# 项目名称

## 项目概述
- 技术栈:Next.js 14 + TypeScript + Prisma + PostgreSQL
- 部署:Vercel + Railway

## 关键命令
- 开发服务器:`npm run dev`
- 构建:`npm run build`
- 类型检查:`npx tsc --noEmit`
- 测试:`npx vitest run`
- Lint:`npx eslint src/`

## 代码规范
- 使用 TypeScript strict 模式
- ESM 导入(禁止 require())
- 组件使用 PascalCase,工具函数使用 camelCase

## 架构要点
- 页面路由在 `app/` 目录(App Router)
- 共享组件在 `components/`
- API 路由在 `app/api/`
- 数据库 schema 在 `prisma/schema.prisma`

## 禁止触碰的文件
- `prisma/migrations/` 下的迁移文件
- `public/generated/` 下的构建产物
- `.env` 文件
方式 B:使用 /init-deep 生成
/init-deep

这个命令会扫描你的项目,就地改进已有的 AGENTS.md(不会覆盖),并在子目录中生成层级化的上下文文件。生成后建议手动审查并补充项目特有的约定。

方式 C:在 opencode.json 中引用已有文档
{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/architecture.md",
    ".cursor/rules/*.md"      // 兼容 Cursor 规则文件
  ]
}

3.3 第三步:开始协作

在现有项目中,你有多种交互方式:

日常开发对话

这个组件有个 bug,点击按钮后状态没有更新,帮我排查。
帮我在 src/api/ 下新增一个用户管理模块,包含 CRUD 接口。

使用 Prometheus 战略规划(面对复杂需求时):

/start-work

Prometheus 会像一个真实的主管那样采访你——主动深挖需求、指出模糊地带,在改动任何代码前产出经过严密论证的执行计划。

全自动模式

ulw
# 或
ultrawork

当你有明确的、可量化的大任务时(如"重构所有 API 错误处理"、“升级到 Next.js 15”)。

3.4 现有项目快速接入清单

  • 进入项目目录,启动 opencode
  • 如果项目没有 AGENTS.md,运行 /init-deep 生成
  • 如果项目已有 AGENTS.md,运行 /init-deep 就地增强
  • 检查 opencode.json 配置是否需要更新
  • .opencode/oh-my-openagent.jsonc 中添加项目级代理覆盖(可选)
  • 日常小任务:直接对话 → Sisyphus 自动处理
  • 复杂大任务:/start-work → Prometheus 战略规划 → ulw 全自动执行

3.5 已有 AGENTS.md 示例

以下是一个实际项目中 AGENTS.md 的结构参考(银行审批系统):

# NewProductApproval - 新产品审批系统

## 技术栈
- 后端:Java 8、Spring Boot 2.7.x、MyBatis-Plus
- 数据库:MySQL
- 缓存:Redis

## DDD 四层架构
- adapter/   - 适配层(Controller、DTO、事件监听)
- application/ - 应用层(ApplicationService、事件发布)
- domain/    - 领域层(Entity、ValueObject、DomainService、Repository 接口)
- infrastructure/ - 基础设施层(Repository 实现、外部 API 调用)

## 构建命令
- 编译:`mvn clean compile`
- 测试:`mvn test -pl backend`
- 启动:`mvn spring-boot:run -pl backend`

## 重要约定
- 所有 API 返回统一包装类 R<T>
- 异常统一使用 GlobalExceptionHandler 处理
- 领域层禁止引入 Spring 依赖
- 数据库操作必须通过 Repository 接口

四、深度研究指南

场景:需要深入分析代码库、调研技术方案、排查复杂 Bug、设计架构。

4.1 深度研究的核心能力

OpenCode + OhMyOpenCode 提供了一套完整的深度研究工具链,不仅仅是搜索代码,而是有策略地发现、分析、综合信息

能力矩阵
能力 负责代理 触发方式 用途
代码库探索 Explore 自动 / 对话触发 高速代码搜索、模式发现
外部文档搜索 Librarian 提到外部库时自动触发 远程仓库源码、官方文档、网页搜索
架构分析 Oracle 对话触发 / 自动调度 复杂架构设计、硬核调试
需求分析 Metis /start-work 内部触发 捕获遗漏需求、识别歧义点
计划审查 Momus 计划生成后自动触发 审核计划的清晰度和可验证性
深度自主调研 Hephaestus 自动调度(deep 类别) 目标导向的自主研究和实现

4.2 代码库深度探索

当你需要对项目进行深度分析时,系统会自动并行启动 Explore 代理:

触发场景

  • “这个项目的认证流程是怎么实现的?”
  • “找出所有调用 PaymentService 的地方”
  • “有哪些地方使用了过时的 API?”

后台并行机制

Sisyphus 会同时发射多个 Explore 代理并行搜索不同维度:

Explore #1: 搜索认证中间件实现
Explore #2: 搜索 Token 生成和验证逻辑
Explore #3: 搜索登录/注册处理器
Explore #4: 搜索权限控制模式

所有代理异步运行,结果汇总后再由 Sisyphus 综合输出。

4.3 外部技术调研

当你的问题涉及外部库、框架或 API 时,Librarian 代理会自动介入:

触发场景

  • “Next.js 15 的 Server Actions 最佳实践是什么?”
  • “Prisma 的 N+1 查询问题怎么解决?”
  • “看看 Ant Design 的 Table 组件怎么实现虚拟滚动”

Librarian 的搜索能力

工具 用途 示例
GitHub CLI 搜索开源仓库代码 查找实际项目中的用法
Context7 官方文档直连 查询最新 API 文档
Exa 网络搜索 全网搜索 查找最佳实践文章
Grep.app GitHub 代码搜索 百万级仓库代码匹配

最佳实践

# 不要这样问(太模糊)
"React 怎么用?"

# 应该这样问(具体、有上下文)
"在我的 Next.js 项目中,如何在 Server Component 中调用 Prisma
进行分页查询?需要处理排序和搜索过滤。"

4.4 复杂架构分析

当遇到硬核问题需要高 IQ 推理时:

手动调用 Oracle

# 在 TUI 中
@oracle 分析一下当前项目的数据库分库分表方案是否合理,
考虑到我们的业务增长预期是 QPS 从 1000 到 10000。

自动调度
Sisyphus 会在以下情况自动调度 Oracle:

  • 自身实施了 2+ 次修改仍未修复 Bug
  • 遇到了不熟悉的代码模式
  • 需要做出跨多个系统的架构决策

4.5 战略规划研究(/start-work)

对于不确定性高的复杂任务:

/start-work

这个命令会启动完整的规划流水线:

  1. Prometheus 进入采访模式,主动向你提问:

    • “这个功能的主要用户是谁?”
    • “你对性能的要求是什么?QPS 大概多少?”
    • “现有的认证系统需要改动吗?”
    • “有没有我不能修改的文件或模块?”
  2. Metis 分析需求,捕获 Prometheus 可能遗漏的点

  3. 生成详细执行计划后,Momus 审查计划的可行性和完整性

  4. 确认计划后,执行 ulw 全自动实现

4.6 研究深度层级

根据你的需求选择合适的研究深度:

层级 适用场景 命令/方式 关键代理
L1 快速搜索 找个文件、看个函数 直接对话 Explore
L2 模式分析 理解某个功能的实现方式 对话 + 跟进提问 Explore × 2-3
L3 技术调研 评估技术选型、查找最佳实践 对话中涉及外部库 Librarian + Explore
L4 架构审查 审视现有设计的合理性 @oracle 或自动 Oracle
L5 战略规划 大型功能、系统重构 /start-work Prometheus + Metis + Momus
L6 全自主研究 无人干预的端到端研究 ulw 全部代理军团

4.7 深度研究实战示例

示例 1:排查性能瓶颈
# 用户输入
"首页加载很慢,帮我排查一下性能问题。"

Sisyphus 的研究流程

  1. 并行启动 Explore 代理:

    • 搜索数据请求逻辑(getServerSideProps / Server Components)
    • 搜索大型依赖导入
    • 搜索未优化的图片/资源加载
  2. 启动 Librarian 代理:

    • 查找 Next.js 性能优化文档
    • 查找 Lighthouse 优化最佳实践
  3. 汇总分析 → 输出:

    • 列出性能问题清单(按严重程度排序)
    • 给出每个问题的修复方案
    • 估算优化效果
示例 2:技术选型研究
# 用户输入
"项目要用 WebSocket 做实时通知,帮我调研一下技术方案。"

Sisyphus 的研究流程

  1. Librarian 并行搜索:

    • Socket.IO vs WS vs uWebSockets 对比
    • Next.js WebSocket 集成方案
    • 生产规模 WebSocket 最佳实践
  2. Explore 代理分析项目现状:

    • 已有的消息通知模块
    • 现有的部署架构(是否支持 WebSocket)
  3. Oracle 参与分析:

    • 评估各方案与项目架构的匹配度
    • 输出:推荐方案 + 理由 + 潜在风险

4.8 深度研究注意事项

  • 不要过度研究:当信息开始重复出现时,就是该停止搜索的信号
  • 并行优先:Sisyphus 默认并行启动 5+ 个代理,这是正常行为,不是 Bug
  • 等待结果:代理返回前,Sisyphus 不会输出最终结论——耐心等待
  • 上下文管理:每次对话积累的上下文会被自动压缩,不需要手动清空

五、核心概念速查

5.1 自律军团(Discipline Agents)

代理 角色 类别 适合的模型 说明
Sisyphus 主编排器 核心 Claude / Kimi / GLM 制定计划、委派任务、推动完成
Hephaestus 实现者 核心 GPT-5.4 目标导向的自主实现
Oracle 架构顾问 核心 高 IQ 模型 只读,处理架构和调试
Librarian 文档研究者 支持 快速模型 文档和开源代码搜索
Explore 代码搜索 支持 快速模型 高速代码库 grep
Prometheus 战略规划师 规划 Claude / Kimi / GLM 采访式需求分析
Metis 差距分析 规划 高 IQ 模型 捕获遗漏需求
Momus 审查者 规划 高 IQ 模型 审核计划质量
Atlas 执行指挥 编排 高 IQ 模型 分配任务给子代理
Sisyphus Junior 轻量执行 编排 快速模型 轻量任务执行
Multimodal Looker 视觉分析 支持 Gemini 截图和视觉分析

5.2 类别系统(Category)

代理委派时不直接指定模型,而是选择类别。系统自动将类别映射到最优模型:

类别 适用领域 典型模型
visual-engineering 前端、UI/UX、设计 Gemini Pro
ultrabrain 复杂硬核逻辑、算法、架构 GPT-5.4 Codex (xhigh)
deep 深度自主调研与实现 GPT-5.4 Codex (medium)
artistry 创意编程、非传统方案 Gemini Pro
quick 单文件修改、修错字 Claude Haiku / GPT Mini
unspecified-low 低功耗通用任务 Claude Sonnet
unspecified-high 高功耗通用任务 GPT-5.4
writing 文档、技术写作 Gemini Flash

5.3 内置技能(Skills)

技能 用途 触发方式
playwright 浏览器自动化(测试、截图、抓取) 浏览器相关任务
dev-browser 持久化浏览器(表单填写、导航) 网页交互
frontend-ui-ux 设计优先的 UI 实现 前端/UI 任务
git-master 原子级提交、rebase、历史搜索 git 操作
review-work 实施后审查(5 代理并行) “review my work”
ai-slop-remover 移除 AI 生成的冗余代码 代码清理
ui-ux-pro-max UI/UX 设计数据库(自定义) 设计任务

自定义技能存放在 .opencode/skills/*/SKILL.md~/.config/opencode/skills/*/SKILL.md

5.4 配置优先级总览

优先级 来源 说明
1(低) .well-known/opencode 组织级远程默认配置
2 ~/.config/opencode/opencode.json 用户全局偏好
3 OPENCODE_CONFIG 环境变量 自定义配置路径
4 opencode.json(项目根目录) 项目级设置
5 .opencode/ 目录 代理、命令、插件、技能
6 OPENCODE_CONFIG_CONTENT 环境变量 运行时内联配置
7(高) macOS MDM / 系统管理 企业控制

六、常用命令与快捷键

6.1 TUI 命令

命令 用途
ultrawork / ulw 一键全自动开发模式
/start-work Prometheus 战略规划模式
/init-deep 生成层级 AGENTS.md
/ulw-loop Ralph 自我循环(不停机直到完成)
/refactor 智能重构(LSP + AST 感知)
/review 代码审查
/handoff 生成会话上下文,方便切换设备继续
/connect 管理 AI Provider 凭据
@oracle 手动调用 Oracle 代理
Tab 键 切换代理模式

6.2 CLI 命令

# 启动 TUI
opencode

# 直接执行一条指令
opencode run "修复 src/auth.ts 的类型错误"

# 初始化项目
opencode init

# 启动 Web 服务
opencode web

# 管理会话
opencode session list
opencode session resume <id>

# 创建代理
opencode agent create

# 查看统计
opencode stats

6.3 关键环境变量

变量 用途
ANTHROPIC_API_KEY Anthropic Claude API 密钥
OPENAI_API_KEY OpenAI API 密钥
DEEPSEEK_API_KEY DeepSeek API 密钥
OPENCODE_CONFIG 自定义配置文件路径
OMO_SEND_ANONYMOUS_TELEMETRY=0 禁用匿名遥测
OMO_DISABLE_POSTHOG=1 禁用 PostHog 追踪

七、进阶配置

7.1 自定义代理

.opencode/agents/code-reviewer.md 中定义:

---
description: 代码审查专家,检查代码质量和最佳实践
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

你是代码审查专家。审查时关注:
- 代码质量和最佳实践
- 潜在 Bug 和边界情况
- 性能影响
- 安全考虑

7.2 OhMyOpenCode 配置详解

项目级 .opencode/oh-my-openagent.jsonc

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",

  // 覆盖特定代理的模型
  "agents": {
    "sisyphus": {
      "model": "deepseek/deepseek-v4-pro"
    },
    "oracle": {
      "model": "openai/gpt-5.4",
      "variant": "high"
    }
  },

  // 覆盖类别模型映射
  "categories": {
    "quick": { "model": "deepseek/deepseek-v4-flash" },
    "deep": { "model": "deepseek/deepseek-v4-pro" },
    "visual-engineering": { "model": "google/gemini-3.1-pro", "variant": "high" }
  },

  // 禁用不用的代理
  "disabled_agents": ["momus"],

  // 禁用不用的 MCP
  "disabled_mcps": ["grep_app"],

  // 禁用不用的技能
  "disabled_skills": ["ai-slop-remover"]
}

7.3 模型回退策略

{
  "model_fallback": {
    "enabled": true,
    "rules": [
      {
        "provider": "deepseek",
        "fallback": "minimax/minimax-m2.7"
      }
    ]
  }
}

7.4 添加自定义技能

技能文件存放在 .opencode/skills/<skill-name>/SKILL.md

---
name: my-custom-skill
description: 项目特有的代码生成规则
---

# My Custom Skill

## 适用场景
当用户要求生成数据库迁移文件时使用。

## 规则
1. 所有迁移文件必须包含 up 和 down 方法
2. 表名使用复数形式
3. 外键必须显式命名

## 命令约束
- 迁移只能通过 `npx prisma migrate dev` 执行
- 禁止手动编辑 `prisma/migrations/` 下的文件

7.5 项目级目录结构最佳实践

my-project/
├── opencode.json                        # 项目级 OpenCode 配置
├── AGENTS.md                            # 全局项目上下文
├── .opencode/
│   ├── oh-my-openagent.jsonc            # 项目级 OhMyOpenCode 配置
│   ├── agents/                          # 自定义代理定义
│   │   └── code-reviewer.md
│   ├── commands/                        # 自定义斜杠命令
│   │   └── deploy.md
│   ├── skills/                          # 自定义技能
│   │   └── my-custom-skill/
│   │       └── SKILL.md
│   └── themes/                          # 自定义 UI 主题
├── src/
│   ├── AGENTS.md                        # src 级上下文
│   └── components/
│       └── AGENTS.md                    # 组件级详细说明
├── backend/
│   └── AGENTS.md                        # 后端上下文
└── docs/
    └── coding-style.md                  # 被 opencode.json 引用的规则文件

附录

A. 官方资源

  • OpenCode 官方文档:https://opencode.ai/docs/
  • OpenCode 配置文档:https://opencode.ai/docs/config/
  • OpenCode GitHub:https://github.com/anomalyco/opencode
  • OhMyOpenAgent GitHub:https://github.com/code-yeongyu/oh-my-openagent
  • OhMyOpenAgent 官网:https://ohmyopenagent.com/
  • AGENTS.md 规范:https://opencode.ai/docs/rules/
  • Discord 社区:https://discord.gg/PUwSMR9XNk
  • DeepWiki:https://deepwiki.com/code-yeongyu/oh-my-openagent

B. 名词对照表

英文 中文 说明
OpenCode OpenCode AI 编程助手框架
OhMyOpenCode / OhMyOpenAgent OhMyOpenCode 多代理编排插件
Discipline Agents 自律军团 整套专业代理的统称
Sisyphus 西西弗斯 主编排器代理
Hephaestus 赫菲斯托斯 代码实现代理
Oracle 先知 架构与调试顾问
Prometheus 普罗米修斯 战略规划师
Metis 墨提斯 需求差距分析
Momus 摩墨斯 计划质量审查
ultrawork / ulw 全自动模式 一键启动所有代理
IntentGate 意图门 分析用户真实意图的机制
Ralph Loop Ralph 循环 自我引用循环直到完成
Category 类别 任务领域到模型的路由系统
Skill 技能 领域专业知识包
AGENTS.md 代理上下文文件 项目级 AI 行为指令
Hashline Edit 哈希行编辑 基于内容哈希的精确编辑
Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐