ppclaw-cli 0.6.0

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

PPClaw

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

安装

pip install ppclaw-cli

配置

1. 获取 PPIO API Key

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

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

2. 配置 API Key

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

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

# 方式二：设置当前命令的环境变量
PPIO_API_KEY=sk_your_api_key ppclaw-cli 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-cli --json launch                                      # 启动沙箱
ppclaw-cli --json list                                        # 列出沙箱
ppclaw-cli --json status <id>                                 # 沙箱状态与 URL
ppclaw-cli --json stop <id>                                   # 停止沙箱
ppclaw-cli --json pair list <id> --channel telegram           # 待处理配对请求
ppclaw-cli --json pair approve <id> --channel telegram --code X  # 审批配对
ppclaw-cli --json doctor <id>                                 # 运行诊断

启动沙箱

ppclaw-cli launch

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

ppclaw-cli 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-cli list

查看沙箱状态

ppclaw-cli status <sandbox-id>

通过 TUI 连接

ppclaw-cli tui <sandbox-id> --token <gateway-token>

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

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

管理频道配对

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

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

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

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

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

诊断与修复

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

ppclaw-cli doctor <sandbox-id>

自动修复发现的问题：

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

停止沙箱

ppclaw-cli stop <sandbox-id>

安全说明

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

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

相关文档

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