Metadata-Version: 2.4
Name: PPClaw
Version: 1.1.0
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: ppio-sandbox>=1.1.1b3
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0

# 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 中，无需额外认证。

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

```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 助手对话，无需安装任何软件。 |
| **Gateway Token** | 访问沙箱的认证密钥，防止他人未经授权使用你的 AI 助手。 |
| **Sandbox ID** | 沙箱的唯一标识，用于管理操作（查看状态、停止等）。格式如 `iz64antbdg1l8ww7fp2zg-4551786a`。 |

典型使用流程：

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

---

## 命令参考

### 启动沙箱

```bash
PPClaw launch
```

启动成功后会输出 Sandbox ID、Web UI 地址、Gateway Token 等信息。**直接复制 Web UI 地址到浏览器打开即可使用。**

可选参数：

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

示例：

```bash
# 使用自定义 Gateway Token（方便记忆和后续使用）
PPClaw launch --gateway-token my-secret-token-123
```

### 查看沙箱列表

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

```bash
PPClaw list
```

### 查看沙箱状态

查看某个沙箱的运行状态和访问地址：

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

### 停止沙箱

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

```bash
PPClaw stop <sandbox-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 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 输出格式：

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

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

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

---

## 安全说明

Gateway Token 用于保护你的 AI 助手不被他人未授权访问：

- **妥善保管 Token** — 可通过 `PPClaw status <id>` 随时查看
- **及时停止不用的沙箱** — 避免不必要的资源消耗和安全风险
- **不要分享 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 服务。如果遇到连接问题：

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

---

## 相关文档

- [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 管理页面
