oh-my-opencode 插件

程小虎2026-03-22 11:20:00

oh-my-opencode 插件

参考来源:https://ohmyopenagent.com/open in new windowhttps://github.com/code-yeongyu/oh-my-openagentopen in new window

1. 它是什么

oh-my-opencode 是围绕 OpenCode CLI 构建的一套增强层,用来补齐多 Agent 编排、类别化执行、技能系统、内置 MCP、钩子链、后台任务、tmux 面板协作等能力。

从官方资料看,这个项目目前更常用的正式名称是 Oh My OpenCode,并且仓库已经迁移到 oh-my-openagent 命名体系。也就是说:

  • 历史名称:oh-my-opencode
  • 当前仓库主名:oh-my-openagent
  • 常见 npm 包名:oh-my-opencodeoh-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关闭交互界面,适合自动化
--claudeyes / no / max20是否接入 Claude;max20 通常表示 Max 20x 模式
--openaiyes / no是否接入 OpenAI/ChatGPT Plus
--geminiyes / no是否接入 Gemini
--copilotyes / no是否接入 GitHub Copilot
--opencode-zenyes / no是否启用 OpenCode Zen 相关来源
--zai-coding-planyes / no是否启用 Z.ai Coding Plan
--opencode-goyes / no是否启用 OpenCode Go
--tmuxyes / no是否启用 tmux 集成
--skillsyes / 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,交给 hephaestusdeep 类别
  • 查资料,交给 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.jsoncWindows 用户级首选
6%APPDATA%\\opencode\\oh-my-opencode.jsonWindows 用户级备选

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. 顶层配置项总览

下面是写配置文件时最常见的顶层字段。

参数类型默认值/常见值作用
$schemastringSchema URL让编辑器具备字段补全和校验
agentsobject{}覆盖或新增 Agent 配置
categoriesobject{}定义任务类别到模型/工具策略的映射
disabled_agentsstring[][]禁用某些 Agent
disabled_skillsstring[][]禁用某些技能
disabled_hooksstring[][]禁用某些钩子
disabled_mcpsstring[][]禁用某些内置 MCP
disabled_commandsstring[][]禁用某些命令
disabled_toolsstring[][]禁用某些工具
disabled_categoriesstring[][]禁用某些类别
hashline_editbooleanfalse启用基于 hashline 的编辑能力
model_fallbackbooleanfalse开启模型回退机制
runtime_fallbackboolean / objectfalse定义运行时回退策略
background_taskobject-定义后台任务并发与超时
sisyphus_agentobject-控制主编排体系
sisyphusobject-控制任务系统与存储路径
skillsobject-技能来源与启用/禁用配置
tmuxobject-tmux 面板行为
git_masterobject-Git 辅助设置
comment_checkerobject-注释检查器提示设置
notificationobject-通知开关
lspobject-语言服务器配置
browser_automation_engineobject-浏览器自动化提供方
experimentalobject-实验性能力
new_task_system_enabledbooleanfalse启用新任务系统
default_run_agentstring-默认运行 Agent
auto_updatebooleantrue自动更新检查

10.1 这些顶层字段怎么理解

  • agents:你想微调某个具体 Agent 时改这里
  • categories:你想按任务类型路由模型时改这里
  • disabled_*:你想把某些默认能力关掉时改这里
  • background_task:你想控制并发或防止模型打爆限额时改这里
  • skills / lsp / tmux:你想把工程能力接进来时改这里
  • experimental:你愿意承担实验特性风险时再打开

11. agents 参数详解

agents 用来覆盖内置 Agent,或者定义你自己的 Agent 变种。

11.1 单个 Agent 支持的常见字段

参数类型说明
modelstring模型 ID,例如 anthropic/claude-opus-4-6
fallback_modelsstring / string[]当前模型不可用时的回退模型
variantstring常见值如 maxhighmediumlowxhigh
categorystring继承某个类别的默认能力
skillsstring[]默认加载的技能
temperaturenumber采样温度
top_pnumberTop-p 控制
promptstring直接替换系统提示
prompt_appendstring在原提示后追加说明
toolsobject精确限制该 Agent 可用工具
disableboolean禁用这个 Agent
modestring运行模式,如 subagentprimaryall
colorstringUI 颜色,通常是十六进制
permissionobject工具权限控制
maxTokensnumber最大响应 Token
thinkingobject扩展思考配置
reasoningEffortstringOpenAI 风格推理强度
textVerbositystring文本详细程度
providerOptionsobjectProvider 特定选项
ultraworkobjectUltrawork 专用设置
compactionobject上下文压缩相关设置

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
  • 生产仓库里高危命令建议 askdeny
  • external_directory 不建议默认放开
  • 如果团队有统一发布/提交规范,可以把 git pushrmsudo 之类单独限制

13. 内置 Agent 列表与职责

根据官方资料,常见内置 Agent 包括:

Agent常见默认模型主要职责
sisyphusclaude-opus-4-6主编排器,负责总体推进
hephaestusgpt-5.3-codex深度工程与验证闭环
oraclegpt-5.4架构建议与复杂调试咨询
librariangemini-3-flash文档、资料、实现样例搜索
exploregrok-code-fast-1代码结构探索
multimodal-lookergpt-5.3-codex视觉内容读取
prometheusclaude-opus-4-6规划与拆解
metisclaude-opus-4-6预规划分析
momusgpt-5.4计划审查与质量检查
atlasclaude-sonnet-4-6按计划执行
sisyphus-junior类别决定具体类别任务的执行体

这张表不是让你死记,而是帮助你在理解配置时知道“字段会作用到谁”。


14. categories 参数详解

categoriesoh-my-opencode 的另一条主线:按任务类型路由不同模型和工具策略。

14.1 内置类别

类别常见默认模型用途
visual-engineeringgoogle/gemini-3.1-pro前端、UI、动效、设计
ultrabrainopenai/gpt-5.4高强度逻辑推理
deepopenai/gpt-5.3-codex复杂自主实现
artistrygoogle/gemini-3.1-pro创意型任务
quickopenai/gpt-5.4-mini简单任务
unspecified-lowclaude-sonnet-4-6一般低强度任务
unspecified-highclaude-opus-4-6一般高强度任务
writinggemini-3-flash文档写作

14.2 单个 Category 支持的字段

参数类型说明
modelstring默认模型
fallback_modelsstring / string[]回退模型
temperaturenumber采样温度
top_pnumberTop-p
maxTokensnumber最大 Token
thinkingobject扩展思考配置
reasoningEffortstring推理强度
textVerbositystring输出详略
toolsobject工具可用范围
prompt_appendstring类别级提示词追加
variantstring模型变体
descriptionstring类别说明
is_unstable_agentboolean标记该类别不稳定

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

字段说明:

参数类型说明
defaultConcurrencynumber默认并发数
staleTimeoutMsnumber后台任务多久视为陈旧/超时
providerConcurrencyobject按 Provider 限制并发
modelConcurrencyobject按具体模型限制并发

建议:

  • 有高价模型时,优先限制 modelConcurrency
  • 多团队共享账号时,优先限制 providerConcurrency
  • 如果你经常并行开很多调研 Agent,defaultConcurrency 不建议无限放大

16. sisyphus_agentsisyphus 参数详解

16.1 sisyphus_agent

这组配置用于控制主编排体系是否启用以及采用什么策略:

{
  "sisyphus_agent": {
    "disabled": false,
    "default_builder_enabled": false,
    "planner_enabled": true,
    "replace_plan": true
  }
}
参数类型说明
disabledboolean是否禁用 Sisyphus 编排体系
default_builder_enabledboolean是否启用 OpenCode-Builder
planner_enabledboolean是否启用规划器
replace_planboolean是否替换默认 Plan 流程

16.2 sisyphus.tasks

{
  "sisyphus": {
    "tasks": {
      "enabled": false,
      "storage_path": ".sisyphus/tasks",
      "claude_code_compat": false
    }
  }
}
参数类型说明
enabledboolean是否开启任务系统
storage_pathstring任务存储目录
claude_code_compatboolean是否启用 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"]
    }
  }
}

常见字段说明:

参数类型说明
sourcesarray技能源列表,可为本地路径或远程来源
enablestring[]强制启用的技能
disablestring[]强制禁用的技能
<skillName>.descriptionstring技能描述
<skillName>.templatestring自定义提示模板
<skillName>.modelstring指定技能专用模型
<skillName>.allowed-toolsstring[]限制该技能允许使用的工具

官方内置技能中,常见的有 playwrightplaywright-cliagent-browserdev-browsergit-masterfrontend-ui-ux 等。


18. tmuxgit_mastercomment_checkernotification 参数详解

18.1 tmux

{
  "tmux": {
    "enabled": false,
    "layout": "main-vertical",
    "main_pane_size": 60,
    "main_pane_min_width": 120,
    "agent_pane_min_width": 40
  }
}
参数类型说明
enabledboolean是否启用 tmux 协作布局
layoutstring布局方式,如 main-verticaltiled
main_pane_sizenumber主窗格尺寸百分比
main_pane_min_widthnumber主窗格最小宽度
agent_pane_min_widthnumberAgent 面板最小宽度

18.2 git_master

{
  "git_master": {
    "commit_footer": true,
    "include_co_authored_by": true
  }
}
参数类型说明
commit_footerboolean是否添加提交页脚
include_co_authored_byboolean是否带上 Co-authored-by

18.3 comment_checker

{
  "comment_checker": {
    "custom_prompt": "自定义提示词,使用 {{comments}} 占位符"
  }
}
参数类型说明
custom_promptstring自定义注释审查提示

18.4 notification

{
  "notification": {
    "force_enable": false
  }
}
参数类型说明
force_enableboolean是否强制启用通知

19. lspbrowser_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 常见字段:

参数类型说明
commandstring[]启动命令
extensionsstring[]管辖的扩展名
prioritynumber优先级
envobject启动环境变量
initializationobject初始化参数
disabledboolean是否禁用

19.2 browser_automation_engine

{
  "browser_automation_engine": {
    "provider": "playwright"
  }
}
参数类型说明
providerstring浏览器自动化引擎,常见为 playwrightagent-browser

20. runtime_fallbackmodel_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
  }
}

字段说明:

参数类型默认值/常见值说明
enabledbooleanfalse是否启用运行时回退
retry_on_errorsnumber[][400,429,503,529]哪些错误码触发回退
max_fallback_attemptsnumber3最多尝试几次
cooldown_secondsnumber60失败模型冷却时间
timeout_secondsnumber30超时时间;0 通常表示关闭
notify_on_fallbackbooleantrue是否通知用户已回退

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_outputsboolean是否统一截断工具输出
aggressive_truncationboolean是否启用更激进的截断策略
auto_resumeboolean是否允许自动恢复会话
disable_omo_envboolean是否关闭 omo-env 注入
task_systemboolean是否启用实验性任务系统

21.2 dynamic_context_pruning

参数类型说明
enabledboolean是否启用动态上下文裁剪
notificationstring提示级别,如 detailed
turn_protection.enabledboolean是否保护最近若干轮对话
turn_protection.turnsnumber保护多少轮
protected_toolsstring[]不参与清理的工具
strategies.deduplication.enabledboolean是否做重复内容去重
strategies.supersede_writes.enabledboolean是否清理已被后续内容覆盖的写入
strategies.supersede_writes.aggressiveboolean是否启用激进覆盖策略
strategies.purge_errors.enabledboolean是否清理旧错误输出
strategies.purge_errors.turnsnumber若干轮后清理错误

建议把 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_appGitHub 代码搜索启用

禁用方式示例:

{
  "disabled_mcps": ["websearch", "context7"]
}

23.2 常见内置 Hook

官方资料里常提到这些 Hook:

  • todo-continuation-enforcer
  • context-window-monitor
  • session-recovery
  • session-notification
  • comment-checker
  • grep-output-truncator
  • tool-output-truncator
  • directory-agents-injector
  • directory-readme-injector
  • rules-injector
  • think-mode
  • keyword-detector
  • ralph-loop
  • auto-update-checker
  • hashline-read-enhancer
  • hashline-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. 一套推荐使用流程

如果你是第一次正式把它引入项目,可以按下面顺序落地:

  1. 先确认原生 OpenCode 已能正常使用
  2. bunx oh-my-opencode install --dry-run 预演安装
  3. 选用 .opencode/oh-my-opencode.jsonc 作为项目级配置入口
  4. 先只启用主 Agent、Category、基础 Skill
  5. 再逐步接入 tmux、后台任务、MCP、LSP、浏览器自动化
  6. 最后再考虑打开 runtime_fallbackexperimental

这样做的好处是:一旦出现问题,你更容易知道是哪一层配置引起的。


27. 常见问题与排查建议

27.1 安装后没有生效

优先检查:

  • 是否真的安装到当前 OpenCode 使用的配置目录
  • 项目级配置是否覆盖了用户级配置
  • 文件是否是合法 JSONC
  • 当前 OpenCode 版本是否过旧

27.2 Agent 行为不符合预期

优先检查:

  • 有没有 prompt_appendprompt 覆盖
  • 是否命中了 category
  • 是否被 disabled_agentsdisabled_tools 影响
  • 是否走了 fallback_models

27.3 并行任务太多导致成本或限流异常

优先检查:

  • background_task.defaultConcurrency
  • providerConcurrency
  • modelConcurrency
  • runtime_fallback 是否导致额外重试

27.4 升级后配置不兼容

建议做法:

  • 保留 $schema
  • 升级后先对照官方 configuration.md
  • experimental 区块逐项复查
  • 如果旧教程里用的是 oh-my-opencode,优先去仓库确认是否已迁移到 oh-my-openagent

28. 官方参考资料


29. 最后怎么理解它

如果只用一句话概括:

oh-my-opencode 不是简单给 OpenCode 加几个命令,而是把 OpenCode 变成一套更完整、更工程化、更适合多 Agent 协作的增强工作流。

对于个人开发者,它提升的是效率与自动化程度;对于团队场景,它提升的是复用性、可控性和可维护性。

如果你接下来要继续深入,建议下一步结合本知识库中的 OpenCode Agent 选择指南一起看,这样会更容易把“配置怎么写”和“任务怎么分配”连起来理解。


30. 相关阅读

  • Superpowers 插件 — 强制软件工程纪律的技能框架,与 Oh-My-OpenCode 配合使用效果更佳

如果你已经理解了 Oh-My-OpenCode 负责的是 Agent 编排、任务拆分、技能装载和基础设施增强,那么下一步很适合继续看 Superpowers:它解决的是“Agent 应该按什么工程纪律工作”的问题。

最近更新 3/22/2026, 10:53:24 AM
目录