Oh My OpenCode帮你项目从Claude Code无缝迁移到开源OpenCode

Oh My OpenCode 正是这样一位贴心又酷炫的东道主——它不仅完整保留了 Claude Code 用户过去积累的所有自定义逻辑、钩子脚本、技能模块和插件配置，还把这些宝贝统统塞进一个更强大、更灵活、更智能的新引擎里继续跑。

这种兼容策略不是简单的“支持旧格式”，而是真正意义上的“无痛迁移”：用户无需重写一行配置，就能立刻享受多模型协作、背景代理并行执行、LSP 精准重构等前沿能力。如果哪天觉得旧包袱太重，还能一键关闭兼容层，彻底拥抱 OpenCode 原生架构。这种“既要又要还要”的设计哲学，让开发者既能稳坐旧船舱，又能驶向新大陆。

再见 Claude Code，欢迎 Oh My OpenCode！

这句话其实有两层意思：

1. 官方在跟大家说：原来大家用的 Claude Code 那套生态，在这个项目里已经不再是主角了，
2. 但同样也说明：尽管我们把 Claude Code 替换成了 OpenCode，但兼容层、迁移路径是已经做好的，也就是说：
   • 如果你之前是在用 Claude Code 的配置、插件、hook 等等，
   • 那么迁移到 Oh My OpenCode 是 “可以无缝继续用” 的。所以标题上的“Goodbye”并不是说强行把你从 Claude Code 拉开、断掉你的旧设置，而是在告诉你：新的时代开始啦，你可以继续用你原来写的东西。

兼容层如何像时间胶囊一样封存旧逻辑
OpenCode 的兼容机制并非简单地读取旧文件然后假装它们存在，而是构建了一套完整的“Claude Code 模拟器”。

这套模拟器会主动扫描三个关键路径：用户主目录下的 ~/.claude/settings.json、项目根目录的 ./.claude/settings.json，以及本地专用的 ./.claude/settings.local.json。这三个位置正是 Claude Code 生态中钩子（Hooks）系统的标准栖息地。

一旦发现这些文件，OpenCode 就会启动解析流程，把其中定义的 PreToolUse、PostToolUse、UserPromptSubmit 和 Stop 四类事件钩子精准映射到自身生命周期中对应的时间节点上。

例如，当 AI 代理准备调用代码编辑工具前，PreToolUse 钩子会先被触发，允许外部脚本修改输入参数；工具执行完毕后，PostToolUse 钩子立即接手，可能启动 eslint 自动修复或安全扫描。

整个过程如同在新引擎上安装了一个复古仪表盘——指针还是熟悉的样式，但驱动它的已是涡轮增压心脏。

钩子系统如何在新架构中焕发第二春

Claude Code 重要的功能叫做 “Hooks（钩子）”。钩子就是：在某些特定事件发生的时候，自动执行一些你自定义的命令或脚本

举个例子：
当 Agent（AI 智能体）：

• 开始用一个工具之前
• 用完工具之后
• 提交提示之前
• AI 不再响应的时候

钩子机制之所以强大，在于它赋予了自动化流程“条件反射”般的能力。

为了兼容原先 Claude Code 的钩子系统，Oh My OpenCode 做了这样的支持机制：
它会读这些位置里的 Hook 文件：

1. ~/.claude/settings.json→ 用户主目录里的全局设置钩子
2. ./.claude/settings.json→ 当前项目的本地设置钩子
3. ./.claude/settings.local.json→ 避免被 Git 管理、只属于本地环境的钩子

想象一下：每当 AI 修改了某个 JavaScript 文件，系统自动运行单元测试；每当提交提示包含“紧急修复”字样，就强制插入代码审查步骤。这些智能行为在 Oh My OpenCode 中不仅完全保留，还因底层架构升级而变得更可靠。

因为 OpenCode 的代理调度器能确保钩子执行不会阻塞主线程——PostToolUse 触发的 eslint --fix $FILE 命令会在后台安静运行，而主代理早已继续处理下一个任务。这种非阻塞特性解决了 Claude Code 时代常见的“钩子卡死”问题。

更有趣的是，由于 OpenCode 支持多模型协作，钩子甚至可以指定由特定模型执行：比如让 GPT-5.2 负责分析 PostToolUse 的输出质量，而 Gemini 3 Pro 专注处理前端相关的钩子逻辑。旧瓶装新酒，酒香还翻倍！

以下这些钩子事件触发机制一样、跟 Claude Code 里写法也一致：

| Hook 事件名           | 意味着什么时候运行 | 用意         |
| ------------------ | --------- | ---------- |
| <code>PreToolUse</code>       | 工具调用之前    | 拦截或修改工具输入  |
| <code>PostToolUse</code>      | 工具调用之后    | 可以做检查或发出警告 |
| <code>UserPromptSubmit</code> | 用户提交提示之后  | 可以审查/替换提示  |
| <code>Stop</code>             | 会话闲置空转时   | 可以注入后续提示   |

你写的钩子 还是会照常被执行，而 Oh My OpenCode 就负责把这个流程接上，让它跑在 OpenCode 的生命周期里面。

完整例子：老用户如何继续用钩子
下面是一个原来在 Claude Code 里面可能常见的 settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "eslint --fix $FILE" }
        ]
      }
    ]
  }
}

这个意思是：

当 Agent 写代码或编辑代码后，自动执行 eslint --fix $FILE —— 就是：
自动修复代码风格错误！

在 OpenCode 里，你只要 把这个文件继续放在合适的位置：

• 它会自动被 OpenCode 读入
• 钩子依旧照常触发
• 自动修复逻辑继续生效

所有原来比较复杂、经过自己调试的钩子逻辑都没必要重新写。

Config Loaders（配置加载器）
为了让 OpenCode 兼容 Claude Code 的各种自定义模块，还支持把原来你在 Claude Code 里面习惯放：

• Slash commands
• Skills
• 自定义 agent 定义文件
• MCP 相关配置

Slash commands（斜线命令）和 Skills（技能模块）是 Claude Code 用户打造个性化工作流的核心积木。
Oh My OpenCode 对这两者的兼容堪称教科书级别：它同时监听四组目录路径——~/.claude/commands/（全局命令）、./.claude/commands/（项目命令）、~/.config/opencode/command/（OpenCode 全局命令）和 ./.opencode/command/（OpenCode 项目命令）。
这种双轨制设计既尊重历史路径，又为未来扩展留出空间。
当用户输入 /deploy 这样的命令时，系统会按优先级顺序搜索所有目录，找到第一个匹配的 markdown 文件就立即执行。

技能模块同理，无论是放在 ~/.claude/skills/ 里的数据库连接脚本，还是 ./claude/skills/ 中的 API 测试模板，都会被自动加载到 OpenCode 的技能库中。
这意味着过去花费数周调试的自动化套路，现在只需复制文件夹就能在新平台重生，连变量名都不用改！

自定义 Agent 定义文件（通常以 .md 格式存放在 ~/.claude/agents/ 或 ./.claude/agents/）是高级用户的秘密武器。
这些文件描述了专属 AI 代理的行为准则、工具权限和对话风格。Oh My OpenCode 直接把这些文件纳入自己的代理注册表，让老代理们无缝融入新团队。

更关键的是对 MCP（Model Control Plane）配置的支持——那些以 .mcp.json 结尾的文件曾是 Claude Code 集成外部服务的桥梁。

MCP 是 Model Control Plane 的缩写，原来是 Claude Code 在做链路解析和集成的一种机制。
如果你有：

• ~/.claude/.mcp.json
• ./.mcp.json
• ./.claude/.mcp.json

OpenCode 不仅识别 ~/.claude/.mcp.json 和 ./.mcp.json 等旧路径，还将其转化为内部服务注册机制。例如，一个指向 GitHub Actions 的旧 MCP 配置，现在能驱动 OpenCode 的 Orchestrator 代理直接触发 CI/CD 流水线。

这种深度兼容让企业级用户松了一口气：过去投资在 Claude Code 生态中的集成工作，丝毫没有浪费。

数据存储也兼容原格式

Claude Code 有一些它自己日志、Todo、会话记录存储的约定格式和目录：

类型       原存放位置         OpenCode 会兼容吗？
Todo 管理    ~/.claude/todos/        ✅ 是兼容的
会话记录    ~/.claude/transcripts/    ✅ 兼容

也就是说：
你原本用 Claude Code 做的项目历史、笔记、待办事项列表，都不会被丢掉。

自动化工具的价值往往沉淀在历史记录中。Oh My OpenCode 特意保留了 Claude Code 的数据存储约定：
~/.claude/todos/ 目录下的待办事项列表会被 Todo Continuation Enforcer 组件接管，确保未完成的任务在新会话中自动续跑；
~/.claue/transcripts/ 中的会话日志则成为 Session Tools 的分析素材，支持关键词回溯和上下文重建。

这种设计避免了“升级即失忆”的灾难——上周五中断的代码重构任务，周一早上打开 OpenCode 就能接着干，连上次卡在哪个函数都记得清清楚楚。对于依赖长期任务追踪的开发者而言，这种连续性比任何新功能都珍贵。

想要禁用 Claude Code 兼容功能？

官方还贴心地给了一个开关，万一你：

✔ 不想再继续让 OpenCode 读那些 Claude Code 格式的内容
✔ 想让 OpenCode 完全走它自己的方式
✔ 想简化启动过程

那么你可以在配置里面加上一个配置对象：

{
  "claude_code": {
    "mcp": false,
    "commands": false,
    "skills": false,
    "agents": false,
    "hooks": false,
    "plugins": false
  }
}

这段意思是：

把 Claude Code 兼容层的所有功能都关掉
→ OpenCode 就 不会去读旧的 Claude Code 配置了
→ 你就可以彻底把项目迁移到新的 OpenCode 配置体系下

Oh My OpenCode 深知有些用户渴望彻底拥抱新时代。在配置文件中埋藏了一组精妙的开关：通过设置 claude_code 对象下的 mcp、commands、skills、agents、hooks、plugins 等字段为 false，就能逐项关闭兼容功能。

更绝的是 plugins_override 机制——当某些旧插件与新架构冲突时，只需在配置中声明 "claude-mem@thedotmack": false，就能精准屏蔽特定插件而不影响其他组件。这种粒度控制让用户既能享受平滑过渡的便利，又保留了随时“断舍离”的自由。

要不要兼容？兼容哪些部分？决定权始终握在用户手中，而不是被工具绑架。

插件覆盖（plugins_override）

还有个很实用的小技巧：

假设你有一些 Claude Code 的插件，但你 不想要 OpenCode 把它们加回去，

你可以用：

{
  "claude_code": {
    "plugins_override": {
      "claude-mem@thedotmack": false,
      "some-other-plugin@marketplace": false
    }
  }
}

来禁止某些特定旧插件被 OpenCode 自动载入。

oh My OpenCode 的目标是：

✨ 让 OpenCode 成为一个强大的、多 Agent 协作的自动化代码平台
✨ 支持各种自动化流程、插件系统、背景任务、多模型协作
✨ 并且能接管你以前在 Claude Code 里面写的所有自定义结构

这就意味着：

如果你是 Claude Code 老用户
你不用担心迁移成本
你的所有旧业务逻辑、钩子、命令等都会继续 work
但底层执行的逻辑已经变成 OpenCode 的新架构了

为什么这种兼容策略堪称行业典范
在软件工程领域，生态迁移常伴随阵痛：要么强制用户重写所有配置（如 AngularJS 到 Angular 的惨烈升级），要么维持臃肿的双模式导致性能下降（某些 IDE 的旧插件系统）。Oh My OpenCode 却走出第三条路——用轻量级适配层实现零成本迁移。

其核心智慧在于：不把旧逻辑当作负担，而视为用户资产。当 Anthropic 收紧 Claude Code 的第三方访问权限时，这个兼容层更显珍贵：它让用户从封闭生态平稳过渡到开源平台，既保住既有投资，又获得社区驱动的创新活力。

这种设计哲学背后是对开发者心理的深刻洞察——人们抗拒的从来不是改变本身，而是被迫放弃自己亲手搭建的城堡。

从技术细节看兼容层的精巧实现
深入代码层面，兼容层的实现展现了极高的工程素养。

它并非简单复制 Claude Code 的解析逻辑，而是构建了抽象语法树（AST）级别的转换器。例如，当读取 settings.json 中的 hooks 配置时，系统会将其编译成 OpenCode 内部的 HookDescriptor 对象，再注入到事件总线中。这种中间表示法确保了旧配置能享受新架构的优化——比如自动合并重复钩子、动态调整执行超时等。

对于 MCP 配置，兼容层甚至实现了协议翻译：将 Claude Code 的 JSON-RPC 调用规范转译为 OpenCode 的 gRPC 接口。

这种“语义级兼容”远超表面文件读取，使得旧配置在新环境中不仅能跑，还能跑得更快更稳。

兼容性与创新性的完美平衡术
Oh My OpenCode 的真正高明之处，在于兼容层与新特性的共生关系。

当用户启用 ultrawork 关键词时，Sisyphus 主代理会自动激活背景任务分发机制——此时兼容层加载的旧钩子反而成为增强能力的燃料。例如，一个原本用于代码格式化的 PostToolUse 钩子，现在能与 LSP 重构工具协同工作：先由 AST-Grep 精准定位需修改的代码段，再触发钩子执行定制化格式化，最后用 Git-Master 技能生成原子提交。

旧逻辑非但没被淘汰，反而在新架构中找到了更高阶的应用场景。这种设计让兼容性不再是妥协，而成为创新的跳板。

对开发者工作流的革命性影响
当兼容层消除迁移恐惧后，开发者能立即体验 OpenCode 的杀手级特性。

比如 Todo Continuation Enforcer 机制——它监控 ~/.claude/todos/ 中的任务状态，一旦检测到未完成项就强制代理回到“推石头”模式。这意味着即使 AI 代理因 token 限制中途退出，系统也会自动续跑直至任务闭环。

再如 Comment Checker 功能，它会扫描旧钩子生成的代码，自动删除冗余注释使输出更接近人类手写风格。

这些新能力与旧配置的化学反应，创造出 Claude Code 时代无法想象的工作流：用户只需维护熟悉的钩子脚本，就能获得多代理协作、上下文感知、永不放弃执行等超能力。