chrome-openclaw-sider 1.0.0 → 1.0.2

package/README.md

@@ -1,98 +1,65 @@
-# chrome-openclaw-sider
+# Chrome Channel for OpenClaw in Sider
 
-Official OpenClaw channel plugin for connecting OpenClaw in Sider.
+The official Chrome channel plugin for connecting OpenClaw to the Sider Chrome extension.
 
-It supports the standard OpenClaw channel login flow, one-time setup token exchange, and direct relay-token configuration.
+Once connected, you can control OpenClaw directly from the Sider Chrome sidebar.
 
-## Compatibility
+## 【【【 Quick install from the terminal 】】】
 
-- `openclaw >= 2026.3.22`
-
-## Recommended Install
-
-For most users, use the companion CLI:
+Run in Terminal:
 
+================================
 ```bash
 npx -y @sider-ai/chrome-openclaw-sider-cli install
 ```
+================================
 
-This installs or updates the plugin and starts terminal pairing automatically.
+You can also paste this command into the OpenClaw chat box and ask OpenClaw to install it for you. This will install or update the plugin and automatically start terminal pairing.
 
-## Manual Install
+## 【【【 Manual installation 】】】
 
-Install the plugin:
+If the quick install does not work, follow these steps:
 
-```bash
-openclaw plugins install chrome-openclaw-sider
-```
+### 【 1. Install or update the plugin 】
 
-If the plugin is already installed, update it instead:
+Install in Terminal:
 
+================================
 ```bash
-openclaw plugins update chrome-openclaw-sider
+openclaw plugins install clawhub:chrome-openclaw-sider
 ```
+================================
 
-Start the pairing flow:
+If the plugin is already installed, update it with:
 
+================================
 ```bash
-openclaw channels login --channel chrome-openclaw-sider
+openclaw plugins update clawhub:chrome-openclaw-sider
 ```
+================================
 
-The terminal will show a short pairing code. Enter that code in the Sider browser extension, then the plugin writes the long-lived token back to `channels.chrome-openclaw-sider`.
-
-## Configuration
+You can run these commands directly in your terminal, or paste them into the OpenClaw chat box and ask OpenClaw to execute them.
 
-The plugin supports three common setup modes.
+### 【 2. Pair the plugin with Sider’s Chrome extension using a pairing code 】
 
-### Terminal Pairing
-
-Use the built-in OpenClaw login flow:
+Run in Terminal:
 
+================================
 ```bash
 openclaw channels login --channel chrome-openclaw-sider
 ```
+================================
 
-### Setup Token
-
-Write a one-time token to `channels.chrome-openclaw-sider.setupToken`:
-
-```json
-{
-  "channels": {
-    "chrome-openclaw-sider": {
-      "enabled": true,
-      "setupToken": "<one-time-token>"
-    }
-  }
-}
-```
-
-On startup, the plugin exchanges `setupToken` for a long-lived `token`, writes it back to config, and removes `setupToken`.
-
-### Direct Relay Token
+Your terminal will display a short pairing code. Enter this code in the Sider browser extension.
 
-Write a long-lived relay token directly:
+In the Sider Chrome extension, open the **Claw** widget from the right column of the extension and enter the pairing code there. This will connect the Sider Chrome extension to your OpenClaw instance.
 
-```json
-{
-  "channels": {
-    "chrome-openclaw-sider": {
-      "enabled": true,
-      "token": "<relay-token>"
-    }
-  }
-}
-```
-
-Named accounts can be configured under `channels.chrome-openclaw-sider.accounts.<id>`.
+### 【 3. Restart the gateway 】
 
-After changing config manually, restart the gateway:
+After entering the pairing code, restart the gateway in Terminal:
 
+================================
 ```bash
 openclaw gateway restart
 ```
-
-## Notes
-
-- `setupToken` and `token` should not be used together for the same account.
-- Pairing is the simplest setup path for most users.
+================================

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chrome-openclaw-sider",
   "private": false,
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Official Chrome channel plugin for connecting OpenClaw in Sider Chrome extension",
   "type": "module",
   "files": [

package/src/account.ts

@@ -191,6 +191,7 @@ export const siderSetupWizard: ChannelSetupWizard = {
 
       const progress = prompter.progress("Waiting for connection...");
       const reportPendingUpdate = createSiderPairingPendingUpdateReporter({
+        pairingCode: pairing.pairingCode,
         report: (message) => {
           progress.update(message);
         },
@@ -199,6 +200,9 @@ export const siderSetupWizard: ChannelSetupWizard = {
         const paired = await waitForSiderPairing({
           pairing,
           onPending: reportPendingUpdate,
+          onRetryableError: (message) => {
+            progress.update(message);
+          },
         });
         progress.stop("Connected.");
 

package/src/auth.ts

@@ -1,13 +1,15 @@
 import { type OpenClawConfig, type PluginRuntime } from "openclaw/plugin-sdk";
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
 import { type OpenClawPluginService } from "openclaw/plugin-sdk/plugin-entry";
-import { SIDER_CHANNEL_ID, SIDER_DEFAULT_BASE_URL } from "./config.js";
+import {
+  SIDER_CHANNEL_ID,
+  SIDER_DEFAULT_BASE_URL,
+  readDefaultSiderSetupTokenEnv,
+  readSiderBaseUrlEnv,
+} from "./config.js";
 import { SIDER_USER_AGENT } from "./user-agent.js";
 
 export const SIDER_AUTH_EXCHANGE_API_PATH = "/v1/claws/register";
-export const SIDER_SETUP_TOKEN_ENV = "SIDER_SETUP_TOKEN";
-export const SIDER_BASE_URL_ENV = "SIDER_BASE_URL";
-
 export type SiderSetupConfigSnapshot = {
   enabled?: boolean;
   setupToken?: string;
@@ -51,12 +53,8 @@ function normalizeGatewayUrl(raw?: string): string | undefined {
   return trimmed ? trimmed.replace(/\/+$/, "") : undefined;
 }
 
-function normalizeAccountEnvSuffix(accountId: string): string {
-  return accountId.trim().replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase();
-}
-
 export function resolveSiderBaseUrl(): string {
-  return normalizeGatewayUrl(process.env[SIDER_BASE_URL_ENV]) ?? SIDER_DEFAULT_BASE_URL;
+  return normalizeGatewayUrl(readSiderBaseUrlEnv()) ?? SIDER_DEFAULT_BASE_URL;
 }
 
 function getPendingOperation(accountId: string): Promise<OpenClawConfig> | undefined {
@@ -232,15 +230,8 @@ export function resolveSiderSetupToken(
   if (configuredToken) {
     return configuredToken;
   }
-  const accountSuffix = normalizeAccountEnvSuffix(accountId);
-  if (accountSuffix) {
-    const namedToken = trimMaybe(process.env[`${SIDER_SETUP_TOKEN_ENV}_${accountSuffix}`]);
-    if (namedToken) {
-      return namedToken;
-    }
-  }
   if (accountId === DEFAULT_ACCOUNT_ID) {
-    return trimMaybe(process.env[SIDER_SETUP_TOKEN_ENV]);
+    return trimMaybe(readDefaultSiderSetupTokenEnv());
   }
   return undefined;
 }

package/src/channel.ts

@@ -3817,6 +3817,7 @@ export const siderPlugin: ChannelPlugin<ResolvedSiderAccount> = {
           }),
         );
         const reportPendingUpdate = createSiderPairingPendingUpdateReporter({
+          pairingCode: pairing.pairingCode,
           report: (message) => {
             runtime.log(message);
           },
@@ -3825,6 +3826,9 @@ export const siderPlugin: ChannelPlugin<ResolvedSiderAccount> = {
           const paired = await waitForSiderPairing({
             pairing,
             onPending: reportPendingUpdate,
+            onRetryableError: (message) => {
+              runtime.log(message);
+            },
           });
           const latestCfg = loadConfig();
           const nextCfg = applySiderSetupAccountConfig({

package/src/config.ts

@@ -12,3 +12,18 @@ export const SIDER_CHANNEL_BLURB = "Command your OpenClaw from Chrome Sidebar di
 export const SIDER_CHANNEL_ALIASES = ["sider"] as const;
 
 export const SIDER_DEFAULT_BASE_URL = "https://sider.ai/api/claw/self";
+export const SIDER_SETUP_TOKEN_ENV = "SIDER_SETUP_TOKEN";
+export const SIDER_BASE_URL_ENV = "SIDER_BASE_URL";
+export const SIDER_REMOTE_BROWSER_ENABLE_ENV = "SIDER_ENABLE_REMOTE_BROWSER_MCP";
+
+export function readSiderBaseUrlEnv(): string | undefined {
+  return process.env.SIDER_BASE_URL;
+}
+
+export function readDefaultSiderSetupTokenEnv(): string | undefined {
+  return process.env.SIDER_SETUP_TOKEN;
+}
+
+export function readSiderRemoteBrowserEnableEnv(): string | undefined {
+  return process.env.SIDER_ENABLE_REMOTE_BROWSER_MCP;
+}

package/src/remote-browser-support.ts

@@ -1,7 +1,11 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { SIDER_CHANNEL_ID } from "./config.js";
+import {
+  SIDER_CHANNEL_ID,
+  SIDER_REMOTE_BROWSER_ENABLE_ENV,
+  readSiderRemoteBrowserEnableEnv,
+} from "./config.js";
 
-export const SIDER_REMOTE_BROWSER_ENABLE_ENV = "SIDER_ENABLE_REMOTE_BROWSER_MCP";
+export { SIDER_REMOTE_BROWSER_ENABLE_ENV } from "./config.js";
 
 const SIDER_REMOTE_BROWSER_PREPEND_CONTEXT = [
   "Sider remote-browser mode is enabled.",
@@ -31,7 +35,7 @@ function isTruthyEnv(value: string | undefined): boolean {
 }
 
 function isRemoteBrowserSupportEnabled(): boolean {
-  return isTruthyEnv(process.env[SIDER_REMOTE_BROWSER_ENABLE_ENV]);
+  return isTruthyEnv(readSiderRemoteBrowserEnableEnv());
 }
 
 function buildRemoteBrowserPromptInjection(): RemoteBrowserPromptInjection {

package/src/setup-core.ts

@@ -60,6 +60,13 @@ export class SiderPairingExpiredError extends Error {
   }
 }
 
+export class SiderPairingTransientError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SiderPairingTransientError";
+  }
+}
+
 function trimMaybe(value: unknown): string | undefined {
   return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
@@ -134,6 +141,43 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function describeUnknownError(error: unknown): string {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  return String(error);
+}
+
+function isRetryableFetchError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  if (error.name === "TypeError" && /fetch failed/i.test(error.message)) {
+    return true;
+  }
+
+  const cause = "cause" in error ? error.cause : undefined;
+  const causeCode =
+    cause && typeof cause === "object" && "code" in cause && typeof cause.code === "string"
+      ? cause.code
+      : undefined;
+  return Boolean(
+    causeCode &&
+      [
+        "ECONNRESET",
+        "ECONNREFUSED",
+        "EHOSTUNREACH",
+        "ENETUNREACH",
+        "ENOTFOUND",
+        "ETIMEDOUT",
+        "UND_ERR_CONNECT_TIMEOUT",
+        "UND_ERR_HEADERS_TIMEOUT",
+        "UND_ERR_BODY_TIMEOUT",
+        "UND_ERR_SOCKET",
+      ].includes(causeCode),
+  );
+}
+
 function supportsTerminalFormatting(): boolean {
   return Boolean(process.stdout.isTTY);
 }
@@ -170,11 +214,24 @@ export function formatSiderPairingTtl(remainingMs: number): string {
   return `${minutes}:${String(seconds).padStart(2, "0")}`;
 }
 
-export function formatSiderPairingPendingMessage(remainingMs: number): string {
-  return `Waiting for connection... Pairing code expires in ${formatSiderPairingTtl(remainingMs)}.`;
+export function formatSiderPairingPendingMessage(params: {
+  pairingCode: string;
+  remainingMs: number;
+}): string {
+  return `Waiting for connection... Pairing code: ${formatHighlightedPairingCode(params.pairingCode)}. Pairing code expires in ${formatSiderPairingTtl(params.remainingMs)}.`;
+}
+
+export function formatSiderPairingRetryMessage(params: {
+  pairingCode: string;
+  remainingMs: number;
+  retryAfterMs: number;
+  detail: string;
+}): string {
+  return `Temporary connection issue while checking pairing status (${params.detail}). Retrying in ${formatSiderPairingTtl(params.retryAfterMs)}. Pairing code: ${formatHighlightedPairingCode(params.pairingCode)}. Pairing code expires in ${formatSiderPairingTtl(params.remainingMs)}.`;
 }
 
 export function createSiderPairingPendingUpdateReporter(params: {
+  pairingCode: string;
   report: (message: string) => void | Promise<void>;
   intervalMs?: number;
 }): (state: { remainingMs: number; pollIntervalMs: number }) => void | Promise<void> {
@@ -192,7 +249,12 @@ export function createSiderPairingPendingUpdateReporter(params: {
     }
     hasReported = true;
     lastReportedAt = now;
-    await params.report(formatSiderPairingPendingMessage(remainingMs));
+    await params.report(
+      formatSiderPairingPendingMessage({
+        pairingCode: params.pairingCode,
+        remainingMs,
+      }),
+    );
   };
 }
 
@@ -262,19 +324,33 @@ export async function requestSiderPairing(): Promise<SiderPairingSession> {
 export async function readSiderPairingStatus(
   pairingToken: string,
 ): Promise<SiderPairStatusResponse | { status: "expired" }> {
-  const response = await fetch(resolveSiderApiUrl(SIDER_PAIR_STATUS_API_PATH), {
-    method: "GET",
-    headers: {
-      Authorization: formatAuthorizationHeader(pairingToken),
-      "User-Agent": SIDER_USER_AGENT,
-    },
-  });
+  const url = resolveSiderApiUrl(SIDER_PAIR_STATUS_API_PATH);
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: formatAuthorizationHeader(pairingToken),
+        "User-Agent": SIDER_USER_AGENT,
+      },
+    });
+  } catch (error) {
+    if (isRetryableFetchError(error)) {
+      throw new SiderPairingTransientError(describeUnknownError(error));
+    }
+    throw error;
+  }
   if (response.status === 410) {
     return { status: "expired" };
   }
+  if ([502, 503, 504].includes(response.status)) {
+    throw new SiderPairingTransientError(
+      `server returned ${response.status} ${response.statusText}${await parseErrorDetail(response)}`,
+    );
+  }
   if (!response.ok) {
     throw new Error(
-      `selfclaw pairing status failed (${response.status} ${response.statusText})${await parseErrorDetail(response)}`,
+      `selfclaw pairing status failed (${url} ${response.status} ${response.statusText})${await parseErrorDetail(response)}`,
     );
   }
   return parsePairStatusResponse(await readJsonResponse(response));
@@ -283,11 +359,31 @@ export async function readSiderPairingStatus(
 export async function waitForSiderPairing(params: {
   pairing: SiderPairingSession;
   onPending?: (state: { remainingMs: number; pollIntervalMs: number }) => void | Promise<void>;
+  onRetryableError?: (message: string) => void | Promise<void>;
 }): Promise<SiderPairingResult> {
   const expiresAtMs = params.pairing.expiresAt * 1000;
 
   while (true) {
-    const status = await readSiderPairingStatus(params.pairing.pairingToken);
+    let status: SiderPairStatusResponse | { status: "expired" };
+    try {
+      status = await readSiderPairingStatus(params.pairing.pairingToken);
+    } catch (error) {
+      const remainingMs = Math.max(0, expiresAtMs - Date.now());
+      if (error instanceof SiderPairingTransientError && remainingMs > 0) {
+        const retryAfterMs = Math.min(params.pairing.pollIntervalMs, remainingMs);
+        await params.onRetryableError?.(
+          formatSiderPairingRetryMessage({
+            pairingCode: params.pairing.pairingCode,
+            remainingMs,
+            retryAfterMs,
+            detail: error.message,
+          }),
+        );
+        await sleep(retryAfterMs);
+        continue;
+      }
+      throw error;
+    }
     if (status.status === "paired") {
       return {
         clawId: status.claw_id,
@@ -323,7 +419,8 @@ export function formatSiderPairingInstructions(params: {
     "",
     "1. Install the Sider Chrome extension from the link above",
     "2. Click the Sider icon in your browser toolbar to open the side panel",
-    '3. Click "Connect to OpenClaw" and enter the pairing code above',
+    "3. In the right sidebar, find and click the Claw icon (the paw-shaped icon, 2nd from top)",
+    `4. Enter the pairing code "${params.pairingCode}" and click Connect`,
     "",
     "I'm waiting for the connection...",
   ].join("\n");