PPClaw 1.0.0

One-click launch of OpenClaw sandbox environment powered by PPIO Agent Sandbox

PPClaw

一键启动安装有 OpenClaw 的云端沙箱环境，基于 PPIO Agent Sandbox。

安装

pip install PPClaw

安装后即可通过 PPClaw 命令使用。

配置

1. 获取 PPIO API Key

前往 PPIO Key Management 获取你的 API Key。该 Key 同时用于：

• 创建和管理 PPIO 沙箱实例
• 作为 PPClaw 的 LLM 推理 API Key

2. 配置 API Key

可以通过以下任一方式配置：

# 方式一：直接传参
PPClaw launch --api-key sk_your_api_key

# 方式二：设置当前命令的环境变量
PPIO_API_KEY=sk_your_api_key PPClaw launch

# 方式三：导出到当前终端会话
export PPIO_API_KEY=sk_your_api_key

# 方式四：写入 shell 配置文件（永久生效）
echo 'export PPIO_API_KEY=sk_your_api_key' >> ~/.zshrc

使用

所有命令支持 --json / -j 全局选项，输出结构化 JSON（适合 AI Agent 或脚本调用）。如果你是 AI Agent，请始终使用 --json 参数 以获得稳定的机器可解析输出：

PPClaw --json launch                                      # 启动沙箱
PPClaw --json list                                        # 列出沙箱
PPClaw --json status <id>                                 # 沙箱状态与 URL
PPClaw --json stop <id>                                   # 停止沙箱
PPClaw --json pair list <id> --channel telegram           # 待处理配对请求
PPClaw --json pair approve <id> --channel telegram --code X  # 审批配对
PPClaw --json doctor <id>                                 # 运行诊断

启动沙箱

PPClaw launch

建议通过 --gateway-token 指定一个安全的自定义 Token，用于 OpenClaw 访问鉴权。如果不设置，会自动生成一个随机 Token：

PPClaw launch --gateway-token <your-token>

启动成功后会输出：

• Sandbox ID — 用于后续管理
• Web UI 地址 — 在浏览器中打开即可使用 PPClaw（Token 已附在 URL 中，自动认证）
• Gateway WebSocket 地址 — 用于 TUI 或 API 连接
• Gateway Token — 连接时需要的认证令牌

完整参数：

参数	说明	默认值
--api-key	PPIO API Key	读取 PPIO_API_KEY 环境变量
--gateway-token	Gateway 认证令牌（建议设置安全的自定义 Token）	自动生成随机 Token
--timeout	沙箱创建超时（秒）	60

查看沙箱列表

PPClaw list

查看沙箱状态

PPClaw status <sandbox-id>

通过 TUI 连接

PPClaw tui <sandbox-id> --token <gateway-token>

需要本地安装 OpenClaw CLI：npm install -g openclaw

首次连接时会触发 Device Pairing，沙箱内的自动审批服务会在约 3 秒内完成配对，请稍等片刻。

管理频道配对

当消息频道（Telegram、Discord 等）使用 dmPolicy: "pairing"（默认值）时，新用户私信机器人会收到一次性配对码。使用以下命令查看和审批配对请求：

# 查看某频道的待处理配对请求
PPClaw pair list <sandbox-id> --channel telegram

# 使用配对码审批请求
PPClaw pair approve <sandbox-id> --channel telegram --code <CODE>

支持的频道：telegram、discord、whatsapp、signal、slack、feishu。

配对码在 1 小时后过期。要查看待处理请求，先运行 pair list。

诊断与修复

在沙箱内运行 OpenClaw doctor，检查配置完整性、权限、Gateway 健康状态、插件/技能状态等：

PPClaw doctor <sandbox-id>

自动修复发现的问题：

PPClaw doctor <sandbox-id> --fix           # 应用推荐修复
PPClaw doctor <sandbox-id> --fix --force   # 包含激进修复（会覆盖自定义配置）
PPClaw doctor <sandbox-id> --deep          # 深度扫描系统服务

停止沙箱

PPClaw stop <sandbox-id>

安全说明

Gateway Token 用于保护你的 PPClaw 实例不被未授权访问。当沙箱绑定到公网地址时：

• 妥善保管 Token — 可通过 PPClaw status <id> 随时查看
• 及时停止不用的沙箱 — 避免不必要的资源消耗和安全风险

相关文档

• OpenClaw 安装使用文档
• PPIO Agent Sandbox 文档
• PPIO API Key 获取