pocketclaw-server

OpenClaw plugin — remote tunnel and QR pairing for PocketClaw iOS App.

What it does

When OpenClaw Gateway starts, this plugin automatically:

1. ✅ Checks that cloudflared is installed (with platform-specific install help)
2. 🌐 Creates a Cloudflare Tunnel (public HTTPS endpoint)
3. 📱 Prints a QR code in the terminal
4. 📲 PocketClaw iOS App scans the QR → remote control ready!

Install

1. Install cloudflared (one-time)

| Platform | Command | |----------|---------| | macOS | brew install cloudflared | | Windows | winget install Cloudflare.cloudflared | | Ubuntu/Debian | sudo apt install cloudflared | | Other Linux / VPS | Download from GitHub |

2. Install the plugin

openclaw plugins install pocketclaw-server

3. (Recommended) Enable full functionality

Quick queries work out of the box. For Commands and AI Tasks, enable the chatCompletions endpoint:

openclaw config set gateway.http.endpoints.chatCompletions.enabled true

4. Start / restart Gateway

openclaw gateway restart

The terminal will display a QR code. Open PocketClaw on your iPhone and scan it.

Supported Platforms

| Platform | OpenClaw | cloudflared | This Plugin | |----------|----------|-------------|-------------| | macOS | ✅ | ✅ brew | ✅ | | Windows | ✅ | ✅ winget | ✅ | | Linux (Ubuntu, Debian, etc.) | ✅ | ✅ apt / binary | ✅ | | VPS / Cloud Server | ✅ | ✅ binary | ✅ |

QR Code Format

{"h":"xxxx.trycloudflare.com","p":443,"t":"gateway-token","s":1,"n":"hostname"}

| Field | Description | |-------|-------------| | h | Tunnel hostname | | p | Port (443 = HTTPS) | | t | Gateway auth token | | s | HTTPS flag (1=yes) | | n | Host machine name |

FAQ

Q: Do I need to re-scan after Gateway restart?

| Scenario | Re-scan needed? | Why | |----------|----------------|-----| | Gateway restart, tunnel process alive | ❌ No | URL and token unchanged | | Gateway restart, cloudflared also restarts | ❌ Usually no | App auto-discovers new URL via LAN | | Phone and computer on different networks + tunnel URL changed | ⚠️ Yes | Cannot discover new URL via LAN | | Using a fixed Cloudflare Tunnel domain | ❌ Never | URL is permanent |

Q: Can I use this from a different network?

Yes! The Cloudflare tunnel works from any network — WiFi, 5G, anywhere.

Remote Control Features

Once installed, the plugin registers the following tools for remote control:

| Tool | Description | |------|-------------| | pocketclaw_session_control | Adjust session settings (thinking level, model, verbose, etc.) | | pocketclaw_elevated | Toggle elevated mode (on/off/ask/full) | | pocketclaw_session_reset | Reset or create new sessions | | pocketclaw_models | List available AI models | | pocketclaw_usage | Check token usage and costs | | pocketclaw_cron_list | List scheduled cron jobs |

Build & Development

# 发布构建（编译 + 混淆）— 用于 npm publish
npm run build

# 开发构建（仅编译，保留可读性）— 用于本地调试
npm run build:dev

# 运行测试
npm test

注意：本地部署到 ~/.openclaw/extensions/pocketclaw-server/ 时建议用 build:dev，混淆版日志可读性较差。发布到 npm 时务必用 build。

Security

代码保护

发布到 npm 的包经过多层保护，防止逆向分析：

| 保护层 | 说明 | |--------|------| | 源码隔离 | TypeScript 源码（src/）、测试（test/）、构建脚本（scripts/）均不发布 | | 标识符混淆 | 变量名、函数名 → 十六进制（_0x1a2b） | | 字符串加密 | 字符串提取到数组 + Base64 编码 | | 键名混淆 | 对象属性键名转换 | | 代码压缩 | 压缩为单行，去除所有注释和空格 |

Session 安全模型

• QR 码仅携带短期一次性 pairingToken（10 分钟有效）
• 扫码后兑换为独立 sessionToken（与 Gateway Token 完全隔离）
• 每个设备独立 Session，支持单设备吊销
• Session 持久化到磁盘，Gateway 重启后自动恢复

License

MIT