——
OpenClaw 新功能：安装后自动迁移 Codex CLI 配置的 3 种场景
OpenClaw 最新版本（commit #81192）引入了一项重要改进：在安装 Harness 插件后，向导可自动提示用户导入现有的 Codex CLI 状态，包括 skills、归档配置、hooks 以及缓存的 advisory 插件。这一功能显著降低了从 Codex CLI 迁移到 OpenClaw 的门槛，让开发者能够无缝延续之前的 AI 工作流。
为什么需要这个功能？
许多开发者在使用 OpenClaw 之前，已经在 Codex CLI 上积累了大量配置：
- 自定义的 skills（AI 技能定义）
- 个性化的 hooks 和配置文件
- 本地缓存的插件数据
手动迁移这些内容既繁琐又容易出错。新功能通过自动检测和一键迁移，解决了这一痛点。
—
核心功能详解
1. 双模式触发机制
迁移提示在两种安装场景下都会触发：
| 场景 | 触发位置 | 交互方式 |
|:—|:—|:—|
| 交互式安装 | src/plugins/provider-auth-choice.ts | 完整向导提示，用户可选择接受或拒绝 |
| 非交互式安装 | src/commands/onboard-non-interactive/... | 仅输出提示信息，不修改状态 |
两个入口都通过统一的 helper 函数 offerPostInstallMigrations 实现，确保行为一致性。
2. 通用迁移架构
迁移逻辑完全解耦，不硬编码 Codex 特定逻辑：
// src/wizard/setup.post-install-migration.ts 核心流程
async function offerPostInstallMigrations(options: {
installedPlugins: string[];
nonInteractive?: boolean;
}) {
// 1. 通过 manifest 的 migrationProviders 契约解析迁移提供者
const providers = await resolveMigrationProviders();
// 2. 过滤出本次安装步骤中标记为已安装的插件
const relevantProviders = providers.filter(p =>
options.installedPlugins.includes(p.ownerPlugin)
);
// 3. 执行 detect() 检测可迁移内容
for (const provider of relevantProviders) {
const detectResult = await provider.detect();
// 4. TTY 环境下提示用户，接受后执行迁移
if (detectResult.hasData && !options.nonInteractive) {
const accepted = await promptUser(provider.name);
if (accepted) {
await migrateDefaultCommand(provider);
}
}
}
}
关键设计原则：所有 detect、prompt、migrate 的失败都被捕获，确保 onboarding 不会因可选迁移而中断。
3. 子进程生命周期加固
由于 detect() 现在运行在更热的 onboarding 路径上，团队强化了 Codex app-server 的子进程管理：
// extensions/codex/src/app-server/request.ts
async function isolatedPluginRead(request: PluginReadRequest) {
const child = spawnCodexAppServer();
try {
// 隔离的 plugin/read 调用
const result = await sendRequest(child, request);
return result;
} finally {
// 确保子进程退出，SIGKILL 兜底
await gracefulShutdown(child, {
timeout: 5000,
killSignal: 'SIGKILL'
});
}
}
这一改进防止了 orphaned codex binary 导致父进程挂起的问题。
—
实际使用场景
场景一：全新安装后的迁移
首次安装 OpenClaw
openclaw onboard
向导输出示例：
✔ Harness 插件安装完成
? 检测到 Codex CLI 配置，是否迁移？ (Y/n)
- 3 个 skills
- 1 个自定义 hook
- 12 个缓存插件
选择 Y 后，自动执行：
openclaw migrate codex --skills --config --cache
场景二：修复安装后的迁移
修复模式重新安装插件
openclaw onboard --repair
同样会触发迁移提示
已迁移的内容会自动去重，避免重复导入
场景三：CI/CD 非交互式环境
自动化脚本中使用
openclaw onboard --non-interactive
输出：
[INFO] Harness 插件已安装
[HINT] 运行 'openclaw migrate codex' 导入现有配置
—
技术实现亮点
| 设计决策 | 优势 |
|:—|:—|
| Manifest 驱动的提供者发现 | 新增迁移源无需修改核心代码 |
| 失败静默处理 | 保障 onboarding 成功率 |
| 隔离子进程 + 强制清理 | 消除资源泄漏风险 |
| 双模式统一入口 | 降低维护复杂度 |
—
常见问题 (FAQ)
Q1: 迁移会覆盖我现有的 OpenClaw 配置吗？
不会。迁移采用追加模式，openclaw migrate codex 命令会智能合并配置。如遇命名冲突，会提示你选择保留哪个版本。
Q2: 非交互式安装后如何手动触发迁移？
运行以下命令：
openclaw migrate codex --all
或使用细粒度选项：
openclaw migrate codex --skills-only # 仅迁移 skills
openclaw migrate codex --config-only # 仅迁移配置
Q3: 迁移失败会影响 OpenClaw 的正常使用吗？
不会。如技术架构所述，所有迁移错误都被捕获并记录为警告，onboarding 流程会继续完成。你可以后续通过日志排查：
openclaw logs --category=migration
Q4: 哪些 Codex CLI 数据可以被迁移？
当前支持：
- Skills：
~/.codex/skills/目录下的自定义技能 - 配置：
~/.codex/config.json及 hooks - 缓存插件：
~/.codex/cache/advisory/中的插件
不支持迁移历史对话记录和临时文件。
Q5: 如何禁用自动迁移提示？
在交互式安装中，选择 n 拒绝即可。如需永久禁用，可在 ~/.openclaw/config.json 中设置：
{
"onboarding": {
"skipPostInstallMigrations": ["codex"]
}
}
—
总结与下一步
本次更新让 OpenClaw 的 onboarding 体验更加顺滑，特别是为 Codex CLI 老用户提供了零摩擦的迁移路径。核心收益：
1. 保留投资——已有的 AI 技能和工作流配置不再浪费
2. 渐进迁移——按需选择迁移内容，降低切换成本
3. 稳定可靠——加固的子进程管理确保安装过程不卡死
推荐操作：
- 新用户：直接运行
openclaw onboard体验完整向导 - 老用户：检查是否有未迁移的 Codex 配置，执行
openclaw migrate codex --detect查看可迁移内容
—
相关阅读
—
参考来源
