PPClaw 1.5.0

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

PPClaw

在云端一键部署你自己的 AI 助手。PPClaw 帮你在 PPIO 云端创建一个独立的运行环境（沙箱），自动安装并配置好 OpenClaw — 一个开源 AI 助手框架，支持通过网页聊天、连接 Telegram / Discord / WhatsApp 等消息平台，让 AI 助手为你服务。

你不需要自己搭服务器，不需要懂 Docker，只需要一个 API Key 和一行命令。

快速上手

只需 3 步，从零开始到打开 AI 助手界面：

第一步：安装 PPClaw

pip install PPClaw

如果提示 pip 找不到，请先参考下方「环境准备」章节安装 Python。

第二步：获取并配置 API Key

1. 前往 PPIO Key Management，注册 / 登录账号
2. 在页面上创建一个 API Key，复制 sk_ 开头的密钥
3. 在终端中设置环境变量：

# macOS / Linux
export PPIO_API_KEY=sk_your_api_key

# Windows PowerShell
$env:PPIO_API_KEY = "sk_your_api_key"

第三步：启动并打开 Web UI

PPClaw launch

等待约 1 分钟，启动成功后会输出一段信息，包括：

• Web UI — AI 助手聊天界面（Token 已附在 URL 中，无需额外认证）
• Web Terminal — 浏览器里的终端，可以直接在沙箱内执行命令
• File Manager — 网页文件管理器，支持上传 / 下载 / 删除沙箱内的文件
• Services 密码 — Web Terminal 和 File Manager 的随机登录密码（用户名默认 admin）

直接复制 Web UI 地址到浏览器打开，即可开始和 AI 助手聊天。

用完之后，记得停止沙箱以释放资源：

PPClaw stop <sandbox-id>

其中 <sandbox-id> 是启动时输出的 Sandbox ID。

---

环境准备

PPClaw 需要 Python 3.9 或更高版本。如果你的电脑还没有安装 Python，请按以下步骤操作。

macOS

macOS 通常自带 Python，打开「终端」应用检查：

python3 --version

如果显示版本号（如 Python 3.12.x），则已就绪。如果提示命令找不到，安装方式：

# 方式一：通过 Homebrew（推荐）
brew install python

# 方式二：从官网下载安装包
# 前往 https://www.python.org/downloads/ 下载并安装

Windows

1. 前往 Python 官网 下载最新版安装包
2. 运行安装程序时，务必勾选底部的 "Add Python to PATH"
3. 安装完成后，打开 PowerShell 验证：

python --version
pip --version

Linux (Ubuntu / Debian)

sudo apt update && sudo apt install python3 python3-pip -y

验证安装

安装 Python 后，确认 pip 可用：

pip --version
# 或
pip3 --version

如果 pip 命令不可用但 pip3 可以，后续命令中将 pip 替换为 pip3 即可。

---

配置 API Key

PPClaw 的所有操作都需要 PPIO API Key。该 Key 同时用于：

• 创建和管理云端沙箱实例
• 作为 AI 助手的 LLM 推理 API Key（驱动 AI 对话能力）

获取 API Key

1. 打开 PPIO Key Management
2. 注册或登录你的 PPIO 账号
3. 点击「创建 API Key」
4. 复制生成的 sk_ 开头的密钥，妥善保管

配置方式

提供 4 种方式，选择适合你的一种即可：

方式一：直接传参（临时使用）

PPClaw launch --api-key sk_your_api_key

方式二：设置环境变量（当前终端会话有效）

# macOS / Linux
export PPIO_API_KEY=sk_your_api_key

# Windows PowerShell
$env:PPIO_API_KEY = "sk_your_api_key"

方式三：写入 Shell 配置文件（永久生效，推荐）

# macOS (zsh)
echo 'export PPIO_API_KEY=sk_your_api_key' >> ~/.zshrc
source ~/.zshrc

# Linux (bash)
echo 'export PPIO_API_KEY=sk_your_api_key' >> ~/.bashrc
source ~/.bashrc

Windows 用户可以通过「系统属性 → 高级 → 环境变量」添加 PPIO_API_KEY。

方式四：在命令前附带（仅当次命令有效）

PPIO_API_KEY=sk_your_api_key PPClaw launch

---

核心概念

在使用 PPClaw 之前，了解几个核心概念会让你更容易理解后续操作：

概念	说明
沙箱 (Sandbox)	一个运行在云端的独立环境，类似一台专属虚拟机。你的 AI 助手就运行在里面。
Gateway	沙箱内运行的网关服务，负责接收和转发消息。Web UI 和消息频道都通过它与 AI 助手通信。
Web UI	网页聊天界面，在浏览器中打开就能和 AI 助手对话，无需安装任何软件。
Web Terminal	基于 ttyd 的浏览器终端，可直接在沙箱内执行命令（端口 7681）。
File Manager	基于 gohttpserver 的网页文件管理器，支持上传 / 下载 / 删除文件（端口 7682）。
Gateway Token	访问沙箱的认证密钥，防止他人未经授权使用你的 AI 助手。
Sandbox ID	沙箱的唯一标识，用于管理操作（查看状态、停止等）。格式如 iz64antbdg1l8ww7fp2zg-4551786a。

典型使用流程：

安装 PPClaw → 配置 API Key → 启动沙箱 → 打开 Web UI 使用 → 不用时停止沙箱

---

命令参考

启动沙箱

PPClaw launch

启动成功后会输出 Sandbox ID、Web UI 地址、Web Terminal / File Manager 地址和登录凭据。直接复制 Web UI 地址到浏览器打开即可使用。

可选参数：

参数	说明	默认值
--api-key	PPIO API Key	读取 PPIO_API_KEY 环境变量
--timeout	沙箱创建超时时间（秒）	60

查看沙箱列表

列出所有正在运行的沙箱：

PPClaw list

查看沙箱状态

查看某个沙箱的运行状态和所有访问地址（Web UI、Web Terminal、File Manager）：

PPClaw status <sandbox-id>

停止沙箱

终止并释放一个沙箱。不再使用时请及时停止，避免不必要的资源消耗：

PPClaw stop <sandbox-id>

管理 Gateway

更新 OpenClaw 到最新版本：

PPClaw gateway update <sandbox-id>

# 更新后自动重启 Gateway 使新版本生效
PPClaw gateway update <sandbox-id> --restart

重启 Gateway：

PPClaw gateway restart <sandbox-id>

诊断与修复

在沙箱内运行诊断，检查配置完整性、权限、Gateway 健康状态等：

PPClaw doctor <sandbox-id>

自动修复发现的问题：

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

频道配对（进阶）

PPClaw 支持将 AI 助手连接到 Telegram、Discord、WhatsApp 等消息平台。当消息频道使用设备配对模式时，新用户私信机器人会收到一次性配对码，使用以下命令审批：

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

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

支持的频道：telegram、discord、whatsapp、signal、slack、feishu。配对码在 1 小时后过期。

连接消息频道需要额外的配置（如 Bot Token），详见 OpenClaw 频道配置文档。

TUI 连接（可选）

如果你习惯在终端中操作，可以通过 TUI（终端用户界面）连接沙箱：

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

前提条件： 需要本地安装 Node.js 和 OpenClaw CLI。

1. 安装 Node.js：前往 nodejs.org 下载 LTS 版本
2. 安装 OpenClaw CLI：npm install -g openclaw

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

---

AI Agent 集成

如果你是 AI Agent 或需要在脚本中调用 PPClaw，所有命令支持 --json / -j 全局选项，输出结构化 JSON：

PPClaw --json launch
PPClaw --json list
PPClaw --json status <id>
PPClaw --json stop <id>
PPClaw --json gateway update <id>
PPClaw --json gateway restart <id>
PPClaw --json pair list <id> --channel telegram
PPClaw --json pair approve <id> --channel telegram --code X
PPClaw --json doctor <id>

JSON 输出格式：

// 成功（exit code 0）
{"status": "ok", "sandbox_id": "...", ...}

// 失败（exit code > 0）
{"status": "error", "error_code": "SANDBOX_CREATE_FAILED", "message": "..."}

如果你是 AI Agent，请始终使用 --json 参数，以获得稳定的机器可解析输出。

---

安全说明

• 妥善保管 Token 和密码 — 可通过 PPClaw status <id> 随时查看 Gateway Token 和 Services 密码
• Web Terminal / File Manager — 每次 launch 自动生成随机密码（HTTP Basic Auth），用户名默认 admin
• 及时停止不用的沙箱 — 避免不必要的资源消耗和安全风险
• 不要分享 Web UI 链接 — 链接中包含 Token，获得链接即可直接访问你的 AI 助手

---

常见问题

pip 或 pip3 命令找不到

Python 未安装或未添加到系统 PATH。请参考上方「环境准备」章节安装 Python。Windows 用户安装时务必勾选 "Add Python to PATH"。

安装后 PPClaw 命令找不到

pip 安装的可执行文件可能不在系统 PATH 中。尝试以下方法：

# 方法一：使用 python -m 方式运行
python -m ppclaw_cli.cli --help

# 方法二：使用 pipx 安装（自动处理 PATH 问题）
pip install pipx
pipx install PPClaw
PPClaw --help

# 方法三：手动将 pip 安装目录加入 PATH
# macOS / Linux: 通常在 ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

API Key 无效或认证失败

• 确认 Key 以 sk_ 开头
• 确认 Key 已正确复制，没有多余空格
• 前往 PPIO Key Management 检查 Key 状态是否正常

启动超时（Gateway 启动失败）

沙箱创建成功但 Gateway 未能在预期时间内启动。可能原因：

• 网络波动导致连接中断 — 稍后重试
• 可以尝试增加超时时间：PPClaw launch --timeout 120
• 使用 PPClaw doctor <sandbox-id> 诊断问题

网络连接问题

PPClaw 需要访问互联网连接 PPIO 服务。如果遇到连接问题：

• 检查网络是否正常
• 如果在公司网络或使用代理，确认代理设置正确
• 重试命令，偶发的网络中断通常重试即可解决

---

开发

环境搭建

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

测试

ruff check .            # Lint
ruff format --check .   # 格式检查
pytest -v -m "not e2e"  # 单元测试（不需要 API Key）

需要真实沙箱的端到端测试：

PPIO_API_KEY=sk_xxx pytest -v -m e2e --timeout=300

CI

每次 PR 和 push 到 main 时，GitHub Actions 自动执行：

1. lint-and-test — ruff lint / format + 单元测试（Python 3.9 / 3.11 / 3.13）
2. e2e — 完整沙箱生命周期测试（launch → list → status → stop），通过 GitHub Secrets 传入 API Key 和 Template ID

构建模板

使用 keli team 的账号构建

沙箱模板分为测试和生产两个环境，配置分别在 template/ppio.test.toml 和 template/ppio.prod.toml：

cd template
./build-test.sh   # 构建测试模板
./build-prod.sh   # 构建生产模板

构建完成后将新的 template_id 更新回对应的 toml 文件。CLI 运行时的 Template ID 可通过环境变量 PPCLAW_TEMPLATE_ID 覆盖。

---

相关文档

• OpenClaw 文档 — AI 助手框架的完整文档
• OpenClaw 频道配置 — 连接 Telegram、Discord 等平台
• PPIO Agent Sandbox — 云端沙箱服务说明
• PPIO API Key 获取 — API Key 管理页面