我前阵子把一个常用项目从 Claude Code 搬到 Hermes，最先想到的是“重新登录一下就行”。真正动手才发现，模型账号只占很小一块。过去半年攒下来的 CLAUDE.md、允许执行的命令、MCP 服务器、个人 Skill，还有那些写在不同目录里的习惯，全散在旧工具的抽屉里。

手工复制看起来简单，实际像搬家时只抱走沙发，钥匙、药箱和水电卡全留在旧屋。规则文件复制了，权限口径没对上；MCP 配置抄了，密钥也顺手暴露；Skill 文件夹挪过去，和 Hermes 里已有同名能力撞车。最麻烦的是，搬完还不知道漏了什么。

Hermes v0.20 新增 hermes import-agent，专门把 Claude Code 或 OpenAI Codex CLI 的现有配置先扫描、再列计划、最后按确认结果导入。它能迁规则、记忆、命令白名单、MCP 和 Skill，凭证则刻意留在原地。第一次使用时只跑 –dry-run，几分钟就能看清这次搬家会带走什么、跳过什么、哪里需要手工补。

真正舍不得的，从来都是调顺后来留下的“小习惯”

一个 Agent 用久了，会积累出自己的工作手感。你可能在全局规则里写过“先读文件再修改”，在权限设置里放行 npm run test，给 GitHub 配过 MCP，还装了几套自己常用的 Skill。这些东西单独看都不大，组合起来才像一张磨合过的办公桌。

换工具时从零配置，损失的重点并非几分钟复制时间，而是隐藏关系。Claude Code 的 Bash 权限规则长什么样，Hermes 的 command_allowlist 又接受什么；Codex 的 config.toml 里 MCP 怎样分组，迁到 YAML 后怎样合并；两个工具都叫 Skill，同名目录发生冲突时谁覆盖谁。稍微抄错一处，Agent 可能静悄悄地少一个能力，也可能获得比预想更宽的权限。

手工搬还有一个认知盲区：旧目录里哪些文件属于“配置”，并没有一张统一清单。有人只复制 CLAUDE.md，忘了 ~/.claude.json 里的 MCP；有人搬了 Skill，漏掉 Codex memories；有人把整个目录压缩带走，连登录凭证也进了备份。文件越多，靠记忆越容易漏。

所以好的迁移工具至少要完成三件事：先发现旧配置，给出清晰映射；写入前展示计划，让人能刹车；对密钥、冲突和坏文件保持保守。import-agent 的设计基本沿着这三条线展开。

它更像搬家公司上门先贴标签。书进书箱，易碎品单独包，旧钥匙不跟车；同名家具先问主人，缺角的柜子记录下来，但不会由于一件坏家具撤销整车搬运。

52 项测试盯住迁移，v0.20 才把它摆到正式入口

这项功能来自 PR #72190，在北京时间 7 月 27 日上午 8 点 47 分合并。PR 增加约 900 行迁移逻辑、独立的命令解析、官方文档和 52 项测试。测试会构造假的 ~/.claude 与 ~/.codex 目录，检查来源发现、格式解析、合并、冲突、原子写入、坏文件跳过和凭证不复制。

北京时间 8 月 4 日凌晨发布的 Hermes v0.20.0，正式把它放进 Release 的 CLI 更新清单。官方定位很克制：它导入的是 setup，也就是工作设置，不承诺把旧工具完整克隆成 Hermes。两个 Agent 的能力边界仍不同，迁移只处理有明确对应关系的部分。

PR 里还有一个很值得普通用户注意的验证：–dry-run 必须“writes nothing”。测试不只检查命令有没有打印 Dry Run，还检查导入产生的 Memory、Skill、白名单和 MCP 都没有落盘。预览若会偷偷改配置，预览就失去意义。

写配置时也采用原子方式。简单理解，先把完整新内容准备好，再一次替换；磁盘写入中途失败时，旧配置不该只剩半截。迁移工具最怕把“省一次重配”变成“修一晚上 YAML”，这道保护很实用。

测试还覆盖了符号链接配置和磁盘写入失败。若 config.yaml 指向另一个真实文件，导入要保留链接关系；若写入时报“磁盘空间不足”，旧文件必须完整留在原处。普通用户不必读测试代码，这些用例却能协助判断维护者有没有认真思考失败现场。

从 Claude Code 搬来时，5 类东西各有自己的落点

Claude Code 的全局 CLAUDE.md 会转成 Hermes 的 Memory 条目，进入
~/.hermes/memories/MEMORY.md。这里搬的是长期指令与习惯，不会把每个项目目录里的所有局部规则一股脑扫走。项目级规则仍应留在项目里，跟着仓库管理更清楚。

settings.json 中 permissions.allow 里的 Bash 规则，会映射到 Hermes config.yaml 的 command_allowlist；deny 规则进入 approvals.deny。例如 Claude 的 Bash(npm run test:*)会转换成 Hermes 能理解的通配形式。Read、WebFetch 等只属于 Claude 工具语义的规则没有直接对应项，报告会标成 unmapped，提醒你手工判断。

MCP 服务器会从 ~/.claude.json 和 settings.json 读取，再合并到 Hermes 的 mcp_servers。Skill 目录中真正带 SKILL.md 的项目，会进入
~/.hermes/skills/claude-code-imports/，单独分组能降低和原生 Skill 混淆的概率。

Claude Code 的 commands/*.md 不会直接搬。官方报告会提示把这类 Slash Command 转成 Skill。缘由很容易理解：一份斜杠命令可能依赖 Claude 特有的调用方式，直接改个目录名，表面出现了，执行语义却未必成立。

这里也能看出迁移报告的价值。它不把“跳过”藏成静默成功，而会列出 unmapped 或 skipped。看见这两个词时，别急着当错误清零；它们往往是需要人工翻译的经验。先问自己这条能力在 Hermes 里还有没有用，再决定重写成 Skill、规则或直接淘汰。

从 Codex 搬来时，AGENTS.md、记忆和 MCP 更容易对齐

Codex CLI 这边，工具会读取全局 AGENTS.md，同样转成 Hermes Memory 条目。~/.codex/memories/*.md 也会逐项合并。已有内容会做去重，避免同一条规则在 Memory 里叠两遍，最后每轮都对模型重复喊话。

config.toml 中的 [mcp_servers.*] 会映射到 Hermes 的 MCP 配置；带 SKILL.md 的技能目录则进入
~/.hermes/skills/codex-imports/。由于两边都采用开放的 Skill 结构，这一部分一般比专属斜杠命令更容易迁。

需要注意，Codex 的模型选择、审批沙箱、账号登录、桌面任务和线程历史没有被列进迁移表。它们或缺少直接对应关系，或属于运行环境与凭证。导入成功只代表可映射的工作资料到了 Hermes，不代表旧会话也跟着续上。

如果 Claude Code 和 Codex 都装着，直接运行无参数命令会自动探测。真正执行前仍会展示逐项计划。我更喜爱显式写来源，先搬一个、验收一个，出了问题更容易知道来自哪只箱子。

两个来源都含同名 Skill 时，顺序会影响冲突报告。先导入 Claude Code，Codex 的同名 Skill 可能随后被跳过；反过来也一样。更稳的做法是先比较两个目录的版本与内容，保留维护更活跃、规则更符合当前工作的那一份，名称一样不代表能力完全一样。

密钥故意不搬，这一点比“一键全迁”更让人放心

官方文档把“never imported”单独列了一节：
~/.claude/.credentials.json、~/.codex/auth.json 不会读取。MCP 环境变量或请求头里带 _TOKEN、_API_KEY、Authorization 等敏感名称的字段，也会被剥离并写进报告，让用户稍后有意识地重配。

这意味着迁完后某个 MCP 显示存在，却连接失败，未必是 Bug。很可能服务器定义到了，钥匙按设计没来。此时应通过 hermes setup 或 ~/.hermes/.env 重新放入凭证，并按最小权限原则检查范围。

已有配置默认采用合并。Memory 会去重，允许与拒绝规则会和当前 YAML 合并；遇到同名 MCP 或 Skill，默认跳过并报告冲突。只有显式加 –overwrite 才会替换。这个默认值看起来不够“爽”，实际很稳：新家里已经摆好的东西，不该被搬家工人一声不吭扔掉。

坏掉的 JSON 或 TOML 也按单项报错处理。一个文件解析失败，其余可迁内容继续列在报告里。你会看到“哪一箱没装上车”，不用面对一句笼统的 migration failed。

把实践放在一起：先预演，再确认，再逐项验收

第一步先升级 Hermes，并检查命令存在。旧版本提示 unknown command 时，别急着手写路径补救，先确认自己真的运行到 v0.20 这一条线上。

hermes --version
hermes import-agent --help

第二步只做 Claude Code 预览。正常结果是一份 Dry Run Results，列出 Memory、command-allowlist、MCP、Skill、冲突、未映射项和被剥离的敏感字段，磁盘内容不应变化。

hermes import-agent claude-code --dry-run

若要预览 Codex，把来源换掉。旧目录不在默认位置时，使用 –source 指向准确目录，别把整个家目录交给扫描器。

hermes import-agent codex --source /path/to/.codex --dry-run

第三步阅读计划。重点看四处：将新增多少 Memory；哪些命令进入 allowlist；哪些 MCP 去掉了密钥；哪些 Skill 因同名冲突被跳过。确认后再运行正式导入。交互终端会继续询问，自动化环境则需要 –yes。

hermes import-agent claude-code
hermes import-agent codex

第四步不要急着上真实项目。先打开 Hermes 检查 Memory 与 Skill 列表，再挑一个无害 MCP 做连接测试，最后让 Agent 运行一条允许名单里的只读命令。成功标志是：旧规则能被找到，Skill 目录出现，MCP 名称存在，凭证仍需单独配置，原有 Hermes 配置没有消失。

验收时我会再做一组反向检查：旧工具目录是否完全没被改；Hermes 里原有的模型、消息平台和审批设置是否还在；被报告为 skipped 的项目是否真的没落盘；导入后的 Memory 有没有把临时路径写成长期规则。迁移成功报告只能证明程序完成，反向检查才能证明工作环境没有被意外改形。

只有确认冲突项的确 应该被旧配置替换时，才使用下面这组强选项。它会跳过询问并允许覆盖，适合已经审过 dry-run 的明确场景，不适合第一次见面就闭眼执行。

hermes import-agent claude-code --overwrite --yes

最容易翻车的 5 个地方，报告里实则已经提前打灯

第一，迁移的是全局设置，不会替你理解每个仓库里的局部规矩。项目里的 AGENTS.md、CLAUDE.md 和其他上下文文件仍要按项目检查，避免全局 Memory 与局部规则相互打架。

第二，命令允许规则在两个工具中的语义不完全一样。自动转换的 Bash 通配符要逐条看，尤其是带星号、路径和脚本参数的规则。允许范围过宽时，应该在 Hermes 里重新收紧。

第三，看到 MCP 导入成功就以为能直接用。敏感环境变量被移除属于保护动作，连接报未授权时先补凭证，别反复覆盖配置。

第四，–overwrite –yes 很省点击，也会跳过两道刹车。默认冲突跳过更适合第一次迁。需要替换时先备份 ~/.hermes，再明确写出是哪一个 Skill 或 MCP 该被覆盖。

第五，当前官方命令只接受 claude-code 与 codex。Cursor、OpenCode 等工具即便也有 Skill 或 MCP，也不在这份映射里。强行把目录伪装成 Codex 来源，可能得到一份看似成功、实际漏项的迁移。

第六，Memory 合并去重依赖文本内容，语义相近、写法不同的两条规则仍可能同时存在。一条写“先运行测试”，另一条写“修改后必须执行测试”，人看着近似，系统未必会合并。导入后读一遍 MEMORY.md，删除重复口径，能减少 Agent 每轮收到的噪声。

第七，旧白名单也许早已过宽。迁移工具忠实带走规则，不会替你判断三个月前放行的命令如今还该不该放。搬家正好是一次权限体检：不认识的删掉，带通配符的收紧，能按项目配置的别放到全局。

我的取舍：先把可复用经验带走，账号和权限重新过一遍

如果你在 Claude Code 或 Codex 里已经积累了规则、Skill 和 MCP，import-agent 很值得用。它最大的收益是给出一份结构化搬家清单，让漏项、冲突和敏感字段都能被看见。

刚装两个工具、配置几乎空白的朋友，手工重设也许更快。团队环境、生产机器和高权限 MCP 则应该把 dry-run 报告交给第二个人复核，再执行正式导入。迁移快不等于授权可以快。

我自己的顺序会固定下来：先预览，保存旧配置备份，导入规则与 Skill，重新配置凭证，用临时目录做最小测试，最后才进入真实项目。旧工具留下的经验值得带走，旧授权不值得不加检查地继承。

一条命令的真正价值，不在把所有东西塞进新家。它帮我分清哪些属于经验，哪些属于钥匙，哪些搬不过去。搬家最舒服的状态，就是桌面很快恢复熟悉，门锁仍由自己重新确认。