Upload 321 files

packages/clawdbot/index.js

@@ -0,0 +1 @@
+export * from "openclaw";

packages/clawdbot/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "clawdbot",
+  "version": "2026.1.27-beta.1",
+  "description": "Compatibility shim that forwards to openclaw",
+  "bin": {
+    "clawdbot": "./bin/clawdbot.js"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./cli-entry": "./bin/clawdbot.js"
+  },
+  "scripts": {
+    "postinstall": "node ./scripts/postinstall.js"
+  },
+  "dependencies": {
+    "openclaw": "workspace:*"
+  }
+}

packages/clawdbot/scripts/postinstall.js

@@ -0,0 +1 @@
+console.warn("clawdbot renamed -> openclaw");

packages/moltbot/index.js

@@ -0,0 +1 @@
+export * from "openclaw";

packages/moltbot/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "moltbot",
+  "version": "2026.1.27-beta.1",
+  "description": "Compatibility shim that forwards to openclaw",
+  "bin": {
+    "moltbot": "./bin/moltbot.js"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./cli-entry": "./bin/moltbot.js"
+  },
+  "scripts": {
+    "postinstall": "node ./scripts/postinstall.js"
+  },
+  "dependencies": {
+    "openclaw": "workspace:*"
+  }
+}

packages/moltbot/scripts/postinstall.js

@@ -0,0 +1 @@
+console.warn("moltbot renamed -> openclaw");

scripts/auth-monitor.sh

@@ -0,0 +1,89 @@
+#!/bin/bash
+# Auth Expiry Monitor
+# Run via cron or systemd timer to get proactive notifications
+# before Claude Code auth expires.
+#
+# Suggested cron: */30 * * * * /home/admin/openclaw/scripts/auth-monitor.sh
+#
+# Environment variables:
+#   NOTIFY_PHONE - Phone number to send OpenClaw notification (e.g., +1234567890)
+#   NOTIFY_NTFY  - ntfy.sh topic for push notifications (e.g., openclaw-alerts)
+#   WARN_HOURS   - Hours before expiry to warn (default: 2)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE_CREDS="$HOME/.claude/.credentials.json"
+STATE_FILE="$HOME/.openclaw/auth-monitor-state"
+
+# Configuration
+WARN_HOURS="${WARN_HOURS:-2}"
+NOTIFY_PHONE="${NOTIFY_PHONE:-}"
+NOTIFY_NTFY="${NOTIFY_NTFY:-}"
+
+# State tracking to avoid spam
+mkdir -p "$(dirname "$STATE_FILE")"
+LAST_NOTIFIED=$(cat "$STATE_FILE" 2>/dev/null || echo "0")
+NOW=$(date +%s)
+
+# Only notify once per hour max
+MIN_INTERVAL=3600
+
+send_notification() {
+    local message="$1"
+    local priority="${2:-default}"
+
+    echo "$(date '+%Y-%m-%d %H:%M:%S') - $message"
+
+    # Check if we notified recently
+    if [ $((NOW - LAST_NOTIFIED)) -lt $MIN_INTERVAL ]; then
+        echo "Skipping notification (sent recently)"
+        return
+    fi
+
+    # Send via OpenClaw if phone configured and auth still valid
+    if [ -n "$NOTIFY_PHONE" ]; then
+        # Check if we can still use openclaw
+        if "$SCRIPT_DIR/claude-auth-status.sh" simple 2>/dev/null | grep -q "OK\|EXPIRING"; then
+            echo "Sending via OpenClaw to $NOTIFY_PHONE..."
+            openclaw send --to "$NOTIFY_PHONE" --message "$message" 2>/dev/null || true
+        fi
+    fi
+
+    # Send via ntfy.sh if configured
+    if [ -n "$NOTIFY_NTFY" ]; then
+        echo "Sending via ntfy.sh to $NOTIFY_NTFY..."
+        curl -s -o /dev/null \
+            -H "Title: OpenClaw Auth Alert" \
+            -H "Priority: $priority" \
+            -H "Tags: warning,key" \
+            -d "$message" \
+            "https://ntfy.sh/$NOTIFY_NTFY" || true
+    fi
+
+    # Update state
+    echo "$NOW" > "$STATE_FILE"
+}
+
+# Check auth status
+if [ ! -f "$CLAUDE_CREDS" ]; then
+    send_notification "Claude Code credentials missing! Run: claude setup-token" "high"
+    exit 1
+fi
+
+EXPIRES_AT=$(jq -r '.claudeAiOauth.expiresAt // 0' "$CLAUDE_CREDS")
+NOW_MS=$((NOW * 1000))
+DIFF_MS=$((EXPIRES_AT - NOW_MS))
+HOURS_LEFT=$((DIFF_MS / 3600000))
+MINS_LEFT=$(((DIFF_MS % 3600000) / 60000))
+
+if [ "$DIFF_MS" -lt 0 ]; then
+    send_notification "Claude Code auth EXPIRED! OpenClaw is down. Run: ssh l36 '~/openclaw/scripts/mobile-reauth.sh'" "urgent"
+    exit 1
+elif [ "$HOURS_LEFT" -lt "$WARN_HOURS" ]; then
+    send_notification "Claude Code auth expires in ${HOURS_LEFT}h ${MINS_LEFT}m. Consider re-auth soon." "high"
+    exit 0
+else
+    echo "$(date '+%Y-%m-%d %H:%M:%S') - Auth OK: ${HOURS_LEFT}h ${MINS_LEFT}m remaining"
+    exit 0
+fi

scripts/bench-model.ts

@@ -0,0 +1,145 @@
+import { completeSimple, getModel, type Model } from "@mariozechner/pi-ai";
+
+type Usage = {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  totalTokens?: number;
+};
+
+type RunResult = {
+  durationMs: number;
+  usage?: Usage;
+};
+
+const DEFAULT_PROMPT = "Reply with a single word: ok. No punctuation or extra text.";
+const DEFAULT_RUNS = 10;
+
+function parseArg(flag: string): string | undefined {
+  const idx = process.argv.indexOf(flag);
+  if (idx === -1) {
+    return undefined;
+  }
+  return process.argv[idx + 1];
+}
+
+function parseRuns(raw: string | undefined): number {
+  if (!raw) {
+    return DEFAULT_RUNS;
+  }
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_RUNS;
+  }
+  return Math.floor(parsed);
+}
+
+function median(values: number[]): number {
+  if (values.length === 0) {
+    return 0;
+  }
+  const sorted = [...values].toSorted((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 0) {
+    return Math.round((sorted[mid - 1] + sorted[mid]) / 2);
+  }
+  return sorted[mid];
+}
+
+async function runModel(opts: {
+  label: string;
+  model: Model<any>;
+  apiKey: string;
+  runs: number;
+  prompt: string;
+}): Promise<RunResult[]> {
+  const results: RunResult[] = [];
+  for (let i = 0; i < opts.runs; i += 1) {
+    const started = Date.now();
+    const res = await completeSimple(
+      opts.model,
+      {
+        messages: [
+          {
+            role: "user",
+            content: opts.prompt,
+            timestamp: Date.now(),
+          },
+        ],
+      },
+      { apiKey: opts.apiKey, maxTokens: 64 },
+    );
+    const durationMs = Date.now() - started;
+    results.push({ durationMs, usage: res.usage });
+    console.log(`${opts.label} run ${i + 1}/${opts.runs}: ${durationMs}ms`);
+  }
+  return results;
+}
+
+async function main(): Promise<void> {
+  const runs = parseRuns(parseArg("--runs"));
+  const prompt = parseArg("--prompt") ?? DEFAULT_PROMPT;
+
+  const anthropicKey = process.env.ANTHROPIC_API_KEY?.trim();
+  const minimaxKey = process.env.MINIMAX_API_KEY?.trim();
+  if (!anthropicKey) {
+    throw new Error("Missing ANTHROPIC_API_KEY in environment.");
+  }
+  if (!minimaxKey) {
+    throw new Error("Missing MINIMAX_API_KEY in environment.");
+  }
+
+  const minimaxBaseUrl = process.env.MINIMAX_BASE_URL?.trim() || "https://api.minimax.io/v1";
+  const minimaxModelId = process.env.MINIMAX_MODEL?.trim() || "MiniMax-M2.1";
+
+  const minimaxModel: Model<"openai-completions"> = {
+    id: minimaxModelId,
+    name: `MiniMax ${minimaxModelId}`,
+    api: "openai-completions",
+    provider: "minimax",
+    baseUrl: minimaxBaseUrl,
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200000,
+    maxTokens: 8192,
+  };
+  const opusModel = getModel("anthropic", "claude-opus-4-5");
+
+  console.log(`Prompt: ${prompt}`);
+  console.log(`Runs: ${runs}`);
+  console.log("");
+
+  const minimaxResults = await runModel({
+    label: "minimax",
+    model: minimaxModel,
+    apiKey: minimaxKey,
+    runs,
+    prompt,
+  });
+  const opusResults = await runModel({
+    label: "opus",
+    model: opusModel,
+    apiKey: anthropicKey,
+    runs,
+    prompt,
+  });
+
+  const summarize = (label: string, results: RunResult[]) => {
+    const durations = results.map((r) => r.durationMs);
+    const med = median(durations);
+    const min = Math.min(...durations);
+    const max = Math.max(...durations);
+    return { label, med, min, max };
+  };
+
+  const summary = [summarize("minimax", minimaxResults), summarize("opus", opusResults)];
+  console.log("");
+  console.log("Summary (ms):");
+  for (const row of summary) {
+    console.log(`${row.label.padEnd(7)} median=${row.med} min=${row.min} max=${row.max}`);
+  }
+}
+
+await main();

scripts/build-and-run-mac.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/../apps/macos"
+
+BUILD_PATH=".build-local"
+PRODUCT="OpenClaw"
+BIN="$BUILD_PATH/debug/$PRODUCT"
+
+printf "\n▶️  Building $PRODUCT (debug, build path: $BUILD_PATH)\n"
+swift build -c debug --product "$PRODUCT" --build-path "$BUILD_PATH"
+
+printf "\n⏹  Stopping existing $PRODUCT...\n"
+killall -q "$PRODUCT" 2>/dev/null || true
+
+printf "\n🚀 Launching $BIN ...\n"
+nohup "$BIN" >/tmp/openclaw.log 2>&1 &
+PID=$!
+printf "Started $PRODUCT (PID $PID). Logs: /tmp/openclaw.log\n"

scripts/build-docs-list.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const binDir = path.join(root, "bin");
+const binPath = path.join(binDir, "docs-list");
+
+fs.mkdirSync(binDir, { recursive: true });
+
+const wrapper = `#!/usr/bin/env node\nimport { spawnSync } from "node:child_process";\nimport path from "node:path";\nimport { fileURLToPath } from "node:url";\n\nconst here = path.dirname(fileURLToPath(import.meta.url));\nconst script = path.join(here, "..", "scripts", "docs-list.js");\n\nconst result = spawnSync(process.execPath, [script], { stdio: "inherit" });\nprocess.exit(result.status ?? 1);\n`;
+
+fs.writeFileSync(binPath, wrapper, { mode: 0o755 });

scripts/build_icon.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Render the macOS .icon bundle to a padded .icns like Trimmy's pipeline.
+# Defaults target the OpenClaw assets so you can just run the script from repo root.
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+ICON_FILE=${1:-"$ROOT_DIR/apps/macos/Icon.icon"}
+BASENAME=${2:-OpenClaw}
+OUT_ROOT=${3:-"$ROOT_DIR/apps/macos/build/icon"}
+XCODE_APP=${XCODE_APP:-/Applications/Xcode.app}
+# Where the final .icns should live; override DEST_ICNS to change.
+DEST_ICNS=${DEST_ICNS:-"$ROOT_DIR/apps/macos/Sources/OpenClaw/Resources/OpenClaw.icns"}
+
+ICTOOL="$XCODE_APP/Contents/Applications/Icon Composer.app/Contents/Executables/ictool"
+if [[ ! -x "$ICTOOL" ]]; then
+  ICTOOL="$XCODE_APP/Contents/Applications/Icon Composer.app/Contents/Executables/icontool"
+fi
+if [[ ! -x "$ICTOOL" ]]; then
+  echo "ictool/icontool not found. Set XCODE_APP if Xcode is elsewhere." >&2
+  exit 1
+fi
+
+ICONSET_DIR="$OUT_ROOT/${BASENAME}.iconset"
+TMP_DIR="$OUT_ROOT/tmp"
+mkdir -p "$ICONSET_DIR" "$TMP_DIR"
+
+MASTER_ART="$TMP_DIR/icon_art_824.png"
+MASTER_1024="$TMP_DIR/icon_1024.png"
+
+# Render inner art (no margin) with macOS Default appearance
+"$ICTOOL" "$ICON_FILE" \
+  --export-preview macOS Default 824 824 1 -45 "$MASTER_ART"
+
+# Pad to 1024x1024 with transparent border
+sips --padToHeightWidth 1024 1024 "$MASTER_ART" --out "$MASTER_1024" >/dev/null
+
+# Generate required sizes
+sizes=(16 32 64 128 256 512 1024)
+for sz in "${sizes[@]}"; do
+  out="$ICONSET_DIR/icon_${sz}x${sz}.png"
+  sips -z "$sz" "$sz" "$MASTER_1024" --out "$out" >/dev/null
+  if [[ "$sz" -ne 1024 ]]; then
+    dbl=$((sz*2))
+    out2="$ICONSET_DIR/icon_${sz}x${sz}@2x.png"
+    sips -z "$dbl" "$dbl" "$MASTER_1024" --out "$out2" >/dev/null
+  fi
+done
+
+# 512x512@2x already covered by 1024; ensure it exists
+cp "$MASTER_1024" "$ICONSET_DIR/icon_512x512@2x.png"
+
+iconutil -c icns "$ICONSET_DIR" -o "$OUT_ROOT/${BASENAME}.icns"
+
+mkdir -p "$(dirname "$DEST_ICNS")"
+cp "$OUT_ROOT/${BASENAME}.icns" "$DEST_ICNS"
+
+echo "Icon.icns generated at $DEST_ICNS"

scripts/bundle-a2ui.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+on_error() {
+  echo "A2UI bundling failed. Re-run with: pnpm canvas:a2ui:bundle" >&2
+  echo "If this persists, verify pnpm deps and try again." >&2
+}
+trap on_error ERR
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+HASH_FILE="$ROOT_DIR/src/canvas-host/a2ui/.bundle.hash"
+OUTPUT_FILE="$ROOT_DIR/src/canvas-host/a2ui/a2ui.bundle.js"
+A2UI_RENDERER_DIR="$ROOT_DIR/vendor/a2ui/renderers/lit"
+A2UI_APP_DIR="$ROOT_DIR/apps/shared/OpenClawKit/Tools/CanvasA2UI"
+
+# Docker builds exclude vendor/apps via .dockerignore.
+# In that environment we must keep the prebuilt bundle.
+if [[ ! -d "$A2UI_RENDERER_DIR" || ! -d "$A2UI_APP_DIR" ]]; then
+  echo "A2UI sources missing; keeping prebuilt bundle."
+  exit 0
+fi
+
+INPUT_PATHS=(
+  "$ROOT_DIR/package.json"
+  "$ROOT_DIR/pnpm-lock.yaml"
+  "$A2UI_RENDERER_DIR"
+  "$A2UI_APP_DIR"
+)
+
+compute_hash() {
+  ROOT_DIR="$ROOT_DIR" node --input-type=module - "${INPUT_PATHS[@]}" <<'NODE'
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+const rootDir = process.env.ROOT_DIR ?? process.cwd();
+const inputs = process.argv.slice(2);
+const files = [];
+
+async function walk(entryPath) {
+  const st = await fs.stat(entryPath);
+  if (st.isDirectory()) {
+    const entries = await fs.readdir(entryPath);
+    for (const entry of entries) {
+      await walk(path.join(entryPath, entry));
+    }
+    return;
+  }
+  files.push(entryPath);
+}
+
+for (const input of inputs) {
+  await walk(input);
+}
+
+function normalize(p) {
+  return p.split(path.sep).join("/");
+}
+
+files.sort((a, b) => normalize(a).localeCompare(normalize(b)));
+
+const hash = createHash("sha256");
+for (const filePath of files) {
+  const rel = normalize(path.relative(rootDir, filePath));
+  hash.update(rel);
+  hash.update("\0");
+  hash.update(await fs.readFile(filePath));
+  hash.update("\0");
+}
+
+process.stdout.write(hash.digest("hex"));
+NODE
+}
+
+current_hash="$(compute_hash)"
+if [[ -f "$HASH_FILE" ]]; then
+  previous_hash="$(cat "$HASH_FILE")"
+  if [[ "$previous_hash" == "$current_hash" && -f "$OUTPUT_FILE" ]]; then
+    echo "A2UI bundle up to date; skipping."
+    exit 0
+  fi
+fi
+
+pnpm -s exec tsc -p "$A2UI_RENDERER_DIR/tsconfig.json"
+rolldown -c "$A2UI_APP_DIR/rolldown.config.mjs"
+
+echo "$current_hash" > "$HASH_FILE"

scripts/canvas-a2ui-copy.ts

@@ -0,0 +1,40 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export function getA2uiPaths(env = process.env) {
+  const srcDir = env.OPENCLAW_A2UI_SRC_DIR ?? path.join(repoRoot, "src", "canvas-host", "a2ui");
+  const outDir = env.OPENCLAW_A2UI_OUT_DIR ?? path.join(repoRoot, "dist", "canvas-host", "a2ui");
+  return { srcDir, outDir };
+}
+
+export async function copyA2uiAssets({ srcDir, outDir }: { srcDir: string; outDir: string }) {
+  const skipMissing = process.env.OPENCLAW_A2UI_SKIP_MISSING === "1";
+  try {
+    await fs.stat(path.join(srcDir, "index.html"));
+    await fs.stat(path.join(srcDir, "a2ui.bundle.js"));
+  } catch (err) {
+    const message = 'Missing A2UI bundle assets. Run "pnpm canvas:a2ui:bundle" and retry.';
+    if (skipMissing) {
+      console.warn(`${message} Skipping copy (OPENCLAW_A2UI_SKIP_MISSING=1).`);
+      return;
+    }
+    throw new Error(message, { cause: err });
+  }
+  await fs.mkdir(path.dirname(outDir), { recursive: true });
+  await fs.cp(srcDir, outDir, { recursive: true });
+}
+
+async function main() {
+  const { srcDir, outDir } = getA2uiPaths();
+  await copyA2uiAssets({ srcDir, outDir });
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().catch((err) => {
+    console.error(String(err));
+    process.exit(1);
+  });
+}

scripts/changelog-to-html.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+VERSION=${1:-}
+CHANGELOG_FILE=${2:-}
+
+if [[ -z "$VERSION" ]]; then
+  echo "Usage: $0 <version> [changelog_file]" >&2
+  exit 1
+fi
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+if [[ -z "$CHANGELOG_FILE" ]]; then
+  if [[ -f "$SCRIPT_DIR/../CHANGELOG.md" ]]; then
+    CHANGELOG_FILE="$SCRIPT_DIR/../CHANGELOG.md"
+  elif [[ -f "CHANGELOG.md" ]]; then
+    CHANGELOG_FILE="CHANGELOG.md"
+  elif [[ -f "../CHANGELOG.md" ]]; then
+    CHANGELOG_FILE="../CHANGELOG.md"
+  else
+    echo "Error: Could not find CHANGELOG.md" >&2
+    exit 1
+  fi
+fi
+
+if [[ ! -f "$CHANGELOG_FILE" ]]; then
+  echo "Error: Changelog file '$CHANGELOG_FILE' not found" >&2
+  exit 1
+fi
+
+extract_version_section() {
+  local version=$1
+  local file=$2
+  awk -v version="$version" '
+    BEGIN { found=0 }
+    /^## / {
+      if ($0 ~ "^##[[:space:]]+" version "([[:space:]].*|$)") { found=1; next }
+      if (found) { exit }
+    }
+    found { print }
+  ' "$file"
+}
+
+markdown_to_html() {
+  local text=$1
+  text=$(echo "$text" | sed 's/^##### \(.*\)$/<h5>\1<\/h5>/')
+  text=$(echo "$text" | sed 's/^#### \(.*\)$/<h4>\1<\/h4>/')
+  text=$(echo "$text" | sed 's/^### \(.*\)$/<h3>\1<\/h3>/')
+  text=$(echo "$text" | sed 's/^## \(.*\)$/<h2>\1<\/h2>/')
+  text=$(echo "$text" | sed 's/^- \*\*\([^*]*\)\*\*\(.*\)$/<li><strong>\1<\/strong>\2<\/li>/')
+  text=$(echo "$text" | sed 's/^- \([^*].*\)$/<li>\1<\/li>/')
+  text=$(echo "$text" | sed 's/\*\*\([^*]*\)\*\*/<strong>\1<\/strong>/g')
+  text=$(echo "$text" | sed 's/`\([^`]*\)`/<code>\1<\/code>/g')
+  text=$(echo "$text" | sed 's/\[\([^]]*\)\](\([^)]*\))/<a href="\2">\1<\/a>/g')
+  echo "$text"
+}
+
+version_content=$(extract_version_section "$VERSION" "$CHANGELOG_FILE")
+if [[ -z "$version_content" ]]; then
+  echo "<h2>OpenClaw $VERSION</h2>"
+  echo "<p>Latest OpenClaw update.</p>"
+  echo "<p><a href=\"https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md\">View full changelog</a></p>"
+  exit 0
+fi
+
+echo "<h2>OpenClaw $VERSION</h2>"
+
+in_list=false
+while IFS= read -r line; do
+  if [[ "$line" =~ ^- ]]; then
+    if [[ "$in_list" == false ]]; then
+      echo "<ul>"
+      in_list=true
+    fi
+    markdown_to_html "$line"
+  else
+    if [[ "$in_list" == true ]]; then
+      echo "</ul>"
+      in_list=false
+    fi
+    if [[ -n "$line" ]]; then
+      markdown_to_html "$line"
+    fi
+  fi
+done <<< "$version_content"
+
+if [[ "$in_list" == true ]]; then
+  echo "</ul>"
+fi
+
+echo "<p><a href=\"https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md\">View full changelog</a></p>"

scripts/check-ts-max-loc.ts

@@ -0,0 +1,80 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+type ParsedArgs = {
+  maxLines: number;
+};
+
+function parseArgs(argv: string[]): ParsedArgs {
+  let maxLines = 500;
+
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === "--max") {
+      const next = argv[index + 1];
+      if (!next || Number.isNaN(Number(next))) {
+        throw new Error("Missing/invalid --max value");
+      }
+      maxLines = Number(next);
+      index++;
+      continue;
+    }
+  }
+
+  return { maxLines };
+}
+
+function gitLsFilesAll(): string[] {
+  // Include untracked files too so local refactors don’t “pass” by accident.
+  const stdout = execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard"], {
+    encoding: "utf8",
+  });
+  return stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+async function countLines(filePath: string): Promise<number> {
+  const content = await readFile(filePath, "utf8");
+  // Count physical lines. Keeps the rule simple + predictable.
+  return content.split("\n").length;
+}
+
+async function main() {
+  // Makes `... | head` safe.
+  process.stdout.on("error", (error: NodeJS.ErrnoException) => {
+    if (error.code === "EPIPE") {
+      process.exit(0);
+    }
+    throw error;
+  });
+
+  const { maxLines } = parseArgs(process.argv.slice(2));
+  const files = gitLsFilesAll()
+    .filter((filePath) => existsSync(filePath))
+    .filter((filePath) => filePath.endsWith(".ts") || filePath.endsWith(".tsx"));
+
+  const results = await Promise.all(
+    files.map(async (filePath) => ({ filePath, lines: await countLines(filePath) })),
+  );
+
+  const offenders = results
+    .filter((result) => result.lines > maxLines)
+    .toSorted((a, b) => b.lines - a.lines);
+
+  if (!offenders.length) {
+    return;
+  }
+
+  // Minimal, grep-friendly output.
+  for (const offender of offenders) {
+    // eslint-disable-next-line no-console
+    console.log(`${offender.lines}\t${offender.filePath}`);
+  }
+
+  process.exitCode = 1;
+}
+
+await main();

scripts/claude-auth-status.sh

@@ -0,0 +1,280 @@
+#!/bin/bash
+# Claude Code Authentication Status Checker
+# Checks both Claude Code and OpenClaw auth status
+
+set -euo pipefail
+
+CLAUDE_CREDS="$HOME/.claude/.credentials.json"
+OPENCLAW_AUTH="$HOME/.openclaw/agents/main/agent/auth-profiles.json"
+
+# Colors for terminal output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+# Output mode: "full" (default), "json", or "simple"
+OUTPUT_MODE="${1:-full}"
+
+fetch_models_status_json() {
+    openclaw models status --json 2>/dev/null || true
+}
+
+STATUS_JSON="$(fetch_models_status_json)"
+USE_JSON=0
+if [ -n "$STATUS_JSON" ]; then
+    USE_JSON=1
+fi
+
+calc_status_from_expires() {
+    local expires_at="$1"
+    if ! [[ "$expires_at" =~ ^-?[0-9]+$ ]]; then
+        expires_at=0
+    fi
+    local now_ms=$(( $(date +%s) * 1000 ))
+    local diff_ms=$((expires_at - now_ms))
+    local hours=$((diff_ms / 3600000))
+    local mins=$(((diff_ms % 3600000) / 60000))
+
+    if [ "$expires_at" -le 0 ]; then
+        echo "MISSING"
+        return 1
+    elif [ "$diff_ms" -lt 0 ]; then
+        echo "EXPIRED"
+        return 1
+    elif [ "$diff_ms" -lt 3600000 ]; then
+        echo "EXPIRING:${mins}m"
+        return 2
+    else
+        echo "OK:${hours}h${mins}m"
+        return 0
+    fi
+}
+
+json_expires_for_claude_cli() {
+    echo "$STATUS_JSON" | jq -r '
+        [.auth.oauth.profiles[]
+          | select(.provider == "anthropic" and (.type == "oauth" or .type == "token"))
+          | .expiresAt // 0]
+        | max // 0
+    ' 2>/dev/null || echo "0"
+}
+
+json_expires_for_anthropic_any() {
+    echo "$STATUS_JSON" | jq -r '
+        [.auth.oauth.profiles[]
+          | select(.provider == "anthropic" and .type == "oauth")
+          | .expiresAt // 0]
+        | max // 0
+    ' 2>/dev/null || echo "0"
+}
+
+json_best_anthropic_profile() {
+    echo "$STATUS_JSON" | jq -r '
+        [.auth.oauth.profiles[]
+          | select(.provider == "anthropic" and .type == "oauth")
+          | {id: .profileId, exp: (.expiresAt // 0)}]
+        | sort_by(.exp) | reverse | .[0].id // "none"
+    ' 2>/dev/null || echo "none"
+}
+
+json_anthropic_api_key_count() {
+    echo "$STATUS_JSON" | jq -r '
+        [.auth.providers[] | select(.provider == "anthropic") | .profiles.apiKey]
+        | max // 0
+    ' 2>/dev/null || echo "0"
+}
+
+check_claude_code_auth() {
+    if [ "$USE_JSON" -eq 1 ]; then
+        local expires_at
+        expires_at=$(json_expires_for_claude_cli)
+        calc_status_from_expires "$expires_at"
+        return $?
+    fi
+
+    if [ ! -f "$CLAUDE_CREDS" ]; then
+        echo "MISSING"
+        return 1
+    fi
+
+    local expires_at
+    expires_at=$(jq -r '.claudeAiOauth.expiresAt // 0' "$CLAUDE_CREDS" 2>/dev/null || echo "0")
+    calc_status_from_expires "$expires_at"
+}
+
+check_openclaw_auth() {
+    if [ "$USE_JSON" -eq 1 ]; then
+        local api_keys
+        api_keys=$(json_anthropic_api_key_count)
+        if ! [[ "$api_keys" =~ ^[0-9]+$ ]]; then
+            api_keys=0
+        fi
+        local expires_at
+        expires_at=$(json_expires_for_anthropic_any)
+
+        if [ "$expires_at" -le 0 ] && [ "$api_keys" -gt 0 ]; then
+            echo "OK:static"
+            return 0
+        fi
+
+        calc_status_from_expires "$expires_at"
+        return $?
+    fi
+
+    if [ ! -f "$OPENCLAW_AUTH" ]; then
+        echo "MISSING"
+        return 1
+    fi
+
+    local expires
+    expires=$(jq -r '
+        [.profiles | to_entries[] | select(.value.provider == "anthropic") | .value.expires]
+        | max // 0
+    ' "$OPENCLAW_AUTH" 2>/dev/null || echo "0")
+
+    calc_status_from_expires "$expires"
+}
+
+# JSON output mode
+if [ "$OUTPUT_MODE" = "json" ]; then
+    claude_status=$(check_claude_code_auth 2>/dev/null || true)
+    openclaw_status=$(check_openclaw_auth 2>/dev/null || true)
+
+    claude_expires=0
+    openclaw_expires=0
+    if [ "$USE_JSON" -eq 1 ]; then
+        claude_expires=$(json_expires_for_claude_cli)
+        openclaw_expires=$(json_expires_for_anthropic_any)
+    else
+        claude_expires=$(jq -r '.claudeAiOauth.expiresAt // 0' "$CLAUDE_CREDS" 2>/dev/null || echo "0")
+        openclaw_expires=$(jq -r '.profiles["anthropic:default"].expires // 0' "$OPENCLAW_AUTH" 2>/dev/null || echo "0")
+    fi
+
+    jq -n \
+        --arg cs "$claude_status" \
+        --arg ce "$claude_expires" \
+        --arg bs "$openclaw_status" \
+        --arg be "$openclaw_expires" \
+        '{
+            claude_code: {status: $cs, expires_at_ms: ($ce | tonumber)},
+            openclaw: {status: $bs, expires_at_ms: ($be | tonumber)},
+            needs_reauth: (($cs | startswith("EXPIRED") or startswith("EXPIRING") or startswith("MISSING")) or ($bs | startswith("EXPIRED") or startswith("EXPIRING") or startswith("MISSING")))
+        }'
+    exit 0
+fi
+
+# Simple output mode (for scripts/widgets)
+if [ "$OUTPUT_MODE" = "simple" ]; then
+    claude_status=$(check_claude_code_auth 2>/dev/null || true)
+    openclaw_status=$(check_openclaw_auth 2>/dev/null || true)
+
+    if [[ "$claude_status" == EXPIRED* ]] || [[ "$claude_status" == MISSING* ]]; then
+        echo "CLAUDE_EXPIRED"
+        exit 1
+    elif [[ "$openclaw_status" == EXPIRED* ]] || [[ "$openclaw_status" == MISSING* ]]; then
+        echo "OPENCLAW_EXPIRED"
+        exit 1
+    elif [[ "$claude_status" == EXPIRING* ]]; then
+        echo "CLAUDE_EXPIRING"
+        exit 2
+    elif [[ "$openclaw_status" == EXPIRING* ]]; then
+        echo "OPENCLAW_EXPIRING"
+        exit 2
+    else
+        echo "OK"
+        exit 0
+    fi
+fi
+
+# Full output mode (default)
+echo "=== Claude Code Auth Status ==="
+echo ""
+
+# Claude Code credentials
+echo "Claude Code (~/.claude/.credentials.json):"
+if [ "$USE_JSON" -eq 1 ]; then
+    expires_at=$(json_expires_for_claude_cli)
+else
+    expires_at=$(jq -r '.claudeAiOauth.expiresAt // 0' "$CLAUDE_CREDS" 2>/dev/null || echo "0")
+fi
+
+if [ -f "$CLAUDE_CREDS" ]; then
+    sub_type=$(jq -r '.claudeAiOauth.subscriptionType // "unknown"' "$CLAUDE_CREDS" 2>/dev/null || echo "unknown")
+    rate_tier=$(jq -r '.claudeAiOauth.rateLimitTier // "unknown"' "$CLAUDE_CREDS" 2>/dev/null || echo "unknown")
+    echo "  Subscription: $sub_type"
+    echo "  Rate tier: $rate_tier"
+fi
+
+if [ "$expires_at" -le 0 ]; then
+    echo -e "  Status: ${RED}NOT FOUND${NC}"
+    echo "  Action needed: Run 'claude setup-token'"
+else
+    now_ms=$(( $(date +%s) * 1000 ))
+    diff_ms=$((expires_at - now_ms))
+    hours=$((diff_ms / 3600000))
+    mins=$(((diff_ms % 3600000) / 60000))
+
+    if [ "$diff_ms" -lt 0 ]; then
+        echo -e "  Status: ${RED}EXPIRED${NC}"
+        echo "  Action needed: Run 'claude setup-token' or re-authenticate"
+    elif [ "$diff_ms" -lt 3600000 ]; then
+        echo -e "  Status: ${YELLOW}EXPIRING SOON (${mins}m remaining)${NC}"
+        echo "  Consider running: claude setup-token"
+    else
+        echo -e "  Status: ${GREEN}OK${NC}"
+        echo "  Expires: $(date -d @$((expires_at/1000))) (${hours}h ${mins}m)"
+    fi
+fi
+
+echo ""
+echo "OpenClaw Auth (~/.openclaw/agents/main/agent/auth-profiles.json):"
+if [ "$USE_JSON" -eq 1 ]; then
+    best_profile=$(json_best_anthropic_profile)
+    expires=$(json_expires_for_anthropic_any)
+    api_keys=$(json_anthropic_api_key_count)
+else
+    best_profile=$(jq -r '
+        .profiles | to_entries
+        | map(select(.value.provider == "anthropic"))
+        | sort_by(.value.expires) | reverse
+        | .[0].key // "none"
+    ' "$OPENCLAW_AUTH" 2>/dev/null || echo "none")
+    expires=$(jq -r '
+        [.profiles | to_entries[] | select(.value.provider == "anthropic") | .value.expires]
+        | max // 0
+    ' "$OPENCLAW_AUTH" 2>/dev/null || echo "0")
+    api_keys=0
+fi
+
+echo "  Profile: $best_profile"
+
+if [ "$expires" -le 0 ] && [ "$api_keys" -gt 0 ]; then
+    echo -e "  Status: ${GREEN}OK${NC} (API key)"
+elif [ "$expires" -le 0 ]; then
+    echo -e "  Status: ${RED}NOT FOUND${NC}"
+    echo "  Note: Run 'openclaw doctor --yes' to sync from Claude Code"
+else
+    now_ms=$(( $(date +%s) * 1000 ))
+    diff_ms=$((expires - now_ms))
+    hours=$((diff_ms / 3600000))
+    mins=$(((diff_ms % 3600000) / 60000))
+
+    if [ "$diff_ms" -lt 0 ]; then
+        echo -e "  Status: ${RED}EXPIRED${NC}"
+        echo "  Note: Run 'openclaw doctor --yes' to sync from Claude Code"
+    elif [ "$diff_ms" -lt 3600000 ]; then
+        echo -e "  Status: ${YELLOW}EXPIRING SOON (${mins}m remaining)${NC}"
+    else
+        echo -e "  Status: ${GREEN}OK${NC}"
+        echo "  Expires: $(date -d @$((expires/1000))) (${hours}h ${mins}m)"
+    fi
+fi
+
+echo ""
+echo "=== Service Status ==="
+if systemctl --user is-active openclaw >/dev/null 2>&1; then
+    echo -e "OpenClaw service: ${GREEN}running${NC}"
+else
+    echo -e "OpenClaw service: ${RED}NOT running${NC}"
+fi

scripts/clawlog.sh

@@ -0,0 +1,309 @@
+#!/bin/bash
+
+# VibeTunnel Logging Utility
+# Simplifies access to VibeTunnel logs using macOS unified logging system
+
+set -euo pipefail
+
+# Configuration
+SUBSYSTEM="ai.openclaw"
+DEFAULT_LEVEL="info"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Function to handle sudo password errors
+handle_sudo_error() {
+    echo -e "\n${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${YELLOW}⚠️  Password Required for Log Access${NC}"
+    echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n"
+    echo -e "clawlog needs to use sudo to show complete log data (Apple hides sensitive info by default)."
+    echo -e "\nTo avoid password prompts, configure passwordless sudo for the log command:"
+    echo -e "See: ${BLUE}apple/docs/logging-private-fix.md${NC}\n"
+    echo -e "Quick fix:"
+    echo -e "  1. Run: ${GREEN}sudo visudo${NC}"
+    echo -e "  2. Add: ${GREEN}$(whoami) ALL=(ALL) NOPASSWD: /usr/bin/log${NC}"
+    echo -e "  3. Save and exit (:wq)\n"
+    echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n"
+    exit 1
+}
+
+# Default values
+STREAM_MODE=false
+TIME_RANGE="5m"  # Default to last 5 minutes
+CATEGORY=""
+LOG_LEVEL="$DEFAULT_LEVEL"
+SEARCH_TEXT=""
+OUTPUT_FILE=""
+ERRORS_ONLY=false
+SERVER_ONLY=false
+TAIL_LINES=50  # Default number of lines to show
+SHOW_TAIL=true
+SHOW_HELP=false
+
+# Function to show usage
+show_usage() {
+    cat << EOF
+clawlog - OpenClaw Logging Utility
+
+USAGE:
+    clawlog [OPTIONS]
+
+DESCRIPTION:
+    View OpenClaw logs with full details (bypasses Apple's privacy redaction).
+    Requires sudo access configured for /usr/bin/log command.
+
+LOG FLOW ARCHITECTURE:
+    OpenClaw logs flow through the macOS unified log (subsystem: ai.openclaw).
+
+LOG CATEGORIES (examples):
+    • voicewake           - Voice wake detection/test harness
+    • gateway             - Gateway process manager
+    • xpc                 - XPC service calls
+    • notifications       - Notification helper
+    • screenshot          - Screenshotter
+    • shell               - ShellExecutor
+
+QUICK START:
+    clawlog -n 100             Show last 100 lines from all components
+    clawlog -f                 Follow logs in real-time
+    clawlog -e                 Show only errors
+    clawlog -c ServerManager   Show logs from ServerManager only
+
+OPTIONS:
+    -h, --help              Show this help message
+    -f, --follow            Stream logs continuously (like tail -f)
+    -n, --lines NUM         Number of lines to show (default: 50)
+    -l, --last TIME         Time range to search (default: 5m)
+                           Examples: 5m, 1h, 2d, 1w
+    -c, --category CAT      Filter by category (e.g., ServerManager, SessionService)
+    -e, --errors            Show only error messages
+    -d, --debug             Show debug level logs (more verbose)
+    -s, --search TEXT       Search for specific text in log messages
+    -o, --output FILE       Export logs to file
+    --server                Show only server output logs
+    --all                   Show all logs without tail limit
+    --list-categories       List all available log categories
+    --json                  Output in JSON format
+
+EXAMPLES:
+    clawlog                   Show last 50 lines from past 5 minutes (default)
+    clawlog -f                Stream logs continuously
+    clawlog -n 100            Show last 100 lines
+    clawlog -e                Show only recent errors
+    clawlog -l 30m -n 200     Show last 200 lines from past 30 minutes
+    clawlog -c ServerManager  Show recent ServerManager logs
+    clawlog -s "fail"         Search for "fail" in recent logs
+    clawlog --server -e       Show recent server errors
+    clawlog -f -d             Stream debug logs continuously
+
+CATEGORIES:
+    Common categories include:
+    - ServerManager         - Server lifecycle and configuration
+    - SessionService        - Terminal session management
+    - TerminalManager       - Terminal spawning and control
+    - GitRepository         - Git integration features
+    - ScreencapService      - Screen capture functionality
+    - WebRTCManager         - WebRTC connections
+    - UnixSocket           - Unix socket communication
+    - WindowTracker        - Window tracking and focus
+    - NgrokService         - Ngrok tunnel management
+    - ServerOutput         - Node.js server output
+
+TIME FORMATS:
+    - 5m  = 5 minutes       - 1h  = 1 hour
+    - 2d  = 2 days         - 1w  = 1 week
+
+EOF
+}
+
+# Function to list categories
+list_categories() {
+    echo -e "${BLUE}Fetching VibeTunnel log categories from the last hour...${NC}\n"
+
+    # Get unique categories from recent logs
+    log show --predicate "subsystem == \"$SUBSYSTEM\"" --last 1h 2>/dev/null | \
+        grep -E "category: \"[^\"]+\"" | \
+        sed -E 's/.*category: "([^"]+)".*/\1/' | \
+        sort | uniq | \
+        while read -r cat; do
+            echo "  • $cat"
+        done
+
+    echo -e "\n${YELLOW}Note: Only categories with recent activity are shown${NC}"
+}
+
+# Show help if no arguments provided
+if [[ $# -eq 0 ]]; then
+    show_usage
+    exit 0
+fi
+
+# Parse command line arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            show_usage
+            exit 0
+            ;;
+        -f|--follow)
+            STREAM_MODE=true
+            SHOW_TAIL=false
+            shift
+            ;;
+        -n|--lines)
+            TAIL_LINES="$2"
+            shift 2
+            ;;
+        -l|--last)
+            TIME_RANGE="$2"
+            shift 2
+            ;;
+        -c|--category)
+            CATEGORY="$2"
+            shift 2
+            ;;
+        -e|--errors)
+            ERRORS_ONLY=true
+            shift
+            ;;
+        -d|--debug)
+            LOG_LEVEL="debug"
+            shift
+            ;;
+        -s|--search)
+            SEARCH_TEXT="$2"
+            shift 2
+            ;;
+        -o|--output)
+            OUTPUT_FILE="$2"
+            shift 2
+            ;;
+        --server)
+            SERVER_ONLY=true
+            CATEGORY="ServerOutput"
+            shift
+            ;;
+        --list-categories)
+            list_categories
+            exit 0
+            ;;
+        --json)
+            STYLE_ARGS="--style json"
+            shift
+            ;;
+        --all)
+            SHOW_TAIL=false
+            shift
+            ;;
+        *)
+            echo -e "${RED}Unknown option: $1${NC}"
+            echo "Use -h or --help for usage information"
+            exit 1
+            ;;
+    esac
+done
+
+# Build the predicate
+PREDICATE="subsystem == \"$SUBSYSTEM\""
+
+# Add category filter if specified
+if [[ -n "$CATEGORY" ]]; then
+    PREDICATE="$PREDICATE AND category == \"$CATEGORY\""
+fi
+
+# Add error filter if specified
+if [[ "$ERRORS_ONLY" == true ]]; then
+    PREDICATE="$PREDICATE AND (eventType == \"error\" OR messageType == \"error\" OR eventMessage CONTAINS \"ERROR\" OR eventMessage CONTAINS \"[31m\")"
+fi
+
+# Add search filter if specified
+if [[ -n "$SEARCH_TEXT" ]]; then
+    PREDICATE="$PREDICATE AND eventMessage CONTAINS[c] \"$SEARCH_TEXT\""
+fi
+
+# Build the command - always use sudo with --info to show private data
+if [[ "$STREAM_MODE" == true ]]; then
+    # Streaming mode
+    CMD="sudo log stream --predicate '$PREDICATE' --level $LOG_LEVEL --info"
+
+    echo -e "${GREEN}Streaming VibeTunnel logs continuously...${NC}"
+    echo -e "${YELLOW}Press Ctrl+C to stop${NC}\n"
+else
+    # Show mode
+    CMD="sudo log show --predicate '$PREDICATE'"
+
+    # Add log level for show command
+    if [[ "$LOG_LEVEL" == "debug" ]]; then
+        CMD="$CMD --debug"
+    else
+        CMD="$CMD --info"
+    fi
+
+    # Add time range
+    CMD="$CMD --last $TIME_RANGE"
+
+    if [[ "$SHOW_TAIL" == true ]]; then
+        echo -e "${GREEN}Showing last $TAIL_LINES log lines from the past $TIME_RANGE${NC}"
+    else
+        echo -e "${GREEN}Showing all logs from the past $TIME_RANGE${NC}"
+    fi
+
+    # Show applied filters
+    if [[ "$ERRORS_ONLY" == true ]]; then
+        echo -e "${RED}Filter: Errors only${NC}"
+    fi
+    if [[ -n "$CATEGORY" ]]; then
+        echo -e "${BLUE}Category: $CATEGORY${NC}"
+    fi
+    if [[ -n "$SEARCH_TEXT" ]]; then
+        echo -e "${YELLOW}Search: \"$SEARCH_TEXT\"${NC}"
+    fi
+    echo ""  # Empty line for readability
+fi
+
+# Add style arguments if specified
+if [[ -n "${STYLE_ARGS:-}" ]]; then
+    CMD="$CMD $STYLE_ARGS"
+fi
+
+# Execute the command
+if [[ -n "$OUTPUT_FILE" ]]; then
+    # First check if sudo works without password for the log command
+    if sudo -n /usr/bin/log show --last 1s 2>&1 | grep -q "password"; then
+        handle_sudo_error
+    fi
+
+    echo -e "${BLUE}Exporting logs to: $OUTPUT_FILE${NC}\n"
+    if [[ "$SHOW_TAIL" == true ]] && [[ "$STREAM_MODE" == false ]]; then
+        eval "$CMD" 2>&1 | tail -n "$TAIL_LINES" > "$OUTPUT_FILE"
+    else
+        eval "$CMD" > "$OUTPUT_FILE" 2>&1
+    fi
+
+    # Check if file was created and has content
+    if [[ -s "$OUTPUT_FILE" ]]; then
+        LINE_COUNT=$(wc -l < "$OUTPUT_FILE" | tr -d ' ')
+        echo -e "${GREEN}✓ Exported $LINE_COUNT lines to $OUTPUT_FILE${NC}"
+    else
+        echo -e "${YELLOW}⚠ No logs found matching the criteria${NC}"
+    fi
+else
+    # Run interactively
+    # First check if sudo works without password for the log command
+    if sudo -n /usr/bin/log show --last 1s 2>&1 | grep -q "password"; then
+        handle_sudo_error
+    fi
+
+    if [[ "$SHOW_TAIL" == true ]] && [[ "$STREAM_MODE" == false ]]; then
+        # Apply tail for non-streaming mode
+        eval "$CMD" 2>&1 | tail -n "$TAIL_LINES"
+        echo -e "\n${YELLOW}Showing last $TAIL_LINES lines. Use --all or -n to see more.${NC}"
+    else
+        eval "$CMD"
+    fi
+fi

scripts/clawtributors-map.json

@@ -0,0 +1,39 @@
+{
+  "ensureLogins": [
+    "odrobnik",
+    "alphonse-arianee",
+    "aaronn",
+    "ronak-guliani",
+    "cpojer",
+    "carlulsoe",
+    "jdrhyne",
+    "latitudeki5223",
+    "longmaba",
+    "manmal",
+    "thesash",
+    "rhjoh",
+    "ysqander",
+    "atalovesyou",
+    "0xJonHoldsCrypto",
+    "hougangdev"
+  ],
+  "seedCommit": "d6863f87",
+  "placeholderAvatar": "assets/avatar-placeholder.svg",
+  "displayName": {
+    "jdrhyne": "Jonathan D. Rhyne (DJ-D)"
+  },
+  "nameToLogin": {
+    "peter steinberger": "steipete",
+    "eng. juan combetto": "omniwired",
+    "mariano belinky": "mbelinky",
+    "vasanth rao naik sabavat": "vsabavat",
+    "tu nombre real": "nachx639",
+    "django navarro": "djangonavarro220"
+  },
+  "emailToLogin": {
+    "steipete@gmail.com": "steipete",
+    "sbarrios93@gmail.com": "sebslight",
+    "rltorres26+github@gmail.com": "RandyVentures",
+    "hixvac@gmail.com": "VACInc"
+  }
+}

scripts/codesign-mac-app.sh

@@ -0,0 +1,289 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+APP_BUNDLE="${1:-dist/OpenClaw.app}"
+IDENTITY="${SIGN_IDENTITY:-}"
+TIMESTAMP_MODE="${CODESIGN_TIMESTAMP:-auto}"
+DISABLE_LIBRARY_VALIDATION="${DISABLE_LIBRARY_VALIDATION:-0}"
+SKIP_TEAM_ID_CHECK="${SKIP_TEAM_ID_CHECK:-0}"
+ENT_TMP_BASE=$(mktemp -t openclaw-entitlements-base.XXXXXX)
+ENT_TMP_APP_BASE=$(mktemp -t openclaw-entitlements-app-base.XXXXXX)
+ENT_TMP_RUNTIME=$(mktemp -t openclaw-entitlements-runtime.XXXXXX)
+
+if [[ "${APP_BUNDLE}" == "--help" || "${APP_BUNDLE}" == "-h" ]]; then
+  cat <<'HELP'
+Usage: scripts/codesign-mac-app.sh [app-bundle]
+
+Env:
+  SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"
+  ALLOW_ADHOC_SIGNING=1
+  CODESIGN_TIMESTAMP=auto|on|off
+  DISABLE_LIBRARY_VALIDATION=1      # dev-only Sparkle Team ID workaround
+  SKIP_TEAM_ID_CHECK=1              # bypass Team ID audit
+HELP
+  exit 0
+fi
+
+if [ ! -d "$APP_BUNDLE" ]; then
+  echo "App bundle not found: $APP_BUNDLE" >&2
+  exit 1
+fi
+
+select_identity() {
+  local preferred available first
+
+  # Prefer a Developer ID Application cert.
+  preferred="$(security find-identity -p codesigning -v 2>/dev/null \
+    | awk -F'\"' '/Developer ID Application/ { print $2; exit }')"
+
+  if [ -n "$preferred" ]; then
+    echo "$preferred"
+    return
+  fi
+
+  # Next, try Apple Distribution.
+  preferred="$(security find-identity -p codesigning -v 2>/dev/null \
+    | awk -F'\"' '/Apple Distribution/ { print $2; exit }')"
+  if [ -n "$preferred" ]; then
+    echo "$preferred"
+    return
+  fi
+
+  # Then, try Apple Development.
+  preferred="$(security find-identity -p codesigning -v 2>/dev/null \
+    | awk -F'\"' '/Apple Development/ { print $2; exit }')"
+  if [ -n "$preferred" ]; then
+    echo "$preferred"
+    return
+  fi
+
+  # Fallback to the first valid signing identity.
+  available="$(security find-identity -p codesigning -v 2>/dev/null \
+    | sed -n 's/.*\"\\(.*\\)\"/\\1/p')"
+
+  if [ -n "$available" ]; then
+    first="$(printf '%s\n' "$available" | head -n1)"
+    echo "$first"
+    return
+  fi
+
+  return 1
+}
+
+if [ -z "$IDENTITY" ]; then
+  if ! IDENTITY="$(select_identity)"; then
+    if [[ "${ALLOW_ADHOC_SIGNING:-}" == "1" ]]; then
+      echo "WARN: No signing identity found. Falling back to ad-hoc signing (-)." >&2
+      echo "      !!! WARNING: Ad-hoc signed apps do NOT persist TCC permissions (Accessibility, etc) !!!" >&2
+      echo "      !!! You will need to re-grant permissions every time you restart the app.         !!!" >&2
+      IDENTITY="-"
+    else
+      echo "ERROR: No signing identity found. Set SIGN_IDENTITY to a valid codesigning certificate." >&2
+      echo "       Alternatively, set ALLOW_ADHOC_SIGNING=1 to fallback to ad-hoc signing (limitations apply)." >&2
+      exit 1
+    fi
+  fi
+fi
+
+echo "Using signing identity: $IDENTITY"
+if [[ "$IDENTITY" == "-" ]]; then
+  cat <<'WARN' >&2
+
+================================================================================
+!!! AD-HOC SIGNING IN USE - PERMISSIONS WILL NOT STICK (macOS RESTRICTION) !!!
+
+macOS ties permissions to the code signature, bundle ID, and app path.
+Ad-hoc signing generates a new signature every build, so macOS treats the app
+as a different binary and will forget permissions (prompts may vanish).
+
+For correct permission behavior you MUST sign with a real Apple Development or
+Developer ID certificate.
+
+If prompts disappear: remove the app entry in System Settings -> Privacy & Security,
+relaunch the app, and re-grant. Some permissions only reappear after a full
+macOS restart.
+================================================================================
+
+WARN
+fi
+
+timestamp_arg="--timestamp=none"
+case "$TIMESTAMP_MODE" in
+  1|on|yes|true)
+    timestamp_arg="--timestamp"
+    ;;
+  0|off|no|false)
+    timestamp_arg="--timestamp=none"
+    ;;
+  auto)
+    if [[ "$IDENTITY" == *"Developer ID Application"* ]]; then
+      timestamp_arg="--timestamp"
+    fi
+    ;;
+  *)
+    echo "ERROR: Unknown CODESIGN_TIMESTAMP value: $TIMESTAMP_MODE (use auto|on|off)" >&2
+    exit 1
+    ;;
+esac
+if [[ "$IDENTITY" == "-" ]]; then
+  timestamp_arg="--timestamp=none"
+fi
+
+options_args=()
+if [[ "$IDENTITY" != "-" ]]; then
+  options_args=("--options" "runtime")
+fi
+timestamp_args=("$timestamp_arg")
+
+cat > "$ENT_TMP_BASE" <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.automation.apple-events</key>
+    <true/>
+    <key>com.apple.security.device.audio-input</key>
+    <true/>
+    <key>com.apple.security.device.camera</key>
+    <true/>
+</dict>
+</plist>
+PLIST
+
+cat > "$ENT_TMP_APP_BASE" <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.automation.apple-events</key>
+    <true/>
+    <key>com.apple.security.device.audio-input</key>
+    <true/>
+    <key>com.apple.security.device.camera</key>
+    <true/>
+    <key>com.apple.security.personal-information.location</key>
+    <true/>
+</dict>
+</plist>
+PLIST
+
+cat > "$ENT_TMP_RUNTIME" <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.cs.allow-jit</key>
+    <true/>
+    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+    <true/>
+</dict>
+</plist>
+PLIST
+
+if [[ "$DISABLE_LIBRARY_VALIDATION" == "1" ]]; then
+  /usr/libexec/PlistBuddy -c "Add :com.apple.security.cs.disable-library-validation bool true" "$ENT_TMP_APP_BASE" >/dev/null 2>&1 || \
+    /usr/libexec/PlistBuddy -c "Set :com.apple.security.cs.disable-library-validation true" "$ENT_TMP_APP_BASE"
+  echo "Note: disable-library-validation entitlement enabled (DISABLE_LIBRARY_VALIDATION=1)."
+fi
+
+APP_ENTITLEMENTS="$ENT_TMP_APP_BASE"
+
+# clear extended attributes to avoid stale signatures
+xattr -cr "$APP_BUNDLE" 2>/dev/null || true
+
+sign_item() {
+  local target="$1"
+  local entitlements="$2"
+  codesign --force ${options_args+"${options_args[@]}"} "${timestamp_args[@]}" --entitlements "$entitlements" --sign "$IDENTITY" "$target"
+}
+
+sign_plain_item() {
+  local target="$1"
+  codesign --force ${options_args+"${options_args[@]}"} "${timestamp_args[@]}" --sign "$IDENTITY" "$target"
+}
+
+team_id_for() {
+  codesign -dv --verbose=4 "$1" 2>&1 | awk -F= '/^TeamIdentifier=/{print $2; exit}'
+}
+
+verify_team_ids() {
+  if [[ "$SKIP_TEAM_ID_CHECK" == "1" ]]; then
+    echo "Note: skipping Team ID audit (SKIP_TEAM_ID_CHECK=1)."
+    return 0
+  fi
+
+  local expected
+  expected="$(team_id_for "$APP_BUNDLE" || true)"
+  if [[ -z "$expected" ]]; then
+    echo "WARN: TeamIdentifier missing on app bundle; skipping Team ID audit."
+    return 0
+  fi
+
+  local mismatches=()
+  while IFS= read -r -d '' f; do
+    if /usr/bin/file "$f" | /usr/bin/grep -q "Mach-O"; then
+      local team
+      team="$(team_id_for "$f" || true)"
+      if [[ -z "$team" ]]; then
+        team="not set"
+      fi
+      if [[ "$expected" == "not set" ]]; then
+        if [[ "$team" != "not set" ]]; then
+          mismatches+=("$f (TeamIdentifier=$team)")
+        fi
+      elif [[ "$team" != "$expected" ]]; then
+        mismatches+=("$f (TeamIdentifier=$team)")
+      fi
+    fi
+  done < <(find "$APP_BUNDLE" -type f -print0)
+
+  if [[ "${#mismatches[@]}" -gt 0 ]]; then
+    echo "ERROR: Team ID mismatch detected (expected: $expected)"
+    for entry in "${mismatches[@]}"; do
+      echo " - $entry"
+    done
+    echo "Hint: re-sign embedded frameworks or set DISABLE_LIBRARY_VALIDATION=1 for dev builds."
+    exit 1
+  fi
+}
+
+# Sign main binary
+if [ -f "$APP_BUNDLE/Contents/MacOS/OpenClaw" ]; then
+  echo "Signing main binary"; sign_item "$APP_BUNDLE/Contents/MacOS/OpenClaw" "$APP_ENTITLEMENTS"
+fi
+
+# Sign Sparkle deeply if present
+SPARKLE="$APP_BUNDLE/Contents/Frameworks/Sparkle.framework"
+if [ -d "$SPARKLE" ]; then
+  echo "Signing Sparkle framework and helpers"
+  find "$SPARKLE" -type f -print0 | while IFS= read -r -d '' f; do
+    if /usr/bin/file "$f" | /usr/bin/grep -q "Mach-O"; then
+      sign_plain_item "$f"
+    fi
+  done
+  sign_plain_item "$SPARKLE/Versions/B/Sparkle"
+  sign_plain_item "$SPARKLE/Versions/B/Autoupdate"
+  sign_plain_item "$SPARKLE/Versions/B/Updater.app/Contents/MacOS/Updater"
+  sign_plain_item "$SPARKLE/Versions/B/Updater.app"
+  sign_plain_item "$SPARKLE/Versions/B/XPCServices/Downloader.xpc/Contents/MacOS/Downloader"
+  sign_plain_item "$SPARKLE/Versions/B/XPCServices/Downloader.xpc"
+  sign_plain_item "$SPARKLE/Versions/B/XPCServices/Installer.xpc/Contents/MacOS/Installer"
+  sign_plain_item "$SPARKLE/Versions/B/XPCServices/Installer.xpc"
+  sign_plain_item "$SPARKLE/Versions/B"
+  sign_plain_item "$SPARKLE"
+fi
+
+# Sign any other embedded frameworks/dylibs
+if [ -d "$APP_BUNDLE/Contents/Frameworks" ]; then
+  find "$APP_BUNDLE/Contents/Frameworks" \( -name "*.framework" -o -name "*.dylib" \) ! -path "*Sparkle.framework*" -print0 | while IFS= read -r -d '' f; do
+    echo "Signing framework: $f"; sign_plain_item "$f"
+  done
+fi
+
+# Finally sign the bundle
+sign_item "$APP_BUNDLE" "$APP_ENTITLEMENTS"
+
+verify_team_ids
+
+rm -f "$ENT_TMP_BASE" "$ENT_TMP_APP_BASE" "$ENT_TMP_RUNTIME"
+echo "Codesign complete for $APP_BUNDLE"

scripts/committer

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+# Disable glob expansion to handle brackets in file paths
+set -f
+usage() {
+  printf 'Usage: %s [--force] "commit message" "file" ["file" ...]\n' "$(basename "$0")" >&2
+  exit 2
+}
+
+if [ "$#" -lt 2 ]; then
+  usage
+fi
+
+force_delete_lock=false
+if [ "${1:-}" = "--force" ]; then
+  force_delete_lock=true
+  shift
+fi
+
+if [ "$#" -lt 2 ]; then
+  usage
+fi
+
+commit_message=$1
+shift
+
+if [[ "$commit_message" != *[![:space:]]* ]]; then
+  printf 'Error: commit message must not be empty\n' >&2
+  exit 1
+fi
+
+if [ -e "$commit_message" ]; then
+  printf 'Error: first argument looks like a file path ("%s"); provide the commit message first\n' "$commit_message" >&2
+  exit 1
+fi
+
+if [ "$#" -eq 0 ]; then
+  usage
+fi
+
+files=("$@")
+
+# Disallow "." because it stages the entire repository and defeats the helper's safety guardrails.
+for file in "${files[@]}"; do
+  if [ "$file" = "." ]; then
+    printf 'Error: "." is not allowed; list specific paths instead\n' >&2
+    exit 1
+  fi
+done
+
+# Prevent staging node_modules even if a path is forced.
+for file in "${files[@]}"; do
+  case "$file" in
+    *node_modules* | */node_modules | */node_modules/* | node_modules)
+      printf 'Error: node_modules paths are not allowed: %s\n' "$file" >&2
+      exit 1
+      ;;
+  esac
+done
+
+last_commit_error=''
+
+run_git_commit() {
+  local stderr_log
+  stderr_log=$(mktemp)
+  if git commit -m "$commit_message" -- "${files[@]}" 2> >(tee "$stderr_log" >&2); then
+    rm -f "$stderr_log"
+    last_commit_error=''
+    return 0
+  fi
+
+  last_commit_error=$(cat "$stderr_log")
+  rm -f "$stderr_log"
+  return 1
+}
+
+for file in "${files[@]}"; do
+  if [ ! -e "$file" ]; then
+    if ! git ls-files --error-unmatch -- "$file" >/dev/null 2>&1; then
+      printf 'Error: file not found: %s\n' "$file" >&2
+      exit 1
+    fi
+  fi
+done
+
+git restore --staged :/
+git add --force -- "${files[@]}"
+
+if git diff --staged --quiet; then
+  printf 'Warning: no staged changes detected for: %s\n' "${files[*]}" >&2
+  exit 1
+fi
+
+committed=false
+if run_git_commit; then
+  committed=true
+elif [ "$force_delete_lock" = true ]; then
+  lock_path=$(
+    printf '%s\n' "$last_commit_error" |
+      awk -F"'" '/Unable to create .*\.git\/index\.lock/ { print $2; exit }'
+  )
+
+  if [ -n "$lock_path" ] && [ -e "$lock_path" ]; then
+    rm -f "$lock_path"
+    printf 'Removed stale git lock: %s\n' "$lock_path" >&2
+    if run_git_commit; then
+      committed=true
+    fi
+  fi
+fi
+
+if [ "$committed" = false ]; then
+  exit 1
+fi
+
+printf 'Committed "%s" with %d files\n' "$commit_message" "${#files[@]}"

scripts/copy-hook-metadata.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env tsx
+/**
+ * Copy HOOK.md files from src/hooks/bundled to dist/hooks/bundled
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, "..");
+
+const srcBundled = path.join(projectRoot, "src", "hooks", "bundled");
+const distBundled = path.join(projectRoot, "dist", "hooks", "bundled");
+
+function copyHookMetadata() {
+  if (!fs.existsSync(srcBundled)) {
+    console.warn("[copy-hook-metadata] Source directory not found:", srcBundled);
+    return;
+  }
+
+  if (!fs.existsSync(distBundled)) {
+    fs.mkdirSync(distBundled, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(srcBundled, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const hookName = entry.name;
+    const srcHookDir = path.join(srcBundled, hookName);
+    const distHookDir = path.join(distBundled, hookName);
+    const srcHookMd = path.join(srcHookDir, "HOOK.md");
+    const distHookMd = path.join(distHookDir, "HOOK.md");
+
+    if (!fs.existsSync(srcHookMd)) {
+      console.warn(`[copy-hook-metadata] No HOOK.md found for ${hookName}`);
+      continue;
+    }
+
+    if (!fs.existsSync(distHookDir)) {
+      fs.mkdirSync(distHookDir, { recursive: true });
+    }
+
+    fs.copyFileSync(srcHookMd, distHookMd);
+    console.log(`[copy-hook-metadata] Copied ${hookName}/HOOK.md`);
+  }
+
+  console.log("[copy-hook-metadata] Done");
+}
+
+copyHookMetadata();

scripts/create-dmg.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Create a styled DMG containing the app bundle + /Applications symlink.
+#
+# Usage:
+#   scripts/create-dmg.sh <app_path> [output_dmg]
+#
+# Env:
+#   DMG_VOLUME_NAME        default: CFBundleName (or "OpenClaw")
+#   DMG_BACKGROUND_PATH    default: assets/dmg-background.png
+#   DMG_BACKGROUND_SMALL   default: assets/dmg-background-small.png (recommended)
+#   DMG_WINDOW_BOUNDS      default: "400 100 900 420" (500x320)
+#   DMG_ICON_SIZE          default: 128
+#   DMG_APP_POS            default: "125 160"
+#   DMG_APPS_POS           default: "375 160"
+#   SKIP_DMG_STYLE=1       skip Finder styling
+#   DMG_EXTRA_SECTORS      extra sectors to keep when shrinking RW image (default: 2048)
+
+APP_PATH="${1:-}"
+OUT_PATH="${2:-}"
+
+if [[ -z "$APP_PATH" ]]; then
+  echo "Usage: $0 <app_path> [output_dmg]" >&2
+  exit 1
+fi
+if [[ ! -d "$APP_PATH" ]]; then
+  echo "Error: App not found: $APP_PATH" >&2
+  exit 1
+fi
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+BUILD_DIR="$ROOT_DIR/dist"
+mkdir -p "$BUILD_DIR"
+
+APP_NAME=$(/usr/libexec/PlistBuddy -c "Print CFBundleName" "$APP_PATH/Contents/Info.plist" 2>/dev/null || echo "OpenClaw")
+VERSION=$(/usr/libexec/PlistBuddy -c "Print CFBundleShortVersionString" "$APP_PATH/Contents/Info.plist" 2>/dev/null || echo "0.0.0")
+
+DMG_NAME="${APP_NAME}-${VERSION}.dmg"
+DMG_VOLUME_NAME="${DMG_VOLUME_NAME:-$APP_NAME}"
+DMG_BACKGROUND_SMALL="${DMG_BACKGROUND_SMALL:-$ROOT_DIR/assets/dmg-background-small.png}"
+DMG_BACKGROUND_PATH="${DMG_BACKGROUND_PATH:-$ROOT_DIR/assets/dmg-background.png}"
+
+DMG_WINDOW_BOUNDS="${DMG_WINDOW_BOUNDS:-400 100 900 420}"
+DMG_ICON_SIZE="${DMG_ICON_SIZE:-128}"
+DMG_APP_POS="${DMG_APP_POS:-125 160}"
+DMG_APPS_POS="${DMG_APPS_POS:-375 160}"
+DMG_EXTRA_SECTORS="${DMG_EXTRA_SECTORS:-2048}"
+
+to_applescript_list4() {
+  local raw="$1"
+  echo "$raw" | awk '{ printf "%s, %s, %s, %s", $1, $2, $3, $4 }'
+}
+
+to_applescript_pair() {
+  local raw="$1"
+  echo "$raw" | awk '{ printf "%s, %s", $1, $2 }'
+}
+
+if [[ -z "$OUT_PATH" ]]; then
+  OUT_PATH="$BUILD_DIR/$DMG_NAME"
+fi
+
+echo "Creating DMG: $OUT_PATH"
+
+# Cleanup stuck volumes.
+for vol in "/Volumes/$DMG_VOLUME_NAME"* "/Volumes/$APP_NAME"*; do
+  if [[ -d "$vol" ]]; then
+    hdiutil detach "$vol" -force 2>/dev/null || true
+    sleep 1
+  fi
+done
+
+DMG_TEMP="$(mktemp -d /tmp/openclaw-dmg.XXXXXX)"
+trap 'hdiutil detach "/Volumes/'"$DMG_VOLUME_NAME"'" -force 2>/dev/null || true; rm -rf "$DMG_TEMP" 2>/dev/null || true' EXIT
+
+cp -R "$APP_PATH" "$DMG_TEMP/"
+ln -s /Applications "$DMG_TEMP/Applications"
+
+APP_SIZE_MB=$(du -sm "$APP_PATH" | awk '{print $1}')
+DMG_SIZE_MB=$((APP_SIZE_MB + 80))
+
+DMG_RW_PATH="${OUT_PATH%.dmg}-rw.dmg"
+rm -f "$DMG_RW_PATH" "$OUT_PATH"
+
+hdiutil create \
+  -volname "$DMG_VOLUME_NAME" \
+  -srcfolder "$DMG_TEMP" \
+  -ov \
+  -format UDRW \
+  -size "${DMG_SIZE_MB}m" \
+  "$DMG_RW_PATH"
+
+MOUNT_POINT="/Volumes/$DMG_VOLUME_NAME"
+if [[ -d "$MOUNT_POINT" ]]; then
+  hdiutil detach "$MOUNT_POINT" -force 2>/dev/null || true
+  sleep 2
+fi
+hdiutil attach "$DMG_RW_PATH" -mountpoint "$MOUNT_POINT" -nobrowse
+
+if [[ "${SKIP_DMG_STYLE:-0}" != "1" ]]; then
+  mkdir -p "$MOUNT_POINT/.background"
+  if [[ -f "$DMG_BACKGROUND_SMALL" ]]; then
+    cp "$DMG_BACKGROUND_SMALL" "$MOUNT_POINT/.background/background.png"
+  elif [[ -f "$DMG_BACKGROUND_PATH" ]]; then
+    cp "$DMG_BACKGROUND_PATH" "$MOUNT_POINT/.background/background.png"
+  else
+    echo "WARN: DMG background missing: $DMG_BACKGROUND_SMALL / $DMG_BACKGROUND_PATH" >&2
+  fi
+
+  # Volume icon: reuse the app icon if available.
+  ICON_SRC="$ROOT_DIR/apps/macos/Sources/OpenClaw/Resources/OpenClaw.icns"
+  if [[ -f "$ICON_SRC" ]]; then
+    cp "$ICON_SRC" "$MOUNT_POINT/.VolumeIcon.icns"
+    if command -v SetFile >/dev/null 2>&1; then
+      SetFile -a C "$MOUNT_POINT" 2>/dev/null || true
+    fi
+  fi
+
+  osascript <<EOF
+tell application "Finder"
+  tell disk "$DMG_VOLUME_NAME"
+    open
+    set current view of container window to icon view
+    set toolbar visible of container window to false
+    set statusbar visible of container window to false
+    set the bounds of container window to {$(to_applescript_list4 "$DMG_WINDOW_BOUNDS")}
+    set viewOptions to the icon view options of container window
+    set arrangement of viewOptions to not arranged
+    set icon size of viewOptions to ${DMG_ICON_SIZE}
+    if exists file ".background:background.png" then
+      set background picture of viewOptions to file ".background:background.png"
+    end if
+    set text size of viewOptions to 12
+    set label position of viewOptions to bottom
+    set shows item info of viewOptions to false
+    set shows icon preview of viewOptions to true
+    set position of item "${APP_NAME}.app" of container window to {$(to_applescript_pair "$DMG_APP_POS")}
+    set position of item "Applications" of container window to {$(to_applescript_pair "$DMG_APPS_POS")}
+    update without registering applications
+    delay 2
+    close
+    open
+    delay 1
+  end tell
+end tell
+EOF
+
+  sleep 2
+  osascript -e 'tell application "Finder" to close every window' || true
+fi
+
+for i in {1..5}; do
+  if hdiutil detach "$MOUNT_POINT" -quiet 2>/dev/null; then
+    break
+  fi
+  if [[ "$i" == "3" ]]; then
+    hdiutil detach "$MOUNT_POINT" -force 2>/dev/null || true
+  fi
+  sleep 2
+done
+
+hdiutil resize -limits "$DMG_RW_PATH" >/tmp/openclaw-dmg-limits.txt 2>/dev/null || true
+MIN_SECTORS="$(tail -n 1 /tmp/openclaw-dmg-limits.txt 2>/dev/null | awk '{print $1}')"
+rm -f /tmp/openclaw-dmg-limits.txt
+if [[ "$MIN_SECTORS" =~ ^[0-9]+$ ]] && [[ "$DMG_EXTRA_SECTORS" =~ ^[0-9]+$ ]]; then
+  TARGET_SECTORS=$((MIN_SECTORS + DMG_EXTRA_SECTORS))
+  echo "Shrinking RW image: min sectors=$MIN_SECTORS (+$DMG_EXTRA_SECTORS) -> $TARGET_SECTORS"
+  hdiutil resize -sectors "$TARGET_SECTORS" "$DMG_RW_PATH" >/dev/null 2>&1 || true
+fi
+
+hdiutil convert "$DMG_RW_PATH" -format ULMO -o "$OUT_PATH" -ov
+rm -f "$DMG_RW_PATH"
+
+hdiutil verify "$OUT_PATH" >/dev/null
+echo "✅ DMG ready: $OUT_PATH"

scripts/debug-claude-usage.ts

@@ -0,0 +1,391 @@
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+type Args = {
+  agentId: string;
+  reveal: boolean;
+  sessionKey?: string;
+};
+
+const mask = (value: string) => {
+  const compact = value.trim();
+  if (!compact) {
+    return "missing";
+  }
+  const edge = compact.length >= 12 ? 6 : 4;
+  return `${compact.slice(0, edge)}…${compact.slice(-edge)}`;
+};
+
+const parseArgs = (): Args => {
+  const args = process.argv.slice(2);
+  let agentId = "main";
+  let reveal = false;
+  let sessionKey: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--agent" && args[i + 1]) {
+      agentId = String(args[++i]).trim() || "main";
+      continue;
+    }
+    if (arg === "--reveal") {
+      reveal = true;
+      continue;
+    }
+    if (arg === "--session-key" && args[i + 1]) {
+      sessionKey = String(args[++i]).trim() || undefined;
+      continue;
+    }
+  }
+
+  return { agentId, reveal, sessionKey };
+};
+
+const loadAuthProfiles = (agentId: string) => {
+  const stateRoot =
+    process.env.OPENCLAW_STATE_DIR?.trim() ||
+    process.env.CLAWDBOT_STATE_DIR?.trim() ||
+    path.join(os.homedir(), ".openclaw");
+  const authPath = path.join(stateRoot, "agents", agentId, "agent", "auth-profiles.json");
+  if (!fs.existsSync(authPath)) {
+    throw new Error(`Missing: ${authPath}`);
+  }
+  const store = JSON.parse(fs.readFileSync(authPath, "utf8")) as {
+    profiles?: Record<string, { provider?: string; type?: string; token?: string; key?: string }>;
+  };
+  return { authPath, store };
+};
+
+const pickAnthropicTokens = (store: {
+  profiles?: Record<string, { provider?: string; type?: string; token?: string; key?: string }>;
+}): Array<{ profileId: string; token: string }> => {
+  const profiles = store.profiles ?? {};
+  const found: Array<{ profileId: string; token: string }> = [];
+  for (const [id, cred] of Object.entries(profiles)) {
+    if (cred?.provider !== "anthropic") {
+      continue;
+    }
+    const token = cred.type === "token" ? cred.token?.trim() : undefined;
+    if (token) {
+      found.push({ profileId: id, token });
+    }
+  }
+  return found;
+};
+
+const fetchAnthropicOAuthUsage = async (token: string) => {
+  const res = await fetch("https://api.anthropic.com/api/oauth/usage", {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json",
+      "anthropic-version": "2023-06-01",
+      "anthropic-beta": "oauth-2025-04-20",
+      "User-Agent": "openclaw-debug",
+    },
+  });
+  const text = await res.text();
+  return { status: res.status, contentType: res.headers.get("content-type"), text };
+};
+
+const readClaudeCliKeychain = (): {
+  accessToken: string;
+  expiresAt?: number;
+  scopes?: string[];
+} | null => {
+  if (process.platform !== "darwin") {
+    return null;
+  }
+  try {
+    const raw = execFileSync(
+      "security",
+      ["find-generic-password", "-s", "Claude Code-credentials", "-w"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 },
+    );
+    const parsed = JSON.parse(raw.trim()) as Record<string, unknown>;
+    const oauth = parsed?.claudeAiOauth as Record<string, unknown> | undefined;
+    if (!oauth || typeof oauth !== "object") {
+      return null;
+    }
+    const accessToken = oauth.accessToken;
+    if (typeof accessToken !== "string" || !accessToken.trim()) {
+      return null;
+    }
+    const expiresAt = typeof oauth.expiresAt === "number" ? oauth.expiresAt : undefined;
+    const scopes = Array.isArray(oauth.scopes)
+      ? oauth.scopes.filter((v): v is string => typeof v === "string")
+      : undefined;
+    return { accessToken, expiresAt, scopes };
+  } catch {
+    return null;
+  }
+};
+
+const chromeServiceNameForPath = (cookiePath: string): string => {
+  if (cookiePath.includes("/Arc/")) {
+    return "Arc Safe Storage";
+  }
+  if (cookiePath.includes("/BraveSoftware/")) {
+    return "Brave Safe Storage";
+  }
+  if (cookiePath.includes("/Microsoft Edge/")) {
+    return "Microsoft Edge Safe Storage";
+  }
+  if (cookiePath.includes("/Chromium/")) {
+    return "Chromium Safe Storage";
+  }
+  return "Chrome Safe Storage";
+};
+
+const readKeychainPassword = (service: string): string | null => {
+  try {
+    const out = execFileSync("security", ["find-generic-password", "-w", "-s", service], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    });
+    const pw = out.trim();
+    return pw ? pw : null;
+  } catch {
+    return null;
+  }
+};
+
+const decryptChromeCookieValue = (encrypted: Buffer, service: string): string | null => {
+  if (encrypted.length < 4) {
+    return null;
+  }
+  const prefix = encrypted.subarray(0, 3).toString("utf8");
+  if (prefix !== "v10" && prefix !== "v11") {
+    return null;
+  }
+
+  const password = readKeychainPassword(service);
+  if (!password) {
+    return null;
+  }
+
+  const key = crypto.pbkdf2Sync(password, "saltysalt", 1003, 16, "sha1");
+  const iv = Buffer.alloc(16, 0x20);
+  const data = encrypted.subarray(3);
+
+  try {
+    const decipher = crypto.createDecipheriv("aes-128-cbc", key, iv);
+    decipher.setAutoPadding(true);
+    const decrypted = Buffer.concat([decipher.update(data), decipher.final()]);
+    const text = decrypted.toString("utf8").trim();
+    return text ? text : null;
+  } catch {
+    return null;
+  }
+};
+
+const queryChromeCookieDb = (cookieDb: string): string | null => {
+  try {
+    const out = execFileSync(
+      "sqlite3",
+      [
+        "-readonly",
+        cookieDb,
+        `
+          SELECT
+            COALESCE(NULLIF(value,''), hex(encrypted_value))
+          FROM cookies
+          WHERE (host_key LIKE '%claude.ai%' OR host_key = '.claude.ai')
+            AND name = 'sessionKey'
+          LIMIT 1;
+        `,
+      ],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 },
+    ).trim();
+    if (!out) {
+      return null;
+    }
+    if (out.startsWith("sk-ant-")) {
+      return out;
+    }
+    const hex = out.replace(/[^0-9A-Fa-f]/g, "");
+    if (!hex) {
+      return null;
+    }
+    const buf = Buffer.from(hex, "hex");
+    const service = chromeServiceNameForPath(cookieDb);
+    const decrypted = decryptChromeCookieValue(buf, service);
+    return decrypted && decrypted.startsWith("sk-ant-") ? decrypted : null;
+  } catch {
+    return null;
+  }
+};
+
+const queryFirefoxCookieDb = (cookieDb: string): string | null => {
+  try {
+    const out = execFileSync(
+      "sqlite3",
+      [
+        "-readonly",
+        cookieDb,
+        `
+          SELECT value
+          FROM moz_cookies
+          WHERE (host LIKE '%claude.ai%' OR host = '.claude.ai')
+            AND name = 'sessionKey'
+          LIMIT 1;
+        `,
+      ],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 },
+    ).trim();
+    return out && out.startsWith("sk-ant-") ? out : null;
+  } catch {
+    return null;
+  }
+};
+
+const findClaudeSessionKey = (): { sessionKey: string; source: string } | null => {
+  if (process.platform !== "darwin") {
+    return null;
+  }
+
+  const firefoxRoot = path.join(
+    os.homedir(),
+    "Library",
+    "Application Support",
+    "Firefox",
+    "Profiles",
+  );
+  if (fs.existsSync(firefoxRoot)) {
+    for (const entry of fs.readdirSync(firefoxRoot)) {
+      const db = path.join(firefoxRoot, entry, "cookies.sqlite");
+      if (!fs.existsSync(db)) {
+        continue;
+      }
+      const value = queryFirefoxCookieDb(db);
+      if (value) {
+        return { sessionKey: value, source: `firefox:${db}` };
+      }
+    }
+  }
+
+  const chromeCandidates = [
+    path.join(os.homedir(), "Library", "Application Support", "Google", "Chrome"),
+    path.join(os.homedir(), "Library", "Application Support", "Chromium"),
+    path.join(os.homedir(), "Library", "Application Support", "Arc"),
+    path.join(os.homedir(), "Library", "Application Support", "BraveSoftware", "Brave-Browser"),
+    path.join(os.homedir(), "Library", "Application Support", "Microsoft Edge"),
+  ];
+
+  for (const root of chromeCandidates) {
+    if (!fs.existsSync(root)) {
+      continue;
+    }
+    const profiles = fs
+      .readdirSync(root)
+      .filter((name) => name === "Default" || name.startsWith("Profile "));
+    for (const profile of profiles) {
+      const db = path.join(root, profile, "Cookies");
+      if (!fs.existsSync(db)) {
+        continue;
+      }
+      const value = queryChromeCookieDb(db);
+      if (value) {
+        return { sessionKey: value, source: `chromium:${db}` };
+      }
+    }
+  }
+
+  return null;
+};
+
+const fetchClaudeWebUsage = async (sessionKey: string) => {
+  const headers = {
+    Cookie: `sessionKey=${sessionKey}`,
+    Accept: "application/json",
+    "User-Agent":
+      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1 Safari/605.1.15",
+  };
+  const orgRes = await fetch("https://claude.ai/api/organizations", { headers });
+  const orgText = await orgRes.text();
+  if (!orgRes.ok) {
+    return { ok: false as const, step: "organizations", status: orgRes.status, body: orgText };
+  }
+  const orgs = JSON.parse(orgText) as Array<{ uuid?: string }>;
+  const orgId = orgs?.[0]?.uuid;
+  if (!orgId) {
+    return { ok: false as const, step: "organizations", status: 200, body: orgText };
+  }
+
+  const usageRes = await fetch(`https://claude.ai/api/organizations/${orgId}/usage`, { headers });
+  const usageText = await usageRes.text();
+  return usageRes.ok
+    ? { ok: true as const, orgId, body: usageText }
+    : { ok: false as const, step: "usage", status: usageRes.status, body: usageText };
+};
+
+const main = async () => {
+  const opts = parseArgs();
+  const { authPath, store } = loadAuthProfiles(opts.agentId);
+  console.log(`Auth file: ${authPath}`);
+
+  const keychain = readClaudeCliKeychain();
+  if (keychain) {
+    console.log(
+      `Claude Code CLI keychain: accessToken=${opts.reveal ? keychain.accessToken : mask(keychain.accessToken)} scopes=${keychain.scopes?.join(",") ?? "(unknown)"}`,
+    );
+    const oauth = await fetchAnthropicOAuthUsage(keychain.accessToken);
+    console.log(
+      `OAuth usage (keychain): HTTP ${oauth.status} (${oauth.contentType ?? "no content-type"})`,
+    );
+    console.log(oauth.text.slice(0, 200).replace(/\s+/g, " ").trim());
+  } else {
+    console.log("Claude Code CLI keychain: missing/unreadable");
+  }
+
+  const anthropic = pickAnthropicTokens(store);
+  if (anthropic.length === 0) {
+    console.log("Auth profiles: no Anthropic token profiles found");
+  } else {
+    for (const entry of anthropic) {
+      console.log(
+        `Auth profiles: ${entry.profileId} token=${opts.reveal ? entry.token : mask(entry.token)}`,
+      );
+      const oauth = await fetchAnthropicOAuthUsage(entry.token);
+      console.log(
+        `OAuth usage (${entry.profileId}): HTTP ${oauth.status} (${oauth.contentType ?? "no content-type"})`,
+      );
+      console.log(oauth.text.slice(0, 200).replace(/\s+/g, " ").trim());
+    }
+  }
+
+  const sessionKey =
+    opts.sessionKey?.trim() ||
+    process.env.CLAUDE_AI_SESSION_KEY?.trim() ||
+    process.env.CLAUDE_WEB_SESSION_KEY?.trim() ||
+    findClaudeSessionKey()?.sessionKey;
+  const source = opts.sessionKey
+    ? "--session-key"
+    : process.env.CLAUDE_AI_SESSION_KEY || process.env.CLAUDE_WEB_SESSION_KEY
+      ? "env"
+      : (findClaudeSessionKey()?.source ?? "auto");
+
+  if (!sessionKey) {
+    console.log(
+      "Claude web: no sessionKey found (try --session-key or export CLAUDE_AI_SESSION_KEY)",
+    );
+    return;
+  }
+
+  console.log(
+    `Claude web: sessionKey=${opts.reveal ? sessionKey : mask(sessionKey)} (source: ${source})`,
+  );
+  const web = await fetchClaudeWebUsage(sessionKey);
+  if (!web.ok) {
+    console.log(`Claude web: ${web.step} HTTP ${web.status}`);
+    console.log(String(web.body).slice(0, 400).replace(/\s+/g, " ").trim());
+    return;
+  }
+  console.log(`Claude web: org=${web.orgId} OK`);
+  console.log(web.body.slice(0, 400).replace(/\s+/g, " ").trim());
+};
+
+await main();

scripts/docker/cleanup-smoke/Dockerfile

@@ -0,0 +1,20 @@
+FROM node:22-bookworm-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    bash \
+    ca-certificates \
+    git \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /repo
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY scripts/postinstall.js ./scripts/postinstall.js
+RUN corepack enable \
+  && pnpm install --frozen-lockfile
+
+COPY . .
+COPY scripts/docker/cleanup-smoke/run.sh /usr/local/bin/openclaw-cleanup-smoke
+RUN chmod +x /usr/local/bin/openclaw-cleanup-smoke
+
+ENTRYPOINT ["/usr/local/bin/openclaw-cleanup-smoke"]

scripts/docker/cleanup-smoke/run.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd /repo
+
+export OPENCLAW_STATE_DIR="/tmp/openclaw-test"
+export OPENCLAW_CONFIG_PATH="${OPENCLAW_STATE_DIR}/openclaw.json"
+
+echo "==> Seed state"
+mkdir -p "${OPENCLAW_STATE_DIR}/credentials"
+mkdir -p "${OPENCLAW_STATE_DIR}/agents/main/sessions"
+echo '{}' >"${OPENCLAW_CONFIG_PATH}"
+echo 'creds' >"${OPENCLAW_STATE_DIR}/credentials/marker.txt"
+echo 'session' >"${OPENCLAW_STATE_DIR}/agents/main/sessions/sessions.json"
+
+echo "==> Reset (config+creds+sessions)"
+pnpm openclaw reset --scope config+creds+sessions --yes --non-interactive
+
+test ! -f "${OPENCLAW_CONFIG_PATH}"
+test ! -d "${OPENCLAW_STATE_DIR}/credentials"
+test ! -d "${OPENCLAW_STATE_DIR}/agents/main/sessions"
+
+echo "==> Recreate minimal config"
+mkdir -p "${OPENCLAW_STATE_DIR}/credentials"
+echo '{}' >"${OPENCLAW_CONFIG_PATH}"
+
+echo "==> Uninstall (state only)"
+pnpm openclaw uninstall --state --yes --non-interactive
+
+test ! -d "${OPENCLAW_STATE_DIR}"
+
+echo "OK"

scripts/docker/install-sh-e2e/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:22-bookworm-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    bash \
+    ca-certificates \
+    curl \
+    git \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY run.sh /usr/local/bin/openclaw-install-e2e
+RUN chmod +x /usr/local/bin/openclaw-install-e2e
+
+ENTRYPOINT ["/usr/local/bin/openclaw-install-e2e"]

scripts/docker/install-sh-e2e/run.sh

@@ -0,0 +1,531 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+INSTALL_URL="${OPENCLAW_INSTALL_URL:-${CLAWDBOT_INSTALL_URL:-https://openclaw.bot/install.sh}}"
+MODELS_MODE="${OPENCLAW_E2E_MODELS:-${CLAWDBOT_E2E_MODELS:-both}}" # both|openai|anthropic
+INSTALL_TAG="${OPENCLAW_INSTALL_TAG:-${CLAWDBOT_INSTALL_TAG:-latest}}"
+E2E_PREVIOUS_VERSION="${OPENCLAW_INSTALL_E2E_PREVIOUS:-${CLAWDBOT_INSTALL_E2E_PREVIOUS:-}}"
+SKIP_PREVIOUS="${OPENCLAW_INSTALL_E2E_SKIP_PREVIOUS:-${CLAWDBOT_INSTALL_E2E_SKIP_PREVIOUS:-0}}"
+OPENAI_API_KEY="${OPENAI_API_KEY:-}"
+ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-}"
+ANTHROPIC_API_TOKEN="${ANTHROPIC_API_TOKEN:-}"
+
+if [[ "$MODELS_MODE" != "both" && "$MODELS_MODE" != "openai" && "$MODELS_MODE" != "anthropic" ]]; then
+  echo "ERROR: OPENCLAW_E2E_MODELS must be one of: both|openai|anthropic" >&2
+  exit 2
+fi
+
+if [[ "$MODELS_MODE" == "both" ]]; then
+  if [[ -z "$OPENAI_API_KEY" ]]; then
+    echo "ERROR: OPENCLAW_E2E_MODELS=both requires OPENAI_API_KEY." >&2
+    exit 2
+  fi
+  if [[ -z "$ANTHROPIC_API_TOKEN" && -z "$ANTHROPIC_API_KEY" ]]; then
+    echo "ERROR: OPENCLAW_E2E_MODELS=both requires ANTHROPIC_API_TOKEN or ANTHROPIC_API_KEY." >&2
+    exit 2
+  fi
+elif [[ "$MODELS_MODE" == "openai" && -z "$OPENAI_API_KEY" ]]; then
+  echo "ERROR: OPENCLAW_E2E_MODELS=openai requires OPENAI_API_KEY." >&2
+  exit 2
+elif [[ "$MODELS_MODE" == "anthropic" && -z "$ANTHROPIC_API_TOKEN" && -z "$ANTHROPIC_API_KEY" ]]; then
+  echo "ERROR: OPENCLAW_E2E_MODELS=anthropic requires ANTHROPIC_API_TOKEN or ANTHROPIC_API_KEY." >&2
+  exit 2
+fi
+
+echo "==> Resolve npm versions"
+EXPECTED_VERSION="$(npm view "openclaw@${INSTALL_TAG}" version)"
+if [[ -z "$EXPECTED_VERSION" || "$EXPECTED_VERSION" == "undefined" || "$EXPECTED_VERSION" == "null" ]]; then
+  echo "ERROR: unable to resolve openclaw@${INSTALL_TAG} version" >&2
+  exit 2
+fi
+if [[ -n "$E2E_PREVIOUS_VERSION" ]]; then
+  PREVIOUS_VERSION="$E2E_PREVIOUS_VERSION"
+else
+  PREVIOUS_VERSION="$(node - <<'NODE'
+const { execSync } = require("node:child_process");
+const versions = JSON.parse(execSync("npm view openclaw versions --json", { encoding: "utf8" }));
+if (!Array.isArray(versions) || versions.length === 0) process.exit(1);
+process.stdout.write(versions.length >= 2 ? versions[versions.length - 2] : versions[0]);
+NODE
+  )"
+fi
+echo "expected=$EXPECTED_VERSION previous=$PREVIOUS_VERSION"
+
+if [[ "$SKIP_PREVIOUS" == "1" ]]; then
+  echo "==> Skip preinstall previous (OPENCLAW_INSTALL_E2E_SKIP_PREVIOUS=1)"
+else
+  echo "==> Preinstall previous (forces installer upgrade path; avoids read() prompt)"
+  npm install -g "openclaw@${PREVIOUS_VERSION}"
+fi
+
+echo "==> Run official installer one-liner"
+if [[ "$INSTALL_TAG" == "beta" ]]; then
+  OPENCLAW_BETA=1 CLAWDBOT_BETA=1 curl -fsSL "$INSTALL_URL" | bash
+elif [[ "$INSTALL_TAG" != "latest" ]]; then
+  OPENCLAW_VERSION="$INSTALL_TAG" CLAWDBOT_VERSION="$INSTALL_TAG" curl -fsSL "$INSTALL_URL" | bash
+else
+  curl -fsSL "$INSTALL_URL" | bash
+fi
+
+echo "==> Verify installed version"
+INSTALLED_VERSION="$(openclaw --version 2>/dev/null | head -n 1 | tr -d '\r')"
+echo "installed=$INSTALLED_VERSION expected=$EXPECTED_VERSION"
+if [[ "$INSTALLED_VERSION" != "$EXPECTED_VERSION" ]]; then
+  echo "ERROR: expected openclaw@$EXPECTED_VERSION, got openclaw@$INSTALLED_VERSION" >&2
+  exit 1
+fi
+
+set_image_model() {
+  local profile="$1"
+  shift
+  local candidate
+  for candidate in "$@"; do
+    if openclaw --profile "$profile" models set-image "$candidate" >/dev/null 2>&1; then
+      echo "$candidate"
+      return 0
+    fi
+  done
+  echo "ERROR: could not set an image model (tried: $*)" >&2
+  return 1
+}
+
+set_agent_model() {
+  local profile="$1"
+  local candidate
+  shift
+  for candidate in "$@"; do
+    if openclaw --profile "$profile" models set "$candidate" >/dev/null 2>&1; then
+      echo "$candidate"
+      return 0
+    fi
+  done
+  echo "ERROR: could not set agent model (tried: $*)" >&2
+  return 1
+}
+
+write_png_lr_rg() {
+  local out="$1"
+  node - <<'NODE' "$out"
+const fs = require("node:fs");
+const zlib = require("node:zlib");
+
+const out = process.argv[2];
+const width = 96;
+const height = 64;
+
+const crcTable = (() => {
+  const table = new Uint32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let k = 0; k < 8; k++) c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+    table[i] = c >>> 0;
+  }
+  return table;
+})();
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = crcTable[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+  const typeBuf = Buffer.from(type, "ascii");
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length, 0);
+  const crcBuf = Buffer.alloc(4);
+  crcBuf.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);
+  return Buffer.concat([len, typeBuf, data, crcBuf]);
+}
+
+const sig = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const ihdr = Buffer.alloc(13);
+ihdr.writeUInt32BE(width, 0);
+ihdr.writeUInt32BE(height, 4);
+ihdr[8] = 8; // bit depth
+ihdr[9] = 2; // color type: truecolor
+ihdr[10] = 0; // compression
+ihdr[11] = 0; // filter
+ihdr[12] = 0; // interlace
+
+const rows = [];
+for (let y = 0; y < height; y++) {
+  const row = Buffer.alloc(1 + width * 3);
+  row[0] = 0; // filter: none
+  for (let x = 0; x < width; x++) {
+    const i = 1 + x * 3;
+    const left = x < width / 2;
+    row[i + 0] = left ? 255 : 0;
+    row[i + 1] = left ? 0 : 255;
+    row[i + 2] = 0;
+  }
+  rows.push(row);
+}
+const raw = Buffer.concat(rows);
+const idat = zlib.deflateSync(raw, { level: 9 });
+
+const png = Buffer.concat([
+  sig,
+  chunk("IHDR", ihdr),
+  chunk("IDAT", idat),
+  chunk("IEND", Buffer.alloc(0)),
+]);
+fs.writeFileSync(out, png);
+NODE
+}
+
+run_agent_turn() {
+  local profile="$1"
+  local session_id="$2"
+  local prompt="$3"
+  local out_json="$4"
+  openclaw --profile "$profile" agent \
+    --session-id "$session_id" \
+    --message "$prompt" \
+    --thinking off \
+    --json >"$out_json"
+}
+
+assert_agent_json_has_text() {
+  local path="$1"
+  node - <<'NODE' "$path"
+const fs = require("node:fs");
+const p = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const payloads =
+  Array.isArray(p?.result?.payloads) ? p.result.payloads :
+  Array.isArray(p?.payloads) ? p.payloads :
+  [];
+const texts = payloads.map((x) => String(x?.text ?? "").trim()).filter(Boolean);
+if (texts.length === 0) process.exit(1);
+NODE
+}
+
+assert_agent_json_ok() {
+  local json_path="$1"
+  local expect_provider="$2"
+  node - <<'NODE' "$json_path" "$expect_provider"
+const fs = require("node:fs");
+const jsonPath = process.argv[2];
+const expectProvider = process.argv[3];
+const p = JSON.parse(fs.readFileSync(jsonPath, "utf8"));
+
+if (typeof p?.status === "string" && p.status !== "ok" && p.status !== "accepted") {
+  console.error(`ERROR: gateway status=${p.status}`);
+  process.exit(1);
+}
+
+const result = p?.result ?? p;
+const payloads = Array.isArray(result?.payloads) ? result.payloads : [];
+const anyError = payloads.some((pl) => pl && pl.isError === true);
+const combinedText = payloads.map((pl) => String(pl?.text ?? "")).filter(Boolean).join("\n").trim();
+if (anyError) {
+  console.error(`ERROR: agent returned error payload: ${combinedText}`);
+  process.exit(1);
+}
+if (/rate_limit_error/i.test(combinedText) || /^429\\b/.test(combinedText)) {
+  console.error(`ERROR: agent rate limited: ${combinedText}`);
+  process.exit(1);
+}
+
+const meta = result?.meta;
+const provider =
+  (typeof meta?.agentMeta?.provider === "string" && meta.agentMeta.provider.trim()) ||
+  (typeof meta?.provider === "string" && meta.provider.trim()) ||
+  "";
+if (expectProvider && provider && provider !== expectProvider) {
+  console.error(`ERROR: expected provider=${expectProvider}, got provider=${provider}`);
+  process.exit(1);
+}
+NODE
+}
+
+extract_matching_text() {
+  local path="$1"
+  local expected="$2"
+  node - <<'NODE' "$path" "$expected"
+const fs = require("node:fs");
+const p = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const expected = String(process.argv[3] ?? "");
+const payloads =
+  Array.isArray(p?.result?.payloads) ? p.result.payloads :
+  Array.isArray(p?.payloads) ? p.payloads :
+  [];
+const texts = payloads.map((x) => String(x?.text ?? "").trim()).filter(Boolean);
+const match = texts.find((text) => text === expected);
+process.stdout.write(match ?? texts[0] ?? "");
+NODE
+}
+
+assert_session_used_tools() {
+  local jsonl="$1"
+  shift
+  node - <<'NODE' "$jsonl" "$@"
+const fs = require("node:fs");
+const jsonl = process.argv[2];
+const required = new Set(process.argv.slice(3));
+
+const raw = fs.readFileSync(jsonl, "utf8");
+const lines = raw.split("\n").map((l) => l.trim()).filter(Boolean);
+const seen = new Set();
+
+const toolTypes = new Set([
+  "tool_use",
+  "tool_result",
+  "tool",
+  "tool-call",
+  "tool_call",
+  "tooluse",
+  "tool-use",
+  "toolresult",
+  "tool-result",
+]);
+function walk(node, parent) {
+  if (!node) return;
+  if (Array.isArray(node)) {
+    for (const item of node) walk(item, node);
+    return;
+  }
+  if (typeof node !== "object") return;
+  const obj = node;
+  const t = typeof obj.type === "string" ? obj.type : null;
+  if (t && (toolTypes.has(t) || /tool/i.test(t))) {
+    const name =
+      typeof obj.name === "string" ? obj.name :
+      typeof obj.toolName === "string" ? obj.toolName :
+      typeof obj.tool_name === "string" ? obj.tool_name :
+      (obj.tool && typeof obj.tool.name === "string") ? obj.tool.name :
+      null;
+    if (name) seen.add(name);
+  }
+  if (typeof obj.name === "string" && typeof obj.input === "object" && obj.input) {
+    // Many tool-use blocks look like { type: "...", name: "exec", input: {...} }
+    // but some transcripts omit/rename type.
+    seen.add(obj.name);
+  }
+  // OpenAI-ish tool call shapes.
+  if (Array.isArray(obj.tool_calls)) {
+    for (const c of obj.tool_calls) {
+      const fn = c?.function;
+      if (fn && typeof fn.name === "string") seen.add(fn.name);
+    }
+  }
+  if (obj.function && typeof obj.function.name === "string") seen.add(obj.function.name);
+  for (const v of Object.values(obj)) walk(v, obj);
+}
+
+for (const line of lines) {
+  try {
+    const entry = JSON.parse(line);
+    walk(entry, null);
+  } catch {
+    // ignore unparsable lines
+  }
+}
+
+const missing = [...required].filter((t) => !seen.has(t));
+if (missing.length > 0) {
+  console.error(`Missing tools in transcript: ${missing.join(", ")}`);
+  console.error(`Seen tools: ${[...seen].sort().join(", ")}`);
+  console.error("Transcript head:");
+  console.error(lines.slice(0, 5).join("\n"));
+  process.exit(1);
+}
+NODE
+}
+
+run_profile() {
+  local profile="$1"
+  local port="$2"
+  local workspace="$3"
+  local agent_model_provider="$4" # "openai"|"anthropic"
+
+	  echo "==> Onboard ($profile)"
+	  if [[ "$agent_model_provider" == "openai" ]]; then
+	    openclaw --profile "$profile" onboard \
+	      --non-interactive \
+	      --accept-risk \
+	      --flow quickstart \
+	      --auth-choice openai-api-key \
+	      --openai-api-key "$OPENAI_API_KEY" \
+	      --gateway-port "$port" \
+	      --gateway-bind loopback \
+      --gateway-auth token \
+      --workspace "$workspace" \
+      --skip-health
+	  elif [[ -n "$ANTHROPIC_API_TOKEN" ]]; then
+	    openclaw --profile "$profile" onboard \
+	      --non-interactive \
+	      --accept-risk \
+	      --flow quickstart \
+	      --auth-choice token \
+	      --token-provider anthropic \
+	      --token "$ANTHROPIC_API_TOKEN" \
+	      --gateway-port "$port" \
+      --gateway-bind loopback \
+      --gateway-auth token \
+      --workspace "$workspace" \
+      --skip-health
+	  else
+	    openclaw --profile "$profile" onboard \
+	      --non-interactive \
+	      --accept-risk \
+	      --flow quickstart \
+	      --auth-choice apiKey \
+	      --anthropic-api-key "$ANTHROPIC_API_KEY" \
+	      --gateway-port "$port" \
+	      --gateway-bind loopback \
+      --gateway-auth token \
+      --workspace "$workspace" \
+      --skip-health
+  fi
+
+  echo "==> Verify workspace identity files ($profile)"
+  test -f "$workspace/AGENTS.md"
+  test -f "$workspace/IDENTITY.md"
+  test -f "$workspace/USER.md"
+  test -f "$workspace/SOUL.md"
+  test -f "$workspace/TOOLS.md"
+
+  echo "==> Configure models ($profile)"
+  local agent_model
+  local image_model
+  if [[ "$agent_model_provider" == "openai" ]]; then
+    agent_model="$(set_agent_model "$profile" \
+      "openai/gpt-4.1-mini" \
+      "openai/gpt-4.1" \
+      "openai/gpt-4o-mini" \
+      "openai/gpt-4o")"
+    image_model="$(set_image_model "$profile" \
+      "openai/gpt-4.1" \
+      "openai/gpt-4o-mini" \
+      "openai/gpt-4o" \
+      "openai/gpt-4.1-mini")"
+  else
+    agent_model="$(set_agent_model "$profile" \
+      "anthropic/claude-opus-4-5" \
+      "claude-opus-4-5")"
+    image_model="$(set_image_model "$profile" \
+      "anthropic/claude-opus-4-5" \
+      "claude-opus-4-5")"
+  fi
+  echo "model=$agent_model"
+  echo "imageModel=$image_model"
+
+  echo "==> Prepare tool fixtures ($profile)"
+  PROOF_TXT="$workspace/proof.txt"
+  PROOF_COPY="$workspace/copy.txt"
+  HOSTNAME_TXT="$workspace/hostname.txt"
+  IMAGE_PNG="$workspace/proof.png"
+  IMAGE_TXT="$workspace/image.txt"
+  SESSION_ID="e2e-tools-${profile}"
+  SESSION_JSONL="/root/.openclaw-${profile}/agents/main/sessions/${SESSION_ID}.jsonl"
+
+  PROOF_VALUE="$(node -e 'console.log(require("node:crypto").randomBytes(16).toString("hex"))')"
+  echo -n "$PROOF_VALUE" >"$PROOF_TXT"
+  write_png_lr_rg "$IMAGE_PNG"
+  EXPECTED_HOSTNAME="$(cat /etc/hostname | tr -d '\r\n')"
+
+  echo "==> Start gateway ($profile)"
+  GATEWAY_LOG="$workspace/gateway.log"
+  openclaw --profile "$profile" gateway --port "$port" --bind loopback >"$GATEWAY_LOG" 2>&1 &
+  GATEWAY_PID="$!"
+  cleanup_profile() {
+    if kill -0 "$GATEWAY_PID" 2>/dev/null; then
+      kill "$GATEWAY_PID" 2>/dev/null || true
+      wait "$GATEWAY_PID" 2>/dev/null || true
+    fi
+  }
+  trap cleanup_profile EXIT
+
+  echo "==> Wait for health ($profile)"
+  for _ in $(seq 1 60); do
+    if openclaw --profile "$profile" health --timeout 2000 --json >/dev/null 2>&1; then
+      break
+    fi
+    sleep 0.25
+  done
+  openclaw --profile "$profile" health --timeout 10000 --json >/dev/null
+
+  echo "==> Agent turns ($profile)"
+  TURN1_JSON="/tmp/agent-${profile}-1.json"
+  TURN2_JSON="/tmp/agent-${profile}-2.json"
+  TURN3_JSON="/tmp/agent-${profile}-3.json"
+  TURN4_JSON="/tmp/agent-${profile}-4.json"
+
+  run_agent_turn "$profile" "$SESSION_ID" \
+    "Use the read tool (not exec) to read proof.txt. Reply with the exact contents only (no extra whitespace)." \
+    "$TURN1_JSON"
+  assert_agent_json_has_text "$TURN1_JSON"
+  assert_agent_json_ok "$TURN1_JSON" "$agent_model_provider"
+  local reply1
+  reply1="$(extract_matching_text "$TURN1_JSON" "$PROOF_VALUE" | tr -d '\r\n')"
+  if [[ "$reply1" != "$PROOF_VALUE" ]]; then
+    echo "ERROR: agent did not read proof.txt correctly ($profile): $reply1" >&2
+    exit 1
+  fi
+
+  local prompt2
+  prompt2=$'Use the write tool (not exec) to write exactly this string into copy.txt:\n'"${reply1}"$'\nThen use the read tool (not exec) to read copy.txt and reply with the exact contents only (no extra whitespace).'
+  run_agent_turn "$profile" "$SESSION_ID" "$prompt2" "$TURN2_JSON"
+  assert_agent_json_has_text "$TURN2_JSON"
+  assert_agent_json_ok "$TURN2_JSON" "$agent_model_provider"
+  local copy_value
+  copy_value="$(cat "$PROOF_COPY" 2>/dev/null | tr -d '\r\n' || true)"
+  if [[ "$copy_value" != "$PROOF_VALUE" ]]; then
+    echo "ERROR: copy.txt did not match proof.txt ($profile)" >&2
+    exit 1
+  fi
+  local reply2
+  reply2="$(extract_matching_text "$TURN2_JSON" "$PROOF_VALUE" | tr -d '\r\n')"
+  if [[ "$reply2" != "$PROOF_VALUE" ]]; then
+    echo "ERROR: agent did not read copy.txt correctly ($profile): $reply2" >&2
+    exit 1
+  fi
+
+  local prompt3
+  prompt3=$'Use the exec tool to run: cat /etc/hostname\nThen use the write tool to write the exact stdout (trim trailing newline) into hostname.txt. Reply with the hostname only.'
+  run_agent_turn "$profile" "$SESSION_ID" "$prompt3" "$TURN3_JSON"
+  assert_agent_json_has_text "$TURN3_JSON"
+  assert_agent_json_ok "$TURN3_JSON" "$agent_model_provider"
+  if [[ "$(cat "$HOSTNAME_TXT" 2>/dev/null | tr -d '\r\n' || true)" != "$EXPECTED_HOSTNAME" ]]; then
+    echo "ERROR: hostname.txt did not match /etc/hostname ($profile)" >&2
+    exit 1
+  fi
+
+  run_agent_turn "$profile" "$SESSION_ID" \
+    "Use the image tool on proof.png. Determine which color is on the left half and which is on the right half. Then use the write tool to write exactly: LEFT=RED RIGHT=GREEN into image.txt. Reply with exactly: LEFT=RED RIGHT=GREEN" \
+    "$TURN4_JSON"
+  assert_agent_json_has_text "$TURN4_JSON"
+  assert_agent_json_ok "$TURN4_JSON" "$agent_model_provider"
+  if [[ "$(cat "$IMAGE_TXT" 2>/dev/null | tr -d '\r\n' || true)" != "LEFT=RED RIGHT=GREEN" ]]; then
+    echo "ERROR: image.txt did not contain expected marker ($profile)" >&2
+    exit 1
+  fi
+  local reply4
+  reply4="$(extract_matching_text "$TURN4_JSON" "LEFT=RED RIGHT=GREEN")"
+  if [[ "$reply4" != "LEFT=RED RIGHT=GREEN" ]]; then
+    echo "ERROR: agent reply did not contain expected marker ($profile): $reply4" >&2
+    exit 1
+  fi
+
+  echo "==> Verify tool usage via session transcript ($profile)"
+  # Give the gateway a moment to flush transcripts.
+  sleep 1
+  if [[ ! -f "$SESSION_JSONL" ]]; then
+    echo "ERROR: missing session transcript ($profile): $SESSION_JSONL" >&2
+    ls -la "/root/.openclaw-${profile}/agents/main/sessions" >&2 || true
+    exit 1
+  fi
+  assert_session_used_tools "$SESSION_JSONL" read write exec image
+
+  cleanup_profile
+  trap - EXIT
+}
+
+if [[ "$MODELS_MODE" == "openai" || "$MODELS_MODE" == "both" ]]; then
+  run_profile "e2e-openai" "18789" "/tmp/openclaw-e2e-openai" "openai"
+fi
+
+if [[ "$MODELS_MODE" == "anthropic" || "$MODELS_MODE" == "both" ]]; then
+  run_profile "e2e-anthropic" "18799" "/tmp/openclaw-e2e-anthropic" "anthropic"
+fi
+
+echo "OK"

scripts/docker/install-sh-nonroot/Dockerfile

@@ -0,0 +1,29 @@
+FROM ubuntu:24.04
+
+RUN set -eux; \
+  for attempt in 1 2 3; do \
+    if apt-get update -o Acquire::Retries=3; then break; fi; \
+    echo "apt-get update failed (attempt ${attempt})" >&2; \
+    if [ "${attempt}" -eq 3 ]; then exit 1; fi; \
+    sleep 3; \
+  done; \
+  apt-get -o Acquire::Retries=3 install -y --no-install-recommends \
+    bash \
+    ca-certificates \
+    curl \
+    sudo \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -s /bin/bash app \
+  && echo "app ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/app
+
+USER app
+WORKDIR /home/app
+
+ENV NPM_CONFIG_FUND=false
+ENV NPM_CONFIG_AUDIT=false
+
+COPY run.sh /usr/local/bin/openclaw-install-nonroot
+RUN sudo chmod +x /usr/local/bin/openclaw-install-nonroot
+
+ENTRYPOINT ["/usr/local/bin/openclaw-install-nonroot"]

scripts/docker/install-sh-nonroot/run.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+INSTALL_URL="${OPENCLAW_INSTALL_URL:-https://openclaw.bot/install.sh}"
+DEFAULT_PACKAGE="openclaw"
+PACKAGE_NAME="${OPENCLAW_INSTALL_PACKAGE:-$DEFAULT_PACKAGE}"
+
+echo "==> Pre-flight: ensure git absent"
+if command -v git >/dev/null; then
+  echo "git is present unexpectedly" >&2
+  exit 1
+fi
+
+echo "==> Run installer (non-root user)"
+curl -fsSL "$INSTALL_URL" | bash
+
+# Ensure PATH picks up user npm prefix
+export PATH="$HOME/.npm-global/bin:$PATH"
+
+echo "==> Verify git installed"
+command -v git >/dev/null
+
+EXPECTED_VERSION="${OPENCLAW_INSTALL_EXPECT_VERSION:-}"
+if [[ -n "$EXPECTED_VERSION" ]]; then
+  LATEST_VERSION="$EXPECTED_VERSION"
+else
+  LATEST_VERSION="$(npm view "$PACKAGE_NAME" version)"
+fi
+CLI_NAME="$PACKAGE_NAME"
+CMD_PATH="$(command -v "$CLI_NAME" || true)"
+if [[ -z "$CMD_PATH" && -x "$HOME/.npm-global/bin/$PACKAGE_NAME" ]]; then
+  CLI_NAME="$PACKAGE_NAME"
+  CMD_PATH="$HOME/.npm-global/bin/$PACKAGE_NAME"
+fi
+if [[ -z "$CMD_PATH" ]]; then
+  echo "$PACKAGE_NAME is not on PATH" >&2
+  exit 1
+fi
+echo "==> Verify CLI installed: $CLI_NAME"
+INSTALLED_VERSION="$("$CMD_PATH" --version 2>/dev/null | head -n 1 | tr -d '\r')"
+
+echo "cli=$CLI_NAME installed=$INSTALLED_VERSION expected=$LATEST_VERSION"
+if [[ "$INSTALLED_VERSION" != "$LATEST_VERSION" ]]; then
+  echo "ERROR: expected ${CLI_NAME}@${LATEST_VERSION}, got ${CLI_NAME}@${INSTALLED_VERSION}" >&2
+  exit 1
+fi
+
+echo "==> Sanity: CLI runs"
+"$CMD_PATH" --help >/dev/null
+
+echo "OK"

scripts/docker/install-sh-smoke/Dockerfile

@@ -0,0 +1,21 @@
+FROM node:22-bookworm-slim
+
+RUN set -eux; \
+  for attempt in 1 2 3; do \
+    if apt-get update -o Acquire::Retries=3; then break; fi; \
+    echo "apt-get update failed (attempt ${attempt})" >&2; \
+    if [ "${attempt}" -eq 3 ]; then exit 1; fi; \
+    sleep 3; \
+  done; \
+  apt-get -o Acquire::Retries=3 install -y --no-install-recommends \
+    bash \
+    ca-certificates \
+    curl \
+    git \
+    sudo \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY run.sh /usr/local/bin/openclaw-install-smoke
+RUN chmod +x /usr/local/bin/openclaw-install-smoke
+
+ENTRYPOINT ["/usr/local/bin/openclaw-install-smoke"]

scripts/docker/install-sh-smoke/run.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+INSTALL_URL="${OPENCLAW_INSTALL_URL:-https://openclaw.bot/install.sh}"
+SMOKE_PREVIOUS_VERSION="${OPENCLAW_INSTALL_SMOKE_PREVIOUS:-}"
+SKIP_PREVIOUS="${OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS:-0}"
+DEFAULT_PACKAGE="openclaw"
+PACKAGE_NAME="${OPENCLAW_INSTALL_PACKAGE:-$DEFAULT_PACKAGE}"
+
+echo "==> Resolve npm versions"
+LATEST_VERSION="$(npm view "$PACKAGE_NAME" version)"
+if [[ -n "$SMOKE_PREVIOUS_VERSION" ]]; then
+  PREVIOUS_VERSION="$SMOKE_PREVIOUS_VERSION"
+else
+  VERSIONS_JSON="$(npm view "$PACKAGE_NAME" versions --json)"
+  PREVIOUS_VERSION="$(VERSIONS_JSON="$VERSIONS_JSON" LATEST_VERSION="$LATEST_VERSION" node - <<'NODE'
+const raw = process.env.VERSIONS_JSON || "[]";
+const latest = process.env.LATEST_VERSION || "";
+let versions;
+try {
+  versions = JSON.parse(raw);
+} catch {
+  versions = raw ? [raw] : [];
+}
+if (!Array.isArray(versions)) {
+  versions = [versions];
+}
+if (versions.length === 0) {
+  process.exit(1);
+}
+const latestIndex = latest ? versions.lastIndexOf(latest) : -1;
+if (latestIndex > 0) {
+  process.stdout.write(String(versions[latestIndex - 1]));
+  process.exit(0);
+}
+process.stdout.write(String(latest || versions[versions.length - 1]));
+NODE
+)"
+fi
+
+echo "package=$PACKAGE_NAME latest=$LATEST_VERSION previous=$PREVIOUS_VERSION"
+
+if [[ "$SKIP_PREVIOUS" == "1" ]]; then
+  echo "==> Skip preinstall previous (OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS=1)"
+else
+  echo "==> Preinstall previous (forces installer upgrade path)"
+  npm install -g "${PACKAGE_NAME}@${PREVIOUS_VERSION}"
+fi
+
+echo "==> Run official installer one-liner"
+curl -fsSL "$INSTALL_URL" | bash
+
+echo "==> Verify installed version"
+CLI_NAME="$PACKAGE_NAME"
+if ! command -v "$CLI_NAME" >/dev/null 2>&1; then
+  echo "ERROR: $PACKAGE_NAME is not on PATH" >&2
+  exit 1
+fi
+if [[ -n "${OPENCLAW_INSTALL_LATEST_OUT:-}" ]]; then
+  printf "%s" "$LATEST_VERSION" > "${OPENCLAW_INSTALL_LATEST_OUT:-}"
+fi
+INSTALLED_VERSION="$("$CLI_NAME" --version 2>/dev/null | head -n 1 | tr -d '\r')"
+echo "cli=$CLI_NAME installed=$INSTALLED_VERSION expected=$LATEST_VERSION"
+
+if [[ "$INSTALLED_VERSION" != "$LATEST_VERSION" ]]; then
+  echo "ERROR: expected ${CLI_NAME}@${LATEST_VERSION}, got ${CLI_NAME}@${INSTALLED_VERSION}" >&2
+  exit 1
+fi
+
+echo "==> Sanity: CLI runs"
+"$CLI_NAME" --help >/dev/null
+
+echo "OK"

scripts/docs-i18n/glossary.go

@@ -0,0 +1,29 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+)
+
+type GlossaryEntry struct {
+	Source string `json:"source"`
+	Target string `json:"target"`
+}
+
+func LoadGlossary(path string) ([]GlossaryEntry, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	var entries []GlossaryEntry
+	if err := json.Unmarshal(data, &entries); err != nil {
+		return nil, fmt.Errorf("glossary parse failed: %w", err)
+	}
+
+	return entries, nil
+}

scripts/docs-i18n/go.mod

@@ -0,0 +1,10 @@
+module github.com/openclaw/openclaw/scripts/docs-i18n
+
+go 1.22
+
+require (
+	github.com/joshp123/pi-golang v0.0.4
+	github.com/yuin/goldmark v1.7.8
+	golang.org/x/net v0.24.0
+	gopkg.in/yaml.v3 v3.0.1
+)

scripts/docs-i18n/go.sum

@@ -0,0 +1,10 @@
+github.com/joshp123/pi-golang v0.0.4 h1:82HISyKNN8bIl2lvAd65462LVCQIsjhaUFQxyQgg5Xk=
+github.com/joshp123/pi-golang v0.0.4/go.mod h1:9mHEQkeJELYzubXU3b86/T8yedI/iAOKx0Tz0c41qes=
+github.com/yuin/goldmark v1.7.8 h1:iERMLn0/QJeHFhxSt3p6PeN9mGnvIKSpG9YYorDMnic=
+github.com/yuin/goldmark v1.7.8/go.mod h1:uzxRWxtg69N339t3louHJ7+O03ezfj6PlliRlaOzY1E=
+golang.org/x/net v0.24.0 h1:1PcaxkF854Fu3+lvBIx5SYn9wRlBzzcnHZSiaFFAb0w=
+golang.org/x/net v0.24.0/go.mod h1:2Q7sJY5mzlzWjKtYUEXSlBWCdyaioyXzRB2RtU8KVE8=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

scripts/docs-i18n/html_translate.go

@@ -0,0 +1,160 @@
+package main
+
+import (
+	"context"
+	"io"
+	"strings"
+
+	"github.com/yuin/goldmark"
+	"github.com/yuin/goldmark/ast"
+	"github.com/yuin/goldmark/extension"
+	"github.com/yuin/goldmark/text"
+	"golang.org/x/net/html"
+	"sort"
+)
+
+type htmlReplacement struct {
+	Start int
+	Stop  int
+	Value string
+}
+
+func translateHTMLBlocks(ctx context.Context, translator *PiTranslator, body, srcLang, tgtLang string) (string, error) {
+	source := []byte(body)
+	r := text.NewReader(source)
+	md := goldmark.New(
+		goldmark.WithExtensions(extension.GFM),
+	)
+	doc := md.Parser().Parse(r)
+
+	replacements := make([]htmlReplacement, 0, 8)
+
+	_ = ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
+		if !entering {
+			return ast.WalkContinue, nil
+		}
+		block, ok := n.(*ast.HTMLBlock)
+		if !ok {
+			return ast.WalkContinue, nil
+		}
+		start, stop, ok := htmlBlockSpan(block, source)
+		if !ok {
+			return ast.WalkSkipChildren, nil
+		}
+		htmlText := string(source[start:stop])
+		translated, err := translateHTMLBlock(ctx, translator, htmlText, srcLang, tgtLang)
+		if err != nil {
+			return ast.WalkStop, err
+		}
+		replacements = append(replacements, htmlReplacement{Start: start, Stop: stop, Value: translated})
+		return ast.WalkSkipChildren, nil
+	})
+
+	if len(replacements) == 0 {
+		return body, nil
+	}
+
+	return applyHTMLReplacements(body, replacements), nil
+}
+
+func htmlBlockSpan(block *ast.HTMLBlock, source []byte) (int, int, bool) {
+	lines := block.Lines()
+	if lines.Len() == 0 {
+		return 0, 0, false
+	}
+	start := lines.At(0).Start
+	stop := lines.At(lines.Len() - 1).Stop
+	if start >= stop {
+		return 0, 0, false
+	}
+	return start, stop, true
+}
+
+func applyHTMLReplacements(body string, replacements []htmlReplacement) string {
+	if len(replacements) == 0 {
+		return body
+	}
+	sortHTMLReplacements(replacements)
+	var out strings.Builder
+	last := 0
+	for _, rep := range replacements {
+		if rep.Start < last {
+			continue
+		}
+		out.WriteString(body[last:rep.Start])
+		out.WriteString(rep.Value)
+		last = rep.Stop
+	}
+	out.WriteString(body[last:])
+	return out.String()
+}
+
+func sortHTMLReplacements(replacements []htmlReplacement) {
+	sort.Slice(replacements, func(i, j int) bool {
+		return replacements[i].Start < replacements[j].Start
+	})
+}
+
+func translateHTMLBlock(ctx context.Context, translator *PiTranslator, htmlText, srcLang, tgtLang string) (string, error) {
+	tokenizer := html.NewTokenizer(strings.NewReader(htmlText))
+	var out strings.Builder
+	skipDepth := 0
+
+	for {
+		tt := tokenizer.Next()
+		if tt == html.ErrorToken {
+			if err := tokenizer.Err(); err != nil && err != io.EOF {
+				return "", err
+			}
+			break
+		}
+
+		raw := string(tokenizer.Raw())
+		tok := tokenizer.Token()
+
+		switch tt {
+		case html.StartTagToken:
+			out.WriteString(raw)
+			if isSkipTag(strings.ToLower(tok.Data)) {
+				skipDepth++
+			}
+		case html.EndTagToken:
+			out.WriteString(raw)
+			if isSkipTag(strings.ToLower(tok.Data)) && skipDepth > 0 {
+				skipDepth--
+			}
+		case html.SelfClosingTagToken:
+			out.WriteString(raw)
+		case html.TextToken:
+			if shouldTranslateHTMLText(skipDepth, raw) {
+				translated, err := translator.Translate(ctx, raw, srcLang, tgtLang)
+				if err != nil {
+					return "", err
+				}
+				out.WriteString(translated)
+			} else {
+				out.WriteString(raw)
+			}
+		default:
+			out.WriteString(raw)
+		}
+	}
+
+	return out.String(), nil
+}
+
+func shouldTranslateHTMLText(skipDepth int, text string) bool {
+	if strings.TrimSpace(text) == "" {
+		return false
+	}
+	return skipDepth == 0
+}
+
+func isSkipTag(tag string) bool {
+	switch tag {
+	case "code", "pre", "script", "style":
+		return true
+	default:
+		return false
+	}
+}

scripts/docs-i18n/main.go

@@ -0,0 +1,58 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"path/filepath"
+)
+
+func main() {
+	var (
+		targetLang = flag.String("lang", "zh-CN", "target language (e.g., zh-CN)")
+		sourceLang = flag.String("src", "en", "source language")
+		docsRoot   = flag.String("docs", "docs", "docs root")
+		tmPath     = flag.String("tm", "", "translation memory path")
+	)
+	flag.Parse()
+	files := flag.Args()
+	if len(files) == 0 {
+		fatal(fmt.Errorf("no doc files provided"))
+	}
+
+	resolvedDocsRoot, err := filepath.Abs(*docsRoot)
+	if err != nil {
+		fatal(err)
+	}
+
+	if *tmPath == "" {
+		*tmPath = filepath.Join(resolvedDocsRoot, ".i18n", fmt.Sprintf("%s.tm.jsonl", *targetLang))
+	}
+
+	glossaryPath := filepath.Join(resolvedDocsRoot, ".i18n", fmt.Sprintf("glossary.%s.json", *targetLang))
+	glossary, err := LoadGlossary(glossaryPath)
+	if err != nil {
+		fatal(err)
+	}
+
+	translator, err := NewPiTranslator(*sourceLang, *targetLang, glossary)
+	if err != nil {
+		fatal(err)
+	}
+	defer translator.Close()
+
+	tm, err := LoadTranslationMemory(*tmPath)
+	if err != nil {
+		fatal(err)
+	}
+
+	for _, file := range files {
+		if err := processFile(context.Background(), translator, tm, resolvedDocsRoot, file, *sourceLang, *targetLang); err != nil {
+			fatal(err)
+		}
+	}
+
+	if err := tm.Save(); err != nil {
+		fatal(err)
+	}
+}

scripts/docs-i18n/markdown_segments.go

@@ -0,0 +1,131 @@
+package main
+
+import (
+	"sort"
+	"strings"
+
+	"github.com/yuin/goldmark"
+	"github.com/yuin/goldmark/ast"
+	"github.com/yuin/goldmark/extension"
+	"github.com/yuin/goldmark/text"
+)
+
+func extractSegments(body, relPath string) ([]Segment, error) {
+	source := []byte(body)
+	r := text.NewReader(source)
+	md := goldmark.New(
+		goldmark.WithExtensions(extension.GFM),
+	)
+	doc := md.Parser().Parse(r)
+
+	segments := make([]Segment, 0, 128)
+	skipDepth := 0
+	var lastBlock ast.Node
+
+	err := ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
+		switch n.(type) {
+		case *ast.CodeBlock, *ast.FencedCodeBlock, *ast.CodeSpan, *ast.HTMLBlock, *ast.RawHTML:
+			if entering {
+				skipDepth++
+			} else {
+				skipDepth--
+			}
+			return ast.WalkContinue, nil
+		}
+
+		if !entering || skipDepth > 0 {
+			return ast.WalkContinue, nil
+		}
+
+		textNode, ok := n.(*ast.Text)
+		if !ok {
+			return ast.WalkContinue, nil
+		}
+		block := blockParent(textNode)
+		if block == nil {
+			return ast.WalkContinue, nil
+		}
+		textValue := string(textNode.Segment.Value(source))
+		if strings.TrimSpace(textValue) == "" {
+			return ast.WalkContinue, nil
+		}
+
+		start := textNode.Segment.Start
+		stop := textNode.Segment.Stop
+		if len(segments) > 0 && lastBlock == block {
+			last := &segments[len(segments)-1]
+			gap := string(source[last.Stop:start])
+			if strings.TrimSpace(gap) == "" {
+				last.Stop = stop
+				return ast.WalkContinue, nil
+			}
+		}
+
+		segments = append(segments, Segment{Start: start, Stop: stop})
+		lastBlock = block
+		return ast.WalkContinue, nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	filtered := make([]Segment, 0, len(segments))
+	for _, seg := range segments {
+		textValue := string(source[seg.Start:seg.Stop])
+		trimmed := strings.TrimSpace(textValue)
+		if trimmed == "" {
+			continue
+		}
+		textHash := hashText(textValue)
+		segmentID := segmentID(relPath, textHash)
+		filtered = append(filtered, Segment{
+			Start:     seg.Start,
+			Stop:      seg.Stop,
+			Text:      textValue,
+			TextHash:  textHash,
+			SegmentID: segmentID,
+		})
+	}
+
+	sort.Slice(filtered, func(i, j int) bool {
+		return filtered[i].Start < filtered[j].Start
+	})
+
+	return filtered, nil
+}
+
+func blockParent(n ast.Node) ast.Node {
+	for node := n.Parent(); node != nil; node = node.Parent() {
+		if isTranslatableBlock(node) {
+			return node
+		}
+	}
+	return nil
+}
+
+func isTranslatableBlock(n ast.Node) bool {
+	switch n.(type) {
+	case *ast.Paragraph, *ast.Heading, *ast.ListItem:
+		return true
+	default:
+		return false
+	}
+}
+
+func applyTranslations(body string, segments []Segment) string {
+	if len(segments) == 0 {
+		return body
+	}
+	var out strings.Builder
+	last := 0
+	for _, seg := range segments {
+		if seg.Start < last {
+			continue
+		}
+		out.WriteString(body[last:seg.Start])
+		out.WriteString(seg.Translated)
+		last = seg.Stop
+	}
+	out.WriteString(body[last:])
+	return out.String()
+}

scripts/docs-i18n/masking.go

@@ -0,0 +1,89 @@
+package main
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+var (
+	inlineCodeRe  = regexp.MustCompile("`[^`]+`")
+	angleLinkRe   = regexp.MustCompile(`<https?://[^>]+>`)
+	linkURLRe     = regexp.MustCompile(`\[[^\]]*\]\(([^)]+)\)`)
+	placeholderRe = regexp.MustCompile(`__OC_I18N_\d+__`)
+)
+
+func maskMarkdown(text string, nextPlaceholder func() string, placeholders *[]string, mapping map[string]string) string {
+	masked := maskMatches(text, inlineCodeRe, nextPlaceholder, placeholders, mapping)
+	masked = maskMatches(masked, angleLinkRe, nextPlaceholder, placeholders, mapping)
+	masked = maskLinkURLs(masked, nextPlaceholder, placeholders, mapping)
+	return masked
+}
+
+func maskMatches(text string, re *regexp.Regexp, nextPlaceholder func() string, placeholders *[]string, mapping map[string]string) string {
+	matches := re.FindAllStringIndex(text, -1)
+	if len(matches) == 0 {
+		return text
+	}
+	var out strings.Builder
+	pos := 0
+	for _, span := range matches {
+		start, end := span[0], span[1]
+		if start < pos {
+			continue
+		}
+		out.WriteString(text[pos:start])
+		placeholder := nextPlaceholder()
+		mapping[placeholder] = text[start:end]
+		*placeholders = append(*placeholders, placeholder)
+		out.WriteString(placeholder)
+		pos = end
+	}
+	out.WriteString(text[pos:])
+	return out.String()
+}
+
+func maskLinkURLs(text string, nextPlaceholder func() string, placeholders *[]string, mapping map[string]string) string {
+	matches := linkURLRe.FindAllStringSubmatchIndex(text, -1)
+	if len(matches) == 0 {
+		return text
+	}
+	var out strings.Builder
+	pos := 0
+	for _, span := range matches {
+		fullStart := span[0]
+		urlStart, urlEnd := span[2], span[3]
+		if urlStart < 0 || urlEnd < 0 {
+			continue
+		}
+		if fullStart < pos {
+			continue
+		}
+		out.WriteString(text[pos:urlStart])
+		placeholder := nextPlaceholder()
+		mapping[placeholder] = text[urlStart:urlEnd]
+		*placeholders = append(*placeholders, placeholder)
+		out.WriteString(placeholder)
+		pos = urlEnd
+	}
+	out.WriteString(text[pos:])
+	return out.String()
+}
+
+func unmaskMarkdown(text string, placeholders []string, mapping map[string]string) string {
+	out := text
+	for _, placeholder := range placeholders {
+		original := mapping[placeholder]
+		out = strings.ReplaceAll(out, placeholder, original)
+	}
+	return out
+}
+
+func validatePlaceholders(text string, placeholders []string) error {
+	for _, placeholder := range placeholders {
+		if !strings.Contains(text, placeholder) {
+			return fmt.Errorf("placeholder missing: %s", placeholder)
+		}
+	}
+	return nil
+}

scripts/docs-i18n/placeholders.go

@@ -0,0 +1,30 @@
+package main
+
+import (
+	"fmt"
+)
+
+type PlaceholderState struct {
+	counter int
+	used    map[string]struct{}
+}
+
+func NewPlaceholderState(text string) *PlaceholderState {
+	used := map[string]struct{}{}
+	for _, hit := range placeholderRe.FindAllString(text, -1) {
+		used[hit] = struct{}{}
+	}
+	return &PlaceholderState{counter: 900000, used: used}
+}
+
+func (s *PlaceholderState) Next() string {
+	for {
+		candidate := fmt.Sprintf("__OC_I18N_%d__", s.counter)
+		s.counter++
+		if _, ok := s.used[candidate]; ok {
+			continue
+		}
+		s.used[candidate] = struct{}{}
+		return candidate
+	}
+}

scripts/docs-i18n/process.go

@@ -0,0 +1,205 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"gopkg.in/yaml.v3"
+)
+
+func processFile(ctx context.Context, translator *PiTranslator, tm *TranslationMemory, docsRoot, filePath, srcLang, tgtLang string) error {
+	absPath, err := filepath.Abs(filePath)
+	if err != nil {
+		return err
+	}
+	relPath, err := filepath.Rel(docsRoot, absPath)
+	if err != nil {
+		return err
+	}
+	if relPath == "." || relPath == "" {
+		return fmt.Errorf("file %s resolves to docs root %s", absPath, docsRoot)
+	}
+	if filepath.IsAbs(relPath) || relPath == ".." || strings.HasPrefix(relPath, ".."+string(filepath.Separator)) {
+		return fmt.Errorf("file %s not under docs root %s", absPath, docsRoot)
+	}
+
+	content, err := os.ReadFile(absPath)
+	if err != nil {
+		return err
+	}
+
+	frontMatter, body := splitFrontMatter(string(content))
+	frontData := map[string]any{}
+	if frontMatter != "" {
+		if err := yaml.Unmarshal([]byte(frontMatter), &frontData); err != nil {
+			return fmt.Errorf("frontmatter parse failed for %s: %w", relPath, err)
+		}
+	}
+
+	if err := translateFrontMatter(ctx, translator, tm, frontData, relPath, srcLang, tgtLang); err != nil {
+		return err
+	}
+
+	body, err = translateHTMLBlocks(ctx, translator, body, srcLang, tgtLang)
+	if err != nil {
+		return err
+	}
+
+	segments, err := extractSegments(body, relPath)
+	if err != nil {
+		return err
+	}
+
+	namespace := cacheNamespace()
+	for i := range segments {
+		seg := &segments[i]
+		seg.CacheKey = cacheKey(namespace, srcLang, tgtLang, seg.SegmentID, seg.TextHash)
+		if entry, ok := tm.Get(seg.CacheKey); ok {
+			seg.Translated = entry.Translated
+			continue
+		}
+		translated, err := translator.Translate(ctx, seg.Text, srcLang, tgtLang)
+		if err != nil {
+			return fmt.Errorf("translate failed (%s): %w", relPath, err)
+		}
+		seg.Translated = translated
+		entry := TMEntry{
+			CacheKey:   seg.CacheKey,
+			SegmentID:  seg.SegmentID,
+			SourcePath: relPath,
+			TextHash:   seg.TextHash,
+			Text:       seg.Text,
+			Translated: translated,
+			Provider:   providerName,
+			Model:      modelVersion,
+			SrcLang:    srcLang,
+			TgtLang:    tgtLang,
+			UpdatedAt:  time.Now().UTC().Format(time.RFC3339),
+		}
+		tm.Put(entry)
+	}
+
+	translatedBody := applyTranslations(body, segments)
+	updatedFront, err := encodeFrontMatter(frontData, relPath, content)
+	if err != nil {
+		return err
+	}
+
+	outputPath := filepath.Join(docsRoot, tgtLang, relPath)
+	if err := os.MkdirAll(filepath.Dir(outputPath), 0o755); err != nil {
+		return err
+	}
+
+	output := updatedFront + translatedBody
+	return os.WriteFile(outputPath, []byte(output), 0o644)
+}
+
+func splitFrontMatter(content string) (string, string) {
+	if !strings.HasPrefix(content, "---") {
+		return "", content
+	}
+	lines := strings.Split(content, "\n")
+	if len(lines) < 2 {
+		return "", content
+	}
+	endIndex := -1
+	for i := 1; i < len(lines); i++ {
+		if strings.TrimSpace(lines[i]) == "---" {
+			endIndex = i
+			break
+		}
+	}
+	if endIndex == -1 {
+		return "", content
+	}
+	front := strings.Join(lines[1:endIndex], "\n")
+	body := strings.Join(lines[endIndex+1:], "\n")
+	if strings.HasPrefix(body, "\n") {
+		body = body[1:]
+	}
+	return front, body
+}
+
+func encodeFrontMatter(frontData map[string]any, relPath string, source []byte) (string, error) {
+	if len(frontData) == 0 {
+		return "", nil
+	}
+	frontData["x-i18n"] = map[string]any{
+		"source_path":  relPath,
+		"source_hash":  hashBytes(source),
+		"provider":     providerName,
+		"model":        modelVersion,
+		"workflow":     workflowVersion,
+		"generated_at": time.Now().UTC().Format(time.RFC3339),
+	}
+	encoded, err := yaml.Marshal(frontData)
+	if err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("---\n%s---\n\n", string(encoded)), nil
+}
+
+func translateFrontMatter(ctx context.Context, translator *PiTranslator, tm *TranslationMemory, data map[string]any, relPath, srcLang, tgtLang string) error {
+	if len(data) == 0 {
+		return nil
+	}
+	if summary, ok := data["summary"].(string); ok {
+		translated, err := translateSnippet(ctx, translator, tm, relPath+":frontmatter:summary", summary, srcLang, tgtLang)
+		if err != nil {
+			return err
+		}
+		data["summary"] = translated
+	}
+	if readWhen, ok := data["read_when"].([]any); ok {
+		translated := make([]any, 0, len(readWhen))
+		for idx, item := range readWhen {
+			textValue, ok := item.(string)
+			if !ok {
+				translated = append(translated, item)
+				continue
+			}
+			value, err := translateSnippet(ctx, translator, tm, fmt.Sprintf("%s:frontmatter:read_when:%d", relPath, idx), textValue, srcLang, tgtLang)
+			if err != nil {
+				return err
+			}
+			translated = append(translated, value)
+		}
+		data["read_when"] = translated
+	}
+	return nil
+}
+
+func translateSnippet(ctx context.Context, translator *PiTranslator, tm *TranslationMemory, segmentID, textValue, srcLang, tgtLang string) (string, error) {
+	if strings.TrimSpace(textValue) == "" {
+		return textValue, nil
+	}
+	namespace := cacheNamespace()
+	textHash := hashText(textValue)
+	ck := cacheKey(namespace, srcLang, tgtLang, segmentID, textHash)
+	if entry, ok := tm.Get(ck); ok {
+		return entry.Translated, nil
+	}
+	translated, err := translator.Translate(ctx, textValue, srcLang, tgtLang)
+	if err != nil {
+		return "", err
+	}
+	entry := TMEntry{
+		CacheKey:   ck,
+		SegmentID:  segmentID,
+		SourcePath: segmentID,
+		TextHash:   textHash,
+		Text:       textValue,
+		Translated: translated,
+		Provider:   providerName,
+		Model:      modelVersion,
+		SrcLang:    srcLang,
+		TgtLang:    tgtLang,
+		UpdatedAt:  time.Now().UTC().Format(time.RFC3339),
+	}
+	tm.Put(entry)
+	return translated, nil
+}

scripts/docs-i18n/segment.go

@@ -0,0 +1,11 @@
+package main
+
+type Segment struct {
+	Start      int
+	Stop       int
+	Text       string
+	TextHash   string
+	SegmentID  string
+	Translated string
+	CacheKey   string
+}

scripts/docs-i18n/tm.go

@@ -0,0 +1,126 @@
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+type TMEntry struct {
+	CacheKey   string `json:"cache_key"`
+	SegmentID  string `json:"segment_id"`
+	SourcePath string `json:"source_path"`
+	TextHash   string `json:"text_hash"`
+	Text       string `json:"text"`
+	Translated string `json:"translated"`
+	Provider   string `json:"provider"`
+	Model      string `json:"model"`
+	SrcLang    string `json:"src_lang"`
+	TgtLang    string `json:"tgt_lang"`
+	UpdatedAt  string `json:"updated_at"`
+}
+
+type TranslationMemory struct {
+	path    string
+	entries map[string]TMEntry
+}
+
+func LoadTranslationMemory(path string) (*TranslationMemory, error) {
+	tm := &TranslationMemory{path: path, entries: map[string]TMEntry{}}
+	file, err := os.Open(path)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return tm, nil
+		}
+		return nil, err
+	}
+	defer file.Close()
+
+	reader := bufio.NewReader(file)
+	for {
+		line, err := reader.ReadBytes('\n')
+		if len(line) > 0 {
+			trimmed := strings.TrimSpace(string(line))
+			if trimmed != "" {
+				var entry TMEntry
+				if err := json.Unmarshal([]byte(trimmed), &entry); err != nil {
+					return nil, fmt.Errorf("translation memory decode failed: %w", err)
+				}
+				if entry.CacheKey != "" {
+					tm.entries[entry.CacheKey] = entry
+				}
+			}
+		}
+		if err != nil {
+			if errors.Is(err, io.EOF) {
+				break
+			}
+			return nil, err
+		}
+	}
+	return tm, nil
+}
+
+func (tm *TranslationMemory) Get(cacheKey string) (TMEntry, bool) {
+	entry, ok := tm.entries[cacheKey]
+	return entry, ok
+}
+
+func (tm *TranslationMemory) Put(entry TMEntry) {
+	if entry.CacheKey == "" {
+		return
+	}
+	tm.entries[entry.CacheKey] = entry
+}
+
+func (tm *TranslationMemory) Save() error {
+	if tm.path == "" {
+		return nil
+	}
+	if err := os.MkdirAll(filepath.Dir(tm.path), 0o755); err != nil {
+		return err
+	}
+	tmpPath := tm.path + ".tmp"
+	file, err := os.Create(tmpPath)
+	if err != nil {
+		return err
+	}
+
+	keys := make([]string, 0, len(tm.entries))
+	for key := range tm.entries {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+
+	writer := bufio.NewWriter(file)
+	for _, key := range keys {
+		entry := tm.entries[key]
+		payload, err := json.Marshal(entry)
+		if err != nil {
+			_ = file.Close()
+			return err
+		}
+		if _, err := writer.Write(payload); err != nil {
+			_ = file.Close()
+			return err
+		}
+		if _, err := writer.WriteString("\n"); err != nil {
+			_ = file.Close()
+			return err
+		}
+	}
+	if err := writer.Flush(); err != nil {
+		_ = file.Close()
+		return err
+	}
+	if err := file.Close(); err != nil {
+		return err
+	}
+	return os.Rename(tmpPath, tm.path)
+}

scripts/docs-i18n/translator.go

@@ -0,0 +1,104 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	pi "github.com/joshp123/pi-golang"
+)
+
+type PiTranslator struct {
+	client *pi.OneShotClient
+}
+
+func NewPiTranslator(srcLang, tgtLang string, glossary []GlossaryEntry) (*PiTranslator, error) {
+	options := pi.DefaultOneShotOptions()
+	options.AppName = "openclaw-docs-i18n"
+	options.Mode = pi.ModeDragons
+	options.Dragons = pi.DragonsOptions{
+		Provider: "anthropic",
+		Model:    modelVersion,
+		Thinking: "high",
+	}
+	options.SystemPrompt = translationPrompt(srcLang, tgtLang, glossary)
+	client, err := pi.StartOneShot(options)
+	if err != nil {
+		return nil, err
+	}
+	return &PiTranslator{client: client}, nil
+}
+
+func (t *PiTranslator) Translate(ctx context.Context, text, srcLang, tgtLang string) (string, error) {
+	if t.client == nil {
+		return "", errors.New("pi client unavailable")
+	}
+	prefix, core, suffix := splitWhitespace(text)
+	if core == "" {
+		return text, nil
+	}
+	state := NewPlaceholderState(core)
+	placeholders := make([]string, 0, 8)
+	mapping := map[string]string{}
+	masked := maskMarkdown(core, state.Next, &placeholders, mapping)
+	res, err := t.client.Run(ctx, masked)
+	if err != nil {
+		return "", err
+	}
+	translated := strings.TrimSpace(res.Text)
+	if err := validatePlaceholders(translated, placeholders); err != nil {
+		return "", err
+	}
+	translated = unmaskMarkdown(translated, placeholders, mapping)
+	return prefix + translated + suffix, nil
+}
+
+func (t *PiTranslator) Close() {
+	if t.client != nil {
+		_ = t.client.Close()
+	}
+}
+
+func translationPrompt(srcLang, tgtLang string, glossary []GlossaryEntry) string {
+	srcLabel := srcLang
+	tgtLabel := tgtLang
+	if strings.EqualFold(srcLang, "en") {
+		srcLabel = "English"
+	}
+	if strings.EqualFold(tgtLang, "zh-CN") {
+		tgtLabel = "Simplified Chinese"
+	}
+	glossaryBlock := buildGlossaryPrompt(glossary)
+	return strings.TrimSpace(fmt.Sprintf(`You are a translation function, not a chat assistant.
+Translate from %s to %s.
+
+Rules:
+- Output ONLY the translated text. No preamble, no questions, no commentary.
+- Preserve Markdown syntax exactly (headings, lists, tables, emphasis).
+- Do not translate code spans/blocks, config keys, CLI flags, or env vars.
+- Do not alter URLs or anchors.
+- Preserve placeholders exactly: __OC_I18N_####__.
+- Use neutral technical Chinese; avoid slang or jokes.
+- Keep product names in English: OpenClaw, Gateway, Pi, WhatsApp, Telegram, Discord, iMessage, Slack, Microsoft Teams, Google Chat, Signal.
+
+%s
+
+If the input is empty, output empty.
+If the input contains only placeholders, output it unchanged.`, srcLabel, tgtLabel, glossaryBlock))
+}
+
+func buildGlossaryPrompt(glossary []GlossaryEntry) string {
+	if len(glossary) == 0 {
+		return ""
+	}
+	var lines []string
+	lines = append(lines, "Preferred translations (use when natural):")
+	for _, entry := range glossary {
+		if entry.Source == "" || entry.Target == "" {
+			continue
+		}
+		lines = append(lines, fmt.Sprintf("- %s -> %s", entry.Source, entry.Target))
+	}
+	return strings.Join(lines, "\n")
+}

scripts/docs-i18n/util.go

@@ -0,0 +1,81 @@
+package main
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+)
+
+const (
+	workflowVersion = 9
+	providerName    = "pi"
+	modelVersion    = "claude-opus-4-5"
+)
+
+func cacheNamespace() string {
+	return fmt.Sprintf("wf=%d|provider=%s|model=%s", workflowVersion, providerName, modelVersion)
+}
+
+func cacheKey(namespace, srcLang, tgtLang, segmentID, textHash string) string {
+	raw := fmt.Sprintf("%s|%s|%s|%s|%s", namespace, srcLang, tgtLang, segmentID, textHash)
+	hash := sha256.Sum256([]byte(raw))
+	return hex.EncodeToString(hash[:])
+}
+
+func hashText(text string) string {
+	normalized := normalizeText(text)
+	hash := sha256.Sum256([]byte(normalized))
+	return hex.EncodeToString(hash[:])
+}
+
+func hashBytes(data []byte) string {
+	hash := sha256.Sum256(data)
+	return hex.EncodeToString(hash[:])
+}
+
+func normalizeText(text string) string {
+	return strings.Join(strings.Fields(strings.TrimSpace(text)), " ")
+}
+
+func segmentID(relPath, textHash string) string {
+	shortHash := textHash
+	if len(shortHash) > 16 {
+		shortHash = shortHash[:16]
+	}
+	return fmt.Sprintf("%s:%s", relPath, shortHash)
+}
+
+func splitWhitespace(text string) (string, string, string) {
+	if text == "" {
+		return "", "", ""
+	}
+	start := 0
+	for start < len(text) && isWhitespace(text[start]) {
+		start++
+	}
+	end := len(text)
+	for end > start && isWhitespace(text[end-1]) {
+		end--
+	}
+	return text[:start], text[start:end], text[end:]
+}
+
+func isWhitespace(b byte) bool {
+	switch b {
+	case ' ', '\t', '\n', '\r':
+		return true
+	default:
+		return false
+	}
+}
+
+func fatal(err error) {
+	if err == nil {
+		return
+	}
+	_, _ = io.WriteString(os.Stderr, err.Error()+"\n")
+	os.Exit(1)
+}

scripts/docs-list.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+process.stdout.on("error", (error) => {
+  if (error?.code === "EPIPE") {
+    process.exit(0);
+  }
+  throw error;
+});
+
+const DOCS_DIR = join(process.cwd(), "docs");
+if (!existsSync(DOCS_DIR)) {
+  console.error("docs:list: missing docs directory. Run from repo root.");
+  process.exit(1);
+}
+if (!statSync(DOCS_DIR).isDirectory()) {
+  console.error("docs:list: docs path is not a directory.");
+  process.exit(1);
+}
+
+const EXCLUDED_DIRS = new Set(["archive", "research"]);
+
+/**
+ * @param {unknown[]} values
+ * @returns {string[]}
+ */
+function compactStrings(values) {
+  const result = [];
+  for (const value of values) {
+    if (value === null || value === undefined) {
+      continue;
+    }
+    const normalized =
+      typeof value === "string"
+        ? value.trim()
+        : typeof value === "number" || typeof value === "boolean"
+          ? String(value).trim()
+          : null;
+
+    if (normalized?.length > 0) {
+      result.push(normalized);
+    }
+  }
+  return result;
+}
+
+/**
+ * @param {string} dir
+ * @param {string} base
+ * @returns {string[]}
+ */
+function walkMarkdownFiles(dir, base = dir) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) {
+      continue;
+    }
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (EXCLUDED_DIRS.has(entry.name)) {
+        continue;
+      }
+      files.push(...walkMarkdownFiles(fullPath, base));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push(relative(base, fullPath));
+    }
+  }
+  return files.toSorted((a, b) => a.localeCompare(b));
+}
+
+/**
+ * @param {string} fullPath
+ * @returns {{ summary: string | null; readWhen: string[]; error?: string }}
+ */
+function extractMetadata(fullPath) {
+  const content = readFileSync(fullPath, "utf8");
+
+  if (!content.startsWith("---")) {
+    return { summary: null, readWhen: [], error: "missing front matter" };
+  }
+
+  const endIndex = content.indexOf("\n---", 3);
+  if (endIndex === -1) {
+    return { summary: null, readWhen: [], error: "unterminated front matter" };
+  }
+
+  const frontMatter = content.slice(3, endIndex).trim();
+  const lines = frontMatter.split("\n");
+
+  let summaryLine = null;
+  const readWhen = [];
+  let collectingField = null;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    if (line.startsWith("summary:")) {
+      summaryLine = line;
+      collectingField = null;
+      continue;
+    }
+
+    if (line.startsWith("read_when:")) {
+      collectingField = "read_when";
+      const inline = line.slice("read_when:".length).trim();
+      if (inline.startsWith("[") && inline.endsWith("]")) {
+        try {
+          const parsed = JSON.parse(inline.replace(/'/g, '"'));
+          if (Array.isArray(parsed)) {
+            readWhen.push(...compactStrings(parsed));
+          }
+        } catch {
+          // ignore malformed inline arrays
+        }
+      }
+      continue;
+    }
+
+    if (collectingField === "read_when") {
+      if (line.startsWith("- ")) {
+        const hint = line.slice(2).trim();
+        if (hint) {
+          readWhen.push(hint);
+        }
+      } else if (line === "") {
+        // allow blank lines inside the list
+      } else {
+        collectingField = null;
+      }
+    }
+  }
+
+  if (!summaryLine) {
+    return { summary: null, readWhen, error: "summary key missing" };
+  }
+
+  const summaryValue = summaryLine.slice("summary:".length).trim();
+  const normalized = summaryValue
+    .replace(/^['"]|['"]$/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (!normalized) {
+    return { summary: null, readWhen, error: "summary is empty" };
+  }
+
+  return { summary: normalized, readWhen };
+}
+
+console.log("Listing all markdown files in docs folder:");
+
+const markdownFiles = walkMarkdownFiles(DOCS_DIR);
+
+for (const relativePath of markdownFiles) {
+  const fullPath = join(DOCS_DIR, relativePath);
+  const { summary, readWhen, error } = extractMetadata(fullPath);
+  if (summary) {
+    console.log(`${relativePath} - ${summary}`);
+    if (readWhen.length > 0) {
+      console.log(`  Read when: ${readWhen.join("; ")}`);
+    }
+  } else {
+    const reason = error ? ` - [${error}]` : "";
+    console.log(`${relativePath}${reason}`);
+  }
+}
+
+console.log(
+  '\nReminder: keep docs up to date as behavior changes. When your task matches any "Read when" hint above (React hooks, cache directives, database work, tests, etc.), read that doc before coding, and suggest new coverage when it is missing.',
+);

scripts/e2e/Dockerfile

@@ -0,0 +1,23 @@
+FROM node:22-bookworm
+
+RUN corepack enable
+
+WORKDIR /app
+
+ENV NODE_OPTIONS="--disable-warning=ExperimentalWarning"
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.json vitest.config.ts vitest.e2e.config.ts ./
+COPY src ./src
+COPY test ./test
+COPY scripts ./scripts
+COPY docs ./docs
+COPY skills ./skills
+COPY patches ./patches
+COPY ui ./ui
+COPY extensions/memory-core ./extensions/memory-core
+
+RUN pnpm install --frozen-lockfile
+RUN pnpm build
+RUN pnpm ui:build
+
+CMD ["bash"]

scripts/e2e/Dockerfile.qr-import

@@ -0,0 +1,9 @@
+FROM node:22-bookworm
+
+RUN corepack enable
+
+WORKDIR /app
+
+COPY . .
+
+RUN pnpm install --frozen-lockfile

scripts/e2e/doctor-install-switch-docker.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+IMAGE_NAME="openclaw-doctor-install-switch-e2e"
+
+echo "Building Docker image..."
+docker build -t "$IMAGE_NAME" -f "$ROOT_DIR/scripts/e2e/Dockerfile" "$ROOT_DIR"
+
+echo "Running doctor install switch E2E..."
+docker run --rm -t "$IMAGE_NAME" bash -lc '
+  set -euo pipefail
+
+  # Keep logs focused; the npm global install step can emit noisy deprecation warnings.
+  export npm_config_loglevel=error
+  export npm_config_fund=false
+  export npm_config_audit=false
+
+  # Stub systemd/loginctl so doctor + daemon flows work in Docker.
+  export PATH="/tmp/openclaw-bin:$PATH"
+  mkdir -p /tmp/openclaw-bin
+
+  cat > /tmp/openclaw-bin/systemctl <<"SYSTEMCTL"
+#!/usr/bin/env bash
+set -euo pipefail
+
+args=("$@")
+if [[ "${args[0]:-}" == "--user" ]]; then
+  args=("${args[@]:1}")
+fi
+cmd="${args[0]:-}"
+case "$cmd" in
+  status)
+    exit 0
+    ;;
+  is-enabled)
+    unit="${args[1]:-}"
+    unit_path="$HOME/.config/systemd/user/${unit}"
+    if [ -f "$unit_path" ]; then
+      exit 0
+    fi
+    exit 1
+    ;;
+  show)
+    echo "ActiveState=inactive"
+    echo "SubState=dead"
+    echo "MainPID=0"
+    echo "ExecMainStatus=0"
+    echo "ExecMainCode=0"
+    exit 0
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+SYSTEMCTL
+  chmod +x /tmp/openclaw-bin/systemctl
+
+  cat > /tmp/openclaw-bin/loginctl <<"LOGINCTL"
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "$*" == *"show-user"* ]]; then
+  echo "Linger=yes"
+  exit 0
+fi
+if [[ "$*" == *"enable-linger"* ]]; then
+  exit 0
+fi
+exit 0
+LOGINCTL
+  chmod +x /tmp/openclaw-bin/loginctl
+
+  # Install the npm-global variant from the local /app source.
+  # `npm pack` can emit script output; keep only the tarball name.
+  pkg_tgz="$(npm pack --silent /app | tail -n 1 | tr -d '\r')"
+  if [ ! -f "/app/$pkg_tgz" ]; then
+    echo "npm pack failed (expected /app/$pkg_tgz)"
+    exit 1
+  fi
+  npm install -g --prefix /tmp/npm-prefix "/app/$pkg_tgz"
+
+  npm_bin="/tmp/npm-prefix/bin/openclaw"
+  npm_entry="/tmp/npm-prefix/lib/node_modules/openclaw/openclaw.mjs"
+  git_entry="/app/openclaw.mjs"
+
+  assert_entrypoint() {
+    local unit_path="$1"
+    local expected="$2"
+    local exec_line=""
+    exec_line=$(grep -m1 "^ExecStart=" "$unit_path" || true)
+    if [ -z "$exec_line" ]; then
+      echo "Missing ExecStart in $unit_path"
+      exit 1
+	    fi
+	    exec_line="${exec_line#ExecStart=}"
+	    entrypoint=$(echo "$exec_line" | awk "{print \$2}")
+	    entrypoint="${entrypoint%\"}"
+	    entrypoint="${entrypoint#\"}"
+	    if [ "$entrypoint" != "$expected" ]; then
+	      echo "Expected entrypoint $expected, got $entrypoint"
+	      exit 1
+	    fi
+	  }
+
+  # Each flow: install service with one variant, run doctor from the other,
+  # and verify ExecStart entrypoint switches accordingly.
+  run_flow() {
+    local name="$1"
+    local install_cmd="$2"
+    local install_expected="$3"
+    local doctor_cmd="$4"
+    local doctor_expected="$5"
+
+    echo "== Flow: $name =="
+    home_dir=$(mktemp -d "/tmp/openclaw-switch-${name}.XXXXXX")
+    export HOME="$home_dir"
+    export USER="testuser"
+
+    eval "$install_cmd"
+
+    unit_path="$HOME/.config/systemd/user/openclaw-gateway.service"
+    if [ ! -f "$unit_path" ]; then
+      echo "Missing unit file: $unit_path"
+      exit 1
+    fi
+    assert_entrypoint "$unit_path" "$install_expected"
+
+    eval "$doctor_cmd"
+
+    assert_entrypoint "$unit_path" "$doctor_expected"
+  }
+
+  run_flow \
+    "npm-to-git" \
+    "$npm_bin daemon install --force" \
+    "$npm_entry" \
+    "node $git_entry doctor --repair --force" \
+    "$git_entry"
+
+  run_flow \
+    "git-to-npm" \
+    "node $git_entry daemon install --force" \
+    "$git_entry" \
+    "$npm_bin doctor --repair --force" \
+    "$npm_entry"
+'

scripts/e2e/gateway-network-docker.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+IMAGE_NAME="openclaw-gateway-network-e2e"
+
+PORT="18789"
+TOKEN="e2e-$(date +%s)-$$"
+NET_NAME="openclaw-net-e2e-$$"
+GW_NAME="openclaw-gateway-e2e-$$"
+
+cleanup() {
+  docker rm -f "$GW_NAME" >/dev/null 2>&1 || true
+  docker network rm "$NET_NAME" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+echo "Building Docker image..."
+docker build -t "$IMAGE_NAME" -f "$ROOT_DIR/scripts/e2e/Dockerfile" "$ROOT_DIR"
+
+echo "Creating Docker network..."
+docker network create "$NET_NAME" >/dev/null
+
+echo "Starting gateway container..."
+	docker run --rm -d \
+	  --name "$GW_NAME" \
+	  --network "$NET_NAME" \
+	  -e "OPENCLAW_GATEWAY_TOKEN=$TOKEN" \
+	  -e "OPENCLAW_SKIP_CHANNELS=1" \
+	  -e "OPENCLAW_SKIP_GMAIL_WATCHER=1" \
+	  -e "OPENCLAW_SKIP_CRON=1" \
+	  -e "OPENCLAW_SKIP_CANVAS_HOST=1" \
+	  "$IMAGE_NAME" \
+  bash -lc "node dist/index.js gateway --port $PORT --bind lan --allow-unconfigured > /tmp/gateway-net-e2e.log 2>&1"
+
+echo "Waiting for gateway to come up..."
+for _ in $(seq 1 20); do
+  if docker exec "$GW_NAME" bash -lc "grep -q \"listening on ws://\" /tmp/gateway-net-e2e.log"; then
+    break
+  fi
+  sleep 0.5
+done
+
+docker exec "$GW_NAME" bash -lc "tail -n 50 /tmp/gateway-net-e2e.log"
+
+echo "Running client container (connect + health)..."
+docker run --rm \
+  --network "$NET_NAME" \
+  -e "GW_URL=ws://$GW_NAME:$PORT" \
+  -e "GW_TOKEN=$TOKEN" \
+  "$IMAGE_NAME" \
+  bash -lc "node - <<'NODE'
+import { WebSocket } from \"ws\";
+import { PROTOCOL_VERSION } from \"./dist/gateway/protocol/index.js\";
+
+const url = process.env.GW_URL;
+const token = process.env.GW_TOKEN;
+if (!url || !token) throw new Error(\"missing GW_URL/GW_TOKEN\");
+
+const ws = new WebSocket(url);
+await new Promise((resolve, reject) => {
+  const t = setTimeout(() => reject(new Error(\"ws open timeout\")), 5000);
+  ws.once(\"open\", () => {
+    clearTimeout(t);
+    resolve();
+  });
+});
+
+function onceFrame(filter, timeoutMs = 5000) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error(\"timeout\")), timeoutMs);
+    const handler = (data) => {
+      const obj = JSON.parse(String(data));
+      if (!filter(obj)) return;
+      clearTimeout(t);
+      ws.off(\"message\", handler);
+      resolve(obj);
+    };
+    ws.on(\"message\", handler);
+  });
+}
+
+ws.send(
+  JSON.stringify({
+    type: \"req\",
+    id: \"c1\",
+    method: \"connect\",
+    params: {
+      minProtocol: PROTOCOL_VERSION,
+      maxProtocol: PROTOCOL_VERSION,
+      client: {
+        id: \"test\",
+        displayName: \"docker-net-e2e\",
+        version: \"dev\",
+        platform: process.platform,
+        mode: \"test\",
+      },
+      caps: [],
+      auth: { token },
+    },
+  }),
+	);
+	const connectRes = await onceFrame((o) => o?.type === \"res\" && o?.id === \"c1\");
+	if (!connectRes.ok) throw new Error(\"connect failed: \" + (connectRes.error?.message ?? \"unknown\"));
+
+	ws.send(JSON.stringify({ type: \"req\", id: \"h1\", method: \"health\" }));
+	const healthRes = await onceFrame((o) => o?.type === \"res\" && o?.id === \"h1\", 10000);
+	if (!healthRes.ok) throw new Error(\"health failed: \" + (healthRes.error?.message ?? \"unknown\"));
+	if (healthRes.payload?.ok !== true) throw new Error(\"unexpected health payload\");
+
+	ws.close();
+	console.log(\"ok\");
+NODE"
+
+echo "OK"