最近把 oh-my-opencode 从 V2.x 一路升到 V3.0.1升完以后发现一个很扎心的问题我之前精心调好的原生 Plan 模式被升级脚本直接重置成了默认模板平时用的“先规划后编码”的流程一下子失灵了。折腾了一整个下午翻源码、看 diff、比对配置文件总算把升级逻辑和 Plan 的存储机制捋清楚了。这篇就把升级到 V3.0.1 的完整方法、保留原生 Plan 的小技巧以及我踩过的一堆坑全部整理出来给同样在用 oh-my-opencode 的朋友一个参考。先说清楚本文适合谁你已经在用 oh-my-opencode或 opencode 生态想升级到 V3.0.1并且对 Plan 模式有自定义需求——不管是用它做代码规划、需求拆解还是接大模型 API 跑“先出方案再动手”的工作流这篇文章都能帮你少走弯路。1. 升级前先搞清楚三件事版本、目录、脚本逻辑很多人升级失败不是命令错了而是没搞清楚项目里到底什么会被改动。oh-my-opencode 作为一个用来美化、增强、统一管理 opencode 配置的框架升级时最危险的动作就是“覆盖配置目录”。所以在执行任何升级命令之前我强烈建议你先花五分钟做三件事看当前版本、找 Plan 相关文件、读一遍升级脚本。1.1 怎么看当前版本和执行环境先确认你当前用的是哪个渠道安装的 oh-my-opencode。常见的安装方式无非三种npm 全局包、git clone 到本地、或者通过 opencode 自身的插件机制加载。不同的安装方式升级命令完全不同备份策略也有差别。如果是 npm 安装直接跑npm list -g --depth0 | grep oh-my-opencode或者查版本oh-my-opencode --version如果是 git clone 安装去你 clone 的目录下看git log --oneline -5 git describe --tags我自己的环境是“git clone 到~/.oh-my-opencode再通过 shell 配置 source 加载”这种老派方式升级反而最可控——因为我可以手动控制 pull 的时机不会像 npm 一样自动帮你覆盖。但代价是一旦忘掉看 changelog踩坑概率也不小。1.2 原生 Plan 到底存在哪里这是整个升级里最关键的一步你要保留的“原生 Plan”到底是以什么形式存在的根据我扒源码的结论opencode 本身的 Plan 有两种存在形态第一种是 opencode 内置的规划模式plan mode。它写在 opencode 的源码里是一种系统级行为通常不会被 oh-my-opencode 直接覆盖。你升级 oh-my-opencode 之后只要 opencode 本身的版本不变原生 plan mode 一般都还在。第二种是用户自定义的 Plan 指令文件。这个就危险了——oh-my-opencode 会把 Plan 相关配置以plan.md、AGENTS.md、或者opencode.json里的agent字段形式放到配置目录里。升级 V3.0.1 时如果升级脚本检测到“配置目录版本过旧”默认动作是“迁移并覆盖”你的自定义 Plan 内容就会被默认模板顶掉。所以在升级前请先确认你的 Plan 配置到底在哪find ~/.config/opencode -name *.md -o -name *.json -o -name *.mdx 2/dev/null find ~/.oh-my-opencode -iname *plan* 2/dev/null把输出结果记下来这些都是你升级后的“重点保护区”。1.3 升级脚本的覆盖逻辑要先读一遍很多人升级前从来不看脚本直接执行npm install -g oh-my-opencodelatest结果升级完发现配置全没了。V3.0.1 的升级脚本里有一段逻辑很坑它会先备份现有的opencode.json然后生成一份“推荐配置”如果你的旧配置和新配置存在字段冲突它默认采用“新配置优先”而不是“保留用户自定义”。怎么提前发现这个问题如果你是从 git 仓库安装的直接看git diff V2.x..V3.0.1 -- scripts/install.sh如果是 npm 安装去 npm 包的安装目录里找scripts/下的迁移脚本npm root -g ls -la $(npm root -g)/oh-my-opencode/scripts/读一下里面的migrate.sh或者postinstall.js重点看有没有mv、cp、rm -rf出现在配置目录的操作。我那次就是因为在migrate.sh里看到了这么一行cp $CONFIG_DIR/opencode.json $CONFIG_DIR/opencode.json.bak # 然后直接用默认配置覆盖 install_default_config $CONFIG_DIR才意识到不备份的话自定义 Plan 必死无疑。2. 核心细节为什么升级 V3.0.1 会碰掉原生 Plan理解了上面三个前置检查下面要说的就是问题的核心V3.0.1 的升级逻辑到底动了什么为什么偏偏是 Plan 容易丢。2.1 升级脚本的“默认配置覆盖”机制V3.0.1 这个版本官方为了统一不同用户的基础体验在升级脚本里内置了一套“默认配置初始化”逻辑。简单说就是升级时会检查配置目录下的关键文件是否完整如果发现缺少新版本要求的字段或文件就会自动补齐如果是旧版本字段冲突则以新版本为准。这听起来很合理问题出在“补齐”的动作上。它检测到plan.md存在时并不会去读你写了什么而是直接判断“版本太旧”然后把它替换成新版本自带的 plan 模板。后果就是你精心设计的“需求澄清-方案对比-风险提示-实施步骤”全被清空回到默认的“简单三步走”。这里我打个比方这就像你装修房子装修队说“帮你免费升级厨房”结果进门以后不管你原来的橱柜合不合用直接砸了给你装一套标准款。你原来的定制收纳全没了就剩一个看起来挺新但啥也装不下的空柜子。2.2 Plan 的两种存在形态内置规划模式 vs 自定义指令文件要避免被覆盖得先知道自己在用的是哪一种。内置规划模式原生 Plan是 opencode 进程启动时通过系统提示词注入的。它一般长这样用户输入任务Agent 先输出一段“计划”包括理解目标、列出步骤、识别风险然后停下来等用户确认确认后再执行。这个模式即使升级 oh-my-opencode 也不会丢因为它在 opencode 的核心代码里。自定义指令文件则是另一种你在opencode.json里通过plan字段或instruction字段给 Agent 指定“规划阶段的额外指令”。比如我习惯在里面写{ plan: { enabled: true, instruction: 在动手写任何代码之前必须先输出1. 需求理解2. 技术选型3. 风险点4. 文件改动清单。用户确认后才能开始编码。, model: qwen-plus } }这种自定义配置是存在opencode.json里的而 V3.0.1 升级时恰好会重建这个文件。如果你没有提前备份自定义 Plan 就随着文件覆盖一起灰飞烟灭了。2.3 备份与恢复的完整命令很多人升级前会备份但备份得不完整——只备份了opencode.json忘了备份plan.md和AGENTS.md。这里给出我实测下来还算稳健的一套备份方案。升级前执行TS$(date %Y%m%d_%H%M%S) mkdir -p ~/opencode_backup_$TS cp -r ~/.config/opencode ~/opencode_backup_$TS/opencode_config cp -r ~/.oh-my-opencode ~/opencode_backup_$TS/oh_my_opencode_src # 如果用了 git直接打 tag 最省事 cd ~/.oh-my-opencode git tag backup_before_v3.0.1升级后如果发现 Plan 被重置恢复也很简单cp ~/opencode_backup_$TS/opencode_config/opencode.json ~/.config/opencode/opencode.json cp ~/opencode_backup_$TS/opencode_config/plan.md ~/.config/opencode/plan.md千万别图省事把整个opencode_config直接cp -r回去——那样会把 V3.0.1 新增的默认配置也一并回滚掉容易造成新旧版本配置格式不兼容。最好是“按文件恢复”只回滚你自定义过的部分。3. 实操V3.0.1 升级全流程与保留原生 Plan 的小技巧这一节是全文的干货核心。我给的方案不是“升级完再补救”而是从源头避免 Plan 被覆盖并且提供一个完整可落地的升级路径。3.1 标准升级步骤npm 与 Git 两种方式先看 npm 安装的情况升级命令很简单但顺序有讲究。# 1. 先备份命令见上文务必执行 # 2. 再升级 npm install -g oh-my-opencodev3.0.1 # 3. 升级完成后先不要立刻重启终端 # 4. 检查配置目录下有没有新生成 .bak 文件 ls -la ~/.config/opencode/npm 升级方式的核心风险在于 postinstall 脚本会在安装阶段就触发配置迁移。所以我在执行升级命令前会把配置目录临时改个名字等安装完成后再手动合并mv ~/.config/opencode ~/.config/opencode_old npm install -g oh-my-opencodev3.0.1 # 安装完成后生成默认配置 oh-my-opencode init # 把自定义文件拷贝回新配置目录 cp ~/.config/opencode_old/opencode.json ~/.config/opencode/opencode.json cp ~/.config/opencode_old/plan.md ~/.config/opencode/plan.md这种“先隔离再合并”的方式可以保证 V3.0.1 的默认配置先完整生成然后你的自定义配置再叠加进去不会产生字段缺失导致的启动报错。git 安装方式就更顺手了cd ~/.oh-my-opencode git fetch --tags git checkout v3.0.1 # 让升级脚本跑一遍 ./install.sh在跑install.sh之前给当前分支打个备份 tag或者开一个自定义分支专门放自己的 Plan 配置比什么都管用。3.2 保留原生 Plan 的五个小技巧下面这几个技巧是我实测过、并且在升级 V3.0.1 后成功保住自定义 Plan 的方法。你不需要五个全用挑一两个适合自己的就行。第一个技巧叫“文件锁”。在主配置目录里新建一个.keep_plan文件然后在升级脚本的备份逻辑里加一个判断如果检测到.keep_plan存在就强行跳过 plan 相关文件的覆盖。当然这个技巧要求你能读得懂升级脚本并且愿意去改它。我是在install.sh里找到这样一段if [ -f $CONFIG_DIR/.keep_plan ]; then echo 检测到 .keep_plan保留自定义 plan 配置... cp $CONFIG_DIR/plan.md $BACKUP_DIR/plan.md.custom fi然后后面覆盖完再恢复if [ -f $BACKUP_DIR/plan.md.custom ]; then cp $BACKUP_DIR/plan.md.custom $CONFIG_DIR/plan.md fi这算是我目前觉得最“原生”的保留方案因为是从脚本内部做防护而不是靠外部补救。第二个技巧是用 git 分支隔离。把 Plan 相关文件单独放到一个目录比如~/.config/opencode/custom/然后用opencode.json里的include字段引入。这样升级脚本就算重建opencode.json你只需要在新配置里重新加一行 include 就行{ include: [custom/plan.json] }Plan 文件本身根本不在升级脚本的管辖范围内自然不会被覆盖。第三个技巧是符号链接。把你真正的 Plan 配置放在一个不参与升级的目录比如~/my_config/opencode_plan.md然后在配置目录里做软链ln -sf ~/my_config/opencode_plan.md ~/.config/opencode/plan.md升级脚本即使把plan.md删了重建只要你的软链路径没有变新生成的plan.md依然会指向~/my_config/opencode_plan.md你自己的内容一点不少。第四个技巧和“软链”思路类似但更激进——直接把配置目录设置为 git 仓库cd ~/.config/opencode git init git add . git commit -m before upgrade to v3.0.1升级后如果发现 Plan 被接管直接git diff plan.md git checkout -- plan.md这个技巧的好处是你不光能防 Plan 被覆盖还能看到升级脚本到底改了你哪些配置非常直观。第五个技巧比较取巧升级前把自定义 Plan 内容写进环境变量里然后通过opencode.json的模板语法在升级后重新注入。比如定义一个变量export MY_PLAN_RULES1. 先写方案2. 确认后再动手然后在配置里引用。这样哪怕plan.md被重置成默认模板你的核心规则也已经不在文件里而是在环境变量里升级脚本管不到。3.3 升级后的验证清单升级完不是看一眼版本号就完事的。我给自己定了一个验证清单每次都照着过oh-my-opencode --version # 确认输出 v3.0.1然后看 Plan 是否还在opencode --help | grep -i plan接着用一条最简单的提问来实际测一次 Plan 行为比如输入“帮我写一个读取 CSV 文件的 Python 脚本”看 Agent 在动手前有没有先输出计划结构。最后检查opencode.json的原始内容有没有被改动diff opencode.json opencode.json.bak | head -50只要这四步全过基本可以放心你的原生 Plan 没有被碰掉。4. 常见问题与排查实录升级这件事不怕出问题怕的是出了问题不知道怎么排查。我把这一周在 V3.0.1 上遇到的高频问题集中整理成一张表再挑两个典型场景展开说说。4.1 升级后 Plan 模式消失或回退到默认这是最经典的症状输入指令后Agent 不再输出“计划”直接就开始写代码或者输出的计划非常简陋完全没有自定义内容。排查思路从外到内分三步。第一步确认 opencode 自身的 plan mode 开关还在不在opencode config get plan.enabled如果返回false或者空值说明不是 oh-my-opencode 的问题是 opencode 的配置被重置了。恢复方法是在opencode.json里重新加一行{ plan: { enabled: true } }第二步检查 oh-my-opencode 是否加载了你的plan.md。直接看启动日志oh-my-opencode doctor这个命令会列出当前加载了哪些配置文件、哪些指令被注入了。我升级后第一次跑doctor发现plan.md显示的是“default template”而不是我备份里的自定义文件这时候就知道是被覆盖了。第三步如果确认是文件被覆盖直接按 2.3 节的“按文件恢复”命令操作恢复后重启终端再跑一遍doctor看看文件路径是否已经指向你的自定义版本。4.2 模型与 Token Plan 配置异常Qwen 场景实录升级到 V3.0.1 以后很多人会遇到一个和 Plan 看起来没关系、但实际上影响很大的问题模型 API 配置失效。尤其是那些接了千问 Qwen 的用户升级后会发现 Plan 阶段调用模型时报 401 或者 model not found。我自己也遇到过。我原本在opencode.json里配的是{ provider: { qwen: { api_key: sk-xxx, base_url: https://dashscope.aliyuncs.com/compatible-mode/v1, model: qwen-plus } } }升级后这个配置还在但 Plan 阶段就是不生效。排查到最后发现是 V3.0.1 把model字段改成了models数组格式。新版里如果你只写了旧的model字段Plan 阶段会找不到可用模型。正确写法是{ provider: { qwen: { models: [qwen-plus, qwen-max], default: qwen-plus } } }另外Qwen 不同规格模型对应的上下文窗口大小不一样比如qwen-plus和qwen-max就有明确的 token 上限差异具体数字请以官方文档为准。这里要提醒的是Plan 阶段是要吃上下文窗口的——你让 Agent 先写方案、列步骤、拆风险这一整段规划文本会占用不少 token。我用qwen-plus的时候规划阶段的上下文窗口还够用一旦把 Plan 的指令写得太长比如超过 2000 token部分模型的上下文窗口就会显得局促容易触发截断。解决方案有两个方向一是换用上下文窗口更大的模型规格二是精简plan.md里的指令把冗余的描述性文字去掉只保留必要的结构化要求。4.3 升级后快捷键失效被忽略的“小手术”这个坑我能踩到纯属意外。V3.0.1 的升级脚本里有一条命令会自动重写keybindings.json。我在升级前自定义的“快速进入 Plan 模式”快捷键被静默移除了。症状是按 CtrlP 没反应但是按文档里新给的快捷键又能用。排查方法很简单打开keybindings.json看看里面plan相关的绑定还在不在grep -i plan ~/.config/opencode/keybindings.json如果发现 old_key 被改掉了手动加回来{ command: opencode.plan.toggle, key: ctrlp }这里有个更稳的做法别把快捷键绑定写在全局keybindings.json里而是写进你自己的 profile 文件然后通过opencode.json的profiles字段加载。这样升级脚本再怎么重写全局配置也动不了你的 profile。5. 关于 token plan 与 Plan 模式之间的关系前面聊了很多升级和保留配置的操作最后再单独说一个经常被混淆的概念很多人一看到“Plan”就以为只能用来做代码规划其实在升级到 V3.0.1 之后Plan 的用途可以做得更宽。我在实际使用中发现Plan 模式本质上是给 Agent 提供了一个“先思考后执行”的缓冲层。这个缓冲层尤其适合接入追求高性价比 token 计费方案的场景。比如你使用的是按 token 计费的服务方Plan 阶段相当于让模型先生成一份“浓缩思考”用户确认后再进入完整执行整体消耗其实比“上来就生成一大段代码”更省 token。具体操作上你可以把 Plan 当成一道闸门先在 Plan 阶段用较小的模型跑方案比如qwen-plus确认方向没问题以后再切到更强的模型去执行。这样既不浪费强模型的 token 配额又能保证方案质量。升级到 V3.0.1 之后配置多模型切换比旧版简单不少直接在opencode.json里定义两个 model然后分别在 plan 和 act 阶段引用即可{ plan: { model: qwen-plus }, act: { model: qwen-max } }如果你用的是火山引擎这类提供 token plan 的服务思路也是一样Plan 阶段用小规格、长上下文的模型做入口把关执行阶段再切到专项能力更突出的模型。这样配合 V3.0.1 的多模型配置能力可以让整体成本更可控。再分享一个我踩过坑之后留下的习惯升级后不要只盯着新功能第一时间去看provider配置。新版对 API 兼容性更挑剔一些老接口的 base_url 或者鉴权方式在新版里可能不再被默认支持。我那次就是因为在 Qwen 的兼容模式下忘了更新 api_key 的读取方式导致 Plan 阶段一直是 401还以为是升级把原生 Plan 弄丢了排查了半天才发现是模型配置的问题。最后一个小建议如果你和我一样属于“Plan 重度用户”升级前最好把plan.md和opencode.json同时纳入 git 管理并且养成升级前git commit的习惯。这样不管升级脚本做什么你都可以在五分钟内恢复到升级前的状态。我这次升级 V3.0.1 之所以能快速定位问题靠的就是升级前打的那个 backup tag没有它我可能得花一个晚上去翻默认模板“考古”自己原来写了什么规则。