@clawhive/openclaw-plugin 0.2.3 → 0.2.5

package/README.md

@@ -33,7 +33,7 @@ After plugin install, run:
 openclaw clawhive authorize
 ```
 
-The command prints the approval URL plus `user_code`, waits for approval, and persists the resulting `pluginToken` and `userId` into the OpenClaw config. Then restart the gateway.
+The command prints an app authorization QR plus fallback `user_code`, waits for approval in the signed-in ClawHive app, and persists the resulting `pluginToken` and `userId` into the OpenClaw config. Then restart the gateway.
 
 On the next `openclaw gateway run`:
 
@@ -44,6 +44,25 @@ On the next `openclaw gateway run`:
 
 No shared dev secret exists; each install owns its own credential and can be revoked independently.
 
+### Move this runtime to another account
+
+To remove this OpenClaw installation from its current ClawHive account, run:
+
+```bash
+openclaw clawhive unlink --yes
+```
+
+This revokes the current plugin token and removes its cloud node from the old
+account. Stop or restart the gateway, then run `openclaw clawhive authorize`
+and approve the QR in the new account's signed-in App. The new account gets a
+new node; the old account's agents, conversations, and history are not moved.
+
+The phone device is shared by OpenClaw and Hermes. If OpenClaw is the last
+runtime using it, unlink releases the phone so the original or a different
+account can authorize next. If Hermes still uses the phone, OpenClaw can be
+authorized again only by the same account; unlink Hermes as well before moving
+the shared phone to another account.
+
 ## Configuration
 
 Minimum managed-cloud install: **nothing**. The plugin falls back to the baked `DEFAULT_PROJECT_URL` in `src/defaults.ts`, silently bootstraps, and writes everything else into config.
@@ -126,7 +145,9 @@ The current OpenClaw SDK surface does not yet expose a stable local marketplace
 ## Manual Commands
 
 - `openclaw clawhive authorize`
-  Prints the browser approval URL and device user code, then waits for authorization.
+  Prints the app authorization QR and fallback device user code, then waits for authorization.
+- `openclaw clawhive unlink`
+  Shows the account-transfer impact without changing anything. Add `--yes` to revoke this runtime authorization, remove its node from the current account, and clear the local identity.
 - `openclaw clawhive pair`
   Prints a fresh mobile pairing QR plus short code on demand so you can re-pair a phone after reinstall, add another phone, or recover if you missed the startup banner.
 - `openclaw clawhive pair --ttl-seconds 600`

package/dist/src/authorization.d.ts

@@ -19,6 +19,9 @@ type AuthorizationDeps = {
     printDeviceCodePrompt?: typeof printDeviceCodePrompt;
     awaitDeviceCodeApproval?: typeof awaitDeviceCodeApproval;
 };
+type UnlinkDeps = {
+    createCloudApi?: typeof createClawHiveCloudApi;
+};
 /**
  * Print a fresh mobile pairing QR and short code on demand.
  */
@@ -27,6 +30,13 @@ export declare function printManualPairingCode(api: OpenClawPluginApi, ttlSecond
  * Run the explicit device-authorization command for the ClawHive plugin.
  */
 export declare function authorizeClawHivePlugin(api: OpenClawPluginApi, deps?: AuthorizationDeps): Promise<void>;
+/**
+ * Revoke this runtime's current account authorization before it is approved
+ * from a different signed-in mobile App account.
+ */
+export declare function unlinkClawHivePlugin(api: OpenClawPluginApi, options: {
+    yes?: boolean;
+}, deps?: UnlinkDeps): Promise<void>;
 /**
  * Register the top-level `openclaw clawhive` CLI group for manual plugin authorization.
  */

package/dist/src/authorization.js

@@ -1,5 +1,5 @@
 import { ClawHiveCloudApi, ClawHiveApiError, DeviceCodeDeniedError, DeviceCodeExpiredError, } from "./client.js";
-import { resolveResolvedAccount, writeRegistrationIdentity } from "./config.js";
+import { clearAuthorizationIdentity, resolveResolvedAccount, writeRegistrationIdentity, } from "./config.js";
 import { awaitDeviceCodeApproval, printDeviceCodePrompt, } from "./deviceCode.js";
 import { getPairedDeviceCount, printPairingQr } from "./pairing.js";
 /**
@@ -28,7 +28,7 @@ export function createClawHiveCloudApi(api) {
  */
 export function printAuthorizationCommandHint(logger) {
     logger.warn("ClawHive plugin is installed but not authorized yet.");
-    logger.info("Run `openclaw clawhive authorize` in your terminal to display the approval URL and user code.");
+    logger.info("Run `openclaw clawhive authorize` in your terminal to display an app authorization QR and fallback code.");
     logger.info("If the command reports a missing anon key, set `channels.clawhive.anonKey` in config or export `CLAWHIVE_SUPABASE_ANON_KEY` first.");
 }
 /**
@@ -94,7 +94,8 @@ export async function authorizeClawHivePlugin(api, deps = {}) {
     const { account, cloudApi } = (deps.createCloudApi ?? createClawHiveCloudApi)(api);
     if (cloudApi.pluginToken) {
         try {
-            await cloudApi.registerPluginNode();
+            const registration = await cloudApi.registerPluginNode();
+            await syncRegistrationIdentity(api, { account, registration });
             api.logger.info("ClawHive is already authorized. Restart the gateway if you are waiting for it to connect.");
             return;
         }
@@ -118,13 +119,19 @@ export async function authorizeClawHivePlugin(api, deps = {}) {
             start,
             logger: api.logger,
         });
+        cloudApi.setAuthorizationIdentity({
+            pluginToken: approval.plugin_token,
+            userId: approval.user_id,
+        });
+        const registration = await cloudApi.registerPluginNode();
         const latestCfg = api.runtime.config.loadConfig();
         await api.runtime.config.writeConfigFile(writeRegistrationIdentity(latestCfg, {
             anonKey: account.anonKey,
             pluginToken: approval.plugin_token,
-            userId: approval.user_id,
+            userId: registration.user_id,
+            pluginNodeId: registration.plugin_node.id,
         }));
-        api.logger.info("ClawHive authorization completed. Restart the gateway to finish plugin registration.");
+        api.logger.info("ClawHive authorization completed and plugin node registered. Restart the gateway if you are waiting for it to connect.");
     }
     catch (error) {
         if (error instanceof DeviceCodeDeniedError) {
@@ -138,6 +145,54 @@ export async function authorizeClawHivePlugin(api, deps = {}) {
         throw error;
     }
 }
+/**
+ * Revoke this runtime's current account authorization before it is approved
+ * from a different signed-in mobile App account.
+ */
+export async function unlinkClawHivePlugin(api, options, deps = {}) {
+    if (!options.yes) {
+        api.logger.warn("This removes the current OpenClaw runtime from its ClawHive account. No changes were made.");
+        api.logger.info("Run openclaw clawhive unlink --yes to confirm.");
+        return;
+    }
+    const { account, cloudApi } = (deps.createCloudApi ?? createClawHiveCloudApi)(api);
+    const clearLocalIdentity = async () => {
+        const latestCfg = api.runtime.config.loadConfig();
+        await api.runtime.config.writeConfigFile(clearAuthorizationIdentity(latestCfg));
+    };
+    if (!account.pluginToken || !account.pluginNodeId) {
+        await clearLocalIdentity();
+        api.logger.info("ClawHive local authorization was already incomplete and has been cleared. Run openclaw clawhive authorize to connect an account.");
+        return;
+    }
+    try {
+        const result = await cloudApi.unlinkPluginNode();
+        await clearLocalIdentity();
+        api.logger.info(result.node_removed
+            ? "ClawHive runtime authorization revoked and node removed from the current account."
+            : "ClawHive runtime authorization was already removed from the current account.");
+        if (result.device_released) {
+            api.logger.info("ClawHive shared phone device was released. This runtime can now be authorized by the original or a different ClawHive account.");
+        }
+        else if (result.device_retained_reason === "other_runtime_linked") {
+            const runtimes = result.remaining_runtime_types
+                .map((runtime) => runtime === "hermes" ? "Hermes" : "OpenClaw")
+                .join(" and ");
+            api.logger.warn(`${runtimes || "Another runtime"} still uses this phone. Reauthorize OpenClaw with the same account, or unlink every remaining runtime before moving the phone to another account.`);
+        }
+    }
+    catch (error) {
+        if (!isInvalidStoredPluginTokenError(error)) {
+            throw error;
+        }
+        await clearLocalIdentity();
+        api.logger.info("ClawHive stored authorization was already invalid and has been cleared locally.");
+    }
+    api.logger.info("Stop or restart the OpenClaw gateway, then run openclaw clawhive authorize and approve with the new account in the ClawHive app.");
+    if (process.env.CLAWHIVE_PLUGIN_TOKEN) {
+        api.logger.warn("CLAWHIVE_PLUGIN_TOKEN is set in this shell. Run unset CLAWHIVE_PLUGIN_TOKEN to avoid using the old credential.");
+    }
+}
 function isInvalidStoredPluginTokenError(error) {
     if (!(error instanceof ClawHiveApiError)) {
         return false;
@@ -158,10 +213,17 @@ export function registerClawHiveCli(api) {
             .description("Manage ClawHive plugin authorization and pairing");
         clawhive
             .command("authorize")
-            .description("Display the approval URL and user code, then wait for plugin authorization")
+            .description("Display an app authorization QR and fallback code, then wait for plugin authorization")
             .action(async () => {
             await authorizeClawHivePlugin(api);
         });
+        clawhive
+            .command("unlink")
+            .description("Revoke this OpenClaw runtime authorization and remove it from the current ClawHive account")
+            .option("--yes", "Confirm unlinking this runtime")
+            .action(async (options) => {
+            await unlinkClawHivePlugin(api, options);
+        });
         clawhive
             .command("pair")
             .description("Print a fresh mobile pairing QR code and short code")

package/dist/src/client.d.ts

@@ -47,6 +47,7 @@ export type PluginNode = {
     node_name?: string | null;
     plugin_version?: string | null;
     plugin_status: "online" | "offline" | "degraded";
+    runtime_type?: "openclaw" | "hermes";
     last_heartbeat_at?: string | null;
 };
 export type PluginRegisterResult = {
@@ -57,6 +58,13 @@ export type PluginRegisterResult = {
     heartbeat_interval: number;
     user_session: UserSession;
 };
+export type PluginUnlinkResult = {
+    unlinked: true;
+    node_removed: boolean;
+    device_released: boolean;
+    device_retained_reason: "other_runtime_linked" | "device_not_found" | null;
+    remaining_runtime_types: Array<"openclaw" | "hermes">;
+};
 export type PairingCodeResult = {
     pair_token: string;
     expires_at: string;
@@ -77,11 +85,13 @@ export type SyncAgentInput = {
 export type SyncedAgent = {
     id: string;
     user_id: string;
+    plugin_node_id?: string | null;
+    runtime_type: "openclaw" | "hermes";
+    runtime_agent_id: string;
     openclaw_agent_id: string;
     name: string;
     description: string | null;
     avatar_url: string | null;
-    source_type: string;
     config: Record<string, unknown>;
     created_at: string;
 };
@@ -179,6 +189,10 @@ export declare class ClawHiveCloudApi {
     get baseUrl(): string;
     get userId(): string | null;
     get pluginToken(): string | null;
+    setAuthorizationIdentity(identity: {
+        pluginToken: string;
+        userId: string;
+    }): void;
     private requireUserId;
     private requirePluginToken;
     startDeviceCode(opts?: {
@@ -188,6 +202,7 @@ export declare class ClawHiveCloudApi {
     }): Promise<DeviceCodeStartResult>;
     exchangeDeviceCode(deviceCode: string): Promise<DeviceCodeExchangeResult>;
     registerPluginNode(): Promise<PluginRegisterResult>;
+    unlinkPluginNode(): Promise<PluginUnlinkResult>;
     createPairingCode(pluginNodeId: string, ttlSeconds?: number): Promise<PairingCodeResult>;
     heartbeat(params: {
         pluginNodeId: string;

package/dist/src/client.js

@@ -68,6 +68,10 @@ export class ClawHiveCloudApi {
     get pluginToken() {
         return this.config.pluginToken ?? null;
     }
+    setAuthorizationIdentity(identity) {
+        this.config.pluginToken = identity.pluginToken;
+        this.config.userId = identity.userId;
+    }
     requireUserId() {
         if (!this.config.userId) {
             throw new Error("ClawHiveCloudApi: userId is not set. Call registerPluginNode() before making user-scoped calls.");
@@ -86,6 +90,7 @@ export class ClawHiveCloudApi {
             method: "POST",
             auth: "none",
             body: {
+                runtime_type: "openclaw",
                 node_name: opts?.nodeName ?? this.config.nodeName ?? "OpenClaw Desktop",
                 plugin_version: opts?.pluginVersion ?? this.config.pluginVersion ?? "0.2.0",
                 description: opts?.description,
@@ -128,6 +133,7 @@ export class ClawHiveCloudApi {
             plugin_node_id: this.config.pluginNodeId ?? null,
             node_name: this.config.nodeName ?? "OpenClaw Desktop",
             plugin_version: this.config.pluginVersion ?? "0.2.0",
+            runtime_type: "openclaw",
         };
         if (this.config.userId) {
             body.user_id = this.config.userId;
@@ -139,8 +145,23 @@ export class ClawHiveCloudApi {
             body,
         });
         this.config.userId = result.user_id;
+        this.config.pluginNodeId = result.plugin_node.id;
         return result;
     }
+    async unlinkPluginNode() {
+        if (!this.config.pluginNodeId) {
+            throw new Error("ClawHive plugin node id is missing");
+        }
+        return this.request({
+            path: "plugin-unlink",
+            method: "POST",
+            auth: "plugin",
+            body: {
+                plugin_node_id: this.config.pluginNodeId,
+                runtime_type: "openclaw",
+            },
+        });
+    }
     async createPairingCode(pluginNodeId, ttlSeconds) {
         return this.request({
             path: "pairing-code-create",
@@ -172,6 +193,7 @@ export class ClawHiveCloudApi {
             auth: "plugin",
             body: {
                 plugin_node_id: params.pluginNodeId,
+                runtime_type: "openclaw",
                 session_id: params.sessionId,
                 agent_id: params.agentId,
                 user_id: this.requireUserId(),
@@ -190,7 +212,10 @@ export class ClawHiveCloudApi {
             auth: "plugin",
             body: {
                 user_id: this.requireUserId(),
+                plugin_node_id: this.config.pluginNodeId,
+                runtime_type: "openclaw",
                 agents: agents.map((agent) => ({
+                    runtime_agent_id: agent.openclawAgentId,
                     openclaw_agent_id: agent.openclawAgentId,
                     name: agent.name,
                     description: agent.description ?? null,

package/dist/src/config.d.ts

@@ -26,3 +26,8 @@ export declare function writeRegistrationIdentity(cfg: OpenClawConfig, patch: {
     pluginToken?: string;
     anonKey?: string;
 }): OpenClawConfig;
+/**
+ * Remove only the locally persisted identity for this ClawHive runtime.
+ * Connection defaults and publishing preferences survive account transfer.
+ */
+export declare function clearAuthorizationIdentity(cfg: OpenClawConfig): OpenClawConfig;

package/dist/src/config.js

@@ -79,6 +79,21 @@ export function writeRegistrationIdentity(cfg, patch) {
         next.anonKey = patch.anonKey;
     return patchChannelSection(cfg, next);
 }
+/**
+ * Remove only the locally persisted identity for this ClawHive runtime.
+ * Connection defaults and publishing preferences survive account transfer.
+ */
+export function clearAuthorizationIdentity(cfg) {
+    const { pluginToken: _pluginToken, userId: _userId, pluginNodeId: _pluginNodeId, ...remainingSection } = readRawChannelSection(cfg);
+    const channels = cfg.channels ?? {};
+    return {
+        ...cfg,
+        channels: {
+            ...channels,
+            [CLAWHIVE_CHANNEL_ID]: remainingSection,
+        },
+    };
+}
 function patchChannelSection(cfg, patch) {
     const nextChannels = {
         ...(cfg.channels ?? {}),

package/dist/src/deviceCode.d.ts

@@ -7,6 +7,7 @@ export type DeviceCodeAwaitResult = {
     user_id: string;
     plugin_token: string;
 };
+export declare function normalizeDeviceCodeUrl(url: string): string;
 export declare function printDeviceCodePrompt(start: DeviceCodeStartResult, logger: DeviceCodeLogger): Promise<void>;
 export declare function awaitDeviceCodeApproval(params: {
     api: ClawHiveCloudApi;

package/dist/src/deviceCode.js

@@ -5,18 +5,24 @@ async function renderQr(text) {
         qrcodeTerminal.generate(text, { small: true }, (qr) => resolve(qr));
     });
 }
+export function normalizeDeviceCodeUrl(url) {
+    const parsed = new URL(url);
+    if (parsed.hostname === "127.0.0.1") {
+        parsed.hostname = "localhost";
+    }
+    return parsed.toString();
+}
 export async function printDeviceCodePrompt(start, logger) {
-    const qr = await renderQr(start.verification_uri_complete);
+    const qr = await renderQr(`clawhive-auth:v1:${start.device_code}`);
     const expiresInMin = Math.floor(start.expires_in / 60);
     const lines = [
         "",
         "════════════════════════════════════════════════════════════",
         "  ClawHive: authorize this OpenClaw install.",
         "",
-        `  Visit: ${start.verification_uri}`,
         `  Enter the code: ${start.user_code}`,
         "",
-        "  Or scan this QR to jump straight to the approval page:",
+        "  Scan this QR with the signed-in ClawHive mobile app:",
         qr,
         `  (Expires in ${expiresInMin}m; polling for approval…)`,
         "════════════════════════════════════════════════════════════",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawhive/openclaw-plugin",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "ClawHive channel plugin for OpenClaw",
   "license": "UNLICENSED",
   "homepage": "https://github.com/optimalAIs/clawhive#readme",