跳转到主要内容

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.

本文档中的 --from-local 模式需要 PPHermes v1.1.0 及以上版本（--from 沙箱到沙箱模式 v1.0.0 就支持）。升级 CLI：macOS / Linux：
curl -fsSL https://pphermes.ppio.com/install.sh | bash
Windows (PowerShell)：
irm https://pphermes.ppio.com/install.ps1 | iex
或通过 pip：
pip install -U pphermes
验证版本：
pphermes --version
# 期望输出：pphermes, version 1.1.0（或更高）
还没部署过 Hermes？先完成新手快速部署里的 Python 环境、API Key 和 pphermes launch 步骤，拿到目标 Sandbox ID，再回来看这篇。

​
这篇教程解决什么

你之前用过 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 在云端部署过 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）。新建沙箱请参考新手快速部署。
  4. 确认下数据源 —— 根据你要走的模式，记下源 OpenClaw 沙箱 ID（沙箱到沙箱），或本地 .openclaw 路径（本地到沙箱）。
一键验证： 
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

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

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

--dry-run 会完整走”打包 → 上传 → 沙箱内解压”全流程，但最后一步不会真正改动目标沙箱，只让 Hermes 报告”如果真的迁移，会怎么变化”。适合第一次跑之前提前暴露网络问题或大小超限： 
pphermes migrate <HERMES_SANDBOX_ID> \
  --from <OPENCLAW_SANDBOX_ID> \
  --dry-run \
  -y
看到 dry_run: true + Migration complete 就说明链路通了，目标沙箱没有任何改动。

​
A3. 真的跑一次

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： 
pphermes migrate <HERMES_SANDBOX_ID> \
  --from <OPENCLAW_SANDBOX_ID> \
  --include-workspace \
  --overwrite -y
也可以显式指定要迁的目录（路径必须在源沙箱的 /home/user/ 下）： 
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 传绝对路径： 
ls ~/.openclaw/SOUL.md                      # 文件存在说明目录有效

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

pphermes migrate <HERMES_SANDBOX_ID> \
  --from-local \
  --openclaw-path ~/.openclaw \
  --dry-run \
  -y
看到 dry_run: true + Migration complete 就说明打包、上传、解压链路都通了。

​
B3. 真的跑一次

pphermes migrate <HERMES_SANDBOX_ID> \
  --from-local \
  --openclaw-path ~/.openclaw \
  --overwrite \
  -y
参数 --overwrite / --preset / --exclude-tts 的作用和路径 A 完全相同。

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

本地的项目目录（比如 ~/projects/my-analysis/）可以一起同步： 
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 沙箱已经配好、你只想把本地项目目录拷进去： 
pphermes migrate <HERMES_SANDBOX_ID> \
  --from-local \
  --no-openclaw \
  --workspace-path ~/projects/my-analysis \
  -y

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

软链接和硬链接会被丢弃。为了避免你的本地软链接（比如 ~/.ssh、指向某个绝对路径的快捷方式）在沙箱里被意外解引用到别的文件，--from-local 不会保留任何符号链接或硬链接。如果某个目录是通过软链接组织的（比如 .openclaw/memories → /some/other/path），请先把链接物化成真实目录再跑命令：
cp -rL ~/.openclaw /tmp/openclaw-materialized
pphermes migrate <HERMES_SANDBOX_ID> \
  --from-local \
  --openclaw-path /tmp/openclaw-materialized -y

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

不管走哪条路径，非 dry-run 模式成功完成后都会自动打出两块面板：迁移摘要 + 健康检查。典型输出类似： 
╭──────── 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)      │
╰───────────────────────────────────────╯
关于 Conflicts 这一行的文案 —— 如果有冲突项且没带 --overwrite，面板会提示 Conflicts: N (use --overwrite to replace)；已经带了 --overwrite 但仍然有冲突，说明那些项是 Hermes 主动保护、不会被覆盖的，文案会显示 Conflicts: N (protected by Hermes)（PPHermes ≥ 1.1.1）。
健康检查做了两件事：
  • 配置体检（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 GiBworkspace 打包体积超上限加 --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 健康、模型可用
至此迁移完成。后续日常使用就和新手快速部署里一样，用 pause / resume 管理沙箱生命周期即可。