企业官网建设流程全解析

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，禁用后一切恢复，让我哭笑不得。

还有一个“临时救命”的手段，直接用完整参数指定 agent：opencode --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 以来遇到的高频问题整理成一张速查表，方便你遇到情况时快速对照排查。

这张表里最想让你记住的是第二行：Plan 不生效，永远先去看有没有同名 agent 文件，别去翻别的配置，因为 V3.0.1 的加载顺序决定了这就是头号原因。我的经验是，排查这类问题不要靠猜，直接开目录列表，看到一个算一个，比反复试命令有效得多。

5. 把 Plan 用顺手的几个进阶玩法

5.1 给 Plan 绑一个顺手快捷键和别名

原生 Plan 保住之后，接下来就是怎么用得舒服的问题。我最推荐的是给 Plan 绑定一个快捷键。在 opencode 的配置里，键绑定是支持自定义的，你可以把某个组合键绑定到 plan agent，这样在项目里随手按下就能进入规划模式，不用每次敲完整命令。

我自己是把Alt+P绑定到 Plan，把Alt+B绑定到 build，两个模式之间切换非常顺滑。刚开始可能不习惯，但用两三天之后就会形成肌肉记忆，比在命令行里敲 agent 名字快得多。绑定完记得检查一下和系统快捷键有没有冲突，我遇到过Alt+P被终端模拟器截获导致 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 留在原位，剩下的新特性都可以放心玩。这比我之前写过的任何技巧都重要。