> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 把 OpenClaw 搬到 Hermes 沙箱

> 用 PPHermes 的 migrate 命令一键迁移：既支持从 PPIO 上的 OpenClaw 沙箱同步，也支持从本地电脑的 .openclaw 目录同步到云端 Hermes Agent。

<Warning>
  本文档中的 `--from-local` 模式需要 **PPHermes v1.1.0 及以上版本**（`--from` 沙箱到沙箱模式 v1.0.0 就支持）。升级 CLI：

  **macOS / Linux：**

  ```bash theme={null}
  curl -fsSL https://pphermes.ppio.com/install.sh | bash
  ```

  **Windows (PowerShell)：**

  ```powershell theme={null}
  irm https://pphermes.ppio.com/install.ps1 | iex
  ```

  **或通过 pip：**

  ```bash theme={null}
  pip install -U pphermes
  ```

  验证版本：

  ```bash theme={null}
  pphermes --version
  # 期望输出：pphermes, version 1.1.0（或更高）
  ```
</Warning>

<Tip>
  还没部署过 Hermes？先完成[新手快速部署](/sandbox/hermes-agent/quickstart)里的 Python 环境、API Key 和 `pphermes launch` 步骤，拿到目标 `Sandbox ID`，再回来看这篇。
</Tip>

## 这篇教程解决什么

你之前用过 OpenClaw —— 要么跑在**云端 PPIO 沙箱**上（通过 PPClaw 部署过），要么跑在**自己的电脑**上 —— 现在想把 `.openclaw` 里积累的记忆（memories）、人设（SOUL.md）、profile、技能、密钥、AGENTS.md 等等**一次性搬到云端 Hermes 沙箱**，让 Hermes Agent 接着干活。

`pphermes migrate` 一条命令就能搞定，底层会：

1. 在数据源端把 `.openclaw` 目录打包成 `tar.gz`
2. 通过 File Manager（HTTP）上传到**目标** Hermes 沙箱
3. 沙箱内调用 **Hermes 原生迁移命令**（`hermes claw migrate`）把 OpenClaw 状态翻译成 Hermes 格式
4. 自动跑一次**健康检查 + Chat 探针**，确认 Agent 真的能对话

不需要你自己上传、解压、调用 hermes 任何东西。

## 先选对迁移模式

PPHermes 的 `migrate` 命令有两种工作模式，**不能同时用**（一起指定会直接报 `INVALID_USAGE`）：

| 模式        | 用什么参数                        | 数据源在哪                       | 适用场景                                                         |
| --------- | ---------------------------- | --------------------------- | ------------------------------------------------------------ |
| **沙箱到沙箱** | `--from <source-sandbox-id>` | 已经跑在 PPIO 上的另一个 OpenClaw 沙箱 | 你之前通过 [PPClaw](/sandbox/openclaw-quickstart) 在云端部署过 OpenClaw |
| **本地到沙箱** | `--from-local`               | 你电脑上的 `~/.openclaw/` 目录     | 你一直在本地跑 OpenClaw                                             |

不知道选哪个？简单判断：

* 能在 `ppclaw list` 里看到源沙箱 → **沙箱到沙箱**
* `ls ~/.openclaw/SOUL.md` 能看到文件 → **本地到沙箱**

下面分两条路径讲，用哪条看哪条就行。

## 共同准备工作

不管用哪种模式，这四件事都要先做好：

1. **PPHermes ≥ 1.1.0** —— 见本页顶部的 Warning。
2. **PPIO API Key 已经设好** —— `echo $PPIO_API_KEY` 能看到 `sk_` 开头的字符串。
3. **目标 Hermes 沙箱已经 `running`** —— 手里有目标 `Sandbox ID`（形如 `hermes-abc123-fb47b43e`）。新建沙箱请参考[新手快速部署](/sandbox/hermes-agent/quickstart)。
4. **确认下数据源** —— 根据你要走的模式，记下**源 OpenClaw 沙箱 ID**（沙箱到沙箱），或**本地 `.openclaw` 路径**（本地到沙箱）。

一键验证：

```bash theme={null}
pphermes --version                          # ≥ 1.1.0
echo $PPIO_API_KEY | head -c 10             # sk_ 开头
pphermes list                               # 目标 hermes sandbox 状态 running
```

***

## 路径 A：沙箱到沙箱（`--from`）

适合"你之前在 PPIO 上用 PPClaw 部署过 OpenClaw"的情况。数据完全在云端流转，你本地无需访问 `.openclaw` 文件。

### A1. 拿到源 OpenClaw 沙箱 ID

```bash theme={null}
ppclaw list
```

找到你要迁移的那个沙箱，复制它的 `Sandbox ID`（形如 `sbx-xxx`）。确认它状态是 `running`，不是的话先 `ppclaw resume <id>`。

### A2. 先干跑一次（强烈推荐）

`--dry-run` 会**完整**走"打包 → 上传 → 沙箱内解压"全流程，但最后一步不会真正改动目标沙箱，只让 Hermes 报告"如果真的迁移，会怎么变化"。适合第一次跑之前提前暴露网络问题或大小超限：

```bash theme={null}
pphermes migrate <HERMES_SANDBOX_ID> \
  --from <OPENCLAW_SANDBOX_ID> \
  --dry-run \
  -y
```

看到 `dry_run: true` + `Migration complete` 就说明链路通了，目标沙箱**没有任何改动**。

### A3. 真的跑一次

```bash theme={null}
pphermes migrate <HERMES_SANDBOX_ID> \
  --from <OPENCLAW_SANDBOX_ID> \
  --overwrite \
  -y
```

常用参数：

* **`--overwrite`** —— 目标沙箱里已有同名 Hermes 配置 / 记忆时覆盖。不带的话冲突项会被跳过并留一条警告。
* **`--preset full`**（默认）—— 全量迁移，包括模型配置、API Key 等。
* **`--preset user-data`** —— **只**迁移用户数据（记忆、profile、SOUL.md），不碰 API Key 和 provider 配置；这种情况下你需要在沙箱里自己配 `OPENAI_API_KEY` 等秘钥。
* **`--exclude-tts`** —— 丢掉 TTS 音频缓存（`*.wav`、`*.mp3`、`audio-cache/` 等），传得更快。推荐默认带上。

### A4. 顺带搬项目文件（可选）

默认 `--from` 模式**只**迁移 `.openclaw`。如果你在源沙箱的 `~/workspace/`、`~/projects/` 下有项目文件想一起搬，加上 `--include-workspace`：

```bash theme={null}
pphermes migrate <HERMES_SANDBOX_ID> \
  --from <OPENCLAW_SANDBOX_ID> \
  --include-workspace \
  --overwrite -y
```

也可以显式指定要迁的目录（**路径必须在源沙箱的 `/home/user/` 下**）：

```bash theme={null}
pphermes migrate <HERMES_SANDBOX_ID> \
  --from <OPENCLAW_SANDBOX_ID> \
  --include-workspace \
  --workspace-path /home/user/projects/my-analysis \
  --workspace-path /home/user/projects/another-project \
  --overwrite -y
```

默认排除 `node_modules,.venv,__pycache__,.cache,target,dist,build,.git`（逗号分隔，可通过 `--workspace-exclude` 覆盖）。总大小默认上限 **2 GiB**，超了直接拒绝；真要硬上用 `--force-size`。

***

## 路径 B：本地到沙箱（`--from-local`）

适合"你一直在自己电脑上用 OpenClaw"的情况。打包、上传都在你本机发起。

### B1. 确认本地 `.openclaw` 可读

默认位置是 `~/.openclaw/`，其他位置用 `--openclaw-path` 传绝对路径：

```bash theme={null}
ls ~/.openclaw/SOUL.md                      # 文件存在说明目录有效
```

### B2. 先干跑一次（强烈推荐）

```bash theme={null}
pphermes migrate <HERMES_SANDBOX_ID> \
  --from-local \
  --openclaw-path ~/.openclaw \
  --dry-run \
  -y
```

看到 `dry_run: true` + `Migration complete` 就说明打包、上传、解压链路都通了。

### B3. 真的跑一次

```bash theme={null}
pphermes migrate <HERMES_SANDBOX_ID> \
  --from-local \
  --openclaw-path ~/.openclaw \
  --overwrite \
  -y
```

参数 `--overwrite` / `--preset` / `--exclude-tts` 的作用和路径 A 完全相同。

### B4. 顺带搬本地项目（可选）

本地的项目目录（比如 `~/projects/my-analysis/`）可以一起同步：

```bash theme={null}
pphermes migrate <HERMES_SANDBOX_ID> \
  --from-local \
  --openclaw-path ~/.openclaw \
  --workspace-path ~/projects/my-analysis \
  --workspace-path ~/projects/another-project \
  --overwrite -y
```

* `--workspace-path` 可以**重复多次**，每个目录打包成一个独立 tar.gz 并解压到沙箱的 `~/workspace/from-openclaw/<目录名>/`。
* 默认排除 `node_modules/`、`.venv/`、`__pycache__/`、`.git/`、`dist/`、`build/` 等常见生成物。
* 总大小默认上限 **2 GiB**；自定义排除用 `--workspace-exclude '*.log'`（fnmatch 语法，可重复）。

### B5. 只迁项目、不迁 OpenClaw

Hermes 沙箱已经配好、你只想把本地项目目录拷进去：

```bash theme={null}
pphermes migrate <HERMES_SANDBOX_ID> \
  --from-local \
  --no-openclaw \
  --workspace-path ~/projects/my-analysis \
  -y
```

### B6. 关于软链接和硬链接（仅 `--from-local`）

<Warning>
  **软链接和硬链接会被丢弃**。为了避免你的本地软链接（比如 `~/.ssh`、指向某个绝对路径的快捷方式）在沙箱里被意外解引用到别的文件，`--from-local` **不会**保留任何符号链接或硬链接。

  如果某个目录是通过软链接组织的（比如 `.openclaw/memories` → `/some/other/path`），请**先把链接物化成真实目录**再跑命令：

  ```bash theme={null}
  cp -rL ~/.openclaw /tmp/openclaw-materialized
  pphermes migrate <HERMES_SANDBOX_ID> \
    --from-local \
    --openclaw-path /tmp/openclaw-materialized -y
  ```
</Warning>

***

## 迁移后的健康检查（两种模式共用）

不管走哪条路径，非 dry-run 模式**成功完成后**都会自动打出两块面板：迁移摘要 + 健康检查。典型输出类似：

```text theme={null}
╭──────── Migration complete ────────╮
│ Preset: full                       │
│ Overwrite: no                      │
│ Tarball size: 12.3 MiB             │
│ Migrated: 12 item(s)               │
│ Skipped: 1                         │
╰────────────────────────────────────╯

╭───── Post-migration health check ─────╮
│ ✓ No config pollution detected.       │
│ ✓ Model probe: "Hi there" (0.5s)      │
╰───────────────────────────────────────╯
```

<Note>
  **关于 Conflicts 这一行的文案** —— 如果有冲突项且**没带** `--overwrite`，面板会提示 `Conflicts: N (use --overwrite to replace)`；已经带了 `--overwrite` 但仍然有冲突，说明那些项是 Hermes 主动保护、不会被覆盖的，文案会显示 `Conflicts: N (protected by Hermes)`（PPHermes ≥ 1.1.1）。
</Note>

健康检查做了两件事：

* **配置体检（config sanitizer）** —— 修复 Hermes 已知的几个配置坑（例如 `model.default` 里多出来的 provider 前缀、重复的 `custom_providers`）。有问题时会标 `!` 或 `✗`，自动修复后会带 `(auto-fixed)` 标签并把 before / after 的值打出来。
* **模型探针（chat probe）** —— 向 Agent 真的发一条消息并读回复；成功显示 `✓ Model probe: "..."`，失败会标红并给出错误原因。

两项全绿说明沙箱里的 Hermes Agent 已经可以直接用了。

## 常见问题

| 遇到什么                                                          | 为什么                          | 怎么办                                                                                    |
| ------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------- |
| `INVALID_USAGE` + `--from / --from-local mutually exclusive`  | 两个模式参数一起写了                   | 按表格选一个，删掉另一个                                                                           |
| `INVALID_USAGE` + `--openclaw-path requires --from-local`     | 本地路径参数但没指定模式                 | 加 `--from-local`；或者改用 `--from <source-id>`                                             |
| `INVALID_USAGE` + `source == target`                          | `--from` 传的是目标自己的 ID         | `--from` 要传**源** OpenClaw 沙箱 ID，不是目标 Hermes                                            |
| `MIGRATION_FAILED` + `Local .openclaw directory not found`    | `--from-local` 模式下路径错了或目录不存在 | `ls ~/.openclaw` 检查，用绝对路径传给 `--openclaw-path`                                          |
| `MIGRATION_FAILED` + `File Manager credentials not available` | 目标 Hermes 沙箱的服务还没起来          | `pphermes status <id>` 确认 `filemanager_url` 存在；或 `pphermes gateway restart <id>` 重启    |
| `exceeds limit 2.0 GiB`                                       | workspace 打包体积超上限            | 加 `--workspace-exclude` 过滤大文件，或 `--force-size` 硬上                                      |
| 健康检查面板里 `chat_probe` 红色                                       | 模型配置有问题                      | 进沙箱 Web Terminal 跑 `hermes chat -q "hi"` 看完整报错；常见原因是 `--preset user-data` 之后没配 API Key |
| 沙箱里 `~/workspace/from-openclaw/` 已有同名目录                       | 之前迁移过一次                      | 想覆盖就带 `--overwrite`；想保留两份就改源路径目录名再传                                                    |
| 想看具体会做什么但不执行                                                  | ——                           | 任何模式都支持 `--dry-run`                                                                    |

## 迁完之后

打开 `pphermes status <HERMES_SANDBOX_ID>` 输出里的 **Hermes Web UI** 链接，进入后应该能看到：

* 原来的人设和记忆已经在对话上下文里
* 项目文件在沙箱的 `~/workspace/from-openclaw/<your-project>/`（如果带了 workspace）
* Gateway 健康、模型可用

至此迁移完成。后续日常使用就和[新手快速部署](/sandbox/hermes-agent/quickstart)里一样，用 `pause` / `resume` 管理沙箱生命周期即可。