oh-my-opencode 插件
oh-my-opencode 插件
参考来源:https://ohmyopenagent.com/、https://github.com/code-yeongyu/oh-my-openagent
1. 它是什么
oh-my-opencode 是围绕 OpenCode CLI 构建的一套增强层,用来补齐多 Agent 编排、类别化执行、技能系统、内置 MCP、钩子链、后台任务、tmux 面板协作等能力。
从官方资料看,这个项目目前更常用的正式名称是 Oh My OpenCode,并且仓库已经迁移到 oh-my-openagent 命名体系。也就是说:
- 历史名称:
oh-my-opencode - 当前仓库主名:
oh-my-openagent - 常见 npm 包名:
oh-my-opencode、oh-my-openagent - GitHub 仓库:
code-yeongyu/oh-my-openagent
如果你在社区帖子、脚本或旧教程里看到 oh-my-opencode,通常仍然指的是同一个体系。
2. 它解决什么问题
原生 OpenCode 已经具备 Agent、工具、规则与 MCP 能力,但在重度使用场景里,很多人还会继续补以下东西:
- 更强的主编排 Agent
- 更细的任务类别拆分
- 更容易复用的技能体系
- 更明确的钩子、通知与恢复机制
- 更方便的并行子任务与后台任务工作流
- 更顺手的 tmux / 浏览器自动化 / Git 辅助能力
oh-my-opencode 本质上就是把这些工程化能力整合成一层“增强插件/增强框架”,让 OpenCode 更像一个完整的多 Agent 编码工作平台,而不只是一个单点问答式 CLI。
3. 适合谁用
适合以下人群:
- 已经在日常开发中稳定使用 OpenCode
- 希望把一个大任务拆给多个 Agent 并行执行
- 需要更细粒度的 Agent 分类与模型路由策略
- 想要在项目内沉淀技能、命令、规则和自动化流程
- 希望把调研、实现、审查、验证、通知串成闭环
如果你刚开始接触 OpenCode,建议先熟悉原生 opencode 的基础配置、Provider 连接、AGENTS.md、权限控制,再引入 oh-my-opencode,这样理解成本更低。
4. 安装前准备
4.1 基础要求
根据官方资料,推荐先满足以下条件:
- 已安装 OpenCode CLI,版本建议
>= 1.0.150 - 本机能正常运行
opencode - 至少有一类可用模型来源,例如 Anthropic、OpenAI、Google、Copilot 或兼容接入
- 对项目级配置与用户级配置目录有基本认知
4.2 建议提前准备好的东西
- 一个真实项目目录,用于落地
.opencode/配置 - 你打算使用的模型来源与订阅信息
- 是否要启用 tmux、技能、浏览器自动化、Git 辅助等扩展
5. 安装方式
5.1 交互式安装
官方推荐命令:
# Bun
bunx oh-my-opencode install
# npm
npx oh-my-opencode install
这类方式会进入交互式流程,逐步询问你是否启用 Claude、OpenAI、Gemini、Copilot、技能、tmux 等选项。
5.2 非交互式安装
如果你要在脚本、自动化环境或 AI Agent 里安装,通常使用非交互方式更合适:
bunx oh-my-opencode install --no-tui \
--claude=yes \
--openai=no \
--gemini=yes \
--copilot=no
常见参数如下:
| 参数 | 可选值 | 说明 |
|---|---|---|
--no-tui | 无 | 关闭交互界面,适合自动化 |
--claude | yes / no / max20 | 是否接入 Claude;max20 通常表示 Max 20x 模式 |
--openai | yes / no | 是否接入 OpenAI/ChatGPT Plus |
--gemini | yes / no | 是否接入 Gemini |
--copilot | yes / no | 是否接入 GitHub Copilot |
--opencode-zen | yes / no | 是否启用 OpenCode Zen 相关来源 |
--zai-coding-plan | yes / no | 是否启用 Z.ai Coding Plan |
--opencode-go | yes / no | 是否启用 OpenCode Go |
--tmux | yes / no | 是否启用 tmux 集成 |
--skills | yes / no | 是否安装推荐技能 |
--reset | 无 | 强制覆盖已有配置 |
--dry-run | 无 | 只演练,不实际写入 |
5.3 安装后通常会发生什么
安装脚本一般会做这些事情:
- 写入或更新
oh-my-opencode配置文件 - 写入 Agent、Category、Skill、Hook、MCP 相关默认配置
- 为 OpenCode 工作流注入增强提示与命令
- 在支持的环境中接入 tmux / 浏览器自动化 / Git 辅助能力
如果你已有人手维护的 OpenCode 配置,建议先备份再安装,或者先使用 --dry-run 看一遍会发生什么。
6. 安装完成后怎么确认是否生效
你可以按下面顺序检查:
6.1 检查配置文件
确认以下路径里是否出现 oh-my-opencode 配置:
- 项目级:
.opencode/oh-my-opencode.jsonc - 项目级备选:
.opencode/oh-my-opencode.json - 用户级:
~/.config/opencode/oh-my-opencode.jsonc - 用户级备选:
~/.config/opencode/oh-my-opencode.json - Windows 用户级:
%APPDATA%\opencode\oh-my-opencode.jsonc - Windows 用户级备选:
%APPDATA%\opencode\oh-my-opencode.json
6.2 检查 OpenCode 会话里的能力变化
进入项目后启动 opencode,重点观察是否出现这些变化:
- 可以使用更多命名 Agent,例如
@oracle、@librarian、@explore - 可以使用类别驱动的
task(...) - 出现技能、后台任务、通知、恢复等增强行为
- 具备更多 Slash Command,例如
/init-deep、/handoff、/refactor
6.3 检查配置补全
如果你在配置文件中加了:
{
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json"
}
多数支持 JSON Schema 的编辑器会直接给出字段补全与类型提示,这通常也说明配置路径与格式已经接通。
7. 核心使用方式
7.1 直接用主编排 Agent
安装完成后,最常见的思路不是“把它当一个独立命令学一遍”,而是继续使用 OpenCode,但让增强后的 Agent 体系接管工作流。
例如:
- 复杂端到端任务,交给
sisyphus - 深入修 Bug,交给
hephaestus或deep类别 - 查资料,交给
librarian - 搜代码结构,交给
explore
7.2 用 task(...) 做类别化执行
典型风格如下:
task({
category: "visual-engineering",
load_skills: ["frontend-ui-ux", "playwright"],
prompt: "Add a responsive dashboard card grid",
run_in_background: true
})
这个调用体现了 oh-my-opencode 的核心思想:
- 先按任务类型选类别,而不是先纠结具体 Agent 名
- 再按领域加载技能
- 然后决定同步执行还是后台执行
7.3 用后台任务做并行调研或并行实现
task({
subagent_type: "explore",
load_skills: [],
description: "Find auth patterns",
prompt: "Search the repo for auth middleware, token parsing, and error handling",
run_in_background: true
})
任务启动后,可以再通过:
background_output(task_id="bg_xxx")
取回结果。
7.4 常见增强命令
| 命令 | 作用 |
|---|---|
ultrawork / ulw | 启动更强的自动推进模式 |
@oracle "问题" | 让 Oracle 做架构/调试咨询 |
@librarian "问题" | 做文档、实现样例、外部参考检索 |
@explore "问题" | 做代码结构与上下文搜索 |
/init-deep | 初始化更完整的 AGENTS 结构 |
/refactor <目标> | 用预设工作流做重构 |
/handoff | 生成上下文交接文档 |
/stop-continuation | 停止延续或循环机制 |
8. 配置文件位置与优先级
官方支持项目级和用户级两套配置,优先级通常是:项目级覆盖用户级。
8.1 推荐优先使用的路径
| 优先级 | 路径 | 说明 |
|---|---|---|
| 1 | .opencode/oh-my-opencode.jsonc | 项目级首选 |
| 2 | .opencode/oh-my-opencode.json | 项目级备选 |
| 3 | ~/.config/opencode/oh-my-opencode.jsonc | 用户级首选 |
| 4 | ~/.config/opencode/oh-my-opencode.json | 用户级备选 |
| 5 | %APPDATA%\\opencode\\oh-my-opencode.jsonc | Windows 用户级首选 |
| 6 | %APPDATA%\\opencode\\oh-my-opencode.json | Windows 用户级备选 |
8.2 推荐配置策略
- 团队公共规则放项目级
- 个人模型偏好放用户级
- 涉及仓库内技能、命令、LSP、自定义路径时优先使用项目级
- 需要跨仓库复用的个人偏好放用户级
9. 配置文件格式与最小模板
9.1 JSONC 格式
官方配置支持 JSONC,也就是带注释的 JSON。常见能力包括:
//单行注释/* ... */块注释- 尾随逗号
这比纯 JSON 更适合团队长期维护。
9.2 最小示例
{
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
"agents": {
"sisyphus": {
"model": "anthropic/claude-opus-4-6",
"variant": "max"
}
},
"categories": {
"quick": {
"model": "openai/gpt-5.4-mini"
}
},
"disabled_hooks": [],
"disabled_mcps": [],
"disabled_skills": [],
"disabled_commands": [],
"experimental": {
"task_system": false,
"aggressive_truncation": false
}
}
10. 顶层配置项总览
下面是写配置文件时最常见的顶层字段。
| 参数 | 类型 | 默认值/常见值 | 作用 |
|---|---|---|---|
$schema | string | Schema URL | 让编辑器具备字段补全和校验 |
agents | object | {} | 覆盖或新增 Agent 配置 |
categories | object | {} | 定义任务类别到模型/工具策略的映射 |
disabled_agents | string[] | [] | 禁用某些 Agent |
disabled_skills | string[] | [] | 禁用某些技能 |
disabled_hooks | string[] | [] | 禁用某些钩子 |
disabled_mcps | string[] | [] | 禁用某些内置 MCP |
disabled_commands | string[] | [] | 禁用某些命令 |
disabled_tools | string[] | [] | 禁用某些工具 |
disabled_categories | string[] | [] | 禁用某些类别 |
hashline_edit | boolean | false | 启用基于 hashline 的编辑能力 |
model_fallback | boolean | false | 开启模型回退机制 |
runtime_fallback | boolean / object | false | 定义运行时回退策略 |
background_task | object | - | 定义后台任务并发与超时 |
sisyphus_agent | object | - | 控制主编排体系 |
sisyphus | object | - | 控制任务系统与存储路径 |
skills | object | - | 技能来源与启用/禁用配置 |
tmux | object | - | tmux 面板行为 |
git_master | object | - | Git 辅助设置 |
comment_checker | object | - | 注释检查器提示设置 |
notification | object | - | 通知开关 |
lsp | object | - | 语言服务器配置 |
browser_automation_engine | object | - | 浏览器自动化提供方 |
experimental | object | - | 实验性能力 |
new_task_system_enabled | boolean | false | 启用新任务系统 |
default_run_agent | string | - | 默认运行 Agent |
auto_update | boolean | true | 自动更新检查 |
10.1 这些顶层字段怎么理解
agents:你想微调某个具体 Agent 时改这里categories:你想按任务类型路由模型时改这里disabled_*:你想把某些默认能力关掉时改这里background_task:你想控制并发或防止模型打爆限额时改这里skills/lsp/tmux:你想把工程能力接进来时改这里experimental:你愿意承担实验特性风险时再打开
11. agents 参数详解
agents 用来覆盖内置 Agent,或者定义你自己的 Agent 变种。
11.1 单个 Agent 支持的常见字段
| 参数 | 类型 | 说明 |
|---|---|---|
model | string | 模型 ID,例如 anthropic/claude-opus-4-6 |
fallback_models | string / string[] | 当前模型不可用时的回退模型 |
variant | string | 常见值如 max、high、medium、low、xhigh |
category | string | 继承某个类别的默认能力 |
skills | string[] | 默认加载的技能 |
temperature | number | 采样温度 |
top_p | number | Top-p 控制 |
prompt | string | 直接替换系统提示 |
prompt_append | string | 在原提示后追加说明 |
tools | object | 精确限制该 Agent 可用工具 |
disable | boolean | 禁用这个 Agent |
mode | string | 运行模式,如 subagent、primary、all |
color | string | UI 颜色,通常是十六进制 |
permission | object | 工具权限控制 |
maxTokens | number | 最大响应 Token |
thinking | object | 扩展思考配置 |
reasoningEffort | string | OpenAI 风格推理强度 |
textVerbosity | string | 文本详细程度 |
providerOptions | object | Provider 特定选项 |
ultrawork | object | Ultrawork 专用设置 |
compaction | object | 上下文压缩相关设置 |
11.2 一个常见例子
{
"agents": {
"sisyphus": {
"model": "anthropic/claude-opus-4-6",
"variant": "max",
"fallback_models": [
"openai/gpt-5.4",
"google/gemini-3.1-pro"
],
"prompt_append": "Prefer detailed verification before completion.",
"skills": ["git-master"],
"tools": {
"webfetch": true
}
}
}
}
11.3 什么时候改 agents
适合这些场景:
- 你想让某个 Agent 固定走指定模型
- 你要给某个 Agent 绑定专属技能
- 你要限制某个 Agent 的工具边界
- 你要给特定 Agent 追加额外系统提示
12. permission 参数详解
权限控制通常放在 Agent 配置里,是生产环境里非常关键的一组字段。
12.1 基础形式
{
"agents": {
"explore": {
"permission": {
"edit": "deny",
"bash": "ask",
"webfetch": "allow",
"task": "ask",
"doom_loop": "ask",
"external_directory": "ask"
}
}
}
}
12.2 常见取值
| 值 | 含义 |
|---|---|
allow | 直接允许 |
ask | 执行前询问 |
deny | 完全禁止 |
12.3 bash 的高级写法
bash 除了写成统一策略,还可以按命令粒度细分:
{
"agents": {
"explore": {
"permission": {
"bash": {
"git": "allow",
"rm": "deny",
"sudo *": "deny"
}
}
}
}
}
12.4 实际建议
- 研究型 Agent 通常
edit: deny - 生产仓库里高危命令建议
ask或deny external_directory不建议默认放开- 如果团队有统一发布/提交规范,可以把
git push、rm、sudo之类单独限制
13. 内置 Agent 列表与职责
根据官方资料,常见内置 Agent 包括:
| Agent | 常见默认模型 | 主要职责 |
|---|---|---|
sisyphus | claude-opus-4-6 | 主编排器,负责总体推进 |
hephaestus | gpt-5.3-codex | 深度工程与验证闭环 |
oracle | gpt-5.4 | 架构建议与复杂调试咨询 |
librarian | gemini-3-flash | 文档、资料、实现样例搜索 |
explore | grok-code-fast-1 | 代码结构探索 |
multimodal-looker | gpt-5.3-codex | 视觉内容读取 |
prometheus | claude-opus-4-6 | 规划与拆解 |
metis | claude-opus-4-6 | 预规划分析 |
momus | gpt-5.4 | 计划审查与质量检查 |
atlas | claude-sonnet-4-6 | 按计划执行 |
sisyphus-junior | 类别决定 | 具体类别任务的执行体 |
这张表不是让你死记,而是帮助你在理解配置时知道“字段会作用到谁”。
14. categories 参数详解
categories 是 oh-my-opencode 的另一条主线:按任务类型路由不同模型和工具策略。
14.1 内置类别
| 类别 | 常见默认模型 | 用途 |
|---|---|---|
visual-engineering | google/gemini-3.1-pro | 前端、UI、动效、设计 |
ultrabrain | openai/gpt-5.4 | 高强度逻辑推理 |
deep | openai/gpt-5.3-codex | 复杂自主实现 |
artistry | google/gemini-3.1-pro | 创意型任务 |
quick | openai/gpt-5.4-mini | 简单任务 |
unspecified-low | claude-sonnet-4-6 | 一般低强度任务 |
unspecified-high | claude-opus-4-6 | 一般高强度任务 |
writing | gemini-3-flash | 文档写作 |
14.2 单个 Category 支持的字段
| 参数 | 类型 | 说明 |
|---|---|---|
model | string | 默认模型 |
fallback_models | string / string[] | 回退模型 |
temperature | number | 采样温度 |
top_p | number | Top-p |
maxTokens | number | 最大 Token |
thinking | object | 扩展思考配置 |
reasoningEffort | string | 推理强度 |
textVerbosity | string | 输出详略 |
tools | object | 工具可用范围 |
prompt_append | string | 类别级提示词追加 |
variant | string | 模型变体 |
description | string | 类别说明 |
is_unstable_agent | boolean | 标记该类别不稳定 |
14.3 一个常见例子
{
"categories": {
"quick": {
"model": "openai/gpt-5.4-mini",
"temperature": 0.2,
"textVerbosity": "low"
},
"visual-engineering": {
"model": "google/gemini-3.1-pro",
"variant": "high",
"prompt_append": "Preserve the existing design system."
}
}
}
15. background_task 参数详解
后台任务决定了并行执行能力,也直接影响模型限流、任务堆积与成本控制。
{
"background_task": {
"defaultConcurrency": 5,
"staleTimeoutMs": 180000,
"providerConcurrency": {
"anthropic": 3,
"openai": 5,
"google": 10
},
"modelConcurrency": {
"anthropic/claude-opus-4-6": 2,
"opencode/gpt-5-nano": 20
}
}
}
字段说明:
| 参数 | 类型 | 说明 |
|---|---|---|
defaultConcurrency | number | 默认并发数 |
staleTimeoutMs | number | 后台任务多久视为陈旧/超时 |
providerConcurrency | object | 按 Provider 限制并发 |
modelConcurrency | object | 按具体模型限制并发 |
建议:
- 有高价模型时,优先限制
modelConcurrency - 多团队共享账号时,优先限制
providerConcurrency - 如果你经常并行开很多调研 Agent,
defaultConcurrency不建议无限放大
16. sisyphus_agent 与 sisyphus 参数详解
16.1 sisyphus_agent
这组配置用于控制主编排体系是否启用以及采用什么策略:
{
"sisyphus_agent": {
"disabled": false,
"default_builder_enabled": false,
"planner_enabled": true,
"replace_plan": true
}
}
| 参数 | 类型 | 说明 |
|---|---|---|
disabled | boolean | 是否禁用 Sisyphus 编排体系 |
default_builder_enabled | boolean | 是否启用 OpenCode-Builder |
planner_enabled | boolean | 是否启用规划器 |
replace_plan | boolean | 是否替换默认 Plan 流程 |
16.2 sisyphus.tasks
{
"sisyphus": {
"tasks": {
"enabled": false,
"storage_path": ".sisyphus/tasks",
"claude_code_compat": false
}
}
}
| 参数 | 类型 | 说明 |
|---|---|---|
enabled | boolean | 是否开启任务系统 |
storage_path | string | 任务存储目录 |
claude_code_compat | boolean | 是否启用 Claude Code 兼容路径模式 |
如果你想把任务执行过程落地到仓库并长期保留,这组配置非常关键。
17. skills 参数详解
skills 用来声明技能来源、启用关系和单技能的个性化配置。
{
"skills": {
"sources": [
{ "path": "./my-skills", "recursive": true },
"https://example.com/skill.yaml"
],
"enable": ["my-skill"],
"disable": ["other-skill"],
"my-skill": {
"description": "描述",
"template": "自定义提示模板",
"model": "custom/model",
"allowed-tools": ["read", "bash"]
}
}
}
常见字段说明:
| 参数 | 类型 | 说明 |
|---|---|---|
sources | array | 技能源列表,可为本地路径或远程来源 |
enable | string[] | 强制启用的技能 |
disable | string[] | 强制禁用的技能 |
<skillName>.description | string | 技能描述 |
<skillName>.template | string | 自定义提示模板 |
<skillName>.model | string | 指定技能专用模型 |
<skillName>.allowed-tools | string[] | 限制该技能允许使用的工具 |
官方内置技能中,常见的有 playwright、playwright-cli、agent-browser、dev-browser、git-master、frontend-ui-ux 等。
18. tmux、git_master、comment_checker、notification 参数详解
18.1 tmux
{
"tmux": {
"enabled": false,
"layout": "main-vertical",
"main_pane_size": 60,
"main_pane_min_width": 120,
"agent_pane_min_width": 40
}
}
| 参数 | 类型 | 说明 |
|---|---|---|
enabled | boolean | 是否启用 tmux 协作布局 |
layout | string | 布局方式,如 main-vertical、tiled |
main_pane_size | number | 主窗格尺寸百分比 |
main_pane_min_width | number | 主窗格最小宽度 |
agent_pane_min_width | number | Agent 面板最小宽度 |
18.2 git_master
{
"git_master": {
"commit_footer": true,
"include_co_authored_by": true
}
}
| 参数 | 类型 | 说明 |
|---|---|---|
commit_footer | boolean | 是否添加提交页脚 |
include_co_authored_by | boolean | 是否带上 Co-authored-by |
18.3 comment_checker
{
"comment_checker": {
"custom_prompt": "自定义提示词,使用 {{comments}} 占位符"
}
}
| 参数 | 类型 | 说明 |
|---|---|---|
custom_prompt | string | 自定义注释审查提示 |
18.4 notification
{
"notification": {
"force_enable": false
}
}
| 参数 | 类型 | 说明 |
|---|---|---|
force_enable | boolean | 是否强制启用通知 |
19. lsp 与 browser_automation_engine 参数详解
19.1 lsp
{
"lsp": {
"typescript-language-server": {
"command": ["typescript-language-server", "--stdio"],
"extensions": [".ts", ".tsx"],
"priority": 10,
"env": {
"NODE_OPTIONS": "--max-old-space-size=4096"
},
"initialization": {
"preferences": {
"includeInlayParameterNameHints": "all"
}
}
},
"pylsp": {
"disabled": true
}
}
}
单个 LSP 常见字段:
| 参数 | 类型 | 说明 |
|---|---|---|
command | string[] | 启动命令 |
extensions | string[] | 管辖的扩展名 |
priority | number | 优先级 |
env | object | 启动环境变量 |
initialization | object | 初始化参数 |
disabled | boolean | 是否禁用 |
19.2 browser_automation_engine
{
"browser_automation_engine": {
"provider": "playwright"
}
}
| 参数 | 类型 | 说明 |
|---|---|---|
provider | string | 浏览器自动化引擎,常见为 playwright 或 agent-browser |
20. runtime_fallback 与 model_fallback 参数详解
这部分配置决定:当前模型失效、超时或被限流时,系统要不要自动切换模型。
{
"runtime_fallback": {
"enabled": true,
"retry_on_errors": [400, 429, 503, 529],
"max_fallback_attempts": 3,
"cooldown_seconds": 60,
"timeout_seconds": 30,
"notify_on_fallback": true
}
}
字段说明:
| 参数 | 类型 | 默认值/常见值 | 说明 |
|---|---|---|---|
enabled | boolean | false | 是否启用运行时回退 |
retry_on_errors | number[] | [400,429,503,529] | 哪些错误码触发回退 |
max_fallback_attempts | number | 3 | 最多尝试几次 |
cooldown_seconds | number | 60 | 失败模型冷却时间 |
timeout_seconds | number | 30 | 超时时间;0 通常表示关闭 |
notify_on_fallback | boolean | true | 是否通知用户已回退 |
model_fallback 则更像一个总开关,决定是否允许模型回退体系参与运行。
21. experimental 参数详解
实验性字段通常变化最快,升级时最需要复查。
{
"experimental": {
"truncate_all_tool_outputs": false,
"aggressive_truncation": false,
"auto_resume": false,
"disable_omo_env": false,
"task_system": false,
"dynamic_context_pruning": {
"enabled": false,
"notification": "detailed",
"turn_protection": {
"enabled": true,
"turns": 3
},
"protected_tools": ["task", "todowrite"],
"strategies": {
"deduplication": { "enabled": true },
"supersede_writes": { "enabled": true, "aggressive": false },
"purge_errors": { "enabled": true, "turns": 5 }
}
}
}
}
21.1 顶层实验字段
| 参数 | 类型 | 说明 |
|---|---|---|
truncate_all_tool_outputs | boolean | 是否统一截断工具输出 |
aggressive_truncation | boolean | 是否启用更激进的截断策略 |
auto_resume | boolean | 是否允许自动恢复会话 |
disable_omo_env | boolean | 是否关闭 omo-env 注入 |
task_system | boolean | 是否启用实验性任务系统 |
21.2 dynamic_context_pruning
| 参数 | 类型 | 说明 |
|---|---|---|
enabled | boolean | 是否启用动态上下文裁剪 |
notification | string | 提示级别,如 detailed |
turn_protection.enabled | boolean | 是否保护最近若干轮对话 |
turn_protection.turns | number | 保护多少轮 |
protected_tools | string[] | 不参与清理的工具 |
strategies.deduplication.enabled | boolean | 是否做重复内容去重 |
strategies.supersede_writes.enabled | boolean | 是否清理已被后续内容覆盖的写入 |
strategies.supersede_writes.aggressive | boolean | 是否启用激进覆盖策略 |
strategies.purge_errors.enabled | boolean | 是否清理旧错误输出 |
strategies.purge_errors.turns | number | 若干轮后清理错误 |
建议把 experimental 视为“按需启用、升级必复查”的区域。
22. 其它常见顶层区块
22.1 disabled_* 系列
这些字段都很好理解:把默认内置内容局部关闭。
{
"disabled_mcps": ["websearch", "context7"],
"disabled_skills": ["playwright-cli"],
"disabled_agents": ["multimodal-looker"]
}
适用场景:
- 某个 MCP 有安全顾虑
- 某个技能与你团队规则冲突
- 某个 Agent 会带来额外成本或不稳定性
22.2 default_run_agent
用于指定默认运行的 Agent。适合团队内想把工作流统一到某个主 Agent 时使用。
22.3 auto_update
控制是否自动检查更新。如果你们团队版本固定、需要稳定性高于新特性,可以考虑关闭后自己控版本。
23. 内置 MCP、Hook 与能力生态
23.1 常见内置 MCP
| MCP | 作用 | 默认状态 |
|---|---|---|
websearch | 实时网络搜索 | 启用 |
context7 | 官方文档查询 | 启用 |
grep_app | GitHub 代码搜索 | 启用 |
禁用方式示例:
{
"disabled_mcps": ["websearch", "context7"]
}
23.2 常见内置 Hook
官方资料里常提到这些 Hook:
todo-continuation-enforcercontext-window-monitorsession-recoverysession-notificationcomment-checkergrep-output-truncatortool-output-truncatordirectory-agents-injectordirectory-readme-injectorrules-injectorthink-modekeyword-detectorralph-loopauto-update-checkerhashline-read-enhancerhashline-edit-diff-enhancer
这部分能力不一定需要你逐个手配,但理解它们有助于排查“为什么这轮行为和原生 OpenCode 不太一样”。
24. 环境变量与回退链
24.1 常见环境变量
| 变量 | 说明 |
|---|---|
OPENCODE_CONFIG_DIR | 覆盖 OpenCode 配置目录 |
24.2 模型优先级与回退思路
官方资料里提到过一条常见的来源优先级链:
Native (anthropic/, openai/, google/) > Kimi for Coding > GitHub Copilot > Venice > OpenCode Zen > Z.ai Coding Plan
它表达的是一个总体思路:优先走原生 Provider,其次再落到兼容层或替代来源。
25. 推荐配置示例
下面给一个更适合团队落地的样例:
{
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
"agents": {
"sisyphus": {
"model": "anthropic/claude-opus-4-6",
"variant": "max",
"fallback_models": [
"openai/gpt-5.4",
"google/gemini-3.1-pro"
]
},
"explore": {
"permission": {
"edit": "deny",
"bash": "ask",
"webfetch": "allow"
}
}
},
"categories": {
"quick": {
"model": "openai/gpt-5.4-mini",
"textVerbosity": "low"
},
"visual-engineering": {
"model": "google/gemini-3.1-pro",
"variant": "high"
},
"writing": {
"model": "google/gemini-3-flash"
}
},
"background_task": {
"defaultConcurrency": 4,
"providerConcurrency": {
"anthropic": 2,
"openai": 4,
"google": 6
}
},
"skills": {
"sources": [
{ "path": "./.opencode/skills", "recursive": true }
]
},
"tmux": {
"enabled": true,
"layout": "main-vertical",
"main_pane_size": 60
},
"runtime_fallback": {
"enabled": true,
"max_fallback_attempts": 2,
"notify_on_fallback": true
},
"disabled_mcps": [],
"disabled_skills": [],
"disabled_hooks": []
}
这个样例的思路是:
- 主编排用最强模型
- 简单任务与视觉任务分别路由到更合适的模型
- 研究型 Agent 不允许直接改文件
- 并发受控,避免成本和限流失控
- 项目内技能独立维护
26. 一套推荐使用流程
如果你是第一次正式把它引入项目,可以按下面顺序落地:
- 先确认原生 OpenCode 已能正常使用
- 用
bunx oh-my-opencode install --dry-run预演安装 - 选用
.opencode/oh-my-opencode.jsonc作为项目级配置入口 - 先只启用主 Agent、Category、基础 Skill
- 再逐步接入 tmux、后台任务、MCP、LSP、浏览器自动化
- 最后再考虑打开
runtime_fallback和experimental
这样做的好处是:一旦出现问题,你更容易知道是哪一层配置引起的。
27. 常见问题与排查建议
27.1 安装后没有生效
优先检查:
- 是否真的安装到当前 OpenCode 使用的配置目录
- 项目级配置是否覆盖了用户级配置
- 文件是否是合法 JSONC
- 当前 OpenCode 版本是否过旧
27.2 Agent 行为不符合预期
优先检查:
- 有没有
prompt_append或prompt覆盖 - 是否命中了
category - 是否被
disabled_agents或disabled_tools影响 - 是否走了
fallback_models
27.3 并行任务太多导致成本或限流异常
优先检查:
background_task.defaultConcurrencyproviderConcurrencymodelConcurrencyruntime_fallback是否导致额外重试
27.4 升级后配置不兼容
建议做法:
- 保留
$schema - 升级后先对照官方
configuration.md - 对
experimental区块逐项复查 - 如果旧教程里用的是
oh-my-opencode,优先去仓库确认是否已迁移到oh-my-openagent
28. 官方参考资料
- 官方站点:https://ohmyopenagent.com/
- GitHub 仓库:https://github.com/code-yeongyu/oh-my-openagent
- npm:https://www.npmjs.com/package/oh-my-opencode
- 安装指南:https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md
- 配置参考:https://github.com/code-yeongyu/oh-my-openagent/blob/dev/docs/reference/configuration.md
- 功能参考:https://github.com/code-yeongyu/oh-my-openagent/blob/dev/docs/reference/features.md
- JSON Schema:https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json
29. 最后怎么理解它
如果只用一句话概括:
oh-my-opencode 不是简单给 OpenCode 加几个命令,而是把 OpenCode 变成一套更完整、更工程化、更适合多 Agent 协作的增强工作流。
对于个人开发者,它提升的是效率与自动化程度;对于团队场景,它提升的是复用性、可控性和可维护性。
如果你接下来要继续深入,建议下一步结合本知识库中的 OpenCode Agent 选择指南一起看,这样会更容易把“配置怎么写”和“任务怎么分配”连起来理解。
30. 相关阅读
Superpowers 插件— 强制软件工程纪律的技能框架,与 Oh-My-OpenCode 配合使用效果更佳
如果你已经理解了 Oh-My-OpenCode 负责的是 Agent 编排、任务拆分、技能装载和基础设施增强,那么下一步很适合继续看 Superpowers:它解决的是“Agent 应该按什么工程纪律工作”的问题。
