Metadata-Version: 2.4
Name: PPClaw
Version: 1.7.2
Summary: One-click launch of OpenClaw sandbox environment powered by PPIO Agent Sandbox
Author-email: PPIO <hello@ppio.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.25
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == "server"
Requires-Dist: uvicorn[standard]>=0.34; extra == "server"
Requires-Dist: ppio-sandbox>=1.1.1b3; extra == "server"
Requires-Dist: pyyaml>=6.0; extra == "server"
Requires-Dist: python-json-logger>=3.0; extra == "server"
Requires-Dist: mcp>=1.3; python_version >= "3.10" and extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: httpx>=0.25; extra == "dev"

# PPClaw

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

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

## 快速上手

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

**第一步：安装 ppclaw**

```bash
pip install ppclaw
```

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

**第二步：获取并配置 API Key**

1. 前往 [PPIO Key Management](https://ppio.com/docs/support/api-key)，注册 / 登录账号
2. 在页面上创建一个 API Key，复制 `sk_` 开头的密钥
3. 在终端中设置环境变量：

```bash
# macOS / Linux
export PPIO_API_KEY=sk_your_api_key

# Windows PowerShell
$env:PPIO_API_KEY = "sk_your_api_key"
```

**第三步：启动并打开 Web UI**

```bash
ppclaw launch
```

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

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

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

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

```bash
ppclaw stop <sandbox-id>
```

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

---

## 环境准备

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

### macOS

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

```bash
python3 --version
```

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

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

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

### Windows

1. 前往 [Python 官网](https://www.python.org/downloads/) 下载最新版安装包
2. 运行安装程序时，**务必勾选底部的 "Add Python to PATH"**
3. 安装完成后，打开 PowerShell 验证：

```powershell
python --version
pip --version
```

### Linux (Ubuntu / Debian)

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

### 验证安装

安装 Python 后，确认 pip 可用：

```bash
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](https://ppio.com/docs/support/api-key)
2. 注册或登录你的 PPIO 账号
3. 点击「创建 API Key」
4. 复制生成的 `sk_` 开头的密钥，妥善保管

### 配置方式

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

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

```bash
ppclaw launch --api-key sk_your_api_key
```

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

```bash
# macOS / Linux
export PPIO_API_KEY=sk_your_api_key

# Windows PowerShell
$env:PPIO_API_KEY = "sk_your_api_key"
```

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

```bash
# 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`。

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

```bash
PPIO_API_KEY=sk_your_api_key ppclaw launch
```

---

## 核心概念

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

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

典型使用流程：

```
# Gateway 模式（默认）
安装 ppclaw → 配置 API Key → 启动沙箱 → 打开 Web UI 使用 → 不用时停止沙箱

# Node 模式（扩展已有 Gateway）
启动 Node 沙箱 → 连接到 Gateway → 审批设备 → Node 开始接收任务
```

---

## 命令参考

### 启动沙箱

```bash
ppclaw launch
```

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

可选参数：

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

### 查看沙箱列表

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

```bash
ppclaw list
```

### 查看沙箱状态

查看某个沙箱的运行状态和所有访问地址（Web UI、Web Terminal、File Manager）。对暂停的沙箱也安全，不会唤醒：

```bash
ppclaw status <sandbox-id>
```

### 暂停与恢复沙箱

暂停一个沙箱以节省费用，所有状态（文件系统、内存、进程）均会保留，暂停期间不产生运行时费用：

```bash
ppclaw pause <sandbox-id>
```

恢复暂停的沙箱（约 1 秒恢复到暂停前的完整状态）：

```bash
ppclaw resume <sandbox-id>
```

> **提示：** 暂停时间与沙箱内存成正比，约 4 秒/GB。暂停后网络服务不可访问，恢复后客户端需重新连接。

### 停止沙箱

终止并释放一个沙箱。**此操作不可逆，所有数据将永久丢失。** 如果只是暂时不用，建议使用 `pause` 代替：

```bash
ppclaw stop <sandbox-id>
```

### Node 模式（将沙箱作为计算节点接入已有 Gateway）

默认的 `gateway` 模式会在沙箱内启动完整的 OpenClaw Gateway。如果你**已经有一个运行中的 Gateway**（例如另一个沙箱或自建服务器），可以使用 `node` 模式——只创建一个轻量计算节点，然后将它连接到已有的 Gateway 上，扩展 AI 助手的可用算力。

#### 完整流程示例

以下示例演示：启动一个 Gateway 沙箱，再启动一个 Node 沙箱并接入该 Gateway，最后验证 Node 已正常工作。

**第一步：启动 Gateway 沙箱（如果已有 Gateway 可跳过）**

```bash
ppclaw launch
```

记录输出中的：
- `Sandbox ID`（Gateway 沙箱 ID，后续用于设备审批）
- `Gateway WebSocket`（`wss://...` 地址）
- `Gateway Token`（认证令牌）

**第二步：以 Node 模式启动新沙箱**

```bash
ppclaw launch --mode node --display-name "my-node-1"
```

`--display-name` 可选，用于设置节点在 Gateway 中显示的名称（默认使用沙箱 ID 前缀）。

Node 沙箱启动后会输出 Sandbox ID 和服务信息（Web Terminal / File Manager），但不会有 Gateway 相关信息——因为 Node 还未连接到任何 Gateway。

**第三步：将 Node 连接到 Gateway**

```bash
ppclaw node connect <node-sandbox-id> \
  --gateway wss://your-gateway-url \
  --gateway-token <token>
```

| 参数 | 说明 | 是否必填 |
| --- | --- | --- |
| `<node-sandbox-id>` | 第二步中获得的 Node 沙箱 ID | 是 |
| `--gateway` | Gateway 的 WebSocket 地址（`wss://...`） | 是 |
| `--gateway-token` | Gateway 认证令牌 | 否（如果 Gateway 不要求认证可省略） |

连接成功后，Node 会作为 **待审批设备 (pending device)** 出现在 Gateway 中。

**第四步：在 Gateway 上审批 Node 设备**

```bash
# 查看 Gateway 上的所有设备（包括待审批的）
ppclaw devices list <gateway-sandbox-id>

# 审批所有待审批设备
ppclaw devices approve <gateway-sandbox-id>

# 或指定审批某一个设备
ppclaw devices approve <gateway-sandbox-id> --request-id <request-id>
```

审批通过后，Node 会自动完成配对，可以开始接收 Gateway 分发的任务。

**第五步：验证 Node 是否正常工作**

打开 Gateway 的 Web UI，向 AI 助手发送一条需要执行命令的指令，例如：

```
请运行 uname -a 并告诉我系统信息
```

如果 AI 助手返回了系统信息，说明 Node 已成功接入 Gateway 并正常工作。

你也可以通过 CLI 的 JSON 模式验证：

```bash
# 确认 Node 在 Gateway 设备列表中且状态正常
ppclaw --json devices list <gateway-sandbox-id>
```

#### 断开与重新连接

**断开 Node（不销毁沙箱）：**

```bash
ppclaw node disconnect <node-sandbox-id>
```

沙箱保持运行，可以随时重新连接到相同或不同的 Gateway。

**重新连接到另一个 Gateway：**

```bash
ppclaw node connect <node-sandbox-id> --gateway wss://another-gateway-url
```

无需先断开——直接调用 `node connect` 指定新的 Gateway 即可自动切换。

**停止 Node 沙箱：**

```bash
ppclaw stop <node-sandbox-id>
```

#### AI Agent 集成（JSON 模式）

```bash
ppclaw --json launch --mode node
ppclaw --json node connect <id> --gateway wss://... --gateway-token <token>
ppclaw --json node disconnect <id>
ppclaw --json devices list <gateway-id>
ppclaw --json devices approve <gateway-id>
```

---

### 管理 Gateway

**更新 OpenClaw 到最新版本：**

```bash
ppclaw gateway update <sandbox-id>

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

**重启 Gateway：**

```bash
ppclaw gateway restart <sandbox-id>
```

### 诊断与修复

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

```bash
ppclaw doctor <sandbox-id>
```

自动修复发现的问题：

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

### 频道配对（进阶）

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

```bash
# 查看某频道的待处理配对请求
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 频道配置文档](https://docs.openclaw.ai/channels)。

### TUI 连接（可选）

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

```bash
ppclaw tui <sandbox-id> --token <gateway-token>
```

> **前提条件：** 需要本地安装 Node.js 和 OpenClaw CLI。
>
> 1. 安装 Node.js：前往 [nodejs.org](https://nodejs.org/) 下载 LTS 版本
> 2. 安装 OpenClaw CLI：`npm install -g openclaw`
>
> 首次连接时会触发 Device Pairing，沙箱内的自动审批服务会在约 3 秒内完成配对，请稍等片刻。

---

## AI Agent 集成

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

```bash
ppclaw --json launch
ppclaw --json list
ppclaw --json status <id>
ppclaw --json pause <id>
ppclaw --json resume <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>
ppclaw --json launch --mode node
ppclaw --json node connect <id> --gateway wss://... --gateway-token <token>
ppclaw --json node disconnect <id>
ppclaw --json devices list <gateway-id>
ppclaw --json devices approve <gateway-id>
```

JSON 输出格式：

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

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

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

### MCP (Model Context Protocol)

PPClaw 提供 [MCP](https://modelcontextprotocol.io/) Streamable HTTP 端点，AI 应用（如 Claude Desktop、Cursor、Windsurf 等）可以通过 MCP 协议直接管理沙箱。

**服务地址：** `https://ppclaw.ppio.com/mcp`

**Claude Code**

命令行安装：

```bash
claude mcp add --transport http ppclaw https://ppclaw.ppio.com/mcp \
  -H "Authorization: Bearer <YOUR_PPIO_API_KEY>"
```

或手动编辑 `.claude/settings.local.json`：

```json
{
  "mcpServers": {
    "ppclaw": {
      "type": "http",
      "url": "https://ppclaw.ppio.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_PPIO_API_KEY>"
      }
    }
  }
}
```

将 `<YOUR_PPIO_API_KEY>` 替换为你的 PPIO API Key。

**可用工具：**

| 工具 | 说明 |
| --- | --- |
| `launch` | 启动新沙箱 |
| `pause` | 暂停沙箱（保留所有状态，暂停期间不计费） |
| `resume` | 恢复暂停的沙箱 |
| `stop` | 停止并销毁沙箱 |
| `list_sandboxes` | 列出所有活跃沙箱 |
| `status` | 查看沙箱详细状态和访问地址（不会唤醒暂停的沙箱） |
| `doctor` | 运行诊断，检测并修复问题 |
| `gateway_update` | 更新 OpenClaw 到最新版本 |
| `gateway_restart` | 重启 Gateway |
| `services_setup` | 安装 Web Terminal 和 File Manager |
| `pair_list` | 查看待处理的频道配对请求 |
| `pair_approve` | 审批频道配对请求 |
| `node_connect` | 将 Node 沙箱连接到 Gateway |
| `node_status` | 查看 Node 进程和配对状态 |
| `node_reconnect` | 重新启动已停止的 Node 进程 |
| `node_disconnect` | 断开 Node 与 Gateway 的连接 |
| `devices_list` | 列出 Gateway 上的所有设备（含待审批） |
| `devices_approve` | 审批待配对的 Node 设备 |

---

## 安全说明

- **妥善保管 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 中。尝试以下方法：

```bash
# 方法一：使用 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](https://ppio.com/docs/support/api-key) 检查 Key 状态是否正常

### 启动超时（Gateway 启动失败）

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

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

### 网络连接问题

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

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

---

## 开发

### 环境搭建

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

### 测试

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

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

```bash
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

### 构建模板

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

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

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

---

## 相关文档

- [OpenClaw 文档](https://docs.openclaw.ai/) — AI 助手框架的完整文档
- [OpenClaw 频道配置](https://docs.openclaw.ai/channels) — 连接 Telegram、Discord 等平台
- [PPIO Agent Sandbox](https://ppio.com/docs/sandbox/overview) — 云端沙箱服务说明
- [PPIO API Key 获取](https://ppio.com/docs/support/api-key) — API Key 管理页面
