# Windows (PowerShell)
irm https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.ps1 | iex

# 任意装有 bun 的 OS：同样的设置，外加全局 `oma` 命令
bun install --global oh-my-agent
oma

在 Windows 上，安装器会隐藏 Antigravity、Hermes 和 Kimi，而且 hook 包装器是一个 bash 脚本。默认的 Aside 浏览器 MCP 通过 bash 安装，如果没有 bash，请取消勾选它。

• 安装 bun（必需）。尝试安装 uv、Serena（uv tool install）和 CUE（brew install cue 或 winget），其中任何一个失败都会给出警告并继续。
• 在交互式设置中预先选中 Aside 浏览器 MCP，只有保持选中时才会通过 curl -fsSL https://releases.aside.com/install.sh | bash 安装。可以在浏览器 MCP 步骤中取消勾选，或之后用 oma update mcp 更换。
• 使用 AgentMemory 作为语义记忆，它会运行 bun install -g @agentmemory/agentmemory，并将其注册为登录服务（launchd、systemd 用户单元或 Windows 计划任务）。选择提供方 none 或设置 OMA_NO_AGENTMEMORY=1 即可跳过。
• 把技能链接到主目录下的厂商文件夹（Antigravity、Hermes、Kimi）之前会先询问。在 $HOME 中不带 --global 运行时会请求确认。
• 不经询问写入项目之外的一些文件：~/.claude.json（将项目标记为受信任的 Claude Code 工作区）、~/.serena/（OMA 上下文、回答大小下限、项目注册）、~/.cursor/cli-config.json（关闭 Cursor 的提交署名）、~/.grok/config.toml（遥测）和 ~/.gemini/antigravity-cli/（HUD），每个文件只在你选择了对应厂商时写入。
• 在厂商设置中写入遥测退出选项（Claude 使用 DISABLE_TELEMETRY=1，这也会关闭 Claude Code Remote Control；Gemini、Qwen、Codex 和 Grok 关闭使用统计）。设置 telemetry: true 可保留厂商默认值。
• 向 .claude/settings.json 添加尚未设置的 Claude Code 设置，包括 skipDangerousModePermissionPrompt: true、effortLevel: high、cleanupPeriodDays: 180，以及关闭 auto memory、adaptive thinking、错误报告和内置 git 指令的 env 标志。你已经设置的值会保留。
• 添加共同作者 trailer：Claude Code 的提交署名变为 Co-Authored-By: First Fluke <[email protected]>，PR 会附上一行 "Generated with oh-my-agent"。设置 scm.co_author.enabled: false 可关闭。
• 在 .githooks/ 中安装 commit-msg 守卫，拒绝不在列表中的 Co-authored-by 地址，并在没有其他钩子生效时设置 git config --local core.hooksPath .githooks。设置 scm.co_author.enforce_hook: false 可退出。
• oma update 会在后台更新 oma CLI（用 auto_update_cli: false 或 OMA_SKIP_VERSION_CHECK=1 停止），并运行 uv tool upgrade serena-agent --prerelease=allow（serena.auto_update: false）。
• Serena 处于默认的 bridge 模式时，第一个启动共享 Serena 服务器的代理会话会注册一个清理定时器，每 5 分钟停止空闲的共享 Serena 服务器（launchd dev.oma.serena-daemon-gc、systemd 用户定时器 oma-serena-daemon-gc.timer 或 Windows 计划任务 OMA Serena Daemon GC）。设置 serena.mode: stdio 可跳过共享服务器及其定时器。oma uninstall 不会移除该定时器。
• 非交互式运行（-y、OMA_YES=1、CI=true）使用 All 技能预设、model_preset: auto，并以 Python 作为后端语言。除非 mcp.devtools_browsers 已列出某个浏览器，否则不会选择任何浏览器 MCP（也会跳过 Aside 安装脚本）。

在这些具名预设中，只有 All 包含 coordination、orchestration、docs、security、refactor、explanation、recap、video、slide 和 skill-creation（也可以在 Custom 中单独挑选）。Research 和 Content 缺少 /plan、/review、/debug、/architecture 和 /brainstorm 所依赖的技能。参见需要预设之外技能的工作流。

基础设施工程师（tf-infra-engineer）被要求在任何破坏性或生产环境的 apply 或 destroy 之前先征求你的同意。其余技能（brainstorm、security、scm、dev-workflow、observability、explanation、recap、translation、coordination、orchestration、skill-creation，以及内容与媒体类技能）没有专属角色。你的 agent 会自行加载它们，其中大多数还会由技能注入器根据你的 prompt 推荐合适的那个。

oma verify triggers 使用一份带标注、包含 212 条英文和韩文提示的语料评估检测器，误检超过 10% 或漏检超过 20% 时 CI 就会失败。最近一次实测：漏检 0%，误检 5.3%。完整参考：工作流。

/stack-set 读取你的 manifest 文件，为 backend、frontend 和 mobile 技能写入针对该技术栈的参考资料。在 monorepo 中，前端、后端和移动端工程师会被指向各自的 workspace（pnpm、npm/yarn/bun workspaces、lerna、nx、turbo、mise.toml）。

这些流水线在缺少来源或厂商密钥时会如实报告，而不是悄悄返回一份缩水的结果。

oma hook probe 检查 oma 的 prompt hook 能否接受各运行时的 hook 输入（它不会启动运行时）。每个运行时接入了哪些 hook，见运行时差异。

• oma agent spawn <role> "<task>" <sid> 可在 Antigravity、Claude Code、Codex、Cursor、Grok、Kimi Code、Kiro、OpenCode、pi 或 Qwen Code 上运行角色，并支持 --isolation worktree 和 --fallback-vendors。oma agent parallel 可同时运行多个。这 10 个调度目标属于安装器支持的 14 个集成。
• oma state list --all-projects 和 oma state get <sid>：会话以及记录下的每一条事件。
• oma dashboard terminal / oma dashboard web：实时 agent 状态（Web 仪表盘只监听 127.0.0.1）。仪表盘指南。
• oma stats get（生产力指标）、oma retro（git 回顾）、oma recap --window 7d（你在各个 AI 工具中做了什么）。
• oma visualize --affected <paths>：哪些技能、工作流、agent 和检查依赖你改动的 .agents/ 文件。

Serena 提供基于 LSP 的代码导航和诊断，并在支持时反馈原生编辑结果。能力提供方的选择独立于 agent 运行时；可用能力因提供方和宿主而异。

agent 之间通过 .agents/state/ 中的普通文件协调，不依赖任何外部服务。/tools 用自然语言开启或关闭 MCP 工具。详情：能力提供方。

• oma skill eval 在留出任务上测量技能相对 baseline 的提升幅度。oma skill optimize 会提出能进一步提高这一幅度的修改，加上 --apply 则保留这些修改（skill-eval 指南）。
• oma harness evolution enable --max-dispatches <n> 会安排一个每晚运行的周期：把失败的运行转成回归 fixture，并把通过评测的技能改进作为项目 overlay 应用。加上 --mode propose 则只记录这些改进。
• oma emit 把 .agents/ 源导出为 Agent Skills 包、Agent Plugins 包、Claude Code 插件市场或 AGENTS.md。

• 由用户自己掌管的那份 .agents/oma-config.yaml 在更新后会保留（只有 oma update --force 会重置它）；还可以在它之上叠加私有的 .local.yaml 或 .local.cue overlay。language 设置响应语言。
• 13 条项目规则（backend、commit、database、debug、design 等）在 Claude Code 和 Cursor 中作为原生规则加载，并在为 Codex、Qwen Code 和 Pi 写入的托管 AGENTS.md 区块中建立索引。
• 更新时会在 .agents/backup/ 中保留配置和迁移备份；随附的技能和工作流会被原地替换，所以请把本地修改放在它们之外。oma uninstall --dry-run 会列出将被删除的内容。first-fluke/oma-update-action@v1 会在 CI 中运行 oma update 并开一个 PR。

原生 = oma 写入运行时自己的配置文件；适配器 = oma 还会额外添加 hook 或 agent shim。Amp 会自行读取 .agents/skills/，不是安装目标。

Claude Code 原生 + 适配器	Codex CLI 原生 + 适配器	Antigravity 原生 SSOT	Cursor 原生 + 适配器	Qwen Code 原生派发	DeepSeek Harness Cordis plugin
Pi 原生兼容	OpenCode 原生兼容	Amp 读取 .agents/skills	GitHub Copilot 符号链接技能	Grok Build 原生 hook	Kiro CLI 原生 hook + agent

_{& 更多}

.agents/oma-config.yaml 中的 model_preset 决定每个 agent 角色使用哪个模型。默认值 auto 会沿用当前运行时自身的 agent 和模型设置。

language: en
model_preset: auto   # auto | free | antigravity | claude | codex | cursor | kiro | mixed | qwen | <custom_presets key>

# Optional per-agent overrides; they win over the preset
agents:
  backend: { model: openai/gpt-6.1-terra, effort: high }

• mixed 让编排器、architecture、QA、PM 和 docs 使用 Claude，实现类角色使用 Codex gpt-6.1-terra，因此需要同时具备 Claude Code 和 Codex CLI。
• free 通过 FreeLLMAPI 网关路由，需要 FREELLM_API_KEY 以及一个正在运行的服务器。
• kiro 不在安装器菜单中，需要在配置文件里设置。
• oma doctor --profile 会输出每个角色解析后的模型。
• 完整指南：按 agent 配置模型

限制：

• Stop 门禁只作用于持久型工作流（/orchestrate、/work、/ultrawork、/ralph）。没有 oma goal set --gate 时，它只会再次提示 agent 继续。当项目有低成本的检查时，/ultrawork 会让 agent 设置门禁，但没有任何机制强制执行。想要确保的话，请自己运行 oma goal set --gate test；其他持久型工作流从不设置门禁。
• 只接受 typecheck、test 和 lint 这三个关键词，它们会运行 package.json 中同名的脚本。没有 package.json，或没有同名脚本，门禁就不会运行。非 JS 项目需要一个 package.json 包装脚本。
• 阻止 5 次后、经过 2 小时或 --budget-minutes 用完后，门禁会解除阻止并记录失败。
• 预算：session.quota_cap 限制 token 数、spawn 次数和单厂商 token；任何一个维度超标时，编排器都会拒绝下一次 spawn。

产出物门禁。 缺少产出物表示该阶段没有运行。当会话日志记录了 REFINE 跳过原因时，refactor 检查也会以 skip-recorded 通过。

prompt 驱动的 judge。 /ralph 工作流 prompt 要求编排器把 judge 作为一个拥有全新上下文的独立 agent 来 spawn，只告知它标准本身（绝不告知实现方声称自己修好了什么），并在每一轮重新校验每一条标准，已经 PASS 的也不例外，因为修复一项标准可能导致另一项回退。没有任何东西会检查这次 spawn 是否真的发生：oma ralph verify 把关的是 EXEC 产出物，而不是 judge；无法 spawn subagent 的运行时会被要求以内联方式判定，并记录 ralph.judge-inline-fallback。/ralph 在 5 轮后停止，并给出部分完成报告。

事件日志。 用 oma state list 找到会话，再用 oma state get <sid> 读取。每个事件都带有厂商和运行时会话 id。这个文件的位置取决于 OMA_HOME、OMA_STATE_HOME、OMA_PROFILE 以及旧版的项目本地会话目录，所以不要把路径写死。

按 agent 检查。 类型：backend、frontend、mobile、qa、debug、pm。任意检查失败时命令以 1 退出；TODO/FIXME Comments 和 Inline Styles 只会给出警告。

• backend：<Language> Syntax、SQL Injection（原始 SQL 模式）和 <Language> Tests，来自 stack/stack.yaml 中的命令。没有这个文件（可用 /stack-set 生成）时会跳过这些检查。
• frontend：stack/stack.yaml（位于 oma-frontend 下；若已安装 angular-developer 技能，则位于其下）中的语法和测试命令，或 TypeScript（tsc --noEmit）与 Frontend Tests（Vitest）。Inline Styles 和 Any Types 始终运行。
• mobile：stack/stack.yaml 中的语法和测试命令，或 Flutter/Dart Analysis 与 Flutter Tests。
• debug：Python Tests（通过 uv 运行 pytest）或 Frontend Tests（Vitest）。
• pm：PM Plan（计划文件是合法的 JSON）。
• qa：没有机械检查。

flowchart TD
    S[Agent tries to stop] --> P{Persistent workflow active?}
    P -- no --> A[Stop allowed]
    P -- yes --> D{User or agent said workflow done?}
    D -- yes --> A
    D -- no --> R{Budget spent, state older than 2 h, or 5 blocks reached?}
    R -- yes --> F[Stop allowed, logged as gate.failed]
    R -- no --> G{Gate set and package.json script exists?}
    G -- no --> B1[Blocked: workflow still active]
    G -- yes --> X{Script exits 0 within 25 s?}
    X -- yes --> OK[Stop allowed, logged as gate.passed]
    X -- no --> B2[Blocked with output tail, logged as gate.failed]

不需要。参见技能预设；All 是稳妥的默认选择。

oma doctor 会显示已安装的技能，并在 hook 找不到 oma 时发出警告。在持久型工作流运行期间，oma state list 会显示活跃会话，oma state get <sid> 会显示它的门禁事件。

通常会。技能只在任务需要时加载，但多 agent 工作流和全新上下文审查会花得更多。在单 prompt 基准测试中，oma 的成本是纯 Claude Code 的 1.7 倍。

说“workflow done”（或“workflow complete” / “workflow finished”，或其他受支持语言中的对应说法），或者删除 .agents/state/<workflow>-state-<sid>.json。两者都不做的话，它会在阻止 5 次或 2 小时后自行解除。

oma update 会刷新技能、工作流和 hook，并保留你的配置（--with-new-skills 会加入该版本新增的技能；oma update mcp 可重新选择浏览器 MCP）。oma uninstall --dry-run 会列出将被删除的内容；oma uninstall 执行删除，并保留 oma-config.yaml、mcp.json 和你自己编写的技能。更多解决办法：故障排查。

规划和下一步的选择仍由你的 agent 所用的模型负责；oma 没有固定的工作流图。oma 在模型之外强制执行的有：工具护栏（密钥守卫和搜索守卫）、预算、重试与停止上限、事件日志，以及在你设置了门禁时，一个要等你自己的检查通过才放行的停止。

• Li, X., Liu, Y., Chen, W., You, B., Di, Z., He, Y., Zheng, S., Choe, K. W., Sun, J., Wang, S., Tao, C., Li, B., Zhao, X., Geng, H., Wu, X., Zhou, J., Chen, X., Xing, H., Li, Y., … Song, D. (2026). SkillsBench: Benchmarking how well agent skills work across diverse tasks (Version 4) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2602.12670
• Yu, G., & Wang, X. (2026). Knows: Agent-native structured research representations (Version 1) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2604.17309
• Liang, Q., Wang, H., Liang, Z., & Liu, Y. (2026). From skill text to skill structure: The scheduling-structural-logical representation for agent skills (Version 4) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2604.24026
• Chen, C., Yu, Q., Gu, Y., Huang, Z., Li, H., Liu, H., Liu, S., Liu, J., Peng, D., Wang, J., Yan, Z., Meng, F., Qin, E., Che, C., & Hu, M. (2026). The scaling laws of skills in LLM agent systems (Version 1) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2605.16508
• Tang, L., Rashtchian, C., Ferng, C.-S., Tomkins, A., Juan, D.-C., & Vu, T. (2026). WikiSkill: Compiling agent experience into persistent knowledge for skill evolution [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2608.27454
• Huang, Z., Xu, J., Yang, Y., Gong, Z., Yang, Q., Tian, M., Wang, X., Lv, C., Gao, X., Dai, Q., Liu, B., Qiu, K., Yang, X., Chen, D., Zheng, X., & Luo, C. (2026). From raw experience to skill consumption: A systematic study of model-generated agent skills [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2605.23899
• Hong, D. B., Imani, A., & Ahmed, I. (2026). From anatomy to smells: An empirical study of SKILL.md in agent skills (Version 2) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2607.01456