在 Olares 上使用 oh-my-openagent 编排多代理编码工作流:OpenCode 本地模型配置与 MCP 集成指南
在 Olares 上使用 oh-my-openagent 编排多代理编码工作流:OpenCode 本地模型配置与 MCP 集成指南
oh-my-openagent(简称 OMO)是 OpenCode 的多模型代理编排插件,启用后可用 ultrawork 关键词在 Olares 上触发 Sisyphus、Hephaestus、Oracle、Atlas 等专业代理分工协作,共同处理复杂编码任务。本文基于 Olares 1.12.6 与 OpenCode chart 版本 1.0.6+,完整讲解 OMO 的启用、本地/云/混合模型配置、多代理工作流的使用方法,以及内置 context7、grep_app、websearch 三个 MCP 服务器的接入与自托管 Context7 的路由方案。
本文适用背景与版本前提
OMO 以插件形式运行在 OpenCode 之上。在 Olares 中,OpenCode 以应用形式安装(可从 Market 搜索安装),并通过模型控制台提供的 Model name 与 Base URL 连接到本地模型(详见 将 OpenCode 设置为你的 AI 编码代理)。本文描述的能力针对 Olares 1.12.6 版本,对应的应用版本为 OpenCode chart 1.0.6 或更高,OMO 相关文档版本为 1.1(更新于 2026-07-29)。
开始配置前,你的 Olares 设备必须具备互联网访问权限,并满足以下条件:
| 用途 | 模型 | 获取方式 |
|---|---|---|
| 核心代理 | Qwen3.6-27B (llama.cpp) | 从 Market 安装 |
| 轻量子代理 | Qwen3.5-9B (Ollama) | 通过 Ollama Engine Base 应用创建 |
配置 OMO 前,请先将两个模型分别连接到 OpenCode。Olares 上的独立模型作为与客户端应用分开的服务运行,连接双方需要准确的 Model name 与符合客户端所需 API 格式(如 OpenAI-Compatible)的 Base URL,这两个值均可以从模型控制台获取(参见 AI 服务连接)。在 OpenCode 中连接自定义提供方时,需要填写 Provider ID(唯一标识符)、Base URL 和精确的 Model ID 三项,具体步骤见 连接到自定义提供方。
:::info 模型能力要求
- 参数少于 7B 的本地模型通常无法正确处理
tool_use或结构化输出,避免将它们用于任何代理。 - 建议上下文窗口至少为 32K token;核心代理(Sisyphus、Hephaestus、Prometheus、Atlas)使用 64K 或更多时效果更好。
- 本地模型有时无法正确生成
write工具调用。 :::
了解 Olares 上的 OMO
模型选择机制:主模型与子代理模型
OMO 将模型选择权在你和配置文件之间分配:
- 主模型:你直接与之聊天的代理所使用的模型,在 OpenCode UI 的模型选择器中挑选,独立于
oh-my-openagent.json。 - 子代理模型:当主代理通过
delegate_task将工作交给子代理(如 Explore 或 Librarian)时,该子代理使用~/.config/opencode/oh-my-openagent.json中agents字段下为该代理定义的模型。
默认的 oh-my-openagent.json 为每个子代理配备了多层回退链:付费主模型、付费备用模型,以及 OpenCode 提供的免费模型作为最后的回退。如果第一个模型在运行时不可用,runtime_fallback 会自动沿链向下走到下一个,结构大致如下:
oh-my-openagent.json
└── agents
└── <agent name>
└── model chain: paid primary → paid backup → free fallback
(runtime_fallback auto-switches on failure)
这使子代理委托即使在提供方宕机时也能继续工作。
配置文件中的默认模型
OMO 为每个代理的提示调整特定的模型系列。默认配置文件使用以下主模型(推荐云模型)与免费回退模型:
| 代理 | 推荐的 UI 模型(云) | 免费回退 |
|---|---|---|
| Sisyphus | Claude Opus 4.6 | Big Pickle |
| Hephaestus | GPT-5.4 | Big Pickle |
| Prometheus | Claude Opus 4.6 | Big Pickle |
| Atlas | Claude Sonnet 4.6 | Big Pickle |
| Oracle | GPT-5.4 | Big Pickle |
| Explore | Claude Haiku 4.5 | GPT-5 Nano |
| Librarian | MiniMax M2.7 | GPT-5 Nano |
Olares 为 OMO 管理的文件
安装 OpenCode 时,Olares 会预配置 OMO。预安装项目位于全局 OpenCode 配置目录下,该目录映射到 Olares Files 中的 Application/Data/opencode/.config/opencode/。本文其余部分使用 ~/.config/opencode/ 作为此路径的简写。Olares 管理的文件清单如下:
| 路径 | 作用 |
|---|---|
~/.config/opencode/opencode.json(plugin 字段) |
在全局配置中注册 "oh-my-openagent"。 |
~/.config/opencode/oh-my-openagent.json |
每个代理的推荐模型以及运行时回退链。仅在首次安装时写入。 |
~/.config/opencode/olares-baseline-instructions.md |
Web 预览、包管理和 Olares 域约定。每次启动时刷新。 |
~/.config/opencode/skills/web-preview/ 和 system-admin/ |
技能文件。每次启动时强制更新。 |
/usr/local/lib/node_modules/oh-my-opencode/(容器内) |
npm 包。持久化在系统快照中。 |
两个值得注意的更新策略:
- 所有 Olares 管理的设置都位于全局配置目录,永远不会写入你的工作空间
opencode.json。如果你的工作空间配置仍然包含旧的 Olares 管理的指令,Olares 只会在它们与之前的预设完全匹配时才删除它们;你添加或修改的任何内容都会被保留。 oh-my-openagent.json仅在首次安装时写入。如果你稍后通过install命令或手动更新它,你的更改不会被覆盖。
配置 OMO
启用 OMO
OMO 由 OPENCODE_OMO 环境变量控制:
false(默认):插件不加载。npm 包和配置文件保留在磁盘上,因此稍后启用它不需要再次下载。true:插件在全局配置中注册,并安装 npm 包。
启用步骤如下:
- 打开 Settings 并导航到 Applications > OpenCode > Manage environment variables。
- 找到
OPENCODE_OMO环境变量并点击编辑图标。 - 在 Value 下拉菜单中,选择
true,然后点击 Confirm。 - 点击 Apply 保存更改,并等待应用重启。
首次启动时,OMO 需要时间来完成其初始配置,这可能需要几分钟。要稍后禁用 OMO,重复上述步骤并将 OPENCODE_OMO 设置为 false。插件注册和 MCP 服务器会停止,但 npm 包和 oh-my-openagent.json 配置保留在磁盘上,供下次重新启用。
配置本地模型
配置 ~/.config/opencode/oh-my-openagent.json,让 OMO 将任务委派给本地模型。以下两种情况可以跳过本节:
- 仅使用云模型:在 OpenCode 的提供方中添加 API 密钥并使用云模型。
- 仅使用免费回退模型:使用 OpenCode 自带的免费回退模型,但响应速度可能较慢,并受到额度限制。
OMO 在两个位置使用模型:
- 主代理:在 OpenCode 模型选择器中单独选择模型,本节不会更改该选择。
- 子代理和任务类别:将 Qwen3.6-27B 分配给核心代理和高负载任务,将 Qwen3.5-9B 用于 Explore、Librarian 和轻量任务。
:::tip 需要重启
每次编辑 oh-my-openagent.json 后,都需重启 OpenCode 才能使更改生效。
:::
-
打开文件管理器,前往
Application/Data/opencode/.config/opencode/,找到oh-my-openagent.json。 -
打开文件并点击编辑图标进入编辑模式。
-
更新
agents部分,让子代理委派使用本地模型:a. 设置每个代理的
model字段。该值必须包含 OpenCode 中使用的 provider 前缀,后接准确的模型名称。b. 将 Qwen3.6-27B 分配给核心代理,将 Qwen3.5-9B 分配给 Explore 和 Librarian。为使用 Ollama 模型的代理添加
"stream": false。例如,如果 provider 名称分别为
qwen3.6-27b和qwen3.5-9b:{ "agents": { "sisyphus": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" }, "hephaestus": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" }, "prometheus": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" }, "atlas": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" }, "explore": { "model": "qwen3.5-9b/qwen3.5:9b", "stream": false }, "librarian": { "model": "qwen3.5-9b/qwen3.5:9b", "stream": false } } }:::info
"stream": false要求 Ollama 的流式模式返回 SDK 无法解析的 NDJSON。如果缺少"stream": false,使用工具的代理(尤其是 Librarian 和 Explore)会静默回退到模型链中的下一个模型。这是 Ollama 的已知限制。 ::: -
在
categories部分,为quick和writing使用 Qwen3.5-9B,其他类别使用 Qwen3.6-27B,并保留现有的fallback_models条目。例如:{ "categories": { "visual-engineering": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M", "fallback_models": [ // 保留现有的 fallback 条目 ] }, "quick": { "model": "qwen3.5-9b/qwen3.5:9b", "fallback_models": [ // 保留现有的 fallback 条目 ] }, "writing": { "model": "qwen3.5-9b/qwen3.5:9b", "fallback_models": [ // 保留现有的 fallback 条目 ] } } }categories部分把任务按类型分组,每种类别都配有独立的模型与回退链。以默认配置为例,visual-engineering(视觉工程类)的主模型是qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M,回退链依次为 Qwen3.5-9B、Gemini 3.1 Pro Preview、Claude Opus 4.6、Big Pickle 等;quick(快速类)的主模型为 Qwen3.5-9B,回退链包含 Qwen3.6-27B、GPT-5.4-mini、Claude Haiku 4.5、Gemini 3 Flash Preview、GPT-5 Nano 等轻量模型;writing(写作类)同样以 Qwen3.5-9B 为主,回退到 Gemini 3 Flash Preview、Claude Sonnet 4.6 与 Big Pickle。完整的默认categories结构如下:{ "categories": { "visual-engineering": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M", "fallback_models": [ { "model": "qwen3.5-9b/qwen3.5:9b" }, { "model": "google/gemini-3.1-pro-preview", "variant": "high" }, { "model": "github-copilot/gemini-3.1-pro-preview", "variant": "high" }, { "model": "anthropic/claude-opus-4-6", "variant": "max" }, { "model": "github-copilot/claude-opus-4.6", "variant": "max" }, { "model": "opencode/big-pickle" } ] }, "ultrabrain": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M", "fallback_models": [ { "model": "qwen3.5-9b/qwen3.5:9b" }, { "model": "openai/gpt-5.4", "variant": "xhigh" }, { "model": "google/gemini-3.1-pro-preview", "variant": "high" }, { "model": "github-copilot/gemini-3.1-pro-preview", "variant": "high" }, { "model": "anthropic/claude-opus-4-6", "variant": "max" }, { "model": "github-copilot/claude-opus-4.6", "variant": "max" }, { "model": "opencode/big-pickle" } ] }, "deep": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M", "fallback_models": [ { "model": "qwen3.5-9b/qwen3.5:9b" }, { "model": "openai/gpt-5.4", "variant": "medium" }, { "model": "github-copilot/gpt-5.4", "variant": "medium" }, { "model": "anthropic/claude-opus-4-6", "variant": "max" }, { "model": "github-copilot/claude-opus-4.6", "variant": "max" }, { "model": "google/gemini-3.1-pro-preview", "variant": "high" }, { "model": "github-copilot/gemini-3.1-pro-preview", "variant": "high" }, { "model": "opencode/big-pickle" } ] }, "artistry": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M", "fallback_models": [ { "model": "qwen3.5-9b/qwen3.5:9b" }, { "model": "google/gemini-3.1-pro-preview", "variant": "high" }, { "model": "github-copilot/gemini-3.1-pro-preview", "variant": "high" }, { "model": "anthropic/claude-opus-4-6", "variant": "max" }, { "model": "github-copilot/claude-opus-4.6", "variant": "max" }, { "model": "openai/gpt-5.4" }, { "model": "github-copilot/gpt-5.4" }, { "model": "opencode/big-pickle" } ] }, "quick": { "model": "qwen3.5-9b/qwen3.5:9b", "fallback_models": [ { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" }, { "model": "openai/gpt-5.4-mini" }, { "model": "github-copilot/gpt-5.4-mini" }, { "model": "anthropic/claude-haiku-4-5" }, { "model": "github-copilot/claude-haiku-4.5" }, { "model": "google/gemini-3-flash-preview" }, { "model": "github-copilot/gemini-3-flash-preview" }, { "model": "opencode/gpt-5-nano" } ] }, "unspecified-low": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M", "fallback_models": [ { "model": "qwen3.5-9b/qwen3.5:9b" }, { "model": "anthropic/claude-sonnet-4-6" }, { "model": "github-copilot/claude-sonnet-4.6" }, { "model": "openai/gpt-5.3-codex", "variant": "medium" }, { "model": "google/gemini-3-flash-preview" }, { "model": "github-copilot/gemini-3-flash-preview" }, { "model": "opencode/big-pickle" } ] }, "unspecified-high": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M", "fallback_models": [ { "model": "qwen3.5-9b/qwen3.5:9b" }, { "model": "anthropic/claude-sonnet-4-6" }, { "model": "github-copilot/claude-sonnet-4.6" }, { "model": "openai/gpt-5.3-codex", "variant": "medium" }, { "model": "google/gemini-3-flash-preview" }, { "model": "github-copilot/gemini-3-flash-preview" }, { "model": "opencode/big-pickle" } ] }, "writing": { "model": "qwen3.5-9b/qwen3.5:9b", "fallback_models": [ { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" }, { "model": "google/gemini-3-flash-preview" }, { "model": "github-copilot/gemini-3-flash-preview" }, { "model": "anthropic/claude-sonnet-4-6" }, { "model": "github-copilot/claude-sonnet-4.6" }, { "model": "opencode/big-pickle" } ] } } } -
为两个本地模型添加并发限制:
{ "background_task": { "providerConcurrency": { "qwen3.6-27b": 1, "qwen3.5-9b": 1 }, "modelConcurrency": { "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M": 1, "qwen3.5-9b/qwen3.5:9b": 2 } } }这样会将大模型限制为一个并发请求,同时允许轻量模型最多处理两个请求。对本地模型设置并发上限非常重要:自托管推理引擎的显存与算力有限,过高的并发会导致排队与超时,而轻量模型放宽到 2 可以显著提升 Librarian、Explore 等搜索类子代理的并行效率。
-
保存文件。
-
重启 OpenCode:打开设置,前往应用 > OpenCode,点击停止,然后点击恢复。
完整的本地模型配置示例(含 $schema、runtime_fallback、agents、categories 与 background_task)汇总如下:
{
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
"runtime_fallback": {
"enabled": true,
"max_fallback_attempts": 7
},
"agents": {
"sisyphus": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" },
"hephaestus": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" },
"prometheus": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" },
"atlas": { "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" },
"explore": { "model": "qwen3.5-9b/qwen3.5:9b" },
"librarian": { "model": "qwen3.5-9b/qwen3.5:9b" }
},
"categories": {
"visual-engineering": {
"model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M",
"fallback_models": [
{ "model": "qwen3.5-9b/qwen3.5:9b" },
{ "model": "google/gemini-3.1-pro-preview", "variant": "high" },
{ "model": "github-copilot/gemini-3.1-pro-preview", "variant": "high" },
{ "model": "anthropic/claude-opus-4-6", "variant": "max" },
{ "model": "github-copilot/claude-opus-4.6", "variant": "max" },
{ "model": "opencode/big-pickle" }
]
},
"ultrabrain": {
"model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M",
"fallback_models": [
{ "model": "qwen3.5-9b/qwen3.5:9b" },
{ "model": "openai/gpt-5.4", "variant": "xhigh" },
{ "model": "google/gemini-3.1-pro-preview", "variant": "high" },
{ "model": "github-copilot/gemini-3.1-pro-preview", "variant": "high" },
{ "model": "anthropic/claude-opus-4-6", "variant": "max" },
{ "model": "github-copilot/claude-opus-4.6", "variant": "max" },
{ "model": "opencode/big-pickle" }
]
},
"deep": {
"model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M",
"fallback_models": [
{ "model": "qwen3.5-9b/qwen3.5:9b" },
{ "model": "openai/gpt-5.4", "variant": "medium" },
{ "model": "github-copilot/gpt-5.4", "variant": "medium" },
{ "model": "anthropic/claude-opus-4-6", "variant": "max" },
{ "model": "github-copilot/claude-opus-4.6", "variant": "max" },
{ "model": "google/gemini-3.1-pro-preview", "variant": "high" },
{ "model": "github-copilot/gemini-3.1-pro-preview", "variant": "high" },
{ "model": "opencode/big-pickle" }
]
},
"artistry": {
"model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M",
"fallback_models": [
{ "model": "qwen3.5-9b/qwen3.5:9b" },
{ "model": "google/gemini-3.1-pro-preview", "variant": "high" },
{ "model": "github-copilot/gemini-3.1-pro-preview", "variant": "high" },
{ "model": "anthropic/claude-opus-4-6", "variant": "max" },
{ "model": "github-copilot/claude-opus-4.6", "variant": "max" },
{ "model": "openai/gpt-5.4" },
{ "model": "github-copilot/gpt-5.4" },
{ "model": "opencode/big-pickle" }
]
},
"quick": {
"model": "qwen3.5-9b/qwen3.5:9b",
"fallback_models": [
{ "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" },
{ "model": "openai/gpt-5.4-mini" },
{ "model": "github-copilot/gpt-5.4-mini" },
{ "model": "anthropic/claude-haiku-4-5" },
{ "model": "github-copilot/claude-haiku-4.5" },
{ "model": "google/gemini-3-flash-preview" },
{ "model": "github-copilot/gemini-3-flash-preview" },
{ "model": "opencode/gpt-5-nano" }
]
},
"unspecified-low": {
"model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M",
"fallback_models": [
{ "model": "qwen3.5-9b/qwen3.5:9b" },
{ "model": "anthropic/claude-sonnet-4-6" },
{ "model": "github-copilot/claude-sonnet-4.6" },
{ "model": "openai/gpt-5.3-codex", "variant": "medium" },
{ "model": "google/gemini-3-flash-preview" },
{ "model": "github-copilot/gemini-3-flash-preview" },
{ "model": "opencode/big-pickle" }
]
},
"unspecified-high": {
"model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M",
"fallback_models": [
{ "model": "qwen3.5-9b/qwen3.5:9b" },
{ "model": "anthropic/claude-sonnet-4-6" },
{ "model": "github-copilot/claude-sonnet-4.6" },
{ "model": "openai/gpt-5.3-codex", "variant": "medium" },
{ "model": "google/gemini-3-flash-preview" },
{ "model": "github-copilot/gemini-3-flash-preview" },
{ "model": "opencode/big-pickle" }
]
},
"writing": {
"model": "qwen3.5-9b/qwen3.5:9b",
"fallback_models": [
{ "model": "qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M" },
{ "model": "google/gemini-3-flash-preview" },
{ "model": "github-copilot/gemini-3-flash-preview" },
{ "model": "anthropic/claude-sonnet-4-6" },
{ "model": "github-copilot/claude-sonnet-4.6" },
{ "model": "opencode/big-pickle" }
]
}
},
"background_task": {
"providerConcurrency": {
"qwen3.6-27b": 1,
"qwen3.5-9b": 1
},
"modelConcurrency": {
"qwen3.6-27b/unsloth/Qwen3.6-27B-GGUF:Q4_K_M": 1,
"qwen3.5-9b/qwen3.5:9b": 2
}
}
}
确认插件已加载
启用 OMO 后,打开 OpenCode Web UI。你应该会在顶部的代理选择器中看到 Sisyphus、Prometheus、Atlas 和 Hephaestus,这是插件加载成功的最直观标志。
你也可以点击右上角的状态图标来确认 oh-my-openagent 出现在 plugin 下。
使用 OMO
OMO 附带一组专业代理,每个代理的提示都针对特定角色进行了调整。你从代理选择器中选择 Sisyphus、Prometheus、Atlas 或 Hephaestus 作为主代理,其余的代理在多代理协作期间自动调度。
| 代理 | 角色 | 如何访问 |
|---|---|---|
| Sisyphus | 主编排器。在 ultrawork 模式下规划、委托给子代理并驱动并行执行。 |
代理选择器 |
| Hephaestus | 自主深度工作者。处理架构推理和长时间自主编码会话。 | 代理选择器 |
| Prometheus | 战略规划师。就需求采访你并生成详细计划。 | 代理选择器 |
| Atlas | 计划执行者。接管 Prometheus 计划并执行它。 | 代理选择器,或在规划后使用 /start-work |
| Oracle | 只读架构顾问。就架构决策和复杂调试提供建议,不修改文件。 | 在 ultrawork 中自动调度 |
| Explore | 代码搜索代理。检索整个仓库的代码。 | 在 ultrawork 中自动调度 |
| Librarian | 文档搜索代理。搜索文档和代码。 | 在 ultrawork 中自动调度 |
其他支持代理(如用于计划差距分析的 Metis、用于计划审查的 Momus,以及用于视觉输入的 Multimodal Looker)在需要时由 Sisyphus 自动调度。
单代理模式
启用 OMO 后,代理选择器从 Plan/Build 变为 Sisyphus、Prometheus、Atlas 和 Hephaestus。你不需要每次都启动多代理协作。没有 ultrawork 关键词时,每个代理独立运行,行为类似于原始的 Build 或 Plan 模式,没有额外的资源使用。
| 任务 | 如何操作 |
|---|---|
| 直接编码(以前的 Build) | 选择 Sisyphus 并正常聊天。与原始的 Build 模式体验相同。 |
| 先规划,再执行(以前的 Plan) | 选择 Prometheus。它采访你并生成计划。输入 /start-work 交给 Atlas。 |
| 深度自主编码 | 选择 Hephaestus。适合大型、复杂任务,可自主运行。 |
多代理协作模式
在聊天框中输入 ultrawork(或别名 ulw)后跟任务描述。例如:
ulw Implement a REST API user registration feature with email verification.
OMO 分析任务,将其分配给专业代理,并并行运行它们直到任务完成。当 ultrawork 激活时,聊天框上方闪烁的颜色指示当前正在工作的代理。
Prometheus 规划模式
:::info 意外的技能触发
任务描述中的某些关键词可能会触发 OpenCode 调用 /web-preview 技能。如果发生这种情况,请要求代理忽略它并继续规划。
:::
对于大型、复杂任务,先规划:
-
在代理选择器中切换到 Prometheus。
-
描述你的任务。例如:
Build a CLI tool that scans a folder and generates a summary report of its contents. -
回答 Prometheus 的问题以明确范围和细节。
-
Prometheus 在
.sisyphus/plans/下生成计划文件后,输入/start-work将执行交给 Atlas。如果没有计划文件,/start-work没有内容可传递给 Atlas,因此不会执行任何操作。:::tip 规划期间请耐心等待 如果 Prometheus 没有立即产生输出,或代理状态显示
background output,代理仍在工作。等待它完成后再发送另一条消息。 :::
常用命令
| 命令 | 描述 |
|---|---|
ultrawork / ulw |
启动多代理协作模式。在聊天框中作为关键词输入。 |
/start-work |
执行 Prometheus 生成的计划。 |
/init-deep |
为每个项目目录生成 AGENTS.md 上下文文件。 |
/ulw-loop |
循环运行 ultrawork 直到任务达到 100% 完成。 |
/handoff |
生成上下文摘要,以便你可以在新会话中继续工作。 |
使用内置 MCP 服务器
OMO 注册了三个远程 MCP 服务器,为代理提供对外部知识的实时访问。这些服务器不是 OpenCode 原生的,OMO 通过钩子注入它们。启用 OMO 后,你可以在 Settings 的 MCP 标签页下找到它们。
| MCP 服务器 | 使用场景 | API key |
|---|---|---|
| context7 | 针对官方文档的实时查询。 | 基本使用不需要。添加 key 以获得更高配额。 |
| grep_app | GitHub 全站代码搜索。 | 不需要。 |
| websearch | 实时网页搜索。 | 基本使用不需要。添加 key 以获得更高配额,或从 Exa 切换到 Tavily。 |
下面的示例显式命名 MCP 工具。你也可以让代理在检测到意图时自动选择。
context7:实时官方文档
AI 的训练数据有截止日期。当你使用较新的库版本时,AI 可能会生成已弃用的 API 或不存在的方法。Context7(由 Upstash 在 https://mcp.context7.com/mcp 提供)直接从源文档中提取最新内容并将其注入对话中。
例如,输入:
Implement a form submission with React 19's useActionState Hook. use context7
grep_app:GitHub 全站代码搜索
当 AI 不确定最佳实践或 API 用法时,它可以搜索 GitHub 项目中的真实代码作为参考。此 MCP 服务器由 Vercel 在 https://mcp.grep.app 提供。
例如,输入:
Find real examples of Drizzle ORM with PostgreSQL migrations. use grep_app
websearch:实时网页搜索
此 MCP 服务器默认使用 Exa AI(https://mcp.exa.ai/mcp?tools=web_search_exa),可以通过配置切换到 Tavily。
例如,输入:
What are the major changes in Kubernetes 1.32 released in 2026? use websearch
配置 API key 和切换提供方
context7 和 websearch 都可以在没有 key 的情况下工作,但添加 key 会提高你的配额并解除速率限制。你也可以将 websearch 从 Exa(默认)切换到 Tavily。grep_app 没有 key。
要配置任何这些,请在 ~/.config/opencode/oh-my-openagent.json 的 mcp 字段下添加内置 MCP 定义的覆盖。覆盖会完全替换内置定义,因此 type、url 和 enabled 都必须存在。如果你设置多个覆盖,请将它们放在同一个 mcp 对象下。
:::tip 需要重启
每次编辑 oh-my-openagent.json 后重启 OpenCode,以使新定义生效。
:::
为 context7 添加 API key
从 context7.com 获取 key,然后将其添加到 oh-my-openagent.json:
{
"mcp": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp",
"enabled": true,
"headers": {
"CONTEXT7_API_KEY": "YOUR_CONTEXT7_KEY"
}
}
}
}
要验证 key 是否激活,请要求代理使用 use context7 查找最近发布的库,然后检查你的 Context7 仪表板以了解使用量的增加。
为 websearch 添加 API key(Exa)
默认情况下,websearch 使用 Exa。从 exa.ai 获取 key,然后将其添加到 oh-my-openagent.json:
{
"mcp": {
"websearch": {
"type": "remote",
"url": "https://mcp.exa.ai/mcp?tools=web_search_exa",
"enabled": true,
"headers": {
"x-api-key": "YOUR_EXA_KEY"
}
}
}
}
要验证 key 是否激活,请要求代理运行网页搜索,并在成功搜索后检查 exa.ai 仪表板以了解使用量的增加。
将 websearch 从 Exa 切换到 Tavily
Tavily 是一个替代网页搜索提供方,每月提供 1,000 次免费搜索。从 app.tavily.com 获取 key,然后将 websearch 指向 Tavily:
{
"mcp": {
"websearch": {
"type": "remote",
"url": "https://mcp.tavily.com/mcp/",
"enabled": true,
"headers": {
"Authorization": "Bearer YOUR_TAVILY_KEY"
}
}
}
}
要验证,请从代理运行网页搜索,并检查你的 Tavily 仪表板以了解使用量的增加。要切换回 Exa,请用上面的 Exa 定义替换此块。
禁用特定 MCP 服务器
可以通过两种方式禁用特定 MCP 服务器:
从 UI 禁用:点击右上角的状态图标,然后选择 MCP,关闭特定 MCP 服务器。
通过配置文件禁用:编辑 ~/.config/opencode/oh-my-openagent.json 并添加 disabled_mcps 字段。例如,要禁用 websearch:
{
"disabled_mcps": ["websearch"]
}
允许的值:"websearch"、"context7"、"grep_app"。当你禁用 OMO(OPENCODE_OMO=false)时,所有三个 MCP 服务器都会随之停止。重启 OpenCode 后,当你刷新 OpenCode UI 时,websearch MCP 服务器不再出现,只列出其他两个 MCP 服务器。
使用自托管的 Context7
OMO 的内置 context7 服务器在 https://mcp.context7.com/mcp 查询公共 Context7 云。要使用你自己的实例,请在 Olares 上安装 Context7 并在 OpenCode 中注册它。安装与注册流程如下:从 Market 安装 Context7 应用后,前往 Olares Settings > Applications > Context7 > Entrances,选择 Context7 MCP 并复制 Endpoint URL;然后在 OpenCode 的配置文件中以 type: "remote" 的形式把该 Endpoint 注册为 MCP 服务器(在 Endpoint 后追加 /mcp),详见 将 Context7 连接到 OpenCode。
opencode.json 中的条目优先于 OMO 的内置 MCP 服务器。如果你已经在 opencode.json 中有自托管的 Context7 条目,启用 OMO 时会发生什么取决于条目名称:
- 如果名称不是
context7,你的自托管实例和 OMO 的内置context7服务器都会无冲突地加载。 - 如果名称是
context7,它会与 OMO 的内置服务器冲突。在opencode.json中重命名你的条目(例如,改为context7-local),或添加"disabled_mcps": ["context7"]到~/.config/opencode/oh-my-openagent.json以禁用 OMO 的内置服务器。
高级配置
根据你的订阅重新生成 oh-my-openagent.json
预安装的配置启用了所有提供方。如果你只订阅了其中一些,请要求代理重新生成最佳配置。
使用 --claude、--openai、--gemini 和 --copilot 标志(每个设置为 yes 或 no)来匹配你的实际订阅。例如,如果你订阅了 Claude 和 Copilot 但没有订阅 OpenAI 或 Gemini,请在聊天窗口中输入:
Run: npx oh-my-opencode install --no-tui --claude=yes --openai=no --gemini=no --copilot=yes
根据你实际拥有的提供方调整 yes/no。这会更新 ~/.config/opencode/oh-my-openagent.json。
:::info 版本要求 此命令需要 OpenCode 版本 1.4.0 或更高。它会重写所有代理的配置,但只有子代理模型从文件中生效。主代理始终使用你在 OpenCode UI 中选择的模型。 :::
手动覆盖代理的模型
要为代理设置特定模型,请编辑 ~/.config/opencode/oh-my-openagent.json 并更新 model 字段:
{
"agents": {
"sisyphus": { "model": "kimi-for-coding/k2p5" },
"oracle": { "model": "openai/gpt-5.4", "variant": "high" }
}
}
:::warning Explore 和 Librarian 是使用工具的代理。为它们分配高能力模型会增加 token 使用量而不会改善结果。 :::
常见问题
ultrawork 无响应或抛出错误
要求 OpenCode 运行诊断:
Run: npx oh-my-opencode doctor
通常这意味着没有提供方已通过身份验证。
oh-my-openagent.json 中的设置与 UI 中选择的模型有什么关系?
UI 选择控制主代理(你与之聊天的代理)。oh-my-openagent.json 控制子代理,它们是通过 delegate_task 由主代理分派的后台任务。两者是独立的。
我可以同时使用多个提供方吗?
可以,而且推荐这样做。你配置的提供方越多,UI 选择器中可用的模型就越多,子代理委托可用的回退选项也越多。你仍然需要手动为主代理选择模型。
use context7、use grep_app 或 use websearch 不起作用
确认 OMO 已启用。Settings 中的 MCP 标签页应在每个服务器旁边显示绿色圆点。如果服务器是灰色或断开连接的,远程端点可能暂时不可用。稍后再试。
首次启动时插件安装失败
检查 init-packages 容器的 Pod 日志并搜索 oh-my-opencode。如果 npm 下载超时,请确认你的 Olares 可以访问互联网。
重启后我的身份验证数据会保留吗?
会。身份验证存储在 ~/.config/opencode/ 下,重启后自动重新加载。
Olares 升级会覆盖我的配置吗?
不会。oh-my-openagent.json 仅在文件不存在时写入。全局 opencode.json 只管理 Olares 拥有的 plugin 和 instructions 条目。你添加的任何其他条目都会被保留。技能文件(web-preview、system-admin)在每次启动时强制更新到最新版本。
我会知道模型何时自动切换吗?
会。当 runtime_fallback 切换到另一个模型时,会出现一个 toast 通知,显示当前正在使用的模型。
实操建议与注意事项
- 本地模型编排质量有边界:与付费云模型相比,完全在本地模型上运行 OMO 会明显降低编排质量和多代理协作速度。对于实际工作,推荐混合设置:为主代理使用付费云模型,为子代理使用本地模型。
- 模型必须"分层"使用:核心代理(Sisyphus、Hephaestus、Prometheus、Atlas)承担规划、推理和架构决策,应分配 27B 级别的 Qwen3.6-27B;Explore、Librarian 是轻量的搜索类工具代理,分配 9B 级别的 Qwen3.5-9B 即可,避免为工具代理分配高能力模型造成 token 浪费。
- Ollama 模型务必设置
"stream": false:这是避免 Librarian 和 Explore 静默回退到云模型的关键。 - 每次修改配置后重启 OpenCode:
oh-my-openagent.json的改动不会热生效。 - 关注并发限制:为本地模型设置
providerConcurrency与modelConcurrency,防止推理引擎过载。
了解更多
- 将 OpenCode 设置为你的 AI 编码代理:安装 OpenCode 并将其连接到 Ollama 或 OpenAI。
- 使用技能和插件扩展 OpenCode:通过技能和插件添加功能。
- 使用 Context7 将 AI 编码助手连接到最新文档:在 OpenCode 中将自托管 Context7 注册为远程 MCP 服务器。
- OMO 官方还提供架构与代理介绍的概述文档,以及按代理和任务类别匹配模型的参考表,建议在深入调优代理配置时查阅(需访问 oh-my-openagent 项目的 docs/guide 目录)。

