如何在不丢失上下文的情况下从 Claude Code 迁移到 OpenCode（2026）

首先，您要迁移到哪个 OpenCode 版本

OpenCode 的迁移指南指出：“OpenCode 1 和 OpenCode 2 都使用 opencode 命令，默认情况下不再并存安装。”这两个版本读取相同的配置位置，指南称支持的 V1 行为“旨在与 V1 保持兼容”。但在具体的 Claude Code 文件上，它们有所不同，因此在依赖以下任何内容之前，请先检查您运行的是哪个版本。

指令：CLAUDE.md

在 V1 中，CLAUDE.md 作为备用方案工作。如果没有 AGENTS.md，OpenCode 会读取项目中的 CLAUDE.md；如果没有全局 OpenCode AGENTS.md，它会读取 ~/.claude/CLAUDE.md。规则是“每个类别中第一个匹配的文件胜出”。因此，向项目添加 AGENTS.md 会停用其 CLAUDE.md。

V1 还为您提供了用于此兼容性的开关。“要禁用 Claude Code 兼容性，请设置以下环境变量之一”。OPENCODE_DISABLE_CLAUDE_CODE 会关闭所有 .claude 支持，而 OPENCODE_DISABLE_CLAUDE_CODE_PROMPT 和 OPENCODE_DISABLE_CLAUDE_CODE_SKILLS 则分别关闭全局 CLAUDE.md 和技能。

在 V2 中，没有备用方案。V2 会加载全局 AGENTS.md，然后加载“从当前工作区目录到主目录的每个 AGENTS.md”，并且随着智能体读取该区域，项目更深处的文件也会加载。它还会将它们堆叠起来，而不是选择其中一个：“OpenCode 会合并这些文件，并且不会解决它们之间的冲突。”

V2 迁移指南直接面向 Claude Code 用户：“如果 V1 设置依赖于 CLAUDE.md 备用方案，请将该指南移至适用的 AGENTS.md 中。”它补充道，“V2 目前仅发现 AGENTS.md”，并且由于 V1 行为旨在保持兼容，因此要求用户“同时提交受影响项目详细信息的兼容性问题”。“目前”这个词很重要。这可能会改变，但目前 V2 不会自行加载 CLAUDE.md。

对于这两个版本，安全的做法都是相同的：将您的指令放在 AGENTS.md 中。Claude Code 也可以读取它，正如我们关于 Claude Code 默认使用 AGENTS.md 的指南所解释的那样，因此一个文件可以同时为这两个工具服务。

导入和路径范围规则

Claude Code 的 CLAUDE.md 可以引入其他文件。“导入的文件在启动时会与引用它们的 CLAUDE.md 一起展开并加载到上下文中。”如果您的 CLAUDE.md 大部分是 @docs/... 行，那么您的大部分指令都存在于这些其他文件中。

OpenCode 的 V1 规则文档指出：“虽然 opencode 不会自动解析 AGENTS.md 中的文件引用，但您可以通过两种方式实现类似的功能”。其推荐的途径是 opencode.json 中的 instructions 字段。V2 保留了它：“使用 instructions 数组在发现的 AGENTS.md 文件旁添加文件、glob 模式或 HTTP(S) URL”。如果您在其中列出了远程 URL，我们关于镜像 OpenCode 远程指令文件的指南介绍了获取缓慢时会发生什么。

Claude Code 还支持 .claude/rules/ 中的规则，并带有将规则限制为匹配文件的 paths: 前置元数据（frontmatter）。OpenCode 的指令文档描述了 AGENTS.md 文件和 instructions 数组，而 .claude/rules/ 并不在它列出的位置中。最接近的 OpenCode 模式是在规则覆盖的目录中嵌套 AGENTS.md。在 V2 中，当智能体读取项目的该部分时，嵌套文件会“按最近优先原则加载”。

技能

技能是最容易迁移的部分。两个版本都会读取 Claude Code 的技能文件夹。V2 将 ~/.claude/skills 列为全局兼容性源，将 .claude/skills 列为项目兼容性源，与 OpenCode 自身的 .opencode/skills 并列。

V2 还能理解一个 Claude Code 字段。其表格列出了 disable-model-invocation，并附带说明“设置为 true 的效果与 opencode/autoinvoke: false 相同”。开放技能标准中的字段是被接受的，尽管“V2 接受诸如 license 和 compatibility 等可移植性字段，但并不对其进行解释。”

V2 技能文档列出的字段包括 name、description、metadata.opencode/autoinvoke 和 disable-model-invocation。Claude Code 的其他技能字段（如 context、paths、hooks 和 model）不在其中，因此依赖这些字段的技能需要重写。还有一个需要注意的区别：在 V2 中，“文件路径决定了技能 ID。前置元数据名称仅是一个显示标签。”

子智能体和命令

Claude Code 子智能体存在于 ~/.claude/agents/ 或项目的 .claude/agents/ 中。OpenCode 的智能体文件存在于 ~/.config/opencode/agents/<name>.md 或 .opencode/agents/<name>.md 中，它们的前置元数据是 OpenCode 专属的，带有 mode: subagent 设置和权限列表。Markdown 正文可以干净地保留，因为在 OpenCode 中“Markdown 正文会成为智能体的系统提示词”。

自定义命令遵循相同的模式。Claude Code 的 .claude/commands/ 文件变为 .opencode/commands/<name>.md，全局命令则变为 ~/.config/opencode/commands/。OpenCode 命令也使用 $ARGUMENTS，并注意“仅发现 .md 文件”。

如果您大量使用子智能体，我们关于 Claude Code 子智能体不共享记忆的指南介绍了每个子智能体能看到什么，这在迁移后值得重新检查。

遗留的内容

自动记忆。 Claude Code 会编写自己的笔记：“自动记忆让 Claude 能够跨会话积累知识，而无需您编写任何内容。”它们存储在您的机器上，“每个项目在 ~/.claude/projects/<project>/memory/ 下都有自己的记忆目录。”OpenCode 的文档没有描述读取该目录。Claude 在那里学到的任何内容（例如您的纠正、偏好和项目事实）都会留在 Claude Code 中，除非您手动移动它。我们关于从 Claude Code 迁移到 Cursor 的指南介绍了另一个目的地的相同差距。

会话。 OpenCode 的 V1 CLI 可以将会话数据导出和导入为 JSON，但这些命令描述的是 OpenCode 自身的会话。您的 Claude Code 对话仍保留在 Claude Code 中。我们关于将 Claude Code 会话导出到另一台机器的指南介绍了如何保留它们。

钩子和插件。 Claude Code 钩子存在于其设置中。OpenCode 则通过插件扩展行为，V2 指南警告说“V1 插件实现无法在 V2 中运行”。请将钩子视为需要重建而不是复制的内容。

MCP 服务器。 这些作为配置进行迁移。OpenCode 在 opencode.json 中定义它们，V2 将它们归类在 servers 键下。重新连接每一个并在需要的地方重新登录。

步骤 1：构建一个 OpenCode 在任一版本中都会读取的 AGENTS.md

首先收集影响 Claude 在此项目中工作方式的所有内容：

• 您的 CLAUDE.md 文件，位于项目根目录、.claude/CLAUDE.md、子目录以及 ~/.claude/CLAUDE.md 中。
• 它们使用 @ 导入的每个文件。
• 您的 .claude/rules/ 文件，注意哪些使用了 paths:。
• 您的自动记忆。 打开 ~/.claude/projects/<project>/memory/ 并阅读 MEMORY.md 及其指向的主题文件。

然后将结果写入 AGENTS.md：

• 项目范围的指令放入根目录的 AGENTS.md 中。将导入文件的内容复制进去，或者在 opencode.json 的 instructions 数组中列出它们，以便在不粘贴的情况下加载它们。
• 路径范围规则放入它们所覆盖目录的 AGENTS.md 中。
• 自动记忆笔记进行整理。仍然有效的纠正和项目事实将成为指令。适用于跨项目的个人偏好放入 ~/.config/opencode/AGENTS.md 中。任何过时的内容都将遗留。
• 来自 ~/.claude/CLAUDE.md 的全局指令移至 ~/.config/opencode/AGENTS.md。

如果您要继续在同一个仓库上使用 Claude Code，请保留 CLAUDE.md 作为一个简短的文件，将 Claude 指向 AGENTS.md，这样两个工具就可以读取同一套指令。我们关于将 CLAUDE.md 迁移到 AGENTS.md 的指南介绍了这种模式。

因为 V2 会合并它找到的每个 AGENTS.md 而不解决冲突，所以在完成后请一起阅读这些文件并消除矛盾。

步骤 2：移动技能、智能体和命令，然后在没有备用方案的情况下进行测试

技能可以保留在原处，因为 OpenCode 会读取 .claude/skills/ 和 ~/.claude/skills/。打开每个 SKILL.md 并检查其前置元数据。保留 name、description 和 disable-model-invocation。重写任何依赖于仅限 Claude Code 字段的内容，并保持每个文件夹名称稳定，因为在 V2 中，路径决定了技能的 ID。

子智能体从 .claude/agents/ 移至 .opencode/agents/。保留 Markdown 正文，设置 mode: subagent，并将工具限制转换为 OpenCode 的权限。

命令从 .claude/commands/ 移至 .opencode/commands/。检查每个模板的 $ARGUMENTS 用法是否仍然合理。

然后进行测试。在 V1 上，在您的会话环境中设置 OPENCODE_DISABLE_CLAUDE_CODE，并确认智能体仍然遵循您的指令。该变量还会关闭 .claude/skills，因此您留在那里的技能将在该会话中消失。任何丢失的指令都来自您尚未移动的 Claude Code 文件。在 V2 上，不需要进行此类测试，因为没有备用方案。启动一个会话，要求智能体总结它正在运行的指令，并将其与您的 AGENTS.md 进行比较。测试时的一个 V2 细节：“嵌套文件的编辑在加载后不会自动检测到。”修改文件后请启动一个新会话。

步骤 1 是这次迁移的难点，大部分工作在于自动记忆笔记和导入的文件，即 Claude Code 在没有明显文件的情况下积累的上下文。将其移入 AGENTS.md 可以解决这次迁移问题。但它对下一次迁移没有帮助，而且它不包含属于您自己而不是仓库的上下文。

MemoryLake 是一个记忆层，用于将决策和偏好保存在您维护的一个列表中，供 Claude Code 和您连接的其他助手使用。

您自己用自己的话编写条目。不会从您的 CLAUDE.md 文件、Claude Code 的自动记忆、您的 OpenCode 配置或任何厂商的存储中读取、写入或删除任何内容。在将项目详细信息存储在仓库之外之前，请先检查您组织的政策。

步骤 1：创建 API 密钥

登录并从控制面板生成密钥。该密钥属于您的 MemoryLake 工作区，与您的 Anthropic 账户和您的模型提供商是分开的。

步骤 2：上传您的第一批记忆

从您在自动记忆中发现的非仓库规则内容开始：您的偏好、决策背后的推理、您排除的方法。每个条目一个决策，并注明日期。

步骤 3：连接您的 AI 和智能体

连接您使用的助手。这样，无论您在哪里工作，都可以使用这些上下文，而不是绑定到最初学习它的工具上。

第一个区别是使用单个指令文件而不是备用链。有了 AGENTS.md，OpenCode 就可以在 V1 和 V2 中读取您的指令，并且 Claude Code 也可以读取同一个文件。

第二个区别是，没有任何重要内容仅存在于 Claude 的自动记忆中。在迁移过程中阅读它，可以将 Claude 为自己编写的笔记转化为您可以查看和编辑的指令。

第三个区别是您可以重复进行测试。关闭 V1 兼容性或运行 V2 可以准确显示 OpenCode 读取的内容，因此您可以确切知道迁移已完成，而不是仅凭猜测。

首先检查您的 OpenCode 版本。 V1 将 CLAUDE.md 作为备用读取。V2 则不然。

编写 AGENTS.md，而不是 CLAUDE.md。 它在两个版本以及 Claude Code 中都有效。

解决导入问题。 粘贴导入的内容或使用 instructions 数组。

在离开前阅读您的自动记忆。 这是唯一由 Claude 而不是您编写的来源。

如果愿意，可以将技能留在 .claude/skills/ 中。 OpenCode 会读取它们，但请检查前置元数据。

将智能体和命令移至 .opencode/。 它们的 Claude Code 文件夹不在 OpenCode 的列表中。

在关闭备用方案的情况下进行测试。 这会显示哪些内容仍然依赖于 Claude Code 文件。

OpenCode 的文档从一开始就面向 Claude Code 用户，对于技能来说，迁移仍然很容易：两个版本都会读取 .claude/skills。对于指令，情况取决于版本。当没有 AGENTS.md 时，V1 会读取 CLAUDE.md。V2 仅识别 AGENTS.md，其迁移指南会告诉您将指导内容移过去。

无论哪种方式，可靠的路径都是相同的。根据您的 CLAUDE.md 文件、它们的导入、您的路径范围规则以及 Claude 为自己保留的自动记忆构建一个 AGENTS.md。将子智能体和命令移至 .opencode/，检查技能前置元数据，并在关闭备用方案的情况下进行测试。然后，无论您运行哪个版本，OpenCode 都会根据您的上下文工作。