---
name: privateclaw-plugin-setup
description: Install, enable, verify, pair, and manage PrivateClaw OpenClaw sessions, preferring same-conversation /privateclaw QR replies and falling back to the local CLI when needed.
version: 1.1.3
metadata:
  openclaw:
    requires:
      bins:
        - openclaw
    skillKey: privateclaw
    emoji: "🔐"
    homepage: https://github.com/topcheer/PrivateClaw/tree/main/packages/privateclaw-provider
---

# PrivateClaw plugin setup

Use this skill when the user wants to install, enable, verify, configure, or pair the **PrivateClaw** OpenClaw plugin.

This skill is especially relevant for requests like:

- install PrivateClaw
- enable the PrivateClaw plugin
- set up private encrypted chat for OpenClaw
- start QR pairing
- return the pairing QR to the current Telegram, Discord, or QQ chat
- configure a custom PrivateClaw relay
- use `/privateclaw`, `/privateclaw group`, `/session-qr`, or `openclaw privateclaw pair`
- inspect active local sessions with `openclaw privateclaw sessions`
- remove one participant with `openclaw privateclaw kick <sessionId> <appId>`
- use the standalone `privateclaw-provider` CLI instead of the OpenClaw alias
- pause or resume group-bot replies with `/mute-bot` or `/unmute-bot`
- renew or re-share an existing PrivateClaw session
- 安装 PrivateClaw 插件
- 启用 PrivateClaw
- 配置 PrivateClaw relay
- 启动二维码配对
- 把配对二维码发回当前 Telegram / Discord / QQ 对话
- 查看当前本地会话或踢出群组成员

## Core facts

- The production plugin package is `@privateclaw/privateclaw`.
- Keep `--dangerously-force-unsafe-install` on every manual install path. `openclaw plugins install --dangerously-force-unsafe-install @privateclaw/privateclaw@latest` is the default published install, and if the user already has a local package directory, prefer `openclaw plugins install --dangerously-force-unsafe-install ./packages/privateclaw-provider` over archive installs.
- The plugin id is `privateclaw`.
- The standalone npm binary is `privateclaw-provider`.
- The default public relay is `https://relay.privateclaw.us`.
- The iOS App Store release (YourClaw) is available at `https://apps.apple.com/us/app/yourclaw/id6760531637`.
- The Android closed alpha lives at `https://play.google.com/store/apps/details?id=gg.ai.privateclaw`, but Google Play only grants access after the tester joins `https://groups.google.com/g/gg-studio-ai-products`.
- Desktop app releases live at `https://github.com/topcheer/PrivateClaw/releases`; tell users to choose the `app-v*` GitHub Releases when they need Windows / macOS / Linux builds.
- If the user is happy with the default public relay, do **not** set `relayBaseUrl`.
- PrivateClaw is an **OpenClaw plugin**, not an OpenClaw channel. Do **not** run `openclaw channels add privateclaw`.
- The public local CLI surface is `pair`, `sessions`, and `kick`, available as either `openclaw privateclaw <subcommand>` or `privateclaw-provider <subcommand>`.
- `pair` now defaults to returning after printing the QR while the session stays alive in a background daemon until expiry.
- `pair --foreground` keeps the session in the current terminal; on supported runtimes, `Ctrl+D` hands the live session off to the detached background daemon without invalidating the QR.
- `pair --print-only` prints the invite and QR, then immediately closes the session instead of keeping it alive.
- Active sessions expose `/session-qr` and `/renew-session`; active group sessions also expose `/mute-bot` and `/unmute-bot`.
- After `openclaw plugins install`, `openclaw plugins enable`, or any `openclaw config set plugins.entries.privateclaw.config...` change, the running OpenClaw gateway or service must be restarted before testing.

## Preferred behavior

Default to the production npm install path unless the user explicitly asks for:

- a local checkout / linked development install
- a custom relay
- a pinned package version

If the user wants the pairing QR or invite to be sent back to the **current existing OpenClaw chat conversation**, prefer the registered plugin command flow:

- `/privateclaw` for a normal one-to-one encrypted session
- `/privateclaw group` for a multi-participant encrypted room

That flow is preferred because the plugin command returns the invite URI and QR image back to the original Telegram, Discord, or QQ conversation through OpenClaw's normal reply payload path.

If the current environment can directly invoke the registered `privateclaw` plugin command in the active conversation, prefer that over local CLI pairing.

If there is no suitable active OpenClaw chat channel available, fall back to the local CLI pairing flow:

- `openclaw privateclaw pair`
- `openclaw privateclaw pair --group`
- `openclaw privateclaw pair --open`
- `openclaw privateclaw sessions`
- `openclaw privateclaw kick <sessionId> <appId>`

If the user does not have the OpenClaw alias available but does have the standalone npm binary installed, use the equivalent `privateclaw-provider ...` commands.

## Client app access

When a user asks where to get the PrivateClaw client builds, point them at:

- iOS App Store (YourClaw): `https://apps.apple.com/us/app/yourclaw/id6760531637`
- Android closed alpha tester group: `https://groups.google.com/g/gg-studio-ai-products`
- Android closed alpha (Google Play): `https://play.google.com/store/apps/details?id=gg.ai.privateclaw`
- Desktop GitHub Releases (Windows / macOS / Linux, choose the `app-v*` releases): `https://github.com/topcheer/PrivateClaw/releases`

Be explicit that Android testers must join the Google Group before Google Play will admit them to the closed alpha, and that desktop users should download from the `app-v*` GitHub Releases rather than the provider / relay `v*` releases.

## Recommended execution flow

### 1. Preflight

First confirm that the `openclaw` CLI is available:

```bash
openclaw --version
```

If `openclaw` is missing, stop and tell the user that OpenClaw itself must be installed first.

### 2. Install and enable the plugin

Use the published npm package by default, and keep `--dangerously-force-unsafe-install` on every manual install path:

```bash
openclaw plugins install --dangerously-force-unsafe-install @privateclaw/privateclaw@latest
openclaw plugins enable privateclaw
```

If the user already has a local package directory, prefer installing that directory instead of an archive because OpenClaw `2026.3.31` can drop the unsafe-install override on archive installs:

```bash
openclaw plugins install --dangerously-force-unsafe-install ./packages/privateclaw-provider
openclaw plugins enable privateclaw
```

### 3. Optional relay override

Only do this when the user explicitly wants to point PrivateClaw at a self-hosted or custom relay:

```bash
openclaw config set plugins.entries.privateclaw.config.relayBaseUrl https://your-relay.example.com
```

If the user is using the default public relay at `https://relay.privateclaw.us`, skip this step.

### 4. Restart the running OpenClaw gateway or service

Do not claim setup is complete until the running OpenClaw process has reloaded the plugin and config.

That usually means restarting the active `openclaw start` process or whichever service unit hosts the gateway.

### 5. Verify command registration

Check that the `privateclaw` command is now registered:

```bash
openclaw commands list
```

Confirm that `privateclaw` appears in the command list before moving on.

## Pairing flows

### Flow A: return the QR to the current Telegram / Discord / QQ conversation

Use this flow when:

- the user is already using an OpenClaw-backed channel conversation
- the user wants the pairing QR returned to that same chat

Preferred next step:

- have the user send `/privateclaw` in that same conversation
- use `/privateclaw group` when the user wants a shared encrypted room for multiple app participants

Expected result:

- OpenClaw replies in the original channel conversation
- the reply contains the invite URI and QR image
- the user scans that QR with the PrivateClaw mobile app

If the runtime can execute the registered plugin command directly for the current channel conversation, do that instead of asking the user to repeat the command manually.

### Flow B: local CLI fallback

Use this flow when there is no active OpenClaw chat channel available, or when the user explicitly wants local terminal pairing:

```bash
openclaw privateclaw pair
```

Useful variants:

```bash
openclaw privateclaw pair --group
openclaw privateclaw pair --open
openclaw privateclaw pair --group --foreground
openclaw privateclaw sessions
openclaw privateclaw kick <sessionId> <appId>
```

`--group` creates a multi-participant room.

`--open` opens a local browser preview page for the QR, which is useful when terminal rendering alone is inconvenient.

By default, `pair` prints the invite and then returns while a background daemon keeps the session alive until expiry.

Use `--foreground` when the user explicitly wants to keep the session attached to the current terminal. On supported runtimes, `Ctrl+D` hands that live foreground session off to the background daemon without replacing the QR.

Do **not** recommend `--print-only` unless the user only wants a one-shot QR printout, because that mode closes the session immediately after printing.

The same public subcommands also exist on the standalone npm binary:

```bash
privateclaw-provider pair --group --foreground
privateclaw-provider sessions
privateclaw-provider sessions killall
privateclaw-provider killall
privateclaw-provider kick <sessionId> <appId>
```

### Flow C: active-session commands inside PrivateClaw

Once a PrivateClaw session is already active, the participant can request the current pairing QR again from inside that encrypted session:

```text
/session-qr
```

Use this when the user wants to re-share the existing active session instead of creating a new one.

If the user needs to extend the session lifetime without replacing the whole setup, use:

```text
/renew-session
```

In active group sessions, participants can also pause or resume assistant replies without interrupting participant-to-participant chat:

```text
/mute-bot
/unmute-bot
```

Use those only for group sessions where the user specifically wants the chat room to stay open while temporarily muting or restoring bot replies.

## Local checkout / development flow

Only use this when the user explicitly wants to install from a local repository checkout instead of npm:

```bash
openclaw plugins install --link ./packages/privateclaw-provider
openclaw plugins enable privateclaw
openclaw config set plugins.entries.privateclaw.config.relayBaseUrl ws://127.0.0.1:8787
```

Then restart the running OpenClaw gateway or service before testing.

## Guardrails

- Do not use `openclaw channels add privateclaw`; PrivateClaw is not a channel transport.
- Do not set `relayBaseUrl` unless the user asks for a custom relay.
- Do not default to the `--link` development install unless the user is working from a local checkout.
- Do not say setup succeeded until the gateway or service has been restarted and `openclaw commands list` shows `privateclaw`.
- If the user's goal is to receive the QR in the current Telegram, Discord, or QQ conversation, prefer `/privateclaw` over `openclaw privateclaw pair`.
- Do not recommend `--print-only` when the user expects the QR to remain usable after the command exits.
- If the OpenClaw alias is unavailable but the standalone binary exists, use `privateclaw-provider ...` rather than inventing a different command surface.
- After a successful pairing flow, remind the user to scan the returned QR with the PrivateClaw app.

## Troubleshooting

### `privateclaw` does not appear in `openclaw commands list`

Likely causes:

- the plugin was installed but not enabled
- the gateway or service was not restarted after install or config change
- the user is looking at an older OpenClaw instance than the one they just modified

### The user wants `/privateclaw` in Telegram, Discord, or QQ but nothing happens there

PrivateClaw is only the plugin that creates the QR invite. The surrounding channel transport still has to exist separately in OpenClaw. If the user wants `/privateclaw` inside Telegram, Discord, or QQ, those channels must already be set up in OpenClaw.

### The user wants to use their own relay

Set:

```bash
openclaw config set plugins.entries.privateclaw.config.relayBaseUrl <relay-base-url>
```

Then restart the running OpenClaw gateway or service before testing again.

### `openclaw privateclaw pair` returns immediately and the user thinks the session stopped

That is expected with the current default behavior. Local pairing now returns after printing while a background daemon keeps the session alive.

If the user wants the session to stay attached to the current shell, use:

```bash
openclaw privateclaw pair --foreground
```

If the user already started a foreground session and wants to hand it off without stopping it, `Ctrl+D` is the preferred path on supported runtimes.

### The user printed a QR but nobody can join anymore

Check whether they used `--print-only`. That mode prints the invite and QR, then immediately closes the session.

If they need a live reusable session, have them use normal `pair`, `pair --group`, or `pair --foreground` instead.

### The user needs to inspect or moderate a locally managed group session

Use:

```bash
openclaw privateclaw sessions
openclaw privateclaw sessions killall
openclaw privateclaw kick <sessionId> <appId>
```

Use the standalone `privateclaw-provider sessions` / `privateclaw-provider kick ...` forms when the user is working outside the OpenClaw alias. If they need to clear all background daemon sessions at once, use `openclaw privateclaw sessions killall` or `privateclaw-provider killall`.

## Completion checklist

The setup should usually end with all of the following being true:

- the plugin is installed
- the plugin is enabled
- the running OpenClaw gateway or service has been restarted
- `openclaw commands list` shows `privateclaw`
- the user has either:
  - received a `/privateclaw` QR reply in the original channel conversation, or
  - received a local `openclaw privateclaw pair` or `privateclaw-provider pair` QR and invite URI
- if the user expects a local CLI session to stay alive after the command returns, `sessions` shows the active session instead of the session having been created with `--print-only`