OpenCode 入门指南#

7.1.1 简介#

oh-my-openagent（简称 OMO，前身为 oh-my-opencode）是 OpenCode 生态中最受欢迎的多代理插件。它将 OpenCode 从单一 AI 助手升级为一个高度自治的 AI 团队，通过 Sisyphus 主协调代理调度多个专业子代理并行工作，能够将复杂的软件工程任务自动化——几乎做到”交代任务后去喝杯咖啡，回来就完成了”。

7.1.2 核心功能#

执行模式#

Ultra Work 模式（ulw）

最核心的执行模式。输入 ulw + 任务描述，所有代理同时激活，自动规划、并行执行、自我纠错，持续运行直到任务完成，无需手动干预。

Ralph Loop（/ulw-loop）

自引用执行循环，与 Ultra Work 配合使用。代理会反复迭代，直到任务完全达成目标——适合需要多轮修改和验证的复杂任务。

深度初始化（/init-deep）

在项目目录树中自动生成分层的 AGENTS.md 文件，为每个代理提供分层、有作用域的上下文，既节省 Token 又提升代理对项目的理解能力。

规划模式（/start-work）

由 Prometheus 代理驱动的面试式规划流程。在编写任何代码之前，它会像真正的工程师一样向你提问、澄清需求、确定范围，然后生成详细的执行计划。

质量保障机制#

IntentGate（意图门控）

在分类或执行操作前，先分析用户的真实意图，防止对提示词的字面误解。

Hashline（哈希锚定编辑）

代理读取的每一行都会标记内容哈希（如 11#VK|），编辑时引用这些标记，哈希不匹配的修改会被直接拒绝，从源头防止文件损坏。据官方报告，编辑成功率从 6.7% 提升到 68.3%。

Todo Enforcer（任务强制器）

自动将偏离主线的代理拉回正轨，确保当前任务不会被遗忘或搁置。

Comment Checker（注释检查器）

阻止低质量的 AI 生成注释，确保代码注释的专业性和可读性。

工具链集成#

LSP 与 AST-Grep

• LSP 工具：lsp_rename、lsp_goto_definition、lsp_find_references、lsp_diagnostics
• AST-Grep：跨 25 种语言的模式感知搜索与重写

内置 MCP 服务

• Exa — 网页搜索
• Context7 — 官方文档查询
• Grep.app — GitHub 代码搜索

Skill-Embedded MCPs（技能内嵌 MCP）

每个技能可携带自己的 MCP 服务器，按需启动、用完即销毁，不会占用上下文窗口。内置技能包括 playwright（浏览器自动化）、git-master（原子提交 / Rebase）、frontend-ui-ux（设计优先的 UI 开发）等。

Tmux 集成

完整的交互式终端支持，可在代理会话中运行 REPL、调试器和 TUI 应用程序。

智能模型路由

根据任务类型自动选择最合适的模型（如 Claude 做规划、GPT Codex 写代码），按类别而非具体模型分配，在节省 Token 的同时保持高效。

Claude Code 完全兼容

现有的所有 Hooks、Commands、Skills、MCPs 和插件均可直接使用，无需任何改动。

7.1.3 安装#

进入 OpenCode 终端后，直接发送以下内容让 LLM 自动完成安装：

1
Install and configure oh-my-opencode by following the instructions here:
2
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

安装成功后，重新进入 OpenCode，默认模式变为 Sisyphus (Ultraworker) 即表示安装成功。

7.1.4 配置模型#

oh-my-openagent 默认配置的模型为 GPT、Claude、Gemini 等官方模型。由于我们使用的是 CPA 提供商，需要手动修改配置文件。

编辑 oh-my-opencode 配置文件：

macOS：

1
code ~/.config/opencode/oh-my-opencode.json

Windows（WSL 环境下）：

1
code ~/.config/opencode/oh-my-opencode.json

也可使用 nano 或 vim 替代 code，编辑方式参见上方第 4 节的说明。

将内容替换为：

1
{
2
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/dev/assets/oh-my-opencode.schema.json",
3
  "agents": {
4
    "sisyphus": {
5
      "model": "cpa/gpt-latest",
6
      "variant": "high"
7
    },
8
    "hephaestus": {
9
      "model": "cpa/gpt-codex-latest",
10
      "variant": "xhigh"
11
    },
12
    "oracle": {
13
      "model": "cpa/gpt-latest",
14
      "variant": "xhigh"
15
    },
16
    "librarian": {
17
      "model": "cpa/gpt-codex-latest",
18
      "variant": "high"
19
    },
20
    "explore": {
21
      "model": "cpa/gpt-codex-latest",
22
      "variant": "high"
23
    },
24
    "multimodal-looker": {
25
      "model": "cpa/gpt-latest",
26
      "variant": "high"
27
    },
28
    "prometheus": {
29
      "model": "cpa/gpt-latest",
30
      "variant": "xhigh"
31
    },
32
    "metis": {
33
      "model": "cpa/gpt-latest",
34
      "variant": "xhigh"
35
    },
36
    "momus": {
37
      "model": "cpa/gpt-latest",
38
      "variant": "xhigh"
39
    },
40
    "atlas": {
41
      "model": "cpa/gpt-latest",
42
      "variant": "high"
43
    }
44
  },
45
  "categories": {
46
    "visual-engineering": {
47
      "model": "cpa/gpt-latest",
48
      "variant": "high"
49
    },
50
    "ultrabrain": {
51
      "model": "cpa/gpt-latest",
52
      "variant": "xhigh"
53
    },
54
    "deep": {
55
      "model": "cpa/gpt-codex-latest",
56
      "variant": "xhigh"
57
    },
58
    "artistry": {
59
      "model": "cpa/gpt-latest",
60
      "variant": "high"
61
    },
62
    "quick": {
63
      "model": "cpa/gpt-codex-latest",
64
      "variant": "high"
65
    },
66
    "unspecified-low": {
67
      "model": "cpa/gpt-codex-latest",
68
      "variant": "high"
69
    },
70
    "unspecified-high": {
71
      "model": "cpa/gpt-latest",
72
      "variant": "high"
73
    },
74
    "writing": {
75
      "model": "cpa/gpt-latest",
76
      "variant": "high"
77
    }
78
  }
79
}

说明： 以上配置根据各代理和分类的职责特点，在两个可用模型之间做了差异化分配：需要深度推理的角色（规划、架构、审查）使用 gpt-latest + xhigh；需要深度编码的角色使用 gpt-codex-latest + xhigh；轻量搜索和快速任务使用 gpt-codex-latest + high（成本更低）；通用协调和执行角色使用 gpt-latest + high。

7.1.5 Agents 与 Categories 参考#

推荐 MCP 服务#

1. Context7 — 官方文档查询

实时查询任意编程库的最新文档和代码示例，避免 AI 使用过时的 API。

1
{
2
  "mcp": {
3
    "context7": {
4
      "type": "remote",
5
      "url": "https://mcp.context7.com/mcp",
6
    },
7
  },
8
}

2. Grep.app — GitHub 代码搜索

搜索 GitHub 上的公开代码，快速找到真实项目中的用法和参考实现。

1
{
2
  "mcp": {
3
    "gh_grep": {
4
      "type": "remote",
5
      "url": "https://mcp.grep.app",
6
    },
7
  },
8
}

3. Exa — 网页搜索

让 AI 具备实时联网搜索能力，获取最新资讯和技术文章。需要 Exa API Key。

1
{
2
  "mcp": {
3
    "exa": {
4
      "type": "local",
5
      "command": ["npx", "-y", "exa-mcp-server"],
6
      "environment": {
7
        "EXA_API_KEY": "你的 Exa API Key"
8
      },
9
    },
10
  },
11
}

组合配置示例#

以上服务可同时启用，合并写入配置文件的 mcp 字段中：

1
{
2
  "$schema": "https://opencode.ai/config.json",
3
  // ... 其他配置（provider 等）
4
  "mcp": {
5
    "context7": {
6
      "type": "remote",
7
      "url": "https://mcp.context7.com/mcp",
8
    },
9
    "gh_grep": {
10
      "type": "remote",
11
      "url": "https://mcp.grep.app",
12
    },
13
  },
14
}

常用管理命令#

提示： MCP 服务会增加上下文消耗，建议只启用当前需要的服务，避免因工具过多导致 Token 超限。

ui-ux-pro-max — AI 驱动的 UI/UX 设计智能#

适用范围：仅限前端项目。 该技能专为前端 UI/UX 开发设计，不适用于后端、CLI 工具、数据处理等非前端场景。如果你的项目不涉及界面开发，无需安装此技能。

ui-ux-pro-max 是一款面向前端开发者的设计智能技能。当你向 AI 描述 UI 需求时，它会自动生成完整的设计系统（配色、字体、布局、风格、反模式检查），然后基于该系统输出高质量代码。

核心能力

• 设计系统生成器：用自然语言描述项目，自动输出完整设计系统——布局模式、视觉风格、配色方案、字体组合、特效建议及反模式检查清单
• 161 条行业推理规则：覆盖 SaaS、金融科技、电商、医疗、餐饮、游戏、Web3 等细分领域，每条规则包含推荐布局、风格优先级、色彩基调和排版建议
• 67 种 UI 风格：Glassmorphism、Neumorphism、Brutalism、Bento Grid、Liquid Glass、Cyberpunk UI、Aurora UI 等主流与前沿风格
• 57 组精选字体搭配：附带 Google Fonts 链接，开箱即用
• 161 套配色方案：按产品类型匹配，确保行业适配性
• 25 种图表类型：适用于仪表盘和数据分析场景

支持的技术栈

安装

前置依赖：Python 3.x

1
# 安装 CLI
2
npm install -g uipro-cli
3

4
# 进入项目目录后初始化（指定 opencode 作为 AI 工具）
5
cd /path/to/your/project
6
uipro init --ai opencode

使用方式

安装后无需额外操作，当你在 OpenCode 中发起 UI/UX 相关请求时（如 build、design、create、implement、review、fix、improve），技能会自动激活并执行以下流程：

1. 分析你的需求，匹配产品类型和行业规则
2. 自动生成完整设计系统（配色、字体、布局、风格）
3. 基于设计系统生成代码，确保色彩、间距、最佳实践一致
4. 交付前自动检查常见反模式

提示： 在提示词中注明技术栈（如”用 Next.js + shadcn/ui”），可获得更精准的代码输出。未指定时默认使用 HTML + Tailwind CSS。