企业官网建设流程全解析

1. 升级前必须做好的三件事：备份、版本确认与依赖检查

升级这种事，最怕的就是"看起来成功了，一用就炸"。我这次从旧版本往 V3.0.1 升，第一反应不是急着跑安装命令，而是先把当前环境摸清楚。

1.1 先确认你现在到底用的哪个版本

很多人升级失败，根源在于根本不知道自己当前装的是哪个版本、什么渠道装的。OpenCode 的安装方式五花八门——有通过 npm 全局装的，有通过 Homebrew 装的，也有直接拉 GitHub Release 二进制跑的。不同渠道对应的升级路径完全不一样。

我在升级前习惯先跑一条命令：

opencode --version

如果这条命令报错，说明你的 PATH 环境变量有问题，或者安装本身就不完整。如果输出版本号，把它记下来。这里有个小细节：OpenCode 的版本号有时候会带后缀，比如v3.0.1-beta或者v3.0.1-canary，这类预发布版本和生产版本的结构不同，升级逻辑也要区分对待。

另外还有一条命令值得跑：

which opencode

这条命令能告诉你 opencode 可执行文件到底被装到了哪里。我遇到过一种情况：用户同时通过 npm 和 Homebrew 装了 OpenCode，which opencode指向的是 Homebrew 的路径，但升级时却只升了 npm 的那个，结果怎么升版本号都不变。这种"双安装"冲突是升级问题里最隐蔽的坑之一。

1.2 备份现有配置和会话数据

OpenCode 的配置和会话数据默认存放在用户目录下的.opencode文件夹中。升级前务必备份，因为 V3.0.1 对配置文件的解析逻辑有过调整，旧配置里某些字段在新版本下可能不再被识别，甚至会导致启动崩溃。

备份命令很简单：

cp -r ~/.opencode ~/.opencode_backup_$(date +%Y%m%d)

如果你在使用 Oh My OpenCode 这个辅助层，还需要额外备份它的配置目录。Oh My OpenCode 通常会维护自己的配置入口、主题文件、模型路由规则等，这些内容跟原生 OpenCode 的配置是分开存的。建议把~/.oh-my-opencode或者它对应的配置目录一起备份。

提示：备份这件事，升级前做一次，升级后验证完再删。别嫌麻烦，我见过不止一次因为配置迁移失败导致全部会话记录丢失的情况。会话记录这种东西，丢了就是丢了，找不回来。

1.3 检查 Node.js 版本和系统依赖

如果你是通过 npm 安装的 OpenCode，V3.0.1 对 Node.js 的版本有明确要求。这里我踩过一个很典型的坑：升级完 OpenCode 之后，npm 报了一堆依赖错误，最后排查了半天才发现是 Node.js 版本太旧。

比较稳妥的做法是先把 Node.js 升到 LTS 版本（建议用 Node 20 或更高）。如果你用的是 nvm，可以先执行：

nvm install --lts nvm use --lts node --version

确认 Node 版本没问题之后，再执行升级操作。如果你在 Linux 服务器上通过编译方式升级过 Node.js，还遇到过"gcc 升级后为啥还是旧版本"这类问题，那通常是因为编译缓存或者 PATH 优先级的问题，建议优先使用二进制包或者包管理器安装，省心很多。

2. V3.0.1 升级实操：三种常见安装渠道的对应步骤

OpenCode 的安装渠道不同，升级命令也完全不同。我按最常见的三种渠道分别说明，你对照自己的安装方式选一种执行即可。

2.1 通过 npm 全局安装的升级方式

这是最常见的一种方式。升级前先确认自己确实是通过 npm 安装的——你可以在终端输入npm list -g opencode-ai或者直接看which opencode的路径是否指向 npm 的全局目录。

确认之后执行：

npm install -g opencode-ai@latest

这里有个非常重要的细节：opencode-ai是 OpenCode 在 npm 上的包名，不是opencode。如果你直接运行npm install -g opencode，装到的可能是另外一个完全不相干的包。这个坑非常多人踩，升级完发现 opencode 命令还是老版本，其实是因为装错了包。

装完之后，用opencode --version验证版本号。如果版本号没变，大概率是 npm 缓存问题，可以执行：

npm cache clean --force

然后再重新安装。注意，npm cache clean --force会清理整个 npm 缓存，副作用是后续安装其他包时会重新下载依赖，速度会慢一些，但为了排除缓存干扰是值得的。

2.2 通过 Homebrew 安装的升级方式

macOS 用户常用 Homebrew 安装 OpenCode。升级命令为：

brew update brew upgrade opencode

如果brew upgrade的时候提示"already installed"但版本没变，可以尝试：

brew uninstall opencode brew install opencode

不过这里要提醒一句：卸载重装会导致配置目录的默认行为发生变化。Homebrew 安装的 OpenCode，配置目录通常仍然在~/.opencode，一般不会丢失，但以防万一，卸载前还是把配置目录备份一遍。

2.3 通过二进制 Release 安装的升级方式

如果你是从 GitHub Release 页面下载二进制文件手动安装的，那升级方式就是去 Release 页面下载新版本，覆盖旧的可执行文件。注意，覆盖前最好把旧的可执行文件改名留作备份，比如：

mv /usr/local/bin/opencode /usr/local/bin/opencode_old

然后把新下载的二进制文件放到/usr/local/bin/opencode，并且赋予执行权限：

chmod +x /usr/local/bin/opencode

这种安装方式没有包管理器的版本追踪机制，全靠手动管理，更要注意路径覆盖的准确性。如果安装完成后执行opencode --version仍然显示旧版本，九成是 PATH 中还有另一个 opencode 可执行文件优先被加载了，回到第 1.1 节说的which opencode去排查。

3. 保留原生 Plan 的核心原理与配置迁移要点

关于这版升级，我看到社区里讨论最多的就是"保留原生 Plan"。很多人升级到 V3.0.1 后发现，自己原本在旧版本里用 Plan 功能配置好的内容全部失效了，或者界面里 Plan 选项不见了，其实本质上是版本升级后配置结构变化导致的兼容问题。

3.1 原生 Plan 到底是什么，它和插件结构的 Plan 有什么区别

OpenCode 的"Plan"指的是它内置的规划/计划执行模式——用户给 AI 一个高级目标，OpenCode 会先生成一个执行计划，再按步骤执行。这种模式在复杂任务拆解时非常好用，相当于给 AI 一个"先思考再动手"的路径。

问题在于，V3.0.1 对插件系统的加载逻辑做了调整。有些用户在旧版本里通过第三方插件实现的"Plan"功能，升级后插件失效，导致 Plan 消失。还有一部分用户使用的是 OpenCode 原生自带的 Plan 能力，升级后因为配置字段迁移不完整，导致 Plan 相关的设置丢失。

这里我用一个生活化的类比来解释：原生 Plan 就好比手机自带的计算器，第三方插件实现的 Plan 就像你从应用商店另装的一个计算器 App。升级系统（OpenCode 版本）时，自带的计算器不会丢，但第三方 App 可能因为兼容性问题打不开。所以"保留原生 Plan"的核心，在于确保升级过程中没有把原生自带的 Plan 相关配置文件搞丢或者搞坏。

3.2 升级后 Plan 消失的常见原因排查

按照我实测的经验，升级到 V3.0.1 后 Plan 出现问题的原因基本可以锁定为以下几类：

第一，配置目录中的config.toml或opencode.json里与 Plan 相关的旧字段被新版本标记为废弃，导致加载失败。第二，第三方插件完全覆盖了原生 Plan 的入口，升级后插件加载顺序变化，原生 Plan 入口被隐藏。第三，会话历史数据中保存了旧版的 Plan 执行状态，升级后状态机不兼容，导致 Plan 会话无法恢复。

针对第一个原因，你需要在配置文件中搜索与 plan 相关的关键字，比如plan、planner、plan_mode等，确认有没有使用已经废弃的配置格式。如果发现疑似废弃字段，可以把它们临时注释掉，重启 OpenCode 看 Plan 是否恢复。

针对第二个原因，建议先禁用所有第三方插件，确认原生 Plan 是否恢复。我自己在测试中遇到的情况是：某个主题插件会在侧边栏渲染时覆盖原生 Plan 的按钮，禁用之后立刻恢复。所以排查时别急着动配置，先把插件全部关掉，一个一个加回来，找到冲突源。

3.3 配置迁移的具体操作

如果你在升级前按照第 1.2 节备份了~/.opencode目录，那么迁移就很从容。升级后先用旧备份里的配置启动一次看看，如果启动报错，再用最小化配置逐步加回。

我自己习惯的迁移步骤是：

mv ~/.opencode/config.toml ~/.opencode/config.toml.new cp ~/.opencode_backup_20250101/config.toml ~/.opencode/config.toml

然后用opencode启动，验证 Plan 功能。如果验证正常，再去比较新旧配置文件的差异，一项一项地把旧配置里已经扩展的新功能手动合并回来。这样既保证了原生 Plan 可用，又不会丢失新版本的功能。

这里有一个反直觉的经验：不要直接把旧配置完整覆盖到新版本上。V3.0.1 的配置解析更严格，旧配置里某些为兼容旧版而存在的冗余字段，新版本见到就会直接报错。最优策略永远是"从最小配置开始，逐项加回"。

4. 升级过程中最典型的报错：free tier 限制提示的应对

这轮升级后，很多人在终端里看到了这样一条报错：

error from provider (console): opencode's free tier can only be used from within opencode

这条报错从表面看是在说"OpenCode 的免费额度只能在 OpenCode 内部使用"，但实际含义是：你试图通过一个不被识别的客户端或渠道去访问 OpenCode 的免费额度接口。V3.0.1 加强了对调用来源的校验，任何非 OpenCode 自身进程发起的免费额度请求都会被拒绝。

4.1 什么情况下最容易触发这个报错

根据社区反馈和我的实测，最容易触发这个报错的操作有三类：

第一类，在 VSCode 或其他编辑器里通过某种集成插件去调用 OpenCode 的后端服务，而这套集成方式携带的客户端标识不符合新版本的要求。第二类，环境变量里配置了代理或者重定向规则，导致 OpenCode 的请求被转发到了其他服务，来源校验失败。第三类，你之前通过 CC-Switch 这类工具切换过模型服务商，切换后 Provider 的配置残留导致 OpenCode 误认为请求来源非法。

4.2 针对这个报错的排查步骤

遇到这个报错别慌，按顺序排查：

先确认你是否真的在 OpenCode 的终端/会话中运行。如果你直接在终端敲命令调用了 opencode 的 API 接口，那报错是正常的，因为新版本限制了免费额度的调用来源必须是 OpenCode 自身的交互会话。

再检查环境变量。OpenCode 的请求行为受OPENCODE_PROVIDER、OPENCODE_API_BASE等环境变量影响。如果你之前手动设置过这些变量，先取消设置再试试：

unset OPENCODE_API_BASE unset OPENCODE_PROVIDER

如果是通过 CC-Switch 切换过服务商，建议把 CC-Switch 的配置清掉或者更新到与 V3.0.1 兼容的版本。CC-Switch 本质上是通过改写环境变量或配置文件来切换不同的服务商入口，这跟 OpenCode 的免费额度来源校验天然冲突。

注意：免费额度限制是 OpenCode 服务端的行为，不是本地配置能绕过的。如果你确实需要稳定、无来源限制的使用，考虑配置自己的 API Key 或服务商渠道。凡是声称能"解锁免费额度限制"的第三方工具，都要谨慎评估其安全性和合规性。

5. Oh My OpenCode 的配置保留技巧与自定义项迁移

如果说前面讲的是 OpenCode 本体的升级，那 Oh My OpenCode 就是一个更容易被忽略的部分。它作为 OpenCode 之上的辅助层，负责主题、模型路由、命令增强等能力。升级 OpenCode 后，Oh My OpenCode 如果没跟上，同样会造成功能异常。

5.1 Oh My OpenCode 升级的基本操作

Oh My OpenCode 的升级方式和 OpenCode 安装渠道有关。如果你的 Oh My OpenCode 是通过 npm 安装的，升级命令为：

npm install -g oh-my-opencode@latest

如果它是以仓库形式 clone 到本地的，那就进入仓库目录拉取最新代码：

git pull origin main

然后看它的安装脚本是否需要重新执行，比如：

./install.sh

或者根据项目文档执行对应的 setup 命令。拉取代码后不重新执行安装脚本，是 Oh My OpenCode 升级后失效的最常见原因——文件更新了，但符号链接和配置注入没有重建。

5.2 自定义主题和命令的迁移

V3.0.1 对主题的加载方式有过调整，旧版自定义主题如果直接沿用，可能出现颜色变量不生效的情况。我的建议是：升级后先切回默认主题，确认基础功能正常，再逐步把自定义主题的变量逐个套回来，观察效果。

Oh My OpenCode 的自定义命令通常定义在某个commands目录下，格式一般是 markdown 或者 yaml。旧版本的自定义命令里有少数字段名在 V3.0.1 中会被解析为不同含义，所以升级后务必检查自定义命令是否仍然按照预期行为工作，而不只是看命令是否出现。

5.3 保留原生 Plan 在 Oh My OpenCode 中的注意点

在 Oh My OpenCode 的场景下，保留原生 Plan 的关键是：确保 Oh My OpenCode 的配置没有在入口层覆盖 OpenCode 的 Plan 模式。我在使用中发现，某些 Oh My OpenCode 的配置项会重定义快捷键，如果快捷键映射里恰好覆盖了 Plan 模式的快捷键，就会出现"升级后按快捷键没反应"的情况。

具体排查方式是：检查 Oh My OpenCode 配置里与键位映射相关的段落，看看有没有plan关键字，有的话先删掉或注释，然后重启。如果 Plan 恢复，说明确实是键位冲突。

6. 升级后的功能验证清单：从启动到跑通一次完整 Plan

升级完成、配置迁移完毕，不代表万事大吉。按照我多次升级的经验，一套完整的功能验证清单是必要的，能帮你在使用过程中省掉大量排查时间。

6.1 启动层面的验证

先跑最简单的命令验证程序能否正常启动：

opencode --version opencode --help

版本号确认是 V3.0.1 之后，再执行opencode进入交互界面。重点关注终端是否有报错输出。有时候程序启动看起来正常，但后台会报一些非致命错误，比如某个插件加载失败。这些报错虽然不影响主流程使用，但会隐藏副作用。

6.2 Plan 功能验证

进入交互界面后，直接给 AI 一个适合规划的任务，比如"帮我设计一个 Python 项目的目录结构，并给出实施步骤"。观察它是否先给出计划再逐步执行。如果 AI 直接跳过了计划阶段，说明 Plan 模式可能没有正确启用。

这时候检查配置文件里的默认模式设置。OpenCode 的交互模式有几种，你需要在配置中确认默认启动模式是 Plan 还是别的模式。如果自己不确定配置项怎么写，优先去翻官方文档，别凭记忆猜。

6.3 会话持久化验证

升级最怕的就是旧会话打不开。验证方式很简单：启动 OpenCode 后，在会话列表里找到升级前创建的会话，打开一个看看是否正常加载。如果出现乱码、报错或者空白，说明会话数据的迁移出现了问题。

这种情况通常只能靠备份恢复。所以再次强调：升级前一定要备份~/.opencode目录。会话数据一旦损坏，几乎没有修复手段。

6.4 模型服务验证

先跑一次简单的对话，确认模型响应正常。再跑一个耗时会话，确认多轮对话中上下文没有被截断。如果你配置了多个 Provider，还需要分别验证每个 Provider 是否都能正常切换。这一步容易被忽略——有的人升级后默认 Provider 正常，但切换第二个 Provider 时直接报错，检查发现是新版本改了 Provider 的配置格式。

7. 实操中容易忽略的两个隐藏问题

最后分享两个升级后未必立刻暴露、但会慢慢发酵的隐藏问题。

7.1 环境变量残留导致的间歇性异常

升级后若干天内，如果 OpenCode 偶尔出现奇怪的报错，比如请求超时、服务商跳变，先检查 shell 配置文件（.bashrc、.zshrc等）里是否有旧版本的 OpenCode 环境变量残留。这些变量在升级过程中不会自动清除，会持续影响新版本的运行行为。

可以执行以下命令检查：

env | grep -i opencode

如果看到了相关变量，结合第 4.2 节的方法逐一取消设置。

7.2 升级工具的缓存干扰

无论你用的是 npm、Homebrew 还是直接下载二进制，都可能遇到缓存干扰。npm 升级后版本号不变的情况我已经在 2.1 节提过；Homebrew 的缓存问题通常表现为下载了新版但链接到旧版；二进制方式则容易因为浏览器下载了旧版本的缓存文件导致覆盖失败。这些问题的排查思路都一样：清理对应工具的缓存，确认下载文件的实际版本，再执行升级。

8. 我的个人体会：升级节奏与回滚预案

作为一个多次折腾过 OpenCode 升级的人，我最想分享的一点是：升级要选时机，不要在大项目进行到一半的时候升级。

V3.0.1 整体是一个稳定性有提升的版本，尤其是插件系统的加载逻辑明显更严谨了。但"更严谨"也意味着以前糊弄过去的配置写法现在可能直接暴露问题。所以如果你手头有正在进行的活跃项目，先把手头的会话收尾，再升级；升级后留出半小时到一小时做功能验证，不要急着立刻投入到新工作中。

回滚预案方面，只要你在升级前做了完整备份，回滚就不复杂。OpenCode 本体可以通过包管理器降级安装，配置文件直接恢复备份。唯一要注意的是：如果你在升级后创建了新会话，又决定回滚，这些新会话在旧版本里大概率无法正常打开。所以在决定回滚之前，想清楚新会话里的内容是否值得保留，需要的话先手动导出。

最后再补充一个小技巧：OpenCode 的配置目录里有一个log子目录，升级后如果遇到任何疑难杂症，先去看最新的日志文件。日志里记录了每个插件的加载结果、每个配置项的解析状态，很多时候报错信息本身并不会显示在终端里，但日志里写得清清楚楚。这个习惯帮我在很多升级问题上节省了大量时间，算是我最想推荐给所有 OpenCode 用户的一条经验。