第三章：安装、订阅与环境配置

本章把 oh-my-openagent（OmO）从零跑起来的全过程一步步走一遍：先理解订阅与提供商之间的关系，再用交互式安装器把插件装上，最后配置 Auth、做 Doctor 检查并跑出第一个 ultrawork。

重要前提：OmO 是一个 OpenCode 插件，它不能脱离 OpenCode 单独运行。如果你还没装 OpenCode，先去 opencode.ai/docs 看一眼。

---

3.1 准备工作

3.1.1 系统与运行时

OmO 的 CLI 自带各平台的独立可执行文件，安装之后不依赖 Bun / Node.js 运行时。但安装时仍然会通过 bunx 调起，所以本机至少要能调用 Bun。

支持平台：

• macOS：ARM64、x64
• Linux：x64、ARM64、Alpine（musl）
• Windows：x64

最低 OpenCode 版本：1.0.150 或更高。

3.1.2 提前盘点你的"订阅资产"

OmO 的安装流程会问你一连串"你有没有 X 订阅"的问题，答错或漏答会直接影响后面的模型分配。建议提前对照下面这张表，把自己有的订阅勾出来：

订阅	CLI 标志	说明
Claude Pro / Max	--claude=yes 或 --claude=max20	主力 Sisyphus / Prometheus / Atlas 之一
ChatGPT Plus / OpenAI	--openai=yes	让 Hephaestus、Oracle 跑在 GPT-5.4
Gemini（Antigravity）	--gemini=yes	提供 Gemini 3.x 系列，主打前端/视觉
GitHub Copilot	--copilot=yes	兜底回退（含 Claude / GPT / Grok 镜像）
OpenCode Zen	--opencode-zen=yes	提供 opencode/ 前缀模型
Z.ai Coding Plan	--zai-coding-plan=yes	提供 glm-5 / glm-4.6v
OpenCode Go ($10/月)	--opencode-go=yes	提供 GLM-5 / Kimi K2.5 / MiniMax M2.7
Kimi for Coding	--kimi-for-coding=yes	Sisyphus 的关键 Claude-like 备胎
Vercel AI Gateway	--vercel-ai-gateway=yes	通用网关

提供商选择是按 Agent 维度的，OmO 不存在"全局优先级"，每个 Agent 都跑自己独立的 fallback 链。所以多勾一个订阅都意味着多一条逃生通道。

⚠️ 强提醒：如果 没有 Claude 订阅，Sisyphus 智能体将很可能不在最佳状态。Sisyphus 的提示词是按 Claude Opus 4.7 的指令跟随风格调过的，强行换成普通 GPT 模型效果会断崖式下跌。退而求其次的"Claude-like"是 Kimi K2.5 / GLM 5。

3.1.3 选一种工作方式：让 Agent 装，还是自己装？

OmO 文档明确推荐"让另一个 LLM Agent（Claude Code、Cursor、Codex 等）来帮你装"，理由是人类配环境太容易敲错字母。

给 Agent 看的指令（推荐）：

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

或者让 Agent 直接 curl 一份安装手册回来：

curl -fsSL https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

文档里特别强调：Agent 必须用 curl 拿这份文件，不要用 WebFetch，因为 WebFetch 会做摘要、丢掉 --openai、subscription、max20 等关键标志。

自己手动装也可以，下面我们就走手动路径，便于你看清每一步实际在干什么。

---

3.2 第 0 步：装 / 校验 OpenCode

if command -v opencode &> /dev/null; then
    echo "OpenCode $(opencode --version) is installed"
else
    echo "OpenCode is not installed. Please install it first."
fi

如果没装：参考 https://opencode.ai/docs。装完务必确认版本 ≥ 1.0.150：

opencode --version

---

3.3 第 1 步：交互式安装 OmO

最快上手：

bunx oh-my-opencode install

它会进入 TUI 一个个问你订阅的问题，按你的回答自动写入 ~/.config/opencode/opencode.json 的 plugin 字段，并配出每个 Agent 默认模型。

非交互模式（适合 Agent 自动执行）：

bunx oh-my-opencode install --no-tui \
    --claude=<yes|no|max20> \
    --gemini=<yes|no> \
    --copilot=<yes|no> \
    [--openai=<yes|no>] \
    [--opencode-go=<yes|no>] \
    [--opencode-zen=<yes|no>] \
    [--zai-coding-plan=<yes|no>] \
    [--kimi-for-coding=<yes|no>] \
    [--vercel-ai-gateway=<yes|no>] \
    [--skip-auth]

几个常见组合的实际命令：

• 全订阅满血流：

  bunx oh-my-opencode install --no-tui \
       --claude=max20 --openai=yes --gemini=yes --copilot=no
  

• 只有 Claude 订阅（最常见）：

  bunx oh-my-opencode install --no-tui \
       --claude=yes --gemini=no --copilot=no
  

• 只有 GitHub Copilot：

  bunx oh-my-opencode install --no-tui \
       --claude=no --gemini=no --copilot=yes
  

• OpenCode Go（极致性价比）：

  bunx oh-my-opencode install --no-tui \
       --claude=no --openai=no --gemini=no --copilot=no --opencode-go=yes
  

• 没有任何订阅（裸跑，效果有限）：

  bunx oh-my-opencode install --no-tui --claude=no --gemini=no --copilot=no
  

3.3.1 安装做了什么

无论交互或非交互，CLI 都会：

1. 把 oh-my-openagent（兼容旧名 oh-my-opencode）注册到 opencode.json 的 plugin 数组；
2. 根据订阅生成每个 Agent 的默认模型映射；
3. 输出后续需要做的 opencode auth login 步骤清单。

如果你看到 Using legacy package name "oh-my-opencode" 警告，就把 opencode.json 里 plugin 数组里的 "oh-my-opencode" 改成 "oh-my-openagent"，旧名仍然能加载，只是会警告。

3.3.2 校验注册结果

opencode --version                            # 确认 ≥ 1.0.150
cat ~/.config/opencode/opencode.json          # 应当包含 "oh-my-openagent"（或 legacy "oh-my-opencode"）
bunx oh-my-opencode doctor                    # Doctor 健康检查

doctor 会跑：

• 系统检查（OS、运行时、二进制完整性）；
• 配置检查（plugin 数组、配置文件路径是否对）；
• 工具检查（LSP、AST-Grep、Tmux 是否可用）；
• 模型解析（每个 Agent 实际会跑在哪个模型上）；
• 兼容性诊断（是否还有 legacy 名字；fallback 是否生效）。

---

3.4 第 2 步：配置 Auth

OmO 装好后只是把"路线图"画好了，模型用的 Auth 必须自己 opencode auth login。下面分提供商展开。

3.4.1 Anthropic（Claude）

opencode auth login
# Provider: Anthropic
# Login method: Claude Pro/Max
# 浏览器完成 OAuth

确认登录成功后，Sisyphus / Prometheus / Atlas 等核心 Agent 就能跑起来了。

3.4.2 Google Gemini（Antigravity OAuth）

Gemini 在 OmO 里推荐使用 opencode-antigravity-auth 这个第三方插件，把它加到 opencode.json：

{
  "plugin": ["oh-my-openagent", "opencode-antigravity-auth@latest"]
}

然后从 opencode-antigravity-auth README 里复制完整的 model 配置合并进 opencode.json。注意：新插件用 variant 系统——antigravity-gemini-3-pro 这种基础模型加 low / high 变体，不再用 -low / -high 后缀。

模型清单

Antigravity 配额：

• google/antigravity-gemini-3-pro（变体：low、high）
• google/antigravity-gemini-3-flash（变体：minimal、low、medium、high）
• google/antigravity-claude-sonnet-4-6（无变体）
• google/antigravity-claude-sonnet-4-6-thinking（变体：low、max）
• google/antigravity-claude-opus-4-5-thinking（变体：low、max）

Gemini CLI 配额：

• google/gemini-2.5-flash、google/gemini-2.5-pro、google/gemini-3-flash-preview、google/gemini-3.1-pro-preview

在 oh-my-openagent.json / oh-my-opencode.json 里覆盖模型

{
  "agents": {
    "multimodal-looker": { "model": "google/antigravity-gemini-3-flash" }
  }
}

Auth

opencode auth login
# Provider: Google
# Login method: OAuth with Google (Antigravity)
# 可以加多个 Google 账号实现多账号轮转

多账号负载均衡：插件支持最多 10 个 Google 账号，命中限流时自动切换。

3.4.3 GitHub Copilot

Copilot 在 OmO 里被定位为全员通用的兜底回退。常见映射：

Agent	Copilot 默认模型
Sisyphus	github-copilot/claude-opus-4.7
Oracle	github-copilot/gpt-5.4
Explore	github-copilot/grok-code-fast-1
Atlas	github-copilot/claude-sonnet-4.6

Librarian 不会装 Copilot 的版本——它依赖 OpenCode Go / OpenCode Zen 的 MiniMax 系列。

3.4.4 Z.ai Coding Plan

主要贡献 glm-5 / glm-4.6v 备胎。如果它是你的主力，那么核心映射会是：

Agent	Z.ai 模型
Sisyphus	zai-coding-plan/glm-5
visual-engineering	zai-coding-plan/glm-5
unspecified-high	zai-coding-plan/glm-5
Multimodal-Looker	zai-coding-plan/glm-4.6v

3.4.5 OpenCode Zen

提供 opencode/ 前缀的统一目录：claude-opus-4-7、gpt-5.4、gpt-5.3-codex、gpt-5-nano、glm-5、big-pickle、minimax-m2.7、minimax-m2.7-highspeed。代表性映射：

Agent	Zen 模型
Sisyphus	opencode/claude-opus-4-7
Oracle	opencode/gpt-5.4
Explore	opencode/minimax-m2.7

安装时回答 "Yes" 给 OpenCode Zen，或者：

bunx oh-my-opencode install --no-tui \
     --claude=no --openai=no --gemini=no --opencode-zen=yes

3.4.6 OpenCode Go / Kimi for Coding / Vercel AI Gateway

按需开启即可。其中 OpenCode Go 性价比极高，10 美元/月即解锁 GLM-5、Kimi K2.5、MiniMax M2.7 三大主力模型，强烈推荐预算敏感型用户。

---

3.5 第 3 步：理解你拿到了什么

装完之后，OmO 会把每个 Agent 配上一条优先级链。这一节回答两个问题：我装出来的是个什么阵容？这套阵容里谁是主角谁是替补？

3.5.1 模型家族划分

Claude-like（指令跟随强，适合长流程）：

模型	提供商	备注
Claude Opus 4.7	anthropic / github-copilot / opencode	总司令首选
Claude Sonnet 4.6	同上	性价比高
Claude Haiku 4.5	anthropic / opencode	快、便宜，适合 quick
Kimi K2.5	kimi-for-coding / opencode-go / opencode / moonshotai 等	极像 Claude，回退链常客
Kimi K2.5 Free	opencode	免费档，限速
GLM 5	zai-coding-plan / opencode	行为类似 Claude，覆盖广
Big Pickle (GLM 4.6)	opencode	免费档兜底

GPT 系列（原则驱动，适合深推理）：

模型	提供商	备注
GPT-5.3-codex	openai / github-copilot / opencode	deep 类别可选
GPT-5.4	同上	Oracle、Hephaestus、Momus 默认
GPT-5.4 Mini	同上	quick 默认
GPT-5-Nano	opencode	极速极便宜

风格不同的模型：

模型	提供商	备注
Gemini 3.1 Pro	google / github-copilot / opencode	前端/视觉强
Gemini 3 Flash	同上	文档检索、轻量任务
MiniMax M2.7 / M2.7 Highspeed	opencode-go / opencode	工具型 Agent 主力

速度优先的模型：

模型	提供商	速度	备注
Grok Code Fast 1	github-copilot / xai	极快	Explore 默认
Claude Haiku 4.5	anthropic / opencode	快	兼顾智商
MiniMax M2.7 Highspeed	opencode-go / opencode	极快	Explore / Librarian fallback
GPT-5.3-codex-spark	openai	极快	但压缩太狠，不推荐给 OmO

3.5.2 每个 Agent 默认拿到了谁

挑核心几个再看一眼（详细见第二章 2.5 节，或源码 src/shared/model-requirements.ts）：

• Sisyphus：claude-opus-4-7(max) → kimi-k2.5 → kimi/k2p5 → kimi-k2.5(其他) → gpt-5.4(medium) → glm-5 → big-pickle
• Hephaestus：gpt-5.4 (medium) only（不回退 Claude）
• Oracle：gpt-5.4 (high) → gemini-3.1-pro (high) → claude-opus-4-7 (max) → glm-5
• Atlas：claude-sonnet-4-6 → kimi-k2.5 → gpt-5.4 (medium) → minimax-m2.7
• Explore / Librarian：grok-code-fast-1 / minimax-m2.7-highspeed → … → gpt-5-nano

重点：没有全局优先级，每个 Agent 自己选。所以装完后跑一次 bunx oh-my-opencode doctor 看看具体每个 Agent 落到了谁身上，最直观。

---

3.6 第 4 步：自定义模型映射

OmO 默认配置已经"开箱满血"，但如果你想覆盖（比如把 Sisyphus 强制换成 Kimi K2.5），可以在插件配置文件里写：

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

  "agents": {
    "sisyphus": {
      "model": "kimi-for-coding/k2p5",
      "ultrawork": { "model": "anthropic/claude-opus-4-7", "variant": "max" }
    },
    "librarian":  { "model": "google/gemini-3-flash" },
    "explore":    { "model": "github-copilot/grok-code-fast-1" },
    "oracle":     { "model": "openai/gpt-5.4", "variant": "high" }
  },

  "categories": {
    "visual-engineering": { "model": "google/gemini-3.1-pro", "variant": "high" },
    "ultrabrain":         { "model": "openai/gpt-5.4", "variant": "xhigh" },
    "deep":               { "model": "openai/gpt-5.4", "variant": "high" },
    "artistry":           { "model": "google/gemini-3.1-pro", "variant": "high" },
    "quick":              { "model": "openai/gpt-5.4-mini" },
    "unspecified-low":    { "model": "openai/gpt-5.4-mini" },
    "unspecified-high":   { "model": "anthropic/claude-opus-4-7", "variant": "max" },
    "writing":            { "model": "anthropic/claude-opus-4-7", "variant": "high" }
  }
}

配置文件位置：

• 全局：~/.config/opencode/oh-my-openagent.json（或老名 oh-my-opencode.json / .jsonc）
• 项目：.opencode/oh-my-openagent.json（或 oh-my-opencode.json）

兼容层会同时识别新旧两种文件名，逐步迁移即可。

3.6.1 安全 vs 危险的覆盖

安全（同家族）：

• Sisyphus：Opus → Sonnet / Kimi K2.5 / GLM 5；
• Prometheus：Opus → GPT-5.4（自动切到 GPT 提示词）；
• Atlas：Kimi K2.5 → Sonnet / GPT-5.4。

危险（不要做）：

• Sisyphus → 老旧 GPT：仍然不合适，只有 GPT-5.4 有专门提示词；
• Hephaestus → Claude：它是为 Codex 设计的，Claude 复刻不出来；
• Explore → Opus：天价浪费 Token；
• Librarian → Opus：同上，文档检索根本不需要。

3.6.2 Fallback 模型对象 / 字符串混合

每个 Agent / Category 都可以写 fallback_models 数组，元素既可以是字符串，也可以是带 variant / temperature / thinking 的对象：

{
  "agents": {
    "sisyphus": {
      "fallback_models": [
        "opencode/glm-5",
        { "model": "openai/gpt-5.4", "variant": "high" },
        { "model": "anthropic/claude-sonnet-4-6", "thinking": { "type": "enabled", "budgetTokens": 64000 } }
      ]
    }
  }
}

runtime-fallback Hook 在主模型 429 / 503 / 缺 Key / 自动重试信号时按数组顺序切换，并按模型加冷却时间。

---

3.7 第 5 步：模型能力缓存（models.dev）

OmO 的模型能力（上下文窗口、是否支持 thinking、是否多模态等）来自 models.dev 的快照 + 可刷新缓存 + 提供商运行时元数据 + 启发式回退。

刷新本地缓存：

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"
  }
}

bunx oh-my-opencode doctor 会输出每个 Agent / Category 实际跑在哪个模型上、是否落到兼容性回退、覆盖参数是否生效，是排错的第一站。

---

3.8 第 6 步：把 OmO 跑起来

3.8.1 跑第一个 ultrawork

opencode  # 启动 OpenCode TUI

进入会话后，第一句话直接：

ultrawork 给 README.md 加一段中文版的项目简介

Agent 会自动：

1. 触发 keyword-detector Hook 进入 ultrawork 模式；
2. 经 IntentGate 分类为"实现/写作"；
3. Sisyphus 做 todo 列表；
4. 派 Librarian 去查现有 README、Explore 看相关代码；
5. 写、读 hashline 编辑、跑 lsp_diagnostics（Markdown 不会有）、做完。

如果你想做"先访谈再执行"的精细工作流：

（Tab 切到 Prometheus）→ 描述需求 → 回答问题 → 让 Prometheus 写计划
（回到 Sisyphus）→ /start-work → Atlas 执行

3.8.2 启用 Tmux 多 Pane 观察

{
  "tmux": {
    "enabled": true,
    "layout": "main-vertical"
  }
}

之后你在一个 tmux 会话里跑 opencode，所有后台 Agent 会真的在新 Pane 里跑给你看，结束自动销毁，超酷。

---

3.9 遥测、隐私与卸载

3.9.1 匿名遥测

OmO 默认开启匿名遥测，仅用于统计活跃安装数（DAU/WAU/MAU）：每天每机器最多发一次事件，使用哈希化的安装标识，不创建 PostHog person profile，绝不上传原始主机名。要关掉：

export OMO_SEND_ANONYMOUS_TELEMETRY=0
# 或者
export OMO_DISABLE_POSTHOG=1

详见 Privacy Policy 和 Terms of Service。

3.9.2 卸载

不打算继续用了？三步：

1. 从 ~/.config/opencode/opencode.json 的 plugin 数组里删掉 "oh-my-opencode"（或 "oh-my-openagent"）：

   jq '.plugin = [.plugin[] | select(. != "oh-my-opencode")]' \
       ~/.config/opencode/opencode.json > /tmp/oc.json && \
       mv /tmp/oc.json ~/.config/opencode/opencode.json
   

2. 删除全局/项目配置（可选）：

   rm -f ~/.config/opencode/oh-my-opencode.json ~/.config/opencode/oh-my-opencode.jsonc
   rm -f .opencode/oh-my-opencode.json .opencode/oh-my-opencode.jsonc
   

3. 校验：

   opencode --version
   # 不应再有任何插件相关输出
   

---

3.10 安装阶段最常见的坑

下面这些是社区里反复出现的故障，提前知道能省掉一晚上的 debug：

1. OpenCode 版本不够：opencode --version < 1.0.150 → 升级 OpenCode。
2. Claude OAuth 浏览器没回调：检查防火墙、再次 opencode auth login。
3. bunx 没装：curl -fsSL https://bun.com/install | bash，重新打开终端。
4. Using legacy package name "oh-my-opencode"：把 opencode.json 里 plugin 数组的 "oh-my-opencode" 改成 "oh-my-openagent"。
5. Doctor 提示某 Agent 落到了"compatibility fallback"：通常意味着你给它配的模型在 models.dev 缓存中没匹配能力，运行 refresh-model-capabilities。
6. 想要免费/低成本路线但默认配置仍然走 Claude：用 --claude=no 重新跑 install，或在 oh-my-openagent.json 里把 agents.sisyphus.model 显式改为 opencode-go/kimi-k2.5 / zai-coding-plan/glm-5。
7. Ollama 本地模型出 JSON Parse error: Unexpected EOF：见第十章故障排除——把 stream: false。

---

3.11 进入下一步

到这一步，你应该已经：

• 在 opencode.json 里看到 "oh-my-openagent" 插件入口；
• bunx oh-my-opencode doctor 全绿（或只剩你能解读的小警告）；
• opencode 启动后能跑出第一个 ultrawork 任务。

下一章我们将放下安装，开始第四章：智能体（Agents）全景详解——挨个讲清楚 11 个 Agent 各自的角色、提示词风格、模型偏好与工具权限。