Metadata-Version: 2.4
Name: PPClaw
Version: 1.0.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

一键启动安装有 [OpenClaw](https://docs.openclaw.ai/) 的云端沙箱环境，基于 [PPIO Agent Sandbox](https://ppio.com/docs/sandbox/overview)。

## 安装

```bash
pip install PPClaw
```

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

## 配置

### 1. 获取 PPIO API Key

前往 [PPIO Key Management](https://ppio.com/docs/support/api-key) 获取你的 API Key。该 Key 同时用于：
- 创建和管理 PPIO 沙箱实例
- 作为 PPClaw 的 LLM 推理 API Key

### 2. 配置 API Key

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

```bash
# 方式一：直接传参
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` 参数** 以获得稳定的机器可解析输出：

```bash
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>                                 # 运行诊断
```

### 启动沙箱

```bash
PPClaw launch
```

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

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

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

完整参数：

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--api-key` | [PPIO API Key](https://ppio.com/docs/support/api-key) | 读取 `PPIO_API_KEY` 环境变量 |
| `--gateway-token` | Gateway 认证令牌（建议设置安全的自定义 Token） | 自动生成随机 Token |
| `--timeout` | 沙箱创建超时（秒） | 60 |

### 查看沙箱列表

```bash
PPClaw list
```

### 查看沙箱状态

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

### 通过 TUI 连接

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

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

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

### 管理频道配对

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

```bash
# 查看某频道的待处理配对请求
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](https://docs.openclaw.ai/gateway/doctor)，检查配置完整性、权限、Gateway 健康状态、插件/技能状态等：

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

自动修复发现的问题：

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

### 停止沙箱

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

## 安全说明

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

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

## 相关文档

- [OpenClaw 安装使用文档](https://docs.openclaw.ai/install)
- [PPIO Agent Sandbox 文档](https://ppio.com/docs/sandbox/overview)
- [PPIO API Key 获取](https://ppio.com/docs/support/api-key)
