一位开发者将一个运行了数月的 Claude Code 工作流迁移到 OpenCode 时，发现文件处理、规则加载、工具清单、技能元数据以及跨会话记忆全部失效了。他记录下的修复方案，现在可以作为任何从 Claude 生态系统转向开源替代方案的人员的实用清单。

为什么这次迁移至关重要

Claude Code 用户依赖于一组紧密捆绑的文件——规则、技能定义和记忆日志——来保持 AI 驱动的编程助手顺畅运行。当作者的设置停止加载规则、混淆文件并导致 token 使用量激增时，他的日常编程助手变得不再可靠。OpenCode 承诺“权限优先的安全机制”、通过 OpenRouter 实现的模型无关访问以及按需付费的定价，这使其极具吸引力。但这种过渡并非简单的复制粘贴；你必须按照 OpenCode 预期的格式重新声明每个组件。

导致故障的原因

Claude Code 使用名为 CLAUDE.md 的文件，而 OpenCode 会忽略它，转而读取 AGENTS.md 来获取额外的元数据。作者原以为这两个系统是可以互换的，导致多个核心部分对 OpenCode 来说是不可见的。

具体的故障及其修复方法

  • 规则文件被忽略
    OpenCode 从不读取 CLAUDE.md；它只解析 AGENTS.md。仅仅重命名文件是不够的，因为内容必须以新格式重新声明。
    修复方法： 创建一个新的 AGENTS.md，复制规则文本，启动一个新的 OpenCode 会话并询问 agent “我的规则是什么？”。如果它无法引用这些规则，说明规则尚未加载。

  • 工具清单缺失
    原本应该复制技能和 MCP (multi-cloud platform) 服务器的迁移命令失败了，因为 OpenCode 无法对从未注册过的工具进行清点。
    修复方法： 在 Claude Code 工具仍在运行时，手动列出每个技能和命令。决定哪些需要在 OpenCode 中重建，哪些可以舍弃。

  • 技能中的 front-matter 被剥离
    迁移后的技能文件丢失了大部分 front-matter，包括模型分配和工具处理指令。OpenCode 仅支持少数字段，因此导入的技能表现得不可预测。
    修复方法： 将每个导入的技能都视为已损坏。从头开始重新创建最常用的三个技能，确保它们仅包含受支持的字段。删除任何未使用的技能文件。

  • 无跨会话记忆
    Claude Code 保留了作者赖以获取上下文的持久历史记录。OpenCode 不会在会话之间维持记忆，因此助手在切换后的第二天就“忘记”了一切。
    修复方法： 在 AGENTS.md 中添加一条明确的指令：“在每个会话结束时，向 session-log.md 追加一段简短摘要，涵盖已完成的工作、待处理事项以及做出的决策。” 这样，会话日志就成为了保持连续性的唯一事实来源。

权衡：你将获得什么，失去什么

收益

  • 权限优先的安全机制：OpenCode 在执行任何操作前都会询问，减少了意外的代码更改。
  • 模型自由度：通过 OpenRouter，单个 API 密钥即可解锁数十种模型，让你无需更改配置文件即可进行实验。
  • 成本控制：计费基于使用量，避免了在 token 消耗激增时变得昂贵的固定费率订阅。

损失

  • 没有内置的长期记忆，意味着你必须维护手动日志。
  • 受限的技能元数据迫使你重建大部分自定义工具。

实用迁移清单

  1. 首先创建 AGENTS.md – 在导入任何其他文件之前，声明你需要的每一条规则。
  2. 添加会话日志指令 – 在 AGENTS.md 的顶部嵌入“追加摘要”规则。
  3. 重建前三个核心技能 – 仅复制受支持的字段；隔离测试每个技能。
  4. 手动重新声明 MCP – 列出你仍需访问的每个服务器或云端点。
  5. 验证 – 启动一个新的 OpenCode 会话，并查询助手的规则、技能列表和记忆状态。

总结

从 Claude Code 迁移到 OpenCode 不仅仅是移动文件，更多的是重新构建驱动助手的声明架构。这个过程迫使你精简到核心规则、重建必要的技能并采用手动记忆日志，但它也为你通往更便宜、模型无关的 AI 辅助体验打开了大门。如果你准备好用便利性换取控制权，请遵循上述清单，并将每个导入的组件视为一个全新的开始。