Claude Code 迁移 OpenCode 踩坑实录

我的 Claude Code 配置很小，正因如此，它出问题时才让我如此意外。根目录下有一个 CLAUDE.md，旁边放着一个 MEMORY.md，还有一个参考文档文件夹，以及另一个充当规则文件的 CLAUDE.md。这套配置安稳运行了几个月。然后，在我完全没有改动任何东西的情况下，它开始泄漏上下文。

Claude 混淆了这些文件——规则被当成了指令，记忆被当成了参考资料——而且我眼看着每次会话的 token 数量不断攀升。我明明什么都没碰。最令人沮丧的正是这一点：它证明了这套配置从第一天起就很脆弱，只是裂缝过了几个月才显现出来。

所以我换了工具。彻底换了。我把所有文件都带到了 OpenCode，然后开始和它对话。它记得我，却无视了我的指令。

下面就是迁移之后出问题的地方——按影响程度排序，并附上每一项的重建方式。简而言之：迁移不是复制文件，而是重新声明。

出了哪些问题，按影响程度排序

下面的排序依据，是每项故障给我造成了多大损失，而不是它闹出了多大动静。最安静的问题，造成的伤害反而最大。

问题 1——我的指令没有一起迁移过来

OpenCode 加载了我的记忆——它能够正确引用 MEMORY.md 里的笔记和约定。但我在 CLAUDE.md 中定义的规则并没有生效。究竟是当时四月份的 OpenCode 版本根本没有加载这个文件，还是加载后又忽略了它，结果都一样：我的指令没有得到遵守。

等我停下来认真想了想，原因就变得很明显：CLAUDE.md 是 Claude 的规则文件，而 OpenCode 读取的是 AGENTS.md。

从纸面上看，这只是改一行文件名。实际操作中，它却第一次证实了这次迁移本质上是一场翻译，而翻译工作落在了我身上，不是工具身上。

重建方式：在 AGENTS.md 中重新声明你的规则。不要直接复制——要重新声明，因为旧规则里一些原本被默认成立的前提，在新环境中已经成了不可或缺的基础。然后验证这些规则是否真的生效。运行 /init（OpenCode 会读取 CLAUDE.md，并以此生成 AGENTS.md——参见文档），再在一个全新会话中询问 Agent：“我的规则是什么？”如果它不能复述这些规则，就说明规则没有被加载。已加载并不等于会遵守。

问题 2——我让 OpenCode 迁移它前任的配置

我把这次迁移理解成：“带上文件，再告诉新 Agent 我原来有什么。”接着我又多走了一步：我让 OpenCode 替我迁移 skills 和 MCP servers。

让一个工具迁移其前任工具链的问题在于：它不知道自己不知道什么。它无法盘点那些自己从未拥有过的东西。它不知道我的哪些 skills 是不可或缺的，哪些 MCP 我只用过一次便忘了，也不知道配置究竟存放在哪里。它告诉了我它所知道的内容，却无法告诉我遗漏了什么，因为那些缺失的东西从未存在于它的世界里。

重建方式：先盘点。接触新工具之前，列出你实际使用的每一个 skill、命令和 MCP server。趁旧工具仍然可用、还能向它询问时，把这些内容全部写下来。然后有意识地决定哪些需要重建，哪些应该舍弃。这份清单就是迁移计划——没有它，你迁移的只会是那些碰巧幸存下来的东西。

问题 3——成功迁移的东西也悄悄降级了

那些确实迁移过来的 skills，行为也和以前不同。OpenCode 能够读取它们，却会忽略 frontmatter 中的部分内容，包括模型分配、允许使用的工具和参数处理方式。它也不会像 Claude Code 那样自动触发这些 skills；在 OpenCode 中，skills 是按需加载的，只有 Agent 决定调用时才会加载。

整个过程没有大声报错。它们只是变得没那么好用了。这是最糟糕的一类故障：悄无声息的故障。因为只有当你信任某个 skill，而它又悄悄做错事情时，问题才会暴露出来。

这一点甚至已经写进了文档：OpenCode 只识别 skill frontmatter 中的 name、description、license、compatibility 和 metadata（参见 skills 文档），其他所有内容都会被静默忽略。

重建方式：在证明效果一致之前，先假设每个移植过来的 skill 都已经降级。重建你真正会用到的 skills，删除其余内容（后文“重建，不要移植”一节会详细说明）。

问题 4——摩擦成本

你需要按 Tab 键手动切换 plan 和 build 模式，而不是像 Claude Code 那样自动过渡。快捷键不同，滚动行为也不同。这些都不是 bug，但在最初几周里，它们会不断带来一种低强度的“哪里不太对劲”的感觉。

迁移指南里从来不会提到这个问题，因为功能对照表中根本看不到它。这是一种成本，而不是缺陷。

重建方式：像评估学习曲线一样，为适应期预留时间——预计会有两到三周无法顺畅进入工作状态，而不是两天。第一天就把 Claude Code 中最常用的三个快捷键映射到 OpenCode 的对应操作。强迫自己适应变化，不要继续依赖旧的肌肉记忆。

问题 5——它没有影响我，但会影响你：没有自动记忆

OpenCode 没有原生的跨会话记忆。它不会像 Claude Code 那样，悄悄“记得你上周说过什么”。相关功能请求（#20322）仍处于开放状态，尚未发布。

我的 MEMORY.md 能够在迁移后保留下来，是因为它本身就是一个文件。你的记忆未必能留下。如果你一直依赖 Agent 自动记住不同会话中的内容，那么切换工具的那一天，这些记忆就会全部蒸发。

重建方式：为 Agent 准备一份会话日志。在 AGENTS.md 中加入一条指令：

## Session log
At the end of every session, append a short summary to `session-log.md`:
what was done, what's pending, and any decisions made. Never lose a decision.

仅这一条指令，就替代了我失去的静默记忆——而且让我的记忆系统变得更好，因为现在它是显式的、可以通过 grep 搜索的，也能移植到我接下来使用的任何工具中。

我得到了什么（另一面的砝码）

只列出四项故障，却不提任何收益，就成了一篇刻意攻击 OpenCode 的文章。下面是另一半真实情况。

默认权限优先。OpenCode 运行在我自己的硬件上——密钥也由我自己提供。它开箱即用的行为是：执行操作前先征求许可。如果它想读取当前目录之外的文件夹，就会停下来询问。我批准之后，它才继续执行。相比任何基准测试表，这种行为都更快地重建了我对工具的信任。它的限制也必须如实说明：在工作目录内部，默认权限比较宽松；而 .env 文件默认禁止访问——这是正确的默认设置。另外，请保持版本更新：2026-22812 和 22813 这两个 CVE 已经修复，而在一套原本强调 local-first 的配置中，使用过时的 harness 才是最大的风险。

一个密钥，多个模型。我的配置刻意保持简单：内置模型，再加上一枚 OpenRouter API key。一枚密钥就能使用数十个模型。针对某项任务切换模型，只需要改一行配置——不需要更换 harness，不需要新的订阅，也不需要重新走注册流程。用过 Claude Code 之后，那种模型只能取决于 Anthropic 发布了什么的感觉，终于消失了，仿佛天花板被掀开。

真实的成本。2026 年 1 月 9 日，是很多人都记得的日子——那一天，Anthropic 开始限制第三方工具使用 Claude subscription OAuth，并计划在当年四月彻底切断访问。那也是我的项目停摆的一天：我坐下来准备继续两三周前开始的工作，却发现什么也做不了。一个工作日就这样浪费了，项目卡住了，而我付费购买的订阅，也不再以我付费时所期待的方式工作。换到另一边后，我的 token 账单终于变成了一笔可以实际分析和推算的开支，而不是一项要么能用、要么不能用的固定订阅。

真正重要的一条经验：重建，不要移植

有一个完全相反的现象，重塑了我对整件事的理解：我迁移过来的 skills 会悄悄降级，但一个全新安装的 skill 第一次运行就成功了。不需要调试，不需要和 frontmatter 较劲，也没有“为什么这个东西加载不了”的疑问。放进去，调用它，就完成了。

这彻底改变了我看待整个迁移过程的方式。不要移植你的 skills——重建那些你真正使用的 skills。

这不仅适用于 skills，也适用于规则、记忆和 MCP 配置。它还解释了为什么移植过来的东西会有不同的行为：harness 的影响比人们愿意承认的更大。同一个模型，换一个 wrapper，结果就会出现可衡量的差异——在 2026 年的一项基准测试中，OpenCode 用 7 分钟完成了任务，零错误；Claude Code 使用同一模型耗时 14 分钟，并犯了两个错误。另一组来自 tracker 的 SWE-bench 数据显示，同一模型在两种 harness 下运行，成绩会相差约 3.6 分。Agent 的能力上限，取决于你向它声明了什么。

带走知识，重建工具链。

我还会再迁移一次吗？会。这是我重来第一天的做法

直接说答案：会。故障清单中的问题加在一起，也从未严重到足以让我退回去。本地运行、默认权限优先、重建后比原版更好的 skill 工作流，以及成本——这四项收益压过了故障清单上的每一个问题。这一点比那些故障本身更让我意外。

但如果重来一次，我会改变第一天的做法，顺序如下：

先构建 AGENTS.md——由这个文件统一管理状态。整个上午都应该花在它身上，而不是迁移其他东西。

加入 session log 指令（“记录每个会话中做过的事情”），确保任何内容都不会被遗忘，任何决定都不会从缝隙中掉下去。

重建你真正使用的三个 skills，删除其余内容。

手动重新声明 MCP。信任它们之前，先审查版本。

有意识地决定模型和权限策略——运行什么模型、密钥保存在哪里、允许它读取哪些位置。

这次迁移中，大多数出问题的地方并不在工具本身，而在于我的知识存放在新工具无法读取的位置。解决办法不是打造一个更好的导入器，而是从第一天起就写好一个统一管理状态的文件。

如果你想获得多 provider 的自由，或者使用本地模型；如果你已经被 subscription OAuth 的经济账折腾得筋疲力尽；如果你看重权限优先的工作流；如果你愿意重新声明规则，而不是简单复制它们——那就迁移。

如果你已经深度投入 Claude 生态——skills、hooks、自动记忆；如果你希望开箱即用的速度和完成度；如果你对固定订阅感到满意；如果你无法承受数周适应期——那就留下。

或者两者一起用。这是诚实的折中方案：用 Claude Code 处理快速的交互式工作，用 OpenCode 做 provider 实验。几位评审者都明确推荐这种方式，而我的迁移经历也没有任何地方与之矛盾。

不要做这些事（检查清单）

复制文件，却不重新声明规则。迁移是重新声明，不是复制文件。

相信“直接放进去就能用”或“完全对等”之类的说法。真正的对等需要 wrappers、plugins，以及手动重新声明。

仅仅因为文件已经加载，就假定规则已经生效。已加载 ≠ 会遵守。务必验证。

让新 Agent 迁移旧配置。它无法盘点那些自己从未拥有过的东西。

忽视成本模式的变化：按 token 计费的模型、prompt cache 未命中，以及新的订阅成本结构。

跳过安全和版本审计。2026-22812/22813 这两个 CVE 已经修复，请保持版本更新。

四项故障，四项收益，毫不后悔。所有故障都可以追溯到同一个根源：知识确实存在，只是存放在新工具无法读取的位置。而每一个问题的解决办法也完全相同——把它声明出来，再把它记录下来。

这次迁移的重点，并不是哪种 harness 更好，而是有意识地让我的工作流具备可移植性。只有这样，迁移才能真正站稳脚跟——无论你现在迁移、以后迁移，还是永远不迁移。

OpenCode 会读取 CLAUDE.md 吗？

OpenCode 读取的是 AGENTS.md。只有在不存在 AGENTS.md 时，才会把 CLAUDE.md 作为 fallback 使用——这就是为什么直接复制 CLAUDE.md 并期待规则自动生效，会成为迁移中的头号错误。请重新声明这些规则。

我的 Claude Code skills 能在 OpenCode 中使用吗？

只能部分使用。OpenCode 只识别 skill frontmatter 中的 name、description、license、compatibility 和 metadata——其他所有内容都会被静默忽略，而且 skills 是按需加载的，不会自动触发。请重建那些你真正使用的 skills。

OpenCode 有 Claude Code 那样的自动记忆吗？

没有原生的跨会话记忆，相关功能请求 #20322 仍处于开放状态。请在 AGENTS.md 中加入 session log 指令，确保不同会话之间不会遗忘任何内容。

迁移值得吗？

如果你想要 provider 自由、local-first 的运行方式以及权限优先的工作流——值得。如果你已经深度投入 Claude 生态，包括 hooks、自动记忆和固定订阅——那就留下，或者两者同时使用。

我能在两边使用同一个模型吗？

可以——OpenCode 支持 75 个以上的 providers，包括 Anthropic 和 OpenRouter，因此你可以使用同一个模型进行 A/B 测试，比较不同 harness 带来的影响。

如果你也一直在和同样的问题斗争——指令得不到遵守，记忆在不同会话之间消失——我写了一份完整的解决手册：AGENTS.md 是为你的 AI Agent 编程，而不是为人类编写文档。

你迁移时遇到了什么问题？说出那个没人提醒过你、而你最终失去的东西——如果什么都没出问题，也请告诉我，尤其是我说错的地方。我会收集大家回复中的重建方案，整理到后续文章里。

这是我的 Agent 工作流迁移系列的第一篇文章。

如果需要采取进一步措施，你可以考虑屏蔽此人和／或举报滥用行为。