privateclaw-plugin-setup（privateclaw 插件设置）

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:

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:

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:

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:

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:

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:

openclaw privateclaw pair

Useful variants:

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:

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:

/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:

/renew-session

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

/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:

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:

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:

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:

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