返回
oh-my-claudecode 教程系列 开发工具

oh-my-claudecode 教程 1：入门与安装配置完全指南

本文详细介绍 oh-my-claudecode 的安装配置方法，包括 Plugin Marketplace 安装、手动安装、tmux 配置、验证步骤和常见问题排查。

教程概述

本教程是 oh-my-claudecode 系列的第一篇，将带你完成从零开始的安装配置过程。只需三个命令，即可让 Claude Code 拥有多代理协作能力。

你将学到

  • ✅ oh-my-claudecode 的核心工作原理
  • ✅ 在 Claude Code 中安装和配置 OMC
  • ✅ 验证安装是否成功
  • ✅ 常见问题排查

oh-my-claudecode 是什么？

oh-my-claudecode (OMC) 是一个多代理编排层，为 Claude Code 提供：

  • 32 个专业代理 - 架构师、设计师、测试工程师等各司其职
  • Team Mode - 多代理协调，任务自动分发与整合
  • 智能路由 - Haiku/Sonnet/Opus 按任务复杂度自动选择
  • 跨 AI 协作 - Codex/Gemini/Claude 三模型合成

核心价值

flowchart LR
    A[复杂任务] --> B[OMC 编排层]
    B --> C[专业代理协作]
    C --> D[高质量交付]

    B --> E[自动并行]
    B --> F[智能验证]
    B --> G[成本优化]

    style B fill:#e1f5ff
    style C fill:#e8f5e9

工作流程示意

flowchart TD
    A[用户: autopilot: build a REST API] --> B{OMC 解析}
    B --> C[team-plan: 规划阶段]
    C --> D[team-prd: 需求文档]
    D --> E[team-exec: 并行执行]
    E --> F[team-verify: 验证确认]
    F --> G{通过？}
    G -->|否| H[team-fix: 修复]
    H --> E
    G -->|是| I[完成]

    style B fill:#e1f5ff
    style C fill:#e3f2fd
    style E fill:#e8f5e9
    style F fill:#fff3e0

安装前准备

系统要求

要求 说明
Claude Code CLI 已安装并正常使用
Claude 订阅 Max/Pro 订阅或 Anthropic API key
Git 基本操作知识
tmux 用于 Team 模式（推荐）

tmux 安装

tmux 是 Team 模式的关键依赖，用于管理多终端会话。

平台 安装命令
macOS brew install tmux
Ubuntu/Debian sudo apt install tmux
Fedora sudo dnf install tmux
Arch sudo pacman -S tmux
Windows (WSL) sudo apt install tmux
Windows (原生) winget install psmux

Windows 用户注意：psmux 提供原生 tmux 兼容实现，无需 WSL。

快速安装（三步法）

步骤 1：添加 Marketplace

/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode

步骤 2：安装插件

/plugin install oh-my-claudecode

步骤 3：初始化配置

/setup
/omc-setup

完成！ 现在你可以使用：

autopilot: build a REST API for managing tasks

手动安装（备选方案）

如果 Marketplace 不可用，可以手动安装：

# 克隆仓库
git clone https://github.com/Yeachan-Heo/oh-my-claudecode.git ~/.claude/plugins/oh-my-claudecode

# 在 Claude Code 中加载
/plugin load ~/.claude/plugins/oh-my-claudecode

通过 npm 安装 CLI 工具

npm i -g oh-my-claude-sisyphus@latest

注意：npm 包名是 oh-my-claude-sisyphus，但项目品牌名是 oh-my-claudecode。

初始化配置详解

启用 Claude Code Native Teams

编辑 ~/.claude/settings.json：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

这是启用 Team 模式的关键配置。

运行 Setup 命令

/setup

这个命令会：

  1. 检测当前环境
  2. 配置必要的环境变量
  3. 生成默认配置文件
/omc-setup

这个命令会：

  1. 安装 OMC 代理定义
  2. 配置 Skills 系统
  3. 设置通知集成（可选）

验证安装成功

测试 1：检查 Team 模式

/team 2:executor "create a hello world function"

期望行为：

  • 系统创建团队
  • 分配任务给 worker
  • 完成后报告结果

测试 2：测试 Magic Keywords

ralph: list all files in current directory

期望行为：

  • 触发 Ralph 持久模式
  • 执行并验证任务
  • 报告完成状态

测试 3：测试 Deep-Interview

deep-interview "I want to build a task management app"

期望行为：

  • AI 开始苏格拉底式提问
  • 澄清你的需求
  • 生成 PRD 文档

验证检查清单

## 安装验证清单

- [ ] `/plugin list` 显示 oh-my-claudecode
- [ ] `/team 1:executor "echo hello"` 正常执行
- [ ] `autopilot:` 关键词触发自动执行
- [ ] tmux 会话可以正常创建
- [ ] HUD 状态栏正常显示

常见问题排查

问题 1：插件加载失败

症状：/plugin install 报错

解决方案：

# 清除插件缓存
rm -rf ~/.claude/plugins/oh-my-claudecode

# 重新安装
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode

问题 2：Team 模式不工作

症状：/team 命令无响应或报错

排查步骤：

  1. 检查环境变量：

    echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

    应输出 1

  2. 检查 tmux 是否安装：

    tmux -V

  3. 运行诊断命令：

    /omc-doctor

问题 3：tmux 配置问题

症状：无法创建 tmux 会话

解决方案：

# 检查 tmux 服务状态
tmux list-sessions

# 清理残留会话
tmux kill-server

# 重新测试
tmux new -s test

问题 4：Magic Keywords 不触发

症状：输入 autopilot: 但无反应

解决方案：

  1. 确认插件已加载：

    /plugin list

  2. 尝试显式调用：

    /oh-my-claudecode:autopilot "your task"

  3. 检查 CLAUDE.md 是否包含 OMC 指令

问题 5：权限问题

症状：无法写入配置文件

解决方案：

# 修复权限
chmod -R 755 ~/.claude/
chmod -R 755 ~/.omc/

更新 OMC

通过 Marketplace 更新

/plugin marketplace update omc
/omc-setup

通过 npm 更新 CLI

npm i -g oh-my-claude-sisyphus@latest

运行诊断

更新后如有问题：

/omc-doctor

这会自动检测并修复常见配置问题。

最佳实践建议

1. 渐进式学习

第 1 天：安装配置 + Team Mode 基础
第 2 天：尝试 autopilot 和 ralph 模式
第 3 天：配置 CLI Workers (Codex/Gemini)
第 4 天：创建自定义 Skills

2. 环境变量管理

创建 ~/.claude/env 文件管理配置：

# OMC 配置
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
OMC_TEAM_SCALING_ENABLED=1

# 可选：通知配置
OMC_OPENCLAW=0

3. 配置备份

定期备份你的配置：

# 备份关键配置
cp ~/.claude/settings.json ~/.claude/settings.json.backup
cp -r ~/.omc ~/.omc.backup

下一步

安装完成后，继续学习：

参考资源

📚 完整教程系列导航

你正在阅读本系列的 教程 1，以下是完整目录：

  1. 系列介绍：让 Claude Code 拥有多代理协作能力
  2. 教程 1：入门与安装配置（当前）
  3. 教程 2：Team Mode 多代理协作核心编排模式
  4. 教程 3：tmux CLI Workers 多 AI 协作
  5. 教程 4：编排模式详解 - Autopilot/Ralph/Ultrawork/CCG
  6. 教程 5：Magic Keywords 与 Deep-Interview 自然语言驱动
  7. 教程 6：32 个专业代理与智能路由
  8. 教程 7：Skills 系统 - 自定义技能与自动学习
  9. 教程 8：验证与调试 - Ralph 循环与 Trace 系统
  10. 教程 9：通知集成与 HUD 状态栏
  11. 教程 10：实战案例 - 从需求到上线的完整工作流

遇到问题？ 在评论区留言或前往 GitHub Issues 提问！

系列导航：