opencode 这个 AI 编程终端我从第一版就开始用了最近把 oh-my-opencode 从 V2.x 一路升到了 V3.0.1。升级过程本身不算复杂一条命令就能拉过去但升级完之后有个特别容易踩的坑原生的 Plan 模式会被新版本的配置优先级逻辑给顶掉你满心欢喜地敲opencode plan结果它直接进了 build 模式计划没生成反而开始改代码。这篇文章就把升级步骤、保留原生 Plan 的方法、升级后的高频问题以及几个把 Plan 用顺手的进阶技巧一次说清楚。如果你还没接触过 oh-my-opencode先给你一句话定位它是 opencode 的“外壳”类似 oh-my-zsh 和 zsh 的关系。opencode 是终端里的 AI 编程助手能读项目、调模型、自动改代码而 oh-my-opencode命令简称omoc帮你统一管理主题、命令、agents 和全局配置升级到 V3.0.1 后它最核心的变化是重写了 agent 的加载顺序和配置合并策略。这个内容适合三类人正准备升级又怕出问题的、升级完发现 Plan 被覆盖的、想借版本升级把 Plan 用得更顺手的老玩家。1. 升级前先弄明白 V3.0.1 到底改了哪些关键东西1.1 一句话说清 oh-my-opencode 和 opencode 的关系很多朋友第一次听说这俩名字时容易懵我打个比方opencode 是一台发动机负责真正干活oh-my-opencode 是装在发动机外面的控制台和仪表盘让你能一键切换主题、快速调取自己写的指令模板、管理多个 agent 配置。平时你输入命令操作的是omoc而omoc底层会调用 opencode 的配置文件去驱动动作。在 V3.0.1 之前我的使用方式很简单装好之后主题用 oh-my-opencode 提供的命令模板自己手写几个放进去agent 基本不管全靠 opencode 自带的内置 agent。V3.0.1 发布后我观察到的最大变化是它默认启用了“用户配置优先于内置 agent”的加载策略。这个改动的初衷是好的让重度用户可以彻底定制自己的 agent 行为但副作用也很明显任何历史残留的、或者新迁移生成的plan定义都会把 opencode 原生的 Plan agent 顶掉。所以开篇我就想强调一个判断标准升级前你一定要先知道自己的配置里有没有一个叫plan的 agent 文件。有这个文件升级后大概率丢原生 Plan没这个文件你才可以在升级后安安静静地享受新版本的红利。这个判断只需要打开配置目录看一下成本极低收益极高。1.2 V3.0.1 的主要变化agent 加载顺序与配置合并策略V3.0.1 的 Release Notes 看下来最影响日常使用的有三条我一条条说人话。第一agent 的加载顺序从“先内置、后用户”变成了“用户先、内置兜底”。老版本里内置的 build、plan、ask、debug 这几个 agent 拥有最高优先级你在用户目录写一个同名 agent 也不会生效。V3.0.1 把这个顺序反过来了只要用户配置里存在同名 agent就以用户配置为准。好处是定制自由度上来了坏处是迁移配置时如果没有清理同名文件原生功能就会悄悄消失。第二配置合并策略从“整个文件覆盖”改成了“按字段深度合并”。以前你自定义一个 agent 配置文件OpenCode 会认为整个文件都归你管现在它会把你写的字段和内置字段做合并。这个策略的好处是你可以只改某个 agent 的 temperature其他参数自动沿用默认值坏处是当你只想覆盖一部分参数时如果不小心写错了类型比如把model写到了顶层而不是 agent 内合并时就会产生一些很隐晦的行为异常。第三插件系统的依赖管理重做了。V3.0.1 对插件声明了更严格的依赖版本老插件如果没有跟上升级后可能直接不加载表现出来就是主题失效、命令丢了一部分。很多人升级完发现“我的快捷键怎么没了”多半不是 opencode 的问题而是 oh-my-opencode 里的某个主题或命令插件没被新版本加载。所以升级后做一次omoc doctor这种健康检查应该成为标准动作。1.3 升级前三件套备份、版本核对、干净环境升级前我的固定流程是三件事顺序不能乱。第一件事是备份。先把~/.config/opencode和~/.config/oh-my-opencode这两个目录完整复制一份我用的是带时间戳的目录名比如opencode-backup-20250101。别再问“要不要备份”配置这东西平时不值钱升级一次你就知道它有多值钱。我的习惯是不仅备份还会把自定义的 agent 目录、command 目录单独再打一个 tar 包因为后续排查问题时这个压缩包能让你快速对比升级前后到底多了哪些文件。第二件事是核对版本。运行opencode --version看底层版本再运行omoc --version看外层版本。升级 oh-my-opencode 前先确认你的 opencode 是否满足 V3.0.1 要求的基线版本否则会出现“外壳升了发动机没跟上”的奇葩状态。我在一次升级里就遇到过omoc已经是新版但 opencode 还是旧版导致配置写入格式不兼容终端直接报语法错误。第三件事是准备一个干净测试环境。如果你手里有正在进行的项目别直接在项目目录里升级可以新建一个临时目录把 opencode 的全局配置指过去做一次预演。预演的目的不是跑通流程而是确认“原生 Plan 是否还在”。这一步如果在临时环境里提前发现 Plan 丢失你会有充足时间去查原因而不是在正式项目里手忙脚乱。2. 两种升级方式实测自动脚本和手动迁移2.1 自动升级一条命令适合大多数用户oh-my-opencode 的自动升级很简单终端里执行omoc upgrade脚本会依次做三件事拉取新版本代码、迁移旧配置、重装插件。整个过程大概几分钟中间会有几个交互提示问你是否要覆盖某些配置文件。我实测下来的建议是遇到交互提示时能选“保留原配置”就不要选“重置默认配置”。V3.0.1 的迁移脚本会生成一份新的默认配置但它不会读心术不知道你哪些配置是手工精调过的。选择重置会让你的主题、命令、自定义 agent 全部回到出厂状态丢失原生 Plan 的问题反而被掩盖了因为自定义 plan 也被一起删了表面上一切正常实际上你丢的是自己的定制资产。自动升级完成之后先别急着关终端。执行一次omoc doctor看健康状态再执行omoc plugin list确认插件加载情况。如果doctor报告有红色错误项先解决掉再继续否则后面排查问题的时候很多现象都会互相干扰。这里还有一个容易忽略的点自动升级脚本结束后会提示你“重新打开终端或 source 配置文件”。这一步别偷懒因为 V3.0.1 会更新 shell 的补全脚本和 PATH 注入逻辑不 source 的话你敲opencode plan时可能还是带着旧环境变量表现就是命令能进但加载的配置是旧的。2.2 手动升级四步走适合定制过大量配置的用户自动升级适合大多数人但如果你像我一样自定义了几十个 command 模板和七八个 agent 定义我建议你走手动升级。手动升级不会自动迁移配置所有文件变动都尽在掌控反而更稳。第一步更新 oh-my-opencode 本体。如果你是通过 Git 方式安装的进到安装目录执行git pull拉到最新 tag如果用的是包管理器就执行对应的包更新命令。这一步完成后先不要做任何配置迁移直接检查新版的默认配置模板长什么样心里有个底。第二步安装依赖并重新构建。很多 V2.x 时代的插件在 V3.0.1 下依赖版本需要更新执行项目自己的依赖安装命令把node_modules刷新一遍。如果项目里有构建脚本也一并执行否则新版代码可能引用到旧的编译产物报一些莫名其妙的模块找不到错误。第三步做配置迁移。omoc提供migrate子命令它会扫描旧配置目录帮你把命令和 agent 文件搬到新目录结构下。这一步最关键的动作是迁移完后立刻打开 agent 目录排查有没有生成plan.md或plan相关的文件。V3.0.1 的迁移脚本会有选择地把某些旧的自定义命令当作 agent 来迁移我亲眼见过它把一个旧命令模板plan-steps迁移成了planagent直接把原生 Plan 干掉了。第四步启动一次完整的功能验证。验证清单我固定是三条opencode plan能进入计划模式opencode build能进入执行模式omoc theme list能列出你之前安装的主题。这三个命令分别覆盖了 agent 加载、命令分发、插件主题三条链路任何一条失败都说明迁移中有东西没对齐。2.3 升级后的基线检查先确认原生命令还在不在不管你是自动升级还是手动升级升级后我强烈建议做一次基线检查而且要在任何实际项目里开工之前做。基线检查第一条命令opencode agent list看看输出里有没有plan。注意看有没有其他名字里带plan的自定义 agent比如plan-v2、planner这些不会覆盖原生 Plan但会在你按 Tab 补全时干扰你选错 agent。基线检查第二条命令直接运行opencode plan观察它的行为。正常情况下你会看到 opencode 进入计划模式只分析文件、生成计划不会写任何代码文件。如果你发现它直接开始改代码或者提示找不到 plan agent那就是原生 Plan 已经被覆盖了接着看第三章的解决方法。基线检查第三条命令omoc config list把当前生效的配置键值对打印出来重点看有没有agent.plan或agents.plan这类字段。这条命令能帮你确认是用户配置里的哪个文件在起作用比打开文件一个个查要快得多。我每次升级完都会把这份输出保存下来当作本次升级的“配置快照”后面调坏了还能对照着还原。3. 保留原生 Plan 的三个关键技巧3.1 原生 Plan 是什么为什么升级会把它搞丢先明确一点我们说的“原生 Plan”指的是 opencode 内置的 plan agent不是 oh-my-opencode 提供的任何插件或模板。这个内置 agent 的职责是在不修改项目文件的前提下分析需求、拆解任务、输出实现计划。它和 build agent 是互补关系build 负责动手plan 负责动脑。为什么升级后它会丢根源就是 1.2 里说的加载顺序反转。V3.0.1 里任何用户级、项目级配置下的plan定义优先级都高于内置 agent。而 oh-my-opencode 老版本在初始化时如果检测到你曾经自定义过和规划相关的命令会在配置目录里留一个plan文件这个文件在 V2.x 时代毫无威胁因为当时内置 agent 优先升级到 V3.0.1 后它摇身一变就成了“用户定义 agent”直接把原生 Plan 顶替了。还有一个隐蔽来源是插件。有些第三方插件为了在规划阶段注入自己的 prompt会主动声明一个planagent 来覆盖内置行为。在 V2.x 时代这类插件是没法生效的V3.0.1 之后它们突然有了“实权”升级完 Plan 被换掉你甚至都意识不到是哪个插件干的。所以排查思路要清晰先看自己的 agent 目录里有没有plan文件再看插件列表里有没有声明过 plan 相关能力的插件。如果没有自定义文件也没有插件那就检查迁移脚本有没有自作主张生成同名文件。按这个顺序查基本五分钟内能找到元凶。3.2 配置里给原生 Plan 留一条“安全通道”保留原生 Plan原则很简单不要在用户级和项目级配置里留下任何名为plan的自定义 agent。但如果你确实想扩展规划能力也别直接改名顶替我推荐三条实际可行的路径。第一条路径检查并清理同名文件。打开~/.config/opencode/agent目录如果看到plan.md或plan.json直接把它改名成plan-custom.md或者移到~/.config/opencode/command下面当成普通命令。这样既保住了你的自定义规则又不会覆盖原生 Plan。同理检查项目根目录的.opencode目录有时候项目级的 agent 定义也会造成同样的干扰。第二条路径利用配置合并的“软开关”。如果你用的版本支持按字段合并可以在配置里只给 plan agent 加一些轻量参数但不提供完整定义比如设定它的默认温度更低一些。这种写法不会生成一个覆盖型 agent只是给内置 plan 加修饰原生行为保存完好。具体配置名以omoc config list里显示的键为准各小版本可能略有差异。第三条路径也是最推荐的把扩展内容放到别处让原生 Plan 留在原位。你想注入的行业规范、项目约定可以写进项目里的AGENTS.md这个文件本来就会被所有 agent 读取你想要的自定义规划步骤可以做成一个普通的 command 模板比如/plan-detail在进入原生 Plan 后再调用它补充细节。这样无论 oh-my-opencode 怎么升级你都不需要跟内置 agent 抢名字原生 Plan 永远健在。3.3 让 Plan 和大上下文模型、Token 配额协同工作保留住原生 Plan 之后另一个常见问题浮现出来Plan 模式怎么配置模型才能既规划得完整又不把 Token 额度烧得太快先解释一个现象Plan 阶段往往是最消耗上下文的阶段。因为 agent 要读取项目结构、核心文件、需求描述然后才能输出一份像样的实现计划。如果你的模型上下文窗口太小比如只有几十 K它读几个文件就满了计划质量会很差。我实测下来规划大型功能时使用支持长上下文的模型比如千问的长上下文版本效果明显更好它能把项目里多个关键模块一次性读进来给出的改动方案更连贯。具体到 oh-my-opencode 的使用上你可以在配置里给 plan agent 单独绑定一个大上下文模型给 build agent 绑定一个更快更便宜的模型。这样规划阶段冲上下文容量执行阶段冲速度和成本各得其所。opencode 支持按 agent 指定 model只要你的 API 渠道支持多个模型这个方案是立竿见影的。再说 Token 配额。很多模型的 API 是按计划套餐计费的也就是标题里常说的 token plan。同一个 API Key 在 Plan 阶段消耗会比 build 阶段大很多因为计划输出通常很长而且每轮要携带大量项目上下文。如果你发现升级到 V3.0.1 后同样的项目跑下来 Token 用量涨了 30% 左右别慌很可能是新版本默认在 Plan 阶段注入了更详细的项目树信息属于正常现象。对策是给 Plan 阶段单独准备一个 Key 或配额或者把规划任务拆分成多次小任务避免一次性读入整个项目。平时我遇到那种“this account is ineligible for higher rate limits”之类的报错第一反应都是先去检查账户套餐和当前额度而不是怀疑配置出错了。在 V3.0.1 下同时用大上下文模型和长规划输出时触发限流的概率会明显上升提前把规划和执行拆到不同额度下能省掉很多中途卡壳的麻烦。4. 升级后高频问题和排查实录4.1 升级完opencode命令消失了这是升级后最常见的现象没有之一。很多人升级完 omoc然后发现直接在终端里敲opencode报“command not found”第一反应是卸载装坏了其实大概率是 PATH 被新版本的安装脚本重置了。排查第一步检查安装目录是否存在。如果你用 Git 方式安装目录就在原处如果用了包管理器先确认包列表里有没有 opencode。目录还在的话多半是 shell 配置文件里的 PATH 没刷新。我的处理方法是重新 source 一下配置文件再开一个新的终端窗口测试。如果新窗口里能正常使用说明只是缓存问题顺手把 shell 的补全缓存清掉即可。排查第二步确认是不是软链接失效。有些安装方式会在/usr/local/bin或用户 bin 目录下创建软链接指向实际执行文件升级脚本重装时可能把旧的软链接删了又没建新的。用which opencode和ls -l看一下当前路径指向哪里如果链接断了重新建一个就行。排查第三步如果上面都正常还是找不到命令那就检查安装脚本有没有因为权限问题没有完成。看到安装日志里有 failed、permission 之类的关键词直接以当前用户的权限重新执行安装脚本然后再次验证。别在这个问题上死磕太久命令消失基本都是环境变量或软链接问题正常情况下十分钟内能解决。4.2 Plan 模式不生效一进去就变成 build 模式这个问题是本文主角症状很典型运行opencode plan没有进入计划模式终端直接变成了 build 模式开始调用工具改文件。我在 3.2 里给了预防方法这里给出升级后已经中招的排查顺序。第一步运行opencode agent list看输出中是否有两个plan。如果只有一个plan而且来自自定义配置那就确认是覆盖没跑了。如果连plan都没有说明内置 agent 列表可能出了异常先检查 opencode 本体版本是否满足 V3.0.1 的要求再检查是不是插件系统把内置 agent 过滤掉了。第二步检查配置优先级。打开~/.config/opencode/agent目录把plan开头的文件全部列出来。如果存在plan.md直接把它改名或者移到备份目录。为了不留隐患我还会检查一下项目级.opencode/agent目录项目里如果有团队共享的 plan 定义也会顶掉全局的原生 Plan。第三步禁用可疑插件做对照实验。如果你装了多个插件可以用omoc plugin disable逐个禁用每禁用一个就试一次opencode plan。如果禁用某个插件后 Plan 恢复正常就是这个插件在作怪要么升级插件要么弃用。我遇到过的一个案例是某个状态栏插件为了显示当前模式硬生生注册了一个 plan agent禁用后一切恢复让我哭笑不得。还有一个“临时救命”的手段直接用完整参数指定 agentopencode --agent plan。这个命令会绕过默认的 agent 选择逻辑强制走内置 Plan。它不能解决根本问题但能在你单步调试时确认内置 agent 本身没坏排除最坏的情况。真正彻底解决还是要把自定义的plan文件挪走让名字干干净净地留给原生 Plan。4.3 模型报配额和限流是不是升级升坏了升级到 V3.0.1 之后有一部分用户会遇到 API 层面的报错最常见的是提示账户没有资格获得更高速率限制。很多人第一反应是 oh-my-opencode 配置有问题但这类问题的根因通常不在 opencode 这一层而是在 API 配额和套餐本身。先说明为什么升级后更容易碰到这个报错。V3.0.1 在 Plan 阶段默认注入的项目上下文更完整导致单次请求的 Token 消耗变大单位时间内的请求频率也可能变高。如果你的账户本就处在免费档或试用档一次大上下文请求就可能撞上速率限制于是出现“升级前好好的升级后天天报错”的错觉。处理思路分两条线。一条线是检查 API 账户的套餐状态看是免费额度用完了还是账单信息不全导致无法升级到更高档位还是触发了新账号的冷却期。另一条线是降低请求体积比如在配置里限制 plan agent 一次最多读取多少文件、设置更简短的项目说明模板。这些限制能明显减小单次请求的大小在没提升配额前先把频率降下来。我更推荐的做法是给 Plan 阶段单独配一个额度充足的 Key避免占满执行阶段的额度。想想看规划阶段读一堆文件、输出一长串计划动不动就把日配额烧掉一大半轮到 build 真正干活时反而没额度了这个体验非常差。分开之后规划可以放心大胆地读文件执行也能稳定地跑完两不耽误。这里也顺便说一句有些报错文案跟限流提示长得像但实际上是因为模型名称配置错了API 侧返回了不存在的型号。排查时先重新检查配置里的模型名是否和账户可用列表一致再去看配额问题顺序别颠倒。4.4 一眼定位问题速查表我把升级到 V3.0.1 以来遇到的高频问题整理成一张速查表方便你遇到情况时快速对照排查。现象最可能原因优先处理方式opencode命令找不到PATH 未刷新或软链接失效重新 source 配置文件检查并重建软链接opencode plan进入 build 模式自定义 plan agent 覆盖内置把 agent 目录下的plan文件改名或删除升级后主题/快捷键丢失插件依赖版本不满足 V3.0.1执行omoc doctor和omoc plugin list检查模型报限流或资格错误账户配额不足或单次请求过大检查 API 套餐给 Plan 单独配置 Key配置项改了不生效配置合并顺序与预期不符用omoc config list查实际生效键名迁移后自定义命令消失迁移脚本变更了目录结构对比备份目录手动搬回 command 文件这张表里最想让你记住的是第二行Plan 不生效永远先去看有没有同名 agent 文件别去翻别的配置因为 V3.0.1 的加载顺序决定了这就是头号原因。我的经验是排查这类问题不要靠猜直接开目录列表看到一个算一个比反复试命令有效得多。5. 把 Plan 用顺手的几个进阶玩法5.1 给 Plan 绑一个顺手快捷键和别名原生 Plan 保住之后接下来就是怎么用得舒服的问题。我最推荐的是给 Plan 绑定一个快捷键。在 opencode 的配置里键绑定是支持自定义的你可以把某个组合键绑定到 plan agent这样在项目里随手按下就能进入规划模式不用每次敲完整命令。我自己是把AltP绑定到 Plan把AltB绑定到 build两个模式之间切换非常顺滑。刚开始可能不习惯但用两三天之后就会形成肌肉记忆比在命令行里敲 agent 名字快得多。绑定完记得检查一下和系统快捷键有没有冲突我遇到过AltP被终端模拟器截获导致 opencode 根本没收到按键的情况调整后就好了。如果还在用别名方式也可以在omoc的命令别名里加一个短命令比如把p映射到opencode plan。设置完成并生效后在项目目录里输入p就进入 Plan 模式输入b就进入 build效率提升是很明显的。不过要注意别名别起得太短或太通用避免和项目里的其他命令冲突我曾经用pl当别名结果和某个项目的自定义脚本撞了折腾了好一会儿。5.2 用 hooks 把 Plan 输出变成可执行任务卡Plan 模式有个天生的问题它生成计划但计划只停留在对话流里。模型上下文一滚动前面规划的内容可能就被冲掉了等你执行到一半再回头看发现和最初的计划有出入。我的解决方案是加一个 hook让 Plan 模式每次输出计划时自动把内容落盘成一份 Markdown 任务清单。opencode 支持事件钩子配置在 plan 模式完成一轮输出时把返回的消息追加写入项目下的.tasks/todo.md。配置思路大致如下hooks: PostToolUse: - match: plan/src command: bash -c cat /dev/stdin .tasks/todo.md上面这只是简化示例实际使用时我建议在脚本里做一次消息过滤只保留 Plan 的模式、任务列表、涉及文件这三个关键部分避免把无关内容也写进去。比如用一个小脚本判断本轮消息是否来自 plan agent是的话再追加写入。这个习惯坚持两周后你会发现自己做项目的节奏清晰很多。每次编码前先跑 Plan得到一份任务卡然后照着任务卡逐项 build。中途想调整时再跑一次 Plan 更新任务卡。这样即使模型上下文丢了或者对话自动清理了你的计划还在磁盘上不会前功尽弃。对长周期项目来说这个价值怎么强调都不过分。5.3 升级后的日常维护与长期习惯最后分享几个升级后养成的日常维护习惯都是踩坑换来的。第一个习惯是升级前必做配置快照。我用omoc config list把生效配置导出来和备份目录一起存起来。这样升级后如果发现行为不对可以快速 diff 到底哪些配置变了。这个习惯帮我节省了大量对比时间强烈建议你也试试。第二个习惯是升级后固定跑一遍“原生功能三连”opencode plan、opencode build、opencode ask。三个命令一起测任何覆盖问题都会第一时间暴露。这个方法已经帮我截获了两次潜在问题都是 plan 被覆盖的隐患在它影响到正式项目之前就处理掉了。第三个习惯是关注新版本的配置模板。每次升级后我都会花几分钟看看新版本生成的默认配置模板长什么样特别留意 agent 加载顺序和相关注释。因为 V3.0.1 这类大版本迭代往往不只是新增功能还会改变既有默认行为看懂模板比看什么总结文章都管用。说到最后我个人在实际操作中的体会是升级工具最怕的不是升级本身而是升级后那些无声无息的行为变化。V3.0.1 是一次值得升级的大版本但它把 agent 加载顺序反转等于让每个用户重新掌握了配置主动权。你只要记住一件事自定义 agent 不要跟内置的 plan 抢名字把原生 Plan 留在原位剩下的新特性都可以放心玩。这比我之前写过的任何技巧都重要。