openclaw-migrator 🦞

小龙虾导出 / 导入工具 — 将 OpenClaw 的完整个性化状态打包为一个 .zip 文件，并可在任意环境中完整恢复。

无论是换新设备、备份历史状态，还是在团队之间共享龙虾人格，都可以用这个工具一键完成。

特性

完整覆盖：涵盖人格（SOUL/IDENTITY）、记忆、配置、技能、Hook、插件扩展、会话历史等 9 个可选范围
默认安全：API keys 自动脱敏，auth-profiles.json / OAuth token 默认不打包
凭证可选：本地迁移时可通过 --with-credentials 显式开启凭证打包
交互引导：无参数运行时全程交互，引导选择打包内容；也可完全参数化用于自动化脚本
冲突处理：导入时支持逐项询问、全部覆盖、保留本地三种策略
Dry-run：预演导入，不写入文件，查看将要发生的变化
Manifest：每个包附带 manifest.json，记录导出时间、来源、范围、是否含凭证
多工作区：支持 --profile 切换不同 OpenClaw 工作区
纯 Node.js：无额外系统依赖，Node 20+ 即可运行

安装

方式一：在项目目录中直接运行

git clone <this-repo>
cd openclaw-migrator
npm install
npm run build
node bin/cli.cjs --help

方式二：全局安装（推荐）

cd openclaw-migrator
npm install
npm run build
npm link
# 之后可在任意目录使用
openclaw-migrator --help

系统要求

Node.js >= 20.0.0
npm >= 9（或 pnpm / yarn）

快速上手

导出（交互引导模式）

openclaw-migrator export

工具会依次询问：

输出文件路径（默认为当前目录下 openclaw-<timestamp>.zip）
工作区 Profile 名（多工作区时使用）
Agent ID（影响会话历史路径，默认 pi）
打包内容选择（多选，按空格切换）

导出（非交互，指定参数）

openclaw-migrator export -o ~/my-lobster.zip -s config,workspace,skills,extensions -y

查看包内容

openclaw-migrator info ~/my-lobster.zip

导入恢复

openclaw-migrator import ~/my-lobster.zip

遇到冲突时会逐项询问：覆盖此文件 / 跳过此文件 / 覆盖所有冲突 / 跳过所有冲突。

命令详解

`export` — 导出打包

将 ~/.openclaw/ 下的用户数据打包为 .zip。

别名： pack

openclaw-migrator export [options]
openclaw-migrator pack [options]

选项

选项	说明	默认值
`-o, --output <file>`	输出 `.zip` 文件路径	`openclaw-<timestamp>.zip`（当前目录）
`-s, --scopes <ids>`	打包范围，逗号分隔（见打包范围）	交互选择
`-p, --profile <name>`	工作区 Profile，对应 `~/.openclaw/workspace-<name>/`	默认 workspace
`--agent-id <id>`	Agent ID，影响会话历史路径	`pi`
`-y, --yes`	跳过所有交互提示，使用默认值	—
`--with-credentials`	开启凭证打包（详见安全机制）	不开启

示例

# 全交互引导（推荐初次使用）
openclaw-migrator export

# 指定输出路径，其余交互
openclaw-migrator export -o ~/backup/lobster.zip

# 指定打包范围，快速导出（跳过交互）
openclaw-migrator export -o ~/backup.zip -s config,workspace,skills,extensions -y

# 导出人格 + 技能 + 插件（不含配置，适合分享龙虾人格）
openclaw-migrator export -o ~/persona-only.zip -s workspace,skills,extensions -y

# 导出包含会话历史（文件可能较大）
openclaw-migrator export -o ~/full.zip -s config,workspace,skills,hooks,extensions,sessions -y

# 完整本地迁移（含凭证，勿分享！）
openclaw-migrator export -o ~/migration.zip --with-credentials -y

# 使用指定 profile 的工作区
openclaw-migrator export --profile work -o ~/work-lobster.zip

# CI / 自动备份脚本
openclaw-migrator export -o "backup-$(date +%Y%m%d).zip" -s config,workspace,skills -y

`import` — 导入恢复

从 .zip 包恢复到 ~/.openclaw/（或指定目录）。

别名： restore

openclaw-migrator import <package> [options]
openclaw-migrator restore <package> [options]

选项

选项	说明	默认值
`<package>`	`.zip` 文件路径（必填）	—
`-d, --dest <dir>`	导入目标目录	`~/.openclaw`（或 `$OPENCLAW_STATE_DIR`）
`-c, --conflict <strategy>`	冲突策略：`ask` / `overwrite` / `skip`	`ask`
`--dry-run`	预演，不实际写入	—
`-y, --yes`	跳过确认，冲突时直接覆盖	—

冲突处理策略说明

策略	行为
`ask`（默认）	遇到冲突文件时弹出交互菜单，可选择：覆盖此文件 / 跳过此文件 / 覆盖所有冲突 / 跳过所有冲突
`overwrite`	所有冲突文件直接覆盖，无需确认
`skip`	本地已有的文件一律跳过，只补充缺失文件

示例

# 交互模式，遇到冲突逐项确认
openclaw-migrator import my-lobster.zip

# 先预演，查看会写入哪些文件，不实际执行
openclaw-migrator import my-lobster.zip --dry-run

# 直接覆盖所有文件（换新设备时常用）
openclaw-migrator import my-lobster.zip --conflict overwrite

# 保留本地文件，只补充包中有而本地没有的
openclaw-migrator import my-lobster.zip --conflict skip

# 导入到测试目录（不影响真实环境）
openclaw-migrator import my-lobster.zip -d /tmp/openclaw-test

# 非交互覆盖（脚本/CI 恢复场景）
openclaw-migrator import my-lobster.zip -y

# 使用别名 restore
openclaw-migrator restore my-lobster.zip --dry-run

注意： 如果导入的包含 openclaw.json，其中的 API keys 已被脱敏为占位符 [REDACTED by openclaw-migrator]，导入后需手动编辑补充真实的 key：
$EDITOR ~/.openclaw/openclaw.json

`info` — 查看包内容

查看 .zip 包的元数据和文件列表，不解压，不写入任何文件。

别名： inspect

openclaw-migrator info <package>
openclaw-migrator inspect <package>

输出内容

文件大小
Manifest 元数据：工具版本、导出时间、来源目录、包含范围、是否含凭证
按目录分组的文件列表（含各文件大小）
解压后总大小估算

示例

openclaw-migrator info my-lobster.zip
openclaw-migrator inspect ~/backups/lobster-20260319.zip

输出示例：

🦞 OpenClaw Migrator — 包信息

  文件:     /Users/you/my-lobster.zip
  大小:     128.5 KB

── 包元数据 ─────────────────────────────────────
  工具:     openclaw-migrator v1
  导出时间: 2026-03-19T03:24:20.462Z
  来源目录: /Users/you/.openclaw
  包含范围: config, workspace, skills, extensions
  Agent ID: pi
  含凭证:   否 ✓  (已脱敏 / 已剥离)

  ℹ  API keys and auth tokens have been redacted...

── 文件列表 (12 个) ─────────────────────────────

  extensions/  (2 个文件, 3.3 KB)
    · skillhub/index.ts  2.0 KB
    · skillhub/openclaw.plugin.json  1.3 KB

  skills/  (3 个文件, 87 B)
    · frontend-design  36 B
    · gog  24 B
    · simple  27 B

  workspace/  (7 个文件, 42.1 KB)
    · SOUL.md  3.2 KB
    · IDENTITY.md  0.8 KB
    ...

  共 12 个文件，解压后约 45.5 KB

`scopes` — 列出打包范围

列出所有支持的打包范围 ID、说明和默认状态。

openclaw-migrator scopes

打包范围

通过 -s, --scopes 参数指定，多个用逗号分隔。

Scope ID	内容	路径	默认
`config`	主配置文件，渠道、模型、技能加载等所有配置（API keys 自动脱敏）	`~/.openclaw/openclaw.json`	✅
`workspace`	工作区核心：人格（SOUL.md）、身份（IDENTITY.md）、用户档案（USER.md）、行为规则（AGENTS.md）、长期记忆（MEMORY.md）、每日日记等	`~/.openclaw/workspace/`	✅
`skills`	通过 `openclaw skill install` 安装的用户技能包	`~/.openclaw/skills/`	✅
`hooks`	用户安装的 Hook 事件响应器	`~/.openclaw/hooks/`	✅
`extensions`	用户安装的插件扩展（`openclaw.plugin.json` + 实现代码）	`~/.openclaw/extensions/`	✅
`cron`	持久化的定时任务列表	`~/.openclaw/cron/jobs.json`	❌
`memory-lancedb`	LanceDB 向量记忆数据库，体积可能较大	`~/.openclaw/memory/lancedb/`	❌
`media`	Agent 接收的图片、音频等媒体文件	`~/.openclaw/media/`	❌
`sessions`	完整对话历史记录（JSONL），体积大且含敏感信息	`~/.openclaw/agents/<id>/sessions/`	❌

默认启用的 5 个范围（config、workspace、skills、hooks、extensions）覆盖了小龙虾的全部"人格与能力"，适合绝大多数迁移和备份场景。sessions、memory-lancedb 等体积大、含敏感内容的范围需要显式开启。

安全机制

默认安全行为（无需任何参数）

以下文件始终被剥离，无论选择了哪些范围：

被剥离的文件/目录	原因
`auth-profiles.json`	所有 provider 的 API key、OAuth token
`auth.json`	旧版认证文件
`oauth.json`	OAuth 认证状态
`.env`	环境变量文件
`credentials/` 目录	OAuth 凭证目录

openclaw.json 中以下字段的非空字符串值会被替换为占位符 [REDACTED by openclaw-migrator]：

apiKey · token · botToken · appToken · clientSecret · clientId
accessToken · refreshToken · secret · password · webhookSecret
signingSecret · verificationToken · bearerToken · privateKey · cert · key

`--with-credentials` 模式（显式开启）

当需要在本地可信设备之间完整迁移（例如更换电脑）时，可使用此参数：

openclaw-migrator export -o ~/migration.zip --with-credentials

开启后的变化：

auth-profiles.json、oauth.json 等凭证文件会被包含
openclaw.json 中的敏感字段不会脱敏，保留原始值
Manifest 中 credentialsIncluded: true，info 命令会显示红色警告

安全建议：

使用完整迁移包后立即删除本地文件
绝不将含凭证的包上传到云存储、发送给他人或提交到 Git
传输时使用加密渠道（AirDrop、加密 U 盘等）

环境变量

工具完整支持 OpenClaw 的路径环境变量，可用于在非标准安装位置或多实例场景中工作：

变量	说明	默认值
`OPENCLAW_STATE_DIR`	覆盖整个状态目录根路径	`~/.openclaw`
`OPENCLAW_CONFIG_PATH`	覆盖 `openclaw.json` 路径	`$STATE_DIR/openclaw.json`
`OPENCLAW_OAUTH_DIR`	覆盖 OAuth 凭证目录	`$STATE_DIR/credentials`

示例： 在自定义路径的 OpenClaw 实例上导出

OPENCLAW_STATE_DIR=/data/my-openclaw openclaw-migrator export -o backup.zip -y

示例： 导入到测试实例

OPENCLAW_STATE_DIR=/tmp/openclaw-test openclaw-migrator import backup.zip --conflict overwrite -y

典型使用场景

场景一：换新电脑（完整迁移）

# 旧电脑：完整打包（含凭证）
openclaw-migrator export -o ~/Desktop/migration.zip --with-credentials -y

# 将文件传输到新电脑（AirDrop / 加密 U 盘）

# 新电脑：安装 OpenClaw 后恢复
openclaw-migrator import ~/migration.zip --conflict overwrite -y

# 完成后删除迁移包
rm ~/migration.zip

场景二：日常备份（安全，可云端存储）

# 每天自动备份人格和配置（API keys 已脱敏）
openclaw-migrator export \
  -o "~/backups/lobster-$(date +%Y%m%d).zip" \
  -s config,workspace,skills,extensions \
  -y

# 保留最近 7 天的备份
ls -t ~/backups/lobster-*.zip | tail -n +8 | xargs rm -f

场景三：分享龙虾人格（不含任何凭证或配置）

# 只打包人格 + 技能 + 插件，安全可分享
openclaw-migrator export \
  -o ~/share/my-persona.zip \
  -s workspace,skills,extensions \
  -y

场景四：多工作区切换

# 导出 work profile
openclaw-migrator export --profile work -o ~/work-lobster.zip -y

# 切换到 personal profile 后导入 work 配置到测试目录
openclaw-migrator import ~/work-lobster.zip \
  -d ~/.openclaw-work-backup \
  --conflict skip

场景五：在导入前检查包内容

# 先查看，再决定是否导入
openclaw-migrator info ~/someone-shared.zip

# 确认没问题后导入，先 dry-run
openclaw-migrator import ~/someone-shared.zip --dry-run
openclaw-migrator import ~/someone-shared.zip --conflict ask

场景六：恢复部分内容（只补充缺失的技能）

# 跳过已存在的文件，只补充包中有而本地没有的技能/插件
openclaw-migrator import backup.zip --conflict skip

项目结构

openclaw-migrator/
├── src/
│   ├── cli.ts          # CLI 入口（commander），命令注册与参数解析
│   ├── export.ts       # export 命令实现：交互引导、范围收集、打包、脱敏
│   ├── import.ts       # import 命令实现：解压、冲突处理、文件写入
│   ├── info.ts         # info 命令实现：读取 manifest、展示文件列表
│   ├── paths.ts        # ~/.openclaw 路径解析（支持环境变量覆盖）
│   ├── scope.ts        # 9 个打包范围定义 + ALWAYS_STRIP_PATTERNS
│   └── sanitize.ts     # openclaw.json 敏感字段递归脱敏
├── bin/
│   └── cli.cjs         # 构建产物（esbuild bundle，CJS，含 shebang）
├── build.mjs           # esbuild 构建脚本
├── package.json
└── README.md

依赖说明

依赖	版本	用途
`commander`	^12	CLI 命令框架
`@inquirer/prompts`	via `inquirer` ^10	交互式提示（checkbox、input、confirm、select）
`archiver`	^7	创建 zip 压缩包
`unzipper`	^0.12	解析/解压 zip 包
`chalk`	^5	终端彩色输出
`ora`	^8	终端 spinner 进度指示
`esbuild`	^0.24	构建打包（devDependency）

开发

# 安装依赖
npm install

# 开发模式（直接运行 TypeScript 源码，Node 22+ 支持原生 strip-types）
npm run dev -- export --help
npm run dev -- export -o /tmp/test.zip -s extensions -y

# 构建产物
npm run build
# → bin/cli.cjs

# 运行构建产物
npm start -- --help
node bin/cli.cjs export --help

# 全局链接（开发时方便测试）
npm link
openclaw-migrator --help

# 取消全局链接
npm unlink -g openclaw-migrator

添加新的打包范围

在 src/scope.ts 的 SCOPE_DEFINITIONS 数组中追加一个 ScopeDefinition 对象：

{
  id: "my-scope" as ScopeId,
  label: "我的新范围 (my-scope/)",
  description: "描述这个范围包含什么",
  defaultEnabled: false,
  getItems({ agentId }) {
    return [{ src: join(getStateDir(), "my-dir"), dest: "my-dir", type: "dir" }];
  },
}

同时在 ScopeId 类型联合中添加对应字符串字面量。重新 npm run build 后即生效。

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src		src
.gitignore		.gitignore
README.md		README.md
build.mjs		build.mjs
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

openclaw-migrator 🦞

目录

特性

安装

方式一：在项目目录中直接运行

方式二：全局安装（推荐）

系统要求

快速上手

导出（交互引导模式）

导出（非交互，指定参数）

查看包内容

导入恢复

命令详解

export — 导出打包

选项

示例

import — 导入恢复

选项

冲突处理策略说明

示例

info — 查看包内容

输出内容

示例

scopes — 列出打包范围

打包范围

安全机制

默认安全行为（无需任何参数）

--with-credentials 模式（显式开启）

环境变量

典型使用场景

场景一：换新电脑（完整迁移）

场景二：日常备份（安全，可云端存储）

场景三：分享龙虾人格（不含任何凭证或配置）

场景四：多工作区切换

场景五：在导入前检查包内容

场景六：恢复部分内容（只补充缺失的技能）

项目结构

依赖说明

开发

添加新的打包范围

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`export` — 导出打包

`import` — 导入恢复

`info` — 查看包内容

`scopes` — 列出打包范围

`--with-credentials` 模式（显式开启）

Packages