From 8dea2b124b7a5cf84d2316e16b828dd372eb6d3f Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 13:25:05 -0700 Subject: [PATCH 01/69] docs: rename VPS to Linux Server, update provider links for moved pages --- docs/platforms/linux.md | 2 +- docs/vps.md | 22 ++++++++++++++-------- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/platforms/linux.md b/docs/platforms/linux.md index c03dba6f795..522218ddc72 100644 --- a/docs/platforms/linux.md +++ b/docs/platforms/linux.md @@ -21,7 +21,7 @@ Native Linux companion apps are planned. Contributions are welcome if you want t 4. From your laptop: `ssh -N -L 18789:127.0.0.1:18789 @` 5. Open `http://127.0.0.1:18789/` and paste your token -Step-by-step VPS guide: [exe.dev](/install/exe-dev) +Full Linux server guide: [Linux Server](/vps). Step-by-step VPS example: [exe.dev](/install/exe-dev) ## Install diff --git a/docs/vps.md b/docs/vps.md index 2367043650e..4a1eb692c85 100644 --- a/docs/vps.md +++ b/docs/vps.md @@ -1,26 +1,32 @@ --- -summary: "VPS hosting hub for OpenClaw (Oracle/Fly/Hetzner/GCP/Azure/exe.dev)" +summary: "Run OpenClaw on a Linux server or cloud VPS — provider picker, architecture, and tuning" read_when: - - You want to run the Gateway in the cloud - - You need a quick map of VPS/hosting guides -title: "VPS Hosting" + - You want to run the Gateway on a Linux server or cloud VPS + - You need a quick map of hosting guides + - You want generic Linux server tuning for OpenClaw +title: "Linux Server" +sidebarTitle: "Linux Server" --- -# VPS Hosting +# Linux Server -Run the OpenClaw Gateway around the clock on a cloud VPS. This page helps you pick a provider, explains how cloud deployments work, and covers generic Linux server tuning that applies to every provider. +Run the OpenClaw Gateway on any Linux server or cloud VPS. This page helps you +pick a provider, explains how cloud deployments work, and covers generic Linux +tuning that applies everywhere. ## Pick a provider One-click, browser setup One-click, browser setup - Always Free ARM tier ($0/month, capacity can be finicky) + Simple paid VPS + Always Free ARM tier Fly Machines Docker on Hetzner VPS Compute Engine Linux VM VM with HTTPS proxy + ARM self-hosted **AWS (EC2 / Lightsail / free tier)** also works well. @@ -72,7 +78,7 @@ source ~/.bashrc - `NODE_COMPILE_CACHE` improves repeated command startup times. - `OPENCLAW_NO_RESPAWN=1` avoids extra startup overhead from a self-respawn path. - First command run warms the cache; subsequent runs are faster. -- For Raspberry Pi specifics, see [Raspberry Pi](/platforms/raspberry-pi). +- For Raspberry Pi specifics, see [Raspberry Pi](/install/raspberry-pi). ### systemd tuning checklist (optional) From 3de8c3d053f8ebde5816d38f4302cbb89907be9d Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 13:29:35 -0700 Subject: [PATCH 02/69] docs: move Oracle, DigitalOcean, Raspberry Pi to Install > Hosting, rewrite with Steps --- docs/docs.json | 20 ++++- docs/install/digitalocean.md | 129 ++++++++++++++++++++++++++++ docs/install/oracle.md | 156 ++++++++++++++++++++++++++++++++++ docs/install/raspberry-pi.md | 159 +++++++++++++++++++++++++++++++++++ 4 files changed, 460 insertions(+), 4 deletions(-) create mode 100644 docs/install/digitalocean.md create mode 100644 docs/install/oracle.md create mode 100644 docs/install/raspberry-pi.md diff --git a/docs/docs.json b/docs/docs.json index 6c46e660152..1ae8e5d34b8 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -52,6 +52,18 @@ ] }, "redirects": [ + { + "source": "/platforms/oracle", + "destination": "/install/oracle" + }, + { + "source": "/platforms/digitalocean", + "destination": "/install/digitalocean" + }, + { + "source": "/platforms/raspberry-pi", + "destination": "/install/raspberry-pi" + }, { "source": "/brave-search", "destination": "/tools/brave-search" @@ -885,6 +897,7 @@ "group": "Hosting", "pages": [ "install/azure", + "install/digitalocean", "install/docker-vm-runtime", "install/exe-dev", "install/fly", @@ -893,7 +906,9 @@ "install/kubernetes", "install/macos-vm", "install/northflank", + "install/oracle", "install/railway", + "install/raspberry-pi", "install/render", "vps" ] @@ -1164,10 +1179,7 @@ "platforms/linux", "platforms/windows", "platforms/android", - "platforms/ios", - "platforms/digitalocean", - "platforms/oracle", - "platforms/raspberry-pi" + "platforms/ios" ] }, { diff --git a/docs/install/digitalocean.md b/docs/install/digitalocean.md new file mode 100644 index 00000000000..92b2efc1e2d --- /dev/null +++ b/docs/install/digitalocean.md @@ -0,0 +1,129 @@ +--- +summary: "Host OpenClaw on a DigitalOcean Droplet" +read_when: + - Setting up OpenClaw on DigitalOcean + - Looking for a simple paid VPS for OpenClaw +title: "DigitalOcean" +--- + +# DigitalOcean + +Run a persistent OpenClaw Gateway on a DigitalOcean Droplet. + +## Prerequisites + +- DigitalOcean account ([signup](https://cloud.digitalocean.com/registrations/new)) +- SSH key pair (or willingness to use password auth) +- About 20 minutes + +## Setup + + + + + Use a clean base image (Ubuntu 24.04 LTS). Avoid third-party Marketplace 1-click images unless you have reviewed their startup scripts and firewall defaults. + + + 1. Log into [DigitalOcean](https://cloud.digitalocean.com/). + 2. Click **Create > Droplets**. + 3. Choose: + - **Region:** Closest to you + - **Image:** Ubuntu 24.04 LTS + - **Size:** Basic, Regular, 1 vCPU / 1 GB RAM / 25 GB SSD + - **Authentication:** SSH key (recommended) or password + 4. Click **Create Droplet** and note the IP address. + + + + + ```bash + ssh root@YOUR_DROPLET_IP + + apt update && apt upgrade -y + + # Install Node.js 24 + curl -fsSL https://deb.nodesource.com/setup_24.x | bash - + apt install -y nodejs + + # Install OpenClaw + curl -fsSL https://openclaw.ai/install.sh | bash + openclaw --version + ``` + + + + + ```bash + openclaw onboard --install-daemon + ``` + + The wizard walks you through model auth, channel setup, gateway token generation, and daemon installation (systemd). + + + + + ```bash + fallocate -l 2G /swapfile + chmod 600 /swapfile + mkswap /swapfile + swapon /swapfile + echo '/swapfile none swap sw 0 0' >> /etc/fstab + ``` + + + + ```bash + openclaw status + systemctl --user status openclaw-gateway.service + journalctl --user -u openclaw-gateway.service -f + ``` + + + + The gateway binds to loopback by default. Pick one of these options. + + **Option A: SSH tunnel (simplest)** + + ```bash + # From your local machine + ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP + ``` + + Then open `http://localhost:18789`. + + **Option B: Tailscale Serve** + + ```bash + curl -fsSL https://tailscale.com/install.sh | sh + tailscale up + openclaw config set gateway.tailscale.mode serve + openclaw gateway restart + ``` + + Then open `https:///` from any device on your tailnet. + + **Option C: Tailnet bind (no Serve)** + + ```bash + openclaw config set gateway.bind tailnet + openclaw gateway restart + ``` + + Then open `http://:18789` (token required). + + + + +## Troubleshooting + +**Gateway will not start** -- Run `openclaw doctor --non-interactive` and check logs with `journalctl --user -u openclaw-gateway.service -n 50`. + +**Port already in use** -- Run `lsof -i :18789` to find the process, then stop it. + +**Out of memory** -- Verify swap is active with `free -h`. If still hitting OOM, use API-based models (Claude, GPT) rather than local models, or upgrade to a 2 GB Droplet. + +## Next steps + +- [Channels](/channels) -- connect Telegram, WhatsApp, Discord, and more +- [Gateway configuration](/gateway/configuration) -- all config options +- [Updating](/install/updating) -- keep OpenClaw up to date diff --git a/docs/install/oracle.md b/docs/install/oracle.md new file mode 100644 index 00000000000..892674b5431 --- /dev/null +++ b/docs/install/oracle.md @@ -0,0 +1,156 @@ +--- +summary: "Host OpenClaw on Oracle Cloud's Always Free ARM tier" +read_when: + - Setting up OpenClaw on Oracle Cloud + - Looking for free VPS hosting for OpenClaw + - Want 24/7 OpenClaw on a small server +title: "Oracle Cloud" +--- + +# Oracle Cloud + +Run a persistent OpenClaw Gateway on Oracle Cloud's **Always Free** ARM tier (up to 4 OCPU, 24 GB RAM, 200 GB storage) at no cost. + +## Prerequisites + +- Oracle Cloud account ([signup](https://www.oracle.com/cloud/free/)) -- see [community signup guide](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd) if you hit issues +- Tailscale account (free at [tailscale.com](https://tailscale.com)) +- An SSH key pair +- About 30 minutes + +## Setup + + + + 1. Log into [Oracle Cloud Console](https://cloud.oracle.com/). + 2. Navigate to **Compute > Instances > Create Instance**. + 3. Configure: + - **Name:** `openclaw` + - **Image:** Ubuntu 24.04 (aarch64) + - **Shape:** `VM.Standard.A1.Flex` (Ampere ARM) + - **OCPUs:** 2 (or up to 4) + - **Memory:** 12 GB (or up to 24 GB) + - **Boot volume:** 50 GB (up to 200 GB free) + - **SSH key:** Add your public key + 4. Click **Create** and note the public IP address. + + + If instance creation fails with "Out of capacity", try a different availability domain or retry later. Free tier capacity is limited. + + + + + + ```bash + ssh ubuntu@YOUR_PUBLIC_IP + + sudo apt update && sudo apt upgrade -y + sudo apt install -y build-essential + ``` + + `build-essential` is required for ARM compilation of some dependencies. + + + + + ```bash + sudo hostnamectl set-hostname openclaw + sudo passwd ubuntu + sudo loginctl enable-linger ubuntu + ``` + + Enabling linger keeps user services running after logout. + + + + + ```bash + curl -fsSL https://tailscale.com/install.sh | sh + sudo tailscale up --ssh --hostname=openclaw + ``` + + From now on, connect via Tailscale: `ssh ubuntu@openclaw`. + + + + + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash + source ~/.bashrc + ``` + + When prompted "How do you want to hatch your bot?", select **Do this later**. + + + + + Use token auth with Tailscale Serve for secure remote access. + + ```bash + openclaw config set gateway.bind loopback + openclaw config set gateway.auth.mode token + openclaw doctor --generate-gateway-token + openclaw config set gateway.tailscale.mode serve + openclaw config set gateway.trustedProxies '["127.0.0.1"]' + + systemctl --user restart openclaw-gateway + ``` + + + + + Block all traffic except Tailscale at the network edge: + + 1. Go to **Networking > Virtual Cloud Networks** in the OCI Console. + 2. Click your VCN, then **Security Lists > Default Security List**. + 3. **Remove** all ingress rules except `0.0.0.0/0 UDP 41641` (Tailscale). + 4. Keep default egress rules (allow all outbound). + + This blocks SSH on port 22, HTTP, HTTPS, and everything else at the network edge. You can only connect via Tailscale from this point on. + + + + + ```bash + openclaw --version + systemctl --user status openclaw-gateway + tailscale serve status + curl http://localhost:18789 + ``` + + Access the Control UI from any device on your tailnet: + + ``` + https://openclaw..ts.net/ + ``` + + Replace `` with your tailnet name (visible in `tailscale status`). + + + + +## Fallback: SSH tunnel + +If Tailscale Serve is not working, use an SSH tunnel from your local machine: + +```bash +ssh -L 18789:127.0.0.1:18789 ubuntu@openclaw +``` + +Then open `http://localhost:18789`. + +## Troubleshooting + +**Instance creation fails ("Out of capacity")** -- Free tier ARM instances are popular. Try a different availability domain or retry during off-peak hours. + +**Tailscale will not connect** -- Run `sudo tailscale up --ssh --hostname=openclaw --reset` to re-authenticate. + +**Gateway will not start** -- Run `openclaw doctor --non-interactive` and check logs with `journalctl --user -u openclaw-gateway -n 50`. + +**ARM binary issues** -- Most npm packages work on ARM64. For native binaries, look for `linux-arm64` or `aarch64` releases. Verify architecture with `uname -m`. + +## Next steps + +- [Channels](/channels) -- connect Telegram, WhatsApp, Discord, and more +- [Gateway configuration](/gateway/configuration) -- all config options +- [Updating](/install/updating) -- keep OpenClaw up to date diff --git a/docs/install/raspberry-pi.md b/docs/install/raspberry-pi.md new file mode 100644 index 00000000000..49e3d63b8dc --- /dev/null +++ b/docs/install/raspberry-pi.md @@ -0,0 +1,159 @@ +--- +summary: "Host OpenClaw on a Raspberry Pi for always-on self-hosting" +read_when: + - Setting up OpenClaw on a Raspberry Pi + - Running OpenClaw on ARM devices + - Building a cheap always-on personal AI +title: "Raspberry Pi" +--- + +# Raspberry Pi + +Run a persistent, always-on OpenClaw Gateway on a Raspberry Pi. Since the Pi is just the gateway (models run in the cloud via API), even a modest Pi handles the workload well. + +## Prerequisites + +- Raspberry Pi 4 or 5 with 2 GB+ RAM (4 GB recommended) +- MicroSD card (16 GB+) or USB SSD (better performance) +- Official Pi power supply +- Network connection (Ethernet or WiFi) +- 64-bit Raspberry Pi OS (required -- do not use 32-bit) +- About 30 minutes + +## Setup + + + + Use **Raspberry Pi OS Lite (64-bit)** -- no desktop needed for a headless server. + + 1. Download [Raspberry Pi Imager](https://www.raspberrypi.com/software/). + 2. Choose OS: **Raspberry Pi OS Lite (64-bit)**. + 3. In the settings dialog, pre-configure: + - Hostname: `gateway-host` + - Enable SSH + - Set username and password + - Configure WiFi (if not using Ethernet) + 4. Flash to your SD card or USB drive, insert it, and boot the Pi. + + + + + ```bash + ssh user@gateway-host + ``` + + + + ```bash + sudo apt update && sudo apt upgrade -y + sudo apt install -y git curl build-essential + + # Set timezone (important for cron and reminders) + sudo timedatectl set-timezone America/Chicago + ``` + + + + + ```bash + curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - + sudo apt install -y nodejs + node --version + ``` + + + + ```bash + sudo fallocate -l 2G /swapfile + sudo chmod 600 /swapfile + sudo mkswap /swapfile + sudo swapon /swapfile + echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab + + # Reduce swappiness for low-RAM devices + echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf + sudo sysctl -p + ``` + + + + + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash + ``` + + + + ```bash + openclaw onboard --install-daemon + ``` + + Follow the wizard. API keys are recommended over OAuth for headless devices. Telegram is the easiest channel to start with. + + + + + ```bash + openclaw status + sudo systemctl status openclaw + journalctl -u openclaw -f + ``` + + + + On your computer, get a dashboard URL from the Pi: + + ```bash + ssh user@gateway-host 'openclaw dashboard --no-open' + ``` + + Then create an SSH tunnel in another terminal: + + ```bash + ssh -N -L 18789:127.0.0.1:18789 user@gateway-host + ``` + + Open the printed URL in your local browser. For always-on remote access, see [Tailscale integration](/gateway/tailscale). + + + + +## Performance tips + +**Use a USB SSD** -- SD cards are slow and wear out. A USB SSD dramatically improves performance. See the [Pi USB boot guide](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot). + +**Enable module compile cache** -- Speeds up repeated CLI invocations on lower-power Pi hosts: + +```bash +grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret +export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache +mkdir -p /var/tmp/openclaw-compile-cache +export OPENCLAW_NO_RESPAWN=1 +EOF +source ~/.bashrc +``` + +**Reduce memory usage** -- For headless setups, free GPU memory and disable unused services: + +```bash +echo 'gpu_mem=16' | sudo tee -a /boot/config.txt +sudo systemctl disable bluetooth +``` + +## Troubleshooting + +**Out of memory** -- Verify swap is active with `free -h`. Disable unused services (`sudo systemctl disable cups bluetooth avahi-daemon`). Use API-based models only. + +**Slow performance** -- Use a USB SSD instead of an SD card. Check for CPU throttling with `vcgencmd get_throttled` (should return `0x0`). + +**Service will not start** -- Check logs with `journalctl -u openclaw --no-pager -n 100` and run `openclaw doctor --non-interactive`. + +**ARM binary issues** -- If a skill fails with "exec format error", check whether the binary has an ARM64 build. Verify architecture with `uname -m` (should show `aarch64`). + +**WiFi drops** -- Disable WiFi power management: `sudo iwconfig wlan0 power off`. + +## Next steps + +- [Channels](/channels) -- connect Telegram, WhatsApp, Discord, and more +- [Gateway configuration](/gateway/configuration) -- all config options +- [Updating](/install/updating) -- keep OpenClaw up to date From 7bc7dd055ad8c539e19d09dd6dba6600379f84bb Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 13:31:55 -0700 Subject: [PATCH 03/69] docs: sort Linux Server (vps) alphabetically in Hosting nav --- docs/docs.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 1ae8e5d34b8..bd7d01fc43b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -904,13 +904,13 @@ "install/gcp", "install/hetzner", "install/kubernetes", + "vps", "install/macos-vm", "install/northflank", "install/oracle", "install/railway", "install/raspberry-pi", - "install/render", - "vps" + "install/render" ] }, { From 0aa4950d21af10163244c8cd6d07016fd607ad77 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 09:06:02 -0700 Subject: [PATCH 04/69] fix(core): restore session reset defaults and type seams --- src/agents/acp-spawn.test.ts | 17 +++-- .../subagent-announce.format.e2e.test.ts | 21 +++--- src/auto-reply/command-auth.ts | 57 ++++++++++++++++- src/auto-reply/reply/acp-reset-target.ts | 64 +++++++++++++++++++ src/auto-reply/reply/mentions.ts | 15 ++++- src/auto-reply/reply/session.test.ts | 4 +- src/commands/channels/remove.ts | 9 +-- src/config/sessions/reset.ts | 2 +- src/config/sessions/sessions.test.ts | 8 +-- src/config/types.telegram.ts | 15 ++++- src/infra/outbound/message-action-spec.ts | 1 + src/plugin-sdk/core.ts | 1 + 12 files changed, 184 insertions(+), 30 deletions(-) diff --git a/src/agents/acp-spawn.test.ts b/src/agents/acp-spawn.test.ts index 0ca4dd2c903..ad6ad0391c0 100644 --- a/src/agents/acp-spawn.test.ts +++ b/src/agents/acp-spawn.test.ts @@ -16,6 +16,7 @@ import * as heartbeatWake from "../infra/heartbeat-wake.js"; import { __testing as sessionBindingServiceTesting, registerSessionBindingAdapter, + type SessionBindingAdapterCapabilities, type SessionBindingPlacement, type SessionBindingRecord, } from "../infra/outbound/session-binding-service.js"; @@ -104,9 +105,8 @@ function replaceSpawnConfig(next: OpenClawConfig): void { setRuntimeConfigSnapshot(hoisted.state.cfg); } -function createSessionBindingCapabilities() { +function createSessionBindingCapabilities(): SessionBindingAdapterCapabilities { return { - adapterAvailable: true, bindSupported: true, unbindSupported: true, placements: ["current", "child"] satisfies SessionBindingPlacement[], @@ -184,9 +184,16 @@ describe("spawnAcpDirect", () => { metaCleared: false, }); getAcpSessionManagerSpy.mockReset().mockReturnValue({ - initializeSession: async (params: AcpInitializeSessionInput) => - await hoisted.initializeSessionMock(params), - closeSession: async (params: AcpCloseSessionInput) => await hoisted.closeSessionMock(params), + initializeSession: async ( + params: Parameters< + ReturnType["initializeSession"] + >[0], + ) => await hoisted.initializeSessionMock(params), + closeSession: async ( + params: Parameters< + ReturnType["closeSession"] + >[0], + ) => await hoisted.closeSessionMock(params), } as unknown as ReturnType); hoisted.initializeSessionMock.mockReset().mockImplementation(async (argsUnknown: unknown) => { const args = argsUnknown as AcpInitializeSessionInput; diff --git a/src/agents/subagent-announce.format.e2e.test.ts b/src/agents/subagent-announce.format.e2e.test.ts index 265fda978e9..1fe179a05c9 100644 --- a/src/agents/subagent-announce.format.e2e.test.ts +++ b/src/agents/subagent-announce.format.e2e.test.ts @@ -49,6 +49,8 @@ type MockSubagentRun = { error?: string; }; }; +type SessionEntryFixture = Omit & { updatedAt?: number }; +type SessionStoreFixture = Record; const agentSpy = vi.fn(async (_req: AgentCallRequest) => ({ runId: "run-main", status: "ok" })); const sendSpy = vi.fn(async (_req: AgentCallRequest) => ({ runId: "send-main", status: "ok" })); @@ -119,8 +121,7 @@ const hookRunnerMock = { const chatHistoryMock = vi.fn(async (_sessionKey?: string) => ({ messages: [] as Array, })); -type TestSessionStore = Record>; -let sessionStore: TestSessionStore = {}; +let sessionStore: SessionStoreFixture = {}; let configOverride: OpenClawConfig = { session: { mainKey: "main", @@ -163,21 +164,21 @@ function toSessionEntry( } function loadSessionStoreFixture(): Record { - return new Proxy({} as Record, { - get(_target, key: string | symbol) { + return new Proxy(sessionStore, { + get(target, key: string | symbol) { if (typeof key !== "string") { return undefined; } - if (!(key in sessionStore) && key.includes(":subagent:")) { + if (!(key in target) && key.includes(":subagent:")) { return toSessionEntry(key, { inputTokens: 1, outputTokens: 1, totalTokens: 2, }); } - return toSessionEntry(key, sessionStore[key]); + return toSessionEntry(key, target[key]); }, - }); + }) as unknown as Record; } vi.mock("./subagent-registry.js", () => subagentRegistryMock); @@ -2387,7 +2388,7 @@ describe("subagent announce formatting", () => { requesterOrigin: { channel: "whatsapp", to: "+1555", accountId: "acct-main" }, }); sessionStore = { - "agent:main:subagent:orchestrator": undefined as unknown as Record, + "agent:main:subagent:orchestrator": undefined, }; const didAnnounce = await runSubagentAnnounceFlow({ @@ -2411,7 +2412,7 @@ describe("subagent announce formatting", () => { subagentRegistryMock.isSubagentSessionRunActive.mockReturnValue(false); subagentRegistryMock.resolveRequesterForChildSession.mockReturnValue(null); sessionStore = { - "agent:main:subagent:orchestrator": undefined as unknown as Record, + "agent:main:subagent:orchestrator": undefined, }; const didAnnounce = await runSubagentAnnounceFlow({ @@ -2574,7 +2575,7 @@ describe("subagent announce formatting", () => { embeddedRunMock.isEmbeddedPiRunActive.mockReturnValue(false); embeddedRunMock.isEmbeddedPiRunStreaming.mockReturnValue(false); subagentRegistryMock.isSubagentSessionRunActive.mockReturnValue(false); - sessionStore = testCase.sessionStoreFixture as Record>; + sessionStore = testCase.sessionStoreFixture as SessionStoreFixture; subagentRegistryMock.resolveRequesterForChildSession.mockReturnValue({ requesterSessionKey: "agent:main:main", requesterOrigin: { channel: "discord", accountId: "jaris-account" }, diff --git a/src/auto-reply/command-auth.ts b/src/auto-reply/command-auth.ts index 956c132d773..44e9f5f30db 100644 --- a/src/auto-reply/command-auth.ts +++ b/src/auto-reply/command-auth.ts @@ -30,6 +30,7 @@ function resolveProviderFromContext(ctx: MsgContext, cfg: OpenClawConfig): Chann } const direct = normalizeAnyChannelId(explicitMessageChannel ?? undefined) ?? + (explicitMessageChannel as ChannelId | undefined) ?? normalizeAnyChannelId(ctx.Provider) ?? normalizeAnyChannelId(ctx.Surface) ?? normalizeAnyChannelId(ctx.OriginatingChannel); @@ -46,6 +47,7 @@ function resolveProviderFromContext(ctx: MsgContext, cfg: OpenClawConfig): Chann } const normalized = normalizeAnyChannelId(normalizedCandidateChannel ?? undefined) ?? + (normalizedCandidateChannel as ChannelId | undefined) ?? normalizeAnyChannelId(candidate); if (normalized) { return normalized; @@ -254,6 +256,50 @@ function resolveSenderCandidates(params: { return normalized; } +function resolveFallbackAllowFrom(params: { + cfg: OpenClawConfig; + providerId?: ChannelId; + accountId?: string | null; +}): Array { + const providerId = params.providerId?.trim(); + if (!providerId) { + return []; + } + const channels = params.cfg.channels as + | Record< + string, + | { + allowFrom?: Array; + dm?: { allowFrom?: Array }; + accounts?: Record< + string, + { + allowFrom?: Array; + dm?: { allowFrom?: Array }; + } + >; + } + | undefined + > + | undefined; + const channelCfg = channels?.[providerId]; + const accountCfg = params.accountId ? channelCfg?.accounts?.[params.accountId] : undefined; + const allowFrom = + accountCfg?.allowFrom ?? + accountCfg?.dm?.allowFrom ?? + channelCfg?.allowFrom ?? + channelCfg?.dm?.allowFrom; + return Array.isArray(allowFrom) ? allowFrom : []; +} + +function resolveFallbackCommandOptions(providerId?: ChannelId): { + enforceOwnerForCommands: boolean; +} { + return { + enforceOwnerForCommands: providerId === "whatsapp", + }; +} + export function resolveCommandAuthorization(params: { ctx: MsgContext; cfg: OpenClawConfig; @@ -275,7 +321,11 @@ export function resolveCommandAuthorization(params: { const allowFromRaw = plugin?.config?.resolveAllowFrom ? plugin.config.resolveAllowFrom({ cfg, accountId: ctx.AccountId }) - : []; + : resolveFallbackAllowFrom({ + cfg, + providerId, + accountId: ctx.AccountId, + }); const allowFromList = formatAllowFromList({ plugin, cfg, @@ -344,7 +394,10 @@ export function resolveCommandAuthorization(params: { : undefined; const senderId = matchedSender ?? senderCandidates[0]; - const enforceOwner = Boolean(plugin?.commands?.enforceOwnerForCommands); + const enforceOwner = Boolean( + plugin?.commands?.enforceOwnerForCommands ?? + resolveFallbackCommandOptions(providerId).enforceOwnerForCommands, + ); const senderIsOwnerByIdentity = Boolean(matchedSender); const senderIsOwnerByScope = isInternalMessageChannel(ctx.Provider) && diff --git a/src/auto-reply/reply/acp-reset-target.ts b/src/auto-reply/reply/acp-reset-target.ts index b77d0f320cc..e89380e6024 100644 --- a/src/auto-reply/reply/acp-reset-target.ts +++ b/src/auto-reply/reply/acp-reset-target.ts @@ -1,4 +1,10 @@ +import { + buildConfiguredAcpSessionKey, + normalizeBindingConfig, + type ConfiguredAcpBindingChannel, +} from "../../acp/persistent-bindings.types.js"; import { resolveConfiguredBindingRecord } from "../../channels/plugins/binding-registry.js"; +import { listAcpBindings } from "../../config/bindings.js"; import type { OpenClawConfig } from "../../config/config.js"; import { getSessionBindingService } from "../../infra/outbound/session-binding-service.js"; import { DEFAULT_ACCOUNT_ID, isAcpSessionKey } from "../../routing/session-key.js"; @@ -7,6 +13,52 @@ function normalizeText(value: string | undefined | null): string { return value?.trim() ?? ""; } +function resolveRawConfiguredAcpSessionKey(params: { + cfg: OpenClawConfig; + channel: string; + accountId: string; + conversationId: string; + parentConversationId?: string; +}): string | undefined { + for (const binding of listAcpBindings(params.cfg)) { + const bindingChannel = normalizeText(binding.match.channel).toLowerCase(); + if (!bindingChannel || bindingChannel !== params.channel) { + continue; + } + + const bindingAccountId = normalizeText(binding.match.accountId); + if (bindingAccountId && bindingAccountId !== "*" && bindingAccountId !== params.accountId) { + continue; + } + + const peerId = normalizeText(binding.match.peer?.id); + const matchedConversationId = + peerId === params.conversationId + ? params.conversationId + : peerId && peerId === params.parentConversationId + ? params.parentConversationId + : undefined; + if (!matchedConversationId) { + continue; + } + + const acp = normalizeBindingConfig(binding.acp); + return buildConfiguredAcpSessionKey({ + channel: params.channel as ConfiguredAcpBindingChannel, + accountId: bindingAccountId && bindingAccountId !== "*" ? bindingAccountId : params.accountId, + conversationId: matchedConversationId, + ...(params.parentConversationId ? { parentConversationId: params.parentConversationId } : {}), + agentId: binding.agentId, + mode: acp.mode === "oneshot" ? "oneshot" : "persistent", + ...(acp.cwd ? { cwd: acp.cwd } : {}), + ...(acp.backend ? { backend: acp.backend } : {}), + ...(acp.label ? { label: acp.label } : {}), + }); + } + + return undefined; +} + export function resolveEffectiveResetTargetSessionKey(params: { cfg: OpenClawConfig; channel?: string | null; @@ -68,6 +120,18 @@ export function resolveEffectiveResetTargetSessionKey(params: { } return isAcpSessionKey(configuredSessionKey) ? configuredSessionKey : undefined; } + + const rawConfiguredSessionKey = resolveRawConfiguredAcpSessionKey({ + cfg: params.cfg, + channel, + accountId, + conversationId, + ...(parentConversationId ? { parentConversationId } : {}), + }); + if (rawConfiguredSessionKey) { + return rawConfiguredSessionKey; + } + if (params.fallbackToActiveAcpWhenUnbound === false) { return undefined; } diff --git a/src/auto-reply/reply/mentions.ts b/src/auto-reply/reply/mentions.ts index 5b60cf6688f..66c5dcd1e38 100644 --- a/src/auto-reply/reply/mentions.ts +++ b/src/auto-reply/reply/mentions.ts @@ -117,6 +117,17 @@ function resolveMentionPatterns(cfg: OpenClawConfig | undefined, agentId?: strin return derived.length > 0 ? derived : []; } +function resolveFallbackProviderMentionStripRegexes(providerId?: string | null): RegExp[] { + switch (providerId?.trim().toLowerCase()) { + case "discord": + return [/<@!?\d+>/gi]; + case "slack": + return [/<@[^>\s]+>/gi]; + default: + return []; + } +} + export function buildMentionRegexes(cfg: OpenClawConfig | undefined, agentId?: string): RegExp[] { const patterns = normalizeMentionPatterns(resolveMentionPatterns(cfg, agentId)); return compileMentionPatternsCached({ @@ -215,7 +226,9 @@ export function stripMentions( cache: mentionStripRegexCompileCache, warnRejected: false, }); - for (const re of [...configRegexes, ...providerRegexes]) { + const fallbackProviderRegexes = + providerRegexes.length > 0 ? [] : resolveFallbackProviderMentionStripRegexes(providerId); + for (const re of [...configRegexes, ...providerRegexes, ...fallbackProviderRegexes]) { result = result.replace(re, " "); } if (providerMentions?.stripMentions) { diff --git a/src/auto-reply/reply/session.test.ts b/src/auto-reply/reply/session.test.ts index 4218731e42e..6de8811faee 100644 --- a/src/auto-reply/reply/session.test.ts +++ b/src/auto-reply/reply/session.test.ts @@ -1846,7 +1846,7 @@ describe("persistSessionUsageUpdate", () => { }, }, }, - } as OpenClawConfig, + } satisfies OpenClawConfig, usage: { input: 2_000, output: 500, cacheRead: 1_000, cacheWrite: 200 }, lastCallUsage: { input: 800, output: 200, cacheRead: 300, cacheWrite: 50 }, providerUsed: "openai", @@ -1892,7 +1892,7 @@ describe("persistSessionUsageUpdate", () => { }, }, }, - } as OpenClawConfig, + } satisfies OpenClawConfig, usage: { input: 5_107, output: 1_827, cacheRead: 1_536, cacheWrite: 0 }, lastCallUsage: { input: 5_107, output: 1_827, cacheRead: 1_536, cacheWrite: 0 }, providerUsed: "openai-codex", diff --git a/src/commands/channels/remove.ts b/src/commands/channels/remove.ts index d35cd285fc7..4b508bf4f33 100644 --- a/src/commands/channels/remove.ts +++ b/src/commands/channels/remove.ts @@ -119,6 +119,7 @@ export async function channelsRemoveCommand( runtime.exit(1); return; } + const resolvedChannelId: ChatChannel = resolvedChannel; const resolvedAccountId = normalizeAccountId(accountId) ?? resolveChannelDefaultAccountId({ plugin, cfg }); const accountKey = resolvedAccountId || DEFAULT_ACCOUNT_ID; @@ -163,14 +164,14 @@ export async function channelsRemoveCommand( if (useWizard && prompter) { await prompter.outro( deleteConfig - ? `Deleted ${channelLabel(resolvedChannel)} account "${accountKey}".` - : `Disabled ${channelLabel(resolvedChannel)} account "${accountKey}".`, + ? `Deleted ${channelLabel(resolvedChannelId)} account "${accountKey}".` + : `Disabled ${channelLabel(resolvedChannelId)} account "${accountKey}".`, ); } else { runtime.log( deleteConfig - ? `Deleted ${channelLabel(resolvedChannel)} account "${accountKey}".` - : `Disabled ${channelLabel(resolvedChannel)} account "${accountKey}".`, + ? `Deleted ${channelLabel(resolvedChannelId)} account "${accountKey}".` + : `Disabled ${channelLabel(resolvedChannelId)} account "${accountKey}".`, ); } } diff --git a/src/config/sessions/reset.ts b/src/config/sessions/reset.ts index 278e8d65bf8..2390f2e1dd3 100644 --- a/src/config/sessions/reset.ts +++ b/src/config/sessions/reset.ts @@ -17,7 +17,7 @@ export type SessionFreshness = { idleExpiresAt?: number; }; -export const DEFAULT_RESET_MODE: SessionResetMode = "idle"; +export const DEFAULT_RESET_MODE: SessionResetMode = "daily"; export const DEFAULT_RESET_AT_HOUR = 4; const THREAD_SESSION_MARKERS = [":thread:", ":topic:"]; diff --git a/src/config/sessions/sessions.test.ts b/src/config/sessions/sessions.test.ts index a149a742c0d..ff38953aae2 100644 --- a/src/config/sessions/sessions.test.ts +++ b/src/config/sessions/sessions.test.ts @@ -143,18 +143,18 @@ describe("resolveSessionResetPolicy", () => { resetType: "group", }); - expect(groupPolicy.mode).toBe("idle"); + expect(groupPolicy.mode).toBe("daily"); }); }); - it("defaults idle resets to zero idle minutes so sessions do not auto reset", () => { + it("defaults to daily resets at 4am local time", () => { const policy = resolveSessionResetPolicy({ resetType: "direct", }); expect(policy).toMatchObject({ - mode: "idle", - idleMinutes: 0, + mode: "daily", + atHour: 4, }); }); diff --git a/src/config/types.telegram.ts b/src/config/types.telegram.ts index aa40cec7077..71ded650deb 100644 --- a/src/config/types.telegram.ts +++ b/src/config/types.telegram.ts @@ -30,6 +30,19 @@ export type TelegramActionConfig = { editForumTopic?: boolean; }; +export type TelegramThreadBindingsConfig = SessionThreadBindingsConfig & { + /** + * Allow `sessions_spawn({ thread: true })` to auto-create + bind Telegram + * topics for subagent sessions. Default: false (opt-in). + */ + spawnSubagentSessions?: boolean; + /** + * Allow `/acp spawn` to auto-create + bind Telegram topics for ACP + * sessions. Default: false (opt-in). + */ + spawnAcpSessions?: boolean; +}; + export type TelegramNetworkConfig = { /** Override Node's autoSelectFamily behavior (true = enable, false = disable). */ autoSelectFamily?: boolean; @@ -166,7 +179,7 @@ export type TelegramAccountConfig = { /** Per-action tool gating (default: true for all). */ actions?: TelegramActionConfig; /** Telegram thread/conversation binding overrides. */ - threadBindings?: SessionThreadBindingsConfig; + threadBindings?: TelegramThreadBindingsConfig; /** * Controls which user reactions trigger notifications: * - "off" (default): ignore all reactions diff --git a/src/infra/outbound/message-action-spec.ts b/src/infra/outbound/message-action-spec.ts index f5149e715ef..08ba61de0f8 100644 --- a/src/infra/outbound/message-action-spec.ts +++ b/src/infra/outbound/message-action-spec.ts @@ -58,6 +58,7 @@ export const MESSAGE_ACTION_TARGET_MODE: Record Date: Thu, 19 Mar 2026 09:06:39 -0700 Subject: [PATCH 05/69] fix(extensions): repair matrix contracts and test boundaries --- extensions/matrix/src/channel.ts | 6 +++--- .../src/matrix/monitor/handler.media-failure.test.ts | 1 + extensions/matrix/src/matrix/monitor/handler.test.ts | 1 + .../src/matrix/monitor/handler.thread-root-media.test.ts | 1 + test/helpers/extensions/plugin-routing.ts | 7 +++++++ 5 files changed, 13 insertions(+), 3 deletions(-) create mode 100644 test/helpers/extensions/plugin-routing.ts diff --git a/extensions/matrix/src/channel.ts b/extensions/matrix/src/channel.ts index 34b6b9610e3..e02e12d881d 100644 --- a/extensions/matrix/src/channel.ts +++ b/extensions/matrix/src/channel.ts @@ -434,7 +434,7 @@ export const matrixPlugin: ChannelPlugin = { // // INVARIANT: The import() below cannot hang because: // 1. It only loads local ESM modules with no circular awaits - // 2. Module initialization is synchronous (no top-level await in ./matrix/index.js) + // 2. Module initialization is synchronous (no top-level await in ./matrix/monitor/index.js) // 3. The lock only serializes the import phase, not the provider startup const previousLock = matrixStartupLock; let releaseLock: () => void = () => {}; @@ -445,9 +445,9 @@ export const matrixPlugin: ChannelPlugin = { // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles. // Wrap in try/finally to ensure lock is released even if import fails. - let monitorMatrixProvider: typeof import("./matrix/index.js").monitorMatrixProvider; + let monitorMatrixProvider: typeof import("./matrix/monitor/index.js").monitorMatrixProvider; try { - const module = await import("./matrix/index.js"); + const module = await import("./matrix/monitor/index.js"); monitorMatrixProvider = module.monitorMatrixProvider; } finally { // Release lock after import completes or fails diff --git a/extensions/matrix/src/matrix/monitor/handler.media-failure.test.ts b/extensions/matrix/src/matrix/monitor/handler.media-failure.test.ts index 25f17cb0254..d8a0432627b 100644 --- a/extensions/matrix/src/matrix/monitor/handler.media-failure.test.ts +++ b/extensions/matrix/src/matrix/monitor/handler.media-failure.test.ts @@ -104,6 +104,7 @@ function createHandlerHarness() { directTracker: { isDirectMessage: vi.fn().mockResolvedValue(true), }, + dropPreStartupMessages: true, getRoomInfo: vi.fn().mockResolvedValue({ name: "Media Room", canonicalAlias: "#media:example.org", diff --git a/extensions/matrix/src/matrix/monitor/handler.test.ts b/extensions/matrix/src/matrix/monitor/handler.test.ts index fc55012a6b5..a02a0a825fb 100644 --- a/extensions/matrix/src/matrix/monitor/handler.test.ts +++ b/extensions/matrix/src/matrix/monitor/handler.test.ts @@ -594,6 +594,7 @@ describe("matrix monitor handler pairing account scope", () => { directTracker: { isDirectMessage: async () => false, }, + dropPreStartupMessages: true, getRoomInfo: async () => ({ altAliases: [] }), getMemberDisplayName: async () => "sender", needsRoomAliasesForConfig: false, diff --git a/extensions/matrix/src/matrix/monitor/handler.thread-root-media.test.ts b/extensions/matrix/src/matrix/monitor/handler.thread-root-media.test.ts index c08452cd76b..c3d42d87d11 100644 --- a/extensions/matrix/src/matrix/monitor/handler.thread-root-media.test.ts +++ b/extensions/matrix/src/matrix/monitor/handler.thread-root-media.test.ts @@ -119,6 +119,7 @@ describe("createMatrixRoomMessageHandler thread root media", () => { directTracker: { isDirectMessage: vi.fn().mockResolvedValue(true), }, + dropPreStartupMessages: true, getRoomInfo: vi.fn().mockResolvedValue({ name: "Media Room", canonicalAlias: "#media:example.org", diff --git a/test/helpers/extensions/plugin-routing.ts b/test/helpers/extensions/plugin-routing.ts new file mode 100644 index 00000000000..33e8b0f67c1 --- /dev/null +++ b/test/helpers/extensions/plugin-routing.ts @@ -0,0 +1,7 @@ +export { + __testing as sessionBindingTesting, + registerSessionBindingAdapter, +} from "../../../src/infra/outbound/session-binding-service.js"; +export { setActivePluginRegistry } from "../../../src/plugins/runtime.js"; +export { resolveAgentRoute } from "../../../src/routing/resolve-route.js"; +export { createTestRegistry } from "../../../src/test-utils/channel-plugins.js"; From 7bbd01379e76a17a55427a1aeb76108dd047a427 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 09:06:55 -0700 Subject: [PATCH 06/69] fix(deps): use https git sources for extension installs --- extensions/tlon/src/tloncorp-api.d.ts | 14 ++++++++++++++ pnpm-lock.yaml | 16 ++++++++-------- 2 files changed, 22 insertions(+), 8 deletions(-) create mode 100644 extensions/tlon/src/tloncorp-api.d.ts diff --git a/extensions/tlon/src/tloncorp-api.d.ts b/extensions/tlon/src/tloncorp-api.d.ts new file mode 100644 index 00000000000..c14eba98133 --- /dev/null +++ b/extensions/tlon/src/tloncorp-api.d.ts @@ -0,0 +1,14 @@ +declare module "@tloncorp/api" { + export function configureClient(params: { + shipUrl: string; + shipName: string; + verbose: boolean; + getCode: () => Promise; + }): void; + + export function uploadFile(params: { + blob: Blob; + fileName: string; + contentType: string; + }): Promise<{ url: string }>; +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5460d7e72cb..ba0d4e1ad3a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -535,7 +535,7 @@ importers: dependencies: '@tloncorp/api': specifier: git+https://github.com/tloncorp/api-beta.git#7eede1c1a756977b09f96aa14a92e2b06318ae87 - version: https://codeload.github.com/tloncorp/api-beta/tar.gz/7eede1c1a756977b09f96aa14a92e2b06318ae87 + version: git+https://github.com/tloncorp/api-beta.git#7eede1c1a756977b09f96aa14a92e2b06318ae87 '@tloncorp/tlon-skill': specifier: 0.2.2 version: 0.2.2 @@ -3237,8 +3237,8 @@ packages: resolution: {integrity: sha512-5Kc5CM2Ysn3vTTArBs2vESUt0AQiWZA86yc1TI3B+lxXmtEq133C1nxXNOgnzhrivdPZIh3zLj5gDnZjoLL5GA==} engines: {node: '>=12.17.0'} - '@tloncorp/api@https://codeload.github.com/tloncorp/api-beta/tar.gz/7eede1c1a756977b09f96aa14a92e2b06318ae87': - resolution: {tarball: https://codeload.github.com/tloncorp/api-beta/tar.gz/7eede1c1a756977b09f96aa14a92e2b06318ae87} + '@tloncorp/api@git+https://github.com/tloncorp/api-beta.git#7eede1c1a756977b09f96aa14a92e2b06318ae87': + resolution: {commit: 7eede1c1a756977b09f96aa14a92e2b06318ae87, repo: https://github.com/tloncorp/api-beta.git, type: git} version: 0.0.2 '@tloncorp/tlon-skill-darwin-arm64@0.2.2': @@ -3548,8 +3548,8 @@ packages: link-preview-js: optional: true - '@whiskeysockets/libsignal-node@https://codeload.github.com/whiskeysockets/libsignal-node/tar.gz/1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67': - resolution: {tarball: https://codeload.github.com/whiskeysockets/libsignal-node/tar.gz/1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67} + '@whiskeysockets/libsignal-node@git+https://github.com/whiskeysockets/libsignal-node.git#1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67': + resolution: {commit: 1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67, repo: https://github.com/whiskeysockets/libsignal-node.git, type: git} version: 2.0.1 abbrev@1.1.1: @@ -10124,7 +10124,7 @@ snapshots: '@tinyhttp/content-disposition@2.2.4': {} - '@tloncorp/api@https://codeload.github.com/tloncorp/api-beta/tar.gz/7eede1c1a756977b09f96aa14a92e2b06318ae87': + '@tloncorp/api@git+https://github.com/tloncorp/api-beta.git#7eede1c1a756977b09f96aa14a92e2b06318ae87': dependencies: '@aws-sdk/client-s3': 3.1000.0 '@aws-sdk/s3-request-presigner': 3.1000.0 @@ -10515,7 +10515,7 @@ snapshots: '@cacheable/node-cache': 1.7.6 '@hapi/boom': 9.1.4 async-mutex: 0.5.0 - libsignal: '@whiskeysockets/libsignal-node@https://codeload.github.com/whiskeysockets/libsignal-node/tar.gz/1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67' + libsignal: '@whiskeysockets/libsignal-node@git+https://github.com/whiskeysockets/libsignal-node.git#1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67' lru-cache: 11.2.7 music-metadata: 11.12.3 p-queue: 9.1.0 @@ -10531,7 +10531,7 @@ snapshots: - supports-color - utf-8-validate - '@whiskeysockets/libsignal-node@https://codeload.github.com/whiskeysockets/libsignal-node/tar.gz/1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67': + '@whiskeysockets/libsignal-node@git+https://github.com/whiskeysockets/libsignal-node.git#1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67': dependencies: curve25519-js: 0.0.4 protobufjs: 6.8.8 From 3b79494cbf72d06feb55591d28f03154e65451ca Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 12:17:25 -0700 Subject: [PATCH 07/69] fix(runtime): lazy-load setup shims and align contracts --- extensions/discord/src/account-inspect.ts | 2 +- extensions/discord/src/accounts.ts | 6 +- extensions/discord/src/channel.runtime.ts | 6 +- extensions/discord/src/setup-account-state.ts | 163 +++++++ extensions/discord/src/setup-core.ts | 63 +-- .../discord/src/setup-runtime-helpers.ts | 436 ++++++++++++++++++ extensions/discord/src/setup-surface.ts | 30 +- .../monitor/handler.media-failure.test.ts | 1 - .../matrix/src/matrix/monitor/handler.test.ts | 1 - .../monitor/handler.thread-root-media.test.ts | 1 - package.json | 8 + scripts/lib/plugin-sdk-entrypoints.json | 2 + src/agents/acp-spawn.test.ts | 5 +- src/channels/plugins/contracts/registry.ts | 110 +++-- src/channels/plugins/contracts/suites.ts | 2 +- src/channels/plugins/setup-wizard-helpers.ts | 15 +- src/cli/command-secret-gateway.ts | 31 +- .../message-action-runner.context.test.ts | 159 +++++-- src/infra/outbound/message-action-spec.ts | 1 - src/plugin-sdk/core.ts | 1 - src/plugin-sdk/setup-adapter-runtime.ts | 1 + src/plugin-sdk/setup-runtime.ts | 25 + 22 files changed, 909 insertions(+), 160 deletions(-) create mode 100644 extensions/discord/src/setup-account-state.ts create mode 100644 extensions/discord/src/setup-runtime-helpers.ts create mode 100644 src/plugin-sdk/setup-adapter-runtime.ts create mode 100644 src/plugin-sdk/setup-runtime.ts diff --git a/extensions/discord/src/account-inspect.ts b/extensions/discord/src/account-inspect.ts index 9f13b612dab..7e0a28ec7fd 100644 --- a/extensions/discord/src/account-inspect.ts +++ b/extensions/discord/src/account-inspect.ts @@ -3,12 +3,12 @@ import { hasConfiguredSecretInput, normalizeSecretInputString, } from "openclaw/plugin-sdk/config-runtime"; -import type { DiscordAccountConfig, OpenClawConfig } from "openclaw/plugin-sdk/discord-core"; import { mergeDiscordAccountConfig, resolveDefaultDiscordAccountId, resolveDiscordAccountConfig, } from "./accounts.js"; +import type { DiscordAccountConfig, OpenClawConfig } from "./runtime-api.js"; export type DiscordCredentialStatus = "available" | "configured_unavailable" | "missing"; diff --git a/extensions/discord/src/accounts.ts b/extensions/discord/src/accounts.ts index ab014f4bc4a..a323120a787 100644 --- a/extensions/discord/src/accounts.ts +++ b/extensions/discord/src/accounts.ts @@ -3,12 +3,8 @@ import { createAccountListHelpers, } from "openclaw/plugin-sdk/account-helpers"; import { normalizeAccountId } from "openclaw/plugin-sdk/account-id"; -import type { - DiscordAccountConfig, - DiscordActionConfig, - OpenClawConfig, -} from "openclaw/plugin-sdk/discord-core"; import { resolveAccountEntry } from "openclaw/plugin-sdk/routing"; +import type { DiscordAccountConfig, DiscordActionConfig, OpenClawConfig } from "./runtime-api.js"; import { resolveDiscordToken } from "./token.js"; export type ResolvedDiscordAccount = { diff --git a/extensions/discord/src/channel.runtime.ts b/extensions/discord/src/channel.runtime.ts index d4da518fdc1..263cba44e35 100644 --- a/extensions/discord/src/channel.runtime.ts +++ b/extensions/discord/src/channel.runtime.ts @@ -1,5 +1,7 @@ -import { discordSetupWizard as discordSetupWizardImpl } from "./setup-surface.js"; +import { createDiscordSetupWizardProxy } from "./setup-core.js"; type DiscordSetupWizard = typeof import("./setup-surface.js").discordSetupWizard; -export const discordSetupWizard: DiscordSetupWizard = { ...discordSetupWizardImpl }; +export const discordSetupWizard: DiscordSetupWizard = createDiscordSetupWizardProxy( + async () => (await import("./setup-surface.js")).discordSetupWizard, +); diff --git a/extensions/discord/src/setup-account-state.ts b/extensions/discord/src/setup-account-state.ts new file mode 100644 index 00000000000..725e6e4037e --- /dev/null +++ b/extensions/discord/src/setup-account-state.ts @@ -0,0 +1,163 @@ +import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id"; +import { + hasConfiguredSecretInput, + normalizeSecretInputString, + type OpenClawConfig, +} from "openclaw/plugin-sdk/config-runtime"; +import type { DiscordAccountConfig } from "./runtime-api.js"; +import { resolveDiscordToken } from "./token.js"; + +export type InspectedDiscordSetupAccount = { + accountId: string; + enabled: boolean; + token: string; + tokenSource: "env" | "config" | "none"; + tokenStatus: "available" | "configured_unavailable" | "missing"; + configured: boolean; + config: DiscordAccountConfig; +}; + +function resolveDiscordAccountEntry( + cfg: OpenClawConfig, + accountId: string, +): DiscordAccountConfig | undefined { + const accounts = cfg.channels?.discord?.accounts; + if (!accounts || typeof accounts !== "object" || Array.isArray(accounts)) { + return undefined; + } + const normalized = normalizeAccountId(accountId); + const direct = accounts[normalized]; + if (direct) { + return direct; + } + const matchKey = Object.keys(accounts).find((key) => normalizeAccountId(key) === normalized); + return matchKey ? accounts[matchKey] : undefined; +} + +function inspectConfiguredToken(value: unknown): { + token: string; + tokenSource: "config"; + tokenStatus: "available" | "configured_unavailable"; +} | null { + const normalized = normalizeSecretInputString(value); + if (normalized) { + return { + token: normalized.replace(/^Bot\s+/i, ""), + tokenSource: "config", + tokenStatus: "available", + }; + } + if (hasConfiguredSecretInput(value)) { + return { + token: "", + tokenSource: "config", + tokenStatus: "configured_unavailable", + }; + } + return null; +} + +export function listDiscordSetupAccountIds(cfg: OpenClawConfig): string[] { + const accounts = cfg.channels?.discord?.accounts; + const ids = + accounts && typeof accounts === "object" && !Array.isArray(accounts) + ? Object.keys(accounts) + .map((accountId) => normalizeAccountId(accountId)) + .filter(Boolean) + : []; + return [...new Set([DEFAULT_ACCOUNT_ID, ...ids])]; +} + +export function resolveDefaultDiscordSetupAccountId(cfg: OpenClawConfig): string { + return listDiscordSetupAccountIds(cfg)[0] ?? DEFAULT_ACCOUNT_ID; +} + +export function resolveDiscordSetupAccountConfig(params: { + cfg: OpenClawConfig; + accountId?: string | null; +}): { accountId: string; config: DiscordAccountConfig } { + const accountId = normalizeAccountId(params.accountId ?? DEFAULT_ACCOUNT_ID); + const { accounts: _ignored, ...base } = (params.cfg.channels?.discord ?? + {}) as DiscordAccountConfig & { + accounts?: unknown; + }; + return { + accountId, + config: { + ...base, + ...(resolveDiscordAccountEntry(params.cfg, accountId) ?? {}), + }, + }; +} + +export function inspectDiscordSetupAccount(params: { + cfg: OpenClawConfig; + accountId?: string | null; +}): InspectedDiscordSetupAccount { + const { accountId, config } = resolveDiscordSetupAccountConfig(params); + const enabled = params.cfg.channels?.discord?.enabled !== false && config.enabled !== false; + const accountConfig = resolveDiscordAccountEntry(params.cfg, accountId); + const hasAccountToken = Boolean( + accountConfig && + Object.prototype.hasOwnProperty.call(accountConfig as Record, "token"), + ); + const accountToken = inspectConfiguredToken(accountConfig?.token); + if (accountToken) { + return { + accountId, + enabled, + token: accountToken.token, + tokenSource: accountToken.tokenSource, + tokenStatus: accountToken.tokenStatus, + configured: true, + config, + }; + } + if (hasAccountToken) { + return { + accountId, + enabled, + token: "", + tokenSource: "none", + tokenStatus: "missing", + configured: false, + config, + }; + } + + const channelToken = inspectConfiguredToken(params.cfg.channels?.discord?.token); + if (channelToken) { + return { + accountId, + enabled, + token: channelToken.token, + tokenSource: channelToken.tokenSource, + tokenStatus: channelToken.tokenStatus, + configured: true, + config, + }; + } + + const tokenResolution = resolveDiscordToken(params.cfg, { accountId }); + if (tokenResolution.token) { + return { + accountId, + enabled, + token: tokenResolution.token, + tokenSource: tokenResolution.source, + tokenStatus: "available", + configured: true, + config, + }; + } + + return { + accountId, + enabled, + token: "", + tokenSource: "none", + tokenStatus: "missing", + configured: false, + config, + }; +} diff --git a/extensions/discord/src/setup-core.ts b/extensions/discord/src/setup-core.ts index 7e82a9bcc35..e8bf6bb424d 100644 --- a/extensions/discord/src/setup-core.ts +++ b/extensions/discord/src/setup-core.ts @@ -1,24 +1,27 @@ +import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id"; import type { DiscordGuildEntry } from "openclaw/plugin-sdk/config-runtime"; +import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime"; +import { createEnvPatchedAccountSetupAdapter } from "openclaw/plugin-sdk/setup-adapter-runtime"; +import type { + ChannelSetupAdapter, + ChannelSetupDmPolicy, + ChannelSetupWizard, +} from "openclaw/plugin-sdk/setup-runtime"; +import { formatDocsLink } from "openclaw/plugin-sdk/setup-tools"; +import { + inspectDiscordSetupAccount, + listDiscordSetupAccountIds, + resolveDiscordSetupAccountConfig, +} from "./setup-account-state.js"; import { createAccountScopedAllowFromSection, createAccountScopedGroupAccessSection, + createAllowlistSetupWizardProxy, createLegacyCompatChannelDmPolicy, - DEFAULT_ACCOUNT_ID, - createEnvPatchedAccountSetupAdapter, parseMentionOrPrefixedId, patchChannelConfigForAccount, setSetupChannelEnabled, - type OpenClawConfig, -} from "openclaw/plugin-sdk/setup"; -import { - createAllowlistSetupWizardProxy, - type ChannelSetupAdapter, - type ChannelSetupDmPolicy, - type ChannelSetupWizard, -} from "openclaw/plugin-sdk/setup"; -import { formatDocsLink } from "openclaw/plugin-sdk/setup-tools"; -import { inspectDiscordAccount } from "./account-inspect.js"; -import { listDiscordAccountIds, resolveDiscordAccount } from "./accounts.js"; +} from "./setup-runtime-helpers.js"; const channel = "discord" as const; @@ -104,8 +107,8 @@ export function createDiscordSetupWizardBase(handlers: { configuredScore: 2, unconfiguredScore: 1, resolveConfigured: ({ cfg }) => - listDiscordAccountIds(cfg).some((accountId) => { - const account = inspectDiscordAccount({ cfg, accountId }); + listDiscordSetupAccountIds(cfg).some((accountId) => { + const account = inspectDiscordSetupAccount({ cfg, accountId }); return account.configured; }), }, @@ -122,7 +125,7 @@ export function createDiscordSetupWizardBase(handlers: { inputPrompt: "Enter Discord bot token", allowEnv: ({ accountId }: { accountId: string }) => accountId === DEFAULT_ACCOUNT_ID, inspect: ({ cfg, accountId }: { cfg: OpenClawConfig; accountId: string }) => { - const account = inspectDiscordAccount({ cfg, accountId }); + const account = inspectDiscordSetupAccount({ cfg, accountId }); return { accountConfigured: account.configured, hasConfiguredValue: account.tokenStatus !== "missing", @@ -136,25 +139,24 @@ export function createDiscordSetupWizardBase(handlers: { }, ], groupAccess: createAccountScopedGroupAccessSection({ - channel, label: "Discord channels", placeholder: "My Server/#general, guildId/channelId, #support", currentPolicy: ({ cfg, accountId }: { cfg: OpenClawConfig; accountId: string }) => - resolveDiscordAccount({ cfg, accountId }).config.groupPolicy ?? "allowlist", + resolveDiscordSetupAccountConfig({ cfg, accountId }).config.groupPolicy ?? "allowlist", currentEntries: ({ cfg, accountId }: { cfg: OpenClawConfig; accountId: string }) => - Object.entries(resolveDiscordAccount({ cfg, accountId }).config.guilds ?? {}).flatMap( - ([guildKey, value]) => { - const channels = value?.channels ?? {}; - const channelKeys = Object.keys(channels); - if (channelKeys.length === 0) { - const input = /^\d+$/.test(guildKey) ? `guild:${guildKey}` : guildKey; - return [input]; - } - return channelKeys.map((channelKey) => `${guildKey}/${channelKey}`); - }, - ), + Object.entries( + resolveDiscordSetupAccountConfig({ cfg, accountId }).config.guilds ?? {}, + ).flatMap(([guildKey, value]) => { + const channels = value?.channels ?? {}; + const channelKeys = Object.keys(channels); + if (channelKeys.length === 0) { + const input = /^\d+$/.test(guildKey) ? `guild:${guildKey}` : guildKey; + return [input]; + } + return channelKeys.map((channelKey) => `${guildKey}/${channelKey}`); + }), updatePrompt: ({ cfg, accountId }: { cfg: OpenClawConfig; accountId: string }) => - Boolean(resolveDiscordAccount({ cfg, accountId }).config.guilds), + Boolean(resolveDiscordSetupAccountConfig({ cfg, accountId }).config.guilds), resolveAllowlist: handlers.resolveGroupAllowlist, fallbackResolved: (entries) => entries.map((input) => ({ input, resolved: false })), applyAllowlist: ({ @@ -168,7 +170,6 @@ export function createDiscordSetupWizardBase(handlers: { }) => setDiscordGuildChannelAllowlist(cfg, accountId, resolved as never), }), allowFrom: createAccountScopedAllowFromSection({ - channel, credentialInputKey: "token", helpTitle: "Discord allowlist", helpLines: [ diff --git a/extensions/discord/src/setup-runtime-helpers.ts b/extensions/discord/src/setup-runtime-helpers.ts new file mode 100644 index 00000000000..0d5cfff68a4 --- /dev/null +++ b/extensions/discord/src/setup-runtime-helpers.ts @@ -0,0 +1,436 @@ +import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id"; +import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime"; +import type { + ChannelSetupDmPolicy, + ChannelSetupWizard, + WizardPrompter, +} from "openclaw/plugin-sdk/setup-runtime"; +import { + resolveDefaultDiscordSetupAccountId, + resolveDiscordSetupAccountConfig, +} from "./setup-account-state.js"; + +export function parseMentionOrPrefixedId(params: { + value: string; + mentionPattern: RegExp; + prefixPattern?: RegExp; + idPattern: RegExp; + normalizeId?: (id: string) => string; +}): string | null { + const trimmed = params.value.trim(); + if (!trimmed) { + return null; + } + const mentionMatch = trimmed.match(params.mentionPattern); + if (mentionMatch?.[1]) { + return params.normalizeId ? params.normalizeId(mentionMatch[1]) : mentionMatch[1]; + } + if (params.prefixPattern?.test(trimmed)) { + const stripped = trimmed.replace(params.prefixPattern, "").trim(); + if (!stripped || !params.idPattern.test(stripped)) { + return null; + } + return params.normalizeId ? params.normalizeId(stripped) : stripped; + } + if (!params.idPattern.test(trimmed)) { + return null; + } + return params.normalizeId ? params.normalizeId(trimmed) : trimmed; +} + +function splitSetupEntries(raw: string): string[] { + return raw + .split(/[\n,;]+/g) + .map((entry) => entry.trim()) + .filter(Boolean); +} + +function mergeAllowFromEntries( + current: Array | null | undefined, + additions: Array, +): string[] { + const merged = [...(current ?? []), ...additions] + .map((value) => String(value).trim()) + .filter(Boolean); + return [...new Set(merged)]; +} + +function patchDiscordChannelConfigForAccount(params: { + cfg: OpenClawConfig; + accountId: string; + patch: Record; +}): OpenClawConfig { + const accountId = normalizeAccountId(params.accountId); + const channelConfig = (params.cfg.channels?.discord as Record | undefined) ?? {}; + if (accountId === DEFAULT_ACCOUNT_ID) { + return { + ...params.cfg, + channels: { + ...params.cfg.channels, + discord: { + ...channelConfig, + ...params.patch, + enabled: true, + }, + }, + }; + } + const accounts = + (channelConfig.accounts as Record> | undefined) ?? {}; + const accountConfig = accounts[accountId] ?? {}; + return { + ...params.cfg, + channels: { + ...params.cfg.channels, + discord: { + ...channelConfig, + enabled: true, + accounts: { + ...accounts, + [accountId]: { + ...accountConfig, + ...params.patch, + enabled: true, + }, + }, + }, + }, + }; +} + +export function setSetupChannelEnabled( + cfg: OpenClawConfig, + channel: string, + enabled: boolean, +): OpenClawConfig { + const channelConfig = (cfg.channels?.[channel] as Record | undefined) ?? {}; + return { + ...cfg, + channels: { + ...cfg.channels, + [channel]: { + ...channelConfig, + enabled, + }, + }, + }; +} + +export function patchChannelConfigForAccount(params: { + cfg: OpenClawConfig; + channel: "discord"; + accountId: string; + patch: Record; +}): OpenClawConfig { + return patchDiscordChannelConfigForAccount({ + cfg: params.cfg, + accountId: params.accountId, + patch: params.patch, + }); +} + +export function createLegacyCompatChannelDmPolicy(params: { + label: string; + channel: "discord"; + promptAllowFrom?: ChannelSetupDmPolicy["promptAllowFrom"]; +}): ChannelSetupDmPolicy { + return { + label: params.label, + channel: params.channel, + policyKey: `channels.${params.channel}.dmPolicy`, + allowFromKey: `channels.${params.channel}.allowFrom`, + getCurrent: (cfg) => + ( + cfg.channels?.[params.channel] as + | { + dmPolicy?: "open" | "pairing" | "allowlist"; + dm?: { policy?: "open" | "pairing" | "allowlist" }; + } + | undefined + )?.dmPolicy ?? + ( + cfg.channels?.[params.channel] as + | { + dmPolicy?: "open" | "pairing" | "allowlist"; + dm?: { policy?: "open" | "pairing" | "allowlist" }; + } + | undefined + )?.dm?.policy ?? + "pairing", + setPolicy: (cfg, policy) => + patchDiscordChannelConfigForAccount({ + cfg, + accountId: DEFAULT_ACCOUNT_ID, + patch: { + dmPolicy: policy, + ...(policy === "open" + ? { + allowFrom: [ + ...new Set( + [ + ...((( + cfg.channels?.discord as { allowFrom?: Array } | undefined + )?.allowFrom ?? []) as Array), + "*", + ] + .map((value) => String(value).trim()) + .filter(Boolean), + ), + ], + } + : {}), + }, + }), + ...(params.promptAllowFrom ? { promptAllowFrom: params.promptAllowFrom } : {}), + }; +} + +async function noteChannelLookupFailure(params: { + prompter: Pick; + label: string; + error: unknown; +}) { + await params.prompter.note( + `Channel lookup failed; keeping entries as typed. ${String(params.error)}`, + params.label, + ); +} + +export function createAccountScopedAllowFromSection(params: { + credentialInputKey?: NonNullable["credentialInputKey"]; + helpTitle?: string; + helpLines?: string[]; + message: string; + placeholder: string; + invalidWithoutCredentialNote: string; + parseId: NonNullable["parseId"]>; + resolveEntries: NonNullable["resolveEntries"]>; +}): NonNullable { + return { + ...(params.helpTitle ? { helpTitle: params.helpTitle } : {}), + ...(params.helpLines ? { helpLines: params.helpLines } : {}), + ...(params.credentialInputKey ? { credentialInputKey: params.credentialInputKey } : {}), + message: params.message, + placeholder: params.placeholder, + invalidWithoutCredentialNote: params.invalidWithoutCredentialNote, + parseId: params.parseId, + resolveEntries: params.resolveEntries, + apply: ({ cfg, accountId, allowFrom }) => + patchDiscordChannelConfigForAccount({ + cfg, + accountId, + patch: { dmPolicy: "allowlist", allowFrom }, + }), + }; +} + +export function createAccountScopedGroupAccessSection(params: { + label: string; + placeholder: string; + helpTitle?: string; + helpLines?: string[]; + skipAllowlistEntries?: boolean; + currentPolicy: NonNullable["currentPolicy"]; + currentEntries: NonNullable["currentEntries"]; + updatePrompt: NonNullable["updatePrompt"]; + resolveAllowlist?: NonNullable< + NonNullable["resolveAllowlist"] + >; + fallbackResolved: (entries: string[]) => TResolved; + applyAllowlist: (params: { + cfg: OpenClawConfig; + accountId: string; + resolved: TResolved; + }) => OpenClawConfig; +}): NonNullable { + return { + label: params.label, + placeholder: params.placeholder, + ...(params.helpTitle ? { helpTitle: params.helpTitle } : {}), + ...(params.helpLines ? { helpLines: params.helpLines } : {}), + ...(params.skipAllowlistEntries ? { skipAllowlistEntries: true } : {}), + currentPolicy: params.currentPolicy, + currentEntries: params.currentEntries, + updatePrompt: params.updatePrompt, + setPolicy: ({ cfg, accountId, policy }) => + patchDiscordChannelConfigForAccount({ + cfg, + accountId, + patch: { groupPolicy: policy }, + }), + ...(params.resolveAllowlist + ? { + resolveAllowlist: async ({ cfg, accountId, credentialValues, entries, prompter }) => { + try { + return await params.resolveAllowlist!({ + cfg, + accountId, + credentialValues, + entries, + prompter, + }); + } catch (error) { + await noteChannelLookupFailure({ + prompter, + label: params.label, + error, + }); + return params.fallbackResolved(entries); + } + }, + } + : {}), + applyAllowlist: ({ cfg, accountId, resolved }) => + params.applyAllowlist({ + cfg, + accountId, + resolved: resolved as TResolved, + }), + }; +} + +export function createAllowlistSetupWizardProxy(params: { + loadWizard: () => Promise; + createBase: (handlers: { + promptAllowFrom: NonNullable; + resolveAllowFromEntries: NonNullable< + NonNullable["resolveEntries"] + >; + resolveGroupAllowlist: NonNullable< + NonNullable["resolveAllowlist"]> + >; + }) => ChannelSetupWizard; + fallbackResolvedGroupAllowlist: (entries: string[]) => TGroupResolved; +}) { + return params.createBase({ + promptAllowFrom: async ({ cfg, prompter, accountId }) => { + const wizard = await params.loadWizard(); + if (!wizard.dmPolicy?.promptAllowFrom) { + return cfg; + } + return await wizard.dmPolicy.promptAllowFrom({ cfg, prompter, accountId }); + }, + resolveAllowFromEntries: async ({ cfg, accountId, credentialValues, entries }) => { + const wizard = await params.loadWizard(); + if (!wizard.allowFrom) { + return entries.map((input) => ({ input, resolved: false, id: null })); + } + return await wizard.allowFrom.resolveEntries({ + cfg, + accountId, + credentialValues, + entries, + }); + }, + resolveGroupAllowlist: async ({ cfg, accountId, credentialValues, entries, prompter }) => { + const wizard = await params.loadWizard(); + if (!wizard.groupAccess?.resolveAllowlist) { + return params.fallbackResolvedGroupAllowlist(entries) as Awaited< + ReturnType< + NonNullable["resolveAllowlist"]> + > + >; + } + return (await wizard.groupAccess.resolveAllowlist({ + cfg, + accountId, + credentialValues, + entries, + prompter, + })) as Awaited< + ReturnType["resolveAllowlist"]>> + >; + }, + }); +} + +export async function resolveEntriesWithOptionalToken(params: { + token?: string | null; + entries: string[]; + buildWithoutToken: (input: string) => TResult; + resolveEntries: (params: { token: string; entries: string[] }) => Promise; +}): Promise { + const token = params.token?.trim(); + if (!token) { + return params.entries.map(params.buildWithoutToken); + } + return await params.resolveEntries({ + token, + entries: params.entries, + }); +} + +export async function promptLegacyChannelAllowFromForAccount(params: { + cfg: OpenClawConfig; + prompter: WizardPrompter; + accountId?: string; + noteTitle: string; + noteLines: string[]; + message: string; + placeholder: string; + parseId: (value: string) => string | null; + invalidWithoutTokenNote: string; + resolveEntries: (params: { + token: string; + entries: string[]; + }) => Promise>; + resolveToken: (accountId: string) => string | null | undefined; + resolveExisting: (accountId: string, cfg: OpenClawConfig) => Array; +}): Promise { + const accountId = normalizeAccountId( + params.accountId ?? resolveDefaultDiscordSetupAccountId(params.cfg), + ); + await params.prompter.note(params.noteLines.join("\n"), params.noteTitle); + const token = params.resolveToken(accountId); + const existing = params.resolveExisting(accountId, params.cfg); + + while (true) { + const entry = await params.prompter.text({ + message: params.message, + placeholder: params.placeholder, + initialValue: existing[0] ? String(existing[0]) : undefined, + validate: (value) => (String(value ?? "").trim() ? undefined : "Required"), + }); + const parts = splitSetupEntries(String(entry)); + if (!token) { + const ids = parts.map(params.parseId).filter(Boolean) as string[]; + if (ids.length !== parts.length) { + await params.prompter.note(params.invalidWithoutTokenNote, params.noteTitle); + continue; + } + return patchDiscordChannelConfigForAccount({ + cfg: params.cfg, + accountId, + patch: { + dmPolicy: "allowlist", + allowFrom: mergeAllowFromEntries(existing, ids), + }, + }); + } + + const results = await params.resolveEntries({ token, entries: parts }).catch(() => null); + if (!results) { + await params.prompter.note("Failed to resolve usernames. Try again.", params.noteTitle); + continue; + } + const unresolved = results.filter((result) => !result.resolved || !result.id); + if (unresolved.length > 0) { + await params.prompter.note( + `Could not resolve: ${unresolved.map((result) => result.input).join(", ")}`, + params.noteTitle, + ); + continue; + } + return patchDiscordChannelConfigForAccount({ + cfg: params.cfg, + accountId, + patch: { + dmPolicy: "allowlist", + allowFrom: mergeAllowFromEntries( + existing, + results.map((result) => result.id as string), + ), + }, + }); + } +} diff --git a/extensions/discord/src/setup-surface.ts b/extensions/discord/src/setup-surface.ts index fae95d56916..a970ff5773b 100644 --- a/extensions/discord/src/setup-surface.ts +++ b/extensions/discord/src/setup-surface.ts @@ -1,20 +1,26 @@ import { - resolveEntriesWithOptionalToken, type OpenClawConfig, - promptLegacyChannelAllowFromForAccount, type WizardPrompter, -} from "openclaw/plugin-sdk/setup"; -import { type ChannelSetupWizard } from "openclaw/plugin-sdk/setup"; + type ChannelSetupWizard, +} from "openclaw/plugin-sdk/setup-runtime"; import { formatDocsLink } from "openclaw/plugin-sdk/setup-tools"; -import { resolveDefaultDiscordAccountId, resolveDiscordAccount } from "./accounts.js"; import { resolveDiscordChannelAllowlist } from "./resolve-channels.js"; import { resolveDiscordUserAllowlist } from "./resolve-users.js"; +import { + resolveDefaultDiscordSetupAccountId, + resolveDiscordSetupAccountConfig, +} from "./setup-account-state.js"; import { createDiscordSetupWizardBase, DISCORD_TOKEN_HELP_LINES, parseDiscordAllowFromId, setDiscordGuildChannelAllowlist, } from "./setup-core.js"; +import { + promptLegacyChannelAllowFromForAccount, + resolveEntriesWithOptionalToken, +} from "./setup-runtime-helpers.js"; +import { resolveDiscordToken } from "./token.js"; const channel = "discord" as const; @@ -48,13 +54,8 @@ async function promptDiscordAllowFrom(params: { }): Promise { return await promptLegacyChannelAllowFromForAccount({ cfg: params.cfg, - channel, prompter: params.prompter, accountId: params.accountId, - defaultAccountId: resolveDefaultDiscordAccountId(params.cfg), - resolveAccount: (cfg, accountId) => resolveDiscordAccount({ cfg, accountId }), - resolveExisting: (account) => account.config.allowFrom ?? account.config.dm?.allowFrom ?? [], - resolveToken: (account) => account.token, noteTitle: "Discord allowlist", noteLines: [ "Allowlist Discord DMs by username (we resolve to user ids).", @@ -69,6 +70,11 @@ async function promptDiscordAllowFrom(params: { placeholder: "@alice, 123456789012345678", parseId: parseDiscordAllowFromId, invalidWithoutTokenNote: "Bot token missing; use numeric user ids (or mention form) only.", + resolveExisting: (accountId, cfg) => { + const account = resolveDiscordSetupAccountConfig({ cfg, accountId }).config; + return account.allowFrom ?? account.dm?.allowFrom ?? []; + }, + resolveToken: (accountId) => resolveDiscordToken(params.cfg, { accountId }).token, resolveEntries: async ({ token, entries }) => ( await resolveDiscordUserAllowlist({ @@ -91,7 +97,7 @@ async function resolveDiscordGroupAllowlist(params: { }) { return await resolveEntriesWithOptionalToken({ token: - resolveDiscordAccount({ cfg: params.cfg, accountId: params.accountId }).token || + resolveDiscordToken(params.cfg, { accountId: params.accountId }).token || (typeof params.credentialValues.token === "string" ? params.credentialValues.token : ""), entries: params.entries, buildWithoutToken: (input) => ({ @@ -111,7 +117,7 @@ export const discordSetupWizard: ChannelSetupWizard = createDiscordSetupWizardBa resolveAllowFromEntries: async ({ cfg, accountId, credentialValues, entries }) => await resolveDiscordAllowFromEntries({ token: - resolveDiscordAccount({ cfg, accountId }).token || + resolveDiscordToken(cfg, { accountId }).token || (typeof credentialValues.token === "string" ? credentialValues.token : ""), entries, }), diff --git a/extensions/matrix/src/matrix/monitor/handler.media-failure.test.ts b/extensions/matrix/src/matrix/monitor/handler.media-failure.test.ts index d8a0432627b..45c7484d3ca 100644 --- a/extensions/matrix/src/matrix/monitor/handler.media-failure.test.ts +++ b/extensions/matrix/src/matrix/monitor/handler.media-failure.test.ts @@ -100,7 +100,6 @@ function createHandlerHarness() { mediaMaxBytes: 5 * 1024 * 1024, startupMs: Date.now() - 120_000, startupGraceMs: 60_000, - dropPreStartupMessages: false, directTracker: { isDirectMessage: vi.fn().mockResolvedValue(true), }, diff --git a/extensions/matrix/src/matrix/monitor/handler.test.ts b/extensions/matrix/src/matrix/monitor/handler.test.ts index a02a0a825fb..538de6c9a80 100644 --- a/extensions/matrix/src/matrix/monitor/handler.test.ts +++ b/extensions/matrix/src/matrix/monitor/handler.test.ts @@ -590,7 +590,6 @@ describe("matrix monitor handler pairing account scope", () => { mediaMaxBytes: 10_000_000, startupMs: 0, startupGraceMs: 0, - dropPreStartupMessages: false, directTracker: { isDirectMessage: async () => false, }, diff --git a/extensions/matrix/src/matrix/monitor/handler.thread-root-media.test.ts b/extensions/matrix/src/matrix/monitor/handler.thread-root-media.test.ts index c3d42d87d11..51f5a07bdd0 100644 --- a/extensions/matrix/src/matrix/monitor/handler.thread-root-media.test.ts +++ b/extensions/matrix/src/matrix/monitor/handler.thread-root-media.test.ts @@ -115,7 +115,6 @@ describe("createMatrixRoomMessageHandler thread root media", () => { mediaMaxBytes: 5 * 1024 * 1024, startupMs: Date.now() - 120_000, startupGraceMs: 60_000, - dropPreStartupMessages: false, directTracker: { isDirectMessage: vi.fn().mockResolvedValue(true), }, diff --git a/package.json b/package.json index 7d32a97fee5..e7142b76a54 100644 --- a/package.json +++ b/package.json @@ -77,6 +77,14 @@ "types": "./dist/plugin-sdk/setup.d.ts", "default": "./dist/plugin-sdk/setup.js" }, + "./plugin-sdk/setup-adapter-runtime": { + "types": "./dist/plugin-sdk/setup-adapter-runtime.d.ts", + "default": "./dist/plugin-sdk/setup-adapter-runtime.js" + }, + "./plugin-sdk/setup-runtime": { + "types": "./dist/plugin-sdk/setup-runtime.d.ts", + "default": "./dist/plugin-sdk/setup-runtime.js" + }, "./plugin-sdk/channel-setup": { "types": "./dist/plugin-sdk/channel-setup.d.ts", "default": "./dist/plugin-sdk/channel-setup.js" diff --git a/scripts/lib/plugin-sdk-entrypoints.json b/scripts/lib/plugin-sdk-entrypoints.json index 403f9523f1d..f9c20590e4b 100644 --- a/scripts/lib/plugin-sdk-entrypoints.json +++ b/scripts/lib/plugin-sdk-entrypoints.json @@ -9,6 +9,8 @@ "runtime", "runtime-env", "setup", + "setup-adapter-runtime", + "setup-runtime", "channel-setup", "setup-tools", "config-runtime", diff --git a/src/agents/acp-spawn.test.ts b/src/agents/acp-spawn.test.ts index ad6ad0391c0..c464b7d1b19 100644 --- a/src/agents/acp-spawn.test.ts +++ b/src/agents/acp-spawn.test.ts @@ -1,9 +1,6 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import * as acpSessionManager from "../acp/control-plane/manager.js"; -import type { - AcpCloseSessionInput, - AcpInitializeSessionInput, -} from "../acp/control-plane/manager.types.js"; +import type { AcpInitializeSessionInput } from "../acp/control-plane/manager.types.js"; import { clearRuntimeConfigSnapshot, setRuntimeConfigSnapshot, diff --git a/src/channels/plugins/contracts/registry.ts b/src/channels/plugins/contracts/registry.ts index 3068f790053..cc2b8b7f34a 100644 --- a/src/channels/plugins/contracts/registry.ts +++ b/src/channels/plugins/contracts/registry.ts @@ -1,4 +1,4 @@ -import fs from "node:fs/promises"; +import fs from "node:fs"; import os from "node:os"; import path from "node:path"; import { expect, vi } from "vitest"; @@ -7,7 +7,11 @@ import { createThreadBindingManager as createDiscordThreadBindingManager, } from "../../../../extensions/discord/runtime-api.js"; import { createFeishuThreadBindingManager } from "../../../../extensions/feishu/api.js"; -import { createMatrixThreadBindingManager } from "../../../../extensions/matrix/api.js"; +import { + createMatrixThreadBindingManager, + resetMatrixThreadBindingsForTests, +} from "../../../../extensions/matrix/api.js"; +import { setMatrixRuntime } from "../../../../extensions/matrix/index.js"; import { createTelegramThreadBindingManager } from "../../../../extensions/telegram/runtime-api.js"; import type { OpenClawConfig } from "../../../config/config.js"; import { @@ -181,6 +185,12 @@ function expectClearedSessionBinding(params: { const telegramDescribeMessageToolMock = vi.fn(); const discordDescribeMessageToolMock = vi.fn(); +const sendMessageMatrixMock = vi.hoisted(() => + vi.fn(async (to: string, _message: string, opts?: { threadId?: string }) => ({ + messageId: opts?.threadId ? "$matrix-thread" : "$matrix-root", + roomId: to.replace(/^room:/, ""), + })), +); bundledChannelRuntimeSetters.setTelegramRuntime({ channel: { @@ -213,6 +223,48 @@ bundledChannelRuntimeSetters.setLineRuntime({ }, } as never); +vi.mock("../../../../extensions/matrix/src/matrix/send.js", async () => { + const actual = await vi.importActual< + typeof import("../../../../extensions/matrix/src/matrix/send.js") + >("../../../../extensions/matrix/src/matrix/send.js"); + return { + ...actual, + sendMessageMatrix: sendMessageMatrixMock, + }; +}); + +const matrixSessionBindingStateDir = fs.mkdtempSync( + path.join(os.tmpdir(), "openclaw-matrix-session-binding-contract-"), +); +const matrixSessionBindingAuth = { + accountId: "ops", + homeserver: "https://matrix.example.org", + userId: "@bot:example.org", + accessToken: "token", +} as const; + +function resetMatrixSessionBindingStateDir() { + fs.rmSync(matrixSessionBindingStateDir, { recursive: true, force: true }); + fs.mkdirSync(matrixSessionBindingStateDir, { recursive: true }); +} + +async function createContractMatrixThreadBindingManager() { + resetMatrixSessionBindingStateDir(); + setMatrixRuntime({ + state: { + resolveStateDir: () => matrixSessionBindingStateDir, + }, + } as never); + return await createMatrixThreadBindingManager({ + accountId: matrixSessionBindingAuth.accountId, + auth: matrixSessionBindingAuth, + client: {} as never, + idleTimeoutMs: 24 * 60 * 60 * 1000, + maxAgeMs: 0, + enableSweeper: false, + }); +} + export const pluginContractRegistry: PluginContractEntry[] = bundledChannelPlugins.map( (plugin) => ({ id: plugin.id, @@ -595,24 +647,6 @@ const baseSessionBindingCfg = { session: { mainKey: "main", scope: "per-sender" }, } satisfies OpenClawConfig; -async function createContractMatrixThreadBindingManager() { - const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "matrix-contract-thread-bindings-")); - return await createMatrixThreadBindingManager({ - accountId: "ops", - auth: { - accountId: "ops", - homeserver: "https://matrix.example.org", - userId: "@bot:example.org", - accessToken: "token", - }, - client: {} as never, - stateDir, - idleTimeoutMs: 24 * 60 * 60 * 1000, - maxAgeMs: 0, - enableSweeper: false, - }); -} - export const sessionBindingContractRegistry: SessionBindingContractEntry[] = [ { id: "discord", @@ -744,47 +778,43 @@ export const sessionBindingContractRegistry: SessionBindingContractEntry[] = [ await createContractMatrixThreadBindingManager(); return getSessionBindingService().getCapabilities({ channel: "matrix", - accountId: "ops", + accountId: matrixSessionBindingAuth.accountId, }); }, bindAndResolve: async () => { await createContractMatrixThreadBindingManager(); const service = getSessionBindingService(); const binding = await service.bind({ - targetSessionKey: "agent:matrix:subagent:child-1", + targetSessionKey: "agent:matrix:child:thread-1", targetKind: "subagent", conversation: { channel: "matrix", - accountId: "ops", - conversationId: "!room:example", + accountId: matrixSessionBindingAuth.accountId, + conversationId: "$thread", + parentConversationId: "!room:example", }, - placement: "child", + placement: "current", metadata: { label: "codex-matrix", - introText: "intro root", }, }); expectResolvedSessionBinding({ channel: "matrix", - accountId: "ops", - conversationId: "$root", - parentConversationId: "!room:example", - targetSessionKey: "agent:matrix:subagent:child-1", + accountId: matrixSessionBindingAuth.accountId, + conversationId: "$thread", + targetSessionKey: "agent:matrix:child:thread-1", }); return binding; }, unbindAndVerify: unbindAndExpectClearedSessionBinding, cleanup: async () => { - const manager = await createContractMatrixThreadBindingManager(); - manager.stop(); - expect( - getSessionBindingService().resolveByConversation({ - channel: "matrix", - accountId: "ops", - conversationId: "$root", - parentConversationId: "!room:example", - }), - ).toBeNull(); + resetMatrixThreadBindingsForTests(); + resetMatrixSessionBindingStateDir(); + expectClearedSessionBinding({ + channel: "matrix", + accountId: matrixSessionBindingAuth.accountId, + conversationId: "$thread", + }); }, }, { diff --git a/src/channels/plugins/contracts/suites.ts b/src/channels/plugins/contracts/suites.ts index 7c9803ee47f..2224b13fbb7 100644 --- a/src/channels/plugins/contracts/suites.ts +++ b/src/channels/plugins/contracts/suites.ts @@ -485,7 +485,7 @@ export function installSessionBindingContractSuite(params: { expectedCapabilities: SessionBindingCapabilities; }) { it("registers the expected session binding capabilities", async () => { - expect(await params.getCapabilities()).toEqual(params.expectedCapabilities); + expect(await Promise.resolve(params.getCapabilities())).toEqual(params.expectedCapabilities); }); it("binds and resolves a session binding through the shared service", async () => { diff --git a/src/channels/plugins/setup-wizard-helpers.ts b/src/channels/plugins/setup-wizard-helpers.ts index 23299816f5e..0a0cd291684 100644 --- a/src/channels/plugins/setup-wizard-helpers.ts +++ b/src/channels/plugins/setup-wizard-helpers.ts @@ -1,10 +1,6 @@ import type { OpenClawConfig } from "../../config/config.js"; import type { DmPolicy, GroupPolicy } from "../../config/types.js"; import type { SecretInput } from "../../config/types.secrets.js"; -import { - promptSecretRefForSetup, - resolveSecretInputModeForEnvSelection, -} from "../../plugins/provider-auth-input.js"; import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../../routing/session-key.js"; import type { WizardPrompter } from "../../wizard/prompts.js"; import { @@ -18,6 +14,15 @@ import type { } from "./setup-wizard-types.js"; import type { ChannelSetupWizard, ChannelSetupWizardAllowFromEntry } from "./setup-wizard.js"; +let providerAuthInputPromise: + | Promise + | undefined; + +function loadProviderAuthInput() { + providerAuthInputPromise ??= import("../../plugins/provider-auth-input.js"); + return providerAuthInputPromise; +} + export const promptAccountId: PromptAccountId = async (params: PromptAccountIdParams) => { const existingIds = params.listAccountIds(params.cfg); const initial = params.currentId?.trim() || params.defaultAccountId || DEFAULT_ACCOUNT_ID; @@ -994,6 +999,8 @@ export async function promptSingleChannelSecretInput(params: { inputPrompt: string; preferredEnvVar?: string; }): Promise { + const { promptSecretRefForSetup, resolveSecretInputModeForEnvSelection } = + await loadProviderAuthInput(); const selectedMode = await resolveSecretInputModeForEnvSelection({ prompter: params.prompter as WizardPrompter, explicitMode: params.secretInputMode, diff --git a/src/cli/command-secret-gateway.ts b/src/cli/command-secret-gateway.ts index 4e0c4d0c49a..bb428e8dc14 100644 --- a/src/cli/command-secret-gateway.ts +++ b/src/cli/command-secret-gateway.ts @@ -314,6 +314,12 @@ function isUnsupportedSecretsResolveError(err: unknown): boolean { ); } +function isDirectRuntimeWebTargetPath(path: string): boolean { + return ( + path === "tools.web.fetch.firecrawl.apiKey" || /^tools\.web\.search\.[^.]+\.apiKey$/.test(path) + ); +} + async function resolveCommandSecretRefsLocally(params: { config: OpenClawConfig; commandName: string; @@ -329,12 +335,22 @@ async function resolveCommandSecretRefsLocally(params: { env: process.env, }); const localResolutionDiagnostics: string[] = []; + const discoveredTargets = discoverConfigSecretTargetsByIds(sourceConfig, params.targetIds).filter( + (target) => !params.allowedPaths || params.allowedPaths.has(target.path), + ); + const runtimeWebTargets = discoveredTargets.filter((target) => + targetsRuntimeWebPath(target.path), + ); collectConfigAssignments({ config: structuredClone(params.config), context, }); if ( - targetsRuntimeWebResolution({ targetIds: params.targetIds, allowedPaths: params.allowedPaths }) + targetsRuntimeWebResolution({ + targetIds: params.targetIds, + allowedPaths: params.allowedPaths, + }) && + !runtimeWebTargets.every((target) => isDirectRuntimeWebTargetPath(target.path)) ) { try { await resolveRuntimeWebTools({ @@ -359,13 +375,7 @@ async function resolveCommandSecretRefsLocally(params: { ); const runtimeWebActivePaths = new Set(); const runtimeWebInactiveDiagnostics: string[] = []; - for (const target of discoverConfigSecretTargetsByIds(sourceConfig, params.targetIds)) { - if (!targetsRuntimeWebPath(target.path)) { - continue; - } - if (params.allowedPaths && !params.allowedPaths.has(target.path)) { - continue; - } + for (const target of runtimeWebTargets) { const runtimeState = classifyRuntimeWebTargetPathState({ config: sourceConfig, path: target.path, @@ -390,10 +400,7 @@ async function resolveCommandSecretRefsLocally(params: { .filter((warning) => !params.allowedPaths || params.allowedPaths.has(warning.path)) .map((warning) => warning.message); const activePaths = new Set(context.assignments.map((assignment) => assignment.path)); - for (const target of discoverConfigSecretTargetsByIds(sourceConfig, params.targetIds)) { - if (params.allowedPaths && !params.allowedPaths.has(target.path)) { - continue; - } + for (const target of discoveredTargets) { await resolveTargetSecretLocally({ target, sourceConfig, diff --git a/src/infra/outbound/message-action-runner.context.test.ts b/src/infra/outbound/message-action-runner.context.test.ts index 36dccd0534f..0819c2cfae1 100644 --- a/src/infra/outbound/message-action-runner.context.test.ts +++ b/src/infra/outbound/message-action-runner.context.test.ts @@ -1,8 +1,17 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest"; -import type { ChannelPlugin } from "../../channels/plugins/types.js"; +import type { + ChannelDirectoryEntryKind, + ChannelMessagingAdapter, + ChannelOutboundAdapter, + ChannelPlugin, +} from "../../channels/plugins/types.js"; import type { OpenClawConfig } from "../../config/config.js"; import { setActivePluginRegistry } from "../../plugins/runtime.js"; -import { createOutboundTestPlugin, createTestRegistry } from "../../test-utils/channel-plugins.js"; +import { + createChannelTestPluginBase, + createTestRegistry, +} from "../../test-utils/channel-plugins.js"; +import { createIMessageTestPlugin } from "../../test-utils/imessage-test-plugin.js"; import { runMessageAction } from "./message-action-runner.js"; const slackConfig = { @@ -52,48 +61,112 @@ const runDrySend = (params: { action: "send", }); -const createDryRunPlugin = (id: "slack" | "whatsapp" | "telegram" | "imessage"): ChannelPlugin => { - const plugin = createOutboundTestPlugin({ - id, - outbound: {} as never, - }); +type ResolvedTestTarget = { to: string; kind: ChannelDirectoryEntryKind }; - const resolveTarget: NonNullable< - NonNullable["targetResolver"] - >["resolveTarget"] = async ({ input, normalized }) => { - if (id === "slack") { - const raw = input.replace(/^#/, ""); - return { to: `channel:${raw}`, kind: "group", source: "normalized" }; - } - if (id === "telegram") { - return { to: `group:${normalized || input}`, kind: "group", source: "normalized" }; - } - if (id === "whatsapp") { - return { to: `group:${normalized || input}`, kind: "group", source: "normalized" }; - } - return { to: normalized || input, kind: "user", source: "normalized" }; +const directOutbound: ChannelOutboundAdapter = { deliveryMode: "direct" }; + +function normalizeSlackTarget(raw: string): string { + const trimmed = raw.trim(); + if (!trimmed) { + return trimmed; + } + if (trimmed.startsWith("#")) { + return trimmed.slice(1).trim(); + } + if (/^channel:/i.test(trimmed)) { + return trimmed.replace(/^channel:/i, "").trim(); + } + if (/^user:/i.test(trimmed)) { + return trimmed.replace(/^user:/i, "").trim(); + } + const mention = trimmed.match(/^<@([A-Z0-9]+)>$/i); + if (mention?.[1]) { + return mention[1]; + } + return trimmed; +} + +function createConfiguredTestPlugin(params: { + id: "slack" | "telegram" | "whatsapp"; + isConfigured: (cfg: OpenClawConfig) => boolean; + normalizeTarget: (raw: string) => string | undefined; + resolveTarget: (input: string) => ResolvedTestTarget | null; +}): ChannelPlugin { + const messaging: ChannelMessagingAdapter = { + normalizeTarget: params.normalizeTarget, + targetResolver: { + looksLikeId: (raw) => Boolean(params.resolveTarget(raw.trim())), + hint: "", + resolveTarget: async (resolverParams) => { + const resolved = params.resolveTarget(resolverParams.input); + return resolved ? { ...resolved, source: "normalized" } : null; + }, + }, + inferTargetChatType: (inferParams) => + params.resolveTarget(inferParams.to)?.kind === "user" ? "direct" : "group", }; - return { - ...plugin, - config: { - listAccountIds: () => ["default"], - resolveAccount: () => ({}), - }, - messaging: { - inferTargetChatType: ({ to }) => { - if (id === "imessage" && to.startsWith("imessage:")) { - return "direct"; - } - return "group"; + ...createChannelTestPluginBase({ + id: params.id, + config: { + listAccountIds: () => ["default"], + resolveAccount: () => ({ enabled: true }), + isConfigured: (_account, cfg) => params.isConfigured(cfg), }, - targetResolver: { - looksLikeId: () => true, - resolveTarget, - }, - }, + }), + outbound: directOutbound, + messaging, }; -}; +} + +const slackTestPlugin = createConfiguredTestPlugin({ + id: "slack", + isConfigured: (cfg) => Boolean(cfg.channels?.slack?.botToken?.trim()), + normalizeTarget: (raw) => normalizeSlackTarget(raw) || undefined, + resolveTarget: (input) => { + const normalized = normalizeSlackTarget(input); + if (!normalized) { + return null; + } + if (/^[A-Z0-9]+$/i.test(normalized)) { + const kind = /^U/i.test(normalized) ? "user" : "group"; + return { to: normalized, kind }; + } + return null; + }, +}); + +const telegramTestPlugin = createConfiguredTestPlugin({ + id: "telegram", + isConfigured: (cfg) => Boolean(cfg.channels?.telegram?.botToken?.trim()), + normalizeTarget: (raw) => raw.trim() || undefined, + resolveTarget: (input) => { + const normalized = input.trim(); + if (!normalized) { + return null; + } + return { + to: normalized.replace(/^telegram:/i, ""), + kind: normalized.startsWith("@") ? "user" : "group", + }; + }, +}); + +const whatsappTestPlugin = createConfiguredTestPlugin({ + id: "whatsapp", + isConfigured: (cfg) => Boolean(cfg.channels?.whatsapp), + normalizeTarget: (raw) => raw.trim() || undefined, + resolveTarget: (input) => { + const normalized = input.trim(); + if (!normalized) { + return null; + } + return { + to: normalized, + kind: normalized.endsWith("@g.us") ? "group" : "user", + }; + }, +}); describe("runMessageAction context isolation", () => { beforeEach(() => { @@ -102,22 +175,22 @@ describe("runMessageAction context isolation", () => { { pluginId: "slack", source: "test", - plugin: createDryRunPlugin("slack"), + plugin: slackTestPlugin, }, { pluginId: "whatsapp", source: "test", - plugin: createDryRunPlugin("whatsapp"), + plugin: whatsappTestPlugin, }, { pluginId: "telegram", source: "test", - plugin: createDryRunPlugin("telegram"), + plugin: telegramTestPlugin, }, { pluginId: "imessage", source: "test", - plugin: createDryRunPlugin("imessage"), + plugin: createIMessageTestPlugin(), }, ]), ); diff --git a/src/infra/outbound/message-action-spec.ts b/src/infra/outbound/message-action-spec.ts index 08ba61de0f8..f5149e715ef 100644 --- a/src/infra/outbound/message-action-spec.ts +++ b/src/infra/outbound/message-action-spec.ts @@ -58,7 +58,6 @@ export const MESSAGE_ACTION_TARGET_MODE: Record Date: Thu, 19 Mar 2026 13:39:56 -0700 Subject: [PATCH 08/69] refactor(scripts): move container setup entrypoints --- .github/labeler.yml | 3 + docker-setup.sh | 612 +------------------------- scripts/docker/setup.sh | 616 +++++++++++++++++++++++++++ scripts/podman/openclaw.container.in | 2 +- scripts/podman/setup.sh | 312 ++++++++++++++ scripts/run-openclaw-podman.sh | 14 +- setup-podman.sh | 310 +------------- src/docker-setup.e2e.test.ts | 19 +- 8 files changed, 962 insertions(+), 926 deletions(-) create mode 100755 scripts/docker/setup.sh create mode 100755 scripts/podman/setup.sh diff --git a/.github/labeler.yml b/.github/labeler.yml index 7dcc038de4c..4ee43d5e6fa 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -165,7 +165,10 @@ - "Dockerfile.*" - "docker-compose.yml" - "docker-setup.sh" + - "setup-podman.sh" - ".dockerignore" + - "scripts/docker/setup.sh" + - "scripts/podman/setup.sh" - "scripts/**/*docker*" - "scripts/**/Dockerfile*" - "scripts/sandbox-*.sh" diff --git a/docker-setup.sh b/docker-setup.sh index 19e5461765b..e8d6335bf42 100755 --- a/docker-setup.sh +++ b/docker-setup.sh @@ -2,615 +2,11 @@ set -euo pipefail ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -COMPOSE_FILE="$ROOT_DIR/docker-compose.yml" -EXTRA_COMPOSE_FILE="$ROOT_DIR/docker-compose.extra.yml" -IMAGE_NAME="${OPENCLAW_IMAGE:-openclaw:local}" -EXTRA_MOUNTS="${OPENCLAW_EXTRA_MOUNTS:-}" -HOME_VOLUME_NAME="${OPENCLAW_HOME_VOLUME:-}" -RAW_SANDBOX_SETTING="${OPENCLAW_SANDBOX:-}" -SANDBOX_ENABLED="" -DOCKER_SOCKET_PATH="${OPENCLAW_DOCKER_SOCKET:-}" -TIMEZONE="${OPENCLAW_TZ:-}" +SCRIPT_PATH="$ROOT_DIR/scripts/docker/setup.sh" -fail() { - echo "ERROR: $*" >&2 - exit 1 -} - -require_cmd() { - if ! command -v "$1" >/dev/null 2>&1; then - echo "Missing dependency: $1" >&2 - exit 1 - fi -} - -is_truthy_value() { - local raw="${1:-}" - raw="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')" - case "$raw" in - 1 | true | yes | on) return 0 ;; - *) return 1 ;; - esac -} - -read_config_gateway_token() { - local config_path="$OPENCLAW_CONFIG_DIR/openclaw.json" - if [[ ! -f "$config_path" ]]; then - return 0 - fi - if command -v python3 >/dev/null 2>&1; then - python3 - "$config_path" <<'PY' -import json -import sys - -path = sys.argv[1] -try: - with open(path, "r", encoding="utf-8") as f: - cfg = json.load(f) -except Exception: - raise SystemExit(0) - -gateway = cfg.get("gateway") -if not isinstance(gateway, dict): - raise SystemExit(0) -auth = gateway.get("auth") -if not isinstance(auth, dict): - raise SystemExit(0) -token = auth.get("token") -if isinstance(token, str): - token = token.strip() - if token: - print(token) -PY - return 0 - fi - if command -v node >/dev/null 2>&1; then - node - "$config_path" <<'NODE' -const fs = require("node:fs"); -const configPath = process.argv[2]; -try { - const cfg = JSON.parse(fs.readFileSync(configPath, "utf8")); - const token = cfg?.gateway?.auth?.token; - if (typeof token === "string" && token.trim().length > 0) { - process.stdout.write(token.trim()); - } -} catch { - // Keep docker-setup resilient when config parsing fails. -} -NODE - fi -} - -read_env_gateway_token() { - local env_path="$1" - local line="" - local token="" - if [[ ! -f "$env_path" ]]; then - return 0 - fi - while IFS= read -r line || [[ -n "$line" ]]; do - line="${line%$'\r'}" - if [[ "$line" == OPENCLAW_GATEWAY_TOKEN=* ]]; then - token="${line#OPENCLAW_GATEWAY_TOKEN=}" - fi - done <"$env_path" - if [[ -n "$token" ]]; then - printf '%s' "$token" - fi -} - -ensure_control_ui_allowed_origins() { - if [[ "${OPENCLAW_GATEWAY_BIND}" == "loopback" ]]; then - return 0 - fi - - local allowed_origin_json - local current_allowed_origins - allowed_origin_json="$(printf '["http://127.0.0.1:%s"]' "$OPENCLAW_GATEWAY_PORT")" - current_allowed_origins="$( - docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli \ - config get gateway.controlUi.allowedOrigins 2>/dev/null || true - )" - current_allowed_origins="${current_allowed_origins//$'\r'/}" - - if [[ -n "$current_allowed_origins" && "$current_allowed_origins" != "null" && "$current_allowed_origins" != "[]" ]]; then - echo "Control UI allowlist already configured; leaving gateway.controlUi.allowedOrigins unchanged." - return 0 - fi - - docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli \ - config set gateway.controlUi.allowedOrigins "$allowed_origin_json" --strict-json >/dev/null - echo "Set gateway.controlUi.allowedOrigins to $allowed_origin_json for non-loopback bind." -} - -sync_gateway_mode_and_bind() { - docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli \ - config set gateway.mode local >/dev/null - docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli \ - config set gateway.bind "$OPENCLAW_GATEWAY_BIND" >/dev/null - echo "Pinned gateway.mode=local and gateway.bind=$OPENCLAW_GATEWAY_BIND for Docker setup." -} - -contains_disallowed_chars() { - local value="$1" - [[ "$value" == *$'\n'* || "$value" == *$'\r'* || "$value" == *$'\t'* ]] -} - -is_valid_timezone() { - local value="$1" - [[ -e "/usr/share/zoneinfo/$value" && ! -d "/usr/share/zoneinfo/$value" ]] -} - -validate_mount_path_value() { - local label="$1" - local value="$2" - if [[ -z "$value" ]]; then - fail "$label cannot be empty." - fi - if contains_disallowed_chars "$value"; then - fail "$label contains unsupported control characters." - fi - if [[ "$value" =~ [[:space:]] ]]; then - fail "$label cannot contain whitespace." - fi -} - -validate_named_volume() { - local value="$1" - if [[ ! "$value" =~ ^[A-Za-z0-9][A-Za-z0-9_.-]*$ ]]; then - fail "OPENCLAW_HOME_VOLUME must match [A-Za-z0-9][A-Za-z0-9_.-]* when using a named volume." - fi -} - -validate_mount_spec() { - local mount="$1" - if contains_disallowed_chars "$mount"; then - fail "OPENCLAW_EXTRA_MOUNTS entries cannot contain control characters." - fi - # Keep mount specs strict to avoid YAML structure injection. - # Expected format: source:target[:options] - if [[ ! "$mount" =~ ^[^[:space:],:]+:[^[:space:],:]+(:[^[:space:],:]+)?$ ]]; then - fail "Invalid mount format '$mount'. Expected source:target[:options] without spaces." - fi -} - -require_cmd docker -if ! docker compose version >/dev/null 2>&1; then - echo "Docker Compose not available (try: docker compose version)" >&2 +if [[ ! -f "$SCRIPT_PATH" ]]; then + echo "Docker setup script not found at $SCRIPT_PATH" >&2 exit 1 fi -if [[ -z "$DOCKER_SOCKET_PATH" && "${DOCKER_HOST:-}" == unix://* ]]; then - DOCKER_SOCKET_PATH="${DOCKER_HOST#unix://}" -fi -if [[ -z "$DOCKER_SOCKET_PATH" ]]; then - DOCKER_SOCKET_PATH="/var/run/docker.sock" -fi -if is_truthy_value "$RAW_SANDBOX_SETTING"; then - SANDBOX_ENABLED="1" -fi - -OPENCLAW_CONFIG_DIR="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}" -OPENCLAW_WORKSPACE_DIR="${OPENCLAW_WORKSPACE_DIR:-$HOME/.openclaw/workspace}" - -validate_mount_path_value "OPENCLAW_CONFIG_DIR" "$OPENCLAW_CONFIG_DIR" -validate_mount_path_value "OPENCLAW_WORKSPACE_DIR" "$OPENCLAW_WORKSPACE_DIR" -if [[ -n "$HOME_VOLUME_NAME" ]]; then - if [[ "$HOME_VOLUME_NAME" == *"/"* ]]; then - validate_mount_path_value "OPENCLAW_HOME_VOLUME" "$HOME_VOLUME_NAME" - else - validate_named_volume "$HOME_VOLUME_NAME" - fi -fi -if contains_disallowed_chars "$EXTRA_MOUNTS"; then - fail "OPENCLAW_EXTRA_MOUNTS cannot contain control characters." -fi -if [[ -n "$SANDBOX_ENABLED" ]]; then - validate_mount_path_value "OPENCLAW_DOCKER_SOCKET" "$DOCKER_SOCKET_PATH" -fi -if [[ -n "$TIMEZONE" ]]; then - if contains_disallowed_chars "$TIMEZONE"; then - fail "OPENCLAW_TZ contains unsupported control characters." - fi - if [[ ! "$TIMEZONE" =~ ^[A-Za-z0-9/_+\-]+$ ]]; then - fail "OPENCLAW_TZ must be a valid IANA timezone string (e.g. Asia/Shanghai)." - fi - if ! is_valid_timezone "$TIMEZONE"; then - fail "OPENCLAW_TZ must match a timezone in /usr/share/zoneinfo (e.g. Asia/Shanghai)." - fi -fi - -mkdir -p "$OPENCLAW_CONFIG_DIR" -mkdir -p "$OPENCLAW_WORKSPACE_DIR" -# Seed directory tree eagerly so bind mounts work even on Docker Desktop/Windows -# where the container (even as root) cannot create new host subdirectories. -mkdir -p "$OPENCLAW_CONFIG_DIR/identity" -mkdir -p "$OPENCLAW_CONFIG_DIR/agents/main/agent" -mkdir -p "$OPENCLAW_CONFIG_DIR/agents/main/sessions" - -export OPENCLAW_CONFIG_DIR -export OPENCLAW_WORKSPACE_DIR -export OPENCLAW_GATEWAY_PORT="${OPENCLAW_GATEWAY_PORT:-18789}" -export OPENCLAW_BRIDGE_PORT="${OPENCLAW_BRIDGE_PORT:-18790}" -export OPENCLAW_GATEWAY_BIND="${OPENCLAW_GATEWAY_BIND:-lan}" -export OPENCLAW_IMAGE="$IMAGE_NAME" -export OPENCLAW_DOCKER_APT_PACKAGES="${OPENCLAW_DOCKER_APT_PACKAGES:-}" -export OPENCLAW_EXTENSIONS="${OPENCLAW_EXTENSIONS:-}" -export OPENCLAW_EXTRA_MOUNTS="$EXTRA_MOUNTS" -export OPENCLAW_HOME_VOLUME="$HOME_VOLUME_NAME" -export OPENCLAW_ALLOW_INSECURE_PRIVATE_WS="${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}" -export OPENCLAW_SANDBOX="$SANDBOX_ENABLED" -export OPENCLAW_DOCKER_SOCKET="$DOCKER_SOCKET_PATH" -export OPENCLAW_TZ="$TIMEZONE" - -# Detect Docker socket GID for sandbox group_add. -DOCKER_GID="" -if [[ -n "$SANDBOX_ENABLED" && -S "$DOCKER_SOCKET_PATH" ]]; then - DOCKER_GID="$(stat -c '%g' "$DOCKER_SOCKET_PATH" 2>/dev/null || stat -f '%g' "$DOCKER_SOCKET_PATH" 2>/dev/null || echo "")" -fi -export DOCKER_GID - -if [[ -z "${OPENCLAW_GATEWAY_TOKEN:-}" ]]; then - EXISTING_CONFIG_TOKEN="$(read_config_gateway_token || true)" - if [[ -n "$EXISTING_CONFIG_TOKEN" ]]; then - OPENCLAW_GATEWAY_TOKEN="$EXISTING_CONFIG_TOKEN" - echo "Reusing gateway token from $OPENCLAW_CONFIG_DIR/openclaw.json" - else - DOTENV_GATEWAY_TOKEN="$(read_env_gateway_token "$ROOT_DIR/.env" || true)" - if [[ -n "$DOTENV_GATEWAY_TOKEN" ]]; then - OPENCLAW_GATEWAY_TOKEN="$DOTENV_GATEWAY_TOKEN" - echo "Reusing gateway token from $ROOT_DIR/.env" - elif command -v openssl >/dev/null 2>&1; then - OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)" - else - OPENCLAW_GATEWAY_TOKEN="$(python3 - <<'PY' -import secrets -print(secrets.token_hex(32)) -PY -)" - fi - fi -fi -export OPENCLAW_GATEWAY_TOKEN - -COMPOSE_FILES=("$COMPOSE_FILE") -COMPOSE_ARGS=() - -write_extra_compose() { - local home_volume="$1" - shift - local mount - local gateway_home_mount - local gateway_config_mount - local gateway_workspace_mount - - cat >"$EXTRA_COMPOSE_FILE" <<'YAML' -services: - openclaw-gateway: - volumes: -YAML - - if [[ -n "$home_volume" ]]; then - gateway_home_mount="${home_volume}:/home/node" - gateway_config_mount="${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw" - gateway_workspace_mount="${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace" - validate_mount_spec "$gateway_home_mount" - validate_mount_spec "$gateway_config_mount" - validate_mount_spec "$gateway_workspace_mount" - printf ' - %s\n' "$gateway_home_mount" >>"$EXTRA_COMPOSE_FILE" - printf ' - %s\n' "$gateway_config_mount" >>"$EXTRA_COMPOSE_FILE" - printf ' - %s\n' "$gateway_workspace_mount" >>"$EXTRA_COMPOSE_FILE" - fi - - for mount in "$@"; do - validate_mount_spec "$mount" - printf ' - %s\n' "$mount" >>"$EXTRA_COMPOSE_FILE" - done - - cat >>"$EXTRA_COMPOSE_FILE" <<'YAML' - openclaw-cli: - volumes: -YAML - - if [[ -n "$home_volume" ]]; then - printf ' - %s\n' "$gateway_home_mount" >>"$EXTRA_COMPOSE_FILE" - printf ' - %s\n' "$gateway_config_mount" >>"$EXTRA_COMPOSE_FILE" - printf ' - %s\n' "$gateway_workspace_mount" >>"$EXTRA_COMPOSE_FILE" - fi - - for mount in "$@"; do - validate_mount_spec "$mount" - printf ' - %s\n' "$mount" >>"$EXTRA_COMPOSE_FILE" - done - - if [[ -n "$home_volume" && "$home_volume" != *"/"* ]]; then - validate_named_volume "$home_volume" - cat >>"$EXTRA_COMPOSE_FILE" <>"$tmp" - seen="$seen$k " - replaced=true - break - fi - done - if [[ "$replaced" == false ]]; then - printf '%s\n' "$line" >>"$tmp" - fi - done <"$file" - fi - - for k in "${keys[@]}"; do - if [[ "$seen" != *" $k "* ]]; then - printf '%s=%s\n' "$k" "${!k-}" >>"$tmp" - fi - done - - mv "$tmp" "$file" -} - -upsert_env "$ENV_FILE" \ - OPENCLAW_CONFIG_DIR \ - OPENCLAW_WORKSPACE_DIR \ - OPENCLAW_GATEWAY_PORT \ - OPENCLAW_BRIDGE_PORT \ - OPENCLAW_GATEWAY_BIND \ - OPENCLAW_GATEWAY_TOKEN \ - OPENCLAW_IMAGE \ - OPENCLAW_EXTRA_MOUNTS \ - OPENCLAW_HOME_VOLUME \ - OPENCLAW_DOCKER_APT_PACKAGES \ - OPENCLAW_EXTENSIONS \ - OPENCLAW_SANDBOX \ - OPENCLAW_DOCKER_SOCKET \ - DOCKER_GID \ - OPENCLAW_INSTALL_DOCKER_CLI \ - OPENCLAW_ALLOW_INSECURE_PRIVATE_WS \ - OPENCLAW_TZ - -if [[ "$IMAGE_NAME" == "openclaw:local" ]]; then - echo "==> Building Docker image: $IMAGE_NAME" - docker build \ - --build-arg "OPENCLAW_DOCKER_APT_PACKAGES=${OPENCLAW_DOCKER_APT_PACKAGES}" \ - --build-arg "OPENCLAW_EXTENSIONS=${OPENCLAW_EXTENSIONS}" \ - --build-arg "OPENCLAW_INSTALL_DOCKER_CLI=${OPENCLAW_INSTALL_DOCKER_CLI:-}" \ - -t "$IMAGE_NAME" \ - -f "$ROOT_DIR/Dockerfile" \ - "$ROOT_DIR" -else - echo "==> Pulling Docker image: $IMAGE_NAME" - if ! docker pull "$IMAGE_NAME"; then - echo "ERROR: Failed to pull image $IMAGE_NAME. Please check the image name and your access permissions." >&2 - exit 1 - fi -fi - -# Ensure bind-mounted data directories are writable by the container's `node` -# user (uid 1000). Host-created dirs inherit the host user's uid which may -# differ, causing EACCES when the container tries to mkdir/write. -# Running a brief root container to chown is the portable Docker idiom -- -# it works regardless of the host uid and doesn't require host-side root. -echo "" -echo "==> Fixing data-directory permissions" -# Use -xdev to restrict chown to the config-dir mount only — without it, -# the recursive chown would cross into the workspace bind mount and rewrite -# ownership of all user project files on Linux hosts. -# After fixing the config dir, only the OpenClaw metadata subdirectory -# (.openclaw/) inside the workspace gets chowned, not the user's project files. -docker compose "${COMPOSE_ARGS[@]}" run --rm --user root --entrypoint sh openclaw-cli -c \ - 'find /home/node/.openclaw -xdev -exec chown node:node {} +; \ - [ -d /home/node/.openclaw/workspace/.openclaw ] && chown -R node:node /home/node/.openclaw/workspace/.openclaw || true' - -echo "" -echo "==> Onboarding (interactive)" -echo "Docker setup pins Gateway mode to local." -echo "Gateway runtime bind comes from OPENCLAW_GATEWAY_BIND (default: lan)." -echo "Current runtime bind: $OPENCLAW_GATEWAY_BIND" -echo "Gateway token: $OPENCLAW_GATEWAY_TOKEN" -echo "Tailscale exposure: Off (use host-level tailnet/Tailscale setup separately)." -echo "Install Gateway daemon: No (managed by Docker Compose)" -echo "" -docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli onboard --mode local --no-install-daemon - -echo "" -echo "==> Docker gateway defaults" -sync_gateway_mode_and_bind - -echo "" -echo "==> Control UI origin allowlist" -ensure_control_ui_allowed_origins - -echo "" -echo "==> Provider setup (optional)" -echo "WhatsApp (QR):" -echo " ${COMPOSE_HINT} run --rm openclaw-cli channels login" -echo "Telegram (bot token):" -echo " ${COMPOSE_HINT} run --rm openclaw-cli channels add --channel telegram --token " -echo "Discord (bot token):" -echo " ${COMPOSE_HINT} run --rm openclaw-cli channels add --channel discord --token " -echo "Docs: https://docs.openclaw.ai/channels" - -echo "" -echo "==> Starting gateway" -docker compose "${COMPOSE_ARGS[@]}" up -d openclaw-gateway - -# --- Sandbox setup (opt-in via OPENCLAW_SANDBOX=1) --- -if [[ -n "$SANDBOX_ENABLED" ]]; then - echo "" - echo "==> Sandbox setup" - - # Build sandbox image if Dockerfile.sandbox exists. - if [[ -f "$ROOT_DIR/Dockerfile.sandbox" ]]; then - echo "Building sandbox image: openclaw-sandbox:bookworm-slim" - docker build \ - -t "openclaw-sandbox:bookworm-slim" \ - -f "$ROOT_DIR/Dockerfile.sandbox" \ - "$ROOT_DIR" - else - echo "WARNING: Dockerfile.sandbox not found in $ROOT_DIR" >&2 - echo " Sandbox config will be applied but no sandbox image will be built." >&2 - echo " Agent exec may fail if the configured sandbox image does not exist." >&2 - fi - - # Defense-in-depth: verify Docker CLI in the running image before enabling - # sandbox. This avoids claiming sandbox is enabled when the image cannot - # launch sandbox containers. - if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --entrypoint docker openclaw-gateway --version >/dev/null 2>&1; then - echo "WARNING: Docker CLI not found inside the container image." >&2 - echo " Sandbox requires Docker CLI. Rebuild with --build-arg OPENCLAW_INSTALL_DOCKER_CLI=1" >&2 - echo " or use a local build (OPENCLAW_IMAGE=openclaw:local). Skipping sandbox setup." >&2 - SANDBOX_ENABLED="" - fi -fi - -# Apply sandbox config only if prerequisites are met. -if [[ -n "$SANDBOX_ENABLED" ]]; then - # Mount Docker socket via a dedicated compose overlay. This overlay is - # created only after sandbox prerequisites pass, so the socket is never - # exposed when sandbox cannot actually run. - if [[ -S "$DOCKER_SOCKET_PATH" ]]; then - SANDBOX_COMPOSE_FILE="$ROOT_DIR/docker-compose.sandbox.yml" - cat >"$SANDBOX_COMPOSE_FILE" <>"$SANDBOX_COMPOSE_FILE" < Sandbox: added Docker socket mount" - else - echo "WARNING: OPENCLAW_SANDBOX enabled but Docker socket not found at $DOCKER_SOCKET_PATH." >&2 - echo " Sandbox requires Docker socket access. Skipping sandbox setup." >&2 - SANDBOX_ENABLED="" - fi -fi - -if [[ -n "$SANDBOX_ENABLED" ]]; then - # Enable sandbox in OpenClaw config. - sandbox_config_ok=true - if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \ - config set agents.defaults.sandbox.mode "non-main" >/dev/null; then - echo "WARNING: Failed to set agents.defaults.sandbox.mode" >&2 - sandbox_config_ok=false - fi - if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \ - config set agents.defaults.sandbox.scope "agent" >/dev/null; then - echo "WARNING: Failed to set agents.defaults.sandbox.scope" >&2 - sandbox_config_ok=false - fi - if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \ - config set agents.defaults.sandbox.workspaceAccess "none" >/dev/null; then - echo "WARNING: Failed to set agents.defaults.sandbox.workspaceAccess" >&2 - sandbox_config_ok=false - fi - - if [[ "$sandbox_config_ok" == true ]]; then - echo "Sandbox enabled: mode=non-main, scope=agent, workspaceAccess=none" - echo "Docs: https://docs.openclaw.ai/gateway/sandboxing" - # Restart gateway with sandbox compose overlay to pick up socket mount + config. - docker compose "${COMPOSE_ARGS[@]}" up -d openclaw-gateway - else - echo "WARNING: Sandbox config was partially applied. Check errors above." >&2 - echo " Skipping gateway restart to avoid exposing Docker socket without a full sandbox policy." >&2 - if ! docker compose "${BASE_COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \ - config set agents.defaults.sandbox.mode "off" >/dev/null; then - echo "WARNING: Failed to roll back agents.defaults.sandbox.mode to off" >&2 - else - echo "Sandbox mode rolled back to off due to partial sandbox config failure." - fi - if [[ -n "${SANDBOX_COMPOSE_FILE:-}" ]]; then - rm -f "$SANDBOX_COMPOSE_FILE" - fi - # Ensure gateway service definition is reset without sandbox overlay mount. - docker compose "${BASE_COMPOSE_ARGS[@]}" up -d --force-recreate openclaw-gateway - fi -else - # Keep reruns deterministic: if sandbox is not active for this run, reset - # persisted sandbox mode so future execs do not require docker.sock by stale - # config alone. - if ! docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli \ - config set agents.defaults.sandbox.mode "off" >/dev/null; then - echo "WARNING: Failed to reset agents.defaults.sandbox.mode to off" >&2 - fi - if [[ -f "$ROOT_DIR/docker-compose.sandbox.yml" ]]; then - rm -f "$ROOT_DIR/docker-compose.sandbox.yml" - fi -fi - -echo "" -echo "Gateway running with host port mapping." -echo "Access from tailnet devices via the host's tailnet IP." -echo "Config: $OPENCLAW_CONFIG_DIR" -echo "Workspace: $OPENCLAW_WORKSPACE_DIR" -echo "Token: $OPENCLAW_GATEWAY_TOKEN" -echo "" -echo "Commands:" -echo " ${COMPOSE_HINT} logs -f openclaw-gateway" -echo " ${COMPOSE_HINT} exec openclaw-gateway node dist/index.js health --token \"$OPENCLAW_GATEWAY_TOKEN\"" +exec "$SCRIPT_PATH" "$@" diff --git a/scripts/docker/setup.sh b/scripts/docker/setup.sh new file mode 100755 index 00000000000..cfa6fd4046e --- /dev/null +++ b/scripts/docker/setup.sh @@ -0,0 +1,616 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +COMPOSE_FILE="$ROOT_DIR/docker-compose.yml" +EXTRA_COMPOSE_FILE="$ROOT_DIR/docker-compose.extra.yml" +IMAGE_NAME="${OPENCLAW_IMAGE:-openclaw:local}" +EXTRA_MOUNTS="${OPENCLAW_EXTRA_MOUNTS:-}" +HOME_VOLUME_NAME="${OPENCLAW_HOME_VOLUME:-}" +RAW_SANDBOX_SETTING="${OPENCLAW_SANDBOX:-}" +SANDBOX_ENABLED="" +DOCKER_SOCKET_PATH="${OPENCLAW_DOCKER_SOCKET:-}" +TIMEZONE="${OPENCLAW_TZ:-}" + +fail() { + echo "ERROR: $*" >&2 + exit 1 +} + +require_cmd() { + if ! command -v "$1" >/dev/null 2>&1; then + echo "Missing dependency: $1" >&2 + exit 1 + fi +} + +is_truthy_value() { + local raw="${1:-}" + raw="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')" + case "$raw" in + 1 | true | yes | on) return 0 ;; + *) return 1 ;; + esac +} + +read_config_gateway_token() { + local config_path="$OPENCLAW_CONFIG_DIR/openclaw.json" + if [[ ! -f "$config_path" ]]; then + return 0 + fi + if command -v python3 >/dev/null 2>&1; then + python3 - "$config_path" <<'PY' +import json +import sys + +path = sys.argv[1] +try: + with open(path, "r", encoding="utf-8") as f: + cfg = json.load(f) +except Exception: + raise SystemExit(0) + +gateway = cfg.get("gateway") +if not isinstance(gateway, dict): + raise SystemExit(0) +auth = gateway.get("auth") +if not isinstance(auth, dict): + raise SystemExit(0) +token = auth.get("token") +if isinstance(token, str): + token = token.strip() + if token: + print(token) +PY + return 0 + fi + if command -v node >/dev/null 2>&1; then + node - "$config_path" <<'NODE' +const fs = require("node:fs"); +const configPath = process.argv[2]; +try { + const cfg = JSON.parse(fs.readFileSync(configPath, "utf8")); + const token = cfg?.gateway?.auth?.token; + if (typeof token === "string" && token.trim().length > 0) { + process.stdout.write(token.trim()); + } +} catch { + // Keep docker-setup resilient when config parsing fails. +} +NODE + fi +} + +read_env_gateway_token() { + local env_path="$1" + local line="" + local token="" + if [[ ! -f "$env_path" ]]; then + return 0 + fi + while IFS= read -r line || [[ -n "$line" ]]; do + line="${line%$'\r'}" + if [[ "$line" == OPENCLAW_GATEWAY_TOKEN=* ]]; then + token="${line#OPENCLAW_GATEWAY_TOKEN=}" + fi + done <"$env_path" + if [[ -n "$token" ]]; then + printf '%s' "$token" + fi +} + +ensure_control_ui_allowed_origins() { + if [[ "${OPENCLAW_GATEWAY_BIND}" == "loopback" ]]; then + return 0 + fi + + local allowed_origin_json + local current_allowed_origins + allowed_origin_json="$(printf '["http://127.0.0.1:%s"]' "$OPENCLAW_GATEWAY_PORT")" + current_allowed_origins="$( + docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli \ + config get gateway.controlUi.allowedOrigins 2>/dev/null || true + )" + current_allowed_origins="${current_allowed_origins//$'\r'/}" + + if [[ -n "$current_allowed_origins" && "$current_allowed_origins" != "null" && "$current_allowed_origins" != "[]" ]]; then + echo "Control UI allowlist already configured; leaving gateway.controlUi.allowedOrigins unchanged." + return 0 + fi + + docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli \ + config set gateway.controlUi.allowedOrigins "$allowed_origin_json" --strict-json >/dev/null + echo "Set gateway.controlUi.allowedOrigins to $allowed_origin_json for non-loopback bind." +} + +sync_gateway_mode_and_bind() { + docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli \ + config set gateway.mode local >/dev/null + docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli \ + config set gateway.bind "$OPENCLAW_GATEWAY_BIND" >/dev/null + echo "Pinned gateway.mode=local and gateway.bind=$OPENCLAW_GATEWAY_BIND for Docker setup." +} + +contains_disallowed_chars() { + local value="$1" + [[ "$value" == *$'\n'* || "$value" == *$'\r'* || "$value" == *$'\t'* ]] +} + +is_valid_timezone() { + local value="$1" + [[ -e "/usr/share/zoneinfo/$value" && ! -d "/usr/share/zoneinfo/$value" ]] +} + +validate_mount_path_value() { + local label="$1" + local value="$2" + if [[ -z "$value" ]]; then + fail "$label cannot be empty." + fi + if contains_disallowed_chars "$value"; then + fail "$label contains unsupported control characters." + fi + if [[ "$value" =~ [[:space:]] ]]; then + fail "$label cannot contain whitespace." + fi +} + +validate_named_volume() { + local value="$1" + if [[ ! "$value" =~ ^[A-Za-z0-9][A-Za-z0-9_.-]*$ ]]; then + fail "OPENCLAW_HOME_VOLUME must match [A-Za-z0-9][A-Za-z0-9_.-]* when using a named volume." + fi +} + +validate_mount_spec() { + local mount="$1" + if contains_disallowed_chars "$mount"; then + fail "OPENCLAW_EXTRA_MOUNTS entries cannot contain control characters." + fi + # Keep mount specs strict to avoid YAML structure injection. + # Expected format: source:target[:options] + if [[ ! "$mount" =~ ^[^[:space:],:]+:[^[:space:],:]+(:[^[:space:],:]+)?$ ]]; then + fail "Invalid mount format '$mount'. Expected source:target[:options] without spaces." + fi +} + +require_cmd docker +if ! docker compose version >/dev/null 2>&1; then + echo "Docker Compose not available (try: docker compose version)" >&2 + exit 1 +fi + +if [[ -z "$DOCKER_SOCKET_PATH" && "${DOCKER_HOST:-}" == unix://* ]]; then + DOCKER_SOCKET_PATH="${DOCKER_HOST#unix://}" +fi +if [[ -z "$DOCKER_SOCKET_PATH" ]]; then + DOCKER_SOCKET_PATH="/var/run/docker.sock" +fi +if is_truthy_value "$RAW_SANDBOX_SETTING"; then + SANDBOX_ENABLED="1" +fi + +OPENCLAW_CONFIG_DIR="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}" +OPENCLAW_WORKSPACE_DIR="${OPENCLAW_WORKSPACE_DIR:-$HOME/.openclaw/workspace}" + +validate_mount_path_value "OPENCLAW_CONFIG_DIR" "$OPENCLAW_CONFIG_DIR" +validate_mount_path_value "OPENCLAW_WORKSPACE_DIR" "$OPENCLAW_WORKSPACE_DIR" +if [[ -n "$HOME_VOLUME_NAME" ]]; then + if [[ "$HOME_VOLUME_NAME" == *"/"* ]]; then + validate_mount_path_value "OPENCLAW_HOME_VOLUME" "$HOME_VOLUME_NAME" + else + validate_named_volume "$HOME_VOLUME_NAME" + fi +fi +if contains_disallowed_chars "$EXTRA_MOUNTS"; then + fail "OPENCLAW_EXTRA_MOUNTS cannot contain control characters." +fi +if [[ -n "$SANDBOX_ENABLED" ]]; then + validate_mount_path_value "OPENCLAW_DOCKER_SOCKET" "$DOCKER_SOCKET_PATH" +fi +if [[ -n "$TIMEZONE" ]]; then + if contains_disallowed_chars "$TIMEZONE"; then + fail "OPENCLAW_TZ contains unsupported control characters." + fi + if [[ ! "$TIMEZONE" =~ ^[A-Za-z0-9/_+\-]+$ ]]; then + fail "OPENCLAW_TZ must be a valid IANA timezone string (e.g. Asia/Shanghai)." + fi + if ! is_valid_timezone "$TIMEZONE"; then + fail "OPENCLAW_TZ must match a timezone in /usr/share/zoneinfo (e.g. Asia/Shanghai)." + fi +fi + +mkdir -p "$OPENCLAW_CONFIG_DIR" +mkdir -p "$OPENCLAW_WORKSPACE_DIR" +# Seed directory tree eagerly so bind mounts work even on Docker Desktop/Windows +# where the container (even as root) cannot create new host subdirectories. +mkdir -p "$OPENCLAW_CONFIG_DIR/identity" +mkdir -p "$OPENCLAW_CONFIG_DIR/agents/main/agent" +mkdir -p "$OPENCLAW_CONFIG_DIR/agents/main/sessions" + +export OPENCLAW_CONFIG_DIR +export OPENCLAW_WORKSPACE_DIR +export OPENCLAW_GATEWAY_PORT="${OPENCLAW_GATEWAY_PORT:-18789}" +export OPENCLAW_BRIDGE_PORT="${OPENCLAW_BRIDGE_PORT:-18790}" +export OPENCLAW_GATEWAY_BIND="${OPENCLAW_GATEWAY_BIND:-lan}" +export OPENCLAW_IMAGE="$IMAGE_NAME" +export OPENCLAW_DOCKER_APT_PACKAGES="${OPENCLAW_DOCKER_APT_PACKAGES:-}" +export OPENCLAW_EXTENSIONS="${OPENCLAW_EXTENSIONS:-}" +export OPENCLAW_EXTRA_MOUNTS="$EXTRA_MOUNTS" +export OPENCLAW_HOME_VOLUME="$HOME_VOLUME_NAME" +export OPENCLAW_ALLOW_INSECURE_PRIVATE_WS="${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}" +export OPENCLAW_SANDBOX="$SANDBOX_ENABLED" +export OPENCLAW_DOCKER_SOCKET="$DOCKER_SOCKET_PATH" +export OPENCLAW_TZ="$TIMEZONE" + +# Detect Docker socket GID for sandbox group_add. +DOCKER_GID="" +if [[ -n "$SANDBOX_ENABLED" && -S "$DOCKER_SOCKET_PATH" ]]; then + DOCKER_GID="$(stat -c '%g' "$DOCKER_SOCKET_PATH" 2>/dev/null || stat -f '%g' "$DOCKER_SOCKET_PATH" 2>/dev/null || echo "")" +fi +export DOCKER_GID + +if [[ -z "${OPENCLAW_GATEWAY_TOKEN:-}" ]]; then + EXISTING_CONFIG_TOKEN="$(read_config_gateway_token || true)" + if [[ -n "$EXISTING_CONFIG_TOKEN" ]]; then + OPENCLAW_GATEWAY_TOKEN="$EXISTING_CONFIG_TOKEN" + echo "Reusing gateway token from $OPENCLAW_CONFIG_DIR/openclaw.json" + else + DOTENV_GATEWAY_TOKEN="$(read_env_gateway_token "$ROOT_DIR/.env" || true)" + if [[ -n "$DOTENV_GATEWAY_TOKEN" ]]; then + OPENCLAW_GATEWAY_TOKEN="$DOTENV_GATEWAY_TOKEN" + echo "Reusing gateway token from $ROOT_DIR/.env" + elif command -v openssl >/dev/null 2>&1; then + OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)" + else + OPENCLAW_GATEWAY_TOKEN="$(python3 - <<'PY' +import secrets +print(secrets.token_hex(32)) +PY +)" + fi + fi +fi +export OPENCLAW_GATEWAY_TOKEN + +COMPOSE_FILES=("$COMPOSE_FILE") +COMPOSE_ARGS=() + +write_extra_compose() { + local home_volume="$1" + shift + local mount + local gateway_home_mount + local gateway_config_mount + local gateway_workspace_mount + + cat >"$EXTRA_COMPOSE_FILE" <<'YAML' +services: + openclaw-gateway: + volumes: +YAML + + if [[ -n "$home_volume" ]]; then + gateway_home_mount="${home_volume}:/home/node" + gateway_config_mount="${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw" + gateway_workspace_mount="${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace" + validate_mount_spec "$gateway_home_mount" + validate_mount_spec "$gateway_config_mount" + validate_mount_spec "$gateway_workspace_mount" + printf ' - %s\n' "$gateway_home_mount" >>"$EXTRA_COMPOSE_FILE" + printf ' - %s\n' "$gateway_config_mount" >>"$EXTRA_COMPOSE_FILE" + printf ' - %s\n' "$gateway_workspace_mount" >>"$EXTRA_COMPOSE_FILE" + fi + + for mount in "$@"; do + validate_mount_spec "$mount" + printf ' - %s\n' "$mount" >>"$EXTRA_COMPOSE_FILE" + done + + cat >>"$EXTRA_COMPOSE_FILE" <<'YAML' + openclaw-cli: + volumes: +YAML + + if [[ -n "$home_volume" ]]; then + printf ' - %s\n' "$gateway_home_mount" >>"$EXTRA_COMPOSE_FILE" + printf ' - %s\n' "$gateway_config_mount" >>"$EXTRA_COMPOSE_FILE" + printf ' - %s\n' "$gateway_workspace_mount" >>"$EXTRA_COMPOSE_FILE" + fi + + for mount in "$@"; do + validate_mount_spec "$mount" + printf ' - %s\n' "$mount" >>"$EXTRA_COMPOSE_FILE" + done + + if [[ -n "$home_volume" && "$home_volume" != *"/"* ]]; then + validate_named_volume "$home_volume" + cat >>"$EXTRA_COMPOSE_FILE" <>"$tmp" + seen="$seen$k " + replaced=true + break + fi + done + if [[ "$replaced" == false ]]; then + printf '%s\n' "$line" >>"$tmp" + fi + done <"$file" + fi + + for k in "${keys[@]}"; do + if [[ "$seen" != *" $k "* ]]; then + printf '%s=%s\n' "$k" "${!k-}" >>"$tmp" + fi + done + + mv "$tmp" "$file" +} + +upsert_env "$ENV_FILE" \ + OPENCLAW_CONFIG_DIR \ + OPENCLAW_WORKSPACE_DIR \ + OPENCLAW_GATEWAY_PORT \ + OPENCLAW_BRIDGE_PORT \ + OPENCLAW_GATEWAY_BIND \ + OPENCLAW_GATEWAY_TOKEN \ + OPENCLAW_IMAGE \ + OPENCLAW_EXTRA_MOUNTS \ + OPENCLAW_HOME_VOLUME \ + OPENCLAW_DOCKER_APT_PACKAGES \ + OPENCLAW_EXTENSIONS \ + OPENCLAW_SANDBOX \ + OPENCLAW_DOCKER_SOCKET \ + DOCKER_GID \ + OPENCLAW_INSTALL_DOCKER_CLI \ + OPENCLAW_ALLOW_INSECURE_PRIVATE_WS \ + OPENCLAW_TZ + +if [[ "$IMAGE_NAME" == "openclaw:local" ]]; then + echo "==> Building Docker image: $IMAGE_NAME" + docker build \ + --build-arg "OPENCLAW_DOCKER_APT_PACKAGES=${OPENCLAW_DOCKER_APT_PACKAGES}" \ + --build-arg "OPENCLAW_EXTENSIONS=${OPENCLAW_EXTENSIONS}" \ + --build-arg "OPENCLAW_INSTALL_DOCKER_CLI=${OPENCLAW_INSTALL_DOCKER_CLI:-}" \ + -t "$IMAGE_NAME" \ + -f "$ROOT_DIR/Dockerfile" \ + "$ROOT_DIR" +else + echo "==> Pulling Docker image: $IMAGE_NAME" + if ! docker pull "$IMAGE_NAME"; then + echo "ERROR: Failed to pull image $IMAGE_NAME. Please check the image name and your access permissions." >&2 + exit 1 + fi +fi + +# Ensure bind-mounted data directories are writable by the container's `node` +# user (uid 1000). Host-created dirs inherit the host user's uid which may +# differ, causing EACCES when the container tries to mkdir/write. +# Running a brief root container to chown is the portable Docker idiom -- +# it works regardless of the host uid and doesn't require host-side root. +echo "" +echo "==> Fixing data-directory permissions" +# Use -xdev to restrict chown to the config-dir mount only — without it, +# the recursive chown would cross into the workspace bind mount and rewrite +# ownership of all user project files on Linux hosts. +# After fixing the config dir, only the OpenClaw metadata subdirectory +# (.openclaw/) inside the workspace gets chowned, not the user's project files. +docker compose "${COMPOSE_ARGS[@]}" run --rm --user root --entrypoint sh openclaw-cli -c \ + 'find /home/node/.openclaw -xdev -exec chown node:node {} +; \ + [ -d /home/node/.openclaw/workspace/.openclaw ] && chown -R node:node /home/node/.openclaw/workspace/.openclaw || true' + +echo "" +echo "==> Onboarding (interactive)" +echo "Docker setup pins Gateway mode to local." +echo "Gateway runtime bind comes from OPENCLAW_GATEWAY_BIND (default: lan)." +echo "Current runtime bind: $OPENCLAW_GATEWAY_BIND" +echo "Gateway token: $OPENCLAW_GATEWAY_TOKEN" +echo "Tailscale exposure: Off (use host-level tailnet/Tailscale setup separately)." +echo "Install Gateway daemon: No (managed by Docker Compose)" +echo "" +docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli onboard --mode local --no-install-daemon + +echo "" +echo "==> Docker gateway defaults" +sync_gateway_mode_and_bind + +echo "" +echo "==> Control UI origin allowlist" +ensure_control_ui_allowed_origins + +echo "" +echo "==> Provider setup (optional)" +echo "WhatsApp (QR):" +echo " ${COMPOSE_HINT} run --rm openclaw-cli channels login" +echo "Telegram (bot token):" +echo " ${COMPOSE_HINT} run --rm openclaw-cli channels add --channel telegram --token " +echo "Discord (bot token):" +echo " ${COMPOSE_HINT} run --rm openclaw-cli channels add --channel discord --token " +echo "Docs: https://docs.openclaw.ai/channels" + +echo "" +echo "==> Starting gateway" +docker compose "${COMPOSE_ARGS[@]}" up -d openclaw-gateway + +# --- Sandbox setup (opt-in via OPENCLAW_SANDBOX=1) --- +if [[ -n "$SANDBOX_ENABLED" ]]; then + echo "" + echo "==> Sandbox setup" + + # Build sandbox image if Dockerfile.sandbox exists. + if [[ -f "$ROOT_DIR/Dockerfile.sandbox" ]]; then + echo "Building sandbox image: openclaw-sandbox:bookworm-slim" + docker build \ + -t "openclaw-sandbox:bookworm-slim" \ + -f "$ROOT_DIR/Dockerfile.sandbox" \ + "$ROOT_DIR" + else + echo "WARNING: Dockerfile.sandbox not found in $ROOT_DIR" >&2 + echo " Sandbox config will be applied but no sandbox image will be built." >&2 + echo " Agent exec may fail if the configured sandbox image does not exist." >&2 + fi + + # Defense-in-depth: verify Docker CLI in the running image before enabling + # sandbox. This avoids claiming sandbox is enabled when the image cannot + # launch sandbox containers. + if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --entrypoint docker openclaw-gateway --version >/dev/null 2>&1; then + echo "WARNING: Docker CLI not found inside the container image." >&2 + echo " Sandbox requires Docker CLI. Rebuild with --build-arg OPENCLAW_INSTALL_DOCKER_CLI=1" >&2 + echo " or use a local build (OPENCLAW_IMAGE=openclaw:local). Skipping sandbox setup." >&2 + SANDBOX_ENABLED="" + fi +fi + +# Apply sandbox config only if prerequisites are met. +if [[ -n "$SANDBOX_ENABLED" ]]; then + # Mount Docker socket via a dedicated compose overlay. This overlay is + # created only after sandbox prerequisites pass, so the socket is never + # exposed when sandbox cannot actually run. + if [[ -S "$DOCKER_SOCKET_PATH" ]]; then + SANDBOX_COMPOSE_FILE="$ROOT_DIR/docker-compose.sandbox.yml" + cat >"$SANDBOX_COMPOSE_FILE" <>"$SANDBOX_COMPOSE_FILE" < Sandbox: added Docker socket mount" + else + echo "WARNING: OPENCLAW_SANDBOX enabled but Docker socket not found at $DOCKER_SOCKET_PATH." >&2 + echo " Sandbox requires Docker socket access. Skipping sandbox setup." >&2 + SANDBOX_ENABLED="" + fi +fi + +if [[ -n "$SANDBOX_ENABLED" ]]; then + # Enable sandbox in OpenClaw config. + sandbox_config_ok=true + if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \ + config set agents.defaults.sandbox.mode "non-main" >/dev/null; then + echo "WARNING: Failed to set agents.defaults.sandbox.mode" >&2 + sandbox_config_ok=false + fi + if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \ + config set agents.defaults.sandbox.scope "agent" >/dev/null; then + echo "WARNING: Failed to set agents.defaults.sandbox.scope" >&2 + sandbox_config_ok=false + fi + if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \ + config set agents.defaults.sandbox.workspaceAccess "none" >/dev/null; then + echo "WARNING: Failed to set agents.defaults.sandbox.workspaceAccess" >&2 + sandbox_config_ok=false + fi + + if [[ "$sandbox_config_ok" == true ]]; then + echo "Sandbox enabled: mode=non-main, scope=agent, workspaceAccess=none" + echo "Docs: https://docs.openclaw.ai/gateway/sandboxing" + # Restart gateway with sandbox compose overlay to pick up socket mount + config. + docker compose "${COMPOSE_ARGS[@]}" up -d openclaw-gateway + else + echo "WARNING: Sandbox config was partially applied. Check errors above." >&2 + echo " Skipping gateway restart to avoid exposing Docker socket without a full sandbox policy." >&2 + if ! docker compose "${BASE_COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \ + config set agents.defaults.sandbox.mode "off" >/dev/null; then + echo "WARNING: Failed to roll back agents.defaults.sandbox.mode to off" >&2 + else + echo "Sandbox mode rolled back to off due to partial sandbox config failure." + fi + if [[ -n "${SANDBOX_COMPOSE_FILE:-}" ]]; then + rm -f "$SANDBOX_COMPOSE_FILE" + fi + # Ensure gateway service definition is reset without sandbox overlay mount. + docker compose "${BASE_COMPOSE_ARGS[@]}" up -d --force-recreate openclaw-gateway + fi +else + # Keep reruns deterministic: if sandbox is not active for this run, reset + # persisted sandbox mode so future execs do not require docker.sock by stale + # config alone. + if ! docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli \ + config set agents.defaults.sandbox.mode "off" >/dev/null; then + echo "WARNING: Failed to reset agents.defaults.sandbox.mode to off" >&2 + fi + if [[ -f "$ROOT_DIR/docker-compose.sandbox.yml" ]]; then + rm -f "$ROOT_DIR/docker-compose.sandbox.yml" + fi +fi + +echo "" +echo "Gateway running with host port mapping." +echo "Access from tailnet devices via the host's tailnet IP." +echo "Config: $OPENCLAW_CONFIG_DIR" +echo "Workspace: $OPENCLAW_WORKSPACE_DIR" +echo "Token: $OPENCLAW_GATEWAY_TOKEN" +echo "" +echo "Commands:" +echo " ${COMPOSE_HINT} logs -f openclaw-gateway" +echo " ${COMPOSE_HINT} exec openclaw-gateway node dist/index.js health --token \"$OPENCLAW_GATEWAY_TOKEN\"" diff --git a/scripts/podman/openclaw.container.in b/scripts/podman/openclaw.container.in index e0ad2ac8bde..1618774b841 100644 --- a/scripts/podman/openclaw.container.in +++ b/scripts/podman/openclaw.container.in @@ -1,5 +1,5 @@ # OpenClaw gateway — Podman Quadlet (rootless) -# Installed by setup-podman.sh into openclaw's ~/.config/containers/systemd/ +# Installed by scripts/podman/setup.sh into openclaw's ~/.config/containers/systemd/ # {{OPENCLAW_HOME}} is replaced at install time. [Unit] diff --git a/scripts/podman/setup.sh b/scripts/podman/setup.sh new file mode 100755 index 00000000000..1851271bee4 --- /dev/null +++ b/scripts/podman/setup.sh @@ -0,0 +1,312 @@ +#!/usr/bin/env bash +# One-time host setup for rootless OpenClaw in Podman: creates the openclaw +# user, builds the image, loads it into that user's Podman store, and installs +# the launch script. Run from repo root with sudo capability. +# +# Usage: ./scripts/podman/setup.sh [--quadlet|--container] +# --quadlet Install systemd Quadlet so the container runs as a user service +# --container Only install user + image + launch script; you start the container manually (default) +# Or set OPENCLAW_PODMAN_QUADLET=1 (or 0) to choose without a flag. +# +# After this, start the gateway manually: +# ./scripts/run-openclaw-podman.sh launch +# ./scripts/run-openclaw-podman.sh launch setup # onboarding wizard +# Or as the openclaw user: sudo -u openclaw /home/openclaw/run-openclaw-podman.sh +# If you used --quadlet, you can also: sudo systemctl --machine openclaw@ --user start openclaw.service +set -euo pipefail + +OPENCLAW_USER="${OPENCLAW_PODMAN_USER:-openclaw}" +REPO_PATH="${OPENCLAW_REPO_PATH:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}" +RUN_SCRIPT_SRC="$REPO_PATH/scripts/run-openclaw-podman.sh" +QUADLET_TEMPLATE="$REPO_PATH/scripts/podman/openclaw.container.in" + +require_cmd() { + if ! command -v "$1" >/dev/null 2>&1; then + echo "Missing dependency: $1" >&2 + exit 1 + fi +} + +is_writable_dir() { + local dir="$1" + [[ -n "$dir" && -d "$dir" && ! -L "$dir" && -w "$dir" && -x "$dir" ]] +} + +is_safe_tmp_base() { + local dir="$1" + local mode="" + local owner="" + is_writable_dir "$dir" || return 1 + mode="$(stat -Lc '%a' "$dir" 2>/dev/null || true)" + if [[ -n "$mode" ]]; then + local perm=$((8#$mode)) + if (( (perm & 0022) != 0 && (perm & 01000) == 0 )); then + return 1 + fi + fi + if is_root; then + owner="$(stat -Lc '%u' "$dir" 2>/dev/null || true)" + if [[ -n "$owner" && "$owner" != "0" ]]; then + return 1 + fi + fi + return 0 +} + +resolve_image_tmp_dir() { + if ! is_root && is_safe_tmp_base "${TMPDIR:-}"; then + printf '%s' "$TMPDIR" + return 0 + fi + if is_safe_tmp_base "/var/tmp"; then + printf '%s' "/var/tmp" + return 0 + fi + if is_safe_tmp_base "/tmp"; then + printf '%s' "/tmp" + return 0 + fi + printf '%s' "/tmp" +} + +is_root() { [[ "$(id -u)" -eq 0 ]]; } + +run_root() { + if is_root; then + "$@" + else + sudo "$@" + fi +} + +run_as_user() { + # When switching users, the caller's cwd may be inaccessible to the target + # user (e.g. a private home dir). Wrap in a subshell that cd's to a + # world-traversable directory so sudo/runuser don't fail with "cannot chdir". + # TODO: replace with fully rootless podman build to eliminate the need for + # user-switching entirely. + local user="$1" + shift + if command -v sudo >/dev/null 2>&1; then + ( cd /tmp 2>/dev/null || cd /; sudo -u "$user" "$@" ) + elif is_root && command -v runuser >/dev/null 2>&1; then + ( cd /tmp 2>/dev/null || cd /; runuser -u "$user" -- "$@" ) + else + echo "Need sudo (or root+runuser) to run commands as $user." >&2 + exit 1 + fi +} + +run_as_openclaw() { + # Avoid root writes into $OPENCLAW_HOME (symlink/hardlink/TOCTOU footguns). + # Anything under the target user's home should be created/modified as that user. + run_as_user "$OPENCLAW_USER" env HOME="$OPENCLAW_HOME" "$@" +} + +escape_sed_replacement_pipe_delim() { + # Escape replacement metacharacters for sed "s|...|...|g" replacement text. + printf '%s' "$1" | sed -e 's/[\\&|]/\\&/g' +} + +# Quadlet: opt-in via --quadlet or OPENCLAW_PODMAN_QUADLET=1 +INSTALL_QUADLET=false +for arg in "$@"; do + case "$arg" in + --quadlet) INSTALL_QUADLET=true ;; + --container) INSTALL_QUADLET=false ;; + esac +done +if [[ -n "${OPENCLAW_PODMAN_QUADLET:-}" ]]; then + case "${OPENCLAW_PODMAN_QUADLET,,}" in + 1|yes|true) INSTALL_QUADLET=true ;; + 0|no|false) INSTALL_QUADLET=false ;; + esac +fi + +require_cmd podman +if ! is_root; then + require_cmd sudo +fi +if [[ ! -f "$REPO_PATH/Dockerfile" ]]; then + echo "Dockerfile not found at $REPO_PATH. Set OPENCLAW_REPO_PATH to the repo root." >&2 + exit 1 +fi +if [[ ! -f "$RUN_SCRIPT_SRC" ]]; then + echo "Launch script not found at $RUN_SCRIPT_SRC." >&2 + exit 1 +fi + +generate_token_hex_32() { + if command -v openssl >/dev/null 2>&1; then + openssl rand -hex 32 + return 0 + fi + if command -v python3 >/dev/null 2>&1; then + python3 - <<'PY' +import secrets +print(secrets.token_hex(32)) +PY + return 0 + fi + if command -v od >/dev/null 2>&1; then + # 32 random bytes -> 64 lowercase hex chars + od -An -N32 -tx1 /dev/urandom | tr -d " \n" + return 0 + fi + echo "Missing dependency: need openssl or python3 (or od) to generate OPENCLAW_GATEWAY_TOKEN." >&2 + exit 1 +} + +user_exists() { + local user="$1" + if command -v getent >/dev/null 2>&1; then + getent passwd "$user" >/dev/null 2>&1 && return 0 + fi + id -u "$user" >/dev/null 2>&1 +} + +resolve_user_home() { + local user="$1" + local home="" + if command -v getent >/dev/null 2>&1; then + home="$(getent passwd "$user" 2>/dev/null | cut -d: -f6 || true)" + fi + if [[ -z "$home" && -f /etc/passwd ]]; then + home="$(awk -F: -v u="$user" '$1==u {print $6}' /etc/passwd 2>/dev/null || true)" + fi + if [[ -z "$home" ]]; then + home="/home/$user" + fi + printf '%s' "$home" +} + +resolve_nologin_shell() { + for cand in /usr/sbin/nologin /sbin/nologin /usr/bin/nologin /bin/false; do + if [[ -x "$cand" ]]; then + printf '%s' "$cand" + return 0 + fi + done + printf '%s' "/usr/sbin/nologin" +} + +# Create openclaw user (non-login, with home) if missing +if ! user_exists "$OPENCLAW_USER"; then + NOLOGIN_SHELL="$(resolve_nologin_shell)" + echo "Creating user $OPENCLAW_USER ($NOLOGIN_SHELL, with home)..." + if command -v useradd >/dev/null 2>&1; then + run_root useradd -m -s "$NOLOGIN_SHELL" "$OPENCLAW_USER" + elif command -v adduser >/dev/null 2>&1; then + # Debian/Ubuntu: adduser supports --disabled-password/--gecos. Busybox adduser differs. + run_root adduser --disabled-password --gecos "" --shell "$NOLOGIN_SHELL" "$OPENCLAW_USER" + else + echo "Neither useradd nor adduser found, cannot create user $OPENCLAW_USER." >&2 + exit 1 + fi +else + echo "User $OPENCLAW_USER already exists." +fi + +OPENCLAW_HOME="$(resolve_user_home "$OPENCLAW_USER")" +OPENCLAW_UID="$(id -u "$OPENCLAW_USER" 2>/dev/null || true)" +OPENCLAW_CONFIG="$OPENCLAW_HOME/.openclaw" +LAUNCH_SCRIPT_DST="$OPENCLAW_HOME/run-openclaw-podman.sh" + +# Prefer systemd user services (Quadlet) for production. Enable lingering early so rootless Podman can run +# without an interactive login. +if command -v loginctl &>/dev/null; then + run_root loginctl enable-linger "$OPENCLAW_USER" 2>/dev/null || true +fi +if [[ -n "${OPENCLAW_UID:-}" && -d /run/user ]] && command -v systemctl &>/dev/null; then + if [[ ! -d "/run/user/$OPENCLAW_UID" ]]; then + run_root install -d -m 700 -o "$OPENCLAW_UID" -g "$OPENCLAW_UID" "/run/user/$OPENCLAW_UID" || true + fi + run_root mkdir -p "/run/user/$OPENCLAW_UID/containers" || true + run_root chown "$OPENCLAW_UID:$OPENCLAW_UID" "/run/user/$OPENCLAW_UID/containers" || true + run_root chmod 700 "/run/user/$OPENCLAW_UID/containers" || true +fi + +mkdir_user_dirs_as_openclaw() { + run_root install -d -m 700 -o "$OPENCLAW_UID" -g "$OPENCLAW_UID" "$OPENCLAW_HOME" "$OPENCLAW_CONFIG" + run_root install -d -m 700 -o "$OPENCLAW_UID" -g "$OPENCLAW_UID" "$OPENCLAW_CONFIG/workspace" +} + +ensure_subid_entry() { + local file="$1" + if [[ ! -f "$file" ]]; then + return 1 + fi + grep -q "^${OPENCLAW_USER}:" "$file" 2>/dev/null +} + +if ! ensure_subid_entry /etc/subuid || ! ensure_subid_entry /etc/subgid; then + echo "WARNING: ${OPENCLAW_USER} may not have subuid/subgid ranges configured." >&2 + echo "If rootless Podman fails, add 'openclaw:100000:65536' to both /etc/subuid and /etc/subgid." >&2 +fi + +mkdir_user_dirs_as_openclaw + +IMAGE_TMP_BASE="$(resolve_image_tmp_dir)" +echo "Using temp base for image export: $IMAGE_TMP_BASE" +IMAGE_TAR_DIR="$(mktemp -d "${IMAGE_TMP_BASE%/}/openclaw-podman-image.XXXXXX")" +chmod 700 "$IMAGE_TAR_DIR" +IMAGE_TAR="$IMAGE_TAR_DIR/openclaw-image.tar" +cleanup_image_tar() { + rm -rf "$IMAGE_TAR_DIR" +} +trap cleanup_image_tar EXIT + +BUILD_ARGS=() +if [[ -n "${OPENCLAW_DOCKER_APT_PACKAGES:-}" ]]; then + BUILD_ARGS+=(--build-arg "OPENCLAW_DOCKER_APT_PACKAGES=${OPENCLAW_DOCKER_APT_PACKAGES}") +fi +if [[ -n "${OPENCLAW_EXTENSIONS:-}" ]]; then + BUILD_ARGS+=(--build-arg "OPENCLAW_EXTENSIONS=${OPENCLAW_EXTENSIONS}") +fi + +echo "Building image openclaw:local..." +podman build -t openclaw:local -f "$REPO_PATH/Dockerfile" "${BUILD_ARGS[@]}" "$REPO_PATH" +echo "Saving image to $IMAGE_TAR ..." +podman save -o "$IMAGE_TAR" openclaw:local + +echo "Loading image into $OPENCLAW_USER Podman store..." +run_as_openclaw podman load -i "$IMAGE_TAR" + +echo "Installing launch script to $LAUNCH_SCRIPT_DST ..." +run_root install -m 0755 -o "$OPENCLAW_UID" -g "$OPENCLAW_UID" "$RUN_SCRIPT_SRC" "$LAUNCH_SCRIPT_DST" + +if [[ ! -f "$OPENCLAW_CONFIG/.env" ]]; then + TOKEN="$(generate_token_hex_32)" + run_as_openclaw sh -lc "umask 077 && printf '%s\n' 'OPENCLAW_GATEWAY_TOKEN=$TOKEN' > '$OPENCLAW_CONFIG/.env'" + echo "Generated OPENCLAW_GATEWAY_TOKEN and wrote it to $OPENCLAW_CONFIG/.env" +fi + +if [[ ! -f "$OPENCLAW_CONFIG/openclaw.json" ]]; then + run_as_openclaw sh -lc "umask 077 && cat > '$OPENCLAW_CONFIG/openclaw.json' <<'JSON' +{ \"gateway\": { \"mode\": \"local\" } } +JSON" + echo "Wrote minimal config to $OPENCLAW_CONFIG/openclaw.json" +fi + +if [[ "$INSTALL_QUADLET" == true ]]; then + QUADLET_DIR="$OPENCLAW_HOME/.config/containers/systemd" + QUADLET_DST="$QUADLET_DIR/openclaw.container" + echo "Installing Quadlet to $QUADLET_DST ..." + run_as_openclaw mkdir -p "$QUADLET_DIR" + OPENCLAW_HOME_ESCAPED="$(escape_sed_replacement_pipe_delim "$OPENCLAW_HOME")" + sed "s|{{OPENCLAW_HOME}}|$OPENCLAW_HOME_ESCAPED|g" "$QUADLET_TEMPLATE" | \ + run_as_openclaw sh -lc "cat > '$QUADLET_DST'" + run_as_openclaw chmod 0644 "$QUADLET_DST" + + echo "Reloading and enabling user service..." + run_root systemctl --machine "${OPENCLAW_USER}@" --user daemon-reload + run_root systemctl --machine "${OPENCLAW_USER}@" --user enable --now openclaw.service + echo "Quadlet installed and service started." +else + echo "Container + launch script installed." +fi + +echo +echo "Next:" +echo " ./scripts/run-openclaw-podman.sh launch" +echo " ./scripts/run-openclaw-podman.sh launch setup" diff --git a/scripts/run-openclaw-podman.sh b/scripts/run-openclaw-podman.sh index 68b64915479..aa19d3350bf 100755 --- a/scripts/run-openclaw-podman.sh +++ b/scripts/run-openclaw-podman.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # Rootless OpenClaw in Podman: run after one-time setup. # -# One-time setup (from repo root): ./setup-podman.sh +# One-time setup (from repo root): ./scripts/podman/setup.sh # Then: # ./scripts/run-openclaw-podman.sh launch # Start gateway # ./scripts/run-openclaw-podman.sh launch setup # Onboarding wizard @@ -10,7 +10,7 @@ # sudo -u openclaw /home/openclaw/run-openclaw-podman.sh # sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup # -# Legacy: "setup-host" delegates to ../setup-podman.sh +# Legacy: "setup-host" delegates to the Podman setup script set -euo pipefail @@ -35,15 +35,19 @@ OPENCLAW_HOME="$(resolve_user_home "$OPENCLAW_USER")" OPENCLAW_UID="$(id -u "$OPENCLAW_USER" 2>/dev/null || true)" LAUNCH_SCRIPT="$OPENCLAW_HOME/run-openclaw-podman.sh" -# Legacy: setup-host → run setup-podman.sh +# Legacy: setup-host → run the Podman setup script if [[ "${1:-}" == "setup-host" ]]; then shift REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + SETUP_PODMAN="$REPO_ROOT/scripts/podman/setup.sh" + if [[ -f "$SETUP_PODMAN" ]]; then + exec "$SETUP_PODMAN" "$@" + fi SETUP_PODMAN="$REPO_ROOT/setup-podman.sh" if [[ -f "$SETUP_PODMAN" ]]; then exec "$SETUP_PODMAN" "$@" fi - echo "setup-podman.sh not found at $SETUP_PODMAN. Run from repo root: ./setup-podman.sh" >&2 + echo "Podman setup script not found. Run from repo root: ./scripts/podman/setup.sh" >&2 exit 1 fi @@ -228,4 +232,4 @@ podman run --pull="$PODMAN_PULL" -d --replace \ echo "Container $CONTAINER_NAME started. Dashboard: http://127.0.0.1:${HOST_GATEWAY_PORT}/" echo "Logs: podman logs -f $CONTAINER_NAME" -echo "For auto-start/restarts, use: ./setup-podman.sh --quadlet (Quadlet + systemd user service)." +echo "For auto-start/restarts, use: ./scripts/podman/setup.sh --quadlet (Quadlet + systemd user service)." diff --git a/setup-podman.sh b/setup-podman.sh index 5b904684ffa..50a17a57bb0 100755 --- a/setup-podman.sh +++ b/setup-podman.sh @@ -1,312 +1,12 @@ #!/usr/bin/env bash -# One-time host setup for rootless OpenClaw in Podman: creates the openclaw -# user, builds the image, loads it into that user's Podman store, and installs -# the launch script. Run from repo root with sudo capability. -# -# Usage: ./setup-podman.sh [--quadlet|--container] -# --quadlet Install systemd Quadlet so the container runs as a user service -# --container Only install user + image + launch script; you start the container manually (default) -# Or set OPENCLAW_PODMAN_QUADLET=1 (or 0) to choose without a flag. -# -# After this, start the gateway manually: -# ./scripts/run-openclaw-podman.sh launch -# ./scripts/run-openclaw-podman.sh launch setup # onboarding wizard -# Or as the openclaw user: sudo -u openclaw /home/openclaw/run-openclaw-podman.sh -# If you used --quadlet, you can also: sudo systemctl --machine openclaw@ --user start openclaw.service set -euo pipefail -OPENCLAW_USER="${OPENCLAW_PODMAN_USER:-openclaw}" -REPO_PATH="${OPENCLAW_REPO_PATH:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}" -RUN_SCRIPT_SRC="$REPO_PATH/scripts/run-openclaw-podman.sh" -QUADLET_TEMPLATE="$REPO_PATH/scripts/podman/openclaw.container.in" +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SCRIPT_PATH="$ROOT_DIR/scripts/podman/setup.sh" -require_cmd() { - if ! command -v "$1" >/dev/null 2>&1; then - echo "Missing dependency: $1" >&2 - exit 1 - fi -} - -is_writable_dir() { - local dir="$1" - [[ -n "$dir" && -d "$dir" && ! -L "$dir" && -w "$dir" && -x "$dir" ]] -} - -is_safe_tmp_base() { - local dir="$1" - local mode="" - local owner="" - is_writable_dir "$dir" || return 1 - mode="$(stat -Lc '%a' "$dir" 2>/dev/null || true)" - if [[ -n "$mode" ]]; then - local perm=$((8#$mode)) - if (( (perm & 0022) != 0 && (perm & 01000) == 0 )); then - return 1 - fi - fi - if is_root; then - owner="$(stat -Lc '%u' "$dir" 2>/dev/null || true)" - if [[ -n "$owner" && "$owner" != "0" ]]; then - return 1 - fi - fi - return 0 -} - -resolve_image_tmp_dir() { - if ! is_root && is_safe_tmp_base "${TMPDIR:-}"; then - printf '%s' "$TMPDIR" - return 0 - fi - if is_safe_tmp_base "/var/tmp"; then - printf '%s' "/var/tmp" - return 0 - fi - if is_safe_tmp_base "/tmp"; then - printf '%s' "/tmp" - return 0 - fi - printf '%s' "/tmp" -} - -is_root() { [[ "$(id -u)" -eq 0 ]]; } - -run_root() { - if is_root; then - "$@" - else - sudo "$@" - fi -} - -run_as_user() { - # When switching users, the caller's cwd may be inaccessible to the target - # user (e.g. a private home dir). Wrap in a subshell that cd's to a - # world-traversable directory so sudo/runuser don't fail with "cannot chdir". - # TODO: replace with fully rootless podman build to eliminate the need for - # user-switching entirely. - local user="$1" - shift - if command -v sudo >/dev/null 2>&1; then - ( cd /tmp 2>/dev/null || cd /; sudo -u "$user" "$@" ) - elif is_root && command -v runuser >/dev/null 2>&1; then - ( cd /tmp 2>/dev/null || cd /; runuser -u "$user" -- "$@" ) - else - echo "Need sudo (or root+runuser) to run commands as $user." >&2 - exit 1 - fi -} - -run_as_openclaw() { - # Avoid root writes into $OPENCLAW_HOME (symlink/hardlink/TOCTOU footguns). - # Anything under the target user's home should be created/modified as that user. - run_as_user "$OPENCLAW_USER" env HOME="$OPENCLAW_HOME" "$@" -} - -escape_sed_replacement_pipe_delim() { - # Escape replacement metacharacters for sed "s|...|...|g" replacement text. - printf '%s' "$1" | sed -e 's/[\\&|]/\\&/g' -} - -# Quadlet: opt-in via --quadlet or OPENCLAW_PODMAN_QUADLET=1 -INSTALL_QUADLET=false -for arg in "$@"; do - case "$arg" in - --quadlet) INSTALL_QUADLET=true ;; - --container) INSTALL_QUADLET=false ;; - esac -done -if [[ -n "${OPENCLAW_PODMAN_QUADLET:-}" ]]; then - case "${OPENCLAW_PODMAN_QUADLET,,}" in - 1|yes|true) INSTALL_QUADLET=true ;; - 0|no|false) INSTALL_QUADLET=false ;; - esac -fi - -require_cmd podman -if ! is_root; then - require_cmd sudo -fi -if [[ ! -f "$REPO_PATH/Dockerfile" ]]; then - echo "Dockerfile not found at $REPO_PATH. Set OPENCLAW_REPO_PATH to the repo root." >&2 - exit 1 -fi -if [[ ! -f "$RUN_SCRIPT_SRC" ]]; then - echo "Launch script not found at $RUN_SCRIPT_SRC." >&2 +if [[ ! -f "$SCRIPT_PATH" ]]; then + echo "Podman setup script not found at $SCRIPT_PATH" >&2 exit 1 fi -generate_token_hex_32() { - if command -v openssl >/dev/null 2>&1; then - openssl rand -hex 32 - return 0 - fi - if command -v python3 >/dev/null 2>&1; then - python3 - <<'PY' -import secrets -print(secrets.token_hex(32)) -PY - return 0 - fi - if command -v od >/dev/null 2>&1; then - # 32 random bytes -> 64 lowercase hex chars - od -An -N32 -tx1 /dev/urandom | tr -d " \n" - return 0 - fi - echo "Missing dependency: need openssl or python3 (or od) to generate OPENCLAW_GATEWAY_TOKEN." >&2 - exit 1 -} - -user_exists() { - local user="$1" - if command -v getent >/dev/null 2>&1; then - getent passwd "$user" >/dev/null 2>&1 && return 0 - fi - id -u "$user" >/dev/null 2>&1 -} - -resolve_user_home() { - local user="$1" - local home="" - if command -v getent >/dev/null 2>&1; then - home="$(getent passwd "$user" 2>/dev/null | cut -d: -f6 || true)" - fi - if [[ -z "$home" && -f /etc/passwd ]]; then - home="$(awk -F: -v u="$user" '$1==u {print $6}' /etc/passwd 2>/dev/null || true)" - fi - if [[ -z "$home" ]]; then - home="/home/$user" - fi - printf '%s' "$home" -} - -resolve_nologin_shell() { - for cand in /usr/sbin/nologin /sbin/nologin /usr/bin/nologin /bin/false; do - if [[ -x "$cand" ]]; then - printf '%s' "$cand" - return 0 - fi - done - printf '%s' "/usr/sbin/nologin" -} - -# Create openclaw user (non-login, with home) if missing -if ! user_exists "$OPENCLAW_USER"; then - NOLOGIN_SHELL="$(resolve_nologin_shell)" - echo "Creating user $OPENCLAW_USER ($NOLOGIN_SHELL, with home)..." - if command -v useradd >/dev/null 2>&1; then - run_root useradd -m -s "$NOLOGIN_SHELL" "$OPENCLAW_USER" - elif command -v adduser >/dev/null 2>&1; then - # Debian/Ubuntu: adduser supports --disabled-password/--gecos. Busybox adduser differs. - run_root adduser --disabled-password --gecos "" --shell "$NOLOGIN_SHELL" "$OPENCLAW_USER" - else - echo "Neither useradd nor adduser found, cannot create user $OPENCLAW_USER." >&2 - exit 1 - fi -else - echo "User $OPENCLAW_USER already exists." -fi - -OPENCLAW_HOME="$(resolve_user_home "$OPENCLAW_USER")" -OPENCLAW_UID="$(id -u "$OPENCLAW_USER" 2>/dev/null || true)" -OPENCLAW_CONFIG="$OPENCLAW_HOME/.openclaw" -LAUNCH_SCRIPT_DST="$OPENCLAW_HOME/run-openclaw-podman.sh" - -# Prefer systemd user services (Quadlet) for production. Enable lingering early so rootless Podman can run -# without an interactive login. -if command -v loginctl &>/dev/null; then - run_root loginctl enable-linger "$OPENCLAW_USER" 2>/dev/null || true -fi -if [[ -n "${OPENCLAW_UID:-}" && -d /run/user ]] && command -v systemctl &>/dev/null; then - run_root systemctl start "user@${OPENCLAW_UID}.service" 2>/dev/null || true -fi - -# Rootless Podman needs subuid/subgid for the run user -if ! grep -q "^${OPENCLAW_USER}:" /etc/subuid 2>/dev/null; then - echo "Warning: $OPENCLAW_USER has no subuid range. Rootless Podman may fail." >&2 - echo " Add a line to /etc/subuid and /etc/subgid, e.g.: $OPENCLAW_USER:100000:65536" >&2 -fi - -echo "Creating $OPENCLAW_CONFIG and workspace..." -run_as_openclaw mkdir -p "$OPENCLAW_CONFIG/workspace" -run_as_openclaw chmod 700 "$OPENCLAW_CONFIG" "$OPENCLAW_CONFIG/workspace" 2>/dev/null || true - -ENV_FILE="$OPENCLAW_CONFIG/.env" -if run_as_openclaw test -f "$ENV_FILE"; then - if ! run_as_openclaw grep -q '^OPENCLAW_GATEWAY_TOKEN=' "$ENV_FILE" 2>/dev/null; then - TOKEN="$(generate_token_hex_32)" - printf 'OPENCLAW_GATEWAY_TOKEN=%s\n' "$TOKEN" | run_as_openclaw tee -a "$ENV_FILE" >/dev/null - echo "Added OPENCLAW_GATEWAY_TOKEN to $ENV_FILE." - fi - run_as_openclaw chmod 600 "$ENV_FILE" 2>/dev/null || true -else - TOKEN="$(generate_token_hex_32)" - printf 'OPENCLAW_GATEWAY_TOKEN=%s\n' "$TOKEN" | run_as_openclaw tee "$ENV_FILE" >/dev/null - run_as_openclaw chmod 600 "$ENV_FILE" 2>/dev/null || true - echo "Created $ENV_FILE with new token." -fi - -# The gateway refuses to start unless gateway.mode=local is set in config. -# Make first-run non-interactive; users can run the wizard later to configure channels/providers. -OPENCLAW_JSON="$OPENCLAW_CONFIG/openclaw.json" -if ! run_as_openclaw test -f "$OPENCLAW_JSON"; then - printf '%s\n' '{ gateway: { mode: "local" } }' | run_as_openclaw tee "$OPENCLAW_JSON" >/dev/null - run_as_openclaw chmod 600 "$OPENCLAW_JSON" 2>/dev/null || true - echo "Created $OPENCLAW_JSON (minimal gateway.mode=local)." -fi - -echo "Building image from $REPO_PATH..." -BUILD_ARGS=() -[[ -n "${OPENCLAW_DOCKER_APT_PACKAGES:-}" ]] && BUILD_ARGS+=(--build-arg "OPENCLAW_DOCKER_APT_PACKAGES=${OPENCLAW_DOCKER_APT_PACKAGES}") -[[ -n "${OPENCLAW_EXTENSIONS:-}" ]] && BUILD_ARGS+=(--build-arg "OPENCLAW_EXTENSIONS=${OPENCLAW_EXTENSIONS}") -podman build ${BUILD_ARGS[@]+"${BUILD_ARGS[@]}"} -t openclaw:local -f "$REPO_PATH/Dockerfile" "$REPO_PATH" - -echo "Loading image into $OPENCLAW_USER's Podman store..." -TMP_IMAGE_DIR="$(resolve_image_tmp_dir)" -echo "Using temporary image dir: $TMP_IMAGE_DIR" -TMP_STAGE_DIR="$(mktemp -d -p "$TMP_IMAGE_DIR" openclaw-image.XXXXXX)" -TMP_IMAGE="$TMP_STAGE_DIR/image.tar" -chmod 700 "$TMP_STAGE_DIR" -trap 'rm -rf "$TMP_STAGE_DIR"' EXIT -podman save openclaw:local -o "$TMP_IMAGE" -chmod 600 "$TMP_IMAGE" -# Stream the image into the target user's podman load so private temp directories -# do not need to be traversable by $OPENCLAW_USER. -cat "$TMP_IMAGE" | run_as_user "$OPENCLAW_USER" env HOME="$OPENCLAW_HOME" podman load -rm -rf "$TMP_STAGE_DIR" -trap - EXIT - -echo "Copying launch script to $LAUNCH_SCRIPT_DST..." -run_root cat "$RUN_SCRIPT_SRC" | run_as_openclaw tee "$LAUNCH_SCRIPT_DST" >/dev/null -run_as_openclaw chmod 755 "$LAUNCH_SCRIPT_DST" - -# Optionally install systemd quadlet for openclaw user (rootless Podman + systemd) -QUADLET_DIR="$OPENCLAW_HOME/.config/containers/systemd" -if [[ "$INSTALL_QUADLET" == true && -f "$QUADLET_TEMPLATE" ]]; then - echo "Installing systemd quadlet for $OPENCLAW_USER..." - run_as_openclaw mkdir -p "$QUADLET_DIR" - OPENCLAW_HOME_SED="$(escape_sed_replacement_pipe_delim "$OPENCLAW_HOME")" - sed "s|{{OPENCLAW_HOME}}|$OPENCLAW_HOME_SED|g" "$QUADLET_TEMPLATE" | run_as_openclaw tee "$QUADLET_DIR/openclaw.container" >/dev/null - run_as_openclaw chmod 700 "$OPENCLAW_HOME/.config" "$OPENCLAW_HOME/.config/containers" "$QUADLET_DIR" 2>/dev/null || true - run_as_openclaw chmod 600 "$QUADLET_DIR/openclaw.container" 2>/dev/null || true - if command -v systemctl &>/dev/null; then - run_root systemctl --machine "${OPENCLAW_USER}@" --user daemon-reload 2>/dev/null || true - run_root systemctl --machine "${OPENCLAW_USER}@" --user enable openclaw.service 2>/dev/null || true - run_root systemctl --machine "${OPENCLAW_USER}@" --user start openclaw.service 2>/dev/null || true - fi -fi - -echo "" -echo "Setup complete. Start the gateway:" -echo " $RUN_SCRIPT_SRC launch" -echo " $RUN_SCRIPT_SRC launch setup # onboarding wizard" -echo "Or as $OPENCLAW_USER (e.g. from cron):" -echo " sudo -u $OPENCLAW_USER $LAUNCH_SCRIPT_DST" -echo " sudo -u $OPENCLAW_USER $LAUNCH_SCRIPT_DST setup" -if [[ "$INSTALL_QUADLET" == true ]]; then - echo "Or use systemd (quadlet):" - echo " sudo systemctl --machine ${OPENCLAW_USER}@ --user start openclaw.service" - echo " sudo systemctl --machine ${OPENCLAW_USER}@ --user status openclaw.service" -else - echo "To install systemd quadlet later: $0 --quadlet" -fi +exec "$SCRIPT_PATH" "$@" diff --git a/src/docker-setup.e2e.test.ts b/src/docker-setup.e2e.test.ts index 3b46aac5c0c..04b3823388f 100644 --- a/src/docker-setup.e2e.test.ts +++ b/src/docker-setup.e2e.test.ts @@ -50,13 +50,14 @@ exit 0 async function createDockerSetupSandbox(): Promise { const rootDir = await mkdtemp(join(tmpdir(), "openclaw-docker-setup-")); - const scriptPath = join(rootDir, "docker-setup.sh"); + const scriptPath = join(rootDir, "scripts", "docker", "setup.sh"); const dockerfilePath = join(rootDir, "Dockerfile"); const composePath = join(rootDir, "docker-compose.yml"); const binDir = join(rootDir, "bin"); const logPath = join(rootDir, "docker-stub.log"); - await copyFile(join(repoRoot, "docker-setup.sh"), scriptPath); + await mkdir(join(rootDir, "scripts", "docker"), { recursive: true }); + await copyFile(join(repoRoot, "scripts", "docker", "setup.sh"), scriptPath); await chmod(scriptPath, 0o755); await writeFile(dockerfilePath, "FROM scratch\n"); await writeFile( @@ -168,7 +169,7 @@ function resolveBashForCompatCheck(): string | null { return null; } -describe("docker-setup.sh", () => { +describe("scripts/docker/setup.sh", () => { let sandbox: DockerSetupSandbox | null = null; beforeAll(async () => { @@ -439,7 +440,7 @@ describe("docker-setup.sh", () => { }); it("avoids associative arrays so the script remains Bash 3.2-compatible", async () => { - const script = await readFile(join(repoRoot, "docker-setup.sh"), "utf8"); + const script = await readFile(join(repoRoot, "scripts", "docker", "setup.sh"), "utf8"); expect(script).not.toMatch(/^\s*declare -A\b/m); const systemBash = resolveBashForCompatCheck(); @@ -456,9 +457,13 @@ describe("docker-setup.sh", () => { return; } - const syntaxCheck = spawnSync(systemBash, ["-n", join(repoRoot, "docker-setup.sh")], { - encoding: "utf8", - }); + const syntaxCheck = spawnSync( + systemBash, + ["-n", join(repoRoot, "scripts", "docker", "setup.sh")], + { + encoding: "utf8", + }, + ); expect(syntaxCheck.status).toBe(0); expect(syntaxCheck.stderr).not.toContain("declare: -A: invalid option"); From a94e21e0a77602140afa60b4609be61fbff662a2 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 13:40:10 -0700 Subject: [PATCH 09/69] docs(install): update container setup paths --- .dockerignore | 2 +- docker-compose.yml | 2 +- docs/gateway/sandboxing.md | 2 +- docs/install/docker.md | 10 +++++----- docs/install/podman.md | 22 +++++++++++----------- scripts/shell-helpers/README.md | 2 +- scripts/shell-helpers/clawdock-helpers.sh | 2 +- 7 files changed, 21 insertions(+), 21 deletions(-) diff --git a/.dockerignore b/.dockerignore index f24c490e9ad..c6cc1510bcf 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,7 +1,7 @@ .git .worktrees -# Sensitive files – docker-setup.sh writes .env with OPENCLAW_GATEWAY_TOKEN +# Sensitive files – scripts/docker/setup.sh writes .env with OPENCLAW_GATEWAY_TOKEN # into the project root; keep it out of the build context. .env .env.* diff --git a/docker-compose.yml b/docker-compose.yml index c0bffc64458..0a55b342e92 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -16,7 +16,7 @@ services: ## Uncomment the lines below to enable sandbox isolation ## (agents.defaults.sandbox). Requires Docker CLI in the image ## (build with --build-arg OPENCLAW_INSTALL_DOCKER_CLI=1) or use - ## docker-setup.sh with OPENCLAW_SANDBOX=1 for automated setup. + ## scripts/docker/setup.sh with OPENCLAW_SANDBOX=1 for automated setup. ## Set DOCKER_GID to the host's docker group GID (run: stat -c '%g' /var/run/docker.sock). # - /var/run/docker.sock:/var/run/docker.sock # group_add: diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md index 12650357724..e49372ddc41 100644 --- a/docs/gateway/sandboxing.md +++ b/docs/gateway/sandboxing.md @@ -399,7 +399,7 @@ Security defaults: Docker installs and the containerized gateway live here: [Docker](/install/docker) -For Docker gateway deployments, `docker-setup.sh` can bootstrap sandbox config. +For Docker gateway deployments, `scripts/docker/setup.sh` can bootstrap sandbox config. Set `OPENCLAW_SANDBOX=1` (or `true`/`yes`/`on`) to enable that path. You can override socket location with `OPENCLAW_DOCKER_SOCKET`. Full setup and env reference: [Docker](/install/docker#enable-agent-sandbox-for-docker-gateway-opt-in). diff --git a/docs/install/docker.md b/docs/install/docker.md index aaaa11f9917..ce78993e737 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -32,14 +32,14 @@ Docker is **optional**. Use it only if you want a containerized gateway or to va From the repo root, run the setup script: ```bash - ./docker-setup.sh + ./scripts/docker/setup.sh ``` This builds the gateway image locally. To use a pre-built image instead: ```bash export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" - ./docker-setup.sh + ./scripts/docker/setup.sh ``` Pre-built images are published at the @@ -139,7 +139,7 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA ### LAN vs loopback -`docker-setup.sh` defaults `OPENCLAW_GATEWAY_BIND=lan` so host access to +`scripts/docker/setup.sh` defaults `OPENCLAW_GATEWAY_BIND=lan` so host access to `http://127.0.0.1:18789` works with Docker port publishing. - `lan` (default): host browser and host CLI can reach the published gateway port. @@ -180,7 +180,7 @@ See the [`ClawDock` Helper README](https://github.com/openclaw/openclaw/blob/mai ```bash export OPENCLAW_SANDBOX=1 - ./docker-setup.sh + ./scripts/docker/setup.sh ``` Custom socket path (e.g. rootless Docker): @@ -188,7 +188,7 @@ See the [`ClawDock` Helper README](https://github.com/openclaw/openclaw/blob/mai ```bash export OPENCLAW_SANDBOX=1 export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock - ./docker-setup.sh + ./scripts/docker/setup.sh ``` The script mounts `docker.sock` only after sandbox prerequisites pass. If diff --git a/docs/install/podman.md b/docs/install/podman.md index 8c8de73bcd2..c21980b5c08 100644 --- a/docs/install/podman.md +++ b/docs/install/podman.md @@ -21,7 +21,7 @@ Run the OpenClaw Gateway in a **rootless** Podman container. Uses the same image From the repo root, run the setup script. It creates a dedicated `openclaw` user, builds the container image, and installs the launch script: ```bash - ./setup-podman.sh + ./scripts/podman/setup.sh ``` This also creates a minimal config at `~openclaw/.openclaw/openclaw.json` (sets `gateway.mode` to `"local"`) so the Gateway can start without running the wizard. @@ -29,12 +29,12 @@ Run the OpenClaw Gateway in a **rootless** Podman container. Uses the same image By default the container is **not** installed as a systemd service -- you start it manually in the next step. For a production-style setup with auto-start and restarts, pass `--quadlet` instead: ```bash - ./setup-podman.sh --quadlet + ./scripts/podman/setup.sh --quadlet ``` (Or set `OPENCLAW_PODMAN_QUADLET=1`. Use `--container` to install only the container and launch script.) - **Optional build-time env vars** (set before running `setup-podman.sh`): + **Optional build-time env vars** (set before running `scripts/podman/setup.sh`): - `OPENCLAW_DOCKER_APT_PACKAGES` -- install extra apt packages during image build. - `OPENCLAW_EXTENSIONS` -- pre-install extension dependencies (space-separated names, e.g. `diagnostics-otel matrix`). @@ -64,7 +64,7 @@ Run the OpenClaw Gateway in a **rootless** Podman container. Uses the same image ## Systemd (Quadlet, optional) -If you ran `./setup-podman.sh --quadlet` (or `OPENCLAW_PODMAN_QUADLET=1`), a [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) unit is installed so the gateway runs as a systemd user service for the openclaw user. The service is enabled and started at the end of setup. +If you ran `./scripts/podman/setup.sh --quadlet` (or `OPENCLAW_PODMAN_QUADLET=1`), a [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) unit is installed so the gateway runs as a systemd user service for the openclaw user. The service is enabled and started at the end of setup. - **Start:** `sudo systemctl --machine openclaw@ --user start openclaw.service` - **Stop:** `sudo systemctl --machine openclaw@ --user stop openclaw.service` @@ -73,11 +73,11 @@ If you ran `./setup-podman.sh --quadlet` (or `OPENCLAW_PODMAN_QUADLET=1`), a [Po The quadlet file lives at `~openclaw/.config/containers/systemd/openclaw.container`. To change ports or env, edit that file (or the `.env` it sources), then `sudo systemctl --machine openclaw@ --user daemon-reload` and restart the service. On boot, the service starts automatically if lingering is enabled for openclaw (setup does this when loginctl is available). -To add quadlet **after** an initial setup that did not use it, re-run: `./setup-podman.sh --quadlet`. +To add quadlet **after** an initial setup that did not use it, re-run: `./scripts/podman/setup.sh --quadlet`. ## The openclaw user (non-login) -`setup-podman.sh` creates a dedicated system user `openclaw`: +`scripts/podman/setup.sh` creates a dedicated system user `openclaw`: - **Shell:** `nologin` — no interactive login; reduces attack surface. - **Home:** e.g. `/home/openclaw` — holds `~/.openclaw` (config, workspace) and the launch script `run-openclaw-podman.sh`. @@ -98,7 +98,7 @@ To add quadlet **after** an initial setup that did not use it, re-run: `./setup- ## Environment and config -- **Token:** Stored in `~openclaw/.openclaw/.env` as `OPENCLAW_GATEWAY_TOKEN`. `setup-podman.sh` and `run-openclaw-podman.sh` generate it if missing (uses `openssl`, `python3`, or `od`). +- **Token:** Stored in `~openclaw/.openclaw/.env` as `OPENCLAW_GATEWAY_TOKEN`. `scripts/podman/setup.sh` and `run-openclaw-podman.sh` generate it if missing (uses `openssl`, `python3`, or `od`). - **Optional:** In that `.env` you can set provider keys (e.g. `GROQ_API_KEY`, `OLLAMA_API_KEY`) and other OpenClaw env vars. - **Host ports:** By default the script maps `18789` (gateway) and `18790` (bridge). Override the **host** port mapping with `OPENCLAW_PODMAN_GATEWAY_HOST_PORT` and `OPENCLAW_PODMAN_BRIDGE_HOST_PORT` when launching. - **Gateway bind:** By default, `run-openclaw-podman.sh` starts the gateway with `--bind loopback` for safe local access. To expose on LAN, set `OPENCLAW_GATEWAY_BIND=lan` and configure `gateway.controlUi.allowedOrigins` (or explicitly enable host-header fallback) in `openclaw.json`. @@ -110,7 +110,7 @@ To add quadlet **after** an initial setup that did not use it, re-run: `./setup- - **Ephemeral sandbox tmpfs:** if you enable `agents.defaults.sandbox`, the tool sandbox containers mount `tmpfs` at `/tmp`, `/var/tmp`, and `/run`. Those paths are memory-backed and disappear with the sandbox container; the top-level Podman container setup does not add its own tmpfs mounts. - **Disk growth hotspots:** the main paths to watch are `media/`, `agents//sessions/sessions.json`, transcript JSONL files, `cron/runs/*.jsonl`, and rolling file logs under `/tmp/openclaw/` (or your configured `logging.file`). -`setup-podman.sh` now stages the image tar in a private temp directory and prints the chosen base dir during setup. For non-root runs it accepts `TMPDIR` only when that base is safe to use; otherwise it falls back to `/var/tmp`, then `/tmp`. The saved tar stays owner-only and is streamed into the target user’s `podman load`, so private caller temp dirs do not block setup. +`scripts/podman/setup.sh` now stages the image tar in a private temp directory and prints the chosen base dir during setup. For non-root runs it accepts `TMPDIR` only when that base is safe to use; otherwise it falls back to `/var/tmp`, then `/tmp`. The saved tar stays owner-only and is streamed into the target user’s `podman load`, so private caller temp dirs do not block setup. ## Useful commands @@ -122,12 +122,12 @@ To add quadlet **after** an initial setup that did not use it, re-run: `./setup- ## Troubleshooting - **Permission denied (EACCES) on config or auth-profiles:** The container defaults to `--userns=keep-id` and runs as the same uid/gid as the host user running the script. Ensure your host `OPENCLAW_CONFIG_DIR` and `OPENCLAW_WORKSPACE_DIR` are owned by that user. -- **Gateway start blocked (missing `gateway.mode=local`):** Ensure `~openclaw/.openclaw/openclaw.json` exists and sets `gateway.mode="local"`. `setup-podman.sh` creates this file if missing. +- **Gateway start blocked (missing `gateway.mode=local`):** Ensure `~openclaw/.openclaw/openclaw.json` exists and sets `gateway.mode="local"`. `scripts/podman/setup.sh` creates this file if missing. - **Rootless Podman fails for user openclaw:** Check `/etc/subuid` and `/etc/subgid` contain a line for `openclaw` (e.g. `openclaw:100000:65536`). Add it if missing and restart. - **Container name in use:** The launch script uses `podman run --replace`, so the existing container is replaced when you start again. To clean up manually: `podman rm -f openclaw`. -- **Script not found when running as openclaw:** Ensure `setup-podman.sh` was run so that `run-openclaw-podman.sh` is copied to openclaw’s home (e.g. `/home/openclaw/run-openclaw-podman.sh`). +- **Script not found when running as openclaw:** Ensure `scripts/podman/setup.sh` was run so that `run-openclaw-podman.sh` is copied to openclaw’s home (e.g. `/home/openclaw/run-openclaw-podman.sh`). - **Quadlet service not found or fails to start:** Run `sudo systemctl --machine openclaw@ --user daemon-reload` after editing the `.container` file. Quadlet requires cgroups v2: `podman info --format '{{.Host.CgroupsVersion}}'` should show `2`. ## Optional: run as your own user -To run the gateway as your normal user (no dedicated openclaw user): build the image, create `~/.openclaw/.env` with `OPENCLAW_GATEWAY_TOKEN`, and run the container with `--userns=keep-id` and mounts to your `~/.openclaw`. The launch script is designed for the openclaw-user flow; for a single-user setup you can instead run the `podman run` command from the script manually, pointing config and workspace to your home. Recommended for most users: use `setup-podman.sh` and run as the openclaw user so config and process are isolated. +To run the gateway as your normal user (no dedicated openclaw user): build the image, create `~/.openclaw/.env` with `OPENCLAW_GATEWAY_TOKEN`, and run the container with `--userns=keep-id` and mounts to your `~/.openclaw`. The launch script is designed for the openclaw-user flow; for a single-user setup you can instead run the `podman run` command from the script manually, pointing config and workspace to your home. Recommended for most users: use `scripts/podman/setup.sh` and run as the openclaw user so config and process are isolated. diff --git a/scripts/shell-helpers/README.md b/scripts/shell-helpers/README.md index 302606ee002..b789048a975 100644 --- a/scripts/shell-helpers/README.md +++ b/scripts/shell-helpers/README.md @@ -209,7 +209,7 @@ docker ps - Docker and Docker Compose installed - Bash or Zsh shell -- OpenClaw project (from `docker-setup.sh`) +- OpenClaw project (run `scripts/docker/setup.sh`) ## Development diff --git a/scripts/shell-helpers/clawdock-helpers.sh b/scripts/shell-helpers/clawdock-helpers.sh index 8c491374799..6351aa97f0c 100755 --- a/scripts/shell-helpers/clawdock-helpers.sh +++ b/scripts/shell-helpers/clawdock-helpers.sh @@ -114,7 +114,7 @@ _clawdock_ensure_dir() { echo "Clone it first:" echo "" echo " git clone https://github.com/openclaw/openclaw.git ~/openclaw" - echo " cd ~/openclaw && ./docker-setup.sh" + echo " cd ~/openclaw && ./scripts/docker/setup.sh" echo "" echo "Or set CLAWDOCK_DIR if it's elsewhere:" echo "" From f1be7d4cb343b957455b93181983e93b6e95ee14 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 13:44:35 -0700 Subject: [PATCH 10/69] fix(ci): isolate memory OOM hotspots from unit-fast --- test/fixtures/test-parallel.behavior.json | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/test/fixtures/test-parallel.behavior.json b/test/fixtures/test-parallel.behavior.json index b1ed463612e..9d4d5e58f40 100644 --- a/test/fixtures/test-parallel.behavior.json +++ b/test/fixtures/test-parallel.behavior.json @@ -22,6 +22,26 @@ { "file": "src/cli/command-secret-gateway.test.ts", "reason": "Clean in isolation, but can hang after sharing the broad lane." + }, + { + "file": "src/memory/manager.get-concurrency.test.ts", + "reason": "Memory manager cache concurrency coverage can spike shared unit-fast heap on Linux Node 24." + }, + { + "file": "src/memory/manager.vector-dedupe.test.ts", + "reason": "Vector dedupe coverage exercises the memory manager/sqlite stack and is safer outside shared unit-fast forks." + }, + { + "file": "src/memory/manager.watcher-config.test.ts", + "reason": "Watcher config coverage reuses memory manager caches and is safer outside shared unit-fast forks." + }, + { + "file": "src/memory/manager.embedding-batches.test.ts", + "reason": "Embedding batch coverage inflates memory manager state and is safer outside shared unit-fast forks." + }, + { + "file": "src/memory/manager.readonly-recovery.test.ts", + "reason": "Readonly recovery coverage exercises sqlite reopen flows and is safer outside shared unit-fast forks." } ], "threadSingleton": [ From b7c39aa4d4e0813bb63919b70ff845976b514181 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 13:56:40 -0700 Subject: [PATCH 11/69] fix(ci): isolate config doc baseline heap pressure --- src/config/doc-baseline.ts | 1 + src/config/schema.ts | 16 +++++++++++----- test/fixtures/test-parallel.behavior.json | 4 ++++ 3 files changed, 16 insertions(+), 5 deletions(-) diff --git a/src/config/doc-baseline.ts b/src/config/doc-baseline.ts index b90b42f3b78..2f6031589d8 100644 --- a/src/config/doc-baseline.ts +++ b/src/config/doc-baseline.ts @@ -497,6 +497,7 @@ async function loadBundledConfigSchemaResponse(): Promise logConfigDocBaselineDebug(`imported ${channelPlugins.length} bundled channel plugins`); return buildConfigSchema({ + cache: false, plugins: manifestRegistry.plugins .filter((plugin) => plugin.origin === "bundled") .map((plugin) => ({ diff --git a/src/config/schema.ts b/src/config/schema.ts index c81e08ea3c3..2329d8fbc78 100644 --- a/src/config/schema.ts +++ b/src/config/schema.ts @@ -450,6 +450,7 @@ function buildBaseConfigSchema(): ConfigSchemaResponse { export function buildConfigSchema(params?: { plugins?: PluginUiMetadata[]; channels?: ChannelUiMetadata[]; + cache?: boolean; }): ConfigSchemaResponse { const base = buildBaseConfigSchema(); const plugins = params?.plugins ?? []; @@ -457,10 +458,13 @@ export function buildConfigSchema(params?: { if (plugins.length === 0 && channels.length === 0) { return base; } - const cacheKey = buildMergedSchemaCacheKey({ plugins, channels }); - const cached = mergedSchemaCache.get(cacheKey); - if (cached) { - return cached; + const useCache = params?.cache !== false; + const cacheKey = useCache ? buildMergedSchemaCacheKey({ plugins, channels }) : null; + if (cacheKey) { + const cached = mergedSchemaCache.get(cacheKey); + if (cached) { + return cached; + } } const mergedWithoutSensitiveHints = applyHeartbeatTargetHints( applyChannelHints(applyPluginHints(base.uiHints, plugins), channels), @@ -480,7 +484,9 @@ export function buildConfigSchema(params?: { schema: mergedSchema, uiHints: mergedHints, }; - setMergedSchemaCache(cacheKey, merged); + if (cacheKey) { + setMergedSchemaCache(cacheKey, merged); + } return merged; } diff --git a/test/fixtures/test-parallel.behavior.json b/test/fixtures/test-parallel.behavior.json index 9d4d5e58f40..3f7f895a3fb 100644 --- a/test/fixtures/test-parallel.behavior.json +++ b/test/fixtures/test-parallel.behavior.json @@ -23,6 +23,10 @@ "file": "src/cli/command-secret-gateway.test.ts", "reason": "Clean in isolation, but can hang after sharing the broad lane." }, + { + "file": "src/config/doc-baseline.test.ts", + "reason": "Builds the full bundled config schema graph and is safer outside the shared unit-fast heap." + }, { "file": "src/memory/manager.get-concurrency.test.ts", "reason": "Memory manager cache concurrency coverage can spike shared unit-fast heap on Linux Node 24." From 98298f79319fb8914330300f3768dfa1faa04c90 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 14:02:19 -0700 Subject: [PATCH 12/69] fix(ci): trace test runner memory retention --- scripts/test-parallel-memory.mjs | 103 +++++++++++++++++++++++ scripts/test-parallel.mjs | 128 +++++++++++++++++++++++++++++ test/scripts/test-parallel.test.ts | 33 ++++++++ 3 files changed, 264 insertions(+) create mode 100644 scripts/test-parallel-memory.mjs diff --git a/scripts/test-parallel-memory.mjs b/scripts/test-parallel-memory.mjs new file mode 100644 index 00000000000..a4fa2602cd1 --- /dev/null +++ b/scripts/test-parallel-memory.mjs @@ -0,0 +1,103 @@ +import { spawnSync } from "node:child_process"; + +const ESCAPE = String.fromCodePoint(27); +const BELL = String.fromCodePoint(7); +const ANSI_ESCAPE_PATTERN = new RegExp( + // Strip CSI/OSC-style control sequences from Vitest output before parsing file lines. + `${ESCAPE}(?:\\][^${BELL}]*(?:${BELL}|${ESCAPE}\\\\)|\\[[0-?]*[ -/]*[@-~]|[@-Z\\\\-_])`, + "g", +); + +const COMPLETED_TEST_FILE_LINE_PATTERN = + /(?(?:src|extensions|test|ui)\/\S+?\.(?:live\.test|e2e\.test|test)\.ts)\s+\(.*\)\s+(?\d+(?:\.\d+)?)(?ms|s)\s*$/; + +const PS_COLUMNS = ["pid=", "ppid=", "rss="]; + +function parseDurationMs(rawValue, unit) { + const parsed = Number.parseFloat(rawValue); + if (!Number.isFinite(parsed)) { + return null; + } + return unit === "s" ? Math.round(parsed * 1000) : Math.round(parsed); +} + +function stripAnsi(text) { + return text.replaceAll(ANSI_ESCAPE_PATTERN, ""); +} + +export function parseCompletedTestFileLines(text) { + return stripAnsi(text) + .split(/\r?\n/u) + .map((line) => { + const match = line.match(COMPLETED_TEST_FILE_LINE_PATTERN); + if (!match?.groups) { + return null; + } + return { + file: match.groups.file, + durationMs: parseDurationMs(match.groups.duration, match.groups.unit), + }; + }) + .filter((entry) => entry !== null); +} + +export function sampleProcessTreeRssKb(rootPid) { + if (!Number.isInteger(rootPid) || rootPid <= 0 || process.platform === "win32") { + return null; + } + + const result = spawnSync("ps", ["-axo", PS_COLUMNS.join(",")], { + encoding: "utf8", + }); + if (result.status !== 0 || result.error) { + return null; + } + + const childPidsByParent = new Map(); + const rssByPid = new Map(); + for (const line of result.stdout.split(/\r?\n/u)) { + const trimmed = line.trim(); + if (!trimmed) { + continue; + } + const [pidRaw, parentRaw, rssRaw] = trimmed.split(/\s+/u); + const pid = Number.parseInt(pidRaw ?? "", 10); + const parentPid = Number.parseInt(parentRaw ?? "", 10); + const rssKb = Number.parseInt(rssRaw ?? "", 10); + if (!Number.isInteger(pid) || !Number.isInteger(parentPid) || !Number.isInteger(rssKb)) { + continue; + } + const siblings = childPidsByParent.get(parentPid) ?? []; + siblings.push(pid); + childPidsByParent.set(parentPid, siblings); + rssByPid.set(pid, rssKb); + } + + if (!rssByPid.has(rootPid)) { + return null; + } + + let rssKb = 0; + let processCount = 0; + const queue = [rootPid]; + const visited = new Set(); + while (queue.length > 0) { + const pid = queue.shift(); + if (pid === undefined || visited.has(pid)) { + continue; + } + visited.add(pid); + const currentRssKb = rssByPid.get(pid); + if (currentRssKb !== undefined) { + rssKb += currentRssKb; + processCount += 1; + } + for (const childPid of childPidsByParent.get(pid) ?? []) { + if (!visited.has(childPid)) { + queue.push(childPid); + } + } + } + + return { rssKb, processCount }; +} diff --git a/scripts/test-parallel.mjs b/scripts/test-parallel.mjs index 78fcf35f6d1..841132d69e0 100644 --- a/scripts/test-parallel.mjs +++ b/scripts/test-parallel.mjs @@ -4,6 +4,7 @@ import os from "node:os"; import path from "node:path"; import { channelTestPrefixes } from "../vitest.channel-paths.mjs"; import { isUnitConfigTestFile } from "../vitest.unit-paths.mjs"; +import { parseCompletedTestFileLines, sampleProcessTreeRssKb } from "./test-parallel-memory.mjs"; import { appendCapturedOutput, hasFatalTestRunOutput, @@ -184,6 +185,7 @@ const countExplicitEntryFilters = (entryArgs) => { const { fileFilters } = parsePassthroughArgs(entryArgs.slice(2)); return fileFilters.length > 0 ? fileFilters.length : null; }; +const getExplicitEntryFilters = (entryArgs) => parsePassthroughArgs(entryArgs.slice(2)).fileFilters; const passthroughRequiresSingleRun = passthroughOptionArgs.some((arg) => { if (!arg.startsWith("-")) { return false; @@ -707,6 +709,22 @@ const maxOldSpaceSizeMb = (() => { })(); const formatElapsedMs = (elapsedMs) => elapsedMs >= 1000 ? `${(elapsedMs / 1000).toFixed(1)}s` : `${Math.round(elapsedMs)}ms`; +const formatMemoryKb = (rssKb) => + rssKb >= 1024 ** 2 + ? `${(rssKb / 1024 ** 2).toFixed(2)}GiB` + : rssKb >= 1024 + ? `${(rssKb / 1024).toFixed(1)}MiB` + : `${rssKb}KiB`; +const formatMemoryDeltaKb = (rssKb) => + `${rssKb >= 0 ? "+" : "-"}${formatMemoryKb(Math.abs(rssKb))}`; +const rawMemoryTrace = process.env.OPENCLAW_TEST_MEMORY_TRACE?.trim().toLowerCase(); +const memoryTraceEnabled = + process.platform !== "win32" && + (rawMemoryTrace === "1" || + rawMemoryTrace === "true" || + (rawMemoryTrace !== "0" && rawMemoryTrace !== "false" && isCI)); +const memoryTracePollMs = Math.max(250, parseEnvNumber("OPENCLAW_TEST_MEMORY_TRACE_POLL_MS", 1000)); +const memoryTraceTopCount = Math.max(1, parseEnvNumber("OPENCLAW_TEST_MEMORY_TRACE_TOP_COUNT", 6)); const runOnce = (entry, extraArgs = []) => new Promise((resolve) => { @@ -718,6 +736,7 @@ const runOnce = (entry, extraArgs = []) => entry.name === "extensions" && maxWorkers === 1 && entry.args.includes("--pool=vmForks") ? entry.args.map((arg) => (arg === "--pool=vmForks" ? "--pool=forks" : arg)) : entry.args; + const explicitEntryFilters = getExplicitEntryFilters(entryArgs); const args = maxWorkers ? [ ...entryArgs, @@ -749,12 +768,115 @@ const runOnce = (entry, extraArgs = []) => let fatalSeen = false; let childError = null; let child; + let pendingLine = ""; + let memoryPollTimer = null; + const memoryFileRecords = []; + let initialTreeSample = null; + let latestTreeSample = null; + let peakTreeSample = null; + const updatePeakTreeSample = (sample, reason) => { + if (!sample) { + return; + } + if (!peakTreeSample || sample.rssKb > peakTreeSample.rssKb) { + peakTreeSample = { ...sample, reason }; + } + }; + const captureTreeSample = (reason) => { + if (!memoryTraceEnabled || !child?.pid) { + return null; + } + const sample = sampleProcessTreeRssKb(child.pid); + if (!sample) { + return null; + } + latestTreeSample = sample; + if (!initialTreeSample) { + initialTreeSample = sample; + } + updatePeakTreeSample(sample, reason); + return sample; + }; + const logMemoryTraceForText = (text) => { + if (!memoryTraceEnabled) { + return; + } + const combined = `${pendingLine}${text}`; + const lines = combined.split(/\r?\n/u); + pendingLine = lines.pop() ?? ""; + const completedFiles = parseCompletedTestFileLines(lines.join("\n")); + for (const completedFile of completedFiles) { + const sample = captureTreeSample(completedFile.file); + if (!sample) { + continue; + } + const previousRssKb = + memoryFileRecords.length > 0 + ? (memoryFileRecords.at(-1)?.rssKb ?? initialTreeSample?.rssKb ?? sample.rssKb) + : (initialTreeSample?.rssKb ?? sample.rssKb); + const deltaKb = sample.rssKb - previousRssKb; + const record = { + ...completedFile, + rssKb: sample.rssKb, + processCount: sample.processCount, + deltaKb, + }; + memoryFileRecords.push(record); + console.log( + `[test-parallel][mem] ${entry.name} file=${record.file} rss=${formatMemoryKb( + record.rssKb, + )} delta=${formatMemoryDeltaKb(record.deltaKb)} peak=${formatMemoryKb( + peakTreeSample?.rssKb ?? record.rssKb, + )} procs=${record.processCount}${record.durationMs ? ` duration=${formatElapsedMs(record.durationMs)}` : ""}`, + ); + } + }; + const logMemoryTraceSummary = () => { + if (!memoryTraceEnabled) { + return; + } + captureTreeSample("close"); + const fallbackRecord = + memoryFileRecords.length === 0 && + explicitEntryFilters.length === 1 && + latestTreeSample && + initialTreeSample + ? [ + { + file: explicitEntryFilters[0], + deltaKb: latestTreeSample.rssKb - initialTreeSample.rssKb, + }, + ] + : []; + const totalDeltaKb = + initialTreeSample && latestTreeSample + ? latestTreeSample.rssKb - initialTreeSample.rssKb + : 0; + const topGrowthFiles = [...memoryFileRecords, ...fallbackRecord] + .filter((record) => record.deltaKb > 0 && typeof record.file === "string") + .toSorted((left, right) => right.deltaKb - left.deltaKb) + .slice(0, memoryTraceTopCount) + .map((record) => `${record.file}:${formatMemoryDeltaKb(record.deltaKb)}`); + console.log( + `[test-parallel][mem] summary ${entry.name} files=${memoryFileRecords.length} peak=${formatMemoryKb( + peakTreeSample?.rssKb ?? 0, + )} totalDelta=${formatMemoryDeltaKb(totalDeltaKb)} peakAt=${ + peakTreeSample?.reason ?? "n/a" + } top=${topGrowthFiles.length > 0 ? topGrowthFiles.join(", ") : "none"}`, + ); + }; try { child = spawn(pnpm, args, { stdio: ["inherit", "pipe", "pipe"], env: { ...process.env, VITEST_GROUP: entry.name, NODE_OPTIONS: resolvedNodeOptions }, shell: isWindows, }); + captureTreeSample("spawn"); + if (memoryTraceEnabled) { + memoryPollTimer = setInterval(() => { + captureTreeSample("poll"); + }, memoryTracePollMs); + } } catch (err) { console.error(`[test-parallel] spawn failed: ${String(err)}`); resolve(1); @@ -765,12 +887,14 @@ const runOnce = (entry, extraArgs = []) => const text = chunk.toString(); fatalSeen ||= hasFatalTestRunOutput(`${output}${text}`); output = appendCapturedOutput(output, text); + logMemoryTraceForText(text); process.stdout.write(chunk); }); child.stderr?.on("data", (chunk) => { const text = chunk.toString(); fatalSeen ||= hasFatalTestRunOutput(`${output}${text}`); output = appendCapturedOutput(output, text); + logMemoryTraceForText(text); process.stderr.write(chunk); }); child.on("error", (err) => { @@ -778,8 +902,12 @@ const runOnce = (entry, extraArgs = []) => console.error(`[test-parallel] child error: ${String(err)}`); }); child.on("close", (code, signal) => { + if (memoryPollTimer) { + clearInterval(memoryPollTimer); + } children.delete(child); const resolvedCode = resolveTestRunExitCode({ code, signal, output, fatalSeen, childError }); + logMemoryTraceSummary(); console.log( `[test-parallel] done ${entry.name} code=${String(resolvedCode)} elapsed=${formatElapsedMs(Date.now() - startedAt)}`, ); diff --git a/test/scripts/test-parallel.test.ts b/test/scripts/test-parallel.test.ts index c2c217ad181..5d88f50e9e1 100644 --- a/test/scripts/test-parallel.test.ts +++ b/test/scripts/test-parallel.test.ts @@ -1,4 +1,5 @@ import { describe, expect, it } from "vitest"; +import { parseCompletedTestFileLines } from "../../scripts/test-parallel-memory.mjs"; import { appendCapturedOutput, hasFatalTestRunOutput, @@ -44,3 +45,35 @@ describe("scripts/test-parallel fatal output guard", () => { expect(appendCapturedOutput(output, "defg", 5)).toBe("cdefg"); }); }); + +describe("scripts/test-parallel memory trace parsing", () => { + it("extracts completed test file lines from colored Vitest output", () => { + const output = [ + "\u001B[32m✓\u001B[39m src/config/doc-baseline.test.ts \u001B[2m(\u001B[22m\u001B[2m8 tests\u001B[22m\u001B[2m)\u001B[22m\u001B[33m 46424\u001B[2mms\u001B[22m\u001B[39m", + " \u001B[32m✓\u001B[39m src/infra/restart.test.ts (5 tests) 4.2s", + ].join("\n"); + + expect(parseCompletedTestFileLines(output)).toEqual([ + { + file: "src/config/doc-baseline.test.ts", + durationMs: 46_424, + }, + { + file: "src/infra/restart.test.ts", + durationMs: 4_200, + }, + ]); + }); + + it("ignores non-file summary lines", () => { + expect( + parseCompletedTestFileLines( + [ + " Test Files 2 passed (2)", + " Tests 30 passed (30)", + "[test-parallel] done unit code=0 elapsed=68.8s", + ].join("\n"), + ), + ).toEqual([]); + }); +}); From ca757b6b77ad7090d88c9f9187862a96a6775b77 Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:01:49 -0500 Subject: [PATCH 13/69] test: add Feishu reply-once lifecycle regression --- .../src/monitor.reply-once.lifecycle.test.ts | 364 ++++++++++++++++++ 1 file changed, 364 insertions(+) create mode 100644 extensions/feishu/src/monitor.reply-once.lifecycle.test.ts diff --git a/extensions/feishu/src/monitor.reply-once.lifecycle.test.ts b/extensions/feishu/src/monitor.reply-once.lifecycle.test.ts new file mode 100644 index 00000000000..7aaf16e93f4 --- /dev/null +++ b/extensions/feishu/src/monitor.reply-once.lifecycle.test.ts @@ -0,0 +1,364 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { createPluginRuntimeMock } from "../../../test/helpers/extensions/plugin-runtime-mock.js"; +import type { ClawdbotConfig, PluginRuntime, RuntimeEnv } from "../runtime-api.js"; +import { monitorSingleAccount } from "./monitor.account.js"; +import { setFeishuRuntime } from "./runtime.js"; +import type { ResolvedFeishuAccount } from "./types.js"; + +const createEventDispatcherMock = vi.hoisted(() => vi.fn()); +const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); +const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); +const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); +const createFeishuReplyDispatcherMock = vi.hoisted(() => vi.fn()); +const resolveBoundConversationMock = vi.hoisted(() => vi.fn(() => null)); +const touchBindingMock = vi.hoisted(() => vi.fn()); +const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); +const dispatchReplyFromConfigMock = vi.hoisted(() => vi.fn()); +const withReplyDispatcherMock = vi.hoisted(() => vi.fn()); +const finalizeInboundContextMock = vi.hoisted(() => vi.fn((ctx) => ctx)); +const getMessageFeishuMock = vi.hoisted(() => vi.fn(async () => null)); +const listFeishuThreadMessagesMock = vi.hoisted(() => vi.fn(async () => [])); +const sendMessageFeishuMock = vi.hoisted(() => + vi.fn(async () => ({ messageId: "om_sent", chatId: "oc_group_1" })), +); + +let handlers: Record Promise> = {}; +let lastRuntime: RuntimeEnv | null = null; +const originalStateDir = process.env.OPENCLAW_STATE_DIR; + +vi.mock("./client.js", async () => { + const actual = await vi.importActual("./client.js"); + return { + ...actual, + createEventDispatcher: createEventDispatcherMock, + }; +}); + +vi.mock("./monitor.transport.js", () => ({ + monitorWebSocket: monitorWebSocketMock, + monitorWebhook: monitorWebhookMock, +})); + +vi.mock("./thread-bindings.js", () => ({ + createFeishuThreadBindingManager: createFeishuThreadBindingManagerMock, +})); + +vi.mock("./reply-dispatcher.js", () => ({ + createFeishuReplyDispatcher: createFeishuReplyDispatcherMock, +})); + +vi.mock("./send.js", () => ({ + getMessageFeishu: getMessageFeishuMock, + listFeishuThreadMessages: listFeishuThreadMessagesMock, + sendMessageFeishu: sendMessageFeishuMock, +})); + +vi.mock("openclaw/plugin-sdk/conversation-runtime", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + getSessionBindingService: () => ({ + resolveByConversation: resolveBoundConversationMock, + touch: touchBindingMock, + }), + }; +}); + +vi.mock("../../../src/infra/outbound/session-binding-service.js", () => ({ + getSessionBindingService: () => ({ + resolveByConversation: resolveBoundConversationMock, + touch: touchBindingMock, + }), +})); + +function createLifecycleConfig(): ClawdbotConfig { + return { + messages: { + inbound: { + debounceMs: 0, + byChannel: { + feishu: 0, + }, + }, + }, + channels: { + feishu: { + enabled: true, + accounts: { + "acct-lifecycle": { + enabled: true, + appId: "cli_test", + appSecret: "secret_test", // pragma: allowlist secret + connectionMode: "websocket", + groupPolicy: "open", + requireMention: false, + resolveSenderNames: false, + groups: { + oc_group_1: { + requireMention: false, + groupSessionScope: "group_topic_sender", + replyInThread: "enabled", + }, + }, + }, + }, + }, + }, + } as ClawdbotConfig; +} + +function createLifecycleAccount(): ResolvedFeishuAccount { + return { + accountId: "acct-lifecycle", + enabled: true, + configured: true, + appId: "cli_test", + appSecret: "secret_test", // pragma: allowlist secret + domain: "feishu", + config: { + enabled: true, + connectionMode: "websocket", + groupPolicy: "open", + requireMention: false, + resolveSenderNames: false, + groups: { + oc_group_1: { + requireMention: false, + groupSessionScope: "group_topic_sender", + replyInThread: "enabled", + }, + }, + }, + } as ResolvedFeishuAccount; +} + +function createRuntimeEnv(): RuntimeEnv { + return { + log: vi.fn(), + error: vi.fn(), + exit: vi.fn(), + } as RuntimeEnv; +} + +function createTextEvent(messageId: string) { + return { + sender: { + sender_id: { open_id: "ou_sender_1" }, + sender_type: "user", + }, + message: { + message_id: messageId, + root_id: "om_root_topic_1", + thread_id: "omt_topic_1", + chat_id: "oc_group_1", + chat_type: "group" as const, + message_type: "text", + content: JSON.stringify({ text: "hello from topic" }), + create_time: "1710000000000", + }, + }; +} + +async function settleAsyncWork(): Promise { + for (let i = 0; i < 6; i += 1) { + await Promise.resolve(); + await new Promise((resolve) => setTimeout(resolve, 0)); + } +} + +async function setupLifecycleMonitor() { + const register = vi.fn((registered: Record Promise>) => { + handlers = registered; + }); + createEventDispatcherMock.mockReturnValue({ register }); + + lastRuntime = createRuntimeEnv(); + + await monitorSingleAccount({ + cfg: createLifecycleConfig(), + account: createLifecycleAccount(), + runtime: lastRuntime, + botOpenIdSource: { + kind: "prefetched", + botOpenId: "ou_bot_1", + botName: "Bot", + }, + }); + + const onMessage = handlers["im.message.receive_v1"]; + if (!onMessage) { + throw new Error("missing im.message.receive_v1 handler"); + } + return onMessage; +} + +describe("Feishu reply-once lifecycle", () => { + beforeEach(() => { + vi.clearAllMocks(); + handlers = {}; + lastRuntime = null; + process.env.OPENCLAW_STATE_DIR = `/tmp/openclaw-feishu-lifecycle-${Date.now()}-${Math.random().toString(36).slice(2)}`; + + const dispatcher = { + sendToolResult: vi.fn(() => false), + sendBlockReply: vi.fn(() => false), + sendFinalReply: vi.fn(async () => true), + waitForIdle: vi.fn(async () => {}), + getQueuedCounts: vi.fn(() => ({ tool: 0, block: 0, final: 0 })), + markComplete: vi.fn(), + }; + + createFeishuReplyDispatcherMock.mockReturnValue({ + dispatcher, + replyOptions: {}, + markDispatchIdle: vi.fn(), + }); + + resolveBoundConversationMock.mockReturnValue({ + bindingId: "binding-1", + targetSessionKey: "agent:bound-agent:feishu:topic:om_root_topic_1:ou_sender_1", + }); + + resolveAgentRouteMock.mockReturnValue({ + agentId: "main", + channel: "feishu", + accountId: "acct-lifecycle", + sessionKey: "agent:main:feishu:group:oc_group_1", + mainSessionKey: "agent:main:main", + matchedBy: "default", + }); + + dispatchReplyFromConfigMock.mockImplementation(async ({ dispatcher }) => { + await dispatcher.sendFinalReply({ text: "reply once" }); + return { + queuedFinal: false, + counts: { final: 1 }, + }; + }); + + withReplyDispatcherMock.mockImplementation(async ({ run }) => await run()); + + setFeishuRuntime( + createPluginRuntimeMock({ + channel: { + debounce: { + resolveInboundDebounceMs: vi.fn(() => 0), + createInboundDebouncer: (params: { + onFlush?: (items: T[]) => Promise; + onError?: (err: unknown, items: T[]) => void; + }) => ({ + enqueue: async (item: T) => { + try { + await params.onFlush?.([item]); + } catch (err) { + params.onError?.(err, [item]); + } + }, + flushKey: async () => {}, + }), + }, + text: { + hasControlCommand: vi.fn(() => false), + }, + routing: { + resolveAgentRoute: + resolveAgentRouteMock as unknown as PluginRuntime["channel"]["routing"]["resolveAgentRoute"], + }, + reply: { + resolveEnvelopeFormatOptions: vi.fn(() => ({})), + formatAgentEnvelope: vi.fn((params: { body: string }) => params.body), + finalizeInboundContext: + finalizeInboundContextMock as unknown as PluginRuntime["channel"]["reply"]["finalizeInboundContext"], + dispatchReplyFromConfig: + dispatchReplyFromConfigMock as unknown as PluginRuntime["channel"]["reply"]["dispatchReplyFromConfig"], + withReplyDispatcher: + withReplyDispatcherMock as unknown as PluginRuntime["channel"]["reply"]["withReplyDispatcher"], + }, + commands: { + shouldComputeCommandAuthorized: vi.fn(() => false), + resolveCommandAuthorizedFromAuthorizers: vi.fn(() => false), + }, + session: { + readSessionUpdatedAt: vi.fn(), + resolveStorePath: vi.fn(() => "/tmp/feishu-lifecycle-sessions.json"), + }, + pairing: { + readAllowFromStore: vi.fn().mockResolvedValue([]), + upsertPairingRequest: vi.fn(), + buildPairingReply: vi.fn(), + }, + }, + media: { + detectMime: vi.fn(async () => "text/plain"), + }, + }) as unknown as PluginRuntime, + ); + }); + + afterEach(() => { + if (originalStateDir === undefined) { + delete process.env.OPENCLAW_STATE_DIR; + return; + } + process.env.OPENCLAW_STATE_DIR = originalStateDir; + }); + + it("routes a topic-bound inbound event and emits one reply across duplicate replay", async () => { + const onMessage = await setupLifecycleMonitor(); + const event = createTextEvent("om_lifecycle_once"); + + await onMessage(event); + await settleAsyncWork(); + await onMessage(event); + await settleAsyncWork(); + + expect(lastRuntime?.error).not.toHaveBeenCalled(); + expect(dispatchReplyFromConfigMock).toHaveBeenCalledTimes(1); + expect(createFeishuReplyDispatcherMock).toHaveBeenCalledTimes(1); + expect(createFeishuReplyDispatcherMock).toHaveBeenCalledWith( + expect.objectContaining({ + accountId: "acct-lifecycle", + chatId: "oc_group_1", + replyToMessageId: "om_root_topic_1", + replyInThread: true, + rootId: "om_root_topic_1", + }), + ); + expect(finalizeInboundContextMock).toHaveBeenCalledWith( + expect.objectContaining({ + AccountId: "acct-lifecycle", + SessionKey: "agent:bound-agent:feishu:topic:om_root_topic_1:ou_sender_1", + MessageSid: "om_lifecycle_once", + MessageThreadId: "om_root_topic_1", + }), + ); + expect(touchBindingMock).toHaveBeenCalledWith("binding-1"); + + const dispatcher = createFeishuReplyDispatcherMock.mock.results[0]?.value.dispatcher as { + sendFinalReply: ReturnType; + }; + expect(dispatcher.sendFinalReply).toHaveBeenCalledTimes(1); + }); + + it("does not duplicate delivery when the first attempt fails after sending the reply", async () => { + const onMessage = await setupLifecycleMonitor(); + const event = createTextEvent("om_lifecycle_retry"); + + dispatchReplyFromConfigMock.mockImplementationOnce(async ({ dispatcher }) => { + await dispatcher.sendFinalReply({ text: "reply once" }); + throw new Error("post-send failure"); + }); + + await onMessage(event); + await settleAsyncWork(); + await onMessage(event); + await settleAsyncWork(); + + expect(lastRuntime?.error).toHaveBeenCalledTimes(1); + expect(dispatchReplyFromConfigMock).toHaveBeenCalledTimes(1); + const dispatcher = createFeishuReplyDispatcherMock.mock.results[0]?.value.dispatcher as { + sendFinalReply: ReturnType; + }; + expect(dispatcher.sendFinalReply).toHaveBeenCalledTimes(1); + }); +}); From 1878272f67c24b37c5094b49e7cdb8a9c100144b Mon Sep 17 00:00:00 2001 From: Josh Avant <830519+joshavant@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:05:43 -0500 Subject: [PATCH 14/69] CLI: prune inactive gateway auth credentials on mode set (#50639) --- src/cli/config-cli.test.ts | 88 ++++++++++++++++++++++++++++++++++++++ src/cli/config-cli.ts | 54 +++++++++++++++++++++++ 2 files changed, 142 insertions(+) diff --git a/src/cli/config-cli.test.ts b/src/cli/config-cli.test.ts index ded6ad806da..d30a476004d 100644 --- a/src/cli/config-cli.test.ts +++ b/src/cli/config-cli.test.ts @@ -209,6 +209,94 @@ describe("config cli", () => { apiKey: "ollama-local", // pragma: allowlist secret }); }); + + it("drops gateway.auth.password when switching mode to token", async () => { + const resolved: OpenClawConfig = { + gateway: { + auth: { + mode: "password", + token: "token-keep", + password: "password-drop", // pragma: allowlist secret + allowTailscale: true, + }, + }, + }; + setSnapshot(resolved, resolved); + + await runConfigCommand(["config", "set", "gateway.auth.mode", "token"]); + + expect(mockWriteConfigFile).toHaveBeenCalledTimes(1); + const written = mockWriteConfigFile.mock.calls[0]?.[0]; + expect(written.gateway?.auth).toEqual({ + mode: "token", + token: "token-keep", + allowTailscale: true, + }); + expect(mockLog).toHaveBeenCalledWith( + expect.stringContaining( + "Removed inactive gateway.auth.password for gateway.auth.mode=token", + ), + ); + }); + + it("drops gateway.auth.token when switching mode to password", async () => { + const resolved: OpenClawConfig = { + gateway: { + auth: { + mode: "token", + token: "token-drop", + password: "password-keep", // pragma: allowlist secret + }, + }, + }; + setSnapshot(resolved, resolved); + + await runConfigCommand(["config", "set", "gateway.auth.mode", "password"]); + + expect(mockWriteConfigFile).toHaveBeenCalledTimes(1); + const written = mockWriteConfigFile.mock.calls[0]?.[0]; + expect(written.gateway?.auth).toEqual({ + mode: "password", + password: "password-keep", // pragma: allowlist secret + }); + expect(mockLog).toHaveBeenCalledWith( + expect.stringContaining( + "Removed inactive gateway.auth.token for gateway.auth.mode=password", + ), + ); + }); + + it("applies mode-based credential cleanup using the final batch result", async () => { + const resolved: OpenClawConfig = { + gateway: { + auth: { + mode: "password", + token: "token-keep", + password: "password-drop", // pragma: allowlist secret + }, + }, + }; + setSnapshot(resolved, resolved); + + await runConfigCommand([ + "config", + "set", + "--batch-json", + '[{"path":"gateway.auth.password","value":"password-updated"},{"path":"gateway.auth.mode","value":"token"}]', + ]); + + expect(mockWriteConfigFile).toHaveBeenCalledTimes(1); + const written = mockWriteConfigFile.mock.calls[0]?.[0]; + expect(written.gateway?.auth).toEqual({ + mode: "token", + token: "token-keep", + }); + expect(mockLog).toHaveBeenCalledWith( + expect.stringContaining( + "Removed inactive gateway.auth.password for gateway.auth.mode=token", + ), + ); + }); }); describe("config get", () => { diff --git a/src/cli/config-cli.ts b/src/cli/config-cli.ts index 8ec98f1804d..604e27666c9 100644 --- a/src/cli/config-cli.ts +++ b/src/cli/config-cli.ts @@ -69,6 +69,7 @@ type ConfigSetOperation = { const OLLAMA_API_KEY_PATH: PathSegment[] = ["models", "providers", "ollama", "apiKey"]; const OLLAMA_PROVIDER_PATH: PathSegment[] = ["models", "providers", "ollama"]; +const GATEWAY_AUTH_MODE_PATH: PathSegment[] = ["gateway", "auth", "mode"]; const SECRET_PROVIDER_PATH_PREFIX: PathSegment[] = ["secrets", "providers"]; const CONFIG_SET_EXAMPLE_VALUE = formatCliCommand( "openclaw config set gateway.port 19001 --strict-json", @@ -352,6 +353,48 @@ function ensureValidOllamaProviderForApiKeySet( }); } +function pruneInactiveGatewayAuthCredentials(params: { + root: Record; + operations: ConfigSetOperation[]; +}): string[] { + const touchedGatewayAuthMode = params.operations.some((operation) => + pathEquals(operation.requestedPath, GATEWAY_AUTH_MODE_PATH), + ); + if (!touchedGatewayAuthMode) { + return []; + } + + const gatewayRaw = params.root.gateway; + if (!gatewayRaw || typeof gatewayRaw !== "object" || Array.isArray(gatewayRaw)) { + return []; + } + const gateway = gatewayRaw as Record; + const authRaw = gateway.auth; + if (!authRaw || typeof authRaw !== "object" || Array.isArray(authRaw)) { + return []; + } + const auth = authRaw as Record; + const mode = typeof auth.mode === "string" ? auth.mode.trim() : ""; + + const removedPaths: string[] = []; + const remove = (key: "token" | "password") => { + if (Object.hasOwn(auth, key)) { + delete auth[key]; + removedPaths.push(`gateway.auth.${key}`); + } + }; + + if (mode === "token") { + remove("password"); + } else if (mode === "password") { + remove("token"); + } else if (mode === "trusted-proxy") { + remove("token"); + remove("password"); + } + return removedPaths; +} + function toDotPath(path: PathSegment[]): string { return path.join("."); } @@ -964,6 +1007,10 @@ export async function runConfigSet(opts: { ensureValidOllamaProviderForApiKeySet(next, operation.setPath); setAtPath(next, operation.setPath, operation.value); } + const removedGatewayAuthPaths = pruneInactiveGatewayAuthCredentials({ + root: next, + operations, + }); const nextConfig = next as OpenClawConfig; if (opts.cliOptions.dryRun) { @@ -1051,6 +1098,13 @@ export async function runConfigSet(opts: { } await writeConfigFile(next); + if (removedGatewayAuthPaths.length > 0) { + runtime.log( + info( + `Removed inactive ${removedGatewayAuthPaths.join(", ")} for gateway.auth.mode=${String(nextConfig.gateway?.auth?.mode ?? "")}.`, + ), + ); + } if (operations.length === 1) { runtime.log( info( From 7f52a8a3a5d635bf64d6ecf9316b0792e6ca52a8 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 14:15:42 -0700 Subject: [PATCH 15/69] fix(ci): isolate top unit-fast OOM offenders --- test/fixtures/test-parallel.behavior.json | 44 +++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/test/fixtures/test-parallel.behavior.json b/test/fixtures/test-parallel.behavior.json index 3f7f895a3fb..3f28709511f 100644 --- a/test/fixtures/test-parallel.behavior.json +++ b/test/fixtures/test-parallel.behavior.json @@ -27,6 +27,50 @@ "file": "src/config/doc-baseline.test.ts", "reason": "Builds the full bundled config schema graph and is safer outside the shared unit-fast heap." }, + { + "file": "src/secrets/runtime.test.ts", + "reason": "Secrets runtime coverage retained the largest unit-fast heap spike in CI and is safer outside the shared lane." + }, + { + "file": "src/memory/index.test.ts", + "reason": "Memory index coverage retained nearly 1 GiB in unit-fast on Linux CI and is safer in its own fork." + }, + { + "file": "src/plugins/http-registry.test.ts", + "reason": "Plugin HTTP registry coverage retained a broad plugin graph in unit-fast and is safer outside the shared lane." + }, + { + "file": "src/infra/channel-summary.test.ts", + "reason": "Channel summary coverage retained a large channel/plugin graph in unit-fast on Linux CI." + }, + { + "file": "src/config/redact-snapshot.test.ts", + "reason": "Snapshot redaction coverage produced a large retained heap jump in unit-fast on Linux CI." + }, + { + "file": "src/infra/outbound/message-action-runner.media.test.ts", + "reason": "Outbound media action coverage retained a large media/plugin graph in unit-fast." + }, + { + "file": "src/media-understanding/apply.echo-transcript.test.ts", + "reason": "Media understanding echo transcript coverage retained a large processing graph in unit-fast." + }, + { + "file": "src/plugin-sdk/index.test.ts", + "reason": "Plugin SDK index coverage retained a broad export graph in unit-fast and is safer outside the shared lane." + }, + { + "file": "src/config/sessions.cache.test.ts", + "reason": "Session cache coverage retained a large config/session graph in unit-fast on Linux CI." + }, + { + "file": "src/secrets/runtime.coverage.test.ts", + "reason": "Secrets runtime coverage tests retained substantial heap in unit-fast and are safer isolated." + }, + { + "file": "src/channels/plugins/contracts/registry.contract.test.ts", + "reason": "Plugin contract registry coverage retained a large cross-plugin graph in both failing unit-fast shards." + }, { "file": "src/memory/manager.get-concurrency.test.ts", "reason": "Memory manager cache concurrency coverage can spike shared unit-fast heap on Linux Node 24." From 0e825ece0540e154681f59ee19d7a37244c7bd31 Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:12:29 -0500 Subject: [PATCH 16/69] test: add Feishu bot-menu lifecycle regression --- extensions/feishu/src/monitor.account.ts | 29 +- .../src/monitor.bot-menu.lifecycle.test.ts | 356 ++++++++++++++++++ .../feishu/src/monitor.bot-menu.test.ts | 81 ++-- 3 files changed, 413 insertions(+), 53 deletions(-) create mode 100644 extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts diff --git a/extensions/feishu/src/monitor.account.ts b/extensions/feishu/src/monitor.account.ts index a15240075d6..ff3a0ba9dc9 100644 --- a/extensions/feishu/src/monitor.account.ts +++ b/extensions/feishu/src/monitor.account.ts @@ -544,6 +544,15 @@ function registerEventHandlers( }), }, }; + const syntheticMessageId = syntheticEvent.message.message_id; + if (await hasProcessedFeishuMessage(syntheticMessageId, accountId, log)) { + log(`feishu[${accountId}]: dropping duplicate bot-menu event for ${syntheticMessageId}`); + return; + } + if (!tryBeginFeishuMessageProcessing(syntheticMessageId, accountId)) { + log(`feishu[${accountId}]: dropping in-flight bot-menu event for ${syntheticMessageId}`); + return; + } const handleLegacyMenu = () => handleFeishuMessage({ cfg, @@ -553,6 +562,7 @@ function registerEventHandlers( runtime, chatHistories, accountId, + processingClaimHeld: true, }); const promise = maybeHandleFeishuQuickActionMenu({ @@ -561,12 +571,19 @@ function registerEventHandlers( operatorOpenId, runtime, accountId, - }).then((handledMenu) => { - if (handledMenu) { - return; - } - return handleLegacyMenu(); - }); + }) + .then(async (handledMenu) => { + if (handledMenu) { + await recordProcessedFeishuMessage(syntheticMessageId, accountId, log); + releaseFeishuMessageProcessing(syntheticMessageId, accountId); + return; + } + return await handleLegacyMenu(); + }) + .catch((err) => { + releaseFeishuMessageProcessing(syntheticMessageId, accountId); + throw err; + }); if (fireAndForget) { promise.catch((err) => { error(`feishu[${accountId}]: error handling bot menu event: ${String(err)}`); diff --git a/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts b/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts new file mode 100644 index 00000000000..187d685d919 --- /dev/null +++ b/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts @@ -0,0 +1,356 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { createPluginRuntimeMock } from "../../../test/helpers/extensions/plugin-runtime-mock.js"; +import type { ClawdbotConfig, PluginRuntime, RuntimeEnv } from "../runtime-api.js"; +import { monitorSingleAccount } from "./monitor.account.js"; +import { setFeishuRuntime } from "./runtime.js"; +import type { ResolvedFeishuAccount } from "./types.js"; + +const createEventDispatcherMock = vi.hoisted(() => vi.fn()); +const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); +const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); +const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); +const createFeishuReplyDispatcherMock = vi.hoisted(() => vi.fn()); +const resolveBoundConversationMock = vi.hoisted(() => vi.fn(() => null)); +const touchBindingMock = vi.hoisted(() => vi.fn()); +const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); +const dispatchReplyFromConfigMock = vi.hoisted(() => vi.fn()); +const withReplyDispatcherMock = vi.hoisted(() => vi.fn()); +const finalizeInboundContextMock = vi.hoisted(() => vi.fn((ctx) => ctx)); +const sendCardFeishuMock = vi.hoisted(() => + vi.fn(async () => ({ messageId: "om_card_sent", chatId: "p2p:ou_user1" })), +); +const getMessageFeishuMock = vi.hoisted(() => vi.fn(async () => null)); +const listFeishuThreadMessagesMock = vi.hoisted(() => vi.fn(async () => [])); +const sendMessageFeishuMock = vi.hoisted(() => + vi.fn(async () => ({ messageId: "om_sent", chatId: "p2p:ou_user1" })), +); + +let handlers: Record Promise> = {}; +let lastRuntime: RuntimeEnv | null = null; +const originalStateDir = process.env.OPENCLAW_STATE_DIR; + +vi.mock("./client.js", async () => { + const actual = await vi.importActual("./client.js"); + return { + ...actual, + createEventDispatcher: createEventDispatcherMock, + }; +}); + +vi.mock("./monitor.transport.js", () => ({ + monitorWebSocket: monitorWebSocketMock, + monitorWebhook: monitorWebhookMock, +})); + +vi.mock("./thread-bindings.js", () => ({ + createFeishuThreadBindingManager: createFeishuThreadBindingManagerMock, +})); + +vi.mock("./reply-dispatcher.js", () => ({ + createFeishuReplyDispatcher: createFeishuReplyDispatcherMock, +})); + +vi.mock("./send.js", () => ({ + sendCardFeishu: sendCardFeishuMock, + getMessageFeishu: getMessageFeishuMock, + listFeishuThreadMessages: listFeishuThreadMessagesMock, + sendMessageFeishu: sendMessageFeishuMock, +})); + +vi.mock("openclaw/plugin-sdk/conversation-runtime", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + getSessionBindingService: () => ({ + resolveByConversation: resolveBoundConversationMock, + touch: touchBindingMock, + }), + }; +}); + +vi.mock("../../../src/infra/outbound/session-binding-service.js", () => ({ + getSessionBindingService: () => ({ + resolveByConversation: resolveBoundConversationMock, + touch: touchBindingMock, + }), +})); + +function createLifecycleConfig(): ClawdbotConfig { + return { + channels: { + feishu: { + enabled: true, + dmPolicy: "open", + requireMention: false, + resolveSenderNames: false, + accounts: { + "acct-menu": { + enabled: true, + appId: "cli_test", + appSecret: "secret_test", // pragma: allowlist secret + connectionMode: "websocket", + dmPolicy: "open", + requireMention: false, + resolveSenderNames: false, + }, + }, + }, + }, + messages: { + inbound: { + debounceMs: 0, + byChannel: { + feishu: 0, + }, + }, + }, + } as ClawdbotConfig; +} + +function createLifecycleAccount(): ResolvedFeishuAccount { + return { + accountId: "acct-menu", + enabled: true, + configured: true, + appId: "cli_test", + appSecret: "secret_test", // pragma: allowlist secret + domain: "feishu", + config: { + enabled: true, + connectionMode: "websocket", + dmPolicy: "open", + requireMention: false, + resolveSenderNames: false, + }, + } as ResolvedFeishuAccount; +} + +function createRuntimeEnv(): RuntimeEnv { + return { + log: vi.fn(), + error: vi.fn(), + exit: vi.fn(), + } as RuntimeEnv; +} + +function createBotMenuEvent(params: { eventKey: string; timestamp: string }) { + return { + event_key: params.eventKey, + timestamp: params.timestamp, + operator: { + operator_id: { + open_id: "ou_user1", + user_id: "user_1", + union_id: "union_1", + }, + }, + }; +} + +async function settleAsyncWork(): Promise { + for (let i = 0; i < 6; i += 1) { + await Promise.resolve(); + await new Promise((resolve) => setTimeout(resolve, 0)); + } +} + +async function setupLifecycleMonitor() { + const register = vi.fn((registered: Record Promise>) => { + handlers = registered; + }); + createEventDispatcherMock.mockReturnValue({ register }); + + lastRuntime = createRuntimeEnv(); + + await monitorSingleAccount({ + cfg: createLifecycleConfig(), + account: createLifecycleAccount(), + runtime: lastRuntime, + botOpenIdSource: { + kind: "prefetched", + botOpenId: "ou_bot_1", + botName: "Bot", + }, + }); + + const onBotMenu = handlers["application.bot.menu_v6"]; + if (!onBotMenu) { + throw new Error("missing application.bot.menu_v6 handler"); + } + return onBotMenu; +} + +describe("Feishu bot-menu lifecycle", () => { + beforeEach(() => { + vi.clearAllMocks(); + handlers = {}; + lastRuntime = null; + process.env.OPENCLAW_STATE_DIR = `/tmp/openclaw-feishu-bot-menu-${Date.now()}-${Math.random().toString(36).slice(2)}`; + + const dispatcher = { + sendToolResult: vi.fn(() => false), + sendBlockReply: vi.fn(() => false), + sendFinalReply: vi.fn(async () => true), + waitForIdle: vi.fn(async () => {}), + getQueuedCounts: vi.fn(() => ({ tool: 0, block: 0, final: 0 })), + markComplete: vi.fn(), + }; + + createFeishuReplyDispatcherMock.mockReturnValue({ + dispatcher, + replyOptions: {}, + markDispatchIdle: vi.fn(), + }); + + resolveBoundConversationMock.mockReturnValue({ + bindingId: "binding-menu", + targetSessionKey: "agent:bound-agent:feishu:direct:ou_user1", + }); + + resolveAgentRouteMock.mockReturnValue({ + agentId: "main", + channel: "feishu", + accountId: "acct-menu", + sessionKey: "agent:main:feishu:direct:ou_user1", + mainSessionKey: "agent:main:main", + matchedBy: "default", + }); + + dispatchReplyFromConfigMock.mockImplementation(async ({ dispatcher }) => { + await dispatcher.sendFinalReply({ text: "menu reply once" }); + return { + queuedFinal: false, + counts: { final: 1 }, + }; + }); + + withReplyDispatcherMock.mockImplementation(async ({ run }) => await run()); + + setFeishuRuntime( + createPluginRuntimeMock({ + channel: { + debounce: { + resolveInboundDebounceMs: vi.fn(() => 0), + createInboundDebouncer: (params: { + onFlush?: (items: T[]) => Promise; + onError?: (err: unknown, items: T[]) => void; + }) => ({ + enqueue: async (item: T) => { + try { + await params.onFlush?.([item]); + } catch (err) { + params.onError?.(err, [item]); + } + }, + flushKey: async () => {}, + }), + }, + text: { + hasControlCommand: vi.fn(() => false), + }, + routing: { + resolveAgentRoute: + resolveAgentRouteMock as unknown as PluginRuntime["channel"]["routing"]["resolveAgentRoute"], + }, + reply: { + resolveEnvelopeFormatOptions: vi.fn(() => ({})), + formatAgentEnvelope: vi.fn((params: { body: string }) => params.body), + finalizeInboundContext: + finalizeInboundContextMock as unknown as PluginRuntime["channel"]["reply"]["finalizeInboundContext"], + dispatchReplyFromConfig: + dispatchReplyFromConfigMock as unknown as PluginRuntime["channel"]["reply"]["dispatchReplyFromConfig"], + withReplyDispatcher: + withReplyDispatcherMock as unknown as PluginRuntime["channel"]["reply"]["withReplyDispatcher"], + }, + commands: { + shouldComputeCommandAuthorized: vi.fn(() => false), + resolveCommandAuthorizedFromAuthorizers: vi.fn(() => false), + }, + session: { + readSessionUpdatedAt: vi.fn(), + resolveStorePath: vi.fn(() => "/tmp/feishu-bot-menu-sessions.json"), + }, + pairing: { + readAllowFromStore: vi.fn().mockResolvedValue([]), + upsertPairingRequest: vi.fn(), + buildPairingReply: vi.fn(), + }, + }, + media: { + detectMime: vi.fn(async () => "text/plain"), + }, + }) as unknown as PluginRuntime, + ); + }); + + afterEach(() => { + if (originalStateDir === undefined) { + delete process.env.OPENCLAW_STATE_DIR; + return; + } + process.env.OPENCLAW_STATE_DIR = originalStateDir; + }); + + it("opens one launcher card across duplicate quick-actions replay", async () => { + const onBotMenu = await setupLifecycleMonitor(); + const event = createBotMenuEvent({ + eventKey: "quick-actions", + timestamp: "1700000000000", + }); + + await onBotMenu(event); + await settleAsyncWork(); + await onBotMenu(event); + await settleAsyncWork(); + + expect(lastRuntime?.error).not.toHaveBeenCalled(); + expect(sendCardFeishuMock).toHaveBeenCalledTimes(1); + expect(sendCardFeishuMock).toHaveBeenCalledWith( + expect.objectContaining({ + accountId: "acct-menu", + to: "user:ou_user1", + }), + ); + expect(dispatchReplyFromConfigMock).not.toHaveBeenCalled(); + expect(createFeishuReplyDispatcherMock).not.toHaveBeenCalled(); + }); + + it("falls back once to the legacy routed reply path when launcher rendering fails", async () => { + const onBotMenu = await setupLifecycleMonitor(); + const event = createBotMenuEvent({ + eventKey: "quick-actions", + timestamp: "1700000000001", + }); + sendCardFeishuMock.mockRejectedValueOnce(new Error("boom")); + + await onBotMenu(event); + await settleAsyncWork(); + await onBotMenu(event); + await settleAsyncWork(); + + expect(lastRuntime?.error).not.toHaveBeenCalled(); + expect(sendCardFeishuMock).toHaveBeenCalledTimes(1); + expect(dispatchReplyFromConfigMock).toHaveBeenCalledTimes(1); + expect(createFeishuReplyDispatcherMock).toHaveBeenCalledTimes(1); + expect(createFeishuReplyDispatcherMock).toHaveBeenCalledWith( + expect.objectContaining({ + accountId: "acct-menu", + chatId: "p2p:ou_user1", + replyToMessageId: "bot-menu:quick-actions:1700000000001", + }), + ); + expect(finalizeInboundContextMock).toHaveBeenCalledWith( + expect.objectContaining({ + AccountId: "acct-menu", + SessionKey: "agent:bound-agent:feishu:direct:ou_user1", + MessageSid: "bot-menu:quick-actions:1700000000001", + }), + ); + expect(touchBindingMock).toHaveBeenCalledWith("binding-menu"); + + const dispatcher = createFeishuReplyDispatcherMock.mock.results[0]?.value.dispatcher as { + sendFinalReply: ReturnType; + }; + expect(dispatcher.sendFinalReply).toHaveBeenCalledTimes(1); + }); +}); diff --git a/extensions/feishu/src/monitor.bot-menu.test.ts b/extensions/feishu/src/monitor.bot-menu.test.ts index 5bcba5716d4..d3170757647 100644 --- a/extensions/feishu/src/monitor.bot-menu.test.ts +++ b/extensions/feishu/src/monitor.bot-menu.test.ts @@ -1,4 +1,4 @@ -import { beforeEach, describe, expect, it, vi } from "vitest"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { hasControlCommand } from "../../../src/auto-reply/command-detection.js"; import { createInboundDebouncer, @@ -18,6 +18,7 @@ const sendCardFeishuMock = vi.hoisted(() => vi.fn(async () => ({ messageId: "m1" const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); let handlers: Record Promise> = {}; +const originalStateDir = process.env.OPENCLAW_STATE_DIR; vi.mock("./client.js", () => ({ createEventDispatcher: createEventDispatcherMock, @@ -63,6 +64,20 @@ function buildAccount(): ResolvedFeishuAccount { } as ResolvedFeishuAccount; } +function createBotMenuEvent(params: { eventKey: string; timestamp: string }) { + return { + event_key: params.eventKey, + timestamp: params.timestamp, + operator: { + operator_id: { + open_id: "ou_user1", + user_id: "user_1", + union_id: "union_1", + }, + }, + }; +} + async function registerHandlers() { setFeishuRuntime( createPluginRuntimeMock({ @@ -108,22 +123,21 @@ describe("Feishu bot menu handler", () => { beforeEach(() => { handlers = {}; vi.clearAllMocks(); + process.env.OPENCLAW_STATE_DIR = `/tmp/openclaw-feishu-bot-menu-test-${Date.now()}-${Math.random().toString(36).slice(2)}`; + }); + + afterEach(() => { + if (originalStateDir === undefined) { + delete process.env.OPENCLAW_STATE_DIR; + return; + } + process.env.OPENCLAW_STATE_DIR = originalStateDir; }); it("opens the quick-action launcher card at the webhook/event layer", async () => { const onBotMenu = await registerHandlers(); - await onBotMenu({ - event_key: "quick-actions", - timestamp: "1700000000000", - operator: { - operator_id: { - open_id: "ou_user1", - user_id: "user_1", - union_id: "union_1", - }, - }, - }); + await onBotMenu(createBotMenuEvent({ eventKey: "quick-actions", timestamp: "1700000000000" })); expect(sendCardFeishuMock).toHaveBeenCalledWith( expect.objectContaining({ @@ -148,24 +162,17 @@ describe("Feishu bot menu handler", () => { }), ); - const pending = onBotMenu({ - event_key: "quick-actions", - timestamp: "1700000000000", - operator: { - operator_id: { - open_id: "ou_user1", - user_id: "user_1", - union_id: "union_1", - }, - }, - }); + const pending = onBotMenu( + createBotMenuEvent({ eventKey: "quick-actions", timestamp: "1700000000001" }), + ); let settled = false; pending.finally(() => { settled = true; }); - await Promise.resolve(); - expect(settled).toBe(true); + await vi.waitFor(() => { + expect(settled).toBe(true); + }); resolveSend?.(); await pending; @@ -174,17 +181,7 @@ describe("Feishu bot menu handler", () => { it("falls back to the legacy /menu synthetic message path for unrelated bot menu keys", async () => { const onBotMenu = await registerHandlers(); - await onBotMenu({ - event_key: "custom-key", - timestamp: "1700000000000", - operator: { - operator_id: { - open_id: "ou_user1", - user_id: "user_1", - union_id: "union_1", - }, - }, - }); + await onBotMenu(createBotMenuEvent({ eventKey: "custom-key", timestamp: "1700000000002" })); expect(handleFeishuMessageMock).toHaveBeenCalledWith( expect.objectContaining({ @@ -202,17 +199,7 @@ describe("Feishu bot menu handler", () => { const onBotMenu = await registerHandlers(); sendCardFeishuMock.mockRejectedValueOnce(new Error("boom")); - await onBotMenu({ - event_key: "quick-actions", - timestamp: "1700000000000", - operator: { - operator_id: { - open_id: "ou_user1", - user_id: "user_1", - union_id: "union_1", - }, - }, - }); + await onBotMenu(createBotMenuEvent({ eventKey: "quick-actions", timestamp: "1700000000003" })); await vi.waitFor(() => { expect(handleFeishuMessageMock).toHaveBeenCalledWith( From 8412498c2c1dbf44da5afc7641816ea3a3c5273e Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 14:17:53 -0700 Subject: [PATCH 17/69] docs: convert FAQ to Mintlify accordion format, fix TOC link, enrich help index --- docs/help/faq.md | 4139 ++++++++++++++++++++++---------------------- docs/help/index.md | 7 + 2 files changed, 2072 insertions(+), 2074 deletions(-) diff --git a/docs/help/faq.md b/docs/help/faq.md index 4d161578ed9..68debcd807c 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -10,196 +10,6 @@ title: "FAQ" Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, multi-agent, OAuth/API keys, model failover). For runtime diagnostics, see [Troubleshooting](/gateway/troubleshooting). For the full config reference, see [Configuration](/gateway/configuration). -## Table of contents - -- [Quick start and first-run setup] - - [I am stuck, fastest way to get unstuck](#i-am-stuck-fastest-way-to-get-unstuck) - - [Recommended way to install and set up OpenClaw](#recommended-way-to-install-and-set-up-openclaw) - - [How do I open the dashboard after onboarding?](#how-do-i-open-the-dashboard-after-onboarding) - - [How do I authenticate the dashboard (token) on localhost vs remote?](#how-do-i-authenticate-the-dashboard-token-on-localhost-vs-remote) - - [What runtime do I need?](#what-runtime-do-i-need) - - [Does it run on Raspberry Pi?](#does-it-run-on-raspberry-pi) - - [Any tips for Raspberry Pi installs?](#any-tips-for-raspberry-pi-installs) - - [It is stuck on "wake up my friend" / onboarding will not hatch. What now?](#it-is-stuck-on-wake-up-my-friend-onboarding-will-not-hatch-what-now) - - [Can I migrate my setup to a new machine (Mac mini) without redoing onboarding?](#can-i-migrate-my-setup-to-a-new-machine-mac-mini-without-redoing-onboarding) - - [Where do I see what is new in the latest version?](#where-do-i-see-what-is-new-in-the-latest-version) - - [Cannot access docs.openclaw.ai (SSL error)](#cannot-access-docsopenclawai-ssl-error) - - [Difference between stable and beta](#difference-between-stable-and-beta) - - [How do I install the beta version and what is the difference between beta and dev](#how-do-i-install-the-beta-version-and-what-is-the-difference-between-beta-and-dev) - - [How do I try the latest bits?](#how-do-i-try-the-latest-bits) - - [How long does install and onboarding usually take?](#how-long-does-install-and-onboarding-usually-take) - - [Installer stuck? How do I get more feedback?](#installer-stuck-how-do-i-get-more-feedback) - - [Windows install says git not found or openclaw not recognized](#windows-install-says-git-not-found-or-openclaw-not-recognized) - - [Windows exec output shows garbled Chinese text what should I do](#windows-exec-output-shows-garbled-chinese-text-what-should-i-do) - - [The docs did not answer my question - how do I get a better answer](#the-docs-did-not-answer-my-question---how-do-i-get-a-better-answer) - - [How do I install OpenClaw on Linux?](#how-do-i-install-openclaw-on-linux) - - [How do I install OpenClaw on a VPS?](#how-do-i-install-openclaw-on-a-vps) - - [Where are the cloud/VPS install guides?](#where-are-the-cloudvps-install-guides) - - [Can I ask OpenClaw to update itself?](#can-i-ask-openclaw-to-update-itself) - - [What does onboarding actually do?](#what-does-onboarding-actually-do) - - [Do I need a Claude or OpenAI subscription to run this?](#do-i-need-a-claude-or-openai-subscription-to-run-this) - - [Can I use Claude Max subscription without an API key](#can-i-use-claude-max-subscription-without-an-api-key) - - [How does Anthropic "setup-token" auth work?](#how-does-anthropic-setuptoken-auth-work) - - [Where do I find an Anthropic setup-token?](#where-do-i-find-an-anthropic-setuptoken) - - [Do you support Claude subscription auth (Claude Pro or Max)?](#do-you-support-claude-subscription-auth-claude-pro-or-max) - - [Why am I seeing `HTTP 429: rate_limit_error` from Anthropic?](#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) - - [Is AWS Bedrock supported?](#is-aws-bedrock-supported) - - [How does Codex auth work?](#how-does-codex-auth-work) - - [Do you support OpenAI subscription auth (Codex OAuth)?](#do-you-support-openai-subscription-auth-codex-oauth) - - [How do I set up Gemini CLI OAuth](#how-do-i-set-up-gemini-cli-oauth) - - [Is a local model OK for casual chats?](#is-a-local-model-ok-for-casual-chats) - - [How do I keep hosted model traffic in a specific region?](#how-do-i-keep-hosted-model-traffic-in-a-specific-region) - - [Do I have to buy a Mac Mini to install this?](#do-i-have-to-buy-a-mac-mini-to-install-this) - - [Do I need a Mac mini for iMessage support?](#do-i-need-a-mac-mini-for-imessage-support) - - [If I buy a Mac mini to run OpenClaw, can I connect it to my MacBook Pro?](#if-i-buy-a-mac-mini-to-run-openclaw-can-i-connect-it-to-my-macbook-pro) - - [Can I use Bun?](#can-i-use-bun) - - [Telegram: what goes in `allowFrom`?](#telegram-what-goes-in-allowfrom) - - [Can multiple people use one WhatsApp number with different OpenClaw instances?](#can-multiple-people-use-one-whatsapp-number-with-different-openclaw-instances) - - [Can I run a "fast chat" agent and an "Opus for coding" agent?](#can-i-run-a-fast-chat-agent-and-an-opus-for-coding-agent) - - [Does Homebrew work on Linux?](#does-homebrew-work-on-linux) - - [Difference between the hackable git install and npm install](#difference-between-the-hackable-git-install-and-npm-install) - - [Can I switch between npm and git installs later?](#can-i-switch-between-npm-and-git-installs-later) - - [Should I run the Gateway on my laptop or a VPS?](#should-i-run-the-gateway-on-my-laptop-or-a-vps) - - [How important is it to run OpenClaw on a dedicated machine?](#how-important-is-it-to-run-openclaw-on-a-dedicated-machine) - - [What are the minimum VPS requirements and recommended OS?](#what-are-the-minimum-vps-requirements-and-recommended-os) - - [Can I run OpenClaw in a VM and what are the requirements](#can-i-run-openclaw-in-a-vm-and-what-are-the-requirements) -- [What is OpenClaw?](#what-is-openclaw) - - [What is OpenClaw, in one paragraph?](#what-is-openclaw-in-one-paragraph) - - [Value proposition](#value-proposition) - - [I just set it up what should I do first](#i-just-set-it-up-what-should-i-do-first) - - [What are the top five everyday use cases for OpenClaw](#what-are-the-top-five-everyday-use-cases-for-openclaw) - - [Can OpenClaw help with lead gen outreach ads and blogs for a SaaS](#can-openclaw-help-with-lead-gen-outreach-ads-and-blogs-for-a-saas) - - [What are the advantages vs Claude Code for web development?](#what-are-the-advantages-vs-claude-code-for-web-development) -- [Skills and automation](#skills-and-automation) - - [How do I customize skills without keeping the repo dirty?](#how-do-i-customize-skills-without-keeping-the-repo-dirty) - - [Can I load skills from a custom folder?](#can-i-load-skills-from-a-custom-folder) - - [How can I use different models for different tasks?](#how-can-i-use-different-models-for-different-tasks) - - [The bot freezes while doing heavy work. How do I offload that?](#the-bot-freezes-while-doing-heavy-work-how-do-i-offload-that) - - [Cron or reminders do not fire. What should I check?](#cron-or-reminders-do-not-fire-what-should-i-check) - - [How do I install skills on Linux?](#how-do-i-install-skills-on-linux) - - [Can OpenClaw run tasks on a schedule or continuously in the background?](#can-openclaw-run-tasks-on-a-schedule-or-continuously-in-the-background) - - [Can I run Apple macOS-only skills from Linux?](#can-i-run-apple-macos-only-skills-from-linux) - - [Do you have a Notion or HeyGen integration?](#do-you-have-a-notion-or-heygen-integration) - - [How do I use my existing signed-in Chrome with OpenClaw?](#how-do-i-use-my-existing-signed-in-chrome-with-openclaw) -- [Sandboxing and memory](#sandboxing-and-memory) - - [Is there a dedicated sandboxing doc?](#is-there-a-dedicated-sandboxing-doc) - - [How do I bind a host folder into the sandbox?](#how-do-i-bind-a-host-folder-into-the-sandbox) - - [How does memory work?](#how-does-memory-work) - - [Memory keeps forgetting things. How do I make it stick?](#memory-keeps-forgetting-things-how-do-i-make-it-stick) - - [Does memory persist forever? What are the limits?](#does-memory-persist-forever-what-are-the-limits) - - [Does semantic memory search require an OpenAI API key?](#does-semantic-memory-search-require-an-openai-api-key) -- [Where things live on disk](#where-things-live-on-disk) - - [Is all data used with OpenClaw saved locally?](#is-all-data-used-with-openclaw-saved-locally) - - [Where does OpenClaw store its data?](#where-does-openclaw-store-its-data) - - [Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?](#where-should-agentsmd-soulmd-usermd-memorymd-live) - - [Recommended backup strategy](#recommended-backup-strategy) - - [How do I completely uninstall OpenClaw?](#how-do-i-completely-uninstall-openclaw) - - [Can agents work outside the workspace?](#can-agents-work-outside-the-workspace) - - [I'm in remote mode - where is the session store?](#im-in-remote-mode-where-is-the-session-store) -- [Config basics](#config-basics) - - [What format is the config? Where is it?](#what-format-is-the-config-where-is-it) - - [I set `gateway.bind: "lan"` (or `"tailnet"`) and now nothing listens / the UI says unauthorized](#i-set-gatewaybind-lan-or-tailnet-and-now-nothing-listens-the-ui-says-unauthorized) - - [Why do I need a token on localhost now?](#why-do-i-need-a-token-on-localhost-now) - - [Do I have to restart after changing config?](#do-i-have-to-restart-after-changing-config) - - [How do I disable funny CLI taglines?](#how-do-i-disable-funny-cli-taglines) - - [How do I enable web search (and web fetch)?](#how-do-i-enable-web-search-and-web-fetch) - - [config.apply wiped my config. How do I recover and avoid this?](#configapply-wiped-my-config-how-do-i-recover-and-avoid-this) - - [How do I run a central Gateway with specialized workers across devices?](#how-do-i-run-a-central-gateway-with-specialized-workers-across-devices) - - [Can the OpenClaw browser run headless?](#can-the-openclaw-browser-run-headless) - - [How do I use Brave for browser control?](#how-do-i-use-brave-for-browser-control) -- [Remote gateways and nodes](#remote-gateways-and-nodes) - - [How do commands propagate between Telegram, the gateway, and nodes?](#how-do-commands-propagate-between-telegram-the-gateway-and-nodes) - - [How can my agent access my computer if the Gateway is hosted remotely?](#how-can-my-agent-access-my-computer-if-the-gateway-is-hosted-remotely) - - [Tailscale is connected but I get no replies. What now?](#tailscale-is-connected-but-i-get-no-replies-what-now) - - [Can two OpenClaw instances talk to each other (local + VPS)?](#can-two-openclaw-instances-talk-to-each-other-local-vps) - - [Do I need separate VPSes for multiple agents](#do-i-need-separate-vpses-for-multiple-agents) - - [Is there a benefit to using a node on my personal laptop instead of SSH from a VPS?](#is-there-a-benefit-to-using-a-node-on-my-personal-laptop-instead-of-ssh-from-a-vps) - - [Do nodes run a gateway service?](#do-nodes-run-a-gateway-service) - - [Is there an API / RPC way to apply config?](#is-there-an-api-rpc-way-to-apply-config) - - [Minimal sane config for a first install](#minimal-sane-config-for-a-first-install) - - [How do I set up Tailscale on a VPS and connect from my Mac?](#how-do-i-set-up-tailscale-on-a-vps-and-connect-from-my-mac) - - [How do I connect a Mac node to a remote Gateway (Tailscale Serve)?](#how-do-i-connect-a-mac-node-to-a-remote-gateway-tailscale-serve) - - [Should I install on a second laptop or just add a node?](#should-i-install-on-a-second-laptop-or-just-add-a-node) -- [Env vars and .env loading](#env-vars-and-env-loading) - - [How does OpenClaw load environment variables?](#how-does-openclaw-load-environment-variables) - - ["I started the Gateway via the service and my env vars disappeared." What now?](#i-started-the-gateway-via-the-service-and-my-env-vars-disappeared-what-now) - - [I set `COPILOT_GITHUB_TOKEN`, but models status shows "Shell env: off." Why?](#i-set-copilotgithubtoken-but-models-status-shows-shell-env-off-why) -- [Sessions and multiple chats](#sessions-and-multiple-chats) - - [How do I start a fresh conversation?](#how-do-i-start-a-fresh-conversation) - - [Do sessions reset automatically if I never send `/new`?](#do-sessions-reset-automatically-if-i-never-send-new) - - [Is there a way to make a team of OpenClaw instances one CEO and many agents](#is-there-a-way-to-make-a-team-of-openclaw-instances-one-ceo-and-many-agents) - - [Why did context get truncated mid-task? How do I prevent it?](#why-did-context-get-truncated-midtask-how-do-i-prevent-it) - - [How do I completely reset OpenClaw but keep it installed?](#how-do-i-completely-reset-openclaw-but-keep-it-installed) - - [I'm getting "context too large" errors - how do I reset or compact?](#im-getting-context-too-large-errors-how-do-i-reset-or-compact) - - [Why am I seeing "LLM request rejected: messages.content.tool_use.input field required"?](#why-am-i-seeing-llm-request-rejected-messagescontenttool_useinput-field-required) - - [Why am I getting heartbeat messages every 30 minutes?](#why-am-i-getting-heartbeat-messages-every-30-minutes) - - [Do I need to add a "bot account" to a WhatsApp group?](#do-i-need-to-add-a-bot-account-to-a-whatsapp-group) - - [How do I get the JID of a WhatsApp group?](#how-do-i-get-the-jid-of-a-whatsapp-group) - - [Why does OpenClaw not reply in a group](#why-does-openclaw-not-reply-in-a-group) - - [Do groups/threads share context with DMs?](#do-groupsthreads-share-context-with-dms) - - [How many workspaces and agents can I create?](#how-many-workspaces-and-agents-can-i-create) - - [Can I run multiple bots or chats at the same time (Slack), and how should I set that up?](#can-i-run-multiple-bots-or-chats-at-the-same-time-slack-and-how-should-i-set-that-up) -- [Models: defaults, selection, aliases, switching](#models-defaults-selection-aliases-switching) - - [What is the "default model"?](#what-is-the-default-model) - - [What model do you recommend?](#what-model-do-you-recommend) - - [How do I switch models without wiping my config?](#how-do-i-switch-models-without-wiping-my-config) - - [Can I use self-hosted models (llama.cpp, vLLM, Ollama)?](#can-i-use-selfhosted-models-llamacpp-vllm-ollama) - - [What do OpenClaw, Flawd, and Krill use for models?](#what-do-openclaw-flawd-and-krill-use-for-models) - - [How do I switch models on the fly (without restarting)?](#how-do-i-switch-models-on-the-fly-without-restarting) - - [Can I use GPT 5.2 for daily tasks and Codex 5.3 for coding](#can-i-use-gpt-52-for-daily-tasks-and-codex-53-for-coding) - - [Why do I see "Model … is not allowed" and then no reply?](#why-do-i-see-model-is-not-allowed-and-then-no-reply) - - [Why do I see "Unknown model: minimax/MiniMax-M2.5"?](#why-do-i-see-unknown-model-minimaxminimaxm25) - - [Can I use MiniMax as my default and OpenAI for complex tasks?](#can-i-use-minimax-as-my-default-and-openai-for-complex-tasks) - - [Are opus / sonnet / gpt built-in shortcuts?](#are-opus-sonnet-gpt-builtin-shortcuts) - - [How do I define/override model shortcuts (aliases)?](#how-do-i-defineoverride-model-shortcuts-aliases) - - [How do I add models from other providers like OpenRouter or Z.AI?](#how-do-i-add-models-from-other-providers-like-openrouter-or-zai) -- [Model failover and "All models failed"](#model-failover-and-all-models-failed) - - [How does failover work?](#how-does-failover-work) - - [What does this error mean?](#what-does-this-error-mean) - - [Fix checklist for `No credentials found for profile "anthropic:default"`](#fix-checklist-for-no-credentials-found-for-profile-anthropicdefault) - - [Why did it also try Google Gemini and fail?](#why-did-it-also-try-google-gemini-and-fail) -- [Auth profiles: what they are and how to manage them](#auth-profiles-what-they-are-and-how-to-manage-them) - - [What is an auth profile?](#what-is-an-auth-profile) - - [What are typical profile IDs?](#what-are-typical-profile-ids) - - [Can I control which auth profile is tried first?](#can-i-control-which-auth-profile-is-tried-first) - - [OAuth vs API key - what is the difference](#oauth-vs-api-key---what-is-the-difference) -- [Gateway: ports, "already running", and remote mode](#gateway-ports-already-running-and-remote-mode) - - [What port does the Gateway use?](#what-port-does-the-gateway-use) - - [Why does `openclaw gateway status` say `Runtime: running` but `RPC probe: failed`?](#why-does-openclaw-gateway-status-say-runtime-running-but-rpc-probe-failed) - - [Why does `openclaw gateway status` show `Config (cli)` and `Config (service)` different?](#why-does-openclaw-gateway-status-show-config-cli-and-config-service-different) - - [What does "another gateway instance is already listening" mean?](#what-does-another-gateway-instance-is-already-listening-mean) - - [How do I run OpenClaw in remote mode (client connects to a Gateway elsewhere)?](#how-do-i-run-openclaw-in-remote-mode-client-connects-to-a-gateway-elsewhere) - - [The Control UI says "unauthorized" (or keeps reconnecting). What now?](#the-control-ui-says-unauthorized-or-keeps-reconnecting-what-now) - - [I set gateway.bind tailnet but it cannot bind and nothing listens](#i-set-gatewaybind-tailnet-but-it-cannot-bind-and-nothing-listens) - - [Can I run multiple Gateways on the same host?](#can-i-run-multiple-gateways-on-the-same-host) - - [What does "invalid handshake" / code 1008 mean?](#what-does-invalid-handshake-code-1008-mean) -- [Logging and debugging](#logging-and-debugging) - - [Where are logs?](#where-are-logs) - - [How do I start/stop/restart the Gateway service?](#how-do-i-startstoprestart-the-gateway-service) - - [I closed my terminal on Windows - how do I restart OpenClaw?](#i-closed-my-terminal-on-windows-how-do-i-restart-openclaw) - - [The Gateway is up but replies never arrive. What should I check?](#the-gateway-is-up-but-replies-never-arrive-what-should-i-check) - - ["Disconnected from gateway: no reason" - what now?](#disconnected-from-gateway-no-reason-what-now) - - [Telegram setMyCommands fails. What should I check?](#telegram-setmycommands-fails-what-should-i-check) - - [TUI shows no output. What should I check?](#tui-shows-no-output-what-should-i-check) - - [How do I completely stop then start the Gateway?](#how-do-i-completely-stop-then-start-the-gateway) - - [ELI5: `openclaw gateway restart` vs `openclaw gateway`](#eli5-openclaw-gateway-restart-vs-openclaw-gateway) - - [Fastest way to get more details when something fails](#fastest-way-to-get-more-details-when-something-fails) -- [Media and attachments](#media-and-attachments) - - [My skill generated an image/PDF, but nothing was sent](#my-skill-generated-an-imagepdf-but-nothing-was-sent) -- [Security and access control](#security-and-access-control) - - [Is it safe to expose OpenClaw to inbound DMs?](#is-it-safe-to-expose-openclaw-to-inbound-dms) - - [Is prompt injection only a concern for public bots?](#is-prompt-injection-only-a-concern-for-public-bots) - - [Should my bot have its own email GitHub account or phone number](#should-my-bot-have-its-own-email-github-account-or-phone-number) - - [Can I give it autonomy over my text messages and is that safe](#can-i-give-it-autonomy-over-my-text-messages-and-is-that-safe) - - [Can I use cheaper models for personal assistant tasks?](#can-i-use-cheaper-models-for-personal-assistant-tasks) - - [I ran /start in Telegram but did not get a pairing code](#i-ran-start-in-telegram-but-did-not-get-a-pairing-code) - - [WhatsApp: will it message my contacts? How does pairing work?](#whatsapp-will-it-message-my-contacts-how-does-pairing-work) -- [Chat commands, aborting tasks, and "it will not stop"](#chat-commands-aborting-tasks-and-it-will-not-stop) - - [How do I stop internal system messages from showing in chat](#how-do-i-stop-internal-system-messages-from-showing-in-chat) - - [How do I stop/cancel a running task?](#how-do-i-stopcancel-a-running-task) - - [How do I send a Discord message from Telegram? ("Cross-context messaging denied")](#how-do-i-send-a-discord-message-from-telegram-crosscontext-messaging-denied) - - [Why does it feel like the bot "ignores" rapid-fire messages?](#why-does-it-feel-like-the-bot-ignores-rapidfire-messages) - ## First 60 seconds if something is broken 1. **Quick status (first check)** @@ -267,2740 +77,2921 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ## Quick start and first-run setup -### I am stuck, fastest way to get unstuck + + + Use a local AI agent that can **see your machine**. That is far more effective than asking + in Discord, because most "I'm stuck" cases are **local config or environment issues** that + remote helpers cannot inspect. -Use a local AI agent that can **see your machine**. That is far more effective than asking -in Discord, because most "I'm stuck" cases are **local config or environment issues** that -remote helpers cannot inspect. + - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) + - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) -- **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) -- **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) + These tools can read the repo, run commands, inspect logs, and help fix your machine-level + setup (PATH, services, permissions, auth files). Give them the **full source checkout** via + the hackable (git) install: -These tools can read the repo, run commands, inspect logs, and help fix your machine-level -setup (PATH, services, permissions, auth files). Give them the **full source checkout** via -the hackable (git) install: + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git + ``` -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git -``` + This installs OpenClaw **from a git checkout**, so the agent can read the code + docs and + reason about the exact version you are running. You can always switch back to stable later + by re-running the installer without `--install-method git`. -This installs OpenClaw **from a git checkout**, so the agent can read the code + docs and -reason about the exact version you are running. You can always switch back to stable later -by re-running the installer without `--install-method git`. + Tip: ask the agent to **plan and supervise** the fix (step-by-step), then execute only the + necessary commands. That keeps changes small and easier to audit. -Tip: ask the agent to **plan and supervise** the fix (step-by-step), then execute only the -necessary commands. That keeps changes small and easier to audit. + If you discover a real bug or fix, please file a GitHub issue or send a PR: + [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) + [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) -If you discover a real bug or fix, please file a GitHub issue or send a PR: -[https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) -[https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) + Start with these commands (share outputs when asking for help): -Start with these commands (share outputs when asking for help): + ```bash + openclaw status + openclaw models status + openclaw doctor + ``` -```bash -openclaw status -openclaw models status -openclaw doctor -``` + What they do: -What they do: + - `openclaw status`: quick snapshot of gateway/agent health + basic config. + - `openclaw models status`: checks provider auth + model availability. + - `openclaw doctor`: validates and repairs common config/state issues. -- `openclaw status`: quick snapshot of gateway/agent health + basic config. -- `openclaw models status`: checks provider auth + model availability. -- `openclaw doctor`: validates and repairs common config/state issues. + Other useful CLI checks: `openclaw status --all`, `openclaw logs --follow`, + `openclaw gateway status`, `openclaw health --verbose`. -Other useful CLI checks: `openclaw status --all`, `openclaw logs --follow`, -`openclaw gateway status`, `openclaw health --verbose`. + Quick debug loop: [First 60 seconds if something is broken](#first-60-seconds-if-something-is-broken). + Install docs: [Install](/install), [Installer flags](/install/installer), [Updating](/install/updating). -Quick debug loop: [First 60 seconds if something is broken](#first-60-seconds-if-something-is-broken). -Install docs: [Install](/install), [Installer flags](/install/installer), [Updating](/install/updating). + -### Recommended way to install and set up OpenClaw + + The repo recommends running from source and using onboarding: -The repo recommends running from source and using onboarding: + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash + openclaw onboard --install-daemon + ``` -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -openclaw onboard --install-daemon -``` + The wizard can also build UI assets automatically. After onboarding, you typically run the Gateway on port **18789**. -The wizard can also build UI assets automatically. After onboarding, you typically run the Gateway on port **18789**. + From source (contributors/dev): -From source (contributors/dev): + ```bash + git clone https://github.com/openclaw/openclaw.git + cd openclaw + pnpm install + pnpm build + pnpm ui:build # auto-installs UI deps on first run + openclaw onboard + ``` -```bash -git clone https://github.com/openclaw/openclaw.git -cd openclaw -pnpm install -pnpm build -pnpm ui:build # auto-installs UI deps on first run -openclaw onboard -``` + If you don't have a global install yet, run it via `pnpm openclaw onboard`. -If you don't have a global install yet, run it via `pnpm openclaw onboard`. + -### How do I open the dashboard after onboarding + + The wizard opens your browser with a clean (non-tokenized) dashboard URL right after onboarding and also prints the link in the summary. Keep that tab open; if it didn't launch, copy/paste the printed URL on the same machine. + -The wizard opens your browser with a clean (non-tokenized) dashboard URL right after onboarding and also prints the link in the summary. Keep that tab open; if it didn't launch, copy/paste the printed URL on the same machine. + + **Localhost (same machine):** -### How do I authenticate the dashboard token on localhost vs remote + - Open `http://127.0.0.1:18789/`. + - If it asks for auth, paste the token from `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) into Control UI settings. + - Retrieve it from the gateway host: `openclaw config get gateway.auth.token` (or generate one: `openclaw doctor --generate-gateway-token`). -**Localhost (same machine):** + **Not on localhost:** -- Open `http://127.0.0.1:18789/`. -- If it asks for auth, paste the token from `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) into Control UI settings. -- Retrieve it from the gateway host: `openclaw config get gateway.auth.token` (or generate one: `openclaw doctor --generate-gateway-token`). + - **Tailscale Serve** (recommended): keep bind loopback, run `openclaw gateway --tailscale serve`, open `https:///`. If `gateway.auth.allowTailscale` is `true`, identity headers satisfy Control UI/WebSocket auth (no token, assumes trusted gateway host); HTTP APIs still require token/password. + - **Tailnet bind**: run `openclaw gateway --bind tailnet --token ""`, open `http://:18789/`, paste token in dashboard settings. + - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/` and paste the token in Control UI settings. -**Not on localhost:** + See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details. -- **Tailscale Serve** (recommended): keep bind loopback, run `openclaw gateway --tailscale serve`, open `https:///`. If `gateway.auth.allowTailscale` is `true`, identity headers satisfy Control UI/WebSocket auth (no token, assumes trusted gateway host); HTTP APIs still require token/password. -- **Tailnet bind**: run `openclaw gateway --bind tailnet --token ""`, open `http://:18789/`, paste token in dashboard settings. -- **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/` and paste the token in Control UI settings. + -See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details. + + Node **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** for the Gateway. + -### What runtime do I need + + Yes. The Gateway is lightweight - docs list **512MB-1GB RAM**, **1 core**, and about **500MB** + disk as enough for personal use, and note that a **Raspberry Pi 4 can run it**. -Node **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** for the Gateway. + If you want extra headroom (logs, media, other services), **2GB is recommended**, but it's + not a hard minimum. -### Does it run on Raspberry Pi + Tip: a small Pi/VPS can host the Gateway, and you can pair **nodes** on your laptop/phone for + local screen/camera/canvas or command execution. See [Nodes](/nodes). -Yes. The Gateway is lightweight - docs list **512MB-1GB RAM**, **1 core**, and about **500MB** -disk as enough for personal use, and note that a **Raspberry Pi 4 can run it**. + -If you want extra headroom (logs, media, other services), **2GB is recommended**, but it's -not a hard minimum. + + Short version: it works, but expect rough edges. -Tip: a small Pi/VPS can host the Gateway, and you can pair **nodes** on your laptop/phone for -local screen/camera/canvas or command execution. See [Nodes](/nodes). + - Use a **64-bit** OS and keep Node >= 22. + - Prefer the **hackable (git) install** so you can see logs and update fast. + - Start without channels/skills, then add them one by one. + - If you hit weird binary issues, it is usually an **ARM compatibility** problem. -### Any tips for Raspberry Pi installs + Docs: [Linux](/platforms/linux), [Install](/install). -Short version: it works, but expect rough edges. + -- Use a **64-bit** OS and keep Node >= 22. -- Prefer the **hackable (git) install** so you can see logs and update fast. -- Start without channels/skills, then add them one by one. -- If you hit weird binary issues, it is usually an **ARM compatibility** problem. + + That screen depends on the Gateway being reachable and authenticated. The TUI also sends + "Wake up, my friend!" automatically on first hatch. If you see that line with **no reply** + and tokens stay at 0, the agent never ran. -Docs: [Linux](/platforms/linux), [Install](/install). + 1. Restart the Gateway: -### It is stuck on wake up my friend onboarding will not hatch What now + ```bash + openclaw gateway restart + ``` -That screen depends on the Gateway being reachable and authenticated. The TUI also sends -"Wake up, my friend!" automatically on first hatch. If you see that line with **no reply** -and tokens stay at 0, the agent never ran. + 2. Check status + auth: -1. Restart the Gateway: + ```bash + openclaw status + openclaw models status + openclaw logs --follow + ``` -```bash -openclaw gateway restart -``` + 3. If it still hangs, run: -2. Check status + auth: + ```bash + openclaw doctor + ``` -```bash -openclaw status -openclaw models status -openclaw logs --follow -``` + If the Gateway is remote, ensure the tunnel/Tailscale connection is up and that the UI + is pointed at the right Gateway. See [Remote access](/gateway/remote). -3. If it still hangs, run: + -```bash -openclaw doctor -``` + + Yes. Copy the **state directory** and **workspace**, then run Doctor once. This + keeps your bot "exactly the same" (memory, session history, auth, and channel + state) as long as you copy **both** locations: -If the Gateway is remote, ensure the tunnel/Tailscale connection is up and that the UI -is pointed at the right Gateway. See [Remote access](/gateway/remote). + 1. Install OpenClaw on the new machine. + 2. Copy `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`) from the old machine. + 3. Copy your workspace (default: `~/.openclaw/workspace`). + 4. Run `openclaw doctor` and restart the Gateway service. -### Can I migrate my setup to a new machine Mac mini without redoing onboarding + That preserves config, auth profiles, WhatsApp creds, sessions, and memory. If you're in + remote mode, remember the gateway host owns the session store and workspace. -Yes. Copy the **state directory** and **workspace**, then run Doctor once. This -keeps your bot "exactly the same" (memory, session history, auth, and channel -state) as long as you copy **both** locations: + **Important:** if you only commit/push your workspace to GitHub, you're backing + up **memory + bootstrap files**, but **not** session history or auth. Those live + under `~/.openclaw/` (for example `~/.openclaw/agents//sessions/`). -1. Install OpenClaw on the new machine. -2. Copy `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`) from the old machine. -3. Copy your workspace (default: `~/.openclaw/workspace`). -4. Run `openclaw doctor` and restart the Gateway service. + Related: [Migrating](/install/migrating), [Where things live on disk](#where-things-live-on-disk), + [Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor), + [Remote mode](/gateway/remote). -That preserves config, auth profiles, WhatsApp creds, sessions, and memory. If you're in -remote mode, remember the gateway host owns the session store and workspace. + -**Important:** if you only commit/push your workspace to GitHub, you're backing -up **memory + bootstrap files**, but **not** session history or auth. Those live -under `~/.openclaw/` (for example `~/.openclaw/agents//sessions/`). + + Check the GitHub changelog: + [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) -Related: [Migrating](/install/migrating), [Where things live on disk](/help/faq#where-does-openclaw-store-its-data), -[Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor), -[Remote mode](/gateway/remote). + Newest entries are at the top. If the top section is marked **Unreleased**, the next dated + section is the latest shipped version. Entries are grouped by **Highlights**, **Changes**, and + **Fixes** (plus docs/other sections when needed). -### Where do I see what is new in the latest version + -Check the GitHub changelog: -[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) + + Some Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity + Advanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. More + detail: [Troubleshooting](/help/faq#docsopenclawai-shows-an-ssl-error-comcast-xfinity). + Please help us unblock it by reporting here: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). -Newest entries are at the top. If the top section is marked **Unreleased**, the next dated -section is the latest shipped version. Entries are grouped by **Highlights**, **Changes**, and -**Fixes** (plus docs/other sections when needed). + If you still can't reach the site, the docs are mirrored on GitHub: + [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) -### Cannot access docs.openclaw.ai (SSL error) + -Some Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity -Advanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. More -detail: [Troubleshooting](/help/faq#docsopenclawai-shows-an-ssl-error-comcast-xfinity). -Please help us unblock it by reporting here: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). + + **Stable** and **beta** are **npm dist-tags**, not separate code lines: -If you still can't reach the site, the docs are mirrored on GitHub: -[https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) + - `latest` = stable + - `beta` = early build for testing -### Difference between stable and beta + We ship builds to **beta**, test them, and once a build is solid we **promote + that same version to `latest`**. That's why beta and stable can point at the + **same version**. -**Stable** and **beta** are **npm dist-tags**, not separate code lines: + See what changed: + [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) -- `latest` = stable -- `beta` = early build for testing + -We ship builds to **beta**, test them, and once a build is solid we **promote -that same version to `latest`**. That's why beta and stable can point at the -**same version**. + + **Beta** is the npm dist-tag `beta` (may match `latest`). + **Dev** is the moving head of `main` (git); when published, it uses the npm dist-tag `dev`. -See what changed: -[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) + One-liners (macOS/Linux): -### How do I install the beta version and what is the difference between beta and dev + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta + ``` -**Beta** is the npm dist-tag `beta` (may match `latest`). -**Dev** is the moving head of `main` (git); when published, it uses the npm dist-tag `dev`. + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git + ``` -One-liners (macOS/Linux): + Windows installer (PowerShell): + [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) -```bash -curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta -``` + More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer). -```bash -curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git -``` + -Windows installer (PowerShell): -[https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) + + Two options: -More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer). + 1. **Dev channel (git checkout):** -### How long does install and onboarding usually take + ```bash + openclaw update --channel dev + ``` -Rough guide: + This switches to the `main` branch and updates from source. -- **Install:** 2-5 minutes -- **Onboarding:** 5-15 minutes depending on how many channels/models you configure + 2. **Hackable install (from the installer site):** -If it hangs, use [Installer stuck](/help/faq#installer-stuck-how-do-i-get-more-feedback) -and the fast debug loop in [I am stuck](/help/faq#i-am-stuck-fastest-way-to-get-unstuck). + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git + ``` -### How do I try the latest bits + That gives you a local repo you can edit, then update via git. -Two options: + If you prefer a clean clone manually, use: -1. **Dev channel (git checkout):** + ```bash + git clone https://github.com/openclaw/openclaw.git + cd openclaw + pnpm install + pnpm build + ``` -```bash -openclaw update --channel dev -``` + Docs: [Update](/cli/update), [Development channels](/install/development-channels), + [Install](/install). -This switches to the `main` branch and updates from source. + -2. **Hackable install (from the installer site):** + + Rough guide: -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git -``` + - **Install:** 2-5 minutes + - **Onboarding:** 5-15 minutes depending on how many channels/models you configure -That gives you a local repo you can edit, then update via git. + If it hangs, use [Installer stuck](#quick-start-and-first-run-setup) + and the fast debug loop in [I am stuck](#quick-start-and-first-run-setup). -If you prefer a clean clone manually, use: + -```bash -git clone https://github.com/openclaw/openclaw.git -cd openclaw -pnpm install -pnpm build -``` + + Re-run the installer with **verbose output**: -Docs: [Update](/cli/update), [Development channels](/install/development-channels), -[Install](/install). + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose + ``` -### Installer stuck How do I get more feedback + Beta install with verbose: -Re-run the installer with **verbose output**: + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose + ``` -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose -``` + For a hackable (git) install: -Beta install with verbose: + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose + ``` -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose -``` + Windows (PowerShell) equivalent: -For a hackable (git) install: + ```powershell + # install.ps1 has no dedicated -Verbose flag yet. + Set-PSDebug -Trace 1 + & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard + Set-PSDebug -Trace 0 + ``` -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose -``` + More options: [Installer flags](/install/installer). -Windows (PowerShell) equivalent: + -```powershell -# install.ps1 has no dedicated -Verbose flag yet. -Set-PSDebug -Trace 1 -& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard -Set-PSDebug -Trace 0 -``` + + Two common Windows issues: -More options: [Installer flags](/install/installer). + **1) npm error spawn git / git not found** -### Windows install says git not found or openclaw not recognized + - Install **Git for Windows** and make sure `git` is on your PATH. + - Close and reopen PowerShell, then re-run the installer. -Two common Windows issues: + **2) openclaw is not recognized after install** -**1) npm error spawn git / git not found** + - Your npm global bin folder is not on PATH. + - Check the path: -- Install **Git for Windows** and make sure `git` is on your PATH. -- Close and reopen PowerShell, then re-run the installer. + ```powershell + npm config get prefix + ``` -**2) openclaw is not recognized after install** + - Add that directory to your user PATH (no `\bin` suffix needed on Windows; on most systems it is `%AppData%\npm`). + - Close and reopen PowerShell after updating PATH. -- Your npm global bin folder is not on PATH. -- Check the path: + If you want the smoothest Windows setup, use **WSL2** instead of native Windows. + Docs: [Windows](/platforms/windows). - ```powershell - npm config get prefix - ``` + -- Add that directory to your user PATH (no `\bin` suffix needed on Windows; on most systems it is `%AppData%\npm`). -- Close and reopen PowerShell after updating PATH. + + This is usually a console code page mismatch on native Windows shells. -If you want the smoothest Windows setup, use **WSL2** instead of native Windows. -Docs: [Windows](/platforms/windows). + Symptoms: -### Windows exec output shows garbled Chinese text what should I do + - `system.run`/`exec` output renders Chinese as mojibake + - The same command looks fine in another terminal profile -This is usually a console code page mismatch on native Windows shells. + Quick workaround in PowerShell: -Symptoms: + ```powershell + chcp 65001 + [Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false) + [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) + $OutputEncoding = [System.Text.UTF8Encoding]::new($false) + ``` -- `system.run`/`exec` output renders Chinese as mojibake -- The same command looks fine in another terminal profile + Then restart the Gateway and retry your command: -Quick workaround in PowerShell: + ```powershell + openclaw gateway restart + ``` -```powershell -chcp 65001 -[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false) -[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) -$OutputEncoding = [System.Text.UTF8Encoding]::new($false) -``` + If you still reproduce this on latest OpenClaw, track/report it in: -Then restart the Gateway and retry your command: + - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) -```powershell -openclaw gateway restart -``` + -If you still reproduce this on latest OpenClaw, track/report it in: + + Use the **hackable (git) install** so you have the full source and docs locally, then ask + your bot (or Claude/Codex) _from that folder_ so it can read the repo and answer precisely. -- [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git + ``` -### The docs did not answer my question - how do I get a better answer + More detail: [Install](/install) and [Installer flags](/install/installer). -Use the **hackable (git) install** so you have the full source and docs locally, then ask -your bot (or Claude/Codex) _from that folder_ so it can read the repo and answer precisely. + -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git -``` + + Short answer: follow the Linux guide, then run onboarding. -More detail: [Install](/install) and [Installer flags](/install/installer). + - Linux quick path + service install: [Linux](/platforms/linux). + - Full walkthrough: [Getting Started](/start/getting-started). + - Installer + updates: [Install & updates](/install/updating). -### How do I install OpenClaw on Linux + -Short answer: follow the Linux guide, then run onboarding. + + Any Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway. -- Linux quick path + service install: [Linux](/platforms/linux). -- Full walkthrough: [Getting Started](/start/getting-started). -- Installer + updates: [Install & updates](/install/updating). + Guides: [exe.dev](/install/exe-dev), [Hetzner](/install/hetzner), [Fly.io](/install/fly). + Remote access: [Gateway remote](/gateway/remote). -### How do I install OpenClaw on a VPS + -Any Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway. + + We keep a **hosting hub** with the common providers. Pick one and follow the guide: -Guides: [exe.dev](/install/exe-dev), [Hetzner](/install/hetzner), [Fly.io](/install/fly). -Remote access: [Gateway remote](/gateway/remote). + - [VPS hosting](/vps) (all providers in one place) + - [Fly.io](/install/fly) + - [Hetzner](/install/hetzner) + - [exe.dev](/install/exe-dev) -### Where are the cloudVPS install guides + How it works in the cloud: the **Gateway runs on the server**, and you access it + from your laptop/phone via the Control UI (or Tailscale/SSH). Your state + workspace + live on the server, so treat the host as the source of truth and back it up. -We keep a **hosting hub** with the common providers. Pick one and follow the guide: + You can pair **nodes** (Mac/iOS/Android/headless) to that cloud Gateway to access + local screen/camera/canvas or run commands on your laptop while keeping the + Gateway in the cloud. -- [VPS hosting](/vps) (all providers in one place) -- [Fly.io](/install/fly) -- [Hetzner](/install/hetzner) -- [exe.dev](/install/exe-dev) + Hub: [Platforms](/platforms). Remote access: [Gateway remote](/gateway/remote). + Nodes: [Nodes](/nodes), [Nodes CLI](/cli/nodes). -How it works in the cloud: the **Gateway runs on the server**, and you access it -from your laptop/phone via the Control UI (or Tailscale/SSH). Your state + workspace -live on the server, so treat the host as the source of truth and back it up. + -You can pair **nodes** (Mac/iOS/Android/headless) to that cloud Gateway to access -local screen/camera/canvas or run commands on your laptop while keeping the -Gateway in the cloud. + + Short answer: **possible, not recommended**. The update flow can restart the + Gateway (which drops the active session), may need a clean git checkout, and + can prompt for confirmation. Safer: run updates from a shell as the operator. -Hub: [Platforms](/platforms). Remote access: [Gateway remote](/gateway/remote). -Nodes: [Nodes](/nodes), [Nodes CLI](/cli/nodes). + Use the CLI: -### Can I ask OpenClaw to update itself + ```bash + openclaw update + openclaw update status + openclaw update --channel stable|beta|dev + openclaw update --tag + openclaw update --no-restart + ``` -Short answer: **possible, not recommended**. The update flow can restart the -Gateway (which drops the active session), may need a clean git checkout, and -can prompt for confirmation. Safer: run updates from a shell as the operator. + If you must automate from an agent: -Use the CLI: + ```bash + openclaw update --yes --no-restart + openclaw gateway restart + ``` -```bash -openclaw update -openclaw update status -openclaw update --channel stable|beta|dev -openclaw update --tag -openclaw update --no-restart -``` + Docs: [Update](/cli/update), [Updating](/install/updating). -If you must automate from an agent: + -```bash -openclaw update --yes --no-restart -openclaw gateway restart -``` + + `openclaw onboard` is the recommended setup path. In **local mode** it walks you through: -Docs: [Update](/cli/update), [Updating](/install/updating). + - **Model/auth setup** (provider OAuth/setup-token flows and API keys supported, plus local model options such as LM Studio) + - **Workspace** location + bootstrap files + - **Gateway settings** (bind/port/auth/tailscale) + - **Providers** (WhatsApp, Telegram, Discord, Mattermost (plugin), Signal, iMessage) + - **Daemon install** (LaunchAgent on macOS; systemd user unit on Linux/WSL2) + - **Health checks** and **skills** selection -### What does onboarding actually do + It also warns if your configured model is unknown or missing auth. -`openclaw onboard` is the recommended setup path. In **local mode** it walks you through: + -- **Model/auth setup** (provider OAuth/setup-token flows and API keys supported, plus local model options such as LM Studio) -- **Workspace** location + bootstrap files -- **Gateway settings** (bind/port/auth/tailscale) -- **Providers** (WhatsApp, Telegram, Discord, Mattermost (plugin), Signal, iMessage) -- **Daemon install** (LaunchAgent on macOS; systemd user unit on Linux/WSL2) -- **Health checks** and **skills** selection + + No. You can run OpenClaw with **API keys** (Anthropic/OpenAI/others) or with + **local-only models** so your data stays on your device. Subscriptions (Claude + Pro/Max or OpenAI Codex) are optional ways to authenticate those providers. -It also warns if your configured model is unknown or missing auth. + If you choose Anthropic subscription auth, decide for yourself whether to use it: + Anthropic has blocked some subscription usage outside Claude Code in the past. + OpenAI Codex OAuth is explicitly supported for external tools like OpenClaw. -### Do I need a Claude or OpenAI subscription to run this + Docs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai), + [Local models](/gateway/local-models), [Models](/concepts/models). -No. You can run OpenClaw with **API keys** (Anthropic/OpenAI/others) or with -**local-only models** so your data stays on your device. Subscriptions (Claude -Pro/Max or OpenAI Codex) are optional ways to authenticate those providers. + -If you choose Anthropic subscription auth, decide for yourself whether to use it: -Anthropic has blocked some subscription usage outside Claude Code in the past. -OpenAI Codex OAuth is explicitly supported for external tools like OpenClaw. + + Yes. You can authenticate with a **setup-token** + instead of an API key. This is the subscription path. -Docs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai), -[Local models](/gateway/local-models), [Models](/concepts/models). + Claude Pro/Max subscriptions **do not include an API key**, so this is the + technical path for subscription accounts. But this is your decision: Anthropic + has blocked some subscription usage outside Claude Code in the past. + If you want the clearest and safest supported path for production, use an Anthropic API key. -### Can I use Claude Max subscription without an API key + -Yes. You can authenticate with a **setup-token** -instead of an API key. This is the subscription path. + + `claude setup-token` generates a **token string** via the Claude Code CLI (it is not available in the web console). You can run it on **any machine**. Choose **Anthropic token (paste setup-token)** in onboarding or paste it with `openclaw models auth paste-token --provider anthropic`. The token is stored as an auth profile for the **anthropic** provider and used like an API key (no auto-refresh). More detail: [OAuth](/concepts/oauth). + -Claude Pro/Max subscriptions **do not include an API key**, so this is the -technical path for subscription accounts. But this is your decision: Anthropic -has blocked some subscription usage outside Claude Code in the past. -If you want the clearest and safest supported path for production, use an Anthropic API key. + + It is **not** in the Anthropic Console. The setup-token is generated by the **Claude Code CLI** on **any machine**: -### How does Anthropic setuptoken auth work + ```bash + claude setup-token + ``` -`claude setup-token` generates a **token string** via the Claude Code CLI (it is not available in the web console). You can run it on **any machine**. Choose **Anthropic token (paste setup-token)** in onboarding or paste it with `openclaw models auth paste-token --provider anthropic`. The token is stored as an auth profile for the **anthropic** provider and used like an API key (no auto-refresh). More detail: [OAuth](/concepts/oauth). + Copy the token it prints, then choose **Anthropic token (paste setup-token)** in onboarding. If you want to run it on the gateway host, use `openclaw models auth setup-token --provider anthropic`. If you ran `claude setup-token` elsewhere, paste it on the gateway host with `openclaw models auth paste-token --provider anthropic`. See [Anthropic](/providers/anthropic). -### Where do I find an Anthropic setuptoken + -It is **not** in the Anthropic Console. The setup-token is generated by the **Claude Code CLI** on **any machine**: + + Yes - via **setup-token**. OpenClaw no longer reuses Claude Code CLI OAuth tokens; use a setup-token or an Anthropic API key. Generate the token anywhere and paste it on the gateway host. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth). -```bash -claude setup-token -``` + Important: this is technical compatibility, not a policy guarantee. Anthropic + has blocked some subscription usage outside Claude Code in the past. + You need to decide whether to use it and verify Anthropic's current terms. + For production or multi-user workloads, Anthropic API key auth is the safer, recommended choice. -Copy the token it prints, then choose **Anthropic token (paste setup-token)** in onboarding. If you want to run it on the gateway host, use `openclaw models auth setup-token --provider anthropic`. If you ran `claude setup-token` elsewhere, paste it on the gateway host with `openclaw models auth paste-token --provider anthropic`. See [Anthropic](/providers/anthropic). + -### Do you support Claude subscription auth (Claude Pro or Max) + + That means your **Anthropic quota/rate limit** is exhausted for the current window. If you + use a **Claude subscription** (setup-token), wait for the window to + reset or upgrade your plan. If you use an **Anthropic API key**, check the Anthropic Console + for usage/billing and raise limits as needed. -Yes - via **setup-token**. OpenClaw no longer reuses Claude Code CLI OAuth tokens; use a setup-token or an Anthropic API key. Generate the token anywhere and paste it on the gateway host. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth). + If the message is specifically: + `Extra usage is required for long context requests`, the request is trying to use + Anthropic's 1M context beta (`context1m: true`). That only works when your + credential is eligible for long-context billing (API key billing or subscription + with Extra Usage enabled). -Important: this is technical compatibility, not a policy guarantee. Anthropic -has blocked some subscription usage outside Claude Code in the past. -You need to decide whether to use it and verify Anthropic's current terms. -For production or multi-user workloads, Anthropic API key auth is the safer, recommended choice. + Tip: set a **fallback model** so OpenClaw can keep replying while a provider is rate-limited. + See [Models](/cli/models), [OAuth](/concepts/oauth), and + [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). -### Why am I seeing HTTP 429 ratelimiterror from Anthropic + -That means your **Anthropic quota/rate limit** is exhausted for the current window. If you -use a **Claude subscription** (setup-token), wait for the window to -reset or upgrade your plan. If you use an **Anthropic API key**, check the Anthropic Console -for usage/billing and raise limits as needed. + + Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/providers/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI-compatible proxy in front of Bedrock is still a valid option. + -If the message is specifically: -`Extra usage is required for long context requests`, the request is trying to use -Anthropic's 1M context beta (`context1m: true`). That only works when your -credential is eligible for long-context billing (API key billing or subscription -with Extra Usage enabled). + + OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). Onboarding can run the OAuth flow and will set the default model to `openai-codex/gpt-5.4` when appropriate. See [Model providers](/concepts/model-providers) and [Onboarding (CLI)](/start/wizard). + -Tip: set a **fallback model** so OpenClaw can keep replying while a provider is rate-limited. -See [Models](/cli/models), [OAuth](/concepts/oauth), and -[/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). + + Yes. OpenClaw fully supports **OpenAI Code (Codex) subscription OAuth**. + OpenAI explicitly allows subscription OAuth usage in external tools/workflows + like OpenClaw. Onboarding can run the OAuth flow for you. -### Is AWS Bedrock supported + See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Onboarding (CLI)](/start/wizard). -Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/providers/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI-compatible proxy in front of Bedrock is still a valid option. + -### How does Codex auth work + + Gemini CLI uses a **plugin auth flow**, not a client id or secret in `openclaw.json`. -OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). Onboarding can run the OAuth flow and will set the default model to `openai-codex/gpt-5.4` when appropriate. See [Model providers](/concepts/model-providers) and [Onboarding (CLI)](/start/wizard). + Steps: -### Do you support OpenAI subscription auth Codex OAuth + 1. Enable the plugin: `openclaw plugins enable google` + 2. Login: `openclaw models auth login --provider google-gemini-cli --set-default` -Yes. OpenClaw fully supports **OpenAI Code (Codex) subscription OAuth**. -OpenAI explicitly allows subscription OAuth usage in external tools/workflows -like OpenClaw. Onboarding can run the OAuth flow for you. + This stores OAuth tokens in auth profiles on the gateway host. Details: [Model providers](/concepts/model-providers). -See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Onboarding (CLI)](/start/wizard). + -### How do I set up Gemini CLI OAuth + + Usually no. OpenClaw needs large context + strong safety; small cards truncate and leak. If you must, run the **largest** MiniMax M2.5 build you can locally (LM Studio) and see [/gateway/local-models](/gateway/local-models). Smaller/quantized models increase prompt-injection risk - see [Security](/gateway/security). + -Gemini CLI uses a **plugin auth flow**, not a client id or secret in `openclaw.json`. + + Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax, Kimi, and GLM; choose the US-hosted variant to keep data in-region. You can still list Anthropic/OpenAI alongside these by using `models.mode: "merge"` so fallbacks stay available while respecting the regioned provider you select. + -Steps: + + No. OpenClaw runs on macOS or Linux (Windows via WSL2). A Mac mini is optional - some people + buy one as an always-on host, but a small VPS, home server, or Raspberry Pi-class box works too. -1. Enable the plugin: `openclaw plugins enable google` -2. Login: `openclaw models auth login --provider google-gemini-cli --set-default` + You only need a Mac **for macOS-only tools**. For iMessage, use [BlueBubbles](/channels/bluebubbles) (recommended) - the BlueBubbles server runs on any Mac, and the Gateway can run on Linux or elsewhere. If you want other macOS-only tools, run the Gateway on a Mac or pair a macOS node. -This stores OAuth tokens in auth profiles on the gateway host. Details: [Model providers](/concepts/model-providers). + Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote). -### Is a local model OK for casual chats + -Usually no. OpenClaw needs large context + strong safety; small cards truncate and leak. If you must, run the **largest** MiniMax M2.5 build you can locally (LM Studio) and see [/gateway/local-models](/gateway/local-models). Smaller/quantized models increase prompt-injection risk - see [Security](/gateway/security). + + You need **some macOS device** signed into Messages. It does **not** have to be a Mac mini - + any Mac works. **Use [BlueBubbles](/channels/bluebubbles)** (recommended) for iMessage - the BlueBubbles server runs on macOS, while the Gateway can run on Linux or elsewhere. -### How do I keep hosted model traffic in a specific region + Common setups: -Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax, Kimi, and GLM; choose the US-hosted variant to keep data in-region. You can still list Anthropic/OpenAI alongside these by using `models.mode: "merge"` so fallbacks stay available while respecting the regioned provider you select. + - Run the Gateway on Linux/VPS, and run the BlueBubbles server on any Mac signed into Messages. + - Run everything on the Mac if you want the simplest single-machine setup. -### Do I have to buy a Mac Mini to install this + Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes), + [Mac remote mode](/platforms/mac/remote). -No. OpenClaw runs on macOS or Linux (Windows via WSL2). A Mac mini is optional - some people -buy one as an always-on host, but a small VPS, home server, or Raspberry Pi-class box works too. + -You only need a Mac **for macOS-only tools**. For iMessage, use [BlueBubbles](/channels/bluebubbles) (recommended) - the BlueBubbles server runs on any Mac, and the Gateway can run on Linux or elsewhere. If you want other macOS-only tools, run the Gateway on a Mac or pair a macOS node. + + Yes. The **Mac mini can run the Gateway**, and your MacBook Pro can connect as a + **node** (companion device). Nodes don't run the Gateway - they provide extra + capabilities like screen/camera/canvas and `system.run` on that device. -Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote). + Common pattern: -### Do I need a Mac mini for iMessage support + - Gateway on the Mac mini (always-on). + - MacBook Pro runs the macOS app or a node host and pairs to the Gateway. + - Use `openclaw nodes status` / `openclaw nodes list` to see it. -You need **some macOS device** signed into Messages. It does **not** have to be a Mac mini - -any Mac works. **Use [BlueBubbles](/channels/bluebubbles)** (recommended) for iMessage - the BlueBubbles server runs on macOS, while the Gateway can run on Linux or elsewhere. + Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes). -Common setups: + -- Run the Gateway on Linux/VPS, and run the BlueBubbles server on any Mac signed into Messages. -- Run everything on the Mac if you want the simplest single‑machine setup. + + Bun is **not recommended**. We see runtime bugs, especially with WhatsApp and Telegram. + Use **Node** for stable gateways. -Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes), -[Mac remote mode](/platforms/mac/remote). + If you still want to experiment with Bun, do it on a non-production gateway + without WhatsApp/Telegram. -### If I buy a Mac mini to run OpenClaw can I connect it to my MacBook Pro + -Yes. The **Mac mini can run the Gateway**, and your MacBook Pro can connect as a -**node** (companion device). Nodes don't run the Gateway - they provide extra -capabilities like screen/camera/canvas and `system.run` on that device. + + `channels.telegram.allowFrom` is **the human sender's Telegram user ID** (numeric). It is not the bot username. -Common pattern: + Onboarding accepts `@username` input and resolves it to a numeric ID, but OpenClaw authorization uses numeric IDs only. -- Gateway on the Mac mini (always-on). -- MacBook Pro runs the macOS app or a node host and pairs to the Gateway. -- Use `openclaw nodes status` / `openclaw nodes list` to see it. + Safer (no third-party bot): -Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes). + - DM your bot, then run `openclaw logs --follow` and read `from.id`. -### Can I use Bun + Official Bot API: -Bun is **not recommended**. We see runtime bugs, especially with WhatsApp and Telegram. -Use **Node** for stable gateways. + - DM your bot, then call `https://api.telegram.org/bot/getUpdates` and read `message.from.id`. -If you still want to experiment with Bun, do it on a non-production gateway -without WhatsApp/Telegram. + Third-party (less private): -### Telegram what goes in allowFrom + - DM `@userinfobot` or `@getidsbot`. -`channels.telegram.allowFrom` is **the human sender's Telegram user ID** (numeric). It is not the bot username. + See [/channels/telegram](/channels/telegram#access-control-and-activation). -Onboarding accepts `@username` input and resolves it to a numeric ID, but OpenClaw authorization uses numeric IDs only. + -Safer (no third-party bot): + + Yes, via **multi-agent routing**. Bind each sender's WhatsApp **DM** (peer `kind: "direct"`, sender E.164 like `+15551234567`) to a different `agentId`, so each person gets their own workspace and session store. Replies still come from the **same WhatsApp account**, and DM access control (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent) and [WhatsApp](/channels/whatsapp). + -- DM your bot, then run `openclaw logs --follow` and read `from.id`. + + Yes. Use multi-agent routing: give each agent its own default model, then bind inbound routes (provider account or specific peers) to each agent. Example config lives in [Multi-Agent Routing](/concepts/multi-agent). See also [Models](/concepts/models) and [Configuration](/gateway/configuration). + -Official Bot API: + + Yes. Homebrew supports Linux (Linuxbrew). Quick setup: -- DM your bot, then call `https://api.telegram.org/bot/getUpdates` and read `message.from.id`. + ```bash + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile + eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" + brew install + ``` -Third-party (less private): + If you run OpenClaw via systemd, ensure the service PATH includes `/home/linuxbrew/.linuxbrew/bin` (or your brew prefix) so `brew`-installed tools resolve in non-login shells. + Recent builds also prepend common user bin dirs on Linux systemd services (for example `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) and honor `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR`, and `FNM_DIR` when set. -- DM `@userinfobot` or `@getidsbot`. + -See [/channels/telegram](/channels/telegram#access-control-and-activation). + + - **Hackable (git) install:** full source checkout, editable, best for contributors. + You run builds locally and can patch code/docs. + - **npm install:** global CLI install, no repo, best for "just run it." + Updates come from npm dist-tags. -### Can multiple people use one WhatsApp number with different OpenClaw instances + Docs: [Getting started](/start/getting-started), [Updating](/install/updating). -Yes, via **multi-agent routing**. Bind each sender's WhatsApp **DM** (peer `kind: "direct"`, sender E.164 like `+15551234567`) to a different `agentId`, so each person gets their own workspace and session store. Replies still come from the **same WhatsApp account**, and DM access control (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent) and [WhatsApp](/channels/whatsapp). + -### Can I run a fast chat agent and an Opus for coding agent + + Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint. + This **does not delete your data** - it only changes the OpenClaw code install. Your state + (`~/.openclaw`) and workspace (`~/.openclaw/workspace`) stay untouched. -Yes. Use multi-agent routing: give each agent its own default model, then bind inbound routes (provider account or specific peers) to each agent. Example config lives in [Multi-Agent Routing](/concepts/multi-agent). See also [Models](/concepts/models) and [Configuration](/gateway/configuration). + From npm to git: -### Does Homebrew work on Linux + ```bash + git clone https://github.com/openclaw/openclaw.git + cd openclaw + pnpm install + pnpm build + openclaw doctor + openclaw gateway restart + ``` -Yes. Homebrew supports Linux (Linuxbrew). Quick setup: + From git to npm: -```bash -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile -eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" -brew install -``` + ```bash + npm install -g openclaw@latest + openclaw doctor + openclaw gateway restart + ``` -If you run OpenClaw via systemd, ensure the service PATH includes `/home/linuxbrew/.linuxbrew/bin` (or your brew prefix) so `brew`-installed tools resolve in non-login shells. -Recent builds also prepend common user bin dirs on Linux systemd services (for example `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) and honor `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR`, and `FNM_DIR` when set. + Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation). -### Difference between the hackable git install and npm install + Backup tips: see [Backup strategy](#where-things-live-on-disk). -- **Hackable (git) install:** full source checkout, editable, best for contributors. - You run builds locally and can patch code/docs. -- **npm install:** global CLI install, no repo, best for "just run it." - Updates come from npm dist-tags. + -Docs: [Getting started](/start/getting-started), [Updating](/install/updating). + + Short answer: **if you want 24/7 reliability, use a VPS**. If you want the + lowest friction and you're okay with sleep/restarts, run it locally. -### Can I switch between npm and git installs later + **Laptop (local Gateway)** -Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint. -This **does not delete your data** - it only changes the OpenClaw code install. Your state -(`~/.openclaw`) and workspace (`~/.openclaw/workspace`) stay untouched. + - **Pros:** no server cost, direct access to local files, live browser window. + - **Cons:** sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake. -From npm → git: + **VPS / cloud** -```bash -git clone https://github.com/openclaw/openclaw.git -cd openclaw -pnpm install -pnpm build -openclaw doctor -openclaw gateway restart -``` + - **Pros:** always-on, stable network, no laptop sleep issues, easier to keep running. + - **Cons:** often run headless (use screenshots), remote file access only, you must SSH for updates. -From git → npm: + **OpenClaw-specific note:** WhatsApp/Telegram/Slack/Mattermost (plugin)/Discord all work fine from a VPS. The only real trade-off is **headless browser** vs a visible window. See [Browser](/tools/browser). -```bash -npm install -g openclaw@latest -openclaw doctor -openclaw gateway restart -``` + **Recommended default:** VPS if you had gateway disconnects before. Local is great when you're actively using the Mac and want local file access or UI automation with a visible browser. -Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation). + -Backup tips: see [Backup strategy](/help/faq#recommended-backup-strategy). + + Not required, but **recommended for reliability and isolation**. -### Should I run the Gateway on my laptop or a VPS + - **Dedicated host (VPS/Mac mini/Pi):** always-on, fewer sleep/reboot interruptions, cleaner permissions, easier to keep running. + - **Shared laptop/desktop:** totally fine for testing and active use, but expect pauses when the machine sleeps or updates. -Short answer: **if you want 24/7 reliability, use a VPS**. If you want the -lowest friction and you're okay with sleep/restarts, run it locally. + If you want the best of both worlds, keep the Gateway on a dedicated host and pair your laptop as a **node** for local screen/camera/exec tools. See [Nodes](/nodes). + For security guidance, read [Security](/gateway/security). -**Laptop (local Gateway)** + -- **Pros:** no server cost, direct access to local files, live browser window. -- **Cons:** sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake. + + OpenClaw is lightweight. For a basic Gateway + one chat channel: -**VPS / cloud** + - **Absolute minimum:** 1 vCPU, 1GB RAM, ~500MB disk. + - **Recommended:** 1-2 vCPU, 2GB RAM or more for headroom (logs, media, multiple channels). Node tools and browser automation can be resource hungry. -- **Pros:** always-on, stable network, no laptop sleep issues, easier to keep running. -- **Cons:** often run headless (use screenshots), remote file access only, you must SSH for updates. + OS: use **Ubuntu LTS** (or any modern Debian/Ubuntu). The Linux install path is best tested there. -**OpenClaw-specific note:** WhatsApp/Telegram/Slack/Mattermost (plugin)/Discord all work fine from a VPS. The only real trade-off is **headless browser** vs a visible window. See [Browser](/tools/browser). + Docs: [Linux](/platforms/linux), [VPS hosting](/vps). -**Recommended default:** VPS if you had gateway disconnects before. Local is great when you're actively using the Mac and want local file access or UI automation with a visible browser. + -### How important is it to run OpenClaw on a dedicated machine + + Yes. Treat a VM the same as a VPS: it needs to be always on, reachable, and have enough + RAM for the Gateway and any channels you enable. -Not required, but **recommended for reliability and isolation**. + Baseline guidance: -- **Dedicated host (VPS/Mac mini/Pi):** always-on, fewer sleep/reboot interruptions, cleaner permissions, easier to keep running. -- **Shared laptop/desktop:** totally fine for testing and active use, but expect pauses when the machine sleeps or updates. + - **Absolute minimum:** 1 vCPU, 1GB RAM. + - **Recommended:** 2GB RAM or more if you run multiple channels, browser automation, or media tools. + - **OS:** Ubuntu LTS or another modern Debian/Ubuntu. -If you want the best of both worlds, keep the Gateway on a dedicated host and pair your laptop as a **node** for local screen/camera/exec tools. See [Nodes](/nodes). -For security guidance, read [Security](/gateway/security). + If you are on Windows, **WSL2 is the easiest VM style setup** and has the best tooling + compatibility. See [Windows](/platforms/windows), [VPS hosting](/vps). + If you are running macOS in a VM, see [macOS VM](/install/macos-vm). -### What are the minimum VPS requirements and recommended OS - -OpenClaw is lightweight. For a basic Gateway + one chat channel: - -- **Absolute minimum:** 1 vCPU, 1GB RAM, ~500MB disk. -- **Recommended:** 1-2 vCPU, 2GB RAM or more for headroom (logs, media, multiple channels). Node tools and browser automation can be resource hungry. - -OS: use **Ubuntu LTS** (or any modern Debian/Ubuntu). The Linux install path is best tested there. - -Docs: [Linux](/platforms/linux), [VPS hosting](/vps). - -### Can I run OpenClaw in a VM and what are the requirements - -Yes. Treat a VM the same as a VPS: it needs to be always on, reachable, and have enough -RAM for the Gateway and any channels you enable. - -Baseline guidance: - -- **Absolute minimum:** 1 vCPU, 1GB RAM. -- **Recommended:** 2GB RAM or more if you run multiple channels, browser automation, or media tools. -- **OS:** Ubuntu LTS or another modern Debian/Ubuntu. - -If you are on Windows, **WSL2 is the easiest VM style setup** and has the best tooling -compatibility. See [Windows](/platforms/windows), [VPS hosting](/vps). -If you are running macOS in a VM, see [macOS VM](/install/macos-vm). + + ## What is OpenClaw? -### What is OpenClaw in one paragraph + + + OpenClaw is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Google Chat, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always-on control plane; the assistant is the product. + -OpenClaw is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Google Chat, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always-on control plane; the assistant is the product. + + OpenClaw is not "just a Claude wrapper." It's a **local-first control plane** that lets you run a + capable assistant on **your own hardware**, reachable from the chat apps you already use, with + stateful sessions, memory, and tools - without handing control of your workflows to a hosted + SaaS. -### Value proposition + Highlights: -OpenClaw is not "just a Claude wrapper." It's a **local-first control plane** that lets you run a -capable assistant on **your own hardware**, reachable from the chat apps you already use, with -stateful sessions, memory, and tools - without handing control of your workflows to a hosted -SaaS. + - **Your devices, your data:** run the Gateway wherever you want (Mac, Linux, VPS) and keep the + workspace + session history local. + - **Real channels, not a web sandbox:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc, + plus mobile voice and Canvas on supported platforms. + - **Model-agnostic:** use Anthropic, OpenAI, MiniMax, OpenRouter, etc., with per-agent routing + and failover. + - **Local-only option:** run local models so **all data can stay on your device** if you want. + - **Multi-agent routing:** separate agents per channel, account, or task, each with its own + workspace and defaults. + - **Open source and hackable:** inspect, extend, and self-host without vendor lock-in. -Highlights: + Docs: [Gateway](/gateway), [Channels](/channels), [Multi-agent](/concepts/multi-agent), + [Memory](/concepts/memory). -- **Your devices, your data:** run the Gateway wherever you want (Mac, Linux, VPS) and keep the - workspace + session history local. -- **Real channels, not a web sandbox:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc, - plus mobile voice and Canvas on supported platforms. -- **Model-agnostic:** use Anthropic, OpenAI, MiniMax, OpenRouter, etc., with per-agent routing - and failover. -- **Local-only option:** run local models so **all data can stay on your device** if you want. -- **Multi-agent routing:** separate agents per channel, account, or task, each with its own - workspace and defaults. -- **Open source and hackable:** inspect, extend, and self-host without vendor lock-in. + -Docs: [Gateway](/gateway), [Channels](/channels), [Multi-agent](/concepts/multi-agent), -[Memory](/concepts/memory). + + Good first projects: -### I just set it up what should I do first + - Build a website (WordPress, Shopify, or a simple static site). + - Prototype a mobile app (outline, screens, API plan). + - Organize files and folders (cleanup, naming, tagging). + - Connect Gmail and automate summaries or follow ups. -Good first projects: + It can handle large tasks, but it works best when you split them into phases and + use sub agents for parallel work. -- Build a website (WordPress, Shopify, or a simple static site). -- Prototype a mobile app (outline, screens, API plan). -- Organize files and folders (cleanup, naming, tagging). -- Connect Gmail and automate summaries or follow ups. + -It can handle large tasks, but it works best when you split them into phases and -use sub agents for parallel work. + + Everyday wins usually look like: -### What are the top five everyday use cases for OpenClaw + - **Personal briefings:** summaries of inbox, calendar, and news you care about. + - **Research and drafting:** quick research, summaries, and first drafts for emails or docs. + - **Reminders and follow ups:** cron or heartbeat driven nudges and checklists. + - **Browser automation:** filling forms, collecting data, and repeating web tasks. + - **Cross device coordination:** send a task from your phone, let the Gateway run it on a server, and get the result back in chat. -Everyday wins usually look like: + -- **Personal briefings:** summaries of inbox, calendar, and news you care about. -- **Research and drafting:** quick research, summaries, and first drafts for emails or docs. -- **Reminders and follow ups:** cron or heartbeat driven nudges and checklists. -- **Browser automation:** filling forms, collecting data, and repeating web tasks. -- **Cross device coordination:** send a task from your phone, let the Gateway run it on a server, and get the result back in chat. + + Yes for **research, qualification, and drafting**. It can scan sites, build shortlists, + summarize prospects, and write outreach or ad copy drafts. -### Can OpenClaw help with lead gen outreach ads and blogs for a SaaS + For **outreach or ad runs**, keep a human in the loop. Avoid spam, follow local laws and + platform policies, and review anything before it is sent. The safest pattern is to let + OpenClaw draft and you approve. -Yes for **research, qualification, and drafting**. It can scan sites, build shortlists, -summarize prospects, and write outreach or ad copy drafts. + Docs: [Security](/gateway/security). -For **outreach or ad runs**, keep a human in the loop. Avoid spam, follow local laws and -platform policies, and review anything before it is sent. The safest pattern is to let -OpenClaw draft and you approve. + -Docs: [Security](/gateway/security). + + OpenClaw is a **personal assistant** and coordination layer, not an IDE replacement. Use + Claude Code or Codex for the fastest direct coding loop inside a repo. Use OpenClaw when you + want durable memory, cross-device access, and tool orchestration. -### What are the advantages vs Claude Code for web development + Advantages: -OpenClaw is a **personal assistant** and coordination layer, not an IDE replacement. Use -Claude Code or Codex for the fastest direct coding loop inside a repo. Use OpenClaw when you -want durable memory, cross-device access, and tool orchestration. + - **Persistent memory + workspace** across sessions + - **Multi-platform access** (WhatsApp, Telegram, TUI, WebChat) + - **Tool orchestration** (browser, files, scheduling, hooks) + - **Always-on Gateway** (run on a VPS, interact from anywhere) + - **Nodes** for local browser/screen/camera/exec -Advantages: + Showcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) -- **Persistent memory + workspace** across sessions -- **Multi-platform access** (WhatsApp, Telegram, TUI, WebChat) -- **Tool orchestration** (browser, files, scheduling, hooks) -- **Always-on Gateway** (run on a VPS, interact from anywhere) -- **Nodes** for local browser/screen/camera/exec - -Showcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) + + ## Skills and automation -### How do I customize skills without keeping the repo dirty + + + Use managed overrides instead of editing the repo copy. Put your changes in `~/.openclaw/skills//SKILL.md` (or add a folder via `skills.load.extraDirs` in `~/.openclaw/openclaw.json`). Precedence is `/skills` > `~/.openclaw/skills` > bundled, so managed overrides win without touching git. Only upstream-worthy edits should live in the repo and go out as PRs. + -Use managed overrides instead of editing the repo copy. Put your changes in `~/.openclaw/skills//SKILL.md` (or add a folder via `skills.load.extraDirs` in `~/.openclaw/openclaw.json`). Precedence is `/skills` > `~/.openclaw/skills` > bundled, so managed overrides win without touching git. Only upstream-worthy edits should live in the repo and go out as PRs. + + Yes. Add extra directories via `skills.load.extraDirs` in `~/.openclaw/openclaw.json` (lowest precedence). Default precedence remains: `/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` installs into `./skills` by default, which OpenClaw treats as `/skills` on the next session. + -### Can I load skills from a custom folder + + Today the supported patterns are: -Yes. Add extra directories via `skills.load.extraDirs` in `~/.openclaw/openclaw.json` (lowest precedence). Default precedence remains: `/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` installs into `./skills` by default, which OpenClaw treats as `/skills`. + - **Cron jobs**: isolated jobs can set a `model` override per job. + - **Sub-agents**: route tasks to separate agents with different default models. + - **On-demand switch**: use `/model` to switch the current session model at any time. -### How can I use different models for different tasks + See [Cron jobs](/automation/cron-jobs), [Multi-Agent Routing](/concepts/multi-agent), and [Slash commands](/tools/slash-commands). -Today the supported patterns are: + -- **Cron jobs**: isolated jobs can set a `model` override per job. -- **Sub-agents**: route tasks to separate agents with different default models. -- **On-demand switch**: use `/model` to switch the current session model at any time. + + Use **sub-agents** for long or parallel tasks. Sub-agents run in their own session, + return a summary, and keep your main chat responsive. -See [Cron jobs](/automation/cron-jobs), [Multi-Agent Routing](/concepts/multi-agent), and [Slash commands](/tools/slash-commands). + Ask your bot to "spawn a sub-agent for this task" or use `/subagents`. + Use `/status` in chat to see what the Gateway is doing right now (and whether it is busy). -### The bot freezes while doing heavy work How do I offload that + Token tip: long tasks and sub-agents both consume tokens. If cost is a concern, set a + cheaper model for sub-agents via `agents.defaults.subagents.model`. -Use **sub-agents** for long or parallel tasks. Sub-agents run in their own session, -return a summary, and keep your main chat responsive. + Docs: [Sub-agents](/tools/subagents). -Ask your bot to "spawn a sub-agent for this task" or use `/subagents`. -Use `/status` in chat to see what the Gateway is doing right now (and whether it is busy). + -Token tip: long tasks and sub-agents both consume tokens. If cost is a concern, set a -cheaper model for sub-agents via `agents.defaults.subagents.model`. + + Use thread bindings. You can bind a Discord thread to a subagent or session target so follow-up messages in that thread stay on that bound session. -Docs: [Sub-agents](/tools/subagents). + Basic flow: -### How do thread-bound subagent sessions work on Discord + - Spawn with `sessions_spawn` using `thread: true` (and optionally `mode: "session"` for persistent follow-up). + - Or manually bind with `/focus `. + - Use `/agents` to inspect binding state. + - Use `/session idle ` and `/session max-age ` to control auto-unfocus. + - Use `/unfocus` to detach the thread. -Use thread bindings. You can bind a Discord thread to a subagent or session target so follow-up messages in that thread stay on that bound session. + Required config: -Basic flow: + - Global defaults: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. + - Discord overrides: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - Auto-bind on spawn: set `channels.discord.threadBindings.spawnSubagentSessions: true`. -- Spawn with `sessions_spawn` using `thread: true` (and optionally `mode: "session"` for persistent follow-up). -- Or manually bind with `/focus `. -- Use `/agents` to inspect binding state. -- Use `/session idle ` and `/session max-age ` to control auto-unfocus. -- Use `/unfocus` to detach the thread. + Docs: [Sub-agents](/tools/subagents), [Discord](/channels/discord), [Configuration Reference](/gateway/configuration-reference), [Slash commands](/tools/slash-commands). -Required config: + -- Global defaults: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. -- Discord overrides: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. -- Auto-bind on spawn: set `channels.discord.threadBindings.spawnSubagentSessions: true`. + + Cron runs inside the Gateway process. If the Gateway is not running continuously, + scheduled jobs will not run. -Docs: [Sub-agents](/tools/subagents), [Discord](/channels/discord), [Configuration Reference](/gateway/configuration-reference), [Slash commands](/tools/slash-commands). + Checklist: -### Cron or reminders do not fire What should I check + - Confirm cron is enabled (`cron.enabled`) and `OPENCLAW_SKIP_CRON` is not set. + - Check the Gateway is running 24/7 (no sleep/restarts). + - Verify timezone settings for the job (`--tz` vs host timezone). -Cron runs inside the Gateway process. If the Gateway is not running continuously, -scheduled jobs will not run. + Debug: -Checklist: + ```bash + openclaw cron run --force + openclaw cron runs --id --limit 50 + ``` -- Confirm cron is enabled (`cron.enabled`) and `OPENCLAW_SKIP_CRON` is not set. -- Check the Gateway is running 24/7 (no sleep/restarts). -- Verify timezone settings for the job (`--tz` vs host timezone). + Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat). -Debug: + -```bash -openclaw cron run --force -openclaw cron runs --id --limit 50 -``` + + Use **ClawHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn't available on Linux. + Browse skills at [https://clawhub.com](https://clawhub.com). -Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat). + Install the ClawHub CLI (pick one package manager): -### How do I install skills on Linux + ```bash + npm i -g clawhub + ``` -Use **ClawHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn't available on Linux. -Browse skills at [https://clawhub.com](https://clawhub.com). + ```bash + pnpm add -g clawhub + ``` -Install the ClawHub CLI (pick one package manager): + -```bash -npm i -g clawhub -``` + + Yes. Use the Gateway scheduler: -```bash -pnpm add -g clawhub -``` + - **Cron jobs** for scheduled or recurring tasks (persist across restarts). + - **Heartbeat** for "main session" periodic checks. + - **Isolated jobs** for autonomous agents that post summaries or deliver to chats. -### Can OpenClaw run tasks on a schedule or continuously in the background + Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat), + [Heartbeat](/gateway/heartbeat). -Yes. Use the Gateway scheduler: + -- **Cron jobs** for scheduled or recurring tasks (persist across restarts). -- **Heartbeat** for "main session" periodic checks. -- **Isolated jobs** for autonomous agents that post summaries or deliver to chats. + + Not directly. macOS skills are gated by `metadata.openclaw.os` plus required binaries, and skills only appear in the system prompt when they are eligible on the **Gateway host**. On Linux, `darwin`-only skills (like `apple-notes`, `apple-reminders`, `things-mac`) will not load unless you override the gating. -Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat), -[Heartbeat](/gateway/heartbeat). + You have three supported patterns: -### Can I run Apple macOS-only skills from Linux? + **Option A - run the Gateway on a Mac (simplest).** + Run the Gateway where the macOS binaries exist, then connect from Linux in [remote mode](#gateway-ports-already-running-and-remote-mode) or over Tailscale. The skills load normally because the Gateway host is macOS. -Not directly. macOS skills are gated by `metadata.openclaw.os` plus required binaries, and skills only appear in the system prompt when they are eligible on the **Gateway host**. On Linux, `darwin`-only skills (like `apple-notes`, `apple-reminders`, `things-mac`) will not load unless you override the gating. + **Option B - use a macOS node (no SSH).** + Run the Gateway on Linux, pair a macOS node (menubar app), and set **Node Run Commands** to "Always Ask" or "Always Allow" on the Mac. OpenClaw can treat macOS-only skills as eligible when the required binaries exist on the node. The agent runs those skills via the `nodes` tool. If you choose "Always Ask", approving "Always Allow" in the prompt adds that command to the allowlist. -You have three supported patterns: + **Option C - proxy macOS binaries over SSH (advanced).** + Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wrappers that run on a Mac. Then override the skill to allow Linux so it stays eligible. -**Option A - run the Gateway on a Mac (simplest).** -Run the Gateway where the macOS binaries exist, then connect from Linux in [remote mode](#how-do-i-run-openclaw-in-remote-mode-client-connects-to-a-gateway-elsewhere) or over Tailscale. The skills load normally because the Gateway host is macOS. + 1. Create an SSH wrapper for the binary (example: `memo` for Apple Notes): -**Option B - use a macOS node (no SSH).** -Run the Gateway on Linux, pair a macOS node (menubar app), and set **Node Run Commands** to "Always Ask" or "Always Allow" on the Mac. OpenClaw can treat macOS-only skills as eligible when the required binaries exist on the node. The agent runs those skills via the `nodes` tool. If you choose "Always Ask", approving "Always Allow" in the prompt adds that command to the allowlist. + ```bash + #!/usr/bin/env bash + set -euo pipefail + exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" + ``` -**Option C - proxy macOS binaries over SSH (advanced).** -Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wrappers that run on a Mac. Then override the skill to allow Linux so it stays eligible. + 2. Put the wrapper on `PATH` on the Linux host (for example `~/bin/memo`). + 3. Override the skill metadata (workspace or `~/.openclaw/skills`) to allow Linux: -1. Create an SSH wrapper for the binary (example: `memo` for Apple Notes): + ```markdown + --- + name: apple-notes + description: Manage Apple Notes via the memo CLI on macOS. + metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } + --- + ``` - ```bash - #!/usr/bin/env bash - set -euo pipefail - exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" - ``` + 4. Start a new session so the skills snapshot refreshes. -2. Put the wrapper on `PATH` on the Linux host (for example `~/bin/memo`). -3. Override the skill metadata (workspace or `~/.openclaw/skills`) to allow Linux: + - ```markdown - --- - name: apple-notes - description: Manage Apple Notes via the memo CLI on macOS. - metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } - --- - ``` + + Not built-in today. -4. Start a new session so the skills snapshot refreshes. + Options: -### Do you have a Notion or HeyGen integration + - **Custom skill / plugin:** best for reliable API access (Notion/HeyGen both have APIs). + - **Browser automation:** works without code but is slower and more fragile. -Not built-in today. + If you want to keep context per client (agency workflows), a simple pattern is: -Options: + - One Notion page per client (context + preferences + active work). + - Ask the agent to fetch that page at the start of a session. -- **Custom skill / plugin:** best for reliable API access (Notion/HeyGen both have APIs). -- **Browser automation:** works without code but is slower and more fragile. + If you want a native integration, open a feature request or build a skill + targeting those APIs. -If you want to keep context per client (agency workflows), a simple pattern is: + Install skills: -- One Notion page per client (context + preferences + active work). -- Ask the agent to fetch that page at the start of a session. + ```bash + clawhub install + clawhub update --all + ``` -If you want a native integration, open a feature request or build a skill -targeting those APIs. + ClawHub installs into `./skills` under your current directory (or falls back to your configured OpenClaw workspace); OpenClaw treats that as `/skills` on the next session. For shared skills across agents, place them in `~/.openclaw/skills//SKILL.md`. Some skills expect binaries installed via Homebrew; on Linux that means Linuxbrew (see the Homebrew Linux FAQ entry above). See [Skills](/tools/skills) and [ClawHub](/tools/clawhub). -Install skills: + -```bash -clawhub install -clawhub update --all -``` + + Use the built-in `user` browser profile, which attaches through Chrome DevTools MCP: -ClawHub installs into `./skills` under your current directory (or falls back to your configured OpenClaw workspace); OpenClaw treats that as `/skills` on the next session. For shared skills across agents, place them in `~/.openclaw/skills//SKILL.md`. Some skills expect binaries installed via Homebrew; on Linux that means Linuxbrew (see the Homebrew Linux FAQ entry above). See [Skills](/tools/skills) and [ClawHub](/tools/clawhub). + ```bash + openclaw browser --browser-profile user tabs + openclaw browser --browser-profile user snapshot + ``` -### How do I use my existing signed-in Chrome with OpenClaw + If you want a custom name, create an explicit MCP profile: -Use the built-in `user` browser profile, which attaches through Chrome DevTools MCP: + ```bash + openclaw browser create-profile --name chrome-live --driver existing-session + openclaw browser --browser-profile chrome-live tabs + ``` -```bash -openclaw browser --browser-profile user tabs -openclaw browser --browser-profile user snapshot -``` + This path is host-local. If the Gateway runs elsewhere, either run a node host on the browser machine or use remote CDP instead. -If you want a custom name, create an explicit MCP profile: - -```bash -openclaw browser create-profile --name chrome-live --driver existing-session -openclaw browser --browser-profile chrome-live tabs -``` - -This path is host-local. If the Gateway runs elsewhere, either run a node host on the browser machine or use remote CDP instead. + + ## Sandboxing and memory -### Is there a dedicated sandboxing doc + + + Yes. See [Sandboxing](/gateway/sandboxing). For Docker-specific setup (full gateway in Docker or sandbox images), see [Docker](/install/docker). + -Yes. See [Sandboxing](/gateway/sandboxing). For Docker-specific setup (full gateway in Docker or sandbox images), see [Docker](/install/docker). + + The default image is security-first and runs as the `node` user, so it does not + include system packages, Homebrew, or bundled browsers. For a fuller setup: -### Docker feels limited How do I enable full features + - Persist `/home/node` with `OPENCLAW_HOME_VOLUME` so caches survive. + - Bake system deps into the image with `OPENCLAW_DOCKER_APT_PACKAGES`. + - Install Playwright browsers via the bundled CLI: + `node /app/node_modules/playwright-core/cli.js install chromium` + - Set `PLAYWRIGHT_BROWSERS_PATH` and ensure the path is persisted. -The default image is security-first and runs as the `node` user, so it does not -include system packages, Homebrew, or bundled browsers. For a fuller setup: + Docs: [Docker](/install/docker), [Browser](/tools/browser). -- Persist `/home/node` with `OPENCLAW_HOME_VOLUME` so caches survive. -- Bake system deps into the image with `OPENCLAW_DOCKER_APT_PACKAGES`. -- Install Playwright browsers via the bundled CLI: - `node /app/node_modules/playwright-core/cli.js install chromium` -- Set `PLAYWRIGHT_BROWSERS_PATH` and ensure the path is persisted. + -Docs: [Docker](/install/docker), [Browser](/tools/browser). + + Yes - if your private traffic is **DMs** and your public traffic is **groups**. -**Can I keep DMs personal but make groups public sandboxed with one agent** + Use `agents.defaults.sandbox.mode: "non-main"` so group/channel sessions (non-main keys) run in Docker, while the main DM session stays on-host. Then restrict what tools are available in sandboxed sessions via `tools.sandbox.tools`. -Yes - if your private traffic is **DMs** and your public traffic is **groups**. + Setup walkthrough + example config: [Groups: personal DMs + public groups](/channels/groups#pattern-personal-dms-public-groups-single-agent) -Use `agents.defaults.sandbox.mode: "non-main"` so group/channel sessions (non-main keys) run in Docker, while the main DM session stays on-host. Then restrict what tools are available in sandboxed sessions via `tools.sandbox.tools`. + Key config reference: [Gateway configuration](/gateway/configuration-reference#agents-defaults-sandbox) -Setup walkthrough + example config: [Groups: personal DMs + public groups](/channels/groups#pattern-personal-dms-public-groups-single-agent) + -Key config reference: [Gateway configuration](/gateway/configuration-reference#agents-defaults-sandbox) + + Set `agents.defaults.sandbox.docker.binds` to `["host:path:mode"]` (e.g., `"/home/user/src:/src:ro"`). Global + per-agent binds merge; per-agent binds are ignored when `scope: "shared"`. Use `:ro` for anything sensitive and remember binds bypass the sandbox filesystem walls. See [Sandboxing](/gateway/sandboxing#custom-bind-mounts) and [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) for examples and safety notes. + -### How do I bind a host folder into the sandbox + + OpenClaw memory is just Markdown files in the agent workspace: -Set `agents.defaults.sandbox.docker.binds` to `["host:path:mode"]` (e.g., `"/home/user/src:/src:ro"`). Global + per-agent binds merge; per-agent binds are ignored when `scope: "shared"`. Use `:ro` for anything sensitive and remember binds bypass the sandbox filesystem walls. See [Sandboxing](/gateway/sandboxing#custom-bind-mounts) and [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) for examples and safety notes. + - Daily notes in `memory/YYYY-MM-DD.md` + - Curated long-term notes in `MEMORY.md` (main/private sessions only) -### How does memory work + OpenClaw also runs a **silent pre-compaction memory flush** to remind the model + to write durable notes before auto-compaction. This only runs when the workspace + is writable (read-only sandboxes skip it). See [Memory](/concepts/memory). -OpenClaw memory is just Markdown files in the agent workspace: + -- Daily notes in `memory/YYYY-MM-DD.md` -- Curated long-term notes in `MEMORY.md` (main/private sessions only) + + Ask the bot to **write the fact to memory**. Long-term notes belong in `MEMORY.md`, + short-term context goes into `memory/YYYY-MM-DD.md`. -OpenClaw also runs a **silent pre-compaction memory flush** to remind the model -to write durable notes before auto-compaction. This only runs when the workspace -is writable (read-only sandboxes skip it). See [Memory](/concepts/memory). + This is still an area we are improving. It helps to remind the model to store memories; + it will know what to do. If it keeps forgetting, verify the Gateway is using the same + workspace on every run. -### Memory keeps forgetting things How do I make it stick + Docs: [Memory](/concepts/memory), [Agent workspace](/concepts/agent-workspace). -Ask the bot to **write the fact to memory**. Long-term notes belong in `MEMORY.md`, -short-term context goes into `memory/YYYY-MM-DD.md`. + -This is still an area we are improving. It helps to remind the model to store memories; -it will know what to do. If it keeps forgetting, verify the Gateway is using the same -workspace on every run. + + Memory files live on disk and persist until you delete them. The limit is your + storage, not the model. The **session context** is still limited by the model + context window, so long conversations can compact or truncate. That is why + memory search exists - it pulls only the relevant parts back into context. -Docs: [Memory](/concepts/memory), [Agent workspace](/concepts/agent-workspace). + Docs: [Memory](/concepts/memory), [Context](/concepts/context). -### Does semantic memory search require an OpenAI API key + -Only if you use **OpenAI embeddings**. Codex OAuth covers chat/completions and -does **not** grant embeddings access, so **signing in with Codex (OAuth or the -Codex CLI login)** does not help for semantic memory search. OpenAI embeddings -still need a real API key (`OPENAI_API_KEY` or `models.providers.openai.apiKey`). + + Only if you use **OpenAI embeddings**. Codex OAuth covers chat/completions and + does **not** grant embeddings access, so **signing in with Codex (OAuth or the + Codex CLI login)** does not help for semantic memory search. OpenAI embeddings + still need a real API key (`OPENAI_API_KEY` or `models.providers.openai.apiKey`). -If you don't set a provider explicitly, OpenClaw auto-selects a provider when it -can resolve an API key (auth profiles, `models.providers.*.apiKey`, or env vars). -It prefers OpenAI if an OpenAI key resolves, otherwise Gemini if a Gemini key -resolves, then Voyage, then Mistral. If no remote key is available, memory -search stays disabled until you configure it. If you have a local model path -configured and present, OpenClaw -prefers `local`. Ollama is supported when you explicitly set -`memorySearch.provider = "ollama"`. + If you don't set a provider explicitly, OpenClaw auto-selects a provider when it + can resolve an API key (auth profiles, `models.providers.*.apiKey`, or env vars). + It prefers OpenAI if an OpenAI key resolves, otherwise Gemini if a Gemini key + resolves, then Voyage, then Mistral. If no remote key is available, memory + search stays disabled until you configure it. If you have a local model path + configured and present, OpenClaw + prefers `local`. Ollama is supported when you explicitly set + `memorySearch.provider = "ollama"`. -If you'd rather stay local, set `memorySearch.provider = "local"` (and optionally -`memorySearch.fallback = "none"`). If you want Gemini embeddings, set -`memorySearch.provider = "gemini"` and provide `GEMINI_API_KEY` (or -`memorySearch.remote.apiKey`). We support **OpenAI, Gemini, Voyage, Mistral, Ollama, or local** embedding -models - see [Memory](/concepts/memory) for the setup details. + If you'd rather stay local, set `memorySearch.provider = "local"` (and optionally + `memorySearch.fallback = "none"`). If you want Gemini embeddings, set + `memorySearch.provider = "gemini"` and provide `GEMINI_API_KEY` (or + `memorySearch.remote.apiKey`). We support **OpenAI, Gemini, Voyage, Mistral, Ollama, or local** embedding + models - see [Memory](/concepts/memory) for the setup details. -### Does memory persist forever What are the limits - -Memory files live on disk and persist until you delete them. The limit is your -storage, not the model. The **session context** is still limited by the model -context window, so long conversations can compact or truncate. That is why -memory search exists - it pulls only the relevant parts back into context. - -Docs: [Memory](/concepts/memory), [Context](/concepts/context). + + ## Where things live on disk -### Is all data used with OpenClaw saved locally + + + No - **OpenClaw's state is local**, but **external services still see what you send them**. -No - **OpenClaw's state is local**, but **external services still see what you send them**. + - **Local by default:** sessions, memory files, config, and workspace live on the Gateway host + (`~/.openclaw` + your workspace directory). + - **Remote by necessity:** messages you send to model providers (Anthropic/OpenAI/etc.) go to + their APIs, and chat platforms (WhatsApp/Telegram/Slack/etc.) store message data on their + servers. + - **You control the footprint:** using local models keeps prompts on your machine, but channel + traffic still goes through the channel's servers. -- **Local by default:** sessions, memory files, config, and workspace live on the Gateway host - (`~/.openclaw` + your workspace directory). -- **Remote by necessity:** messages you send to model providers (Anthropic/OpenAI/etc.) go to - their APIs, and chat platforms (WhatsApp/Telegram/Slack/etc.) store message data on their - servers. -- **You control the footprint:** using local models keeps prompts on your machine, but channel - traffic still goes through the channel's servers. + Related: [Agent workspace](/concepts/agent-workspace), [Memory](/concepts/memory). -Related: [Agent workspace](/concepts/agent-workspace), [Memory](/concepts/memory). + -### Where does OpenClaw store its data + + Everything lives under `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`): -Everything lives under `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`): + | Path | Purpose | + | --------------------------------------------------------------- | ------------------------------------------------------------------ | + | `$OPENCLAW_STATE_DIR/openclaw.json` | Main config (JSON5) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, API keys, and optional `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Optional file-backed secret payload for `file` SecretRef providers | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Legacy compatibility file (static `api_key` entries scrubbed) | + | `$OPENCLAW_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Per-agent state (agentDir + sessions) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Conversation history & state (per agent) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Session metadata (per agent) | -| Path | Purpose | -| --------------------------------------------------------------- | ------------------------------------------------------------------ | -| `$OPENCLAW_STATE_DIR/openclaw.json` | Main config (JSON5) | -| `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) | -| `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, API keys, and optional `keyRef`/`tokenRef`) | -| `$OPENCLAW_STATE_DIR/secrets.json` | Optional file-backed secret payload for `file` SecretRef providers | -| `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Legacy compatibility file (static `api_key` entries scrubbed) | -| `$OPENCLAW_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp//creds.json`) | -| `$OPENCLAW_STATE_DIR/agents/` | Per-agent state (agentDir + sessions) | -| `$OPENCLAW_STATE_DIR/agents//sessions/` | Conversation history & state (per agent) | -| `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Session metadata (per agent) | + Legacy single-agent path: `~/.openclaw/agent/*` (migrated by `openclaw doctor`). -Legacy single-agent path: `~/.openclaw/agent/*` (migrated by `openclaw doctor`). + Your **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agents.defaults.workspace` (default: `~/.openclaw/workspace`). -Your **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agents.defaults.workspace` (default: `~/.openclaw/workspace`). + -### Where should AGENTSmd SOULmd USERmd MEMORYmd live + + These files live in the **agent workspace**, not `~/.openclaw`. -These files live in the **agent workspace**, not `~/.openclaw`. + - **Workspace (per agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + `MEMORY.md` (or legacy fallback `memory.md` when `MEMORY.md` is absent), + `memory/YYYY-MM-DD.md`, optional `HEARTBEAT.md`. + - **State dir (`~/.openclaw`)**: config, credentials, auth profiles, sessions, logs, + and shared skills (`~/.openclaw/skills`). -- **Workspace (per agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md` (or legacy fallback `memory.md` when `MEMORY.md` is absent), - `memory/YYYY-MM-DD.md`, optional `HEARTBEAT.md`. -- **State dir (`~/.openclaw`)**: config, credentials, auth profiles, sessions, logs, - and shared skills (`~/.openclaw/skills`). + Default workspace is `~/.openclaw/workspace`, configurable via: -Default workspace is `~/.openclaw/workspace`, configurable via: + ```json5 + { + agents: { defaults: { workspace: "~/.openclaw/workspace" } }, + } + ``` -```json5 -{ - agents: { defaults: { workspace: "~/.openclaw/workspace" } }, -} -``` + If the bot "forgets" after a restart, confirm the Gateway is using the same + workspace on every launch (and remember: remote mode uses the **gateway host's** + workspace, not your local laptop). -If the bot "forgets" after a restart, confirm the Gateway is using the same -workspace on every launch (and remember: remote mode uses the **gateway host's** -workspace, not your local laptop). + Tip: if you want a durable behavior or preference, ask the bot to **write it into + AGENTS.md or MEMORY.md** rather than relying on chat history. -Tip: if you want a durable behavior or preference, ask the bot to **write it into -AGENTS.md or MEMORY.md** rather than relying on chat history. + See [Agent workspace](/concepts/agent-workspace) and [Memory](/concepts/memory). -See [Agent workspace](/concepts/agent-workspace) and [Memory](/concepts/memory). + -### Recommended backup strategy + + Put your **agent workspace** in a **private** git repo and back it up somewhere + private (for example GitHub private). This captures memory + AGENTS/SOUL/USER + files, and lets you restore the assistant's "mind" later. -Put your **agent workspace** in a **private** git repo and back it up somewhere -private (for example GitHub private). This captures memory + AGENTS/SOUL/USER -files, and lets you restore the assistant's "mind" later. + Do **not** commit anything under `~/.openclaw` (credentials, sessions, tokens, or encrypted secrets payloads). + If you need a full restore, back up both the workspace and the state directory + separately (see the migration question above). -Do **not** commit anything under `~/.openclaw` (credentials, sessions, tokens, or encrypted secrets payloads). -If you need a full restore, back up both the workspace and the state directory -separately (see the migration question above). + Docs: [Agent workspace](/concepts/agent-workspace). -Docs: [Agent workspace](/concepts/agent-workspace). + -### How do I completely uninstall OpenClaw + + See the dedicated guide: [Uninstall](/install/uninstall). + -See the dedicated guide: [Uninstall](/install/uninstall). + + Yes. The workspace is the **default cwd** and memory anchor, not a hard sandbox. + Relative paths resolve inside the workspace, but absolute paths can access other + host locations unless sandboxing is enabled. If you need isolation, use + [`agents.defaults.sandbox`](/gateway/sandboxing) or per-agent sandbox settings. If you + want a repo to be the default working directory, point that agent's + `workspace` to the repo root. The OpenClaw repo is just source code; keep the + workspace separate unless you intentionally want the agent to work inside it. -### Can agents work outside the workspace + Example (repo as default cwd): -Yes. The workspace is the **default cwd** and memory anchor, not a hard sandbox. -Relative paths resolve inside the workspace, but absolute paths can access other -host locations unless sandboxing is enabled. If you need isolation, use -[`agents.defaults.sandbox`](/gateway/sandboxing) or per-agent sandbox settings. If you -want a repo to be the default working directory, point that agent's -`workspace` to the repo root. The OpenClaw repo is just source code; keep the -workspace separate unless you intentionally want the agent to work inside it. + ```json5 + { + agents: { + defaults: { + workspace: "~/Projects/my-repo", + }, + }, + } + ``` -Example (repo as default cwd): + -```json5 -{ - agents: { - defaults: { - workspace: "~/Projects/my-repo", - }, - }, -} -``` - -### Im in remote mode where is the session store - -Session state is owned by the **gateway host**. If you're in remote mode, the session store you care about is on the remote machine, not your local laptop. See [Session management](/concepts/session). + + Session state is owned by the **gateway host**. If you're in remote mode, the session store you care about is on the remote machine, not your local laptop. See [Session management](/concepts/session). + + ## Config basics -### What format is the config Where is it + + + OpenClaw reads an optional **JSON5** config from `$OPENCLAW_CONFIG_PATH` (default: `~/.openclaw/openclaw.json`): -OpenClaw reads an optional **JSON5** config from `$OPENCLAW_CONFIG_PATH` (default: `~/.openclaw/openclaw.json`): + ``` + $OPENCLAW_CONFIG_PATH + ``` -``` -$OPENCLAW_CONFIG_PATH -``` + If the file is missing, it uses safe-ish defaults (including a default workspace of `~/.openclaw/workspace`). -If the file is missing, it uses safe-ish defaults (including a default workspace of `~/.openclaw/workspace`). + -### I set gatewaybind lan or tailnet and now nothing listens the UI says unauthorized + + Non-loopback binds **require auth**. Configure `gateway.auth.mode` + `gateway.auth.token` (or use `OPENCLAW_GATEWAY_TOKEN`). -Non-loopback binds **require auth**. Configure `gateway.auth.mode` + `gateway.auth.token` (or use `OPENCLAW_GATEWAY_TOKEN`). + ```json5 + { + gateway: { + bind: "lan", + auth: { + mode: "token", + token: "replace-me", + }, + }, + } + ``` -```json5 -{ - gateway: { - bind: "lan", - auth: { - mode: "token", - token: "replace-me", - }, - }, -} -``` + Notes: -Notes: + - `gateway.remote.token` / `.password` do **not** enable local gateway auth by themselves. + - Local call paths can use `gateway.remote.*` as fallback only when `gateway.auth.*` is unset. + - If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking). + - The Control UI authenticates via `connect.params.auth.token` (stored in app/UI settings). Avoid putting tokens in URLs. -- `gateway.remote.token` / `.password` do **not** enable local gateway auth by themselves. -- Local call paths can use `gateway.remote.*` as fallback only when `gateway.auth.*` is unset. -- If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking). -- The Control UI authenticates via `connect.params.auth.token` (stored in app/UI settings). Avoid putting tokens in URLs. + -### Why do I need a token on localhost now + + OpenClaw enforces token auth by default, including loopback. If no token is configured, gateway startup auto-generates one and saves it to `gateway.auth.token`, so **local WS clients must authenticate**. This blocks other local processes from calling the Gateway. -OpenClaw enforces token auth by default, including loopback. If no token is configured, gateway startup auto-generates one and saves it to `gateway.auth.token`, so **local WS clients must authenticate**. This blocks other local processes from calling the Gateway. + If you **really** want open loopback, set `gateway.auth.mode: "none"` explicitly in your config. Doctor can generate a token for you any time: `openclaw doctor --generate-gateway-token`. -If you **really** want open loopback, set `gateway.auth.mode: "none"` explicitly in your config. Doctor can generate a token for you any time: `openclaw doctor --generate-gateway-token`. + -### Do I have to restart after changing config + + The Gateway watches the config and supports hot-reload: -The Gateway watches the config and supports hot-reload: + - `gateway.reload.mode: "hybrid"` (default): hot-apply safe changes, restart for critical ones + - `hot`, `restart`, `off` are also supported -- `gateway.reload.mode: "hybrid"` (default): hot-apply safe changes, restart for critical ones -- `hot`, `restart`, `off` are also supported + -### How do I disable funny CLI taglines + + Set `cli.banner.taglineMode` in config: -Set `cli.banner.taglineMode` in config: + ```json5 + { + cli: { + banner: { + taglineMode: "off", // random | default | off + }, + }, + } + ``` -```json5 -{ - cli: { - banner: { - taglineMode: "off", // random | default | off - }, - }, -} -``` + - `off`: hides tagline text but keeps the banner title/version line. + - `default`: uses `All your chats, one OpenClaw.` every time. + - `random`: rotating funny/seasonal taglines (default behavior). + - If you want no banner at all, set env `OPENCLAW_HIDE_BANNER=1`. -- `off`: hides tagline text but keeps the banner title/version line. -- `default`: uses `All your chats, one OpenClaw.` every time. -- `random`: rotating funny/seasonal taglines (default behavior). -- If you want no banner at all, set env `OPENCLAW_HIDE_BANNER=1`. + -### How do I enable web search and web fetch + + `web_fetch` works without an API key. `web_search` requires a key for your + selected provider (Brave, Gemini, Grok, Kimi, or Perplexity). + **Recommended:** run `openclaw configure --section web` and choose a provider. + Environment alternatives: -`web_fetch` works without an API key. `web_search` requires a key for your -selected provider (Brave, Gemini, Grok, Kimi, or Perplexity). -**Recommended:** run `openclaw configure --section web` and choose a provider. -Environment alternatives: + - Brave: `BRAVE_API_KEY` + - Gemini: `GEMINI_API_KEY` + - Grok: `XAI_API_KEY` + - Kimi: `KIMI_API_KEY` or `MOONSHOT_API_KEY` + - Perplexity: `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY` -- Brave: `BRAVE_API_KEY` -- Gemini: `GEMINI_API_KEY` -- Grok: `XAI_API_KEY` -- Kimi: `KIMI_API_KEY` or `MOONSHOT_API_KEY` -- Perplexity: `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY` - -```json5 -{ - plugins: { - entries: { - brave: { - config: { - webSearch: { - apiKey: "BRAVE_API_KEY_HERE", + ```json5 + { + plugins: { + entries: { + brave: { + config: { + webSearch: { + apiKey: "BRAVE_API_KEY_HERE", + }, + }, }, }, }, - }, - }, - tools: { - web: { - search: { - enabled: true, - provider: "brave", - maxResults: 5, + tools: { + web: { + search: { + enabled: true, + provider: "brave", + maxResults: 5, + }, + fetch: { + enabled: true, + }, + }, }, - fetch: { - enabled: true, + } + ``` + + Provider-specific web-search config now lives under `plugins.entries..config.webSearch.*`. + Legacy `tools.web.search.*` provider paths still load temporarily for compatibility, but they should not be used for new configs. + + Notes: + + - If you use allowlists, add `web_search`/`web_fetch` or `group:web`. + - `web_fetch` is enabled by default (unless explicitly disabled). + - Daemons read env vars from `~/.openclaw/.env` (or the service environment). + + Docs: [Web tools](/tools/web). + + + + + `config.apply` replaces the **entire config**. If you send a partial object, everything + else is removed. + + Recover: + + - Restore from backup (git or a copied `~/.openclaw/openclaw.json`). + - If you have no backup, re-run `openclaw doctor` and reconfigure channels/models. + - If this was unexpected, file a bug and include your last known config or any backup. + - A local coding agent can often reconstruct a working config from logs or history. + + Avoid it: + + - Use `openclaw config set` for small changes. + - Use `openclaw configure` for interactive edits. + + Docs: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/gateway/doctor). + + + + + The common pattern is **one Gateway** (e.g. Raspberry Pi) plus **nodes** and **agents**: + + - **Gateway (central):** owns channels (Signal/WhatsApp), routing, and sessions. + - **Nodes (devices):** Macs/iOS/Android connect as peripherals and expose local tools (`system.run`, `canvas`, `camera`). + - **Agents (workers):** separate brains/workspaces for special roles (e.g. "Hetzner ops", "Personal data"). + - **Sub-agents:** spawn background work from a main agent when you want parallelism. + - **TUI:** connect to the Gateway and switch agents/sessions. + + Docs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/web/tui). + + + + + Yes. It's a config option: + + ```json5 + { + browser: { headless: true }, + agents: { + defaults: { + sandbox: { browser: { headless: true } }, + }, }, - }, - }, -} -``` + } + ``` -Provider-specific web-search config now lives under `plugins.entries..config.webSearch.*`. -Legacy `tools.web.search.*` provider paths still load temporarily for compatibility, but they should not be used for new configs. + Default is `false` (headful). Headless is more likely to trigger anti-bot checks on some sites. See [Browser](/tools/browser). -Notes: + Headless uses the **same Chromium engine** and works for most automation (forms, clicks, scraping, logins). The main differences: -- If you use allowlists, add `web_search`/`web_fetch` or `group:web`. -- `web_fetch` is enabled by default (unless explicitly disabled). -- Daemons read env vars from `~/.openclaw/.env` (or the service environment). + - No visible browser window (use screenshots if you need visuals). + - Some sites are stricter about automation in headless mode (CAPTCHAs, anti-bot). + For example, X/Twitter often blocks headless sessions. -Docs: [Web tools](/tools/web). + -### How do I run a central Gateway with specialized workers across devices - -The common pattern is **one Gateway** (e.g. Raspberry Pi) plus **nodes** and **agents**: - -- **Gateway (central):** owns channels (Signal/WhatsApp), routing, and sessions. -- **Nodes (devices):** Macs/iOS/Android connect as peripherals and expose local tools (`system.run`, `canvas`, `camera`). -- **Agents (workers):** separate brains/workspaces for special roles (e.g. "Hetzner ops", "Personal data"). -- **Sub-agents:** spawn background work from a main agent when you want parallelism. -- **TUI:** connect to the Gateway and switch agents/sessions. - -Docs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/web/tui). - -### Can the OpenClaw browser run headless - -Yes. It's a config option: - -```json5 -{ - browser: { headless: true }, - agents: { - defaults: { - sandbox: { browser: { headless: true } }, - }, - }, -} -``` - -Default is `false` (headful). Headless is more likely to trigger anti-bot checks on some sites. See [Browser](/tools/browser). - -Headless uses the **same Chromium engine** and works for most automation (forms, clicks, scraping, logins). The main differences: - -- No visible browser window (use screenshots if you need visuals). -- Some sites are stricter about automation in headless mode (CAPTCHAs, anti-bot). - For example, X/Twitter often blocks headless sessions. - -### How do I use Brave for browser control - -Set `browser.executablePath` to your Brave binary (or any Chromium-based browser) and restart the Gateway. -See the full config examples in [Browser](/tools/browser#use-brave-or-another-chromium-based-browser). + + Set `browser.executablePath` to your Brave binary (or any Chromium-based browser) and restart the Gateway. + See the full config examples in [Browser](/tools/browser#use-brave-or-another-chromium-based-browser). + + ## Remote gateways and nodes -### How do commands propagate between Telegram the gateway and nodes + + + Telegram messages are handled by the **gateway**. The gateway runs the agent and + only then calls nodes over the **Gateway WebSocket** when a node tool is needed: -Telegram messages are handled by the **gateway**. The gateway runs the agent and -only then calls nodes over the **Gateway WebSocket** when a node tool is needed: + Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram -Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram + Nodes don't see inbound provider traffic; they only receive node RPC calls. -Nodes don't see inbound provider traffic; they only receive node RPC calls. + -### How can my agent access my computer if the Gateway is hosted remotely + + Short answer: **pair your computer as a node**. The Gateway runs elsewhere, but it can + call `node.*` tools (screen, camera, system) on your local machine over the Gateway WebSocket. -Short answer: **pair your computer as a node**. The Gateway runs elsewhere, but it can -call `node.*` tools (screen, camera, system) on your local machine over the Gateway WebSocket. + Typical setup: -Typical setup: + 1. Run the Gateway on the always-on host (VPS/home server). + 2. Put the Gateway host + your computer on the same tailnet. + 3. Ensure the Gateway WS is reachable (tailnet bind or SSH tunnel). + 4. Open the macOS app locally and connect in **Remote over SSH** mode (or direct tailnet) + so it can register as a node. + 5. Approve the node on the Gateway: -1. Run the Gateway on the always-on host (VPS/home server). -2. Put the Gateway host + your computer on the same tailnet. -3. Ensure the Gateway WS is reachable (tailnet bind or SSH tunnel). -4. Open the macOS app locally and connect in **Remote over SSH** mode (or direct tailnet) - so it can register as a node. -5. Approve the node on the Gateway: + ```bash + openclaw devices list + openclaw devices approve + ``` - ```bash - openclaw devices list - openclaw devices approve - ``` + No separate TCP bridge is required; nodes connect over the Gateway WebSocket. -No separate TCP bridge is required; nodes connect over the Gateway WebSocket. + Security reminder: pairing a macOS node allows `system.run` on that machine. Only + pair devices you trust, and review [Security](/gateway/security). -Security reminder: pairing a macOS node allows `system.run` on that machine. Only -pair devices you trust, and review [Security](/gateway/security). + Docs: [Nodes](/nodes), [Gateway protocol](/gateway/protocol), [macOS remote mode](/platforms/mac/remote), [Security](/gateway/security). -Docs: [Nodes](/nodes), [Gateway protocol](/gateway/protocol), [macOS remote mode](/platforms/mac/remote), [Security](/gateway/security). + -### Tailscale is connected but I get no replies What now + + Check the basics: -Check the basics: + - Gateway is running: `openclaw gateway status` + - Gateway health: `openclaw status` + - Channel health: `openclaw channels status` -- Gateway is running: `openclaw gateway status` -- Gateway health: `openclaw status` -- Channel health: `openclaw channels status` + Then verify auth and routing: -Then verify auth and routing: + - If you use Tailscale Serve, make sure `gateway.auth.allowTailscale` is set correctly. + - If you connect via SSH tunnel, confirm the local tunnel is up and points at the right port. + - Confirm your allowlists (DM or group) include your account. -- If you use Tailscale Serve, make sure `gateway.auth.allowTailscale` is set correctly. -- If you connect via SSH tunnel, confirm the local tunnel is up and points at the right port. -- Confirm your allowlists (DM or group) include your account. + Docs: [Tailscale](/gateway/tailscale), [Remote access](/gateway/remote), [Channels](/channels). -Docs: [Tailscale](/gateway/tailscale), [Remote access](/gateway/remote), [Channels](/channels). + -### Can two OpenClaw instances talk to each other local VPS + + Yes. There is no built-in "bot-to-bot" bridge, but you can wire it up in a few + reliable ways: -Yes. There is no built-in "bot-to-bot" bridge, but you can wire it up in a few -reliable ways: + **Simplest:** use a normal chat channel both bots can access (Telegram/Slack/WhatsApp). + Have Bot A send a message to Bot B, then let Bot B reply as usual. -**Simplest:** use a normal chat channel both bots can access (Telegram/Slack/WhatsApp). -Have Bot A send a message to Bot B, then let Bot B reply as usual. + **CLI bridge (generic):** run a script that calls the other Gateway with + `openclaw agent --message ... --deliver`, targeting a chat where the other bot + listens. If one bot is on a remote VPS, point your CLI at that remote Gateway + via SSH/Tailscale (see [Remote access](/gateway/remote)). -**CLI bridge (generic):** run a script that calls the other Gateway with -`openclaw agent --message ... --deliver`, targeting a chat where the other bot -listens. If one bot is on a remote VPS, point your CLI at that remote Gateway -via SSH/Tailscale (see [Remote access](/gateway/remote)). + Example pattern (run from a machine that can reach the target Gateway): -Example pattern (run from a machine that can reach the target Gateway): + ```bash + openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to + ``` -```bash -openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to -``` + Tip: add a guardrail so the two bots do not loop endlessly (mention-only, channel + allowlists, or a "do not reply to bot messages" rule). -Tip: add a guardrail so the two bots do not loop endlessly (mention-only, channel -allowlists, or a "do not reply to bot messages" rule). + Docs: [Remote access](/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/tools/agent-send). -Docs: [Remote access](/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/tools/agent-send). + -### Do I need separate VPSes for multiple agents + + No. One Gateway can host multiple agents, each with its own workspace, model defaults, + and routing. That is the normal setup and it is much cheaper and simpler than running + one VPS per agent. -No. One Gateway can host multiple agents, each with its own workspace, model defaults, -and routing. That is the normal setup and it is much cheaper and simpler than running -one VPS per agent. + Use separate VPSes only when you need hard isolation (security boundaries) or very + different configs that you do not want to share. Otherwise, keep one Gateway and + use multiple agents or sub-agents. -Use separate VPSes only when you need hard isolation (security boundaries) or very -different configs that you do not want to share. Otherwise, keep one Gateway and -use multiple agents or sub-agents. + -### Is there a benefit to using a node on my personal laptop instead of SSH from a VPS + + Yes - nodes are the first-class way to reach your laptop from a remote Gateway, and they + unlock more than shell access. The Gateway runs on macOS/Linux (Windows via WSL2) and is + lightweight (a small VPS or Raspberry Pi-class box is fine; 4 GB RAM is plenty), so a common + setup is an always-on host plus your laptop as a node. -Yes - nodes are the first-class way to reach your laptop from a remote Gateway, and they -unlock more than shell access. The Gateway runs on macOS/Linux (Windows via WSL2) and is -lightweight (a small VPS or Raspberry Pi-class box is fine; 4 GB RAM is plenty), so a common -setup is an always-on host plus your laptop as a node. + - **No inbound SSH required.** Nodes connect out to the Gateway WebSocket and use device pairing. + - **Safer execution controls.** `system.run` is gated by node allowlists/approvals on that laptop. + - **More device tools.** Nodes expose `canvas`, `camera`, and `screen` in addition to `system.run`. + - **Local browser automation.** Keep the Gateway on a VPS, but run Chrome locally through a node host on the laptop, or attach to local Chrome on the host via Chrome MCP. -- **No inbound SSH required.** Nodes connect out to the Gateway WebSocket and use device pairing. -- **Safer execution controls.** `system.run` is gated by node allowlists/approvals on that laptop. -- **More device tools.** Nodes expose `canvas`, `camera`, and `screen` in addition to `system.run`. -- **Local browser automation.** Keep the Gateway on a VPS, but run Chrome locally through a node host on the laptop, or attach to local Chrome on the host via Chrome MCP. + SSH is fine for ad-hoc shell access, but nodes are simpler for ongoing agent workflows and + device automation. -SSH is fine for ad-hoc shell access, but nodes are simpler for ongoing agent workflows and -device automation. + Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Browser](/tools/browser). -Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Browser](/tools/browser). + -### Should I install on a second laptop or just add a node + + No. Only **one gateway** should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)). Nodes are peripherals that connect + to the gateway (iOS/Android nodes, or macOS "node mode" in the menubar app). For headless node + hosts and CLI control, see [Node host CLI](/cli/node). -If you only need **local tools** (screen/camera/exec) on the second laptop, add it as a -**node**. That keeps a single Gateway and avoids duplicated config. Local node tools are -currently macOS-only, but we plan to extend them to other OSes. + A full restart is required for `gateway`, `discovery`, and `canvasHost` changes. -Install a second Gateway only when you need **hard isolation** or two fully separate bots. + -Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Multiple gateways](/gateway/multiple-gateways). + + Yes. `config.apply` validates + writes the full config and restarts the Gateway as part of the operation. + -### Do nodes run a gateway service + + ```json5 + { + agents: { defaults: { workspace: "~/.openclaw/workspace" } }, + channels: { whatsapp: { allowFrom: ["+15555550123"] } }, + } + ``` -No. Only **one gateway** should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)). Nodes are peripherals that connect -to the gateway (iOS/Android nodes, or macOS "node mode" in the menubar app). For headless node -hosts and CLI control, see [Node host CLI](/cli/node). + This sets your workspace and restricts who can trigger the bot. -A full restart is required for `gateway`, `discovery`, and `canvasHost` changes. + -### Is there an API RPC way to apply config + + Minimal steps: -Yes. `config.apply` validates + writes the full config and restarts the Gateway as part of the operation. + 1. **Install + login on the VPS** -### configapply wiped my config How do I recover and avoid this + ```bash + curl -fsSL https://tailscale.com/install.sh | sh + sudo tailscale up + ``` -`config.apply` replaces the **entire config**. If you send a partial object, everything -else is removed. + 2. **Install + login on your Mac** + - Use the Tailscale app and sign in to the same tailnet. + 3. **Enable MagicDNS (recommended)** + - In the Tailscale admin console, enable MagicDNS so the VPS has a stable name. + 4. **Use the tailnet hostname** + - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` + - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` -Recover: + If you want the Control UI without SSH, use Tailscale Serve on the VPS: -- Restore from backup (git or a copied `~/.openclaw/openclaw.json`). -- If you have no backup, re-run `openclaw doctor` and reconfigure channels/models. -- If this was unexpected, file a bug and include your last known config or any backup. -- A local coding agent can often reconstruct a working config from logs or history. + ```bash + openclaw gateway --tailscale serve + ``` -Avoid it: + This keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See [Tailscale](/gateway/tailscale). -- Use `openclaw config set` for small changes. -- Use `openclaw configure` for interactive edits. + -Docs: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/gateway/doctor). + + Serve exposes the **Gateway Control UI + WS**. Nodes connect over the same Gateway WS endpoint. -### Minimal sane config for a first install + Recommended setup: -```json5 -{ - agents: { defaults: { workspace: "~/.openclaw/workspace" } }, - channels: { whatsapp: { allowFrom: ["+15555550123"] } }, -} -``` + 1. **Make sure the VPS + Mac are on the same tailnet**. + 2. **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname). + The app will tunnel the Gateway port and connect as a node. + 3. **Approve the node** on the gateway: -This sets your workspace and restricts who can trigger the bot. + ```bash + openclaw devices list + openclaw devices approve + ``` -### How do I set up Tailscale on a VPS and connect from my Mac + Docs: [Gateway protocol](/gateway/protocol), [Discovery](/gateway/discovery), [macOS remote mode](/platforms/mac/remote). -Minimal steps: + -1. **Install + login on the VPS** + + If you only need **local tools** (screen/camera/exec) on the second laptop, add it as a + **node**. That keeps a single Gateway and avoids duplicated config. Local node tools are + currently macOS-only, but we plan to extend them to other OSes. - ```bash - curl -fsSL https://tailscale.com/install.sh | sh - sudo tailscale up - ``` + Install a second Gateway only when you need **hard isolation** or two fully separate bots. -2. **Install + login on your Mac** - - Use the Tailscale app and sign in to the same tailnet. -3. **Enable MagicDNS (recommended)** - - In the Tailscale admin console, enable MagicDNS so the VPS has a stable name. -4. **Use the tailnet hostname** - - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` + Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Multiple gateways](/gateway/multiple-gateways). -If you want the Control UI without SSH, use Tailscale Serve on the VPS: - -```bash -openclaw gateway --tailscale serve -``` - -This keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See [Tailscale](/gateway/tailscale). - -### How do I connect a Mac node to a remote Gateway Tailscale Serve - -Serve exposes the **Gateway Control UI + WS**. Nodes connect over the same Gateway WS endpoint. - -Recommended setup: - -1. **Make sure the VPS + Mac are on the same tailnet**. -2. **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname). - The app will tunnel the Gateway port and connect as a node. -3. **Approve the node** on the gateway: - - ```bash - openclaw devices list - openclaw devices approve - ``` - -Docs: [Gateway protocol](/gateway/protocol), [Discovery](/gateway/discovery), [macOS remote mode](/platforms/mac/remote). + + ## Env vars and .env loading -### How does OpenClaw load environment variables + + + OpenClaw reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads: -OpenClaw reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads: + - `.env` from the current working directory + - a global fallback `.env` from `~/.openclaw/.env` (aka `$OPENCLAW_STATE_DIR/.env`) -- `.env` from the current working directory -- a global fallback `.env` from `~/.openclaw/.env` (aka `$OPENCLAW_STATE_DIR/.env`) + Neither `.env` file overrides existing env vars. -Neither `.env` file overrides existing env vars. + You can also define inline env vars in config (applied only if missing from the process env): -You can also define inline env vars in config (applied only if missing from the process env): + ```json5 + { + env: { + OPENROUTER_API_KEY: "sk-or-...", + vars: { GROQ_API_KEY: "gsk-..." }, + }, + } + ``` -```json5 -{ - env: { - OPENROUTER_API_KEY: "sk-or-...", - vars: { GROQ_API_KEY: "gsk-..." }, - }, -} -``` + See [/environment](/help/environment) for full precedence and sources. -See [/environment](/help/environment) for full precedence and sources. + -### I started the Gateway via the service and my env vars disappeared What now + + Two common fixes: -Two common fixes: + 1. Put the missing keys in `~/.openclaw/.env` so they're picked up even when the service doesn't inherit your shell env. + 2. Enable shell import (opt-in convenience): -1. Put the missing keys in `~/.openclaw/.env` so they're picked up even when the service doesn't inherit your shell env. -2. Enable shell import (opt-in convenience): + ```json5 + { + env: { + shellEnv: { + enabled: true, + timeoutMs: 15000, + }, + }, + } + ``` -```json5 -{ - env: { - shellEnv: { - enabled: true, - timeoutMs: 15000, - }, - }, -} -``` + This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents: + `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. -This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents: -`OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. + -### I set COPILOTGITHUBTOKEN but models status shows Shell env off Why + + `openclaw models status` reports whether **shell env import** is enabled. "Shell env: off" + does **not** mean your env vars are missing - it just means OpenClaw won't load + your login shell automatically. -`openclaw models status` reports whether **shell env import** is enabled. "Shell env: off" -does **not** mean your env vars are missing - it just means OpenClaw won't load -your login shell automatically. + If the Gateway runs as a service (launchd/systemd), it won't inherit your shell + environment. Fix by doing one of these: -If the Gateway runs as a service (launchd/systemd), it won't inherit your shell -environment. Fix by doing one of these: + 1. Put the token in `~/.openclaw/.env`: -1. Put the token in `~/.openclaw/.env`: + ``` + COPILOT_GITHUB_TOKEN=... + ``` - ``` - COPILOT_GITHUB_TOKEN=... - ``` + 2. Or enable shell import (`env.shellEnv.enabled: true`). + 3. Or add it to your config `env` block (applies only if missing). -2. Or enable shell import (`env.shellEnv.enabled: true`). -3. Or add it to your config `env` block (applies only if missing). + Then restart the gateway and recheck: -Then restart the gateway and recheck: + ```bash + openclaw models status + ``` -```bash -openclaw models status -``` + Copilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`). + See [/concepts/model-providers](/concepts/model-providers) and [/environment](/help/environment). -Copilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`). -See [/concepts/model-providers](/concepts/model-providers) and [/environment](/help/environment). + + ## Sessions and multiple chats -### How do I start a fresh conversation + + + Send `/new` or `/reset` as a standalone message. See [Session management](/concepts/session). + -Send `/new` or `/reset` as a standalone message. See [Session management](/concepts/session). + + Yes. Sessions expire after `session.idleMinutes` (default **60**). The **next** + message starts a fresh session id for that chat key. This does not delete + transcripts - it just starts a new session. -### Do sessions reset automatically if I never send new - -Yes. Sessions expire after `session.idleMinutes` (default **60**). The **next** -message starts a fresh session id for that chat key. This does not delete -transcripts - it just starts a new session. - -```json5 -{ - session: { - idleMinutes: 240, - }, -} -``` - -### Is there a way to make a team of OpenClaw instances one CEO and many agents - -Yes, via **multi-agent routing** and **sub-agents**. You can create one coordinator -agent and several worker agents with their own workspaces and models. - -That said, this is best seen as a **fun experiment**. It is token heavy and often -less efficient than using one bot with separate sessions. The typical model we -envision is one bot you talk to, with different sessions for parallel work. That -bot can also spawn sub-agents when needed. - -Docs: [Multi-agent routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [Agents CLI](/cli/agents). - -### Why did context get truncated midtask How do I prevent it - -Session context is limited by the model window. Long chats, large tool outputs, or many -files can trigger compaction or truncation. - -What helps: - -- Ask the bot to summarize the current state and write it to a file. -- Use `/compact` before long tasks, and `/new` when switching topics. -- Keep important context in the workspace and ask the bot to read it back. -- Use sub-agents for long or parallel work so the main chat stays smaller. -- Pick a model with a larger context window if this happens often. - -### How do I completely reset OpenClaw but keep it installed - -Use the reset command: - -```bash -openclaw reset -``` - -Non-interactive full reset: - -```bash -openclaw reset --scope full --yes --non-interactive -``` - -Then re-run setup: - -```bash -openclaw onboard --install-daemon -``` - -Notes: - -- Onboarding also offers **Reset** if it sees an existing config. See [Onboarding (CLI)](/start/wizard). -- If you used profiles (`--profile` / `OPENCLAW_PROFILE`), reset each state dir (defaults are `~/.openclaw-`). -- Dev reset: `openclaw gateway --dev --reset` (dev-only; wipes dev config + credentials + sessions + workspace). - -### Im getting context too large errors how do I reset or compact - -Use one of these: - -- **Compact** (keeps the conversation but summarizes older turns): - - ``` - /compact - ``` - - or `/compact ` to guide the summary. - -- **Reset** (fresh session ID for the same chat key): - - ``` - /new - /reset - ``` - -If it keeps happening: - -- Enable or tune **session pruning** (`agents.defaults.contextPruning`) to trim old tool output. -- Use a model with a larger context window. - -Docs: [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning), [Session management](/concepts/session). - -### Why am I seeing "LLM request rejected: messages.content.tool_use.input field required"? - -This is a provider validation error: the model emitted a `tool_use` block without the required -`input`. It usually means the session history is stale or corrupted (often after long threads -or a tool/schema change). - -Fix: start a fresh session with `/new` (standalone message). - -### Why am I getting heartbeat messages every 30 minutes - -Heartbeats run every **30m** by default. Tune or disable them: - -```json5 -{ - agents: { - defaults: { - heartbeat: { - every: "2h", // or "0m" to disable + ```json5 + { + session: { + idleMinutes: 240, }, - }, - }, -} -``` + } + ``` -If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown -headers like `# Heading`), OpenClaw skips the heartbeat run to save API calls. -If the file is missing, the heartbeat still runs and the model decides what to do. + -Per-agent overrides use `agents.list[].heartbeat`. Docs: [Heartbeat](/gateway/heartbeat). + + Yes, via **multi-agent routing** and **sub-agents**. You can create one coordinator + agent and several worker agents with their own workspaces and models. -### Do I need to add a bot account to a WhatsApp group + That said, this is best seen as a **fun experiment**. It is token heavy and often + less efficient than using one bot with separate sessions. The typical model we + envision is one bot you talk to, with different sessions for parallel work. That + bot can also spawn sub-agents when needed. -No. OpenClaw runs on **your own account**, so if you're in the group, OpenClaw can see it. -By default, group replies are blocked until you allow senders (`groupPolicy: "allowlist"`). + Docs: [Multi-agent routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [Agents CLI](/cli/agents). -If you want only **you** to be able to trigger group replies: + -```json5 -{ - channels: { - whatsapp: { - groupPolicy: "allowlist", - groupAllowFrom: ["+15551234567"], - }, - }, -} -``` + + Session context is limited by the model window. Long chats, large tool outputs, or many + files can trigger compaction or truncation. -### How do I get the JID of a WhatsApp group + What helps: -Option 1 (fastest): tail logs and send a test message in the group: + - Ask the bot to summarize the current state and write it to a file. + - Use `/compact` before long tasks, and `/new` when switching topics. + - Keep important context in the workspace and ask the bot to read it back. + - Use sub-agents for long or parallel work so the main chat stays smaller. + - Pick a model with a larger context window if this happens often. -```bash -openclaw logs --follow --json -``` + -Look for `chatId` (or `from`) ending in `@g.us`, like: -`1234567890-1234567890@g.us`. + + Use the reset command: -Option 2 (if already configured/allowlisted): list groups from config: + ```bash + openclaw reset + ``` -```bash -openclaw directory groups list --channel whatsapp -``` + Non-interactive full reset: -Docs: [WhatsApp](/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs). + ```bash + openclaw reset --scope full --yes --non-interactive + ``` -### Why does OpenClaw not reply in a group + Then re-run setup: -Two common causes: + ```bash + openclaw onboard --install-daemon + ``` -- Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`). -- You configured `channels.whatsapp.groups` without `"*"` and the group isn't allowlisted. + Notes: -See [Groups](/channels/groups) and [Group messages](/channels/group-messages). + - Onboarding also offers **Reset** if it sees an existing config. See [Onboarding (CLI)](/start/wizard). + - If you used profiles (`--profile` / `OPENCLAW_PROFILE`), reset each state dir (defaults are `~/.openclaw-`). + - Dev reset: `openclaw gateway --dev --reset` (dev-only; wipes dev config + credentials + sessions + workspace). -### Do groups/threads share context with DMs + -Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/channels/groups) and [Group messages](/channels/group-messages). + + Use one of these: -### How many workspaces and agents can I create + - **Compact** (keeps the conversation but summarizes older turns): -No hard limits. Dozens (even hundreds) are fine, but watch for: + ``` + /compact + ``` -- **Disk growth:** sessions + transcripts live under `~/.openclaw/agents//sessions/`. -- **Token cost:** more agents means more concurrent model usage. -- **Ops overhead:** per-agent auth profiles, workspaces, and channel routing. + or `/compact ` to guide the summary. -Tips: + - **Reset** (fresh session ID for the same chat key): -- Keep one **active** workspace per agent (`agents.defaults.workspace`). -- Prune old sessions (delete JSONL or store entries) if disk grows. -- Use `openclaw doctor` to spot stray workspaces and profile mismatches. + ``` + /new + /reset + ``` -### Can I run multiple bots or chats at the same time Slack and how should I set that up + If it keeps happening: -Yes. Use **Multi-Agent Routing** to run multiple isolated agents and route inbound messages by -channel/account/peer. Slack is supported as a channel and can be bound to specific agents. + - Enable or tune **session pruning** (`agents.defaults.contextPruning`) to trim old tool output. + - Use a model with a larger context window. -Browser access is powerful but not "do anything a human can" - anti-bot, CAPTCHAs, and MFA can -still block automation. For the most reliable browser control, use local Chrome MCP on the host, -or use CDP on the machine that actually runs the browser. + Docs: [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning), [Session management](/concepts/session). -Best-practice setup: + -- Always-on Gateway host (VPS/Mac mini). -- One agent per role (bindings). -- Slack channel(s) bound to those agents. -- Local browser via Chrome MCP or a node when needed. + + This is a provider validation error: the model emitted a `tool_use` block without the required + `input`. It usually means the session history is stale or corrupted (often after long threads + or a tool/schema change). -Docs: [Multi-Agent Routing](/concepts/multi-agent), [Slack](/channels/slack), -[Browser](/tools/browser), [Nodes](/nodes). + Fix: start a fresh session with `/new` (standalone message). + + + + + Heartbeats run every **30m** by default. Tune or disable them: + + ```json5 + { + agents: { + defaults: { + heartbeat: { + every: "2h", // or "0m" to disable + }, + }, + }, + } + ``` + + If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown + headers like `# Heading`), OpenClaw skips the heartbeat run to save API calls. + If the file is missing, the heartbeat still runs and the model decides what to do. + + Per-agent overrides use `agents.list[].heartbeat`. Docs: [Heartbeat](/gateway/heartbeat). + + + + + No. OpenClaw runs on **your own account**, so if you're in the group, OpenClaw can see it. + By default, group replies are blocked until you allow senders (`groupPolicy: "allowlist"`). + + If you want only **you** to be able to trigger group replies: + + ```json5 + { + channels: { + whatsapp: { + groupPolicy: "allowlist", + groupAllowFrom: ["+15551234567"], + }, + }, + } + ``` + + + + + Option 1 (fastest): tail logs and send a test message in the group: + + ```bash + openclaw logs --follow --json + ``` + + Look for `chatId` (or `from`) ending in `@g.us`, like: + `1234567890-1234567890@g.us`. + + Option 2 (if already configured/allowlisted): list groups from config: + + ```bash + openclaw directory groups list --channel whatsapp + ``` + + Docs: [WhatsApp](/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs). + + + + + Two common causes: + + - Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`). + - You configured `channels.whatsapp.groups` without `"*"` and the group isn't allowlisted. + + See [Groups](/channels/groups) and [Group messages](/channels/group-messages). + + + + + Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/channels/groups) and [Group messages](/channels/group-messages). + + + + No hard limits. Dozens (even hundreds) are fine, but watch for: + + - **Disk growth:** sessions + transcripts live under `~/.openclaw/agents//sessions/`. + - **Token cost:** more agents means more concurrent model usage. + - **Ops overhead:** per-agent auth profiles, workspaces, and channel routing. + + Tips: + + - Keep one **active** workspace per agent (`agents.defaults.workspace`). + - Prune old sessions (delete JSONL or store entries) if disk grows. + - Use `openclaw doctor` to spot stray workspaces and profile mismatches. + + + + + Yes. Use **Multi-Agent Routing** to run multiple isolated agents and route inbound messages by + channel/account/peer. Slack is supported as a channel and can be bound to specific agents. + + Browser access is powerful but not "do anything a human can" - anti-bot, CAPTCHAs, and MFA can + still block automation. For the most reliable browser control, use local Chrome MCP on the host, + or use CDP on the machine that actually runs the browser. + + Best-practice setup: + + - Always-on Gateway host (VPS/Mac mini). + - One agent per role (bindings). + - Slack channel(s) bound to those agents. + - Local browser via Chrome MCP or a node when needed. + + Docs: [Multi-Agent Routing](/concepts/multi-agent), [Slack](/channels/slack), + [Browser](/tools/browser), [Nodes](/nodes). + + + ## Models: defaults, selection, aliases, switching -### What is the default model + + + OpenClaw's default model is whatever you set as: -OpenClaw's default model is whatever you set as: + ``` + agents.defaults.model.primary + ``` -``` -agents.defaults.model.primary -``` + Models are referenced as `provider/model` (example: `anthropic/claude-opus-4-6`). If you omit the provider, OpenClaw currently assumes `anthropic` as a temporary deprecation fallback - but you should still **explicitly** set `provider/model`. -Models are referenced as `provider/model` (example: `anthropic/claude-opus-4-6`). If you omit the provider, OpenClaw currently assumes `anthropic` as a temporary deprecation fallback - but you should still **explicitly** set `provider/model`. + -### What model do you recommend + + **Recommended default:** use the strongest latest-generation model available in your provider stack. + **For tool-enabled or untrusted-input agents:** prioritize model strength over cost. + **For routine/low-stakes chat:** use cheaper fallback models and route by agent role. -**Recommended default:** use the strongest latest-generation model available in your provider stack. -**For tool-enabled or untrusted-input agents:** prioritize model strength over cost. -**For routine/low-stakes chat:** use cheaper fallback models and route by agent role. + MiniMax M2.5 has its own docs: [MiniMax](/providers/minimax) and + [Local models](/gateway/local-models). -MiniMax M2.5 has its own docs: [MiniMax](/providers/minimax) and -[Local models](/gateway/local-models). + Rule of thumb: use the **best model you can afford** for high-stakes work, and a cheaper + model for routine chat or summaries. You can route models per agent and use sub-agents to + parallelize long tasks (each sub-agent consumes tokens). See [Models](/concepts/models) and + [Sub-agents](/tools/subagents). -Rule of thumb: use the **best model you can afford** for high-stakes work, and a cheaper -model for routine chat or summaries. You can route models per agent and use sub-agents to -parallelize long tasks (each sub-agent consumes tokens). See [Models](/concepts/models) and -[Sub-agents](/tools/subagents). + Strong warning: weaker/over-quantized models are more vulnerable to prompt + injection and unsafe behavior. See [Security](/gateway/security). -Strong warning: weaker/over-quantized models are more vulnerable to prompt -injection and unsafe behavior. See [Security](/gateway/security). + More context: [Models](/concepts/models). -More context: [Models](/concepts/models). + -### Can I use selfhosted models llamacpp vLLM Ollama + + Use **model commands** or edit only the **model** fields. Avoid full config replaces. -Yes. Ollama is the easiest path for local models. + Safe options: -Quickest setup: + - `/model` in chat (quick, per-session) + - `openclaw models set ...` (updates just model config) + - `openclaw configure --section model` (interactive) + - edit `agents.defaults.model` in `~/.openclaw/openclaw.json` -1. Install Ollama from `https://ollama.com/download` -2. Pull a local model such as `ollama pull glm-4.7-flash` -3. If you want Ollama Cloud too, run `ollama signin` -4. Run `openclaw onboard` and choose `Ollama` -5. Pick `Local` or `Cloud + Local` + Avoid `config.apply` with a partial object unless you intend to replace the whole config. + If you did overwrite config, restore from backup or re-run `openclaw doctor` to repair. -Notes: + Docs: [Models](/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/gateway/doctor). -- `Cloud + Local` gives you Ollama Cloud models plus your local Ollama models -- cloud models such as `kimi-k2.5:cloud` do not need a local pull -- for manual switching, use `openclaw models list` and `openclaw models set ollama/` + -Security note: smaller or heavily quantized models are more vulnerable to prompt -injection. We strongly recommend **large models** for any bot that can use tools. -If you still want small models, enable sandboxing and strict tool allowlists. + + Yes. Ollama is the easiest path for local models. -Docs: [Ollama](/providers/ollama), [Local models](/gateway/local-models), -[Model providers](/concepts/model-providers), [Security](/gateway/security), -[Sandboxing](/gateway/sandboxing). + Quickest setup: -### How do I switch models without wiping my config + 1. Install Ollama from `https://ollama.com/download` + 2. Pull a local model such as `ollama pull glm-4.7-flash` + 3. If you want Ollama Cloud too, run `ollama signin` + 4. Run `openclaw onboard` and choose `Ollama` + 5. Pick `Local` or `Cloud + Local` -Use **model commands** or edit only the **model** fields. Avoid full config replaces. + Notes: -Safe options: + - `Cloud + Local` gives you Ollama Cloud models plus your local Ollama models + - cloud models such as `kimi-k2.5:cloud` do not need a local pull + - for manual switching, use `openclaw models list` and `openclaw models set ollama/` -- `/model` in chat (quick, per-session) -- `openclaw models set ...` (updates just model config) -- `openclaw configure --section model` (interactive) -- edit `agents.defaults.model` in `~/.openclaw/openclaw.json` + Security note: smaller or heavily quantized models are more vulnerable to prompt + injection. We strongly recommend **large models** for any bot that can use tools. + If you still want small models, enable sandboxing and strict tool allowlists. -Avoid `config.apply` with a partial object unless you intend to replace the whole config. -If you did overwrite config, restore from backup or re-run `openclaw doctor` to repair. + Docs: [Ollama](/providers/ollama), [Local models](/gateway/local-models), + [Model providers](/concepts/model-providers), [Security](/gateway/security), + [Sandboxing](/gateway/sandboxing). -Docs: [Models](/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/gateway/doctor). + -### What do OpenClaw, Flawd, and Krill use for models + + - These deployments can differ and may change over time; there is no fixed provider recommendation. + - Check the current runtime setting on each gateway with `openclaw models status`. + - For security-sensitive/tool-enabled agents, use the strongest latest-generation model available. + -- These deployments can differ and may change over time; there is no fixed provider recommendation. -- Check the current runtime setting on each gateway with `openclaw models status`. -- For security-sensitive/tool-enabled agents, use the strongest latest-generation model available. + + Use the `/model` command as a standalone message: -### How do I switch models on the fly without restarting + ``` + /model sonnet + /model haiku + /model opus + /model gpt + /model gpt-mini + /model gemini + /model gemini-flash + ``` -Use the `/model` command as a standalone message: + You can list available models with `/model`, `/model list`, or `/model status`. -``` -/model sonnet -/model haiku -/model opus -/model gpt -/model gpt-mini -/model gemini -/model gemini-flash -``` + `/model` (and `/model list`) shows a compact, numbered picker. Select by number: -You can list available models with `/model`, `/model list`, or `/model status`. + ``` + /model 3 + ``` -`/model` (and `/model list`) shows a compact, numbered picker. Select by number: + You can also force a specific auth profile for the provider (per session): -``` -/model 3 -``` + ``` + /model opus@anthropic:default + /model opus@anthropic:work + ``` -You can also force a specific auth profile for the provider (per session): + Tip: `/model status` shows which agent is active, which `auth-profiles.json` file is being used, and which auth profile will be tried next. + It also shows the configured provider endpoint (`baseUrl`) and API mode (`api`) when available. -``` -/model opus@anthropic:default -/model opus@anthropic:work -``` + **How do I unpin a profile I set with @profile?** -Tip: `/model status` shows which agent is active, which `auth-profiles.json` file is being used, and which auth profile will be tried next. -It also shows the configured provider endpoint (`baseUrl`) and API mode (`api`) when available. + Re-run `/model` **without** the `@profile` suffix: -**How do I unpin a profile I set with profile** + ``` + /model anthropic/claude-opus-4-6 + ``` -Re-run `/model` **without** the `@profile` suffix: + If you want to return to the default, pick it from `/model` (or send `/model `). + Use `/model status` to confirm which auth profile is active. -``` -/model anthropic/claude-opus-4-6 -``` + -If you want to return to the default, pick it from `/model` (or send `/model `). -Use `/model status` to confirm which auth profile is active. + + Yes. Set one as default and switch as needed: -### Can I use GPT 5.2 for daily tasks and Codex 5.3 for coding + - **Quick switch (per session):** `/model gpt-5.2` for daily tasks, `/model openai-codex/gpt-5.4` for coding with Codex OAuth. + - **Default + switch:** set `agents.defaults.model.primary` to `openai/gpt-5.2`, then switch to `openai-codex/gpt-5.4` when coding (or the other way around). + - **Sub-agents:** route coding tasks to sub-agents with a different default model. -Yes. Set one as default and switch as needed: + See [Models](/concepts/models) and [Slash commands](/tools/slash-commands). -- **Quick switch (per session):** `/model gpt-5.2` for daily tasks, `/model openai-codex/gpt-5.4` for coding with Codex OAuth. -- **Default + switch:** set `agents.defaults.model.primary` to `openai/gpt-5.2`, then switch to `openai-codex/gpt-5.4` when coding (or the other way around). -- **Sub-agents:** route coding tasks to sub-agents with a different default model. + -See [Models](/concepts/models) and [Slash commands](/tools/slash-commands). + + If `agents.defaults.models` is set, it becomes the **allowlist** for `/model` and any + session overrides. Choosing a model that isn't in that list returns: -### Why do I see Model is not allowed and then no reply + ``` + Model "provider/model" is not allowed. Use /model to list available models. + ``` -If `agents.defaults.models` is set, it becomes the **allowlist** for `/model` and any -session overrides. Choosing a model that isn't in that list returns: + That error is returned **instead of** a normal reply. Fix: add the model to + `agents.defaults.models`, remove the allowlist, or pick a model from `/model list`. -``` -Model "provider/model" is not allowed. Use /model to list available models. -``` + -That error is returned **instead of** a normal reply. Fix: add the model to -`agents.defaults.models`, remove the allowlist, or pick a model from `/model list`. + + This means the **provider isn't configured** (no MiniMax provider config or auth + profile was found), so the model can't be resolved. A fix for this detection is + in **2026.1.12** (unreleased at the time of writing). -### Why do I see Unknown model minimaxMiniMaxM25 + Fix checklist: -This means the **provider isn't configured** (no MiniMax provider config or auth -profile was found), so the model can't be resolved. A fix for this detection is -in **2026.1.12** (unreleased at the time of writing). + 1. Upgrade to **2026.1.12** (or run from source `main`), then restart the gateway. + 2. Make sure MiniMax is configured (wizard or JSON), or that a MiniMax API key + exists in env/auth profiles so the provider can be injected. + 3. Use the exact model id (case-sensitive): `minimax/MiniMax-M2.5` or + `minimax/MiniMax-M2.5-highspeed`. + 4. Run: -Fix checklist: + ```bash + openclaw models list + ``` -1. Upgrade to **2026.1.12** (or run from source `main`), then restart the gateway. -2. Make sure MiniMax is configured (wizard or JSON), or that a MiniMax API key - exists in env/auth profiles so the provider can be injected. -3. Use the exact model id (case-sensitive): `minimax/MiniMax-M2.5` or - `minimax/MiniMax-M2.5-highspeed`. -4. Run: + and pick from the list (or `/model list` in chat). - ```bash - openclaw models list - ``` + See [MiniMax](/providers/minimax) and [Models](/concepts/models). - and pick from the list (or `/model list` in chat). + -See [MiniMax](/providers/minimax) and [Models](/concepts/models). + + Yes. Use **MiniMax as the default** and switch models **per session** when needed. + Fallbacks are for **errors**, not "hard tasks," so use `/model` or a separate agent. -### Can I use MiniMax as my default and OpenAI for complex tasks + **Option A: switch per session** -Yes. Use **MiniMax as the default** and switch models **per session** when needed. -Fallbacks are for **errors**, not "hard tasks," so use `/model` or a separate agent. - -**Option A: switch per session** - -```json5 -{ - env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." }, - agents: { - defaults: { - model: { primary: "minimax/MiniMax-M2.5" }, - models: { - "minimax/MiniMax-M2.5": { alias: "minimax" }, - "openai/gpt-5.2": { alias: "gpt" }, + ```json5 + { + env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." }, + agents: { + defaults: { + model: { primary: "minimax/MiniMax-M2.5" }, + models: { + "minimax/MiniMax-M2.5": { alias: "minimax" }, + "openai/gpt-5.2": { alias: "gpt" }, + }, + }, }, - }, - }, -} -``` + } + ``` -Then: + Then: -``` -/model gpt -``` + ``` + /model gpt + ``` -**Option B: separate agents** + **Option B: separate agents** -- Agent A default: MiniMax -- Agent B default: OpenAI -- Route by agent or use `/agent` to switch + - Agent A default: MiniMax + - Agent B default: OpenAI + - Route by agent or use `/agent` to switch -Docs: [Models](/concepts/models), [Multi-Agent Routing](/concepts/multi-agent), [MiniMax](/providers/minimax), [OpenAI](/providers/openai). + Docs: [Models](/concepts/models), [Multi-Agent Routing](/concepts/multi-agent), [MiniMax](/providers/minimax), [OpenAI](/providers/openai). -### Are opus sonnet gpt builtin shortcuts + -Yes. OpenClaw ships a few default shorthands (only applied when the model exists in `agents.defaults.models`): + + Yes. OpenClaw ships a few default shorthands (only applied when the model exists in `agents.defaults.models`): -- `opus` → `anthropic/claude-opus-4-6` -- `sonnet` → `anthropic/claude-sonnet-4-6` -- `gpt` → `openai/gpt-5.4` -- `gpt-mini` → `openai/gpt-5-mini` -- `gemini` → `google/gemini-3.1-pro-preview` -- `gemini-flash` → `google/gemini-3-flash-preview` -- `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` + - `opus` → `anthropic/claude-opus-4-6` + - `sonnet` → `anthropic/claude-sonnet-4-6` + - `gpt` → `openai/gpt-5.4` + - `gpt-mini` → `openai/gpt-5-mini` + - `gemini` → `google/gemini-3.1-pro-preview` + - `gemini-flash` → `google/gemini-3-flash-preview` + - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` -If you set your own alias with the same name, your value wins. + If you set your own alias with the same name, your value wins. -### How do I defineoverride model shortcuts aliases + -Aliases come from `agents.defaults.models..alias`. Example: + + Aliases come from `agents.defaults.models..alias`. Example: -```json5 -{ - agents: { - defaults: { - model: { primary: "anthropic/claude-opus-4-6" }, - models: { - "anthropic/claude-opus-4-6": { alias: "opus" }, - "anthropic/claude-sonnet-4-6": { alias: "sonnet" }, - "anthropic/claude-haiku-4-5": { alias: "haiku" }, + ```json5 + { + agents: { + defaults: { + model: { primary: "anthropic/claude-opus-4-6" }, + models: { + "anthropic/claude-opus-4-6": { alias: "opus" }, + "anthropic/claude-sonnet-4-6": { alias: "sonnet" }, + "anthropic/claude-haiku-4-5": { alias: "haiku" }, + }, + }, }, - }, - }, -} -``` + } + ``` -Then `/model sonnet` (or `/` when supported) resolves to that model ID. + Then `/model sonnet` (or `/` when supported) resolves to that model ID. -### How do I add models from other providers like OpenRouter or ZAI + -OpenRouter (pay-per-token; many models): + + OpenRouter (pay-per-token; many models): -```json5 -{ - agents: { - defaults: { - model: { primary: "openrouter/anthropic/claude-sonnet-4-6" }, - models: { "openrouter/anthropic/claude-sonnet-4-6": {} }, - }, - }, - env: { OPENROUTER_API_KEY: "sk-or-..." }, -} -``` + ```json5 + { + agents: { + defaults: { + model: { primary: "openrouter/anthropic/claude-sonnet-4-6" }, + models: { "openrouter/anthropic/claude-sonnet-4-6": {} }, + }, + }, + env: { OPENROUTER_API_KEY: "sk-or-..." }, + } + ``` -Z.AI (GLM models): + Z.AI (GLM models): -```json5 -{ - agents: { - defaults: { - model: { primary: "zai/glm-5" }, - models: { "zai/glm-5": {} }, - }, - }, - env: { ZAI_API_KEY: "..." }, -} -``` + ```json5 + { + agents: { + defaults: { + model: { primary: "zai/glm-5" }, + models: { "zai/glm-5": {} }, + }, + }, + env: { ZAI_API_KEY: "..." }, + } + ``` -If you reference a provider/model but the required provider key is missing, you'll get a runtime auth error (e.g. `No API key found for provider "zai"`). + If you reference a provider/model but the required provider key is missing, you'll get a runtime auth error (e.g. `No API key found for provider "zai"`). -**No API key found for provider after adding a new agent** + **No API key found for provider after adding a new agent** -This usually means the **new agent** has an empty auth store. Auth is per-agent and -stored in: + This usually means the **new agent** has an empty auth store. Auth is per-agent and + stored in: -``` -~/.openclaw/agents//agent/auth-profiles.json -``` + ``` + ~/.openclaw/agents//agent/auth-profiles.json + ``` -Fix options: + Fix options: -- Run `openclaw agents add ` and configure auth during the wizard. -- Or copy `auth-profiles.json` from the main agent's `agentDir` into the new agent's `agentDir`. + - Run `openclaw agents add ` and configure auth during the wizard. + - Or copy `auth-profiles.json` from the main agent's `agentDir` into the new agent's `agentDir`. -Do **not** reuse `agentDir` across agents; it causes auth/session collisions. + Do **not** reuse `agentDir` across agents; it causes auth/session collisions. + + + ## Model failover and "All models failed" -### How does failover work + + + Failover happens in two stages: -Failover happens in two stages: + 1. **Auth profile rotation** within the same provider. + 2. **Model fallback** to the next model in `agents.defaults.model.fallbacks`. -1. **Auth profile rotation** within the same provider. -2. **Model fallback** to the next model in `agents.defaults.model.fallbacks`. + Cooldowns apply to failing profiles (exponential backoff), so OpenClaw can keep responding even when a provider is rate-limited or temporarily failing. -Cooldowns apply to failing profiles (exponential backoff), so OpenClaw can keep responding even when a provider is rate-limited or temporarily failing. + -### What does this error mean + + It means the system attempted to use the auth profile ID `anthropic:default`, but could not find credentials for it in the expected auth store. -``` -No credentials found for profile "anthropic:default" -``` + **Fix checklist:** -It means the system attempted to use the auth profile ID `anthropic:default`, but could not find credentials for it in the expected auth store. + - **Confirm where auth profiles live** (new vs legacy paths) + - Current: `~/.openclaw/agents//agent/auth-profiles.json` + - Legacy: `~/.openclaw/agent/*` (migrated by `openclaw doctor`) + - **Confirm your env var is loaded by the Gateway** + - If you set `ANTHROPIC_API_KEY` in your shell but run the Gateway via systemd/launchd, it may not inherit it. Put it in `~/.openclaw/.env` or enable `env.shellEnv`. + - **Make sure you're editing the correct agent** + - Multi-agent setups mean there can be multiple `auth-profiles.json` files. + - **Sanity-check model/auth status** + - Use `openclaw models status` to see configured models and whether providers are authenticated. -### Fix checklist for No credentials found for profile anthropicdefault + **Fix checklist for "No credentials found for profile anthropic"** -- **Confirm where auth profiles live** (new vs legacy paths) - - Current: `~/.openclaw/agents//agent/auth-profiles.json` - - Legacy: `~/.openclaw/agent/*` (migrated by `openclaw doctor`) -- **Confirm your env var is loaded by the Gateway** - - If you set `ANTHROPIC_API_KEY` in your shell but run the Gateway via systemd/launchd, it may not inherit it. Put it in `~/.openclaw/.env` or enable `env.shellEnv`. -- **Make sure you're editing the correct agent** - - Multi-agent setups mean there can be multiple `auth-profiles.json` files. -- **Sanity-check model/auth status** - - Use `openclaw models status` to see configured models and whether providers are authenticated. + This means the run is pinned to an Anthropic auth profile, but the Gateway + can't find it in its auth store. -**Fix checklist for No credentials found for profile anthropic** + - **Use a setup-token** + - Run `claude setup-token`, then paste it with `openclaw models auth setup-token --provider anthropic`. + - If the token was created on another machine, use `openclaw models auth paste-token --provider anthropic`. + - **If you want to use an API key instead** + - Put `ANTHROPIC_API_KEY` in `~/.openclaw/.env` on the **gateway host**. + - Clear any pinned order that forces a missing profile: -This means the run is pinned to an Anthropic auth profile, but the Gateway -can't find it in its auth store. + ```bash + openclaw models auth order clear --provider anthropic + ``` -- **Use a setup-token** - - Run `claude setup-token`, then paste it with `openclaw models auth setup-token --provider anthropic`. - - If the token was created on another machine, use `openclaw models auth paste-token --provider anthropic`. -- **If you want to use an API key instead** - - Put `ANTHROPIC_API_KEY` in `~/.openclaw/.env` on the **gateway host**. - - Clear any pinned order that forces a missing profile: + - **Confirm you're running commands on the gateway host** + - In remote mode, auth profiles live on the gateway machine, not your laptop. - ```bash - openclaw models auth order clear --provider anthropic - ``` + -- **Confirm you're running commands on the gateway host** - - In remote mode, auth profiles live on the gateway machine, not your laptop. + + If your model config includes Google Gemini as a fallback (or you switched to a Gemini shorthand), OpenClaw will try it during model fallback. If you haven't configured Google credentials, you'll see `No API key found for provider "google"`. -### Why did it also try Google Gemini and fail + Fix: either provide Google auth, or remove/avoid Google models in `agents.defaults.model.fallbacks` / aliases so fallback doesn't route there. -If your model config includes Google Gemini as a fallback (or you switched to a Gemini shorthand), OpenClaw will try it during model fallback. If you haven't configured Google credentials, you'll see `No API key found for provider "google"`. + **LLM request rejected: thinking signature required (Google Antigravity)** -Fix: either provide Google auth, or remove/avoid Google models in `agents.defaults.model.fallbacks` / aliases so fallback doesn't route there. + Cause: the session history contains **thinking blocks without signatures** (often from + an aborted/partial stream). Google Antigravity requires signatures for thinking blocks. -**LLM request rejected message thinking signature required google antigravity** + Fix: OpenClaw now strips unsigned thinking blocks for Google Antigravity Claude. If it still appears, start a **new session** or set `/thinking off` for that agent. -Cause: the session history contains **thinking blocks without signatures** (often from -an aborted/partial stream). Google Antigravity requires signatures for thinking blocks. - -Fix: OpenClaw now strips unsigned thinking blocks for Google Antigravity Claude. If it still appears, start a **new session** or set `/thinking off` for that agent. + + ## Auth profiles: what they are and how to manage them Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-account patterns) -### What is an auth profile + + + An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in: -An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in: + ``` + ~/.openclaw/agents//agent/auth-profiles.json + ``` -``` -~/.openclaw/agents//agent/auth-profiles.json -``` + -### What are typical profile IDs + + OpenClaw uses provider-prefixed IDs like: -OpenClaw uses provider-prefixed IDs like: + - `anthropic:default` (common when no email identity exists) + - `anthropic:` for OAuth identities + - custom IDs you choose (e.g. `anthropic:work`) -- `anthropic:default` (common when no email identity exists) -- `anthropic:` for OAuth identities -- custom IDs you choose (e.g. `anthropic:work`) + -### Can I control which auth profile is tried first + + Yes. Config supports optional metadata for profiles and an ordering per provider (`auth.order.`). This does **not** store secrets; it maps IDs to provider/mode and sets rotation order. -Yes. Config supports optional metadata for profiles and an ordering per provider (`auth.order.`). This does **not** store secrets; it maps IDs to provider/mode and sets rotation order. + OpenClaw may temporarily skip a profile if it's in a short **cooldown** (rate limits/timeouts/auth failures) or a longer **disabled** state (billing/insufficient credits). To inspect this, run `openclaw models status --json` and check `auth.unusableProfiles`. Tuning: `auth.cooldowns.billingBackoffHours*`. -OpenClaw may temporarily skip a profile if it's in a short **cooldown** (rate limits/timeouts/auth failures) or a longer **disabled** state (billing/insufficient credits). To inspect this, run `openclaw models status --json` and check `auth.unusableProfiles`. Tuning: `auth.cooldowns.billingBackoffHours*`. + You can also set a **per-agent** order override (stored in that agent's `auth-profiles.json`) via the CLI: -You can also set a **per-agent** order override (stored in that agent's `auth-profiles.json`) via the CLI: + ```bash + # Defaults to the configured default agent (omit --agent) + openclaw models auth order get --provider anthropic -```bash -# Defaults to the configured default agent (omit --agent) -openclaw models auth order get --provider anthropic + # Lock rotation to a single profile (only try this one) + openclaw models auth order set --provider anthropic anthropic:default -# Lock rotation to a single profile (only try this one) -openclaw models auth order set --provider anthropic anthropic:default + # Or set an explicit order (fallback within provider) + openclaw models auth order set --provider anthropic anthropic:work anthropic:default -# Or set an explicit order (fallback within provider) -openclaw models auth order set --provider anthropic anthropic:work anthropic:default + # Clear override (fall back to config auth.order / round-robin) + openclaw models auth order clear --provider anthropic + ``` -# Clear override (fall back to config auth.order / round-robin) -openclaw models auth order clear --provider anthropic -``` + To target a specific agent: -To target a specific agent: + ```bash + openclaw models auth order set --provider anthropic --agent main anthropic:default + ``` -```bash -openclaw models auth order set --provider anthropic --agent main anthropic:default -``` + -### OAuth vs API key - what is the difference + + OpenClaw supports both: -OpenClaw supports both: + - **OAuth** often leverages subscription access (where applicable). + - **API keys** use pay-per-token billing. -- **OAuth** often leverages subscription access (where applicable). -- **API keys** use pay-per-token billing. + The wizard explicitly supports Anthropic setup-token and OpenAI Codex OAuth and can store API keys for you. -The wizard explicitly supports Anthropic setup-token and OpenAI Codex OAuth and can store API keys for you. + + ## Gateway: ports, "already running", and remote mode -### What port does the Gateway use + + + `gateway.port` controls the single multiplexed port for WebSocket + HTTP (Control UI, hooks, etc.). -`gateway.port` controls the single multiplexed port for WebSocket + HTTP (Control UI, hooks, etc.). + Precedence: -Precedence: + ``` + --port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789 + ``` -``` ---port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789 -``` + -### Why does openclaw gateway status say Runtime running but RPC probe failed + + Because "running" is the **supervisor's** view (launchd/systemd/schtasks). The RPC probe is the CLI actually connecting to the gateway WebSocket and calling `status`. -Because "running" is the **supervisor's** view (launchd/systemd/schtasks). The RPC probe is the CLI actually connecting to the gateway WebSocket and calling `status`. + Use `openclaw gateway status` and trust these lines: -Use `openclaw gateway status` and trust these lines: + - `Probe target:` (the URL the probe actually used) + - `Listening:` (what's actually bound on the port) + - `Last gateway error:` (common root cause when the process is alive but the port isn't listening) -- `Probe target:` (the URL the probe actually used) -- `Listening:` (what's actually bound on the port) -- `Last gateway error:` (common root cause when the process is alive but the port isn't listening) + -### Why does openclaw gateway status show Config cli and Config service different + + You're editing one config file while the service is running another (often a `--profile` / `OPENCLAW_STATE_DIR` mismatch). -You're editing one config file while the service is running another (often a `--profile` / `OPENCLAW_STATE_DIR` mismatch). + Fix: -Fix: + ```bash + openclaw gateway install --force + ``` -```bash -openclaw gateway install --force -``` + Run that from the same `--profile` / environment you want the service to use. -Run that from the same `--profile` / environment you want the service to use. + -### What does another gateway instance is already listening mean + + OpenClaw enforces a runtime lock by binding the WebSocket listener immediately on startup (default `ws://127.0.0.1:18789`). If the bind fails with `EADDRINUSE`, it throws `GatewayLockError` indicating another instance is already listening. -OpenClaw enforces a runtime lock by binding the WebSocket listener immediately on startup (default `ws://127.0.0.1:18789`). If the bind fails with `EADDRINUSE`, it throws `GatewayLockError` indicating another instance is already listening. + Fix: stop the other instance, free the port, or run with `openclaw gateway --port `. -Fix: stop the other instance, free the port, or run with `openclaw gateway --port `. + -### How do I run OpenClaw in remote mode client connects to a Gateway elsewhere + + Set `gateway.mode: "remote"` and point to a remote WebSocket URL, optionally with a token/password: -Set `gateway.mode: "remote"` and point to a remote WebSocket URL, optionally with a token/password: + ```json5 + { + gateway: { + mode: "remote", + remote: { + url: "ws://gateway.tailnet:18789", + token: "your-token", + password: "your-password", + }, + }, + } + ``` -```json5 -{ - gateway: { - mode: "remote", - remote: { - url: "ws://gateway.tailnet:18789", - token: "your-token", - password: "your-password", - }, - }, -} -``` + Notes: -Notes: + - `openclaw gateway` only starts when `gateway.mode` is `local` (or you pass the override flag). + - The macOS app watches the config file and switches modes live when these values change. -- `openclaw gateway` only starts when `gateway.mode` is `local` (or you pass the override flag). -- The macOS app watches the config file and switches modes live when these values change. + -### The Control UI says unauthorized or keeps reconnecting What now + + Your gateway is running with auth enabled (`gateway.auth.*`), but the UI is not sending the matching token/password. -Your gateway is running with auth enabled (`gateway.auth.*`), but the UI is not sending the matching token/password. + Facts (from code): -Facts (from code): + - The Control UI keeps the token in `sessionStorage` for the current browser tab session and selected gateway URL, so same-tab refreshes keep working without restoring long-lived localStorage token persistence. + - On `AUTH_TOKEN_MISMATCH`, trusted clients can attempt one bounded retry with a cached device token when the gateway returns retry hints (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). -- The Control UI keeps the token in `sessionStorage` for the current browser tab session and selected gateway URL, so same-tab refreshes keep working without restoring long-lived localStorage token persistence. -- On `AUTH_TOKEN_MISMATCH`, trusted clients can attempt one bounded retry with a cached device token when the gateway returns retry hints (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). + Fix: -Fix: + - Fastest: `openclaw dashboard` (prints + copies the dashboard URL, tries to open; shows SSH hint if headless). + - If you don't have a token yet: `openclaw doctor --generate-gateway-token`. + - If remote, tunnel first: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`. + - Set `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) on the gateway host. + - In the Control UI settings, paste the same token. + - If mismatch persists after the one retry, rotate/re-approve the paired device token: + - `openclaw devices list` + - `openclaw devices rotate --device --role operator` + - Still stuck? Run `openclaw status --all` and follow [Troubleshooting](/gateway/troubleshooting). See [Dashboard](/web/dashboard) for auth details. -- Fastest: `openclaw dashboard` (prints + copies the dashboard URL, tries to open; shows SSH hint if headless). -- If you don't have a token yet: `openclaw doctor --generate-gateway-token`. -- If remote, tunnel first: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`. -- Set `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) on the gateway host. -- In the Control UI settings, paste the same token. -- If mismatch persists after the one retry, rotate/re-approve the paired device token: - - `openclaw devices list` - - `openclaw devices rotate --device --role operator` -- Still stuck? Run `openclaw status --all` and follow [Troubleshooting](/gateway/troubleshooting). See [Dashboard](/web/dashboard) for auth details. + -### I set gateway.bind tailnet but it cannot bind and nothing listens + + `tailnet` bind picks a Tailscale IP from your network interfaces (100.64.0.0/10). If the machine isn't on Tailscale (or the interface is down), there's nothing to bind to. -`tailnet` bind picks a Tailscale IP from your network interfaces (100.64.0.0/10). If the machine isn't on Tailscale (or the interface is down), there's nothing to bind to. + Fix: -Fix: + - Start Tailscale on that host (so it has a 100.x address), or + - Switch to `gateway.bind: "loopback"` / `"lan"`. -- Start Tailscale on that host (so it has a 100.x address), or -- Switch to `gateway.bind: "loopback"` / `"lan"`. + Note: `tailnet` is explicit. `auto` prefers loopback; use `gateway.bind: "tailnet"` when you want a tailnet-only bind. -Note: `tailnet` is explicit. `auto` prefers loopback; use `gateway.bind: "tailnet"` when you want a tailnet-only bind. + -### Can I run multiple Gateways on the same host + + Usually no - one Gateway can run multiple messaging channels and agents. Use multiple Gateways only when you need redundancy (ex: rescue bot) or hard isolation. -Usually no - one Gateway can run multiple messaging channels and agents. Use multiple Gateways only when you need redundancy (ex: rescue bot) or hard isolation. + Yes, but you must isolate: -Yes, but you must isolate: + - `OPENCLAW_CONFIG_PATH` (per-instance config) + - `OPENCLAW_STATE_DIR` (per-instance state) + - `agents.defaults.workspace` (workspace isolation) + - `gateway.port` (unique ports) -- `OPENCLAW_CONFIG_PATH` (per-instance config) -- `OPENCLAW_STATE_DIR` (per-instance state) -- `agents.defaults.workspace` (workspace isolation) -- `gateway.port` (unique ports) + Quick setup (recommended): -Quick setup (recommended): + - Use `openclaw --profile ...` per instance (auto-creates `~/.openclaw-`). + - Set a unique `gateway.port` in each profile config (or pass `--port` for manual runs). + - Install a per-profile service: `openclaw --profile gateway install`. -- Use `openclaw --profile …` per instance (auto-creates `~/.openclaw-`). -- Set a unique `gateway.port` in each profile config (or pass `--port` for manual runs). -- Install a per-profile service: `openclaw --profile gateway install`. + Profiles also suffix service names (`ai.openclaw.`; legacy `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). + Full guide: [Multiple gateways](/gateway/multiple-gateways). -Profiles also suffix service names (`ai.openclaw.`; legacy `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). -Full guide: [Multiple gateways](/gateway/multiple-gateways). + -### What does invalid handshake code 1008 mean + + The Gateway is a **WebSocket server**, and it expects the very first message to + be a `connect` frame. If it receives anything else, it closes the connection + with **code 1008** (policy violation). -The Gateway is a **WebSocket server**, and it expects the very first message to -be a `connect` frame. If it receives anything else, it closes the connection -with **code 1008** (policy violation). + Common causes: -Common causes: + - You opened the **HTTP** URL in a browser (`http://...`) instead of a WS client. + - You used the wrong port or path. + - A proxy or tunnel stripped auth headers or sent a non-Gateway request. -- You opened the **HTTP** URL in a browser (`http://...`) instead of a WS client. -- You used the wrong port or path. -- A proxy or tunnel stripped auth headers or sent a non-Gateway request. + Quick fixes: -Quick fixes: + 1. Use the WS URL: `ws://:18789` (or `wss://...` if HTTPS). + 2. Don't open the WS port in a normal browser tab. + 3. If auth is on, include the token/password in the `connect` frame. -1. Use the WS URL: `ws://:18789` (or `wss://...` if HTTPS). -2. Don't open the WS port in a normal browser tab. -3. If auth is on, include the token/password in the `connect` frame. + If you're using the CLI or TUI, the URL should look like: -If you're using the CLI or TUI, the URL should look like: + ``` + openclaw tui --url ws://:18789 --token + ``` -``` -openclaw tui --url ws://:18789 --token -``` + Protocol details: [Gateway protocol](/gateway/protocol). -Protocol details: [Gateway protocol](/gateway/protocol). + + ## Logging and debugging -### Where are logs + + + File logs (structured): -File logs (structured): + ``` + /tmp/openclaw/openclaw-YYYY-MM-DD.log + ``` -``` -/tmp/openclaw/openclaw-YYYY-MM-DD.log -``` + You can set a stable path via `logging.file`. File log level is controlled by `logging.level`. Console verbosity is controlled by `--verbose` and `logging.consoleLevel`. -You can set a stable path via `logging.file`. File log level is controlled by `logging.level`. Console verbosity is controlled by `--verbose` and `logging.consoleLevel`. + Fastest log tail: -Fastest log tail: + ```bash + openclaw logs --follow + ``` -```bash -openclaw logs --follow -``` + Service/supervisor logs (when the gateway runs via launchd/systemd): -Service/supervisor logs (when the gateway runs via launchd/systemd): + - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` and `gateway.err.log` (default: `~/.openclaw/logs/...`; profiles use `~/.openclaw-/logs/...`) + - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` + - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` -- macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` and `gateway.err.log` (default: `~/.openclaw/logs/...`; profiles use `~/.openclaw-/logs/...`) -- Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` -- Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` + See [Troubleshooting](/gateway/troubleshooting) for more. -See [Troubleshooting](/gateway/troubleshooting) for more. + -### How do I start/stop/restart the Gateway service + + Use the gateway helpers: -Use the gateway helpers: + ```bash + openclaw gateway status + openclaw gateway restart + ``` -```bash -openclaw gateway status -openclaw gateway restart -``` + If you run the gateway manually, `openclaw gateway --force` can reclaim the port. See [Gateway](/gateway). -If you run the gateway manually, `openclaw gateway --force` can reclaim the port. See [Gateway](/gateway). + -### I closed my terminal on Windows how do I restart OpenClaw + + There are **two Windows install modes**: -There are **two Windows install modes**: + **1) WSL2 (recommended):** the Gateway runs inside Linux. -**1) WSL2 (recommended):** the Gateway runs inside Linux. + Open PowerShell, enter WSL, then restart: -Open PowerShell, enter WSL, then restart: + ```powershell + wsl + openclaw gateway status + openclaw gateway restart + ``` -```powershell -wsl -openclaw gateway status -openclaw gateway restart -``` + If you never installed the service, start it in the foreground: -If you never installed the service, start it in the foreground: + ```bash + openclaw gateway run + ``` -```bash -openclaw gateway run -``` + **2) Native Windows (not recommended):** the Gateway runs directly in Windows. -**2) Native Windows (not recommended):** the Gateway runs directly in Windows. + Open PowerShell and run: -Open PowerShell and run: + ```powershell + openclaw gateway status + openclaw gateway restart + ``` -```powershell -openclaw gateway status -openclaw gateway restart -``` + If you run it manually (no service), use: -If you run it manually (no service), use: + ```powershell + openclaw gateway run + ``` -```powershell -openclaw gateway run -``` + Docs: [Windows (WSL2)](/platforms/windows), [Gateway service runbook](/gateway). -Docs: [Windows (WSL2)](/platforms/windows), [Gateway service runbook](/gateway). + -### The Gateway is up but replies never arrive What should I check + + Start with a quick health sweep: -Start with a quick health sweep: + ```bash + openclaw status + openclaw models status + openclaw channels status + openclaw logs --follow + ``` -```bash -openclaw status -openclaw models status -openclaw channels status -openclaw logs --follow -``` + Common causes: -Common causes: + - Model auth not loaded on the **gateway host** (check `models status`). + - Channel pairing/allowlist blocking replies (check channel config + logs). + - WebChat/Dashboard is open without the right token. -- Model auth not loaded on the **gateway host** (check `models status`). -- Channel pairing/allowlist blocking replies (check channel config + logs). -- WebChat/Dashboard is open without the right token. + If you are remote, confirm the tunnel/Tailscale connection is up and that the + Gateway WebSocket is reachable. -If you are remote, confirm the tunnel/Tailscale connection is up and that the -Gateway WebSocket is reachable. + Docs: [Channels](/channels), [Troubleshooting](/gateway/troubleshooting), [Remote access](/gateway/remote). -Docs: [Channels](/channels), [Troubleshooting](/gateway/troubleshooting), [Remote access](/gateway/remote). + -### Disconnected from gateway no reason what now + + This usually means the UI lost the WebSocket connection. Check: -This usually means the UI lost the WebSocket connection. Check: + 1. Is the Gateway running? `openclaw gateway status` + 2. Is the Gateway healthy? `openclaw status` + 3. Does the UI have the right token? `openclaw dashboard` + 4. If remote, is the tunnel/Tailscale link up? -1. Is the Gateway running? `openclaw gateway status` -2. Is the Gateway healthy? `openclaw status` -3. Does the UI have the right token? `openclaw dashboard` -4. If remote, is the tunnel/Tailscale link up? + Then tail logs: -Then tail logs: + ```bash + openclaw logs --follow + ``` -```bash -openclaw logs --follow -``` + Docs: [Dashboard](/web/dashboard), [Remote access](/gateway/remote), [Troubleshooting](/gateway/troubleshooting). -Docs: [Dashboard](/web/dashboard), [Remote access](/gateway/remote), [Troubleshooting](/gateway/troubleshooting). + -### Telegram setMyCommands fails What should I check + + Start with logs and channel status: -Start with logs and channel status: + ```bash + openclaw channels status + openclaw channels logs --channel telegram + ``` -```bash -openclaw channels status -openclaw channels logs --channel telegram -``` + Then match the error: -Then match the error: + - `BOT_COMMANDS_TOO_MUCH`: the Telegram menu has too many entries. OpenClaw already trims to the Telegram limit and retries with fewer commands, but some menu entries still need to be dropped. Reduce plugin/skill/custom commands, or disable `channels.telegram.commands.native` if you do not need the menu. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!`, or similar network errors: if you are on a VPS or behind a proxy, confirm outbound HTTPS is allowed and DNS works for `api.telegram.org`. -- `BOT_COMMANDS_TOO_MUCH`: the Telegram menu has too many entries. OpenClaw already trims to the Telegram limit and retries with fewer commands, but some menu entries still need to be dropped. Reduce plugin/skill/custom commands, or disable `channels.telegram.commands.native` if you do not need the menu. -- `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!`, or similar network errors: if you are on a VPS or behind a proxy, confirm outbound HTTPS is allowed and DNS works for `api.telegram.org`. + If the Gateway is remote, make sure you are looking at logs on the Gateway host. -If the Gateway is remote, make sure you are looking at logs on the Gateway host. + Docs: [Telegram](/channels/telegram), [Channel troubleshooting](/channels/troubleshooting). -Docs: [Telegram](/channels/telegram), [Channel troubleshooting](/channels/troubleshooting). + -### TUI shows no output What should I check + + First confirm the Gateway is reachable and the agent can run: -First confirm the Gateway is reachable and the agent can run: + ```bash + openclaw status + openclaw models status + openclaw logs --follow + ``` -```bash -openclaw status -openclaw models status -openclaw logs --follow -``` + In the TUI, use `/status` to see the current state. If you expect replies in a chat + channel, make sure delivery is enabled (`/deliver on`). -In the TUI, use `/status` to see the current state. If you expect replies in a chat -channel, make sure delivery is enabled (`/deliver on`). + Docs: [TUI](/web/tui), [Slash commands](/tools/slash-commands). -Docs: [TUI](/web/tui), [Slash commands](/tools/slash-commands). + -### How do I completely stop then start the Gateway + + If you installed the service: -If you installed the service: + ```bash + openclaw gateway stop + openclaw gateway start + ``` -```bash -openclaw gateway stop -openclaw gateway start -``` + This stops/starts the **supervised service** (launchd on macOS, systemd on Linux). + Use this when the Gateway runs in the background as a daemon. -This stops/starts the **supervised service** (launchd on macOS, systemd on Linux). -Use this when the Gateway runs in the background as a daemon. + If you're running in the foreground, stop with Ctrl-C, then: -If you're running in the foreground, stop with Ctrl-C, then: + ```bash + openclaw gateway run + ``` -```bash -openclaw gateway run -``` + Docs: [Gateway service runbook](/gateway). -Docs: [Gateway service runbook](/gateway). + -### ELI5 openclaw gateway restart vs openclaw gateway + + - `openclaw gateway restart`: restarts the **background service** (launchd/systemd). + - `openclaw gateway`: runs the gateway **in the foreground** for this terminal session. -- `openclaw gateway restart`: restarts the **background service** (launchd/systemd). -- `openclaw gateway`: runs the gateway **in the foreground** for this terminal session. + If you installed the service, use the gateway commands. Use `openclaw gateway` when + you want a one-off, foreground run. -If you installed the service, use the gateway commands. Use `openclaw gateway` when -you want a one-off, foreground run. + -### Fastest way to get more details when something fails - -Start the Gateway with `--verbose` to get more console detail. Then inspect the log file for channel auth, model routing, and RPC errors. + + Start the Gateway with `--verbose` to get more console detail. Then inspect the log file for channel auth, model routing, and RPC errors. + + ## Media and attachments -### My skill generated an imagePDF but nothing was sent + + + Outbound attachments from the agent must include a `MEDIA:` line (on its own line). See [OpenClaw assistant setup](/start/openclaw) and [Agent send](/tools/agent-send). -Outbound attachments from the agent must include a `MEDIA:` line (on its own line). See [OpenClaw assistant setup](/start/openclaw) and [Agent send](/tools/agent-send). + CLI sending: -CLI sending: + ```bash + openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png + ``` -```bash -openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png -``` + Also check: -Also check: + - The target channel supports outbound media and isn't blocked by allowlists. + - The file is within the provider's size limits (images are resized to max 2048px). -- The target channel supports outbound media and isn't blocked by allowlists. -- The file is within the provider's size limits (images are resized to max 2048px). + See [Images](/nodes/images). -See [Images](/nodes/images). + + ## Security and access control -### Is it safe to expose OpenClaw to inbound DMs + + + Treat inbound DMs as untrusted input. Defaults are designed to reduce risk: -Treat inbound DMs as untrusted input. Defaults are designed to reduce risk: + - Default behavior on DM-capable channels is **pairing**: + - Unknown senders receive a pairing code; the bot does not process their message. + - Approve with: `openclaw pairing approve --channel [--account ] ` + - Pending requests are capped at **3 per channel**; check `openclaw pairing list --channel [--account ]` if a code didn't arrive. + - Opening DMs publicly requires explicit opt-in (`dmPolicy: "open"` and allowlist `"*"`). -- Default behavior on DM-capable channels is **pairing**: - - Unknown senders receive a pairing code; the bot does not process their message. - - Approve with: `openclaw pairing approve --channel [--account ] ` - - Pending requests are capped at **3 per channel**; check `openclaw pairing list --channel [--account ]` if a code didn't arrive. -- Opening DMs publicly requires explicit opt-in (`dmPolicy: "open"` and allowlist `"*"`). + Run `openclaw doctor` to surface risky DM policies. -Run `openclaw doctor` to surface risky DM policies. + -### Is prompt injection only a concern for public bots + + No. Prompt injection is about **untrusted content**, not just who can DM the bot. + If your assistant reads external content (web search/fetch, browser pages, emails, + docs, attachments, pasted logs), that content can include instructions that try + to hijack the model. This can happen even if **you are the only sender**. -No. Prompt injection is about **untrusted content**, not just who can DM the bot. -If your assistant reads external content (web search/fetch, browser pages, emails, -docs, attachments, pasted logs), that content can include instructions that try -to hijack the model. This can happen even if **you are the only sender**. + The biggest risk is when tools are enabled: the model can be tricked into + exfiltrating context or calling tools on your behalf. Reduce the blast radius by: -The biggest risk is when tools are enabled: the model can be tricked into -exfiltrating context or calling tools on your behalf. Reduce the blast radius by: + - using a read-only or tool-disabled "reader" agent to summarize untrusted content + - keeping `web_search` / `web_fetch` / `browser` off for tool-enabled agents + - sandboxing and strict tool allowlists -- using a read-only or tool-disabled "reader" agent to summarize untrusted content -- keeping `web_search` / `web_fetch` / `browser` off for tool-enabled agents -- sandboxing and strict tool allowlists + Details: [Security](/gateway/security). -Details: [Security](/gateway/security). + -### Should my bot have its own email GitHub account or phone number + + Yes, for most setups. Isolating the bot with separate accounts and phone numbers + reduces the blast radius if something goes wrong. This also makes it easier to rotate + credentials or revoke access without impacting your personal accounts. -Yes, for most setups. Isolating the bot with separate accounts and phone numbers -reduces the blast radius if something goes wrong. This also makes it easier to rotate -credentials or revoke access without impacting your personal accounts. + Start small. Give access only to the tools and accounts you actually need, and expand + later if required. -Start small. Give access only to the tools and accounts you actually need, and expand -later if required. + Docs: [Security](/gateway/security), [Pairing](/channels/pairing). -Docs: [Security](/gateway/security), [Pairing](/channels/pairing). + -### Can I give it autonomy over my text messages and is that safe + + We do **not** recommend full autonomy over your personal messages. The safest pattern is: -We do **not** recommend full autonomy over your personal messages. The safest pattern is: + - Keep DMs in **pairing mode** or a tight allowlist. + - Use a **separate number or account** if you want it to message on your behalf. + - Let it draft, then **approve before sending**. -- Keep DMs in **pairing mode** or a tight allowlist. -- Use a **separate number or account** if you want it to message on your behalf. -- Let it draft, then **approve before sending**. + If you want to experiment, do it on a dedicated account and keep it isolated. See + [Security](/gateway/security). -If you want to experiment, do it on a dedicated account and keep it isolated. See -[Security](/gateway/security). + -### Can I use cheaper models for personal assistant tasks + + Yes, **if** the agent is chat-only and the input is trusted. Smaller tiers are + more susceptible to instruction hijacking, so avoid them for tool-enabled agents + or when reading untrusted content. If you must use a smaller model, lock down + tools and run inside a sandbox. See [Security](/gateway/security). + -Yes, **if** the agent is chat-only and the input is trusted. Smaller tiers are -more susceptible to instruction hijacking, so avoid them for tool-enabled agents -or when reading untrusted content. If you must use a smaller model, lock down -tools and run inside a sandbox. See [Security](/gateway/security). + + Pairing codes are sent **only** when an unknown sender messages the bot and + `dmPolicy: "pairing"` is enabled. `/start` by itself doesn't generate a code. -### I ran start in Telegram but did not get a pairing code + Check pending requests: -Pairing codes are sent **only** when an unknown sender messages the bot and -`dmPolicy: "pairing"` is enabled. `/start` by itself doesn't generate a code. + ```bash + openclaw pairing list telegram + ``` -Check pending requests: + If you want immediate access, allowlist your sender id or set `dmPolicy: "open"` + for that account. -```bash -openclaw pairing list telegram -``` + -If you want immediate access, allowlist your sender id or set `dmPolicy: "open"` -for that account. + + No. Default WhatsApp DM policy is **pairing**. Unknown senders only get a pairing code and their message is **not processed**. OpenClaw only replies to chats it receives or to explicit sends you trigger. -### WhatsApp will it message my contacts How does pairing work + Approve pairing with: -No. Default WhatsApp DM policy is **pairing**. Unknown senders only get a pairing code and their message is **not processed**. OpenClaw only replies to chats it receives or to explicit sends you trigger. + ```bash + openclaw pairing approve whatsapp + ``` -Approve pairing with: + List pending requests: -```bash -openclaw pairing approve whatsapp -``` + ```bash + openclaw pairing list whatsapp + ``` -List pending requests: + Wizard phone number prompt: it's used to set your **allowlist/owner** so your own DMs are permitted. It's not used for auto-sending. If you run on your personal WhatsApp number, use that number and enable `channels.whatsapp.selfChatMode`. -```bash -openclaw pairing list whatsapp -``` - -Wizard phone number prompt: it's used to set your **allowlist/owner** so your own DMs are permitted. It's not used for auto-sending. If you run on your personal WhatsApp number, use that number and enable `channels.whatsapp.selfChatMode`. + + ## Chat commands, aborting tasks, and "it will not stop" -### How do I stop internal system messages from showing in chat + + + Most internal or tool messages only appear when **verbose** or **reasoning** is enabled + for that session. -Most internal or tool messages only appear when **verbose** or **reasoning** is enabled -for that session. + Fix in the chat where you see it: -Fix in the chat where you see it: + ``` + /verbose off + /reasoning off + ``` -``` -/verbose off -/reasoning off -``` + If it is still noisy, check the session settings in the Control UI and set verbose + to **inherit**. Also confirm you are not using a bot profile with `verboseDefault` set + to `on` in config. -If it is still noisy, check the session settings in the Control UI and set verbose -to **inherit**. Also confirm you are not using a bot profile with `verboseDefault` set -to `on` in config. + Docs: [Thinking and verbose](/tools/thinking), [Security](/gateway/security#reasoning-verbose-output-in-groups). -Docs: [Thinking and verbose](/tools/thinking), [Security](/gateway/security#reasoning-verbose-output-in-groups). + -### How do I stopcancel a running task + + Send any of these **as a standalone message** (no slash): -Send any of these **as a standalone message** (no slash): + ``` + stop + stop action + stop current action + stop run + stop current run + stop agent + stop the agent + stop openclaw + openclaw stop + stop don't do anything + stop do not do anything + stop doing anything + please stop + stop please + abort + esc + wait + exit + interrupt + ``` -``` -stop -stop action -stop current action -stop run -stop current run -stop agent -stop the agent -stop openclaw -openclaw stop -stop don't do anything -stop do not do anything -stop doing anything -please stop -stop please -abort -esc -wait -exit -interrupt -``` + These are abort triggers (not slash commands). -These are abort triggers (not slash commands). + For background processes (from the exec tool), you can ask the agent to run: -For background processes (from the exec tool), you can ask the agent to run: + ``` + process action:kill sessionId:XXX + ``` -``` -process action:kill sessionId:XXX -``` + Slash commands overview: see [Slash commands](/tools/slash-commands). -Slash commands overview: see [Slash commands](/tools/slash-commands). + Most commands must be sent as a **standalone** message that starts with `/`, but a few shortcuts (like `/status`) also work inline for allowlisted senders. -Most commands must be sent as a **standalone** message that starts with `/`, but a few shortcuts (like `/status`) also work inline for allowlisted senders. + -### How do I send a Discord message from Telegram Crosscontext messaging denied + + OpenClaw blocks **cross-provider** messaging by default. If a tool call is bound + to Telegram, it won't send to Discord unless you explicitly allow it. -OpenClaw blocks **cross-provider** messaging by default. If a tool call is bound -to Telegram, it won't send to Discord unless you explicitly allow it. + Enable cross-provider messaging for the agent: -Enable cross-provider messaging for the agent: - -```json5 -{ - agents: { - defaults: { - tools: { - message: { - crossContext: { - allowAcrossProviders: true, - marker: { enabled: true, prefix: "[from {channel}] " }, + ```json5 + { + agents: { + defaults: { + tools: { + message: { + crossContext: { + allowAcrossProviders: true, + marker: { enabled: true, prefix: "[from {channel}] " }, + }, + }, }, }, }, - }, - }, -} -``` + } + ``` -Restart the gateway after editing config. If you only want this for a single -agent, set it under `agents.list[].tools.message` instead. + Restart the gateway after editing config. If you only want this for a single + agent, set it under `agents.list[].tools.message` instead. -### Why does it feel like the bot ignores rapidfire messages + -Queue mode controls how new messages interact with an in-flight run. Use `/queue` to change modes: + + Queue mode controls how new messages interact with an in-flight run. Use `/queue` to change modes: -- `steer` - new messages redirect the current task -- `followup` - run messages one at a time -- `collect` - batch messages and reply once (default) -- `steer-backlog` - steer now, then process backlog -- `interrupt` - abort current run and start fresh + - `steer` - new messages redirect the current task + - `followup` - run messages one at a time + - `collect` - batch messages and reply once (default) + - `steer-backlog` - steer now, then process backlog + - `interrupt` - abort current run and start fresh -You can add options like `debounce:2s cap:25 drop:summarize` for followup modes. + You can add options like `debounce:2s cap:25 drop:summarize` for followup modes. -## Answer the exact question from the screenshot/chat log + + -**Q: "What's the default model for Anthropic with an API key?"** +## Miscellaneous -**A:** In OpenClaw, credentials and model selection are separate. Setting `ANTHROPIC_API_KEY` (or storing an Anthropic API key in auth profiles) enables authentication, but the actual default model is whatever you configure in `agents.defaults.model.primary` (for example, `anthropic/claude-sonnet-4-6` or `anthropic/claude-opus-4-6`). If you see `No credentials found for profile "anthropic:default"`, it means the Gateway couldn't find Anthropic credentials in the expected `auth-profiles.json` for the agent that's running. + + + In OpenClaw, credentials and model selection are separate. Setting `ANTHROPIC_API_KEY` (or storing an Anthropic API key in auth profiles) enables authentication, but the actual default model is whatever you configure in `agents.defaults.model.primary` (for example, `anthropic/claude-sonnet-4-6` or `anthropic/claude-opus-4-6`). If you see `No credentials found for profile "anthropic:default"`, it means the Gateway couldn't find Anthropic credentials in the expected `auth-profiles.json` for the agent that's running. + + --- diff --git a/docs/help/index.md b/docs/help/index.md index 5d0942909b6..26b990c1533 100644 --- a/docs/help/index.md +++ b/docs/help/index.md @@ -19,3 +19,10 @@ If you want a quick “get unstuck” flow, start here: If you’re looking for conceptual questions (not “something broke”): - [FAQ (concepts)](/help/faq) + +## Environment and debugging + +- **Environment variables:** [Where OpenClaw loads env vars and precedence](/help/environment) +- **Debugging:** [Watch mode, raw streams, and dev profile](/help/debugging) +- **Testing:** [Test suites, live tests, and Docker runners](/help/testing) +- **Scripts:** [Repository helper scripts](/help/scripts) From ae02f4014456cbf7ea5cfaac658b8e1d6b8c5890 Mon Sep 17 00:00:00 2001 From: Josh Lehman Date: Thu, 19 Mar 2026 14:21:42 -0700 Subject: [PATCH 18/69] fix: load matrix legacy helper through native ESM when possible (#50623) * fix(matrix): load legacy helper natively when possible * fix(matrix): narrow jiti fallback to source helpers * fix(matrix): fall back to jiti for source-style helper wrappers --- src/infra/matrix-plugin-helper.test.ts | 72 ++++++++++++++++++++++++++ src/infra/matrix-plugin-helper.ts | 37 ++++++++++--- 2 files changed, 103 insertions(+), 6 deletions(-) diff --git a/src/infra/matrix-plugin-helper.test.ts b/src/infra/matrix-plugin-helper.test.ts index ae71aca0bc8..602d151c853 100644 --- a/src/infra/matrix-plugin-helper.test.ts +++ b/src/infra/matrix-plugin-helper.test.ts @@ -25,6 +25,22 @@ function writeMatrixPluginFixture(rootDir: string, helperBody: string): void { fs.writeFileSync(path.join(rootDir, "legacy-crypto-inspector.js"), helperBody, "utf8"); } +function writeMatrixPluginManifest(rootDir: string): void { + fs.mkdirSync(rootDir, { recursive: true }); + fs.writeFileSync( + path.join(rootDir, "openclaw.plugin.json"), + JSON.stringify({ + id: "matrix", + configSchema: { + type: "object", + additionalProperties: false, + }, + }), + "utf8", + ); + fs.writeFileSync(path.join(rootDir, "index.js"), "export default {};\n", "utf8"); +} + describe("matrix plugin helper resolution", () => { it("loads the legacy crypto inspector from the bundled matrix plugin", async () => { await withTempHome( @@ -125,6 +141,62 @@ describe("matrix plugin helper resolution", () => { ); }); + it("keeps source-style root helper shims on the Jiti fallback path", async () => { + await withTempHome( + async (home) => { + const customRoot = path.join(home, "plugins", "matrix-local"); + writeMatrixPluginManifest(customRoot); + fs.mkdirSync(path.join(customRoot, "src", "matrix"), { recursive: true }); + fs.writeFileSync( + path.join(customRoot, "legacy-crypto-inspector.js"), + 'export { inspectLegacyMatrixCryptoStore } from "./src/matrix/legacy-crypto-inspector.js";\n', + "utf8", + ); + fs.writeFileSync( + path.join(customRoot, "src", "matrix", "legacy-crypto-inspector.ts"), + [ + "export async function inspectLegacyMatrixCryptoStore() {", + ' return { deviceId: "SRCJS", roomKeyCounts: null, backupVersion: null, decryptionKeyBase64: null };', + "}", + ].join("\n"), + "utf8", + ); + + const cfg: OpenClawConfig = { + plugins: { + load: { + paths: [customRoot], + }, + }, + }; + + expect(isMatrixLegacyCryptoInspectorAvailable({ cfg, env: process.env })).toBe(true); + const inspectLegacyStore = await loadMatrixLegacyCryptoInspector({ + cfg, + env: process.env, + }); + + await expect( + inspectLegacyStore({ + cryptoRootDir: "/tmp/legacy", + userId: "@bot:example.org", + deviceId: "DEVICE123", + }), + ).resolves.toEqual({ + deviceId: "SRCJS", + roomKeyCounts: null, + backupVersion: null, + decryptionKeyBase64: null, + }); + }, + { + env: { + OPENCLAW_BUNDLED_PLUGINS_DIR: (home) => path.join(home, "empty-bundled"), + }, + }, + ); + }); + it("rejects helper files that escape the plugin root", async () => { await withTempHome( async (home) => { diff --git a/src/infra/matrix-plugin-helper.ts b/src/infra/matrix-plugin-helper.ts index ab40287029f..a0a78eb4d72 100644 --- a/src/infra/matrix-plugin-helper.ts +++ b/src/infra/matrix-plugin-helper.ts @@ -1,11 +1,13 @@ import fs from "node:fs"; import path from "node:path"; +import { pathToFileURL } from "node:url"; import { createJiti } from "jiti"; import type { OpenClawConfig } from "../config/config.js"; import { loadPluginManifestRegistry, type PluginManifestRecord, } from "../plugins/manifest-registry.js"; +import { shouldPreferNativeJiti } from "../plugins/sdk-alias.js"; import { openBoundaryFileSync } from "./boundary-file-read.js"; const MATRIX_PLUGIN_ID = "matrix"; @@ -98,15 +100,26 @@ let jitiLoader: ReturnType | null = null; const inspectorCache = new Map>(); function getJiti() { - if (!jitiLoader) { - jitiLoader = createJiti(import.meta.url, { - interopDefault: false, - extensions: [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs", ".json"], - }); + if (jitiLoader) { + return jitiLoader; } + + jitiLoader = createJiti(import.meta.url, { + interopDefault: false, + tryNative: false, + extensions: [".ts", ".tsx", ".mts", ".cts", ".mtsx", ".ctsx", ".js", ".mjs", ".cjs", ".json"], + }); return jitiLoader; } +function canRetryWithJiti(error: unknown): boolean { + if (!error || typeof error !== "object") { + return false; + } + const code = "code" in error ? (error as { code?: unknown }).code : undefined; + return code === "ERR_MODULE_NOT_FOUND" || code === "ERR_UNKNOWN_FILE_EXTENSION"; +} + function isObjectRecord(value: unknown): value is Record { return typeof value === "object" && value !== null; } @@ -154,7 +167,19 @@ export async function loadMatrixLegacyCryptoInspector(params: { } const pending = (async () => { - const loaded: unknown = await getJiti().import(helperPath); + let loaded: unknown; + if (shouldPreferNativeJiti(helperPath)) { + try { + loaded = await import(pathToFileURL(helperPath).href); + } catch (error) { + if (!canRetryWithJiti(error)) { + throw error; + } + loaded = getJiti()(helperPath); + } + } else { + loaded = getJiti()(helperPath); + } const inspectLegacyMatrixCryptoStore = resolveInspectorExport(loaded); if (!inspectLegacyMatrixCryptoStore) { throw new Error( From 83a267e2f334ceee255f21b1df2a7cc289cacbcb Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 14:23:17 -0700 Subject: [PATCH 19/69] fix(ci): reset deep test runtime state --- .../src/monitor.reply-once.lifecycle.test.ts | 12 +++++-- src/memory/index.test.ts | 34 +++++-------------- src/plugins/http-registry.test.ts | 3 +- src/plugins/runtime.test.ts | 3 +- src/plugins/runtime.ts | 9 +++++ src/secrets/runtime.test.ts | 9 ++++- 6 files changed, 39 insertions(+), 31 deletions(-) diff --git a/extensions/feishu/src/monitor.reply-once.lifecycle.test.ts b/extensions/feishu/src/monitor.reply-once.lifecycle.test.ts index 7aaf16e93f4..e78f0b28a3c 100644 --- a/extensions/feishu/src/monitor.reply-once.lifecycle.test.ts +++ b/extensions/feishu/src/monitor.reply-once.lifecycle.test.ts @@ -10,7 +10,14 @@ const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); const createFeishuReplyDispatcherMock = vi.hoisted(() => vi.fn()); -const resolveBoundConversationMock = vi.hoisted(() => vi.fn(() => null)); +const resolveBoundConversationMock = vi.hoisted(() => + vi.fn< + () => { + bindingId: string; + targetSessionKey: string; + } | null + >(() => null), +); const touchBindingMock = vi.hoisted(() => vi.fn()); const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); const dispatchReplyFromConfigMock = vi.hoisted(() => vi.fn()); @@ -110,6 +117,7 @@ function createLifecycleConfig(): ClawdbotConfig { function createLifecycleAccount(): ResolvedFeishuAccount { return { accountId: "acct-lifecycle", + selectionSource: "explicit", enabled: true, configured: true, appId: "cli_test", @@ -129,7 +137,7 @@ function createLifecycleAccount(): ResolvedFeishuAccount { }, }, }, - } as ResolvedFeishuAccount; + } as unknown as ResolvedFeishuAccount; } function createRuntimeEnv(): RuntimeEnv { diff --git a/src/memory/index.test.ts b/src/memory/index.test.ts index 95d6e8556ee..189fbc0c09d 100644 --- a/src/memory/index.test.ts +++ b/src/memory/index.test.ts @@ -3,13 +3,14 @@ import { mkdirSync, rmSync } from "node:fs"; import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; -import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest"; +import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest"; import "./test-runtime-mocks.js"; import type { MemoryIndexManager } from "./index.js"; type MemoryIndexModule = typeof import("./index.js"); let getMemorySearchManager: MemoryIndexModule["getMemorySearchManager"]; +let closeAllMemorySearchManagers: MemoryIndexModule["closeAllMemorySearchManagers"]; let embedBatchCalls = 0; let embedBatchInputCalls = 0; @@ -125,14 +126,12 @@ describe("memory index", () => { }), ].join("\n"); - // Perf: keep managers open across tests, but only reset the one a test uses. - const managersByCacheKey = new Map(); const managersForCleanup = new Set(); beforeAll(async () => { vi.resetModules(); await import("./test-runtime-mocks.js"); - ({ getMemorySearchManager } = await import("./index.js")); + ({ getMemorySearchManager, closeAllMemorySearchManagers } = await import("./index.js")); fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-mem-fixtures-")); workspaceDir = path.join(fixtureRoot, "workspace"); memoryDir = path.join(workspaceDir, "memory"); @@ -158,6 +157,11 @@ describe("memory index", () => { await fs.rm(fixtureRoot, { recursive: true, force: true }); }); + afterEach(async () => { + await closeAllMemorySearchManagers(); + managersForCleanup.clear(); + }); + beforeEach(async () => { // Perf: most suites don't need atomic swap behavior for full reindexes. // Keep atomic reindex tests on the safe path. @@ -166,7 +170,6 @@ describe("memory index", () => { embedBatchInputCalls = 0; providerCalls = []; - // Keep the workspace stable to allow manager reuse across tests. mkdirSync(memoryDir, { recursive: true }); // Clean additional paths that may have been created by earlier cases. @@ -243,30 +246,9 @@ describe("memory index", () => { return result.manager as MemoryIndexManager; } - function getManagerCacheKey(cfg: TestCfg): string { - const memorySearch = cfg.agents?.defaults?.memorySearch; - const storePath = memorySearch?.store?.path; - if (!storePath) { - throw new Error("store path missing"); - } - return JSON.stringify({ - workspaceDir, - storePath, - memorySearch, - }); - } - async function getPersistentManager(cfg: TestCfg): Promise { - const cacheKey = getManagerCacheKey(cfg); - const cached = managersByCacheKey.get(cacheKey); - if (cached) { - resetManagerForTest(cached); - return cached; - } - const result = await getMemorySearchManager({ cfg, agentId: "main" }); const manager = requireManager(result); - managersByCacheKey.set(cacheKey, manager); managersForCleanup.add(manager); resetManagerForTest(manager); return manager; diff --git a/src/plugins/http-registry.test.ts b/src/plugins/http-registry.test.ts index 05bd337eed6..cee87a16114 100644 --- a/src/plugins/http-registry.test.ts +++ b/src/plugins/http-registry.test.ts @@ -4,6 +4,7 @@ import { createEmptyPluginRegistry } from "./registry.js"; import { pinActivePluginHttpRouteRegistry, releasePinnedPluginHttpRouteRegistry, + resetPluginRuntimeStateForTest, setActivePluginRegistry, } from "./runtime.js"; @@ -45,7 +46,7 @@ function expectRouteRegistrationDenied(params: { describe("registerPluginHttpRoute", () => { afterEach(() => { releasePinnedPluginHttpRouteRegistry(); - setActivePluginRegistry(createEmptyPluginRegistry()); + resetPluginRuntimeStateForTest(); }); it("registers route and unregisters it", () => { diff --git a/src/plugins/runtime.test.ts b/src/plugins/runtime.test.ts index b62a81314aa..e37b97f96bb 100644 --- a/src/plugins/runtime.test.ts +++ b/src/plugins/runtime.test.ts @@ -3,6 +3,7 @@ import { createEmptyPluginRegistry } from "./registry.js"; import { pinActivePluginHttpRouteRegistry, releasePinnedPluginHttpRouteRegistry, + resetPluginRuntimeStateForTest, resolveActivePluginHttpRouteRegistry, setActivePluginRegistry, } from "./runtime.js"; @@ -10,7 +11,7 @@ import { describe("plugin runtime route registry", () => { afterEach(() => { releasePinnedPluginHttpRouteRegistry(); - setActivePluginRegistry(createEmptyPluginRegistry()); + resetPluginRuntimeStateForTest(); }); it("keeps the pinned route registry when the active plugin registry changes", () => { diff --git a/src/plugins/runtime.ts b/src/plugins/runtime.ts index f5f8133e5ba..c1c8974adc2 100644 --- a/src/plugins/runtime.ts +++ b/src/plugins/runtime.ts @@ -98,3 +98,12 @@ export function getActivePluginRegistryKey(): string | null { export function getActivePluginRegistryVersion(): number { return state.version; } + +export function resetPluginRuntimeStateForTest(): void { + const emptyRegistry = createEmptyPluginRegistry(); + state.registry = emptyRegistry; + state.httpRouteRegistry = emptyRegistry; + state.httpRouteRegistryPinned = false; + state.key = null; + state.version += 1; +} diff --git a/src/secrets/runtime.test.ts b/src/secrets/runtime.test.ts index 5afff36b175..92e942ab12f 100644 --- a/src/secrets/runtime.test.ts +++ b/src/secrets/runtime.test.ts @@ -3,7 +3,12 @@ import os from "node:os"; import path from "node:path"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { ensureAuthProfileStore, type AuthProfileStore } from "../agents/auth-profiles.js"; -import { loadConfig, type OpenClawConfig, writeConfigFile } from "../config/config.js"; +import { + clearConfigCache, + loadConfig, + type OpenClawConfig, + writeConfigFile, +} from "../config/config.js"; import { withTempHome } from "../config/home-env.test-harness.js"; import type { PluginWebSearchProviderEntry } from "../plugins/types.js"; import { @@ -121,6 +126,8 @@ describe("secrets runtime snapshot", () => { afterEach(() => { clearSecretsRuntimeSnapshot(); + clearConfigCache(); + resolvePluginWebSearchProvidersMock.mockReset(); }); const allowInsecureTempSecretFile = process.platform === "win32"; From 247a19a694a9bb428cbb523e5a1dd57b81e05209 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 13:55:46 -0700 Subject: [PATCH 20/69] fix(hooks): bypass stale plugin bundle caches --- src/hooks/plugin-hooks.ts | 2 ++ src/plugins/manifest-registry.ts | 1 + 2 files changed, 3 insertions(+) diff --git a/src/hooks/plugin-hooks.ts b/src/hooks/plugin-hooks.ts index 298749d2245..c6651ff560b 100644 --- a/src/hooks/plugin-hooks.ts +++ b/src/hooks/plugin-hooks.ts @@ -28,6 +28,8 @@ export function resolvePluginHookDirs(params: { const registry = loadPluginManifestRegistry({ workspaceDir, config: params.config, + // Hook discovery should reflect freshly written bundle manifests immediately. + cache: false, }); if (registry.plugins.length === 0) { return []; diff --git a/src/plugins/manifest-registry.ts b/src/plugins/manifest-registry.ts index 9671a334d8a..383e6ad47cf 100644 --- a/src/plugins/manifest-registry.ts +++ b/src/plugins/manifest-registry.ts @@ -304,6 +304,7 @@ export function loadPluginManifestRegistry( : discoverOpenClawPlugins({ workspaceDir: params.workspaceDir, extraPaths: normalized.loadPaths, + cache: params.cache, env, }); const diagnostics: PluginDiagnostic[] = [...discovery.diagnostics]; From 3c806a969282f57f8c2902f2a6c9550babe7ebd1 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 14:23:10 -0700 Subject: [PATCH 21/69] fix(ci): stabilize bundle hooks and mcp path seams --- extensions/matrix/runtime-api.ts | 1 + .../matrix/src/matrix/thread-bindings.ts | 2 +- src/channels/plugins/contracts/registry.ts | 6 +-- src/hooks/workspace.ts | 43 ++++++++++--------- src/plugins/bundle-mcp.test-support.ts | 2 + src/plugins/bundle-mcp.ts | 11 +++-- 6 files changed, 35 insertions(+), 30 deletions(-) diff --git a/extensions/matrix/runtime-api.ts b/extensions/matrix/runtime-api.ts index bc8163c9969..04957e707c5 100644 --- a/extensions/matrix/runtime-api.ts +++ b/extensions/matrix/runtime-api.ts @@ -2,3 +2,4 @@ // helpers without traversing the full plugin-sdk/runtime graph. export * from "./src/auth-precedence.js"; export * from "./helper-api.js"; +export { sendMessageMatrix } from "./src/matrix/send.js"; diff --git a/extensions/matrix/src/matrix/thread-bindings.ts b/extensions/matrix/src/matrix/thread-bindings.ts index edbbde5d000..593d88ed7eb 100644 --- a/extensions/matrix/src/matrix/thread-bindings.ts +++ b/extensions/matrix/src/matrix/thread-bindings.ts @@ -1,4 +1,5 @@ import path from "node:path"; +import { sendMessageMatrix } from "../../runtime-api.js"; import { readJsonFileWithFallback, registerSessionBindingAdapter, @@ -10,7 +11,6 @@ import { import { resolveMatrixStoragePaths } from "./client/storage.js"; import type { MatrixAuth } from "./client/types.js"; import type { MatrixClient } from "./sdk.js"; -import { sendMessageMatrix } from "./send.js"; import { deleteMatrixThreadBindingManagerEntry, getMatrixThreadBindingManager, diff --git a/src/channels/plugins/contracts/registry.ts b/src/channels/plugins/contracts/registry.ts index cc2b8b7f34a..cf12d4f4355 100644 --- a/src/channels/plugins/contracts/registry.ts +++ b/src/channels/plugins/contracts/registry.ts @@ -223,10 +223,10 @@ bundledChannelRuntimeSetters.setLineRuntime({ }, } as never); -vi.mock("../../../../extensions/matrix/src/matrix/send.js", async () => { +vi.mock("../../../../extensions/matrix/runtime-api.js", async () => { const actual = await vi.importActual< - typeof import("../../../../extensions/matrix/src/matrix/send.js") - >("../../../../extensions/matrix/src/matrix/send.js"); + typeof import("../../../../extensions/matrix/runtime-api.js") + >("../../../../extensions/matrix/runtime-api.js"); return { ...actual, sendMessageMatrix: sendMessageMatrixMock, diff --git a/src/hooks/workspace.ts b/src/hooks/workspace.ts index 351690ab9d3..b4c2fa4a1f3 100644 --- a/src/hooks/workspace.ts +++ b/src/hooks/workspace.ts @@ -28,6 +28,11 @@ type HookPackageManifest = { } & Partial>; const log = createSubsystemLogger("hooks/workspace"); +type LoadedHook = { + hook: Hook; + frontmatter: ParsedHookFrontmatter; +}; + function filterHookEntries( entries: HookEntry[], config?: OpenClawConfig, @@ -79,7 +84,7 @@ function loadHookFromDir(params: { source: HookSource; pluginId?: string; nameHint?: string; -}): Hook | null { +}): LoadedHook | null { const hookMdPath = path.join(params.hookDir, "HOOK.md"); const content = readBoundaryFileUtf8({ absolutePath: hookMdPath, @@ -123,13 +128,16 @@ function loadHookFromDir(params: { } return { - name, - description, - source: params.source, - pluginId: params.pluginId, - filePath: hookMdPath, - baseDir, - handlerPath, + hook: { + name, + description, + source: params.source, + pluginId: params.pluginId, + filePath: hookMdPath, + baseDir, + handlerPath, + }, + frontmatter, }; } catch (err) { const message = err instanceof Error ? (err.stack ?? err.message) : String(err); @@ -141,7 +149,11 @@ function loadHookFromDir(params: { /** * Scan a directory for hooks (subdirectories containing HOOK.md) */ -function loadHooksFromDir(params: { dir: string; source: HookSource; pluginId?: string }): Hook[] { +function loadHooksFromDir(params: { + dir: string; + source: HookSource; + pluginId?: string; +}): LoadedHook[] { const { dir, source, pluginId } = params; if (!fs.existsSync(dir)) { @@ -153,7 +165,7 @@ function loadHooksFromDir(params: { dir: string; source: HookSource; pluginId?: return []; } - const hooks: Hook[] = []; + const hooks: LoadedHook[] = []; const entries = fs.readdirSync(dir, { withFileTypes: true }); for (const entry of entries) { @@ -211,16 +223,7 @@ export function loadHookEntriesFromDir(params: { source: params.source, pluginId: params.pluginId, }); - return hooks.map((hook) => { - let frontmatter: ParsedHookFrontmatter = {}; - const raw = readBoundaryFileUtf8({ - absolutePath: hook.filePath, - rootPath: hook.baseDir, - boundaryLabel: "hook directory", - }); - if (raw !== null) { - frontmatter = parseFrontmatter(raw); - } + return hooks.map(({ hook, frontmatter }) => { const entry: HookEntry = { hook: { ...hook, diff --git a/src/plugins/bundle-mcp.test-support.ts b/src/plugins/bundle-mcp.test-support.ts index 8b6723e7e13..009078f8f8a 100644 --- a/src/plugins/bundle-mcp.test-support.ts +++ b/src/plugins/bundle-mcp.test-support.ts @@ -1,6 +1,7 @@ import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; +import { clearPluginDiscoveryCache } from "./discovery.js"; import { clearPluginManifestRegistryCache } from "./manifest-registry.js"; export function createBundleMcpTempHarness() { @@ -13,6 +14,7 @@ export function createBundleMcpTempHarness() { return dir; }, async cleanup() { + clearPluginDiscoveryCache(); clearPluginManifestRegistryCache(); await Promise.all( tempDirs diff --git a/src/plugins/bundle-mcp.ts b/src/plugins/bundle-mcp.ts index ebe1b369f3c..c4e2f0651bb 100644 --- a/src/plugins/bundle-mcp.ts +++ b/src/plugins/bundle-mcp.ts @@ -13,7 +13,6 @@ import { } from "./bundle-manifest.js"; import { normalizePluginsConfig, resolveEffectiveEnableState } from "./config-state.js"; import { loadPluginManifestRegistry } from "./manifest-registry.js"; -import { safeRealpathSync } from "./path-safety.js"; import type { PluginBundleFormat } from "./types.js"; export type BundleMcpServerConfig = Record; @@ -122,8 +121,8 @@ function expandBundleRootPlaceholders(value: string, rootDir: string): string { return value.split(CLAUDE_PLUGIN_ROOT_PLACEHOLDER).join(rootDir); } -function canonicalizeBundlePath(targetPath: string): string { - return path.normalize(safeRealpathSync(targetPath) ?? path.resolve(targetPath)); +function normalizeBundlePath(targetPath: string): string { + return path.normalize(path.resolve(targetPath)); } function normalizeExpandedAbsolutePath(value: string): string { @@ -194,7 +193,7 @@ function loadBundleFileBackedMcpConfig(params: { rootDir: string; relativePath: string; }): BundleMcpConfig { - const rootDir = canonicalizeBundlePath(params.rootDir); + const rootDir = normalizeBundlePath(params.rootDir); const absolutePath = path.resolve(rootDir, params.relativePath); const opened = openBoundaryFileSync({ absolutePath, @@ -212,7 +211,7 @@ function loadBundleFileBackedMcpConfig(params: { } const raw = JSON.parse(fs.readFileSync(opened.fd, "utf-8")) as unknown; const servers = extractMcpServerMap(raw); - const baseDir = canonicalizeBundlePath(path.dirname(absolutePath)); + const baseDir = normalizeBundlePath(path.dirname(absolutePath)); return { mcpServers: Object.fromEntries( Object.entries(servers).map(([serverName, server]) => [ @@ -233,7 +232,7 @@ function loadBundleInlineMcpConfig(params: { if (!isRecord(params.raw.mcpServers)) { return { mcpServers: {} }; } - const baseDir = canonicalizeBundlePath(params.baseDir); + const baseDir = normalizeBundlePath(params.baseDir); const servers = extractMcpServerMap(params.raw.mcpServers); return { mcpServers: Object.fromEntries( From 7d50e7fa854efcd2486d7db8d595acfb12d8ba78 Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:21:02 -0500 Subject: [PATCH 22/69] test: add Feishu card-action lifecycle regression --- .../src/monitor.card-action.lifecycle.test.ts | 386 ++++++++++++++++++ 1 file changed, 386 insertions(+) create mode 100644 extensions/feishu/src/monitor.card-action.lifecycle.test.ts diff --git a/extensions/feishu/src/monitor.card-action.lifecycle.test.ts b/extensions/feishu/src/monitor.card-action.lifecycle.test.ts new file mode 100644 index 00000000000..95526d211d9 --- /dev/null +++ b/extensions/feishu/src/monitor.card-action.lifecycle.test.ts @@ -0,0 +1,386 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { createPluginRuntimeMock } from "../../../test/helpers/extensions/plugin-runtime-mock.js"; +import type { ClawdbotConfig, PluginRuntime, RuntimeEnv } from "../runtime-api.js"; +import { createFeishuCardInteractionEnvelope } from "./card-interaction.js"; +import { monitorSingleAccount } from "./monitor.account.js"; +import { setFeishuRuntime } from "./runtime.js"; +import type { ResolvedFeishuAccount } from "./types.js"; + +const createEventDispatcherMock = vi.hoisted(() => vi.fn()); +const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); +const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); +const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); +const createFeishuReplyDispatcherMock = vi.hoisted(() => vi.fn()); +const resolveBoundConversationMock = vi.hoisted(() => vi.fn(() => null)); +const touchBindingMock = vi.hoisted(() => vi.fn()); +const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); +const dispatchReplyFromConfigMock = vi.hoisted(() => vi.fn()); +const withReplyDispatcherMock = vi.hoisted(() => vi.fn()); +const finalizeInboundContextMock = vi.hoisted(() => vi.fn((ctx) => ctx)); +const sendMessageFeishuMock = vi.hoisted(() => + vi.fn(async () => ({ messageId: "om_notice", chatId: "p2p:ou_user1" })), +); +const sendCardFeishuMock = vi.hoisted(() => + vi.fn(async () => ({ messageId: "om_card", chatId: "p2p:ou_user1" })), +); +const getMessageFeishuMock = vi.hoisted(() => vi.fn(async () => null)); +const listFeishuThreadMessagesMock = vi.hoisted(() => vi.fn(async () => [])); + +let handlers: Record Promise> = {}; +let lastRuntime: RuntimeEnv | null = null; +const originalStateDir = process.env.OPENCLAW_STATE_DIR; + +vi.mock("./client.js", async () => { + const actual = await vi.importActual("./client.js"); + return { + ...actual, + createEventDispatcher: createEventDispatcherMock, + }; +}); + +vi.mock("./monitor.transport.js", () => ({ + monitorWebSocket: monitorWebSocketMock, + monitorWebhook: monitorWebhookMock, +})); + +vi.mock("./thread-bindings.js", () => ({ + createFeishuThreadBindingManager: createFeishuThreadBindingManagerMock, +})); + +vi.mock("./reply-dispatcher.js", () => ({ + createFeishuReplyDispatcher: createFeishuReplyDispatcherMock, +})); + +vi.mock("./send.js", () => ({ + sendMessageFeishu: sendMessageFeishuMock, + sendCardFeishu: sendCardFeishuMock, + getMessageFeishu: getMessageFeishuMock, + listFeishuThreadMessages: listFeishuThreadMessagesMock, +})); + +vi.mock("openclaw/plugin-sdk/conversation-runtime", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + getSessionBindingService: () => ({ + resolveByConversation: resolveBoundConversationMock, + touch: touchBindingMock, + }), + }; +}); + +vi.mock("../../../src/infra/outbound/session-binding-service.js", () => ({ + getSessionBindingService: () => ({ + resolveByConversation: resolveBoundConversationMock, + touch: touchBindingMock, + }), +})); + +function createLifecycleConfig(): ClawdbotConfig { + return { + channels: { + feishu: { + enabled: true, + dmPolicy: "open", + requireMention: false, + resolveSenderNames: false, + accounts: { + "acct-card": { + enabled: true, + appId: "cli_test", + appSecret: "secret_test", // pragma: allowlist secret + connectionMode: "websocket", + dmPolicy: "open", + requireMention: false, + resolveSenderNames: false, + }, + }, + }, + }, + messages: { + inbound: { + debounceMs: 0, + byChannel: { + feishu: 0, + }, + }, + }, + } as ClawdbotConfig; +} + +function createLifecycleAccount(): ResolvedFeishuAccount { + return { + accountId: "acct-card", + enabled: true, + configured: true, + appId: "cli_test", + appSecret: "secret_test", // pragma: allowlist secret + domain: "feishu", + config: { + enabled: true, + connectionMode: "websocket", + dmPolicy: "open", + requireMention: false, + resolveSenderNames: false, + }, + } as ResolvedFeishuAccount; +} + +function createRuntimeEnv(): RuntimeEnv { + return { + log: vi.fn(), + error: vi.fn(), + exit: vi.fn(), + } as RuntimeEnv; +} + +function createCardActionEvent(params: { + token: string; + action: string; + command: string; + chatId?: string; + chatType?: "group" | "p2p"; +}) { + const openId = "ou_user1"; + const chatId = params.chatId ?? "p2p:ou_user1"; + const chatType = params.chatType ?? "p2p"; + return { + operator: { + open_id: openId, + user_id: "user_1", + union_id: "union_1", + }, + token: params.token, + action: { + tag: "button", + value: createFeishuCardInteractionEnvelope({ + k: "quick", + a: params.action, + q: params.command, + c: { + u: openId, + h: chatId, + t: chatType, + e: Date.now() + 60_000, + }, + }), + }, + context: { + open_id: openId, + user_id: "user_1", + chat_id: chatId, + }, + }; +} + +async function settleAsyncWork(): Promise { + for (let i = 0; i < 6; i += 1) { + await Promise.resolve(); + await new Promise((resolve) => setTimeout(resolve, 0)); + } +} + +async function setupLifecycleMonitor() { + const register = vi.fn((registered: Record Promise>) => { + handlers = registered; + }); + createEventDispatcherMock.mockReturnValue({ register }); + + lastRuntime = createRuntimeEnv(); + + await monitorSingleAccount({ + cfg: createLifecycleConfig(), + account: createLifecycleAccount(), + runtime: lastRuntime, + botOpenIdSource: { + kind: "prefetched", + botOpenId: "ou_bot_1", + botName: "Bot", + }, + }); + + const onCardAction = handlers["card.action.trigger"]; + if (!onCardAction) { + throw new Error("missing card.action.trigger handler"); + } + return onCardAction; +} + +describe("Feishu card-action lifecycle", () => { + beforeEach(() => { + vi.clearAllMocks(); + handlers = {}; + lastRuntime = null; + process.env.OPENCLAW_STATE_DIR = `/tmp/openclaw-feishu-card-action-${Date.now()}-${Math.random().toString(36).slice(2)}`; + + const dispatcher = { + sendToolResult: vi.fn(() => false), + sendBlockReply: vi.fn(() => false), + sendFinalReply: vi.fn(async () => true), + waitForIdle: vi.fn(async () => {}), + getQueuedCounts: vi.fn(() => ({ tool: 0, block: 0, final: 0 })), + markComplete: vi.fn(), + }; + + createFeishuReplyDispatcherMock.mockReturnValue({ + dispatcher, + replyOptions: {}, + markDispatchIdle: vi.fn(), + }); + + resolveBoundConversationMock.mockReturnValue({ + bindingId: "binding-card", + targetSessionKey: "agent:bound-agent:feishu:direct:ou_user1", + }); + + resolveAgentRouteMock.mockReturnValue({ + agentId: "main", + channel: "feishu", + accountId: "acct-card", + sessionKey: "agent:main:feishu:direct:ou_user1", + mainSessionKey: "agent:main:main", + matchedBy: "default", + }); + + dispatchReplyFromConfigMock.mockImplementation(async ({ dispatcher }) => { + await dispatcher.sendFinalReply({ text: "card action reply once" }); + return { + queuedFinal: false, + counts: { final: 1 }, + }; + }); + + withReplyDispatcherMock.mockImplementation(async ({ run }) => await run()); + + setFeishuRuntime( + createPluginRuntimeMock({ + channel: { + debounce: { + resolveInboundDebounceMs: vi.fn(() => 0), + createInboundDebouncer: (params: { + onFlush?: (items: T[]) => Promise; + onError?: (err: unknown, items: T[]) => void; + }) => ({ + enqueue: async (item: T) => { + try { + await params.onFlush?.([item]); + } catch (err) { + params.onError?.(err, [item]); + } + }, + flushKey: async () => {}, + }), + }, + text: { + hasControlCommand: vi.fn(() => false), + }, + routing: { + resolveAgentRoute: + resolveAgentRouteMock as unknown as PluginRuntime["channel"]["routing"]["resolveAgentRoute"], + }, + reply: { + resolveEnvelopeFormatOptions: vi.fn(() => ({})), + formatAgentEnvelope: vi.fn((params: { body: string }) => params.body), + finalizeInboundContext: + finalizeInboundContextMock as unknown as PluginRuntime["channel"]["reply"]["finalizeInboundContext"], + dispatchReplyFromConfig: + dispatchReplyFromConfigMock as unknown as PluginRuntime["channel"]["reply"]["dispatchReplyFromConfig"], + withReplyDispatcher: + withReplyDispatcherMock as unknown as PluginRuntime["channel"]["reply"]["withReplyDispatcher"], + }, + commands: { + shouldComputeCommandAuthorized: vi.fn(() => false), + resolveCommandAuthorizedFromAuthorizers: vi.fn(() => false), + }, + session: { + readSessionUpdatedAt: vi.fn(), + resolveStorePath: vi.fn(() => "/tmp/feishu-card-action-sessions.json"), + }, + pairing: { + readAllowFromStore: vi.fn().mockResolvedValue([]), + upsertPairingRequest: vi.fn(), + buildPairingReply: vi.fn(), + }, + }, + media: { + detectMime: vi.fn(async () => "text/plain"), + }, + }) as unknown as PluginRuntime, + ); + }); + + afterEach(() => { + if (originalStateDir === undefined) { + delete process.env.OPENCLAW_STATE_DIR; + return; + } + process.env.OPENCLAW_STATE_DIR = originalStateDir; + }); + + it("routes one reply across duplicate callback delivery", async () => { + const onCardAction = await setupLifecycleMonitor(); + const event = createCardActionEvent({ + token: "tok-card-once", + action: "feishu.quick_actions.help", + command: "/help", + }); + + await onCardAction(event); + await settleAsyncWork(); + await onCardAction(event); + await settleAsyncWork(); + + expect(lastRuntime?.error).not.toHaveBeenCalled(); + expect(dispatchReplyFromConfigMock).toHaveBeenCalledTimes(1); + expect(createFeishuReplyDispatcherMock).toHaveBeenCalledTimes(1); + expect(createFeishuReplyDispatcherMock).toHaveBeenCalledWith( + expect.objectContaining({ + accountId: "acct-card", + chatId: "p2p:ou_user1", + replyToMessageId: "card-action-tok-card-once", + }), + ); + expect(finalizeInboundContextMock).toHaveBeenCalledWith( + expect.objectContaining({ + AccountId: "acct-card", + SessionKey: "agent:bound-agent:feishu:direct:ou_user1", + MessageSid: "card-action-tok-card-once", + }), + ); + expect(touchBindingMock).toHaveBeenCalledWith("binding-card"); + + const dispatcher = createFeishuReplyDispatcherMock.mock.results[0]?.value.dispatcher as { + sendFinalReply: ReturnType; + }; + expect(dispatcher.sendFinalReply).toHaveBeenCalledTimes(1); + expect(sendMessageFeishuMock).not.toHaveBeenCalled(); + expect(sendCardFeishuMock).not.toHaveBeenCalled(); + }); + + it("does not duplicate delivery when retrying after a post-send failure", async () => { + const onCardAction = await setupLifecycleMonitor(); + const event = createCardActionEvent({ + token: "tok-card-retry", + action: "feishu.quick_actions.help", + command: "/help", + }); + + dispatchReplyFromConfigMock.mockImplementationOnce(async ({ dispatcher }) => { + await dispatcher.sendFinalReply({ text: "card action reply once" }); + throw new Error("post-send failure"); + }); + + await onCardAction(event); + await settleAsyncWork(); + await onCardAction(event); + await settleAsyncWork(); + + expect(lastRuntime?.error).toHaveBeenCalledTimes(1); + expect(dispatchReplyFromConfigMock).toHaveBeenCalledTimes(1); + + const dispatcher = createFeishuReplyDispatcherMock.mock.results[0]?.value.dispatcher as { + sendFinalReply: ReturnType; + }; + expect(dispatcher.sendFinalReply).toHaveBeenCalledTimes(1); + }); +}); From c7cebd608bbe262d4c9d7e4cc849121485f28924 Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:25:53 -0500 Subject: [PATCH 23/69] test: add Feishu broadcast lifecycle regression --- ...tor.broadcast.reply-once.lifecycle.test.ts | 391 ++++++++++++++++++ 1 file changed, 391 insertions(+) create mode 100644 extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts diff --git a/extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts b/extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts new file mode 100644 index 00000000000..b3eafc2d64b --- /dev/null +++ b/extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts @@ -0,0 +1,391 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { createPluginRuntimeMock } from "../../../test/helpers/extensions/plugin-runtime-mock.js"; +import type { ClawdbotConfig, PluginRuntime, RuntimeEnv } from "../runtime-api.js"; +import { monitorSingleAccount } from "./monitor.account.js"; +import { setFeishuRuntime } from "./runtime.js"; +import type { ResolvedFeishuAccount } from "./types.js"; + +const createEventDispatcherMock = vi.hoisted(() => vi.fn()); +const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); +const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); +const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); +const createFeishuReplyDispatcherMock = vi.hoisted(() => vi.fn()); +const resolveBoundConversationMock = vi.hoisted(() => vi.fn(() => null)); +const touchBindingMock = vi.hoisted(() => vi.fn()); +const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); +const dispatchReplyFromConfigMock = vi.hoisted(() => vi.fn()); +const withReplyDispatcherMock = vi.hoisted(() => vi.fn()); +const finalizeInboundContextMock = vi.hoisted(() => vi.fn((ctx) => ctx)); +const getMessageFeishuMock = vi.hoisted(() => vi.fn(async () => null)); +const listFeishuThreadMessagesMock = vi.hoisted(() => vi.fn(async () => [])); +const sendMessageFeishuMock = vi.hoisted(() => + vi.fn(async () => ({ messageId: "om_sent", chatId: "oc_broadcast_group" })), +); + +let handlersByAccount = new Map Promise>>(); +let runtimesByAccount = new Map(); +const originalStateDir = process.env.OPENCLAW_STATE_DIR; + +vi.mock("./client.js", async () => { + const actual = await vi.importActual("./client.js"); + return { + ...actual, + createEventDispatcher: createEventDispatcherMock, + }; +}); + +vi.mock("./monitor.transport.js", () => ({ + monitorWebSocket: monitorWebSocketMock, + monitorWebhook: monitorWebhookMock, +})); + +vi.mock("./thread-bindings.js", () => ({ + createFeishuThreadBindingManager: createFeishuThreadBindingManagerMock, +})); + +vi.mock("./reply-dispatcher.js", () => ({ + createFeishuReplyDispatcher: createFeishuReplyDispatcherMock, +})); + +vi.mock("./send.js", () => ({ + getMessageFeishu: getMessageFeishuMock, + listFeishuThreadMessages: listFeishuThreadMessagesMock, + sendMessageFeishu: sendMessageFeishuMock, +})); + +vi.mock("openclaw/plugin-sdk/conversation-runtime", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + getSessionBindingService: () => ({ + resolveByConversation: resolveBoundConversationMock, + touch: touchBindingMock, + }), + }; +}); + +vi.mock("../../../src/infra/outbound/session-binding-service.js", () => ({ + getSessionBindingService: () => ({ + resolveByConversation: resolveBoundConversationMock, + touch: touchBindingMock, + }), +})); + +function createLifecycleConfig(): ClawdbotConfig { + return { + broadcast: { + oc_broadcast_group: ["susan", "main"], + }, + agents: { + list: [{ id: "main" }, { id: "susan" }], + }, + channels: { + feishu: { + enabled: true, + groupPolicy: "open", + requireMention: false, + resolveSenderNames: false, + accounts: { + "account-A": { + enabled: true, + appId: "cli_a", + appSecret: "secret_a", // pragma: allowlist secret + connectionMode: "websocket", + groupPolicy: "open", + requireMention: false, + resolveSenderNames: false, + groups: { + oc_broadcast_group: { + requireMention: false, + }, + }, + }, + "account-B": { + enabled: true, + appId: "cli_b", + appSecret: "secret_b", // pragma: allowlist secret + connectionMode: "websocket", + groupPolicy: "open", + requireMention: false, + resolveSenderNames: false, + groups: { + oc_broadcast_group: { + requireMention: false, + }, + }, + }, + }, + }, + }, + messages: { + inbound: { + debounceMs: 0, + byChannel: { + feishu: 0, + }, + }, + }, + } as ClawdbotConfig; +} + +function createLifecycleAccount(accountId: "account-A" | "account-B"): ResolvedFeishuAccount { + return { + accountId, + enabled: true, + configured: true, + appId: accountId === "account-A" ? "cli_a" : "cli_b", + appSecret: accountId === "account-A" ? "secret_a" : "secret_b", // pragma: allowlist secret + domain: "feishu", + config: { + enabled: true, + connectionMode: "websocket", + groupPolicy: "open", + requireMention: false, + resolveSenderNames: false, + groups: { + oc_broadcast_group: { + requireMention: false, + }, + }, + }, + } as ResolvedFeishuAccount; +} + +function createRuntimeEnv(): RuntimeEnv { + return { + log: vi.fn(), + error: vi.fn(), + exit: vi.fn(), + } as RuntimeEnv; +} + +function createBroadcastEvent(messageId: string) { + return { + sender: { + sender_id: { open_id: "ou_sender_1" }, + sender_type: "user", + }, + message: { + message_id: messageId, + chat_id: "oc_broadcast_group", + chat_type: "group" as const, + message_type: "text", + content: JSON.stringify({ text: "hello broadcast" }), + create_time: "1710000000000", + }, + }; +} + +async function settleAsyncWork(): Promise { + for (let i = 0; i < 6; i += 1) { + await Promise.resolve(); + await new Promise((resolve) => setTimeout(resolve, 0)); + } +} + +async function setupLifecycleMonitor(accountId: "account-A" | "account-B") { + const register = vi.fn((registered: Record Promise>) => { + handlersByAccount.set(accountId, registered); + }); + createEventDispatcherMock.mockReturnValueOnce({ register }); + + const runtime = createRuntimeEnv(); + runtimesByAccount.set(accountId, runtime); + + await monitorSingleAccount({ + cfg: createLifecycleConfig(), + account: createLifecycleAccount(accountId), + runtime, + botOpenIdSource: { + kind: "prefetched", + botOpenId: "ou_bot_1", + botName: "Bot", + }, + }); + + const onMessage = handlersByAccount.get(accountId)?.["im.message.receive_v1"]; + if (!onMessage) { + throw new Error(`missing im.message.receive_v1 handler for ${accountId}`); + } + return onMessage; +} + +describe("Feishu broadcast reply-once lifecycle", () => { + beforeEach(() => { + vi.clearAllMocks(); + handlersByAccount = new Map(); + runtimesByAccount = new Map(); + process.env.OPENCLAW_STATE_DIR = `/tmp/openclaw-feishu-broadcast-${Date.now()}-${Math.random().toString(36).slice(2)}`; + + const activeDispatcher = { + sendToolResult: vi.fn(() => false), + sendBlockReply: vi.fn(() => false), + sendFinalReply: vi.fn(async () => true), + waitForIdle: vi.fn(async () => {}), + getQueuedCounts: vi.fn(() => ({ tool: 0, block: 0, final: 0 })), + markComplete: vi.fn(), + }; + + createFeishuReplyDispatcherMock.mockReturnValue({ + dispatcher: activeDispatcher, + replyOptions: {}, + markDispatchIdle: vi.fn(), + }); + + resolveBoundConversationMock.mockReturnValue(null); + resolveAgentRouteMock.mockReturnValue({ + agentId: "main", + channel: "feishu", + accountId: "account-A", + sessionKey: "agent:main:feishu:group:oc_broadcast_group", + mainSessionKey: "agent:main:main", + matchedBy: "default", + }); + + dispatchReplyFromConfigMock.mockImplementation(async ({ ctx, dispatcher }) => { + if ( + typeof ctx?.SessionKey === "string" && + ctx.SessionKey.includes("agent:main:") && + typeof dispatcher?.sendFinalReply === "function" + ) { + await dispatcher.sendFinalReply({ text: "broadcast reply once" }); + } + return { + queuedFinal: false, + counts: { + final: + typeof ctx?.SessionKey === "string" && ctx.SessionKey.includes("agent:main:") ? 1 : 0, + }, + }; + }); + + withReplyDispatcherMock.mockImplementation(async ({ run }) => await run()); + + setFeishuRuntime( + createPluginRuntimeMock({ + channel: { + debounce: { + resolveInboundDebounceMs: vi.fn(() => 0), + createInboundDebouncer: (params: { + onFlush?: (items: T[]) => Promise; + onError?: (err: unknown, items: T[]) => void; + }) => ({ + enqueue: async (item: T) => { + try { + await params.onFlush?.([item]); + } catch (err) { + params.onError?.(err, [item]); + } + }, + flushKey: async () => {}, + }), + }, + text: { + hasControlCommand: vi.fn(() => false), + }, + routing: { + resolveAgentRoute: + resolveAgentRouteMock as unknown as PluginRuntime["channel"]["routing"]["resolveAgentRoute"], + }, + reply: { + resolveEnvelopeFormatOptions: vi.fn(() => ({})), + formatAgentEnvelope: vi.fn((params: { body: string }) => params.body), + finalizeInboundContext: + finalizeInboundContextMock as unknown as PluginRuntime["channel"]["reply"]["finalizeInboundContext"], + dispatchReplyFromConfig: + dispatchReplyFromConfigMock as unknown as PluginRuntime["channel"]["reply"]["dispatchReplyFromConfig"], + withReplyDispatcher: + withReplyDispatcherMock as unknown as PluginRuntime["channel"]["reply"]["withReplyDispatcher"], + }, + commands: { + shouldComputeCommandAuthorized: vi.fn(() => false), + resolveCommandAuthorizedFromAuthorizers: vi.fn(() => false), + }, + session: { + readSessionUpdatedAt: vi.fn(), + resolveStorePath: vi.fn(() => "/tmp/feishu-broadcast-sessions.json"), + }, + pairing: { + readAllowFromStore: vi.fn().mockResolvedValue([]), + upsertPairingRequest: vi.fn(), + buildPairingReply: vi.fn(), + }, + }, + media: { + detectMime: vi.fn(async () => "text/plain"), + }, + }) as unknown as PluginRuntime, + ); + }); + + afterEach(() => { + if (originalStateDir === undefined) { + delete process.env.OPENCLAW_STATE_DIR; + return; + } + process.env.OPENCLAW_STATE_DIR = originalStateDir; + }); + + it("uses one active reply path when the same broadcast event reaches two accounts", async () => { + const onMessageA = await setupLifecycleMonitor("account-A"); + const onMessageB = await setupLifecycleMonitor("account-B"); + const event = createBroadcastEvent("om_broadcast_once"); + + await onMessageA(event); + await settleAsyncWork(); + await onMessageB(event); + await settleAsyncWork(); + + expect(runtimesByAccount.get("account-A")?.error).not.toHaveBeenCalled(); + expect(runtimesByAccount.get("account-B")?.error).not.toHaveBeenCalled(); + + expect(dispatchReplyFromConfigMock).toHaveBeenCalledTimes(2); + expect(createFeishuReplyDispatcherMock).toHaveBeenCalledTimes(1); + expect(createFeishuReplyDispatcherMock).toHaveBeenCalledWith( + expect.objectContaining({ + accountId: "account-a", + chatId: "oc_broadcast_group", + replyToMessageId: "om_broadcast_once", + }), + ); + + const sessionKeys = finalizeInboundContextMock.mock.calls.map( + (call) => (call[0] as { SessionKey?: string }).SessionKey, + ); + expect(sessionKeys).toContain("agent:main:feishu:group:oc_broadcast_group"); + expect(sessionKeys).toContain("agent:susan:feishu:group:oc_broadcast_group"); + + const activeDispatcher = createFeishuReplyDispatcherMock.mock.results[0]?.value.dispatcher as { + sendFinalReply: ReturnType; + }; + expect(activeDispatcher.sendFinalReply).toHaveBeenCalledTimes(1); + }); + + it("does not duplicate delivery after a post-send failure on the first account", async () => { + const onMessageA = await setupLifecycleMonitor("account-A"); + const onMessageB = await setupLifecycleMonitor("account-B"); + const event = createBroadcastEvent("om_broadcast_retry"); + + dispatchReplyFromConfigMock.mockImplementationOnce(async ({ ctx, dispatcher }) => { + if (typeof ctx?.SessionKey === "string" && ctx.SessionKey.includes("agent:susan:")) { + return { queuedFinal: false, counts: { final: 0 } }; + } + await dispatcher.sendFinalReply({ text: "broadcast reply once" }); + throw new Error("post-send failure"); + }); + + await onMessageA(event); + await settleAsyncWork(); + await onMessageB(event); + await settleAsyncWork(); + + expect(runtimesByAccount.get("account-A")?.error).not.toHaveBeenCalled(); + expect(runtimesByAccount.get("account-B")?.error).not.toHaveBeenCalled(); + expect(dispatchReplyFromConfigMock).toHaveBeenCalledTimes(2); + + const activeDispatcher = createFeishuReplyDispatcherMock.mock.results[0]?.value.dispatcher as { + sendFinalReply: ReturnType; + }; + expect(activeDispatcher.sendFinalReply).toHaveBeenCalledTimes(1); + }); +}); From 628b55a825430e2f1bdca38886beeb29d7426bb8 Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:29:52 -0500 Subject: [PATCH 24/69] test: add Feishu ACP failure lifecycle regression --- ...monitor.acp-init-failure.lifecycle.test.ts | 380 ++++++++++++++++++ 1 file changed, 380 insertions(+) create mode 100644 extensions/feishu/src/monitor.acp-init-failure.lifecycle.test.ts diff --git a/extensions/feishu/src/monitor.acp-init-failure.lifecycle.test.ts b/extensions/feishu/src/monitor.acp-init-failure.lifecycle.test.ts new file mode 100644 index 00000000000..922ac97856b --- /dev/null +++ b/extensions/feishu/src/monitor.acp-init-failure.lifecycle.test.ts @@ -0,0 +1,380 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { createPluginRuntimeMock } from "../../../test/helpers/extensions/plugin-runtime-mock.js"; +import type { ClawdbotConfig, PluginRuntime, RuntimeEnv } from "../runtime-api.js"; +import { monitorSingleAccount } from "./monitor.account.js"; +import { setFeishuRuntime } from "./runtime.js"; +import type { ResolvedFeishuAccount } from "./types.js"; + +const createEventDispatcherMock = vi.hoisted(() => vi.fn()); +const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); +const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); +const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); +const resolveBoundConversationMock = vi.hoisted(() => vi.fn(() => null)); +const touchBindingMock = vi.hoisted(() => vi.fn()); +const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); +const resolveConfiguredBindingRouteMock = vi.hoisted(() => vi.fn()); +const ensureConfiguredBindingRouteReadyMock = vi.hoisted(() => vi.fn()); +const dispatchReplyFromConfigMock = vi.hoisted(() => vi.fn()); +const withReplyDispatcherMock = vi.hoisted(() => vi.fn()); +const finalizeInboundContextMock = vi.hoisted(() => vi.fn((ctx) => ctx)); +const sendMessageFeishuMock = vi.hoisted(() => + vi.fn(async () => ({ messageId: "om_notice", chatId: "oc_group_topic" })), +); +const getMessageFeishuMock = vi.hoisted(() => vi.fn(async () => null)); +const listFeishuThreadMessagesMock = vi.hoisted(() => vi.fn(async () => [])); + +let handlers: Record Promise> = {}; +let lastRuntime: RuntimeEnv | null = null; +const originalStateDir = process.env.OPENCLAW_STATE_DIR; + +vi.mock("./client.js", async () => { + const actual = await vi.importActual("./client.js"); + return { + ...actual, + createEventDispatcher: createEventDispatcherMock, + }; +}); + +vi.mock("./monitor.transport.js", () => ({ + monitorWebSocket: monitorWebSocketMock, + monitorWebhook: monitorWebhookMock, +})); + +vi.mock("./thread-bindings.js", () => ({ + createFeishuThreadBindingManager: createFeishuThreadBindingManagerMock, +})); + +vi.mock("./send.js", () => ({ + sendMessageFeishu: sendMessageFeishuMock, + getMessageFeishu: getMessageFeishuMock, + listFeishuThreadMessages: listFeishuThreadMessagesMock, +})); + +vi.mock("openclaw/plugin-sdk/conversation-runtime", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + resolveConfiguredBindingRoute: (params: unknown) => resolveConfiguredBindingRouteMock(params), + ensureConfiguredBindingRouteReady: (params: unknown) => + ensureConfiguredBindingRouteReadyMock(params), + getSessionBindingService: () => ({ + resolveByConversation: resolveBoundConversationMock, + touch: touchBindingMock, + }), + }; +}); + +vi.mock("../../../src/infra/outbound/session-binding-service.js", () => ({ + getSessionBindingService: () => ({ + resolveByConversation: resolveBoundConversationMock, + touch: touchBindingMock, + }), +})); + +function createLifecycleConfig(): ClawdbotConfig { + return { + session: { mainKey: "main", scope: "per-sender" }, + channels: { + feishu: { + enabled: true, + groupPolicy: "open", + requireMention: false, + resolveSenderNames: false, + allowFrom: ["ou_sender_1"], + accounts: { + "acct-acp": { + enabled: true, + appId: "cli_test", + appSecret: "secret_test", // pragma: allowlist secret + connectionMode: "websocket", + groupPolicy: "open", + requireMention: false, + resolveSenderNames: false, + groups: { + oc_group_topic: { + requireMention: false, + groupSessionScope: "group_topic", + replyInThread: "enabled", + }, + }, + }, + }, + }, + }, + messages: { + inbound: { + debounceMs: 0, + byChannel: { + feishu: 0, + }, + }, + }, + } as ClawdbotConfig; +} + +function createLifecycleAccount(): ResolvedFeishuAccount { + return { + accountId: "acct-acp", + enabled: true, + configured: true, + appId: "cli_test", + appSecret: "secret_test", // pragma: allowlist secret + domain: "feishu", + config: { + enabled: true, + connectionMode: "websocket", + groupPolicy: "open", + requireMention: false, + resolveSenderNames: false, + groups: { + oc_group_topic: { + requireMention: false, + groupSessionScope: "group_topic", + replyInThread: "enabled", + }, + }, + allowFrom: ["ou_sender_1"], + }, + } as ResolvedFeishuAccount; +} + +function createRuntimeEnv(): RuntimeEnv { + return { + log: vi.fn(), + error: vi.fn(), + exit: vi.fn(), + } as RuntimeEnv; +} + +function createTopicEvent(messageId: string) { + return { + sender: { + sender_id: { open_id: "ou_sender_1" }, + sender_type: "user", + }, + message: { + message_id: messageId, + root_id: "om_topic_root_1", + thread_id: "omt_topic_1", + chat_id: "oc_group_topic", + chat_type: "group" as const, + message_type: "text", + content: JSON.stringify({ text: "hello topic" }), + create_time: "1710000000000", + }, + }; +} + +async function settleAsyncWork(): Promise { + for (let i = 0; i < 6; i += 1) { + await Promise.resolve(); + await new Promise((resolve) => setTimeout(resolve, 0)); + } +} + +async function setupLifecycleMonitor() { + const register = vi.fn((registered: Record Promise>) => { + handlers = registered; + }); + createEventDispatcherMock.mockReturnValue({ register }); + + lastRuntime = createRuntimeEnv(); + + await monitorSingleAccount({ + cfg: createLifecycleConfig(), + account: createLifecycleAccount(), + runtime: lastRuntime, + botOpenIdSource: { + kind: "prefetched", + botOpenId: "ou_bot_1", + botName: "Bot", + }, + }); + + const onMessage = handlers["im.message.receive_v1"]; + if (!onMessage) { + throw new Error("missing im.message.receive_v1 handler"); + } + return onMessage; +} + +describe("Feishu ACP-init failure lifecycle", () => { + beforeEach(() => { + vi.clearAllMocks(); + handlers = {}; + lastRuntime = null; + process.env.OPENCLAW_STATE_DIR = `/tmp/openclaw-feishu-acp-failure-${Date.now()}-${Math.random().toString(36).slice(2)}`; + + resolveBoundConversationMock.mockReturnValue(null); + resolveAgentRouteMock.mockReturnValue({ + agentId: "main", + channel: "feishu", + accountId: "acct-acp", + sessionKey: "agent:main:feishu:group:oc_group_topic", + mainSessionKey: "agent:main:main", + matchedBy: "default", + }); + resolveConfiguredBindingRouteMock.mockReturnValue({ + bindingResolution: { + configuredBinding: { + spec: { + channel: "feishu", + accountId: "acct-acp", + conversationId: "oc_group_topic:topic:om_topic_root_1", + agentId: "codex", + mode: "persistent", + }, + record: { + bindingId: "config:acp:feishu:acct-acp:oc_group_topic:topic:om_topic_root_1", + targetSessionKey: "agent:codex:acp:binding:feishu:acct-acp:abc123", + targetKind: "session", + conversation: { + channel: "feishu", + accountId: "acct-acp", + conversationId: "oc_group_topic:topic:om_topic_root_1", + parentConversationId: "oc_group_topic", + }, + status: "active", + boundAt: 0, + metadata: { source: "config" }, + }, + }, + statefulTarget: { + kind: "stateful", + driverId: "acp", + sessionKey: "agent:codex:acp:binding:feishu:acct-acp:abc123", + agentId: "codex", + }, + }, + configuredBinding: { + spec: { + channel: "feishu", + accountId: "acct-acp", + conversationId: "oc_group_topic:topic:om_topic_root_1", + agentId: "codex", + mode: "persistent", + }, + }, + route: { + agentId: "codex", + channel: "feishu", + accountId: "acct-acp", + sessionKey: "agent:codex:acp:binding:feishu:acct-acp:abc123", + mainSessionKey: "agent:codex:main", + matchedBy: "binding.channel", + }, + }); + ensureConfiguredBindingRouteReadyMock.mockResolvedValue({ + ok: false, + error: "runtime unavailable", + }); + + dispatchReplyFromConfigMock.mockResolvedValue({ + queuedFinal: false, + counts: { final: 0 }, + }); + withReplyDispatcherMock.mockImplementation(async ({ run }) => await run()); + + setFeishuRuntime( + createPluginRuntimeMock({ + channel: { + debounce: { + resolveInboundDebounceMs: vi.fn(() => 0), + createInboundDebouncer: (params: { + onFlush?: (items: T[]) => Promise; + onError?: (err: unknown, items: T[]) => void; + }) => ({ + enqueue: async (item: T) => { + try { + await params.onFlush?.([item]); + } catch (err) { + params.onError?.(err, [item]); + } + }, + flushKey: async () => {}, + }), + }, + text: { + hasControlCommand: vi.fn(() => false), + }, + routing: { + resolveAgentRoute: + resolveAgentRouteMock as unknown as PluginRuntime["channel"]["routing"]["resolveAgentRoute"], + }, + reply: { + resolveEnvelopeFormatOptions: vi.fn(() => ({})), + formatAgentEnvelope: vi.fn((params: { body: string }) => params.body), + finalizeInboundContext: + finalizeInboundContextMock as unknown as PluginRuntime["channel"]["reply"]["finalizeInboundContext"], + dispatchReplyFromConfig: + dispatchReplyFromConfigMock as unknown as PluginRuntime["channel"]["reply"]["dispatchReplyFromConfig"], + withReplyDispatcher: + withReplyDispatcherMock as unknown as PluginRuntime["channel"]["reply"]["withReplyDispatcher"], + }, + commands: { + shouldComputeCommandAuthorized: vi.fn(() => false), + resolveCommandAuthorizedFromAuthorizers: vi.fn(() => false), + }, + session: { + readSessionUpdatedAt: vi.fn(), + resolveStorePath: vi.fn(() => "/tmp/feishu-acp-failure-sessions.json"), + }, + pairing: { + readAllowFromStore: vi.fn().mockResolvedValue([]), + upsertPairingRequest: vi.fn(), + buildPairingReply: vi.fn(), + }, + }, + media: { + detectMime: vi.fn(async () => "text/plain"), + }, + }) as unknown as PluginRuntime, + ); + }); + + afterEach(() => { + if (originalStateDir === undefined) { + delete process.env.OPENCLAW_STATE_DIR; + return; + } + process.env.OPENCLAW_STATE_DIR = originalStateDir; + }); + + it("sends one ACP failure notice to the topic root across replay", async () => { + const onMessage = await setupLifecycleMonitor(); + const event = createTopicEvent("om_topic_msg_1"); + + await onMessage(event); + await settleAsyncWork(); + await onMessage(event); + await settleAsyncWork(); + + expect(lastRuntime?.error).not.toHaveBeenCalled(); + expect(resolveConfiguredBindingRouteMock).toHaveBeenCalledTimes(1); + expect(ensureConfiguredBindingRouteReadyMock).toHaveBeenCalledTimes(1); + expect(sendMessageFeishuMock).toHaveBeenCalledTimes(1); + expect(sendMessageFeishuMock).toHaveBeenCalledWith( + expect.objectContaining({ + accountId: "acct-acp", + to: "chat:oc_group_topic", + replyToMessageId: "om_topic_root_1", + replyInThread: true, + text: expect.stringContaining("runtime unavailable"), + }), + ); + expect(dispatchReplyFromConfigMock).not.toHaveBeenCalled(); + }); + + it("does not duplicate the ACP failure notice after the first send succeeds", async () => { + const onMessage = await setupLifecycleMonitor(); + const event = createTopicEvent("om_topic_msg_2"); + + await onMessage(event); + await settleAsyncWork(); + await onMessage(event); + await settleAsyncWork(); + + expect(sendMessageFeishuMock).toHaveBeenCalledTimes(1); + expect(lastRuntime?.error).not.toHaveBeenCalled(); + }); +}); From a54d3dc6793c81c62a260abdb59cae5847ec8d2a Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 14:36:57 -0700 Subject: [PATCH 25/69] test(feishu): fix bot-menu binding mock typing --- extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts b/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts index 187d685d919..a01aa67f384 100644 --- a/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts +++ b/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts @@ -10,7 +10,14 @@ const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); const createFeishuReplyDispatcherMock = vi.hoisted(() => vi.fn()); -const resolveBoundConversationMock = vi.hoisted(() => vi.fn(() => null)); +const resolveBoundConversationMock = vi.hoisted(() => + vi.fn< + () => { + bindingId: string; + targetSessionKey: string; + } | null + >(() => null), +); const touchBindingMock = vi.hoisted(() => vi.fn()); const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); const dispatchReplyFromConfigMock = vi.hoisted(() => vi.fn()); From d03c110a0acddeb95c36ef458062f274a696ce68 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 14:37:01 -0700 Subject: [PATCH 26/69] fix(ci): split secrets runtime integration coverage --- src/secrets/runtime.integration.test.ts | 414 ++++++++++++++++++++++ src/secrets/runtime.test.ts | 392 +------------------- test/fixtures/test-parallel.behavior.json | 4 + 3 files changed, 420 insertions(+), 390 deletions(-) create mode 100644 src/secrets/runtime.integration.test.ts diff --git a/src/secrets/runtime.integration.test.ts b/src/secrets/runtime.integration.test.ts new file mode 100644 index 00000000000..f39607cbe80 --- /dev/null +++ b/src/secrets/runtime.integration.test.ts @@ -0,0 +1,414 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; +import { ensureAuthProfileStore, type AuthProfileStore } from "../agents/auth-profiles.js"; +import { + clearConfigCache, + loadConfig, + type OpenClawConfig, + writeConfigFile, +} from "../config/config.js"; +import { withTempHome } from "../config/home-env.test-harness.js"; +import { + activateSecretsRuntimeSnapshot, + clearSecretsRuntimeSnapshot, + getActiveRuntimeWebToolsMetadata, + getActiveSecretsRuntimeSnapshot, + prepareSecretsRuntimeSnapshot, +} from "./runtime.js"; + +const OPENAI_ENV_KEY_REF = { source: "env", provider: "default", id: "OPENAI_API_KEY" } as const; +const allowInsecureTempSecretFile = process.platform === "win32"; + +function asConfig(value: unknown): OpenClawConfig { + return value as OpenClawConfig; +} + +function loadAuthStoreWithProfiles(profiles: AuthProfileStore["profiles"]): AuthProfileStore { + return { + version: 1, + profiles, + }; +} + +describe("secrets runtime snapshot integration", () => { + afterEach(() => { + clearSecretsRuntimeSnapshot(); + clearConfigCache(); + }); + + it("activates runtime snapshots for loadConfig and ensureAuthProfileStore", async () => { + const prepared = await prepareSecretsRuntimeSnapshot({ + config: asConfig({ + models: { + providers: { + openai: { + baseUrl: "https://api.openai.com/v1", + apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" }, + models: [], + }, + }, + }, + }), + env: { OPENAI_API_KEY: "sk-runtime" }, + agentDirs: ["/tmp/openclaw-agent-main"], + loadAuthStore: () => + loadAuthStoreWithProfiles({ + "openai:default": { + type: "api_key", + provider: "openai", + keyRef: OPENAI_ENV_KEY_REF, + }, + }), + }); + + activateSecretsRuntimeSnapshot(prepared); + + expect(loadConfig().models?.providers?.openai?.apiKey).toBe("sk-runtime"); + expect( + ensureAuthProfileStore("/tmp/openclaw-agent-main").profiles["openai:default"], + ).toMatchObject({ + type: "api_key", + key: "sk-runtime", + }); + }); + + it("keeps active secrets runtime snapshots resolved after config writes", async () => { + if (os.platform() === "win32") { + return; + } + await withTempHome("openclaw-secrets-runtime-write-", async (home) => { + const configDir = path.join(home, ".openclaw"); + const secretFile = path.join(configDir, "secrets.json"); + const agentDir = path.join(configDir, "agents", "main", "agent"); + const authStorePath = path.join(agentDir, "auth-profiles.json"); + await fs.mkdir(agentDir, { recursive: true }); + await fs.chmod(configDir, 0o700).catch(() => {}); + await fs.writeFile( + secretFile, + `${JSON.stringify({ providers: { openai: { apiKey: "sk-file-runtime" } } }, null, 2)}\n`, + { encoding: "utf8", mode: 0o600 }, + ); + await fs.writeFile( + authStorePath, + `${JSON.stringify( + { + version: 1, + profiles: { + "openai:default": { + type: "api_key", + provider: "openai", + keyRef: { source: "file", provider: "default", id: "/providers/openai/apiKey" }, + }, + }, + }, + null, + 2, + )}\n`, + { encoding: "utf8", mode: 0o600 }, + ); + + const prepared = await prepareSecretsRuntimeSnapshot({ + config: asConfig({ + secrets: { + providers: { + default: { + source: "file", + path: secretFile, + mode: "json", + ...(allowInsecureTempSecretFile ? { allowInsecurePath: true } : {}), + }, + }, + }, + models: { + providers: { + openai: { + baseUrl: "https://api.openai.com/v1", + apiKey: { source: "file", provider: "default", id: "/providers/openai/apiKey" }, + models: [], + }, + }, + }, + }), + agentDirs: [agentDir], + }); + + activateSecretsRuntimeSnapshot(prepared); + + expect(loadConfig().models?.providers?.openai?.apiKey).toBe("sk-file-runtime"); + expect(ensureAuthProfileStore(agentDir).profiles["openai:default"]).toMatchObject({ + type: "api_key", + key: "sk-file-runtime", + }); + + await writeConfigFile({ + ...loadConfig(), + gateway: { auth: { mode: "token" } }, + }); + + expect(loadConfig().gateway?.auth).toEqual({ mode: "token" }); + expect(loadConfig().models?.providers?.openai?.apiKey).toBe("sk-file-runtime"); + expect(ensureAuthProfileStore(agentDir).profiles["openai:default"]).toMatchObject({ + type: "api_key", + key: "sk-file-runtime", + }); + }); + }); + + it("keeps last-known-good runtime snapshot active when refresh fails after a write", async () => { + if (os.platform() === "win32") { + return; + } + await withTempHome("openclaw-secrets-runtime-refresh-fail-", async (home) => { + const configDir = path.join(home, ".openclaw"); + const secretFile = path.join(configDir, "secrets.json"); + const agentDir = path.join(configDir, "agents", "main", "agent"); + const authStorePath = path.join(agentDir, "auth-profiles.json"); + await fs.mkdir(agentDir, { recursive: true }); + await fs.chmod(configDir, 0o700).catch(() => {}); + await fs.writeFile( + secretFile, + `${JSON.stringify({ providers: { openai: { apiKey: "sk-file-runtime" } } }, null, 2)}\n`, + { encoding: "utf8", mode: 0o600 }, + ); + await fs.writeFile( + authStorePath, + `${JSON.stringify( + { + version: 1, + profiles: { + "openai:default": { + type: "api_key", + provider: "openai", + keyRef: { source: "file", provider: "default", id: "/providers/openai/apiKey" }, + }, + }, + }, + null, + 2, + )}\n`, + { encoding: "utf8", mode: 0o600 }, + ); + + let loadAuthStoreCalls = 0; + const loadAuthStore = () => { + loadAuthStoreCalls += 1; + if (loadAuthStoreCalls > 1) { + throw new Error("simulated secrets runtime refresh failure"); + } + return loadAuthStoreWithProfiles({ + "openai:default": { + type: "api_key", + provider: "openai", + keyRef: { source: "file", provider: "default", id: "/providers/openai/apiKey" }, + }, + }); + }; + + const prepared = await prepareSecretsRuntimeSnapshot({ + config: asConfig({ + secrets: { + providers: { + default: { + source: "file", + path: secretFile, + mode: "json", + ...(allowInsecureTempSecretFile ? { allowInsecurePath: true } : {}), + }, + }, + }, + models: { + providers: { + openai: { + baseUrl: "https://api.openai.com/v1", + apiKey: { source: "file", provider: "default", id: "/providers/openai/apiKey" }, + models: [], + }, + }, + }, + }), + agentDirs: [agentDir], + loadAuthStore, + }); + + activateSecretsRuntimeSnapshot(prepared); + + await expect( + writeConfigFile({ + ...loadConfig(), + gateway: { auth: { mode: "token" } }, + }), + ).rejects.toThrow( + /runtime snapshot refresh failed: simulated secrets runtime refresh failure/i, + ); + + const activeAfterFailure = getActiveSecretsRuntimeSnapshot(); + expect(activeAfterFailure).not.toBeNull(); + expect(loadConfig().gateway?.auth).toBeUndefined(); + expect(loadConfig().models?.providers?.openai?.apiKey).toBe("sk-file-runtime"); + expect(activeAfterFailure?.sourceConfig.models?.providers?.openai?.apiKey).toEqual({ + source: "file", + provider: "default", + id: "/providers/openai/apiKey", + }); + expect(ensureAuthProfileStore(agentDir).profiles["openai:default"]).toMatchObject({ + type: "api_key", + key: "sk-file-runtime", + }); + }); + }); + + it("keeps last-known-good web runtime snapshot when reload introduces unresolved active web refs", async () => { + await withTempHome("openclaw-secrets-runtime-web-reload-lkg-", async (home) => { + const prepared = await prepareSecretsRuntimeSnapshot({ + config: asConfig({ + tools: { + web: { + search: { + provider: "gemini", + gemini: { + apiKey: { source: "env", provider: "default", id: "WEB_SEARCH_GEMINI_API_KEY" }, + }, + }, + }, + }, + }), + env: { + WEB_SEARCH_GEMINI_API_KEY: "web-search-gemini-runtime-key", + }, + agentDirs: ["/tmp/openclaw-agent-main"], + loadAuthStore: () => ({ version: 1, profiles: {} }), + }); + + activateSecretsRuntimeSnapshot(prepared); + + await expect( + writeConfigFile({ + ...loadConfig(), + plugins: { + entries: { + google: { + config: { + webSearch: { + apiKey: { + source: "env", + provider: "default", + id: "MISSING_WEB_SEARCH_GEMINI_API_KEY", + }, + }, + }, + }, + }, + }, + tools: { + web: { + search: { + provider: "gemini", + gemini: { + apiKey: { + source: "env", + provider: "default", + id: "MISSING_WEB_SEARCH_GEMINI_API_KEY", + }, + }, + }, + }, + }, + }), + ).rejects.toThrow( + /runtime snapshot refresh failed: .*WEB_SEARCH_KEY_UNRESOLVED_NO_FALLBACK/i, + ); + + const activeAfterFailure = getActiveSecretsRuntimeSnapshot(); + expect(activeAfterFailure).not.toBeNull(); + expect(loadConfig().tools?.web?.search?.gemini?.apiKey).toBe("web-search-gemini-runtime-key"); + expect(activeAfterFailure?.sourceConfig.tools?.web?.search?.gemini?.apiKey).toEqual({ + source: "env", + provider: "default", + id: "WEB_SEARCH_GEMINI_API_KEY", + }); + expect(getActiveRuntimeWebToolsMetadata()?.search.selectedProvider).toBe("gemini"); + + const persistedConfig = JSON.parse( + await fs.readFile(path.join(home, ".openclaw", "openclaw.json"), "utf8"), + ) as OpenClawConfig; + const persistedGoogleWebSearchConfig = persistedConfig.plugins?.entries?.google?.config as + | { webSearch?: { apiKey?: unknown } } + | undefined; + expect(persistedGoogleWebSearchConfig?.webSearch?.apiKey).toEqual({ + source: "env", + provider: "default", + id: "MISSING_WEB_SEARCH_GEMINI_API_KEY", + }); + }); + }, 180_000); + + it("recomputes config-derived agent dirs when refreshing active secrets runtime snapshots", async () => { + await withTempHome("openclaw-secrets-runtime-agent-dirs-", async (home) => { + const mainAgentDir = path.join(home, ".openclaw", "agents", "main", "agent"); + const opsAgentDir = path.join(home, ".openclaw", "agents", "ops", "agent"); + await fs.mkdir(mainAgentDir, { recursive: true }); + await fs.mkdir(opsAgentDir, { recursive: true }); + await fs.writeFile( + path.join(mainAgentDir, "auth-profiles.json"), + `${JSON.stringify( + { + version: 1, + profiles: { + "openai:default": { + type: "api_key", + provider: "openai", + keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }, + }, + }, + }, + null, + 2, + )}\n`, + { encoding: "utf8", mode: 0o600 }, + ); + await fs.writeFile( + path.join(opsAgentDir, "auth-profiles.json"), + `${JSON.stringify( + { + version: 1, + profiles: { + "anthropic:ops": { + type: "api_key", + provider: "anthropic", + keyRef: { source: "env", provider: "default", id: "ANTHROPIC_API_KEY" }, + }, + }, + }, + null, + 2, + )}\n`, + { encoding: "utf8", mode: 0o600 }, + ); + + const prepared = await prepareSecretsRuntimeSnapshot({ + config: asConfig({}), + env: { + OPENAI_API_KEY: "sk-main-runtime", + ANTHROPIC_API_KEY: "sk-ops-runtime", + }, + }); + + activateSecretsRuntimeSnapshot(prepared); + expect(ensureAuthProfileStore(opsAgentDir).profiles["anthropic:ops"]).toBeUndefined(); + + await writeConfigFile({ + agents: { + list: [{ id: "ops", agentDir: opsAgentDir }], + }, + }); + + expect(ensureAuthProfileStore(opsAgentDir).profiles["anthropic:ops"]).toMatchObject({ + type: "api_key", + key: "sk-ops-runtime", + keyRef: { source: "env", provider: "default", id: "ANTHROPIC_API_KEY" }, + }); + }); + }); +}); diff --git a/src/secrets/runtime.test.ts b/src/secrets/runtime.test.ts index 92e942ab12f..b4f26f3e9a8 100644 --- a/src/secrets/runtime.test.ts +++ b/src/secrets/runtime.test.ts @@ -2,20 +2,13 @@ import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; -import { ensureAuthProfileStore, type AuthProfileStore } from "../agents/auth-profiles.js"; -import { - clearConfigCache, - loadConfig, - type OpenClawConfig, - writeConfigFile, -} from "../config/config.js"; -import { withTempHome } from "../config/home-env.test-harness.js"; +import type { AuthProfileStore } from "../agents/auth-profiles.js"; +import { clearConfigCache, type OpenClawConfig } from "../config/config.js"; import type { PluginWebSearchProviderEntry } from "../plugins/types.js"; import { activateSecretsRuntimeSnapshot, clearSecretsRuntimeSnapshot, getActiveRuntimeWebToolsMetadata, - getActiveSecretsRuntimeSnapshot, prepareSecretsRuntimeSnapshot, } from "./runtime.js"; @@ -130,8 +123,6 @@ describe("secrets runtime snapshot", () => { resolvePluginWebSearchProvidersMock.mockReset(); }); - const allowInsecureTempSecretFile = process.platform === "win32"; - it("resolves env refs for config and auth profiles", async () => { const config = asConfig({ agents: { @@ -731,385 +722,6 @@ describe("secrets runtime snapshot", () => { } }); - it("activates runtime snapshots for loadConfig and ensureAuthProfileStore", async () => { - const prepared = await prepareSecretsRuntimeSnapshot({ - config: asConfig({ - models: { - providers: { - openai: { - baseUrl: "https://api.openai.com/v1", - apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" }, - models: [], - }, - }, - }, - }), - env: { OPENAI_API_KEY: "sk-runtime" }, // pragma: allowlist secret - agentDirs: ["/tmp/openclaw-agent-main"], - loadAuthStore: () => - loadAuthStoreWithProfiles({ - "openai:default": { - type: "api_key", - provider: "openai", - keyRef: OPENAI_ENV_KEY_REF, - }, - }), - }); - - activateSecretsRuntimeSnapshot(prepared); - - expect(loadConfig().models?.providers?.openai?.apiKey).toBe("sk-runtime"); - const store = ensureAuthProfileStore("/tmp/openclaw-agent-main"); - expect(store.profiles["openai:default"]).toMatchObject({ - type: "api_key", - key: "sk-runtime", - }); - }); - - it("keeps active secrets runtime snapshots resolved after config writes", async () => { - if (os.platform() === "win32") { - return; - } - await withTempHome("openclaw-secrets-runtime-write-", async (home) => { - const configDir = path.join(home, ".openclaw"); - const secretFile = path.join(configDir, "secrets.json"); - const agentDir = path.join(configDir, "agents", "main", "agent"); - const authStorePath = path.join(agentDir, "auth-profiles.json"); - await fs.mkdir(agentDir, { recursive: true }); - await fs.chmod(configDir, 0o700).catch(() => { - // best-effort on tmp dirs that already have secure perms - }); - await fs.writeFile( - secretFile, - `${JSON.stringify({ providers: { openai: { apiKey: "sk-file-runtime" } } }, null, 2)}\n`, // pragma: allowlist secret - { encoding: "utf8", mode: 0o600 }, - ); - await fs.writeFile( - authStorePath, - `${JSON.stringify( - { - version: 1, - profiles: { - "openai:default": { - type: "api_key", - provider: "openai", - keyRef: { source: "file", provider: "default", id: "/providers/openai/apiKey" }, - }, - }, - }, - null, - 2, - )}\n`, - { encoding: "utf8", mode: 0o600 }, - ); - - const prepared = await prepareSecretsRuntimeSnapshot({ - config: asConfig({ - secrets: { - providers: { - default: { - source: "file", - path: secretFile, - mode: "json", - ...(allowInsecureTempSecretFile ? { allowInsecurePath: true } : {}), - }, - }, - }, - models: { - providers: { - openai: { - baseUrl: "https://api.openai.com/v1", - apiKey: { source: "file", provider: "default", id: "/providers/openai/apiKey" }, - models: [], - }, - }, - }, - }), - agentDirs: [agentDir], - }); - - activateSecretsRuntimeSnapshot(prepared); - - expect(loadConfig().models?.providers?.openai?.apiKey).toBe("sk-file-runtime"); - expect(ensureAuthProfileStore(agentDir).profiles["openai:default"]).toMatchObject({ - type: "api_key", - key: "sk-file-runtime", - }); - - await writeConfigFile({ - ...loadConfig(), - gateway: { auth: { mode: "token" } }, - }); - - expect(loadConfig().gateway?.auth).toEqual({ mode: "token" }); - expect(loadConfig().models?.providers?.openai?.apiKey).toBe("sk-file-runtime"); - expect(ensureAuthProfileStore(agentDir).profiles["openai:default"]).toMatchObject({ - type: "api_key", - key: "sk-file-runtime", - }); - }); - }); - - it("keeps last-known-good runtime snapshot active when refresh fails after a write", async () => { - if (os.platform() === "win32") { - return; - } - await withTempHome("openclaw-secrets-runtime-refresh-fail-", async (home) => { - const configDir = path.join(home, ".openclaw"); - const secretFile = path.join(configDir, "secrets.json"); - const agentDir = path.join(configDir, "agents", "main", "agent"); - const authStorePath = path.join(agentDir, "auth-profiles.json"); - await fs.mkdir(agentDir, { recursive: true }); - await fs.chmod(configDir, 0o700).catch(() => { - // best-effort on tmp dirs that already have secure perms - }); - await fs.writeFile( - secretFile, - `${JSON.stringify({ providers: { openai: { apiKey: "sk-file-runtime" } } }, null, 2)}\n`, // pragma: allowlist secret - { encoding: "utf8", mode: 0o600 }, - ); - await fs.writeFile( - authStorePath, - `${JSON.stringify( - { - version: 1, - profiles: { - "openai:default": { - type: "api_key", - provider: "openai", - keyRef: { source: "file", provider: "default", id: "/providers/openai/apiKey" }, - }, - }, - }, - null, - 2, - )}\n`, - { encoding: "utf8", mode: 0o600 }, - ); - - let loadAuthStoreCalls = 0; - const loadAuthStore = () => { - loadAuthStoreCalls += 1; - if (loadAuthStoreCalls > 1) { - throw new Error("simulated secrets runtime refresh failure"); - } - return loadAuthStoreWithProfiles({ - "openai:default": { - type: "api_key", - provider: "openai", - keyRef: { source: "file", provider: "default", id: "/providers/openai/apiKey" }, - }, - }); - }; - - const prepared = await prepareSecretsRuntimeSnapshot({ - config: asConfig({ - secrets: { - providers: { - default: { - source: "file", - path: secretFile, - mode: "json", - ...(allowInsecureTempSecretFile ? { allowInsecurePath: true } : {}), - }, - }, - }, - models: { - providers: { - openai: { - baseUrl: "https://api.openai.com/v1", - apiKey: { source: "file", provider: "default", id: "/providers/openai/apiKey" }, - models: [], - }, - }, - }, - }), - agentDirs: [agentDir], - loadAuthStore, - }); - - activateSecretsRuntimeSnapshot(prepared); - - await expect( - writeConfigFile({ - ...loadConfig(), - gateway: { auth: { mode: "token" } }, - }), - ).rejects.toThrow( - /runtime snapshot refresh failed: simulated secrets runtime refresh failure/i, - ); - - const activeAfterFailure = getActiveSecretsRuntimeSnapshot(); - expect(activeAfterFailure).not.toBeNull(); - expect(loadConfig().gateway?.auth).toBeUndefined(); - expect(loadConfig().models?.providers?.openai?.apiKey).toBe("sk-file-runtime"); - expect(activeAfterFailure?.sourceConfig.models?.providers?.openai?.apiKey).toEqual({ - source: "file", - provider: "default", - id: "/providers/openai/apiKey", - }); - - const persistedStore = ensureAuthProfileStore(agentDir).profiles["openai:default"]; - expect(persistedStore).toMatchObject({ - type: "api_key", - key: "sk-file-runtime", - }); - }); - }); - - it("keeps last-known-good web runtime snapshot when reload introduces unresolved active web refs", async () => { - await withTempHome("openclaw-secrets-runtime-web-reload-lkg-", async (home) => { - const prepared = await prepareSecretsRuntimeSnapshot({ - config: asConfig({ - tools: { - web: { - search: { - provider: "gemini", - gemini: { - apiKey: { source: "env", provider: "default", id: "WEB_SEARCH_GEMINI_API_KEY" }, - }, - }, - }, - }, - }), - env: { - WEB_SEARCH_GEMINI_API_KEY: "web-search-gemini-runtime-key", // pragma: allowlist secret - }, - agentDirs: ["/tmp/openclaw-agent-main"], - loadAuthStore: () => ({ version: 1, profiles: {} }), - }); - - activateSecretsRuntimeSnapshot(prepared); - - await expect( - writeConfigFile({ - ...loadConfig(), - plugins: { - entries: { - google: { - config: { - webSearch: { - apiKey: { - source: "env", - provider: "default", - id: "MISSING_WEB_SEARCH_GEMINI_API_KEY", - }, - }, - }, - }, - }, - }, - tools: { - web: { - search: { - provider: "gemini", - gemini: { - apiKey: { - source: "env", - provider: "default", - id: "MISSING_WEB_SEARCH_GEMINI_API_KEY", - }, - }, - }, - }, - }, - }), - ).rejects.toThrow( - /runtime snapshot refresh failed: .*WEB_SEARCH_KEY_UNRESOLVED_NO_FALLBACK/i, - ); - - const activeAfterFailure = getActiveSecretsRuntimeSnapshot(); - expect(activeAfterFailure).not.toBeNull(); - expect(loadConfig().tools?.web?.search?.gemini?.apiKey).toBe("web-search-gemini-runtime-key"); - expect(activeAfterFailure?.sourceConfig.tools?.web?.search?.gemini?.apiKey).toEqual({ - source: "env", - provider: "default", - id: "WEB_SEARCH_GEMINI_API_KEY", - }); - expect(getActiveRuntimeWebToolsMetadata()?.search.selectedProvider).toBe("gemini"); - - const persistedConfig = JSON.parse( - await fs.readFile(path.join(home, ".openclaw", "openclaw.json"), "utf8"), - ) as OpenClawConfig; - const persistedGoogleWebSearchConfig = persistedConfig.plugins?.entries?.google?.config as - | { webSearch?: { apiKey?: unknown } } - | undefined; - expect(persistedGoogleWebSearchConfig?.webSearch?.apiKey).toEqual({ - source: "env", - provider: "default", - id: "MISSING_WEB_SEARCH_GEMINI_API_KEY", - }); - }); - }); - - it("recomputes config-derived agent dirs when refreshing active secrets runtime snapshots", async () => { - await withTempHome("openclaw-secrets-runtime-agent-dirs-", async (home) => { - const mainAgentDir = path.join(home, ".openclaw", "agents", "main", "agent"); - const opsAgentDir = path.join(home, ".openclaw", "agents", "ops", "agent"); - await fs.mkdir(mainAgentDir, { recursive: true }); - await fs.mkdir(opsAgentDir, { recursive: true }); - await fs.writeFile( - path.join(mainAgentDir, "auth-profiles.json"), - `${JSON.stringify( - { - version: 1, - profiles: { - "openai:default": { - type: "api_key", - provider: "openai", - keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }, - }, - }, - }, - null, - 2, - )}\n`, - { encoding: "utf8", mode: 0o600 }, - ); - await fs.writeFile( - path.join(opsAgentDir, "auth-profiles.json"), - `${JSON.stringify( - { - version: 1, - profiles: { - "anthropic:ops": { - type: "api_key", - provider: "anthropic", - keyRef: { source: "env", provider: "default", id: "ANTHROPIC_API_KEY" }, - }, - }, - }, - null, - 2, - )}\n`, - { encoding: "utf8", mode: 0o600 }, - ); - - const prepared = await prepareSecretsRuntimeSnapshot({ - config: asConfig({}), - env: { - OPENAI_API_KEY: "sk-main-runtime", // pragma: allowlist secret - ANTHROPIC_API_KEY: "sk-ops-runtime", // pragma: allowlist secret - }, - }); - - activateSecretsRuntimeSnapshot(prepared); - expect(ensureAuthProfileStore(opsAgentDir).profiles["anthropic:ops"]).toBeUndefined(); - - await writeConfigFile({ - agents: { - list: [{ id: "ops", agentDir: opsAgentDir }], - }, - }); - - expect(ensureAuthProfileStore(opsAgentDir).profiles["anthropic:ops"]).toMatchObject({ - type: "api_key", - key: "sk-ops-runtime", - keyRef: { source: "env", provider: "default", id: "ANTHROPIC_API_KEY" }, - }); - }); - }); - it("skips inactive-surface refs and emits diagnostics", async () => { const config = asConfig({ agents: { diff --git a/test/fixtures/test-parallel.behavior.json b/test/fixtures/test-parallel.behavior.json index 3f28709511f..f0585bd0249 100644 --- a/test/fixtures/test-parallel.behavior.json +++ b/test/fixtures/test-parallel.behavior.json @@ -31,6 +31,10 @@ "file": "src/secrets/runtime.test.ts", "reason": "Secrets runtime coverage retained the largest unit-fast heap spike in CI and is safer outside the shared lane." }, + { + "file": "src/secrets/runtime.integration.test.ts", + "reason": "Secrets runtime activation/write-through integration coverage is CPU-heavy and safer outside the shared unit-fast lane." + }, { "file": "src/memory/index.test.ts", "reason": "Memory index coverage retained nearly 1 GiB in unit-fast on Linux CI and is safer in its own fork." From ec2278192db366de601badffdc9a9983945ad526 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 14:39:22 -0700 Subject: [PATCH 27/69] fix(ci): reduce test runtime retention hotspots --- src/infra/channel-summary.test.ts | 13 ++------ src/memory/qmd-manager.test.ts | 49 +++++++++++++++++++++---------- 2 files changed, 37 insertions(+), 25 deletions(-) diff --git a/src/infra/channel-summary.test.ts b/src/infra/channel-summary.test.ts index 24eb8ca966d..01a4450a640 100644 --- a/src/infra/channel-summary.test.ts +++ b/src/infra/channel-summary.test.ts @@ -1,19 +1,12 @@ -import { beforeEach, describe, expect, it, vi } from "vitest"; +import { describe, expect, it, vi } from "vitest"; +import { listChannelPlugins } from "../channels/plugins/index.js"; import type { ChannelPlugin } from "../channels/plugins/types.js"; +import { buildChannelSummary } from "./channel-summary.js"; vi.mock("../channels/plugins/index.js", () => ({ listChannelPlugins: vi.fn(), })); -let buildChannelSummary: typeof import("./channel-summary.js").buildChannelSummary; -let listChannelPlugins: typeof import("../channels/plugins/index.js").listChannelPlugins; - -beforeEach(async () => { - vi.resetModules(); - ({ buildChannelSummary } = await import("./channel-summary.js")); - ({ listChannelPlugins } = await import("../channels/plugins/index.js")); -}); - function makeSlackHttpSummaryPlugin(): ChannelPlugin { return { id: "slack", diff --git a/src/memory/qmd-manager.test.ts b/src/memory/qmd-manager.test.ts index 0f08affe6a0..f283459c61d 100644 --- a/src/memory/qmd-manager.test.ts +++ b/src/memory/qmd-manager.test.ts @@ -104,16 +104,26 @@ describe("QmdMemoryManager", () => { let stateDir: string; let cfg: OpenClawConfig; const agentId = "main"; + const openManagers = new Set(); + + function trackManager(manager: T): T { + if (manager) { + openManagers.add(manager); + } + return manager; + } async function createManager(params?: { mode?: "full" | "status"; cfg?: OpenClawConfig }) { const cfgToUse = params?.cfg ?? cfg; const resolved = resolveMemoryBackendConfig({ cfg: cfgToUse, agentId }); - const manager = await QmdMemoryManager.create({ - cfg: cfgToUse, - agentId, - resolved, - mode: params?.mode ?? "status", - }); + const manager = trackManager( + await QmdMemoryManager.create({ + cfg: cfgToUse, + agentId, + resolved, + mode: params?.mode ?? "status", + }), + ); expect(manager).toBeTruthy(); if (!manager) { throw new Error("manager missing"); @@ -161,7 +171,14 @@ describe("QmdMemoryManager", () => { } as OpenClawConfig; }); - afterEach(() => { + afterEach(async () => { + await Promise.all( + Array.from(openManagers, async (manager) => { + await manager.close(); + }), + ); + openManagers.clear(); + await fs.rm(tmpRoot, { recursive: true, force: true }); vi.useRealTimers(); delete process.env.OPENCLAW_STATE_DIR; if (originalPath === undefined) { @@ -365,12 +382,14 @@ describe("QmdMemoryManager", () => { }); const resolved = resolveMemoryBackendConfig({ cfg, agentId: devAgentId }); - const manager = await QmdMemoryManager.create({ - cfg, - agentId: devAgentId, - resolved, - mode: "full", - }); + const manager = trackManager( + await QmdMemoryManager.create({ + cfg, + agentId: devAgentId, + resolved, + mode: "full", + }), + ); expect(manager).toBeTruthy(); await manager?.close(); @@ -755,7 +774,7 @@ describe("QmdMemoryManager", () => { const resolved = resolveMemoryBackendConfig({ cfg, agentId }); const createPromise = QmdMemoryManager.create({ cfg, agentId, resolved, mode: "status" }); await vi.advanceTimersByTimeAsync(0); - const manager = await createPromise; + const manager = trackManager(await createPromise); expect(manager).toBeTruthy(); if (!manager) { throw new Error("manager missing"); @@ -1985,7 +2004,7 @@ describe("QmdMemoryManager", () => { const resolved = resolveMemoryBackendConfig({ cfg, agentId }); const createPromise = QmdMemoryManager.create({ cfg, agentId, resolved, mode: "status" }); await vi.advanceTimersByTimeAsync(0); - const manager = await createPromise; + const manager = trackManager(await createPromise); expect(manager).toBeTruthy(); if (!manager) { throw new Error("manager missing"); From 38807fff208edcb3656e1f8a9d960c70a4f9116b Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 14:43:38 -0700 Subject: [PATCH 28/69] fix(ci): split plugin sdk bundle coverage --- src/plugin-sdk/index.bundle.test.ts | 106 ++++++++++++++++++++++ src/plugin-sdk/index.test.ts | 102 +-------------------- test/fixtures/test-parallel.behavior.json | 4 + 3 files changed, 111 insertions(+), 101 deletions(-) create mode 100644 src/plugin-sdk/index.bundle.test.ts diff --git a/src/plugin-sdk/index.bundle.test.ts b/src/plugin-sdk/index.bundle.test.ts new file mode 100644 index 00000000000..1f3afc8ab3a --- /dev/null +++ b/src/plugin-sdk/index.bundle.test.ts @@ -0,0 +1,106 @@ +import { execFile } from "node:child_process"; +import fs from "node:fs/promises"; +import { createRequire } from "node:module"; +import os from "node:os"; +import path from "node:path"; +import { pathToFileURL } from "node:url"; +import { promisify } from "node:util"; +import { describe, expect, it } from "vitest"; +import { + buildPluginSdkEntrySources, + buildPluginSdkPackageExports, + buildPluginSdkSpecifiers, + pluginSdkEntrypoints, +} from "./entrypoints.js"; + +const pluginSdkSpecifiers = buildPluginSdkSpecifiers(); +const execFileAsync = promisify(execFile); +const require = createRequire(import.meta.url); +const tsdownModuleUrl = pathToFileURL(require.resolve("tsdown")).href; + +describe("plugin-sdk bundled exports", () => { + it("emits importable bundled subpath entries", { timeout: 240_000 }, async () => { + const outDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-plugin-sdk-build-")); + const fixtureDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-plugin-sdk-consumer-")); + + try { + const buildScriptPath = path.join(fixtureDir, "build-plugin-sdk.mjs"); + await fs.writeFile( + buildScriptPath, + `import { build } from ${JSON.stringify(tsdownModuleUrl)}; +await build(${JSON.stringify({ + clean: true, + config: false, + dts: false, + entry: buildPluginSdkEntrySources(), + env: { NODE_ENV: "production" }, + fixedExtension: false, + logLevel: "error", + outDir, + platform: "node", + })}); +`, + ); + await execFileAsync(process.execPath, [buildScriptPath], { + cwd: process.cwd(), + }); + await fs.symlink( + path.join(process.cwd(), "node_modules"), + path.join(outDir, "node_modules"), + "dir", + ); + + for (const entry of pluginSdkEntrypoints) { + const module = await import(pathToFileURL(path.join(outDir, `${entry}.js`)).href); + expect(module).toBeTypeOf("object"); + } + + const packageDir = path.join(fixtureDir, "openclaw"); + const consumerDir = path.join(fixtureDir, "consumer"); + const consumerEntry = path.join(consumerDir, "import-plugin-sdk.mjs"); + + await fs.mkdir(path.join(packageDir, "dist"), { recursive: true }); + await fs.symlink(outDir, path.join(packageDir, "dist", "plugin-sdk"), "dir"); + // Mirror the installed package layout so subpaths can resolve root deps. + await fs.symlink( + path.join(process.cwd(), "node_modules"), + path.join(packageDir, "node_modules"), + "dir", + ); + await fs.writeFile( + path.join(packageDir, "package.json"), + JSON.stringify( + { + exports: buildPluginSdkPackageExports(), + name: "openclaw", + type: "module", + }, + null, + 2, + ), + ); + + await fs.mkdir(path.join(consumerDir, "node_modules"), { recursive: true }); + await fs.symlink(packageDir, path.join(consumerDir, "node_modules", "openclaw"), "dir"); + await fs.writeFile( + consumerEntry, + [ + `const specifiers = ${JSON.stringify(pluginSdkSpecifiers)};`, + "const results = {};", + "for (const specifier of specifiers) {", + " results[specifier] = typeof (await import(specifier));", + "}", + "export default results;", + ].join("\n"), + ); + + const { default: importResults } = await import(pathToFileURL(consumerEntry).href); + expect(importResults).toEqual( + Object.fromEntries(pluginSdkSpecifiers.map((specifier: string) => [specifier, "object"])), + ); + } finally { + await fs.rm(outDir, { recursive: true, force: true }); + await fs.rm(fixtureDir, { recursive: true, force: true }); + } + }); +}); diff --git a/src/plugin-sdk/index.test.ts b/src/plugin-sdk/index.test.ts index 89ca3901ff3..30040416729 100644 --- a/src/plugin-sdk/index.test.ts +++ b/src/plugin-sdk/index.test.ts @@ -1,24 +1,9 @@ -import { execFile } from "node:child_process"; import fs from "node:fs/promises"; -import { createRequire } from "node:module"; -import os from "node:os"; import path from "node:path"; -import { pathToFileURL } from "node:url"; -import { promisify } from "node:util"; import { describe, expect, it } from "vitest"; -import { - buildPluginSdkEntrySources, - buildPluginSdkPackageExports, - buildPluginSdkSpecifiers, - pluginSdkEntrypoints, -} from "./entrypoints.js"; +import { buildPluginSdkPackageExports } from "./entrypoints.js"; import * as sdk from "./index.js"; -const pluginSdkSpecifiers = buildPluginSdkSpecifiers(); -const execFileAsync = promisify(execFile); -const require = createRequire(import.meta.url); -const tsdownModuleUrl = pathToFileURL(require.resolve("tsdown")).href; - describe("plugin-sdk exports", () => { it("does not expose runtime modules", () => { const forbidden = [ @@ -70,91 +55,6 @@ describe("plugin-sdk exports", () => { expect(Object.prototype.hasOwnProperty.call(sdk, "isDangerousNameMatchingEnabled")).toBe(false); }); - it("emits importable bundled subpath entries", { timeout: 240_000 }, async () => { - const outDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-plugin-sdk-build-")); - const fixtureDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-plugin-sdk-consumer-")); - - try { - const buildScriptPath = path.join(fixtureDir, "build-plugin-sdk.mjs"); - await fs.writeFile( - buildScriptPath, - `import { build } from ${JSON.stringify(tsdownModuleUrl)}; -await build(${JSON.stringify({ - clean: true, - config: false, - dts: false, - entry: buildPluginSdkEntrySources(), - env: { NODE_ENV: "production" }, - fixedExtension: false, - logLevel: "error", - outDir, - platform: "node", - })}); -`, - ); - await execFileAsync(process.execPath, [buildScriptPath], { - cwd: process.cwd(), - }); - await fs.symlink( - path.join(process.cwd(), "node_modules"), - path.join(outDir, "node_modules"), - "dir", - ); - - for (const entry of pluginSdkEntrypoints) { - const module = await import(pathToFileURL(path.join(outDir, `${entry}.js`)).href); - expect(module).toBeTypeOf("object"); - } - - const packageDir = path.join(fixtureDir, "openclaw"); - const consumerDir = path.join(fixtureDir, "consumer"); - const consumerEntry = path.join(consumerDir, "import-plugin-sdk.mjs"); - - await fs.mkdir(path.join(packageDir, "dist"), { recursive: true }); - await fs.symlink(outDir, path.join(packageDir, "dist", "plugin-sdk"), "dir"); - // Mirror the installed package layout so subpaths can resolve root deps. - await fs.symlink( - path.join(process.cwd(), "node_modules"), - path.join(packageDir, "node_modules"), - "dir", - ); - await fs.writeFile( - path.join(packageDir, "package.json"), - JSON.stringify( - { - exports: buildPluginSdkPackageExports(), - name: "openclaw", - type: "module", - }, - null, - 2, - ), - ); - - await fs.mkdir(path.join(consumerDir, "node_modules"), { recursive: true }); - await fs.symlink(packageDir, path.join(consumerDir, "node_modules", "openclaw"), "dir"); - await fs.writeFile( - consumerEntry, - [ - `const specifiers = ${JSON.stringify(pluginSdkSpecifiers)};`, - "const results = {};", - "for (const specifier of specifiers) {", - " results[specifier] = typeof (await import(specifier));", - "}", - "export default results;", - ].join("\n"), - ); - - const { default: importResults } = await import(pathToFileURL(consumerEntry).href); - expect(importResults).toEqual( - Object.fromEntries(pluginSdkSpecifiers.map((specifier: string) => [specifier, "object"])), - ); - } finally { - await fs.rm(outDir, { recursive: true, force: true }); - await fs.rm(fixtureDir, { recursive: true, force: true }); - } - }); - it("keeps package.json plugin-sdk exports synced with the manifest", async () => { const packageJsonPath = path.join(process.cwd(), "package.json"); const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8")) as { diff --git a/test/fixtures/test-parallel.behavior.json b/test/fixtures/test-parallel.behavior.json index f0585bd0249..bc23a5ab88c 100644 --- a/test/fixtures/test-parallel.behavior.json +++ b/test/fixtures/test-parallel.behavior.json @@ -63,6 +63,10 @@ "file": "src/plugin-sdk/index.test.ts", "reason": "Plugin SDK index coverage retained a broad export graph in unit-fast and is safer outside the shared lane." }, + { + "file": "src/plugin-sdk/index.bundle.test.ts", + "reason": "Plugin SDK bundle validation builds and imports the full bundled export graph and is safer outside the shared lane." + }, { "file": "src/config/sessions.cache.test.ts", "reason": "Session cache coverage retained a large config/session graph in unit-fast on Linux CI." From aeb2adf240f3720c655f8945f6adfce1ff349acb Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 14:46:46 -0700 Subject: [PATCH 29/69] fix(ci): split redact snapshot restore coverage --- src/config/redact-snapshot.restore.test.ts | 267 +++++++++++++++++++++ src/config/redact-snapshot.test.ts | 226 ----------------- test/fixtures/test-parallel.behavior.json | 4 + 3 files changed, 271 insertions(+), 226 deletions(-) create mode 100644 src/config/redact-snapshot.restore.test.ts diff --git a/src/config/redact-snapshot.restore.test.ts b/src/config/redact-snapshot.restore.test.ts new file mode 100644 index 00000000000..1dce823d2b4 --- /dev/null +++ b/src/config/redact-snapshot.restore.test.ts @@ -0,0 +1,267 @@ +import { describe, expect, it } from "vitest"; +import { + REDACTED_SENTINEL, + redactConfigSnapshot, + restoreRedactedValues as restoreRedactedValues_orig, +} from "./redact-snapshot.js"; +import { __test__ } from "./schema.hints.js"; +import type { ConfigUiHints } from "./schema.js"; +import type { ConfigFileSnapshot } from "./types.openclaw.js"; +import { OpenClawSchema } from "./zod-schema.js"; + +const { mapSensitivePaths } = __test__; +const mainSchemaHints = mapSensitivePaths(OpenClawSchema, "", {}); + +type TestSnapshot> = ConfigFileSnapshot & { + parsed: TConfig; + resolved: TConfig; + config: TConfig; +}; + +function makeSnapshot>( + config: TConfig, + raw?: string, +): TestSnapshot { + return { + path: "/home/user/.openclaw/config.json5", + exists: true, + raw: raw ?? JSON.stringify(config), + parsed: config, + resolved: config as ConfigFileSnapshot["resolved"], + valid: true, + config: config as ConfigFileSnapshot["config"], + hash: "abc123", + issues: [], + warnings: [], + legacyIssues: [], + } as unknown as TestSnapshot; +} + +function restoreRedactedValues( + incoming: unknown, + original: TOriginal, + hints?: ConfigUiHints, +): TOriginal { + const result = restoreRedactedValues_orig(incoming, original, hints); + expect(result.ok).toBe(true); + return result.result as TOriginal; +} + +describe("restoreRedactedValues", () => { + it("restores redacted URL endpoint fields on round-trip", () => { + const incoming = { + models: { + providers: { + openai: { baseUrl: REDACTED_SENTINEL }, + }, + }, + }; + const original = { + models: { + providers: { + openai: { baseUrl: "https://alice:secret@example.test/v1" }, + }, + }, + }; + const result = restoreRedactedValues(incoming, original, mainSchemaHints); + expect(result.models.providers.openai.baseUrl).toBe("https://alice:secret@example.test/v1"); + }); + + it("restores sentinel values from original config", () => { + const incoming = { + gateway: { auth: { token: REDACTED_SENTINEL } }, + }; + const original = { + gateway: { auth: { token: "real-secret-token-value" } }, + }; + const result = restoreRedactedValues(incoming, original) as typeof incoming; + expect(result.gateway.auth.token).toBe("real-secret-token-value"); + }); + + it("preserves explicitly changed sensitive values", () => { + const incoming = { + gateway: { auth: { token: "new-token-value-from-user" } }, + }; + const original = { + gateway: { auth: { token: "old-token-value" } }, + }; + const result = restoreRedactedValues(incoming, original) as typeof incoming; + expect(result.gateway.auth.token).toBe("new-token-value-from-user"); + }); + + it("preserves non-sensitive fields unchanged", () => { + const incoming = { + ui: { seamColor: "#ff0000" }, + gateway: { port: 9999, auth: { token: REDACTED_SENTINEL } }, + }; + const original = { + ui: { seamColor: "#0088cc" }, + gateway: { port: 18789, auth: { token: "real-secret" } }, + }; + const result = restoreRedactedValues(incoming, original) as typeof incoming; + expect(result.ui.seamColor).toBe("#ff0000"); + expect(result.gateway.port).toBe(9999); + expect(result.gateway.auth.token).toBe("real-secret"); + }); + + it("handles deeply nested sentinel restoration", () => { + const incoming = { + channels: { + slack: { + accounts: { + ws1: { botToken: REDACTED_SENTINEL }, + ws2: { botToken: "user-typed-new-token-value" }, + }, + }, + }, + }; + const original = { + channels: { + slack: { + accounts: { + ws1: { botToken: "original-ws1-token-value" }, + ws2: { botToken: "original-ws2-token-value" }, + }, + }, + }, + }; + const result = restoreRedactedValues(incoming, original) as typeof incoming; + expect(result.channels.slack.accounts.ws1.botToken).toBe("original-ws1-token-value"); + expect(result.channels.slack.accounts.ws2.botToken).toBe("user-typed-new-token-value"); + }); + + it("handles missing original gracefully", () => { + const incoming = { + channels: { newChannel: { token: REDACTED_SENTINEL } }, + }; + const original = {}; + expect(restoreRedactedValues_orig(incoming, original).ok).toBe(false); + }); + + it("rejects invalid restore inputs", () => { + const invalidInputs = [null, undefined, "token-value"] as const; + for (const input of invalidInputs) { + const result = restoreRedactedValues_orig(input, { token: "x" }); + expect(result.ok).toBe(false); + } + expect(restoreRedactedValues_orig("token-value", { token: "x" })).toEqual({ + ok: false, + error: "input not an object", + }); + }); + + it("returns a human-readable error when sentinel cannot be restored", () => { + const incoming = { + channels: { newChannel: { token: REDACTED_SENTINEL } }, + }; + const result = restoreRedactedValues_orig(incoming, {}); + expect(result.ok).toBe(false); + expect(result.humanReadableMessage).toContain(REDACTED_SENTINEL); + expect(result.humanReadableMessage).toContain("channels.newChannel.token"); + }); + + it("keeps unmatched wildcard array entries unchanged outside extension paths", () => { + const hints: ConfigUiHints = { + "custom.*": { sensitive: true }, + }; + const incoming = { + custom: { items: [REDACTED_SENTINEL] }, + }; + const original = { + custom: { items: ["original-secret-value"] }, + }; + const result = restoreRedactedValues(incoming, original, hints) as typeof incoming; + expect(result.custom.items[0]).toBe(REDACTED_SENTINEL); + }); + + it("round-trips config through redact → restore", () => { + const originalConfig = { + gateway: { auth: { token: "gateway-auth-secret-token-value" }, port: 18789 }, + channels: { + slack: { botToken: "fake-slack-token-placeholder-value" }, + telegram: { + botToken: "fake-telegram-token-placeholder-value", + webhookSecret: "fake-tg-secret-placeholder-value", + }, + }, + models: { + providers: { + openai: { + apiKey: "sk-proj-fake-openai-api-key-value", + baseUrl: "https://api.openai.com", + }, + }, + }, + ui: { seamColor: "#0088cc" }, + }; + const snapshot = makeSnapshot(originalConfig); + const redacted = redactConfigSnapshot(snapshot); + const restored = restoreRedactedValues(redacted.config, snapshot.config); + expect(restored).toEqual(originalConfig); + }); + + it("round-trips with uiHints for custom sensitive fields", () => { + const hints: ConfigUiHints = { + "custom.myApiKey": { sensitive: true }, + "custom.displayName": { sensitive: false }, + }; + const originalConfig = { + custom: { myApiKey: "secret-custom-api-key-value", displayName: "My Bot" }, + }; + const snapshot = makeSnapshot(originalConfig); + const redacted = redactConfigSnapshot(snapshot, hints); + const custom = (redacted.config as typeof originalConfig).custom as Record; + expect(custom.myApiKey).toBe(REDACTED_SENTINEL); + expect(custom.displayName).toBe("My Bot"); + + const restored = restoreRedactedValues( + redacted.config, + snapshot.config, + hints, + ) as typeof originalConfig; + expect(restored).toEqual(originalConfig); + }); + + it("restores with uiHints respecting sensitive:false override", () => { + const hints: ConfigUiHints = { + "gateway.auth.token": { sensitive: false }, + }; + const incoming = { + gateway: { auth: { token: REDACTED_SENTINEL } }, + }; + const original = { + gateway: { auth: { token: "real-secret" } }, + }; + const result = restoreRedactedValues(incoming, original, hints) as typeof incoming; + expect(result.gateway.auth.token).toBe(REDACTED_SENTINEL); + }); + + it("restores array items using wildcard uiHints", () => { + const hints: ConfigUiHints = { + "channels.slack.accounts[].botToken": { sensitive: true }, + }; + const incoming = { + channels: { + slack: { + accounts: [ + { botToken: REDACTED_SENTINEL }, + { botToken: "user-provided-new-token-value" }, + ], + }, + }, + }; + const original = { + channels: { + slack: { + accounts: [ + { botToken: "original-token-first-account" }, + { botToken: "original-token-second-account" }, + ], + }, + }, + }; + const result = restoreRedactedValues(incoming, original, hints) as typeof incoming; + expect(result.channels.slack.accounts[0].botToken).toBe("original-token-first-account"); + expect(result.channels.slack.accounts[1].botToken).toBe("user-provided-new-token-value"); + }); +}); diff --git a/src/config/redact-snapshot.test.ts b/src/config/redact-snapshot.test.ts index 89aa4e1d121..d4c14b29ae6 100644 --- a/src/config/redact-snapshot.test.ts +++ b/src/config/redact-snapshot.test.ts @@ -919,232 +919,6 @@ describe("redactConfigSnapshot", () => { }); }); -describe("restoreRedactedValues", () => { - it("restores redacted URL endpoint fields on round-trip", () => { - const incoming = { - models: { - providers: { - openai: { baseUrl: REDACTED_SENTINEL }, - }, - }, - }; - const original = { - models: { - providers: { - openai: { baseUrl: "https://alice:secret@example.test/v1" }, - }, - }, - }; - const result = restoreRedactedValues(incoming, original, mainSchemaHints); - expect(result.models.providers.openai.baseUrl).toBe("https://alice:secret@example.test/v1"); - }); - - it("restores sentinel values from original config", () => { - const incoming = { - gateway: { auth: { token: REDACTED_SENTINEL } }, - }; - const original = { - gateway: { auth: { token: "real-secret-token-value" } }, - }; - const result = restoreRedactedValues(incoming, original) as typeof incoming; - expect(result.gateway.auth.token).toBe("real-secret-token-value"); - }); - - it("preserves explicitly changed sensitive values", () => { - const incoming = { - gateway: { auth: { token: "new-token-value-from-user" } }, - }; - const original = { - gateway: { auth: { token: "old-token-value" } }, - }; - const result = restoreRedactedValues(incoming, original) as typeof incoming; - expect(result.gateway.auth.token).toBe("new-token-value-from-user"); - }); - - it("preserves non-sensitive fields unchanged", () => { - const incoming = { - ui: { seamColor: "#ff0000" }, - gateway: { port: 9999, auth: { token: REDACTED_SENTINEL } }, - }; - const original = { - ui: { seamColor: "#0088cc" }, - gateway: { port: 18789, auth: { token: "real-secret" } }, - }; - const result = restoreRedactedValues(incoming, original) as typeof incoming; - expect(result.ui.seamColor).toBe("#ff0000"); - expect(result.gateway.port).toBe(9999); - expect(result.gateway.auth.token).toBe("real-secret"); - }); - - it("handles deeply nested sentinel restoration", () => { - const incoming = { - channels: { - slack: { - accounts: { - ws1: { botToken: REDACTED_SENTINEL }, - ws2: { botToken: "user-typed-new-token-value" }, - }, - }, - }, - }; - const original = { - channels: { - slack: { - accounts: { - ws1: { botToken: "original-ws1-token-value" }, - ws2: { botToken: "original-ws2-token-value" }, - }, - }, - }, - }; - const result = restoreRedactedValues(incoming, original) as typeof incoming; - expect(result.channels.slack.accounts.ws1.botToken).toBe("original-ws1-token-value"); - expect(result.channels.slack.accounts.ws2.botToken).toBe("user-typed-new-token-value"); - }); - - it("handles missing original gracefully", () => { - const incoming = { - channels: { newChannel: { token: REDACTED_SENTINEL } }, - }; - const original = {}; - expect(restoreRedactedValues_orig(incoming, original).ok).toBe(false); - }); - - it("rejects invalid restore inputs", () => { - const invalidInputs = [null, undefined, "token-value"] as const; - for (const input of invalidInputs) { - const result = restoreRedactedValues_orig(input, { token: "x" }); - expect(result.ok).toBe(false); - } - expect(restoreRedactedValues_orig("token-value", { token: "x" })).toEqual({ - ok: false, - error: "input not an object", - }); - }); - - it("returns a human-readable error when sentinel cannot be restored", () => { - const incoming = { - channels: { newChannel: { token: REDACTED_SENTINEL } }, - }; - const result = restoreRedactedValues_orig(incoming, {}); - expect(result.ok).toBe(false); - expect(result.humanReadableMessage).toContain(REDACTED_SENTINEL); - expect(result.humanReadableMessage).toContain("channels.newChannel.token"); - }); - - it("keeps unmatched wildcard array entries unchanged outside extension paths", () => { - const hints: ConfigUiHints = { - "custom.*": { sensitive: true }, - }; - const incoming = { - custom: { items: [REDACTED_SENTINEL] }, - }; - const original = { - custom: { items: ["original-secret-value"] }, - }; - const result = restoreRedactedValues(incoming, original, hints) as typeof incoming; - expect(result.custom.items[0]).toBe(REDACTED_SENTINEL); - }); - - it("round-trips config through redact → restore", () => { - const originalConfig = { - gateway: { auth: { token: "gateway-auth-secret-token-value" }, port: 18789 }, - channels: { - slack: { botToken: "fake-slack-token-placeholder-value" }, - telegram: { - botToken: "fake-telegram-token-placeholder-value", - webhookSecret: "fake-tg-secret-placeholder-value", - }, - }, - models: { - providers: { - openai: { - apiKey: "sk-proj-fake-openai-api-key-value", - baseUrl: "https://api.openai.com", - }, - }, - }, - ui: { seamColor: "#0088cc" }, - }; - const snapshot = makeSnapshot(originalConfig); - - // Redact (simulates config.get response) - const redacted = redactConfigSnapshot(snapshot); - - // Restore (simulates config.set before write) - const restored = restoreRedactedValues(redacted.config, snapshot.config); - - expect(restored).toEqual(originalConfig); - }); - - it("round-trips with uiHints for custom sensitive fields", () => { - const hints: ConfigUiHints = { - "custom.myApiKey": { sensitive: true }, - "custom.displayName": { sensitive: false }, - }; - const originalConfig = { - custom: { myApiKey: "secret-custom-api-key-value", displayName: "My Bot" }, - }; - const snapshot = makeSnapshot(originalConfig); - const redacted = redactConfigSnapshot(snapshot, hints); - const custom = (redacted.config as typeof originalConfig).custom as Record; - expect(custom.myApiKey).toBe(REDACTED_SENTINEL); - expect(custom.displayName).toBe("My Bot"); - - const restored = restoreRedactedValues( - redacted.config, - snapshot.config, - hints, - ) as typeof originalConfig; - expect(restored).toEqual(originalConfig); - }); - - it("restores with uiHints respecting sensitive:false override", () => { - const hints: ConfigUiHints = { - "gateway.auth.token": { sensitive: false }, - }; - const incoming = { - gateway: { auth: { token: REDACTED_SENTINEL } }, - }; - const original = { - gateway: { auth: { token: "real-secret" } }, - }; - // With sensitive:false, the sentinel is NOT on a sensitive path, - // so restore should NOT replace it (it's treated as a literal value) - const result = restoreRedactedValues(incoming, original, hints) as typeof incoming; - expect(result.gateway.auth.token).toBe(REDACTED_SENTINEL); - }); - - it("restores array items using wildcard uiHints", () => { - const hints: ConfigUiHints = { - "channels.slack.accounts[].botToken": { sensitive: true }, - }; - const incoming = { - channels: { - slack: { - accounts: [ - { botToken: REDACTED_SENTINEL }, - { botToken: "user-provided-new-token-value" }, - ], - }, - }, - }; - const original = { - channels: { - slack: { - accounts: [ - { botToken: "original-token-first-account" }, - { botToken: "original-token-second-account" }, - ], - }, - }, - }; - const result = restoreRedactedValues(incoming, original, hints) as typeof incoming; - expect(result.channels.slack.accounts[0].botToken).toBe("original-token-first-account"); - expect(result.channels.slack.accounts[1].botToken).toBe("user-provided-new-token-value"); - }); -}); - describe("realredactConfigSnapshot_real", () => { it("main schema redact works (samples)", () => { const schema = OpenClawSchema.toJSONSchema({ diff --git a/test/fixtures/test-parallel.behavior.json b/test/fixtures/test-parallel.behavior.json index bc23a5ab88c..15bb986fa8d 100644 --- a/test/fixtures/test-parallel.behavior.json +++ b/test/fixtures/test-parallel.behavior.json @@ -51,6 +51,10 @@ "file": "src/config/redact-snapshot.test.ts", "reason": "Snapshot redaction coverage produced a large retained heap jump in unit-fast on Linux CI." }, + { + "file": "src/config/redact-snapshot.restore.test.ts", + "reason": "Snapshot restore coverage retains a broad schema/redaction graph and is safer outside the shared lane." + }, { "file": "src/infra/outbound/message-action-runner.media.test.ts", "reason": "Outbound media action coverage retained a large media/plugin graph in unit-fast." From 5841e3b4935dccbb06df121e62cc16817200e5a7 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 14:48:32 -0700 Subject: [PATCH 30/69] fix(ci): split redact snapshot schema coverage --- src/config/redact-snapshot.schema.test.ts | 88 +++++++++++++++++++++++ src/config/redact-snapshot.test.ts | 40 ----------- test/fixtures/test-parallel.behavior.json | 4 ++ 3 files changed, 92 insertions(+), 40 deletions(-) create mode 100644 src/config/redact-snapshot.schema.test.ts diff --git a/src/config/redact-snapshot.schema.test.ts b/src/config/redact-snapshot.schema.test.ts new file mode 100644 index 00000000000..3c67d2cb92b --- /dev/null +++ b/src/config/redact-snapshot.schema.test.ts @@ -0,0 +1,88 @@ +import { describe, expect, it } from "vitest"; +import { + REDACTED_SENTINEL, + redactConfigSnapshot, + restoreRedactedValues as restoreRedactedValues_orig, +} from "./redact-snapshot.js"; +import { __test__ } from "./schema.hints.js"; +import type { ConfigUiHints } from "./schema.js"; +import type { ConfigFileSnapshot } from "./types.openclaw.js"; +import { OpenClawSchema } from "./zod-schema.js"; + +const { mapSensitivePaths } = __test__; +const mainSchemaHints = mapSensitivePaths(OpenClawSchema, "", {}); + +type TestSnapshot> = ConfigFileSnapshot & { + parsed: TConfig; + resolved: TConfig; + config: TConfig; +}; + +function makeSnapshot>( + config: TConfig, + raw?: string, +): TestSnapshot { + return { + path: "/home/user/.openclaw/config.json5", + exists: true, + raw: raw ?? JSON.stringify(config), + parsed: config, + resolved: config as ConfigFileSnapshot["resolved"], + valid: true, + config: config as ConfigFileSnapshot["config"], + hash: "abc123", + issues: [], + warnings: [], + legacyIssues: [], + } as unknown as TestSnapshot; +} + +function restoreRedactedValues( + incoming: unknown, + original: TOriginal, + hints?: ConfigUiHints, +): TOriginal { + const result = restoreRedactedValues_orig(incoming, original, hints); + expect(result.ok).toBe(true); + return result.result as TOriginal; +} + +describe("realredactConfigSnapshot_real", () => { + it("main schema redact works (samples)", () => { + const schema = OpenClawSchema.toJSONSchema({ + target: "draft-07", + unrepresentable: "any", + }); + schema.title = "OpenClawConfig"; + const hints = mainSchemaHints; + + const snapshot = makeSnapshot({ + agents: { + defaults: { + memorySearch: { + remote: { + apiKey: "1234", + }, + }, + }, + list: [ + { + memorySearch: { + remote: { + apiKey: "6789", + }, + }, + }, + ], + }, + }); + + const result = redactConfigSnapshot(snapshot, hints); + const config = result.config as typeof snapshot.config; + expect(config.agents.defaults.memorySearch.remote.apiKey).toBe(REDACTED_SENTINEL); + expect(config.agents.list[0].memorySearch.remote.apiKey).toBe(REDACTED_SENTINEL); + const restored = restoreRedactedValues(result.config, snapshot.config, hints); + expect(restored.agents.defaults.memorySearch.remote.apiKey).toBe("1234"); + expect(restored.agents.list[0].memorySearch.remote.apiKey).toBe("6789"); + }); +}); diff --git a/src/config/redact-snapshot.test.ts b/src/config/redact-snapshot.test.ts index d4c14b29ae6..dd754a44fac 100644 --- a/src/config/redact-snapshot.test.ts +++ b/src/config/redact-snapshot.test.ts @@ -918,43 +918,3 @@ describe("redactConfigSnapshot", () => { expect(channels.slack.accounts[1].botToken).toBe(REDACTED_SENTINEL); }); }); - -describe("realredactConfigSnapshot_real", () => { - it("main schema redact works (samples)", () => { - const schema = OpenClawSchema.toJSONSchema({ - target: "draft-07", - unrepresentable: "any", - }); - schema.title = "OpenClawConfig"; - const hints = mainSchemaHints; - - const snapshot = makeSnapshot({ - agents: { - defaults: { - memorySearch: { - remote: { - apiKey: "1234", - }, - }, - }, - list: [ - { - memorySearch: { - remote: { - apiKey: "6789", - }, - }, - }, - ], - }, - }); - - const result = redactConfigSnapshot(snapshot, hints); - const config = result.config as typeof snapshot.config; - expect(config.agents.defaults.memorySearch.remote.apiKey).toBe(REDACTED_SENTINEL); - expect(config.agents.list[0].memorySearch.remote.apiKey).toBe(REDACTED_SENTINEL); - const restored = restoreRedactedValues(result.config, snapshot.config, hints); - expect(restored.agents.defaults.memorySearch.remote.apiKey).toBe("1234"); - expect(restored.agents.list[0].memorySearch.remote.apiKey).toBe("6789"); - }); -}); diff --git a/test/fixtures/test-parallel.behavior.json b/test/fixtures/test-parallel.behavior.json index 15bb986fa8d..bdbb4583913 100644 --- a/test/fixtures/test-parallel.behavior.json +++ b/test/fixtures/test-parallel.behavior.json @@ -55,6 +55,10 @@ "file": "src/config/redact-snapshot.restore.test.ts", "reason": "Snapshot restore coverage retains a broad schema/redaction graph and is safer outside the shared lane." }, + { + "file": "src/config/redact-snapshot.schema.test.ts", + "reason": "Schema-backed redaction round-trip coverage loads the full config schema graph and is safer outside the shared lane." + }, { "file": "src/infra/outbound/message-action-runner.media.test.ts", "reason": "Outbound media action coverage retained a large media/plugin graph in unit-fast." From 566e4cf77b2d44048e9e5d47b1a1a2c263c1ef42 Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:45:35 -0500 Subject: [PATCH 31/69] test: add Zalo reply-once lifecycle regression --- .../src/monitor.reply-once.lifecycle.test.ts | 315 ++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 extensions/zalo/src/monitor.reply-once.lifecycle.test.ts diff --git a/extensions/zalo/src/monitor.reply-once.lifecycle.test.ts b/extensions/zalo/src/monitor.reply-once.lifecycle.test.ts new file mode 100644 index 00000000000..ab4b409fc23 --- /dev/null +++ b/extensions/zalo/src/monitor.reply-once.lifecycle.test.ts @@ -0,0 +1,315 @@ +import { createServer, type RequestListener } from "node:http"; +import type { AddressInfo } from "node:net"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { createPluginRuntimeMock } from "../../../test/helpers/extensions/plugin-runtime-mock.js"; +import { createEmptyPluginRegistry } from "../../../src/plugins/registry.js"; +import { setActivePluginRegistry } from "../../../src/plugins/runtime.js"; +import type { OpenClawConfig, PluginRuntime } from "../runtime-api.js"; +import { + clearZaloWebhookSecurityStateForTest, + monitorZaloProvider, +} from "./monitor.js"; +import type { ResolvedZaloAccount } from "./accounts.js"; + +const setWebhookMock = vi.hoisted(() => vi.fn(async () => ({ ok: true, result: { url: "" } }))); +const deleteWebhookMock = vi.hoisted(() => vi.fn(async () => ({ ok: true, result: { url: "" } }))); +const getWebhookInfoMock = vi.hoisted(() => vi.fn(async () => ({ ok: true, result: { url: "" } }))); +const getUpdatesMock = vi.hoisted(() => vi.fn(() => new Promise(() => {}))); +const sendChatActionMock = vi.hoisted(() => vi.fn(async () => ({ ok: true }))); +const sendMessageMock = vi.hoisted(() => + vi.fn(async () => ({ ok: true, result: { message_id: "reply-zalo-1" } })), +); +const sendPhotoMock = vi.hoisted(() => vi.fn(async () => ({ ok: true }))); +const getZaloRuntimeMock = vi.hoisted(() => vi.fn()); + +vi.mock("./api.js", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + deleteWebhook: deleteWebhookMock, + getUpdates: getUpdatesMock, + getWebhookInfo: getWebhookInfoMock, + sendChatAction: sendChatActionMock, + sendMessage: sendMessageMock, + sendPhoto: sendPhotoMock, + setWebhook: setWebhookMock, + }; +}); + +vi.mock("./runtime.js", () => ({ + getZaloRuntime: getZaloRuntimeMock, +})); + +async function withServer(handler: RequestListener, fn: (baseUrl: string) => Promise) { + const server = createServer(handler); + await new Promise((resolve) => { + server.listen(0, "127.0.0.1", () => resolve()); + }); + const address = server.address() as AddressInfo | null; + if (!address) { + throw new Error("missing server address"); + } + try { + await fn(`http://127.0.0.1:${address.port}`); + } finally { + await new Promise((resolve) => server.close(() => resolve())); + } +} + +function createLifecycleConfig(): OpenClawConfig { + return { + channels: { + zalo: { + enabled: true, + accounts: { + "acct-zalo-lifecycle": { + enabled: true, + webhookUrl: "https://example.com/hooks/zalo", + webhookSecret: "supersecret", // pragma: allowlist secret + dmPolicy: "open", + }, + }, + }, + }, + } as OpenClawConfig; +} + +function createLifecycleAccount(): ResolvedZaloAccount { + return { + accountId: "acct-zalo-lifecycle", + enabled: true, + token: "zalo-token", + tokenSource: "config", + config: { + webhookUrl: "https://example.com/hooks/zalo", + webhookSecret: "supersecret", // pragma: allowlist secret + dmPolicy: "open", + }, + } as ResolvedZaloAccount; +} + +function createRuntimeEnv() { + return { + log: vi.fn<(message: string) => void>(), + error: vi.fn<(message: string) => void>(), + }; +} + +function createTextUpdate(messageId: string) { + return { + event_name: "message.text.received", + message: { + from: { id: "user-1", name: "User One" }, + chat: { id: "dm-chat-1", chat_type: "PRIVATE" as const }, + message_id: messageId, + date: Math.floor(Date.now() / 1000), + text: "hello from zalo", + }, + }; +} + +async function settleAsyncWork(): Promise { + for (let i = 0; i < 6; i += 1) { + await Promise.resolve(); + await new Promise((resolve) => setTimeout(resolve, 0)); + } +} + +async function postWebhookUpdate(params: { + baseUrl: string; + path: string; + secret: string; + payload: Record; +}) { + return await fetch(`${params.baseUrl}${params.path}`, { + method: "POST", + headers: { + "content-type": "application/json", + "x-bot-api-secret-token": params.secret, + }, + body: JSON.stringify(params.payload), + }); +} + +describe("Zalo reply-once lifecycle", () => { + const finalizeInboundContextMock = vi.fn((ctx: Record) => ctx); + const recordInboundSessionMock = vi.fn(async () => undefined); + const resolveAgentRouteMock = vi.fn(() => ({ + agentId: "main", + channel: "zalo", + accountId: "acct-zalo-lifecycle", + sessionKey: "agent:main:zalo:direct:dm-chat-1", + mainSessionKey: "agent:main:main", + matchedBy: "default", + })); + const dispatchReplyWithBufferedBlockDispatcherMock = vi.fn(); + + beforeEach(() => { + vi.clearAllMocks(); + clearZaloWebhookSecurityStateForTest(); + + getZaloRuntimeMock.mockReturnValue( + createPluginRuntimeMock({ + channel: { + routing: { + resolveAgentRoute: + resolveAgentRouteMock as unknown as PluginRuntime["channel"]["routing"]["resolveAgentRoute"], + }, + reply: { + finalizeInboundContext: + finalizeInboundContextMock as unknown as PluginRuntime["channel"]["reply"]["finalizeInboundContext"], + dispatchReplyWithBufferedBlockDispatcher: + dispatchReplyWithBufferedBlockDispatcherMock as unknown as PluginRuntime["channel"]["reply"]["dispatchReplyWithBufferedBlockDispatcher"], + }, + session: { + recordInboundSession: + recordInboundSessionMock as unknown as PluginRuntime["channel"]["session"]["recordInboundSession"], + }, + }, + }), + ); + }); + + afterEach(() => { + setActivePluginRegistry(createEmptyPluginRegistry()); + }); + + it("routes one accepted webhook event to one visible reply across duplicate replay", async () => { + dispatchReplyWithBufferedBlockDispatcherMock.mockImplementation(async ({ dispatcherOptions }) => { + await dispatcherOptions.deliver({ text: "zalo reply once" }); + }); + + const registry = createEmptyPluginRegistry(); + setActivePluginRegistry(registry); + const abort = new AbortController(); + const runtime = createRuntimeEnv(); + const run = monitorZaloProvider({ + token: "zalo-token", + account: createLifecycleAccount(), + config: createLifecycleConfig(), + runtime, + abortSignal: abort.signal, + useWebhook: true, + webhookUrl: "https://example.com/hooks/zalo", + webhookSecret: "supersecret", + }); + + await vi.waitFor(() => expect(setWebhookMock).toHaveBeenCalledTimes(1)); + expect(registry.httpRoutes).toHaveLength(1); + const route = registry.httpRoutes[0]; + if (!route) { + throw new Error("missing plugin HTTP route"); + } + + await withServer((req, res) => route.handler(req, res), async (baseUrl) => { + const payload = createTextUpdate(`zalo-replay-${Date.now()}`); + const first = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); + const second = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); + + expect(first.status).toBe(200); + expect(second.status).toBe(200); + await settleAsyncWork(); + }); + + expect(finalizeInboundContextMock).toHaveBeenCalledTimes(1); + expect(finalizeInboundContextMock).toHaveBeenCalledWith( + expect.objectContaining({ + AccountId: "acct-zalo-lifecycle", + SessionKey: "agent:main:zalo:direct:dm-chat-1", + MessageSid: expect.stringContaining("zalo-replay-"), + From: "zalo:user-1", + To: "zalo:dm-chat-1", + }), + ); + expect(recordInboundSessionMock).toHaveBeenCalledTimes(1); + expect(recordInboundSessionMock).toHaveBeenCalledWith( + expect.objectContaining({ + sessionKey: "agent:main:zalo:direct:dm-chat-1", + }), + ); + expect(sendMessageMock).toHaveBeenCalledTimes(1); + expect(sendMessageMock).toHaveBeenCalledWith( + "zalo-token", + expect.objectContaining({ + chat_id: "dm-chat-1", + text: "zalo reply once", + }), + undefined, + ); + + abort.abort(); + await run; + }); + + it("does not emit a second visible reply when replay arrives after a post-send failure", async () => { + let dispatchAttempts = 0; + dispatchReplyWithBufferedBlockDispatcherMock.mockImplementation(async ({ dispatcherOptions }) => { + dispatchAttempts += 1; + await dispatcherOptions.deliver({ text: "zalo reply after failure" }); + if (dispatchAttempts === 1) { + throw new Error("post-send failure"); + } + }); + + const registry = createEmptyPluginRegistry(); + setActivePluginRegistry(registry); + const abort = new AbortController(); + const runtime = createRuntimeEnv(); + const run = monitorZaloProvider({ + token: "zalo-token", + account: createLifecycleAccount(), + config: createLifecycleConfig(), + runtime, + abortSignal: abort.signal, + useWebhook: true, + webhookUrl: "https://example.com/hooks/zalo", + webhookSecret: "supersecret", + }); + + await vi.waitFor(() => expect(setWebhookMock).toHaveBeenCalledTimes(1)); + const route = registry.httpRoutes[0]; + if (!route) { + throw new Error("missing plugin HTTP route"); + } + + await withServer((req, res) => route.handler(req, res), async (baseUrl) => { + const payload = createTextUpdate(`zalo-retry-${Date.now()}`); + const first = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); + await settleAsyncWork(); + const replay = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); + + expect(first.status).toBe(200); + expect(replay.status).toBe(200); + await settleAsyncWork(); + }); + + expect(dispatchReplyWithBufferedBlockDispatcherMock).toHaveBeenCalledTimes(1); + expect(sendMessageMock).toHaveBeenCalledTimes(1); + expect(runtime.error).toHaveBeenCalledWith( + expect.stringContaining("Zalo webhook failed: Error: post-send failure"), + ); + + abort.abort(); + await run; + }); +}); From 73e08775d7de9de81eaed4ae25d6068d4ecf4187 Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:47:25 -0500 Subject: [PATCH 32/69] test: add voice-call hangup-once lifecycle regression --- .../src/webhook.hangup-once.lifecycle.test.ts | 127 ++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 extensions/voice-call/src/webhook.hangup-once.lifecycle.test.ts diff --git a/extensions/voice-call/src/webhook.hangup-once.lifecycle.test.ts b/extensions/voice-call/src/webhook.hangup-once.lifecycle.test.ts new file mode 100644 index 00000000000..b6e0604909f --- /dev/null +++ b/extensions/voice-call/src/webhook.hangup-once.lifecycle.test.ts @@ -0,0 +1,127 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { VoiceCallConfigSchema, type VoiceCallConfig } from "./config.js"; +import { CallManager } from "./manager.js"; +import { createTestStorePath, FakeProvider } from "./manager.test-harness.js"; +import type { WebhookContext, WebhookParseOptions } from "./types.js"; +import { VoiceCallWebhookServer } from "./webhook.js"; + +const createConfig = (overrides: Partial = {}): VoiceCallConfig => { + const base = VoiceCallConfigSchema.parse({ + enabled: true, + provider: "plivo", + fromNumber: "+15550000000", + inboundPolicy: "disabled", + }); + base.serve.port = 0; + + return { + ...base, + ...overrides, + serve: { + ...base.serve, + ...(overrides.serve ?? {}), + }, + }; +}; + +async function postWebhookForm(server: VoiceCallWebhookServer, baseUrl: string, body: string) { + const address = ( + server as unknown as { server?: { address?: () => unknown } } + ).server?.address?.(); + const requestUrl = new URL(baseUrl); + if (address && typeof address === "object" && "port" in address && address.port) { + requestUrl.port = String(address.port); + } + return await fetch(requestUrl.toString(), { + method: "POST", + headers: { "content-type": "application/x-www-form-urlencoded" }, + body, + }); +} + +class RejectInboundReplayProvider extends FakeProvider { + override verifyWebhook() { + return { ok: true, verifiedRequestKey: "verified:req:reject-once" }; + } + + override parseWebhookEvent(_ctx: WebhookContext, options?: WebhookParseOptions) { + return { + statusCode: 200, + events: [ + { + id: "evt-reject-once", + dedupeKey: options?.verifiedRequestKey, + type: "call.initiated" as const, + callId: "provider-inbound-1", + providerCallId: "provider-inbound-1", + timestamp: Date.now(), + direction: "inbound" as const, + from: "+15552222222", + to: "+15550000000", + }, + ], + }; + } +} + +class RejectInboundReplayWithHangupFailureProvider extends RejectInboundReplayProvider { + override async hangupCall(input: Parameters[0]): Promise { + this.hangupCalls.push(input); + throw new Error("hangup failed"); + } +} + +describe("Voice-call webhook hangup-once lifecycle", () => { + afterEach(() => { + // Each test uses an isolated store path, so only server cleanup is needed. + }); + + it("hangs up a rejected inbound replay only once across duplicate webhook delivery", async () => { + const provider = new RejectInboundReplayProvider("plivo"); + const config = createConfig(); + const manager = new CallManager(config, createTestStorePath()); + await manager.initialize(provider, "https://example.com/voice/webhook"); + const server = new VoiceCallWebhookServer(config, manager, provider); + + try { + const baseUrl = await server.start(); + const first = await postWebhookForm(server, baseUrl, "CallSid=CA123&From=%2B15552222222"); + const second = await postWebhookForm(server, baseUrl, "CallSid=CA123&From=%2B15552222222"); + + expect(first.status).toBe(200); + expect(second.status).toBe(200); + expect(provider.hangupCalls).toHaveLength(1); + expect(provider.hangupCalls[0]).toEqual( + expect.objectContaining({ + providerCallId: "provider-inbound-1", + reason: "hangup-bot", + }), + ); + expect(manager.getCallByProviderCallId("provider-inbound-1")).toBeUndefined(); + } finally { + await server.stop(); + } + }); + + it("does not attempt a second hangup when replay arrives after the first hangup fails", async () => { + const provider = new RejectInboundReplayWithHangupFailureProvider("plivo"); + const config = createConfig(); + const manager = new CallManager(config, createTestStorePath()); + await manager.initialize(provider, "https://example.com/voice/webhook"); + const server = new VoiceCallWebhookServer(config, manager, provider); + + try { + const baseUrl = await server.start(); + const first = await postWebhookForm(server, baseUrl, "CallSid=CA123&From=%2B15552222222"); + const second = await postWebhookForm(server, baseUrl, "CallSid=CA123&From=%2B15552222222"); + + expect(first.status).toBe(200); + expect(second.status).toBe(200); + expect(provider.hangupCalls).toHaveLength(1); + expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-inbound-1"); + expect(manager.getCallByProviderCallId("provider-inbound-1")).toBeUndefined(); + } finally { + await server.stop(); + } + }); +}); From da8fb705258cc038338a51cb192d88c626626f42 Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Thu, 19 Mar 2026 16:54:39 -0500 Subject: [PATCH 33/69] test: fix Feishu lifecycle type checks --- ...monitor.acp-init-failure.lifecycle.test.ts | 3 ++- .../src/monitor.bot-menu.lifecycle.test.ts | 21 ++++++++++--------- ...tor.broadcast.reply-once.lifecycle.test.ts | 3 ++- .../src/monitor.card-action.lifecycle.test.ts | 16 ++++++++++---- 4 files changed, 27 insertions(+), 16 deletions(-) diff --git a/extensions/feishu/src/monitor.acp-init-failure.lifecycle.test.ts b/extensions/feishu/src/monitor.acp-init-failure.lifecycle.test.ts index 922ac97856b..b7b9a63dc70 100644 --- a/extensions/feishu/src/monitor.acp-init-failure.lifecycle.test.ts +++ b/extensions/feishu/src/monitor.acp-init-failure.lifecycle.test.ts @@ -115,6 +115,7 @@ function createLifecycleConfig(): ClawdbotConfig { function createLifecycleAccount(): ResolvedFeishuAccount { return { accountId: "acct-acp", + selectionSource: "explicit", enabled: true, configured: true, appId: "cli_test", @@ -135,7 +136,7 @@ function createLifecycleAccount(): ResolvedFeishuAccount { }, allowFrom: ["ou_sender_1"], }, - } as ResolvedFeishuAccount; + } as unknown as ResolvedFeishuAccount; } function createRuntimeEnv(): RuntimeEnv { diff --git a/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts b/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts index a01aa67f384..ee04b27b538 100644 --- a/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts +++ b/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts @@ -5,18 +5,18 @@ import { monitorSingleAccount } from "./monitor.account.js"; import { setFeishuRuntime } from "./runtime.js"; import type { ResolvedFeishuAccount } from "./types.js"; +type BoundConversation = { + bindingId: string; + targetSessionKey: string; +}; + const createEventDispatcherMock = vi.hoisted(() => vi.fn()); const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); const createFeishuReplyDispatcherMock = vi.hoisted(() => vi.fn()); -const resolveBoundConversationMock = vi.hoisted(() => - vi.fn< - () => { - bindingId: string; - targetSessionKey: string; - } | null - >(() => null), +const resolveBoundConversationMock = vi.hoisted( + () => vi.fn<() => BoundConversation | null>(() => null), ); const touchBindingMock = vi.hoisted(() => vi.fn()); const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); @@ -117,6 +117,7 @@ function createLifecycleConfig(): ClawdbotConfig { function createLifecycleAccount(): ResolvedFeishuAccount { return { accountId: "acct-menu", + selectionSource: "explicit", enabled: true, configured: true, appId: "cli_test", @@ -129,7 +130,7 @@ function createLifecycleAccount(): ResolvedFeishuAccount { requireMention: false, resolveSenderNames: false, }, - } as ResolvedFeishuAccount; + } as unknown as ResolvedFeishuAccount; } function createRuntimeEnv(): RuntimeEnv { @@ -209,10 +210,10 @@ describe("Feishu bot-menu lifecycle", () => { markDispatchIdle: vi.fn(), }); - resolveBoundConversationMock.mockReturnValue({ + resolveBoundConversationMock.mockImplementation(() => ({ bindingId: "binding-menu", targetSessionKey: "agent:bound-agent:feishu:direct:ou_user1", - }); + })); resolveAgentRouteMock.mockReturnValue({ agentId: "main", diff --git a/extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts b/extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts index b3eafc2d64b..295db8659ee 100644 --- a/extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts +++ b/extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts @@ -131,6 +131,7 @@ function createLifecycleConfig(): ClawdbotConfig { function createLifecycleAccount(accountId: "account-A" | "account-B"): ResolvedFeishuAccount { return { accountId, + selectionSource: "explicit", enabled: true, configured: true, appId: accountId === "account-A" ? "cli_a" : "cli_b", @@ -148,7 +149,7 @@ function createLifecycleAccount(accountId: "account-A" | "account-B"): ResolvedF }, }, }, - } as ResolvedFeishuAccount; + } as unknown as ResolvedFeishuAccount; } function createRuntimeEnv(): RuntimeEnv { diff --git a/extensions/feishu/src/monitor.card-action.lifecycle.test.ts b/extensions/feishu/src/monitor.card-action.lifecycle.test.ts index 95526d211d9..3171a7a125e 100644 --- a/extensions/feishu/src/monitor.card-action.lifecycle.test.ts +++ b/extensions/feishu/src/monitor.card-action.lifecycle.test.ts @@ -6,12 +6,19 @@ import { monitorSingleAccount } from "./monitor.account.js"; import { setFeishuRuntime } from "./runtime.js"; import type { ResolvedFeishuAccount } from "./types.js"; +type BoundConversation = { + bindingId: string; + targetSessionKey: string; +}; + const createEventDispatcherMock = vi.hoisted(() => vi.fn()); const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); const createFeishuReplyDispatcherMock = vi.hoisted(() => vi.fn()); -const resolveBoundConversationMock = vi.hoisted(() => vi.fn(() => null)); +const resolveBoundConversationMock = vi.hoisted( + () => vi.fn<() => BoundConversation | null>(() => null), +); const touchBindingMock = vi.hoisted(() => vi.fn()); const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); const dispatchReplyFromConfigMock = vi.hoisted(() => vi.fn()); @@ -111,6 +118,7 @@ function createLifecycleConfig(): ClawdbotConfig { function createLifecycleAccount(): ResolvedFeishuAccount { return { accountId: "acct-card", + selectionSource: "explicit", enabled: true, configured: true, appId: "cli_test", @@ -123,7 +131,7 @@ function createLifecycleAccount(): ResolvedFeishuAccount { requireMention: false, resolveSenderNames: false, }, - } as ResolvedFeishuAccount; + } as unknown as ResolvedFeishuAccount; } function createRuntimeEnv(): RuntimeEnv { @@ -228,10 +236,10 @@ describe("Feishu card-action lifecycle", () => { markDispatchIdle: vi.fn(), }); - resolveBoundConversationMock.mockReturnValue({ + resolveBoundConversationMock.mockImplementation(() => ({ bindingId: "binding-card", targetSessionKey: "agent:bound-agent:feishu:direct:ou_user1", - }); + })); resolveAgentRouteMock.mockReturnValue({ agentId: "main", From bbd62469faa90febd98bcec92f5151ec4f190e97 Mon Sep 17 00:00:00 2001 From: Harold Hunt Date: Thu, 19 Mar 2026 17:59:13 -0400 Subject: [PATCH 34/69] Tests: Add tooling / skill for detecting and fixing memory leaks in tests (#50654) * Tests: add periodic heap snapshot tooling * Skills: add test heap leak workflow * Apply suggestion from @greptile-apps[bot] Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> * Update scripts/test-parallel.mjs Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --------- Co-authored-by: Vincent Koc Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- .../skills/openclaw-test-heap-leaks/SKILL.md | 71 +++++ .../agents/openai.yaml | 4 + .../scripts/heapsnapshot-delta.mjs | 265 ++++++++++++++++++ scripts/test-parallel-memory.mjs | 43 ++- scripts/test-parallel.mjs | 95 ++++++- 5 files changed, 459 insertions(+), 19 deletions(-) create mode 100644 .agents/skills/openclaw-test-heap-leaks/SKILL.md create mode 100644 .agents/skills/openclaw-test-heap-leaks/agents/openai.yaml create mode 100644 .agents/skills/openclaw-test-heap-leaks/scripts/heapsnapshot-delta.mjs diff --git a/.agents/skills/openclaw-test-heap-leaks/SKILL.md b/.agents/skills/openclaw-test-heap-leaks/SKILL.md new file mode 100644 index 00000000000..a2ab2878430 --- /dev/null +++ b/.agents/skills/openclaw-test-heap-leaks/SKILL.md @@ -0,0 +1,71 @@ +--- +name: openclaw-test-heap-leaks +description: Investigate `pnpm test` memory growth, Vitest worker OOMs, and suspicious RSS increases in OpenClaw using the `scripts/test-parallel.mjs` heap snapshot tooling. Use when Codex needs to reproduce test-lane memory growth, collect repeated `.heapsnapshot` files, compare snapshots from the same worker PID, distinguish transformed-module retention from real data leaks, and fix or reduce the impact by patching cleanup logic or isolating hotspot tests. +--- + +# OpenClaw Test Heap Leaks + +Use this skill for test-memory investigations. Do not guess from RSS alone when heap snapshots are available. + +## Workflow + +1. Reproduce the failing shape first. + - Match the real entrypoint if possible. For Linux CI-style unit failures, start with: + - `pnpm canvas:a2ui:bundle && OPENCLAW_TEST_MEMORY_TRACE=1 OPENCLAW_TEST_HEAPSNAPSHOT_INTERVAL_MS=60000 OPENCLAW_TEST_HEAPSNAPSHOT_DIR=.tmp/heapsnap OPENCLAW_TEST_WORKERS=2 OPENCLAW_TEST_MAX_OLD_SPACE_SIZE_MB=6144 pnpm test` + - Keep `OPENCLAW_TEST_MEMORY_TRACE=1` enabled so the wrapper prints per-file RSS summaries alongside the snapshots. + - If the report is about a specific shard or worker budget, preserve that shape. + +2. Wait for repeated snapshots before concluding anything. + - Take at least two intervals from the same lane. + - Compare snapshots from the same PID inside one lane directory such as `.tmp/heapsnap/unit-fast/`. + - Use `scripts/heapsnapshot-delta.mjs` to compare either two files directly or the earliest/latest pair per PID in one lane directory. + +3. Classify the growth before choosing a fix. + - If growth is dominated by Vite/Vitest transformed source strings, `Module`, `system / Context`, bytecode, descriptor arrays, or property maps, treat it as retained module graph growth in long-lived workers. + - If growth is dominated by app objects, caches, buffers, server handles, timers, mock state, sqlite state, or similar runtime objects, treat it as a likely cleanup or lifecycle leak. + +4. Fix the right layer. + - For retained transformed-module growth in shared workers: + - Move hotspot files out of `unit-fast` by updating `test/fixtures/test-parallel.behavior.json`. + - Prefer `singletonIsolated` for files that are safe alone but inflate shared worker heaps. + - If the file should already have been peeled out by timings but is absent from `test/fixtures/test-timings.unit.json`, call that out explicitly. Missing timings are a scheduling blind spot. + - For real leaks: + - Patch the implicated test or runtime cleanup path. + - Look for missing `afterEach`/`afterAll`, module-reset gaps, retained global state, unreleased DB handles, or listeners/timers that survive the file. + +5. Verify with the most direct proof. + - Re-run the targeted lane or file with heap snapshots enabled if the suite still finishes in reasonable time. + - If snapshot overhead pushes tests over Vitest timeouts, fall back to the same lane without snapshots and confirm the RSS trend or OOM is reduced. + - For wrapper-only changes, at minimum verify the expected lanes start and the snapshot files are written. + +## Heuristics + +- Do not call everything a leak. In this repo, large `unit-fast` growth can be a worker-lifetime problem rather than an application object leak. +- `scripts/test-parallel.mjs` and `scripts/test-parallel-memory.mjs` are the primary control points for wrapper diagnostics. +- The lane names printed by `[test-parallel] start ...` and `[test-parallel][mem] summary ...` tell you where to focus. +- When one or two files account for most of the delta and they are missing from timings, reducing impact by isolating them is usually the first pragmatic fix. +- When the same retained object families grow across multiple intervals in the same worker PID, trust the snapshots over intuition. + +## Snapshot Comparison + +- Direct comparison: + - `node .agents/skills/openclaw-test-heap-leaks/scripts/heapsnapshot-delta.mjs before.heapsnapshot after.heapsnapshot` +- Auto-select earliest/latest snapshots per PID within one lane: + - `node .agents/skills/openclaw-test-heap-leaks/scripts/heapsnapshot-delta.mjs --lane-dir .tmp/heapsnap/unit-fast` +- Useful flags: + - `--top 40` + - `--min-kb 32` + - `--pid 16133` + +Read the top positive deltas first. Large positive growth in module-transform artifacts suggests lane isolation; large positive growth in runtime objects suggests a real leak. + +## Output Expectations + +When using this skill, report: + +- The exact reproduce command. +- Which lane and PID were compared. +- The dominant retained object families from the snapshot delta. +- Whether the issue is a real leak or shared-worker retained module growth. +- The concrete fix or impact-reduction patch. +- What you verified, and what snapshot overhead prevented you from verifying. diff --git a/.agents/skills/openclaw-test-heap-leaks/agents/openai.yaml b/.agents/skills/openclaw-test-heap-leaks/agents/openai.yaml new file mode 100644 index 00000000000..b5157911b77 --- /dev/null +++ b/.agents/skills/openclaw-test-heap-leaks/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Test Heap Leaks" + short_description: "Investigate test OOMs with heap snapshots" + default_prompt: "Use $openclaw-test-heap-leaks to investigate test memory growth with heap snapshots and reduce its impact." diff --git a/.agents/skills/openclaw-test-heap-leaks/scripts/heapsnapshot-delta.mjs b/.agents/skills/openclaw-test-heap-leaks/scripts/heapsnapshot-delta.mjs new file mode 100644 index 00000000000..ccb705c4c82 --- /dev/null +++ b/.agents/skills/openclaw-test-heap-leaks/scripts/heapsnapshot-delta.mjs @@ -0,0 +1,265 @@ +#!/usr/bin/env node + +import fs from "node:fs"; +import path from "node:path"; + +function printUsage() { + console.error( + "Usage: node heapsnapshot-delta.mjs [--top N] [--min-kb N]", + ); + console.error( + " or: node heapsnapshot-delta.mjs --lane-dir [--pid PID] [--top N] [--min-kb N]", + ); +} + +function fail(message) { + console.error(message); + process.exit(1); +} + +function parseArgs(argv) { + const options = { + top: 30, + minKb: 64, + laneDir: null, + pid: null, + files: [], + }; + + for (let index = 0; index < argv.length; index += 1) { + const arg = argv[index]; + if (arg === "--top") { + options.top = Number.parseInt(argv[index + 1] ?? "", 10); + index += 1; + continue; + } + if (arg === "--min-kb") { + options.minKb = Number.parseInt(argv[index + 1] ?? "", 10); + index += 1; + continue; + } + if (arg === "--lane-dir") { + options.laneDir = argv[index + 1] ?? null; + index += 1; + continue; + } + if (arg === "--pid") { + options.pid = Number.parseInt(argv[index + 1] ?? "", 10); + index += 1; + continue; + } + options.files.push(arg); + } + + if (!Number.isFinite(options.top) || options.top <= 0) { + fail("--top must be a positive integer"); + } + if (!Number.isFinite(options.minKb) || options.minKb < 0) { + fail("--min-kb must be a non-negative integer"); + } + if (options.pid !== null && (!Number.isInteger(options.pid) || options.pid <= 0)) { + fail("--pid must be a positive integer"); + } + + return options; +} + +function parseHeapFilename(filePath) { + const base = path.basename(filePath); + const match = base.match( + /^Heap\.(?\d{8}\.\d{6})\.(?\d+)\.0\.(?\d+)\.heapsnapshot$/u, + ); + if (!match?.groups) { + return null; + } + return { + filePath, + pid: Number.parseInt(match.groups.pid, 10), + stamp: match.groups.stamp, + sequence: Number.parseInt(match.groups.seq, 10), + }; +} + +function resolvePair(options) { + if (options.laneDir) { + const entries = fs + .readdirSync(options.laneDir) + .map((name) => parseHeapFilename(path.join(options.laneDir, name))) + .filter((entry) => entry !== null) + .filter((entry) => options.pid === null || entry.pid === options.pid) + .toSorted((left, right) => { + if (left.pid !== right.pid) { + return left.pid - right.pid; + } + if (left.stamp !== right.stamp) { + return left.stamp.localeCompare(right.stamp); + } + return left.sequence - right.sequence; + }); + + if (entries.length === 0) { + fail(`No matching heap snapshots found in ${options.laneDir}`); + } + + const groups = new Map(); + for (const entry of entries) { + const group = groups.get(entry.pid) ?? []; + group.push(entry); + groups.set(entry.pid, group); + } + + const candidates = Array.from(groups.values()) + .map((group) => ({ + pid: group[0].pid, + before: group[0], + after: group.at(-1), + count: group.length, + })) + .filter((entry) => entry.count >= 2); + + if (candidates.length === 0) { + fail(`Need at least two snapshots for one PID in ${options.laneDir}`); + } + + const chosen = + options.pid !== null + ? (candidates.find((entry) => entry.pid === options.pid) ?? null) + : candidates.toSorted((left, right) => right.count - left.count || left.pid - right.pid)[0]; + + if (!chosen) { + fail(`No PID with at least two snapshots matched in ${options.laneDir}`); + } + + return { + before: chosen.before.filePath, + after: chosen.after.filePath, + pid: chosen.pid, + snapshotCount: chosen.count, + }; + } + + if (options.files.length !== 2) { + printUsage(); + process.exit(1); + } + + return { + before: options.files[0], + after: options.files[1], + pid: null, + snapshotCount: 2, + }; +} + +function loadSummary(filePath) { + const data = JSON.parse(fs.readFileSync(filePath, "utf8")); + const meta = data.snapshot?.meta; + if (!meta) { + fail(`Invalid heap snapshot: ${filePath}`); + } + + const nodeFieldCount = meta.node_fields.length; + const typeNames = meta.node_types[0]; + const strings = data.strings; + const typeIndex = meta.node_fields.indexOf("type"); + const nameIndex = meta.node_fields.indexOf("name"); + const selfSizeIndex = meta.node_fields.indexOf("self_size"); + + const summary = new Map(); + for (let offset = 0; offset < data.nodes.length; offset += nodeFieldCount) { + const type = typeNames[data.nodes[offset + typeIndex]]; + const name = strings[data.nodes[offset + nameIndex]]; + const selfSize = data.nodes[offset + selfSizeIndex]; + const key = `${type}\t${name}`; + const current = summary.get(key) ?? { + type, + name, + selfSize: 0, + count: 0, + }; + current.selfSize += selfSize; + current.count += 1; + summary.set(key, current); + } + return { + nodeCount: data.snapshot.node_count, + summary, + }; +} + +function formatBytes(bytes) { + if (Math.abs(bytes) >= 1024 ** 2) { + return `${(bytes / 1024 ** 2).toFixed(2)} MiB`; + } + if (Math.abs(bytes) >= 1024) { + return `${(bytes / 1024).toFixed(1)} KiB`; + } + return `${bytes} B`; +} + +function formatDelta(bytes) { + return `${bytes >= 0 ? "+" : "-"}${formatBytes(Math.abs(bytes))}`; +} + +function truncate(text, maxLength) { + return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`; +} + +function main() { + const options = parseArgs(process.argv.slice(2)); + const pair = resolvePair(options); + const before = loadSummary(pair.before); + const after = loadSummary(pair.after); + const minBytes = options.minKb * 1024; + + const rows = []; + for (const [key, next] of after.summary) { + const previous = before.summary.get(key) ?? { selfSize: 0, count: 0 }; + const sizeDelta = next.selfSize - previous.selfSize; + const countDelta = next.count - previous.count; + if (sizeDelta < minBytes) { + continue; + } + rows.push({ + type: next.type, + name: next.name, + sizeDelta, + countDelta, + afterSize: next.selfSize, + afterCount: next.count, + }); + } + + rows.sort( + (left, right) => right.sizeDelta - left.sizeDelta || right.countDelta - left.countDelta, + ); + + console.log(`before: ${pair.before}`); + console.log(`after: ${pair.after}`); + if (pair.pid !== null) { + console.log(`pid: ${pair.pid} (${pair.snapshotCount} snapshots found)`); + } + console.log( + `nodes: ${before.nodeCount} -> ${after.nodeCount} (${after.nodeCount - before.nodeCount >= 0 ? "+" : ""}${after.nodeCount - before.nodeCount})`, + ); + console.log(`filter: top=${options.top} min=${options.minKb} KiB`); + console.log(""); + + if (rows.length === 0) { + console.log("No entries exceeded the minimum delta."); + return; + } + + for (const row of rows.slice(0, options.top)) { + console.log( + [ + formatDelta(row.sizeDelta).padStart(11), + `count ${row.countDelta >= 0 ? "+" : ""}${row.countDelta}`.padStart(10), + row.type.padEnd(16), + truncate(row.name || "(empty)", 96), + ].join(" "), + ); + } +} + +main(); diff --git a/scripts/test-parallel-memory.mjs b/scripts/test-parallel-memory.mjs index a4fa2602cd1..b036fc22fa6 100644 --- a/scripts/test-parallel-memory.mjs +++ b/scripts/test-parallel-memory.mjs @@ -11,7 +11,7 @@ const ANSI_ESCAPE_PATTERN = new RegExp( const COMPLETED_TEST_FILE_LINE_PATTERN = /(?(?:src|extensions|test|ui)\/\S+?\.(?:live\.test|e2e\.test|test)\.ts)\s+\(.*\)\s+(?\d+(?:\.\d+)?)(?ms|s)\s*$/; -const PS_COLUMNS = ["pid=", "ppid=", "rss="]; +const PS_COLUMNS = ["pid=", "ppid=", "rss=", "comm="]; function parseDurationMs(rawValue, unit) { const parsed = Number.parseFloat(rawValue); @@ -41,7 +41,7 @@ export function parseCompletedTestFileLines(text) { .filter((entry) => entry !== null); } -export function sampleProcessTreeRssKb(rootPid) { +export function getProcessTreeRecords(rootPid) { if (!Number.isInteger(rootPid) || rootPid <= 0 || process.platform === "win32") { return null; } @@ -54,13 +54,13 @@ export function sampleProcessTreeRssKb(rootPid) { } const childPidsByParent = new Map(); - const rssByPid = new Map(); + const recordsByPid = new Map(); for (const line of result.stdout.split(/\r?\n/u)) { const trimmed = line.trim(); if (!trimmed) { continue; } - const [pidRaw, parentRaw, rssRaw] = trimmed.split(/\s+/u); + const [pidRaw, parentRaw, rssRaw, commandRaw] = trimmed.split(/\s+/u, 4); const pid = Number.parseInt(pidRaw ?? "", 10); const parentPid = Number.parseInt(parentRaw ?? "", 10); const rssKb = Number.parseInt(rssRaw ?? "", 10); @@ -70,27 +70,30 @@ export function sampleProcessTreeRssKb(rootPid) { const siblings = childPidsByParent.get(parentPid) ?? []; siblings.push(pid); childPidsByParent.set(parentPid, siblings); - rssByPid.set(pid, rssKb); + recordsByPid.set(pid, { + pid, + parentPid, + rssKb, + command: commandRaw ?? "", + }); } - if (!rssByPid.has(rootPid)) { + if (!recordsByPid.has(rootPid)) { return null; } - let rssKb = 0; - let processCount = 0; const queue = [rootPid]; const visited = new Set(); + const records = []; while (queue.length > 0) { const pid = queue.shift(); if (pid === undefined || visited.has(pid)) { continue; } visited.add(pid); - const currentRssKb = rssByPid.get(pid); - if (currentRssKb !== undefined) { - rssKb += currentRssKb; - processCount += 1; + const record = recordsByPid.get(pid); + if (record) { + records.push(record); } for (const childPid of childPidsByParent.get(pid) ?? []) { if (!visited.has(childPid)) { @@ -99,5 +102,21 @@ export function sampleProcessTreeRssKb(rootPid) { } } + return records; +} + +export function sampleProcessTreeRssKb(rootPid) { + const records = getProcessTreeRecords(rootPid); + if (!records) { + return null; + } + + let rssKb = 0; + let processCount = 0; + for (const record of records) { + rssKb += record.rssKb; + processCount += 1; + } + return { rssKb, processCount }; } diff --git a/scripts/test-parallel.mjs b/scripts/test-parallel.mjs index 841132d69e0..c908ede7e4a 100644 --- a/scripts/test-parallel.mjs +++ b/scripts/test-parallel.mjs @@ -4,7 +4,11 @@ import os from "node:os"; import path from "node:path"; import { channelTestPrefixes } from "../vitest.channel-paths.mjs"; import { isUnitConfigTestFile } from "../vitest.unit-paths.mjs"; -import { parseCompletedTestFileLines, sampleProcessTreeRssKb } from "./test-parallel-memory.mjs"; +import { + getProcessTreeRecords, + parseCompletedTestFileLines, + sampleProcessTreeRssKb, +} from "./test-parallel-memory.mjs"; import { appendCapturedOutput, hasFatalTestRunOutput, @@ -725,6 +729,25 @@ const memoryTraceEnabled = (rawMemoryTrace !== "0" && rawMemoryTrace !== "false" && isCI)); const memoryTracePollMs = Math.max(250, parseEnvNumber("OPENCLAW_TEST_MEMORY_TRACE_POLL_MS", 1000)); const memoryTraceTopCount = Math.max(1, parseEnvNumber("OPENCLAW_TEST_MEMORY_TRACE_TOP_COUNT", 6)); +const heapSnapshotIntervalMs = Math.max( + 0, + parseEnvNumber("OPENCLAW_TEST_HEAPSNAPSHOT_INTERVAL_MS", 0), +); +const heapSnapshotMinIntervalMs = 5000; +const heapSnapshotEnabled = + process.platform !== "win32" && + heapSnapshotIntervalMs >= heapSnapshotMinIntervalMs; +const heapSnapshotEnabled = process.platform !== "win32" && heapSnapshotIntervalMs > 0; +const heapSnapshotSignal = process.env.OPENCLAW_TEST_HEAPSNAPSHOT_SIGNAL?.trim() || "SIGUSR2"; +const heapSnapshotBaseDir = heapSnapshotEnabled + ? path.resolve( + process.env.OPENCLAW_TEST_HEAPSNAPSHOT_DIR?.trim() || + path.join(os.tmpdir(), `openclaw-heapsnapshots-${Date.now()}`), + ) + : null; +const ensureNodeOptionFlag = (nodeOptions, flagPrefix, nextValue) => + nodeOptions.includes(flagPrefix) ? nodeOptions : `${nodeOptions} ${nextValue}`.trim(); +const isNodeLikeProcess = (command) => /(?:^|\/)node(?:$|\.exe$)/iu.test(command); const runOnce = (entry, extraArgs = []) => new Promise((resolve) => { @@ -757,23 +780,44 @@ const runOnce = (entry, extraArgs = []) => (acc, flag) => (acc.includes(flag) ? acc : `${acc} ${flag}`.trim()), nodeOptions, ); - const heapFlag = + const heapSnapshotDir = + heapSnapshotBaseDir === null ? null : path.join(heapSnapshotBaseDir, entry.name); + let resolvedNodeOptions = maxOldSpaceSizeMb && !nextNodeOptions.includes("--max-old-space-size=") - ? `--max-old-space-size=${maxOldSpaceSizeMb}` - : null; - const resolvedNodeOptions = heapFlag - ? `${nextNodeOptions} ${heapFlag}`.trim() - : nextNodeOptions; + ? `${nextNodeOptions} --max-old-space-size=${maxOldSpaceSizeMb}`.trim() + : nextNodeOptions; + if (heapSnapshotEnabled && heapSnapshotDir) { + try { + fs.mkdirSync(heapSnapshotDir, { recursive: true }); + } catch (err) { + console.error(`[test-parallel] failed to create heap snapshot dir ${heapSnapshotDir}: ${String(err)}`); + resolve(1); + return; + } + resolvedNodeOptions = ensureNodeOptionFlag( + resolvedNodeOptions, + "--diagnostic-dir=", + `--diagnostic-dir=${heapSnapshotDir}`, + ); + resolvedNodeOptions = ensureNodeOptionFlag( + resolvedNodeOptions, + "--heapsnapshot-signal=", + `--heapsnapshot-signal=${heapSnapshotSignal}`, + ); + } + } let output = ""; let fatalSeen = false; let childError = null; let child; let pendingLine = ""; let memoryPollTimer = null; + let heapSnapshotTimer = null; const memoryFileRecords = []; let initialTreeSample = null; let latestTreeSample = null; let peakTreeSample = null; + let heapSnapshotSequence = 0; const updatePeakTreeSample = (sample, reason) => { if (!sample) { return; @@ -782,6 +826,35 @@ const runOnce = (entry, extraArgs = []) => peakTreeSample = { ...sample, reason }; } }; + const triggerHeapSnapshot = (reason) => { + if (!heapSnapshotEnabled || !child?.pid || !heapSnapshotDir) { + return; + } + const records = getProcessTreeRecords(child.pid) ?? []; + const targetPids = records + .filter((record) => record.pid !== process.pid && isNodeLikeProcess(record.command)) + .map((record) => record.pid); + if (targetPids.length === 0) { + return; + } + heapSnapshotSequence += 1; + let signaledCount = 0; + for (const pid of targetPids) { + try { + process.kill(pid, heapSnapshotSignal); + signaledCount += 1; + } catch { + // Process likely exited between ps sampling and signal delivery. + } + } + if (signaledCount > 0) { + console.log( + `[test-parallel][heap] ${entry.name} seq=${String(heapSnapshotSequence)} reason=${reason} signaled=${String( + signaledCount, + )}/${String(targetPids.length)} dir=${heapSnapshotDir}`, + ); + } + }; const captureTreeSample = (reason) => { if (!memoryTraceEnabled || !child?.pid) { return null; @@ -877,6 +950,11 @@ const runOnce = (entry, extraArgs = []) => captureTreeSample("poll"); }, memoryTracePollMs); } + if (heapSnapshotEnabled) { + heapSnapshotTimer = setInterval(() => { + triggerHeapSnapshot("interval"); + }, heapSnapshotIntervalMs); + } } catch (err) { console.error(`[test-parallel] spawn failed: ${String(err)}`); resolve(1); @@ -905,6 +983,9 @@ const runOnce = (entry, extraArgs = []) => if (memoryPollTimer) { clearInterval(memoryPollTimer); } + if (heapSnapshotTimer) { + clearInterval(heapSnapshotTimer); + } children.delete(child); const resolvedCode = resolveTestRunExitCode({ code, signal, output, fatalSeen, childError }); logMemoryTraceSummary(); From 35bc00c55bc92be2766b145d7313a755dd1558b8 Mon Sep 17 00:00:00 2001 From: Josh Lehman Date: Thu, 19 Mar 2026 15:02:48 -0700 Subject: [PATCH 35/69] test: reduce low-memory Vitest pressure (#50652) * test: reduce low-memory Vitest pressure Reuse the bundled config baseline inside doc-baseline tests, keep that hotspot out of the shared unit-fast lane, and make OPENCLAW_TEST_PROFILE=low default to process forks instead of vmForks. * test: keep low-profile vmForks in CI Scope the low-profile forks fallback to local runs so the existing CI contracts lane keeps its current pool behavior. --- scripts/test-parallel.mjs | 26 +++++++++++--------- src/config/doc-baseline.test.ts | 29 +++++++++++++++++++---- src/config/doc-baseline.ts | 9 ++++--- test/fixtures/test-parallel.behavior.json | 4 ++++ 4 files changed, 49 insertions(+), 19 deletions(-) diff --git a/scripts/test-parallel.mjs b/scripts/test-parallel.mjs index c908ede7e4a..ed769a0c778 100644 --- a/scripts/test-parallel.mjs +++ b/scripts/test-parallel.mjs @@ -51,17 +51,6 @@ const hostMemoryGiB = Math.floor(os.totalmem() / 1024 ** 3); const highMemLocalHost = !isCI && hostMemoryGiB >= 96; const lowMemLocalHost = !isCI && hostMemoryGiB < 64; const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "", 10); -// vmForks is a big win for transform/import heavy suites. Node 24 is stable again -// for the default unit-fast lane after moving the known flaky files to fork-only -// isolation, but Node 25+ still falls back to process forks until re-validated. -// Keep it opt-out via OPENCLAW_TEST_VM_FORKS=0, and let users force-enable with =1. -const supportsVmForks = Number.isFinite(nodeMajor) ? nodeMajor <= 24 : true; -const useVmForks = - process.env.OPENCLAW_TEST_VM_FORKS === "1" || - (process.env.OPENCLAW_TEST_VM_FORKS !== "0" && !isWindows && supportsVmForks && !lowMemLocalHost); -const disableIsolation = process.env.OPENCLAW_TEST_NO_ISOLATE === "1"; -const includeGatewaySuite = process.env.OPENCLAW_TEST_INCLUDE_GATEWAY === "1"; -const includeExtensionsSuite = process.env.OPENCLAW_TEST_INCLUDE_EXTENSIONS === "1"; const rawTestProfile = process.env.OPENCLAW_TEST_PROFILE?.trim().toLowerCase(); const testProfile = rawTestProfile === "low" || @@ -72,6 +61,21 @@ const testProfile = ? rawTestProfile : "normal"; const isMacMiniProfile = testProfile === "macmini"; +// vmForks is a big win for transform/import heavy suites. Node 24 is stable again +// for the default unit-fast lane after moving the known flaky files to fork-only +// isolation, but Node 25+ still falls back to process forks until re-validated. +// Keep it opt-out via OPENCLAW_TEST_VM_FORKS=0, and let users force-enable with =1. +const supportsVmForks = Number.isFinite(nodeMajor) ? nodeMajor <= 24 : true; +const useVmForks = + process.env.OPENCLAW_TEST_VM_FORKS === "1" || + (process.env.OPENCLAW_TEST_VM_FORKS !== "0" && + !isWindows && + supportsVmForks && + !lowMemLocalHost && + (isCI || testProfile !== "low")); +const disableIsolation = process.env.OPENCLAW_TEST_NO_ISOLATE === "1"; +const includeGatewaySuite = process.env.OPENCLAW_TEST_INCLUDE_GATEWAY === "1"; +const includeExtensionsSuite = process.env.OPENCLAW_TEST_INCLUDE_EXTENSIONS === "1"; // Even on low-memory hosts, keep the isolated lane split so files like // git-commit.test.ts still get the worker/process isolation they require. const shouldSplitUnitRuns = testProfile !== "serial"; diff --git a/src/config/doc-baseline.test.ts b/src/config/doc-baseline.test.ts index 27fe084d2cf..a1e670401b1 100644 --- a/src/config/doc-baseline.test.ts +++ b/src/config/doc-baseline.test.ts @@ -13,6 +13,21 @@ import { describe("config doc baseline", () => { const tempRoots: string[] = []; + let sharedBaselinePromise: Promise>> | null = + null; + let sharedRenderedPromise: Promise< + Awaited> + > | null = null; + + function getSharedBaseline() { + sharedBaselinePromise ??= buildConfigDocBaseline(); + return sharedBaselinePromise; + } + + function getSharedRendered() { + sharedRenderedPromise ??= renderConfigDocBaselineStatefile(getSharedBaseline()); + return sharedRenderedPromise; + } afterEach(async () => { await Promise.all( @@ -31,7 +46,7 @@ describe("config doc baseline", () => { }); it("normalizes array and record paths to wildcard form", async () => { - const baseline = await buildConfigDocBaseline(); + const baseline = await getSharedBaseline(); const paths = new Set(baseline.entries.map((entry) => entry.path)); expect(paths.has("session.sendPolicy.rules.*.match.keyPrefix")).toBe(true); @@ -40,7 +55,7 @@ describe("config doc baseline", () => { }); it("includes core, channel, and plugin config metadata", async () => { - const baseline = await buildConfigDocBaseline(); + const baseline = await getSharedBaseline(); const byPath = new Map(baseline.entries.map((entry) => [entry.path, entry])); expect(byPath.get("gateway.auth.token")).toMatchObject({ @@ -58,7 +73,7 @@ describe("config doc baseline", () => { }); it("preserves help text and tags from merged schema hints", async () => { - const baseline = await buildConfigDocBaseline(); + const baseline = await getSharedBaseline(); const byPath = new Map(baseline.entries.map((entry) => [entry.path, entry])); const tokenEntry = byPath.get("gateway.auth.token"); @@ -68,7 +83,7 @@ describe("config doc baseline", () => { }); it("matches array help hints that still use [] notation", async () => { - const baseline = await buildConfigDocBaseline(); + const baseline = await getSharedBaseline(); const byPath = new Map(baseline.entries.map((entry) => [entry.path, entry])); expect(byPath.get("session.sendPolicy.rules.*.match.keyPrefix")).toMatchObject({ @@ -78,7 +93,7 @@ describe("config doc baseline", () => { }); it("walks union branches for nested config keys", async () => { - const baseline = await buildConfigDocBaseline(); + const baseline = await getSharedBaseline(); const byPath = new Map(baseline.entries.map((entry) => [entry.path, entry])); expect(byPath.get("bindings.*")).toMatchObject({ @@ -121,11 +136,13 @@ describe("config doc baseline", () => { it("supports check mode for stale generated artifacts", async () => { const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-config-doc-baseline-")); tempRoots.push(tempRoot); + const rendered = getSharedRendered(); const initial = await writeConfigDocBaselineStatefile({ repoRoot: tempRoot, jsonPath: "docs/.generated/config-baseline.json", statefilePath: "docs/.generated/config-baseline.jsonl", + rendered, }); expect(initial.wrote).toBe(true); @@ -134,6 +151,7 @@ describe("config doc baseline", () => { jsonPath: "docs/.generated/config-baseline.json", statefilePath: "docs/.generated/config-baseline.jsonl", check: true, + rendered, }); expect(current.changed).toBe(false); @@ -153,6 +171,7 @@ describe("config doc baseline", () => { jsonPath: "docs/.generated/config-baseline.json", statefilePath: "docs/.generated/config-baseline.jsonl", check: true, + rendered, }); expect(stale.changed).toBe(true); expect(stale.wrote).toBe(false); diff --git a/src/config/doc-baseline.ts b/src/config/doc-baseline.ts index 2f6031589d8..525c91bb521 100644 --- a/src/config/doc-baseline.ts +++ b/src/config/doc-baseline.ts @@ -658,11 +658,11 @@ export async function buildConfigDocBaseline(): Promise { } export async function renderConfigDocBaselineStatefile( - baseline?: ConfigDocBaseline, + baseline?: ConfigDocBaseline | Promise, ): Promise { const start = Date.now(); logConfigDocBaselineDebug("render statefile start"); - const resolvedBaseline = baseline ?? (await buildConfigDocBaseline()); + const resolvedBaseline = baseline ? await baseline : await buildConfigDocBaseline(); const json = `${JSON.stringify(resolvedBaseline, null, 2)}\n`; const metadataLine = JSON.stringify({ generatedBy: GENERATED_BY, @@ -706,13 +706,16 @@ export async function writeConfigDocBaselineStatefile(params?: { check?: boolean; jsonPath?: string; statefilePath?: string; + rendered?: ConfigDocBaselineStatefileRender | Promise; }): Promise { const start = Date.now(); logConfigDocBaselineDebug("write statefile start"); const repoRoot = params?.repoRoot ?? resolveRepoRoot(); const jsonPath = path.resolve(repoRoot, params?.jsonPath ?? DEFAULT_JSON_OUTPUT); const statefilePath = path.resolve(repoRoot, params?.statefilePath ?? DEFAULT_STATEFILE_OUTPUT); - const rendered = await renderConfigDocBaselineStatefile(); + const rendered = params?.rendered + ? await params.rendered + : await renderConfigDocBaselineStatefile(); logConfigDocBaselineDebug(`render statefile done elapsedMs=${Date.now() - start}`); logConfigDocBaselineDebug(`read current json start ${jsonPath}`); const currentJson = await readIfExists(jsonPath); diff --git a/test/fixtures/test-parallel.behavior.json b/test/fixtures/test-parallel.behavior.json index bdbb4583913..df7b3939027 100644 --- a/test/fixtures/test-parallel.behavior.json +++ b/test/fixtures/test-parallel.behavior.json @@ -13,6 +13,10 @@ "file": "src/infra/git-commit.test.ts", "reason": "Mutates process.cwd() and core loader seams." }, + { + "file": "src/config/doc-baseline.test.ts", + "reason": "Rebuilds bundled config baselines through many channel schema subprocesses; keep out of the shared lane." + }, { "file": "extensions/imessage/src/monitor.shutdown.unhandled-rejection.test.ts", "reason": "Touches process-level unhandledRejection listeners." From 2884ac13b2dd761732361d1f655c9891d453e641 Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Thu, 19 Mar 2026 17:13:19 -0500 Subject: [PATCH 36/69] test: add Zalo pairing lifecycle regression --- .../src/monitor.bot-menu.lifecycle.test.ts | 4 +- .../src/monitor.card-action.lifecycle.test.ts | 4 +- .../src/monitor.pairing.lifecycle.test.ts | 297 ++++++++++++++++++ .../src/monitor.reply-once.lifecycle.test.ts | 111 ++++--- 4 files changed, 360 insertions(+), 56 deletions(-) create mode 100644 extensions/zalo/src/monitor.pairing.lifecycle.test.ts diff --git a/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts b/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts index ee04b27b538..50c3b3d6f32 100644 --- a/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts +++ b/extensions/feishu/src/monitor.bot-menu.lifecycle.test.ts @@ -15,8 +15,8 @@ const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); const createFeishuReplyDispatcherMock = vi.hoisted(() => vi.fn()); -const resolveBoundConversationMock = vi.hoisted( - () => vi.fn<() => BoundConversation | null>(() => null), +const resolveBoundConversationMock = vi.hoisted(() => + vi.fn<() => BoundConversation | null>(() => null), ); const touchBindingMock = vi.hoisted(() => vi.fn()); const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); diff --git a/extensions/feishu/src/monitor.card-action.lifecycle.test.ts b/extensions/feishu/src/monitor.card-action.lifecycle.test.ts index 3171a7a125e..e297fff9a09 100644 --- a/extensions/feishu/src/monitor.card-action.lifecycle.test.ts +++ b/extensions/feishu/src/monitor.card-action.lifecycle.test.ts @@ -16,8 +16,8 @@ const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); const createFeishuReplyDispatcherMock = vi.hoisted(() => vi.fn()); -const resolveBoundConversationMock = vi.hoisted( - () => vi.fn<() => BoundConversation | null>(() => null), +const resolveBoundConversationMock = vi.hoisted(() => + vi.fn<() => BoundConversation | null>(() => null), ); const touchBindingMock = vi.hoisted(() => vi.fn()); const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); diff --git a/extensions/zalo/src/monitor.pairing.lifecycle.test.ts b/extensions/zalo/src/monitor.pairing.lifecycle.test.ts new file mode 100644 index 00000000000..383474114cf --- /dev/null +++ b/extensions/zalo/src/monitor.pairing.lifecycle.test.ts @@ -0,0 +1,297 @@ +import { createServer, type RequestListener } from "node:http"; +import type { AddressInfo } from "node:net"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { createEmptyPluginRegistry } from "../../../src/plugins/registry.js"; +import { setActivePluginRegistry } from "../../../src/plugins/runtime.js"; +import { createPluginRuntimeMock } from "../../../test/helpers/extensions/plugin-runtime-mock.js"; +import type { OpenClawConfig, PluginRuntime } from "../runtime-api.js"; +import type { ResolvedZaloAccount } from "./accounts.js"; +import { clearZaloWebhookSecurityStateForTest, monitorZaloProvider } from "./monitor.js"; + +const setWebhookMock = vi.hoisted(() => vi.fn(async () => ({ ok: true, result: { url: "" } }))); +const deleteWebhookMock = vi.hoisted(() => vi.fn(async () => ({ ok: true, result: { url: "" } }))); +const getWebhookInfoMock = vi.hoisted(() => vi.fn(async () => ({ ok: true, result: { url: "" } }))); +const getUpdatesMock = vi.hoisted(() => vi.fn(() => new Promise(() => {}))); +const sendChatActionMock = vi.hoisted(() => vi.fn(async () => ({ ok: true }))); +const sendMessageMock = vi.hoisted(() => + vi.fn(async () => ({ ok: true, result: { message_id: "pairing-zalo-1" } })), +); +const sendPhotoMock = vi.hoisted(() => vi.fn(async () => ({ ok: true }))); +const getZaloRuntimeMock = vi.hoisted(() => vi.fn()); + +vi.mock("./api.js", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + deleteWebhook: deleteWebhookMock, + getUpdates: getUpdatesMock, + getWebhookInfo: getWebhookInfoMock, + sendChatAction: sendChatActionMock, + sendMessage: sendMessageMock, + sendPhoto: sendPhotoMock, + setWebhook: setWebhookMock, + }; +}); + +vi.mock("./runtime.js", () => ({ + getZaloRuntime: getZaloRuntimeMock, +})); + +async function withServer(handler: RequestListener, fn: (baseUrl: string) => Promise) { + const server = createServer(handler); + await new Promise((resolve) => { + server.listen(0, "127.0.0.1", () => resolve()); + }); + const address = server.address() as AddressInfo | null; + if (!address) { + throw new Error("missing server address"); + } + try { + await fn(`http://127.0.0.1:${address.port}`); + } finally { + await new Promise((resolve) => server.close(() => resolve())); + } +} + +function createLifecycleConfig(): OpenClawConfig { + return { + channels: { + zalo: { + enabled: true, + accounts: { + "acct-zalo-pairing": { + enabled: true, + webhookUrl: "https://example.com/hooks/zalo", + webhookSecret: "supersecret", // pragma: allowlist secret + dmPolicy: "pairing", + allowFrom: [], + }, + }, + }, + }, + } as OpenClawConfig; +} + +function createLifecycleAccount(): ResolvedZaloAccount { + return { + accountId: "acct-zalo-pairing", + enabled: true, + token: "zalo-token", + tokenSource: "config", + config: { + webhookUrl: "https://example.com/hooks/zalo", + webhookSecret: "supersecret", // pragma: allowlist secret + dmPolicy: "pairing", + allowFrom: [], + }, + } as ResolvedZaloAccount; +} + +function createRuntimeEnv() { + return { + log: vi.fn<(message: string) => void>(), + error: vi.fn<(message: string) => void>(), + }; +} + +function createTextUpdate(messageId: string) { + return { + event_name: "message.text.received", + message: { + from: { id: "user-unauthorized", name: "Unauthorized User" }, + chat: { id: "dm-pairing-1", chat_type: "PRIVATE" as const }, + message_id: messageId, + date: Math.floor(Date.now() / 1000), + text: "hello from zalo", + }, + }; +} + +async function settleAsyncWork(): Promise { + for (let i = 0; i < 6; i += 1) { + await Promise.resolve(); + await new Promise((resolve) => setTimeout(resolve, 0)); + } +} + +async function postWebhookUpdate(params: { + baseUrl: string; + path: string; + secret: string; + payload: Record; +}) { + return await fetch(`${params.baseUrl}${params.path}`, { + method: "POST", + headers: { + "content-type": "application/json", + "x-bot-api-secret-token": params.secret, + }, + body: JSON.stringify(params.payload), + }); +} + +describe("Zalo pairing lifecycle", () => { + const readAllowFromStoreMock = vi.fn(async () => [] as string[]); + const upsertPairingRequestMock = vi.fn(async () => ({ code: "PAIRCODE", created: true })); + beforeEach(() => { + vi.clearAllMocks(); + clearZaloWebhookSecurityStateForTest(); + + getZaloRuntimeMock.mockReturnValue( + createPluginRuntimeMock({ + channel: { + pairing: { + readAllowFromStore: + readAllowFromStoreMock as unknown as PluginRuntime["channel"]["pairing"]["readAllowFromStore"], + upsertPairingRequest: + upsertPairingRequestMock as unknown as PluginRuntime["channel"]["pairing"]["upsertPairingRequest"], + }, + commands: { + shouldComputeCommandAuthorized: vi.fn(() => false), + resolveCommandAuthorizedFromAuthorizers: vi.fn(() => false), + }, + }, + }), + ); + }); + + afterEach(() => { + setActivePluginRegistry(createEmptyPluginRegistry()); + }); + + it("emits one pairing reply across duplicate webhook replay and scopes reads and writes to accountId", async () => { + const registry = createEmptyPluginRegistry(); + setActivePluginRegistry(registry); + const abort = new AbortController(); + const runtime = createRuntimeEnv(); + const run = monitorZaloProvider({ + token: "zalo-token", + account: createLifecycleAccount(), + config: createLifecycleConfig(), + runtime, + abortSignal: abort.signal, + useWebhook: true, + webhookUrl: "https://example.com/hooks/zalo", + webhookSecret: "supersecret", + }); + + await vi.waitFor(() => { + expect(setWebhookMock).toHaveBeenCalledTimes(1); + expect(registry.httpRoutes).toHaveLength(1); + }); + const route = registry.httpRoutes[0]; + if (!route) { + throw new Error("missing plugin HTTP route"); + } + + await withServer( + (req, res) => route.handler(req, res), + async (baseUrl) => { + const payload = createTextUpdate(`zalo-pairing-${Date.now()}`); + const first = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); + const second = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); + + expect(first.status).toBe(200); + expect(second.status).toBe(200); + await settleAsyncWork(); + }, + ); + + expect(readAllowFromStoreMock).toHaveBeenCalledTimes(1); + expect(readAllowFromStoreMock).toHaveBeenCalledWith( + expect.objectContaining({ + channel: "zalo", + accountId: "acct-zalo-pairing", + }), + ); + expect(upsertPairingRequestMock).toHaveBeenCalledTimes(1); + expect(upsertPairingRequestMock).toHaveBeenCalledWith( + expect.objectContaining({ + channel: "zalo", + accountId: "acct-zalo-pairing", + id: "user-unauthorized", + }), + ); + expect(sendMessageMock).toHaveBeenCalledTimes(1); + expect(sendMessageMock).toHaveBeenCalledWith( + "zalo-token", + expect.objectContaining({ + chat_id: "dm-pairing-1", + text: expect.stringContaining("PAIRCODE"), + }), + undefined, + ); + + abort.abort(); + await run; + }); + + it("does not emit a second pairing reply when replay arrives after the first send fails", async () => { + sendMessageMock.mockRejectedValueOnce(new Error("pairing send failed")); + + const registry = createEmptyPluginRegistry(); + setActivePluginRegistry(registry); + const abort = new AbortController(); + const runtime = createRuntimeEnv(); + const run = monitorZaloProvider({ + token: "zalo-token", + account: createLifecycleAccount(), + config: createLifecycleConfig(), + runtime, + abortSignal: abort.signal, + useWebhook: true, + webhookUrl: "https://example.com/hooks/zalo", + webhookSecret: "supersecret", + }); + + await vi.waitFor(() => { + expect(setWebhookMock).toHaveBeenCalledTimes(1); + expect(registry.httpRoutes).toHaveLength(1); + }); + const route = registry.httpRoutes[0]; + if (!route) { + throw new Error("missing plugin HTTP route"); + } + + await withServer( + (req, res) => route.handler(req, res), + async (baseUrl) => { + const payload = createTextUpdate(`zalo-pairing-retry-${Date.now()}`); + const first = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); + await settleAsyncWork(); + const replay = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); + + expect(first.status).toBe(200); + expect(replay.status).toBe(200); + await settleAsyncWork(); + }, + ); + + expect(upsertPairingRequestMock).toHaveBeenCalledTimes(1); + expect(sendMessageMock).toHaveBeenCalledTimes(1); + expect(runtime.error).not.toHaveBeenCalled(); + + abort.abort(); + await run; + }); +}); diff --git a/extensions/zalo/src/monitor.reply-once.lifecycle.test.ts b/extensions/zalo/src/monitor.reply-once.lifecycle.test.ts index ab4b409fc23..8b16869c0a2 100644 --- a/extensions/zalo/src/monitor.reply-once.lifecycle.test.ts +++ b/extensions/zalo/src/monitor.reply-once.lifecycle.test.ts @@ -1,15 +1,12 @@ import { createServer, type RequestListener } from "node:http"; import type { AddressInfo } from "node:net"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; -import { createPluginRuntimeMock } from "../../../test/helpers/extensions/plugin-runtime-mock.js"; import { createEmptyPluginRegistry } from "../../../src/plugins/registry.js"; import { setActivePluginRegistry } from "../../../src/plugins/runtime.js"; +import { createPluginRuntimeMock } from "../../../test/helpers/extensions/plugin-runtime-mock.js"; import type { OpenClawConfig, PluginRuntime } from "../runtime-api.js"; -import { - clearZaloWebhookSecurityStateForTest, - monitorZaloProvider, -} from "./monitor.js"; import type { ResolvedZaloAccount } from "./accounts.js"; +import { clearZaloWebhookSecurityStateForTest, monitorZaloProvider } from "./monitor.js"; const setWebhookMock = vi.hoisted(() => vi.fn(async () => ({ ok: true, result: { url: "" } }))); const deleteWebhookMock = vi.hoisted(() => vi.fn(async () => ({ ok: true, result: { url: "" } }))); @@ -175,9 +172,11 @@ describe("Zalo reply-once lifecycle", () => { }); it("routes one accepted webhook event to one visible reply across duplicate replay", async () => { - dispatchReplyWithBufferedBlockDispatcherMock.mockImplementation(async ({ dispatcherOptions }) => { - await dispatcherOptions.deliver({ text: "zalo reply once" }); - }); + dispatchReplyWithBufferedBlockDispatcherMock.mockImplementation( + async ({ dispatcherOptions }) => { + await dispatcherOptions.deliver({ text: "zalo reply once" }); + }, + ); const registry = createEmptyPluginRegistry(); setActivePluginRegistry(registry); @@ -201,25 +200,28 @@ describe("Zalo reply-once lifecycle", () => { throw new Error("missing plugin HTTP route"); } - await withServer((req, res) => route.handler(req, res), async (baseUrl) => { - const payload = createTextUpdate(`zalo-replay-${Date.now()}`); - const first = await postWebhookUpdate({ - baseUrl, - path: "/hooks/zalo", - secret: "supersecret", - payload, - }); - const second = await postWebhookUpdate({ - baseUrl, - path: "/hooks/zalo", - secret: "supersecret", - payload, - }); + await withServer( + (req, res) => route.handler(req, res), + async (baseUrl) => { + const payload = createTextUpdate(`zalo-replay-${Date.now()}`); + const first = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); + const second = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); - expect(first.status).toBe(200); - expect(second.status).toBe(200); - await settleAsyncWork(); - }); + expect(first.status).toBe(200); + expect(second.status).toBe(200); + await settleAsyncWork(); + }, + ); expect(finalizeInboundContextMock).toHaveBeenCalledTimes(1); expect(finalizeInboundContextMock).toHaveBeenCalledWith( @@ -253,13 +255,15 @@ describe("Zalo reply-once lifecycle", () => { it("does not emit a second visible reply when replay arrives after a post-send failure", async () => { let dispatchAttempts = 0; - dispatchReplyWithBufferedBlockDispatcherMock.mockImplementation(async ({ dispatcherOptions }) => { - dispatchAttempts += 1; - await dispatcherOptions.deliver({ text: "zalo reply after failure" }); - if (dispatchAttempts === 1) { - throw new Error("post-send failure"); - } - }); + dispatchReplyWithBufferedBlockDispatcherMock.mockImplementation( + async ({ dispatcherOptions }) => { + dispatchAttempts += 1; + await dispatcherOptions.deliver({ text: "zalo reply after failure" }); + if (dispatchAttempts === 1) { + throw new Error("post-send failure"); + } + }, + ); const registry = createEmptyPluginRegistry(); setActivePluginRegistry(registry); @@ -282,26 +286,29 @@ describe("Zalo reply-once lifecycle", () => { throw new Error("missing plugin HTTP route"); } - await withServer((req, res) => route.handler(req, res), async (baseUrl) => { - const payload = createTextUpdate(`zalo-retry-${Date.now()}`); - const first = await postWebhookUpdate({ - baseUrl, - path: "/hooks/zalo", - secret: "supersecret", - payload, - }); - await settleAsyncWork(); - const replay = await postWebhookUpdate({ - baseUrl, - path: "/hooks/zalo", - secret: "supersecret", - payload, - }); + await withServer( + (req, res) => route.handler(req, res), + async (baseUrl) => { + const payload = createTextUpdate(`zalo-retry-${Date.now()}`); + const first = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); + await settleAsyncWork(); + const replay = await postWebhookUpdate({ + baseUrl, + path: "/hooks/zalo", + secret: "supersecret", + payload, + }); - expect(first.status).toBe(200); - expect(replay.status).toBe(200); - await settleAsyncWork(); - }); + expect(first.status).toBe(200); + expect(replay.status).toBe(200); + await settleAsyncWork(); + }, + ); expect(dispatchReplyWithBufferedBlockDispatcherMock).toHaveBeenCalledTimes(1); expect(sendMessageMock).toHaveBeenCalledTimes(1); From ac850e815b08a0845ca722011a9eb235eaf4742b Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 15:01:02 -0700 Subject: [PATCH 37/69] fix(ci): replace tlon git api dependency --- extensions/tlon/package.json | 3 +- extensions/tlon/src/channel.runtime.ts | 3 +- extensions/tlon/src/tlon-api.ts | 301 +++++++++++++++++++++++ extensions/tlon/src/tloncorp-api.d.ts | 14 -- extensions/tlon/src/urbit/upload.test.ts | 6 +- extensions/tlon/src/urbit/upload.ts | 2 +- pnpm-lock.yaml | 200 +++------------ 7 files changed, 341 insertions(+), 188 deletions(-) create mode 100644 extensions/tlon/src/tlon-api.ts delete mode 100644 extensions/tlon/src/tloncorp-api.d.ts diff --git a/extensions/tlon/package.json b/extensions/tlon/package.json index a7fdf99b2c4..c1c718ed4b6 100644 --- a/extensions/tlon/package.json +++ b/extensions/tlon/package.json @@ -4,7 +4,8 @@ "description": "OpenClaw Tlon/Urbit channel plugin", "type": "module", "dependencies": { - "@tloncorp/api": "git+https://github.com/tloncorp/api-beta.git#7eede1c1a756977b09f96aa14a92e2b06318ae87", + "@aws-sdk/client-s3": "3.1000.0", + "@aws-sdk/s3-request-presigner": "3.1000.0", "@tloncorp/tlon-skill": "0.2.2", "@urbit/aura": "^3.0.0", "zod": "^4.3.6" diff --git a/extensions/tlon/src/channel.runtime.ts b/extensions/tlon/src/channel.runtime.ts index 78ed1f16e63..56d59d6003b 100644 --- a/extensions/tlon/src/channel.runtime.ts +++ b/extensions/tlon/src/channel.runtime.ts @@ -1,5 +1,4 @@ import crypto from "node:crypto"; -import { configureClient } from "@tloncorp/api"; import type { ChannelAccountSnapshot, ChannelOutboundAdapter, @@ -15,6 +14,7 @@ import { parseTlonTarget, resolveTlonOutboundTarget, } from "./targets.js"; +import { configureClient } from "./tlon-api.js"; import { resolveTlonAccount } from "./types.js"; import { authenticate } from "./urbit/auth.js"; import { ssrfPolicyFromAllowPrivateNetwork } from "./urbit/context.js"; @@ -169,6 +169,7 @@ export const tlonRuntimeOutbound: ChannelOutboundAdapter = { shipName: account.ship.replace(/^~/, ""), verbose: false, getCode: async () => account.code, + allowPrivateNetwork: account.allowPrivateNetwork ?? undefined, }); const uploadedUrl = mediaUrl ? await uploadImageFromUrl(mediaUrl) : undefined; diff --git a/extensions/tlon/src/tlon-api.ts b/extensions/tlon/src/tlon-api.ts new file mode 100644 index 00000000000..04f05979102 --- /dev/null +++ b/extensions/tlon/src/tlon-api.ts @@ -0,0 +1,301 @@ +import crypto from "node:crypto"; +import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3"; +import { getSignedUrl } from "@aws-sdk/s3-request-presigner"; +import { authenticate } from "./urbit/auth.js"; +import { scryUrbitPath } from "./urbit/channel-ops.js"; +import { ssrfPolicyFromAllowPrivateNetwork } from "./urbit/context.js"; + +type ClientConfig = { + shipUrl: string; + shipName: string; + verbose: boolean; + getCode: () => Promise; + allowPrivateNetwork?: boolean; +}; + +type StorageService = "presigned-url" | "credentials"; + +type StorageConfiguration = { + buckets: string[]; + currentBucket: string; + region: string; + publicUrlBase: string; + presignedUrl: string; + service: StorageService; +}; + +type StorageCredentials = { + endpoint: string; + accessKeyId: string; + secretAccessKey: string; +}; + +type UploadFileParams = { + blob: Blob; + fileName?: string; + contentType?: string; +}; + +type UploadResult = { + url: string; +}; + +const MEMEX_BASE_URL = "https://memex.tlon.network"; + +const mimeToExt: Record = { + "image/gif": ".gif", + "image/heic": ".heic", + "image/heif": ".heif", + "image/jpeg": ".jpg", + "image/jpg": ".jpg", + "image/png": ".png", + "image/webp": ".webp", +}; + +let currentClientConfig: ClientConfig | null = null; + +export function configureClient(params: ClientConfig): void { + currentClientConfig = { + ...params, + shipName: params.shipName.replace(/^~/, ""), + }; +} + +function requireClientConfig(): ClientConfig { + if (!currentClientConfig) { + throw new Error("Tlon client not configured"); + } + return currentClientConfig; +} + +function getExtensionFromMimeType(mimeType?: string): string { + if (!mimeType) { + return ".jpg"; + } + return mimeToExt[mimeType.toLowerCase()] || ".jpg"; +} + +function hasCustomS3Creds( + credentials: StorageCredentials | null, +): credentials is StorageCredentials { + return Boolean(credentials?.accessKeyId && credentials?.endpoint && credentials?.secretAccessKey); +} + +function isStorageCredentials(value: unknown): value is StorageCredentials { + if (!value || typeof value !== "object") { + return false; + } + const record = value as Record; + return ( + typeof record.endpoint === "string" && + typeof record.accessKeyId === "string" && + typeof record.secretAccessKey === "string" + ); +} + +function isHostedShipUrl(shipUrl: string): boolean { + try { + const { hostname } = new URL(shipUrl); + return hostname.endsWith("tlon.network") || hostname.endsWith(".test.tlon.systems"); + } catch { + return shipUrl.endsWith("tlon.network") || shipUrl.endsWith(".test.tlon.systems"); + } +} + +function prefixEndpoint(endpoint: string): string { + return endpoint.match(/https?:\/\//) ? endpoint : `https://${endpoint}`; +} + +function sanitizeFileName(fileName: string): string { + return fileName.split(/[/\\]/).pop() || fileName; +} + +async function getAuthCookie(config: ClientConfig): Promise { + return await authenticate(config.shipUrl, await config.getCode(), { + ssrfPolicy: ssrfPolicyFromAllowPrivateNetwork(config.allowPrivateNetwork), + }); +} + +async function scryJson(config: ClientConfig, cookie: string, path: string): Promise { + return (await scryUrbitPath( + { + baseUrl: config.shipUrl, + cookie, + ssrfPolicy: ssrfPolicyFromAllowPrivateNetwork(config.allowPrivateNetwork), + }, + { path, auditContext: "tlon-storage-scry" }, + )) as T; +} + +async function getStorageConfiguration( + config: ClientConfig, + cookie: string, +): Promise { + const result = await scryJson< + { "storage-update"?: { configuration?: StorageConfiguration } } | StorageConfiguration + >(config, cookie, "/storage/configuration.json"); + + if ("storage-update" in result && result["storage-update"]?.configuration) { + return result["storage-update"].configuration; + } + if ("currentBucket" in result) { + return result; + } + throw new Error("Invalid storage configuration response"); +} + +async function getStorageCredentials( + config: ClientConfig, + cookie: string, +): Promise { + const result = await scryJson< + { "storage-update"?: { credentials?: StorageCredentials } } | StorageCredentials + >(config, cookie, "/storage/credentials.json"); + + if ("storage-update" in result) { + return result["storage-update"]?.credentials ?? null; + } + if (isStorageCredentials(result)) { + return result; + } + return null; +} + +async function getMemexUploadUrl(params: { + config: ClientConfig; + cookie: string; + contentLength: number; + contentType: string; + fileName: string; +}): Promise<{ hostedUrl: string; uploadUrl: string }> { + const token = await scryJson( + params.config, + params.cookie, + "/genuine/secret.json", + ); + const resolvedToken = typeof token === "string" ? token : token.secret; + if (!resolvedToken) { + throw new Error("Missing genuine secret"); + } + + const endpoint = `${MEMEX_BASE_URL}/v1/${params.config.shipName}/upload`; + const response = await fetch(endpoint, { + method: "PUT", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + token: resolvedToken, + contentLength: params.contentLength, + contentType: params.contentType, + fileName: params.fileName, + }), + }); + + if (!response.ok) { + throw new Error(`Memex upload request failed: ${response.status}`); + } + + const data = (await response.json()) as { url?: string; filePath?: string } | null; + if (!data?.url || !data.filePath) { + throw new Error("Invalid response from Memex"); + } + + return { hostedUrl: data.filePath, uploadUrl: data.url }; +} + +export async function uploadFile(params: UploadFileParams): Promise { + const config = requireClientConfig(); + const cookie = await getAuthCookie(config); + + const [storageConfig, credentials] = await Promise.all([ + getStorageConfiguration(config, cookie), + getStorageCredentials(config, cookie), + ]); + + const contentType = params.contentType || params.blob.type || "application/octet-stream"; + const extension = getExtensionFromMimeType(contentType); + const fileName = sanitizeFileName(params.fileName || `upload${extension}`); + const fileKey = `${config.shipName}/${Date.now()}-${crypto.randomUUID()}-${fileName}`; + + const useMemex = + isHostedShipUrl(config.shipUrl) && + (storageConfig.service === "presigned-url" || !hasCustomS3Creds(credentials)); + + if (useMemex) { + const { hostedUrl, uploadUrl } = await getMemexUploadUrl({ + config, + cookie, + contentLength: params.blob.size, + contentType, + fileName: fileKey, + }); + + const response = await fetch(uploadUrl, { + method: "PUT", + body: params.blob, + headers: { + "Cache-Control": "public, max-age=3600", + "Content-Type": contentType, + }, + }); + + if (!response.ok) { + throw new Error(`Upload failed: ${response.status}`); + } + + return { url: hostedUrl }; + } + + if (!hasCustomS3Creds(credentials)) { + throw new Error("No storage credentials configured"); + } + + const endpoint = new URL(prefixEndpoint(credentials.endpoint)); + const client = new S3Client({ + endpoint: { + protocol: endpoint.protocol.slice(0, -1) as "http" | "https", + hostname: endpoint.host, + path: endpoint.pathname || "/", + }, + region: storageConfig.region || "us-east-1", + credentials: { + accessKeyId: credentials.accessKeyId, + secretAccessKey: credentials.secretAccessKey, + }, + forcePathStyle: true, + }); + + const headers: Record = { + "Cache-Control": "public, max-age=3600", + "Content-Type": contentType, + "x-amz-acl": "public-read", + }; + + const command = new PutObjectCommand({ + Bucket: storageConfig.currentBucket, + Key: fileKey, + ContentType: headers["Content-Type"], + CacheControl: headers["Cache-Control"], + ACL: "public-read", + }); + + const signedUrl = await getSignedUrl(client, command, { + expiresIn: 3600, + signableHeaders: new Set(Object.keys(headers)), + }); + + const response = await fetch(signedUrl, { + method: "PUT", + body: params.blob, + headers: signedUrl.includes("digitaloceanspaces.com") ? headers : undefined, + }); + + if (!response.ok) { + throw new Error(`Upload failed: ${response.status}`); + } + + const publicUrl = storageConfig.publicUrlBase + ? new URL(fileKey, storageConfig.publicUrlBase).toString() + : signedUrl.split("?")[0]; + + return { url: publicUrl }; +} diff --git a/extensions/tlon/src/tloncorp-api.d.ts b/extensions/tlon/src/tloncorp-api.d.ts deleted file mode 100644 index c14eba98133..00000000000 --- a/extensions/tlon/src/tloncorp-api.d.ts +++ /dev/null @@ -1,14 +0,0 @@ -declare module "@tloncorp/api" { - export function configureClient(params: { - shipUrl: string; - shipName: string; - verbose: boolean; - getCode: () => Promise; - }): void; - - export function uploadFile(params: { - blob: Blob; - fileName: string; - contentType: string; - }): Promise<{ url: string }>; -} diff --git a/extensions/tlon/src/urbit/upload.test.ts b/extensions/tlon/src/urbit/upload.test.ts index bb8f505e7c1..653b3ac6db9 100644 --- a/extensions/tlon/src/urbit/upload.test.ts +++ b/extensions/tlon/src/urbit/upload.test.ts @@ -9,15 +9,15 @@ vi.mock("openclaw/plugin-sdk/infra-runtime", async (importOriginal) => { }; }); -// Mock @tloncorp/api -vi.mock("@tloncorp/api", () => ({ +// Mock the local Tlon upload seam. +vi.mock("../tlon-api.js", () => ({ uploadFile: vi.fn(), })); describe("uploadImageFromUrl", () => { async function loadUploadMocks() { const { fetchWithSsrFGuard } = await import("openclaw/plugin-sdk/infra-runtime"); - const { uploadFile } = await import("@tloncorp/api"); + const { uploadFile } = await import("../tlon-api.js"); const { uploadImageFromUrl } = await import("./upload.js"); return { mockFetch: vi.mocked(fetchWithSsrFGuard), diff --git a/extensions/tlon/src/urbit/upload.ts b/extensions/tlon/src/urbit/upload.ts index f0afe35c29e..121dcb88d8e 100644 --- a/extensions/tlon/src/urbit/upload.ts +++ b/extensions/tlon/src/urbit/upload.ts @@ -1,8 +1,8 @@ /** * Upload an image from a URL to Tlon storage. */ -import { uploadFile } from "@tloncorp/api"; import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/infra-runtime"; +import { uploadFile } from "../tlon-api.js"; import { getDefaultSsrFPolicy } from "./context.js"; /** diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ba0d4e1ad3a..70e7586716b 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -533,9 +533,12 @@ importers: extensions/tlon: dependencies: - '@tloncorp/api': - specifier: git+https://github.com/tloncorp/api-beta.git#7eede1c1a756977b09f96aa14a92e2b06318ae87 - version: git+https://github.com/tloncorp/api-beta.git#7eede1c1a756977b09f96aa14a92e2b06318ae87 + '@aws-sdk/client-s3': + specifier: 3.1000.0 + version: 3.1000.0 + '@aws-sdk/s3-request-presigner': + specifier: 3.1000.0 + version: 3.1000.0 '@tloncorp/tlon-skill': specifier: 0.2.2 version: 0.2.2 @@ -2896,34 +2899,18 @@ packages: resolution: {integrity: sha512-FE3bZdEl62ojmy8x4FHqxq2+BuOHlcxiH5vaZ6aqHJr3AIZzwF5jfx8dEiU/X0a8RboyNDjmXjlbr8AdEyLgiA==} engines: {node: '>=18.0.0'} - '@smithy/eventstream-serde-browser@4.2.11': - resolution: {integrity: sha512-3rEpo3G6f/nRS7fQDsZmxw/ius6rnlIpz4UX6FlALEzz8JoSxFmdBt0SZnthis+km7sQo6q5/3e+UJcuQivoXA==} - engines: {node: '>=18.0.0'} - '@smithy/eventstream-serde-browser@4.2.12': resolution: {integrity: sha512-XUSuMxlTxV5pp4VpqZf6Sa3vT/Q75FVkLSpSSE3KkWBvAQWeuWt1msTv8fJfgA4/jcJhrbrbMzN1AC/hvPmm5A==} engines: {node: '>=18.0.0'} - '@smithy/eventstream-serde-config-resolver@4.3.11': - resolution: {integrity: sha512-XeNIA8tcP/GDWnnKkO7qEm/bg0B/bP9lvIXZBXcGZwZ+VYM8h8k9wuDvUODtdQ2Wcp2RcBkPTCSMmaniVHrMlA==} - engines: {node: '>=18.0.0'} - '@smithy/eventstream-serde-config-resolver@4.3.12': resolution: {integrity: sha512-7epsAZ3QvfHkngz6RXQYseyZYHlmWXSTPOfPmXkiS+zA6TBNo1awUaMFL9vxyXlGdoELmCZyZe1nQE+imbmV+Q==} engines: {node: '>=18.0.0'} - '@smithy/eventstream-serde-node@4.2.11': - resolution: {integrity: sha512-fzbCh18rscBDTQSCrsp1fGcclLNF//nJyhjldsEl/5wCYmgpHblv5JSppQAyQI24lClsFT0wV06N1Porn0IsEw==} - engines: {node: '>=18.0.0'} - '@smithy/eventstream-serde-node@4.2.12': resolution: {integrity: sha512-D1pFuExo31854eAvg89KMn9Oab/wEeJR6Buy32B49A9Ogdtx5fwZPqBHUlDzaCDpycTFk2+fSQgX689Qsk7UGA==} engines: {node: '>=18.0.0'} - '@smithy/eventstream-serde-universal@4.2.11': - resolution: {integrity: sha512-MJ7HcI+jEkqoWT5vp+uoVaAjBrmxBtKhZTeynDRG/seEjJfqyg3SiqMMqyPnAMzmIfLaeJ/uiuSDP/l9AnMy/Q==} - engines: {node: '>=18.0.0'} - '@smithy/eventstream-serde-universal@4.2.12': resolution: {integrity: sha512-+yNuTiyBACxOJUTvbsNsSOfH9G9oKbaJE1lNL3YHpGcuucl6rPZMi3nrpehpVOVR2E07YqFFmtwpImtpzlouHQ==} engines: {node: '>=18.0.0'} @@ -3104,10 +3091,6 @@ packages: resolution: {integrity: sha512-1zopLDUEOwumjcHdJ1mwBHddubYF8GMQvstVCLC54Y46rqoHwlIU+8ZzUeaBcD+WCJHyDGSeZ2ml9YSe9aqcoQ==} engines: {node: '>=18.0.0'} - '@smithy/util-stream@4.5.19': - resolution: {integrity: sha512-v4sa+3xTweL1CLO2UP0p7tvIMH/Rq1X4KKOxd568mpe6LSLMQCnDHs4uv7m3ukpl3HvcN2JH6jiCS0SNRXKP/w==} - engines: {node: '>=18.0.0'} - '@smithy/util-stream@4.5.20': resolution: {integrity: sha512-4yXLm5n/B5SRBR2p8cZ90Sbv4zL4NKsgxdzCzp/83cXw2KxLEumt5p+GAVyRNZgQOSrzXn9ARpO0lUe8XSlSDw==} engines: {node: '>=18.0.0'} @@ -3237,10 +3220,6 @@ packages: resolution: {integrity: sha512-5Kc5CM2Ysn3vTTArBs2vESUt0AQiWZA86yc1TI3B+lxXmtEq133C1nxXNOgnzhrivdPZIh3zLj5gDnZjoLL5GA==} engines: {node: '>=12.17.0'} - '@tloncorp/api@git+https://github.com/tloncorp/api-beta.git#7eede1c1a756977b09f96aa14a92e2b06318ae87': - resolution: {commit: 7eede1c1a756977b09f96aa14a92e2b06318ae87, repo: https://github.com/tloncorp/api-beta.git, type: git} - version: 0.0.2 - '@tloncorp/tlon-skill-darwin-arm64@0.2.2': resolution: {integrity: sha512-R6RPBZKwOlhJm8BkPCbnhLJ9XKPCCp0a3nq1QUCT2bN4orp/IbKFaqGK2mjZsxzKT8aPPPnRqviqpGioDdItuA==} cpu: [arm64] @@ -3468,9 +3447,6 @@ packages: resolution: {integrity: sha512-N8/FHc/lmlMDCumMuTXyRHCxlov5KZY6unmJ9QR2GOw+OpROZMBsXYGwE+ZMtvN21ql9+Xb8KhGNBj08IrG3Wg==} engines: {node: '>=16', npm: '>=8'} - '@urbit/nockjs@1.6.0': - resolution: {integrity: sha512-f2xCIxoYQh+bp/p6qztvgxnhGsnUwcrSSvW2CUKX7BPPVkDNppQCzCVPWo38TbqgChE7wh6rC1pm6YNCOyFlQA==} - '@vitest/browser-playwright@4.1.0': resolution: {integrity: sha512-2RU7pZELY9/aVMLmABNy1HeZ4FX23FXGY1jRuHLHgWa2zaAE49aNW2GLzebW+BmbTZIKKyFF1QXvk7DEWViUCQ==} peerDependencies: @@ -3548,8 +3524,8 @@ packages: link-preview-js: optional: true - '@whiskeysockets/libsignal-node@git+https://github.com/whiskeysockets/libsignal-node.git#1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67': - resolution: {commit: 1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67, repo: https://github.com/whiskeysockets/libsignal-node.git, type: git} + '@whiskeysockets/libsignal-node@https://codeload.github.com/whiskeysockets/libsignal-node/tar.gz/1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67': + resolution: {tarball: https://codeload.github.com/whiskeysockets/libsignal-node/tar.gz/1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67} version: 2.0.1 abbrev@1.1.1: @@ -3633,10 +3609,6 @@ packages: resolution: {integrity: sha512-HqZ5rWlFjGiV0tDm3UxxgNRqsOTniqoKZu0pIAfh7TZQMGuZK+hH0drySty0si0QXj1ieop4+SkSfPZBPPkHig==} engines: {node: '>=14'} - any-ascii@0.3.3: - resolution: {integrity: sha512-8hm+zPrc1VnlxD5eRgMo9F9k2wEMZhbZVLKwA/sPKIt6ywuz7bI9uV/yb27uvc8fv8q6Wl2piJT51q1saKX0Jw==} - engines: {node: '>=12.20'} - any-base@1.1.0: resolution: {integrity: sha512-uMgjozySS8adZZYePpaWs8cxB9/kdzmpX6SgJZ+wbz1K5eYk5QMYDVJaZKhxyIHUdnnJkfR7SVgStgH7LkGUyg==} @@ -3793,10 +3765,6 @@ packages: bidi-js@1.0.3: resolution: {integrity: sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==} - big-integer@1.6.52: - resolution: {integrity: sha512-QxD8cf2eVqJOOz63z6JIN9BzvVs/dlySa5HGSBH5xtR8dPteIRQnBxxKqkNTiT6jbDTF6jAfrd4oMcND9RGbQg==} - engines: {node: '>=0.6'} - bignumber.js@9.3.1: resolution: {integrity: sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==} @@ -3831,9 +3799,6 @@ packages: resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==} engines: {node: '>=8'} - browser-or-node@3.0.0: - resolution: {integrity: sha512-iczIdVJzGEYhP5DqQxYM9Hh7Ztpqqi+CXZpSmX8ALFs9ecXkQIeqRyM6TfxEfMVpwhl3dSuDvxdzzo9sUOIVBQ==} - bs58@6.0.0: resolution: {integrity: sha512-PD0wEnEYg6ijszw/u8s+iI3H17cTymlrwkKhDhPZq+Sokl3AU4htyBFTjAeNAlCCmg0f53g6ih3jATyCKftTfw==} @@ -3846,9 +3811,6 @@ packages: buffer-from@1.1.2: resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==} - buffer@6.0.3: - resolution: {integrity: sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==} - bun-types@1.3.9: resolution: {integrity: sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg==} @@ -4067,9 +4029,6 @@ packages: resolution: {integrity: sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA==} engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0} - date-fns@3.6.0: - resolution: {integrity: sha512-fRHTG8g/Gif+kSh50gaGEdToemgfj74aRX3swtiouboip5JDLAyDE9F11nHMIcvOaXeOC6D7SpNhi7uFyB7Uww==} - debug@4.4.3: resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==} engines: {node: '>=6.0'} @@ -4298,9 +4257,6 @@ packages: resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==} engines: {node: '>=12.0.0'} - exponential-backoff@3.1.3: - resolution: {integrity: sha512-ZgEeZXj30q+I0EN+CbSSpIyPaJ5HVQD18Z1m+u1FXbAeT94mr1zw50q4q6jiiC447Nl/YTcIYSAftiGqetwXCA==} - express-rate-limit@8.3.1: resolution: {integrity: sha512-D1dKN+cmyPWuvB+G2SREQDzPY1agpBIcTa9sJxOPMCNeH3gwzhqJRDWCXW3gg0y//+LQ/8j52JbMROWyrKdMdw==} engines: {node: '>= 16'} @@ -4872,9 +4828,6 @@ packages: koffi@2.15.2: resolution: {integrity: sha512-r9tjJLVRSOhCRWdVyQlF3/Ugzeg13jlzS4czS82MAgLff4W+BcYOW7g8Y62t9O5JYjYOLAjAovAZDNlDfZNu+g==} - libphonenumber-js@1.12.38: - resolution: {integrity: sha512-vwzxmasAy9hZigxtqTbFEwp8ZdZ975TiqVDwj5bKx5sR+zi5ucUQy9mbVTkKM9GzqdLdxux/hTw2nmN5J7POMA==} - lie@3.3.0: resolution: {integrity: sha512-UaiMJzeWRlEujzAuw5LokY1L5ecNQYZKfmyZ9L7wDHb/p5etKaxXhohBcrw0EYby+G/NA52vRSN4N39dxHAIwQ==} @@ -5017,9 +4970,6 @@ packages: lodash.pickby@4.6.0: resolution: {integrity: sha512-AZV+GsS/6ckvPOVQPXSiFFacKvKB4kOQu6ynt9wz0F3LO4R9Ij4K1ddYsIytDpSgLz88JHd9P+oaLeej5/Sl7Q==} - lodash@4.17.23: - resolution: {integrity: sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==} - log-symbols@7.0.1: resolution: {integrity: sha512-ja1E3yCr9i/0hmBVaM0bfwDjnGy8I/s6PP4DFp+yP+a+mrHO4Rm7DtmnqROTUkHIkqffC84YY7AeqX6oFk0WFg==} engines: {node: '>=18'} @@ -6025,9 +5975,6 @@ packages: sonic-boom@4.2.1: resolution: {integrity: sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q==} - sorted-btree@1.8.1: - resolution: {integrity: sha512-395+XIP+wqNn3USkFSrNz7G3Ss/MXlZEqesxvzCRFwL14h6e8LukDHdLBePn5pwbm5OQ9vGu8mDyz2lLDIqamQ==} - source-map-js@1.2.1: resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==} engines: {node: '>=0.10.0'} @@ -6454,10 +6401,6 @@ packages: resolution: {integrity: sha512-hVDIBwsRruT73PbK7uP5ebUt+ezEtCmzZz3F59BSr2F6OVFnJ/6h8liuvdLrQ88Xmnk6/+xGGuq+pG9WwTuy3A==} engines: {node: ^20.17.0 || >=22.9.0} - validator@13.15.26: - resolution: {integrity: sha512-spH26xU080ydGggxRyR1Yhcbgx+j3y5jbNXk/8L+iRvdIEQ4uTRH2Sgf2dokud6Q4oAtsbNvJ1Ft+9xmm6IZcA==} - engines: {node: '>= 0.10'} - vary@1.1.2: resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==} engines: {node: '>= 0.8'} @@ -6805,33 +6748,33 @@ snapshots: '@aws-sdk/util-user-agent-browser': 3.972.8 '@aws-sdk/util-user-agent-node': 3.973.7 '@smithy/config-resolver': 4.4.11 - '@smithy/core': 3.23.11 - '@smithy/eventstream-serde-browser': 4.2.11 - '@smithy/eventstream-serde-config-resolver': 4.3.11 - '@smithy/eventstream-serde-node': 4.2.11 + '@smithy/core': 3.23.12 + '@smithy/eventstream-serde-browser': 4.2.12 + '@smithy/eventstream-serde-config-resolver': 4.3.12 + '@smithy/eventstream-serde-node': 4.2.12 '@smithy/fetch-http-handler': 5.3.15 '@smithy/hash-node': 4.2.12 '@smithy/invalid-dependency': 4.2.12 '@smithy/middleware-content-length': 4.2.12 - '@smithy/middleware-endpoint': 4.4.25 - '@smithy/middleware-retry': 4.4.42 - '@smithy/middleware-serde': 4.2.14 + '@smithy/middleware-endpoint': 4.4.26 + '@smithy/middleware-retry': 4.4.43 + '@smithy/middleware-serde': 4.2.15 '@smithy/middleware-stack': 4.2.12 '@smithy/node-config-provider': 4.3.12 - '@smithy/node-http-handler': 4.4.16 + '@smithy/node-http-handler': 4.5.0 '@smithy/protocol-http': 5.3.12 - '@smithy/smithy-client': 4.12.5 + '@smithy/smithy-client': 4.12.6 '@smithy/types': 4.13.1 '@smithy/url-parser': 4.2.12 '@smithy/util-base64': 4.3.2 '@smithy/util-body-length-browser': 4.2.2 '@smithy/util-body-length-node': 4.2.3 - '@smithy/util-defaults-mode-browser': 4.3.41 - '@smithy/util-defaults-mode-node': 4.2.44 + '@smithy/util-defaults-mode-browser': 4.3.42 + '@smithy/util-defaults-mode-node': 4.2.45 '@smithy/util-endpoints': 3.3.3 '@smithy/util-middleware': 4.2.12 '@smithy/util-retry': 4.2.12 - '@smithy/util-stream': 4.5.19 + '@smithy/util-stream': 4.5.20 '@smithy/util-utf8': 4.2.2 tslib: 2.8.1 transitivePeerDependencies: @@ -9620,7 +9563,7 @@ snapshots: '@smithy/util-base64': 4.3.2 '@smithy/util-body-length-browser': 4.2.2 '@smithy/util-middleware': 4.2.12 - '@smithy/util-stream': 4.5.19 + '@smithy/util-stream': 4.5.20 '@smithy/util-utf8': 4.2.2 '@smithy/uuid': 1.1.2 tslib: 2.8.1 @@ -9660,46 +9603,23 @@ snapshots: '@smithy/util-hex-encoding': 4.2.2 tslib: 2.8.1 - '@smithy/eventstream-serde-browser@4.2.11': - dependencies: - '@smithy/eventstream-serde-universal': 4.2.11 - '@smithy/types': 4.13.1 - tslib: 2.8.1 - '@smithy/eventstream-serde-browser@4.2.12': dependencies: '@smithy/eventstream-serde-universal': 4.2.12 '@smithy/types': 4.13.1 tslib: 2.8.1 - '@smithy/eventstream-serde-config-resolver@4.3.11': - dependencies: - '@smithy/types': 4.13.1 - tslib: 2.8.1 - '@smithy/eventstream-serde-config-resolver@4.3.12': dependencies: '@smithy/types': 4.13.1 tslib: 2.8.1 - '@smithy/eventstream-serde-node@4.2.11': - dependencies: - '@smithy/eventstream-serde-universal': 4.2.11 - '@smithy/types': 4.13.1 - tslib: 2.8.1 - '@smithy/eventstream-serde-node@4.2.12': dependencies: '@smithy/eventstream-serde-universal': 4.2.12 '@smithy/types': 4.13.1 tslib: 2.8.1 - '@smithy/eventstream-serde-universal@4.2.11': - dependencies: - '@smithy/eventstream-codec': 4.2.11 - '@smithy/types': 4.13.1 - tslib: 2.8.1 - '@smithy/eventstream-serde-universal@4.2.12': dependencies: '@smithy/eventstream-codec': 4.2.12 @@ -9761,8 +9681,8 @@ snapshots: '@smithy/middleware-endpoint@4.4.25': dependencies: - '@smithy/core': 3.23.11 - '@smithy/middleware-serde': 4.2.14 + '@smithy/core': 3.23.12 + '@smithy/middleware-serde': 4.2.15 '@smithy/node-config-provider': 4.3.12 '@smithy/shared-ini-file-loader': 4.4.7 '@smithy/types': 4.13.1 @@ -9786,7 +9706,7 @@ snapshots: '@smithy/node-config-provider': 4.3.12 '@smithy/protocol-http': 5.3.12 '@smithy/service-error-classification': 4.2.12 - '@smithy/smithy-client': 4.12.5 + '@smithy/smithy-client': 4.12.6 '@smithy/types': 4.13.1 '@smithy/util-middleware': 4.2.12 '@smithy/util-retry': 4.2.12 @@ -9807,7 +9727,7 @@ snapshots: '@smithy/middleware-serde@4.2.14': dependencies: - '@smithy/core': 3.23.11 + '@smithy/core': 3.23.12 '@smithy/protocol-http': 5.3.12 '@smithy/types': 4.13.1 tslib: 2.8.1 @@ -9890,12 +9810,12 @@ snapshots: '@smithy/smithy-client@4.12.5': dependencies: - '@smithy/core': 3.23.11 - '@smithy/middleware-endpoint': 4.4.25 + '@smithy/core': 3.23.12 + '@smithy/middleware-endpoint': 4.4.26 '@smithy/middleware-stack': 4.2.12 '@smithy/protocol-http': 5.3.12 '@smithy/types': 4.13.1 - '@smithy/util-stream': 4.5.19 + '@smithy/util-stream': 4.5.20 tslib: 2.8.1 '@smithy/smithy-client@4.12.6': @@ -9949,7 +9869,7 @@ snapshots: '@smithy/util-defaults-mode-browser@4.3.41': dependencies: '@smithy/property-provider': 4.2.12 - '@smithy/smithy-client': 4.12.5 + '@smithy/smithy-client': 4.12.6 '@smithy/types': 4.13.1 tslib: 2.8.1 @@ -9966,7 +9886,7 @@ snapshots: '@smithy/credential-provider-imds': 4.2.12 '@smithy/node-config-provider': 4.3.12 '@smithy/property-provider': 4.2.12 - '@smithy/smithy-client': 4.12.5 + '@smithy/smithy-client': 4.12.6 '@smithy/types': 4.13.1 tslib: 2.8.1 @@ -10001,17 +9921,6 @@ snapshots: '@smithy/types': 4.13.1 tslib: 2.8.1 - '@smithy/util-stream@4.5.19': - dependencies: - '@smithy/fetch-http-handler': 5.3.15 - '@smithy/node-http-handler': 4.5.0 - '@smithy/types': 4.13.1 - '@smithy/util-base64': 4.3.2 - '@smithy/util-buffer-from': 4.2.2 - '@smithy/util-hex-encoding': 4.2.2 - '@smithy/util-utf8': 4.2.2 - tslib: 2.8.1 - '@smithy/util-stream@4.5.20': dependencies: '@smithy/fetch-http-handler': 5.3.15 @@ -10124,26 +10033,6 @@ snapshots: '@tinyhttp/content-disposition@2.2.4': {} - '@tloncorp/api@git+https://github.com/tloncorp/api-beta.git#7eede1c1a756977b09f96aa14a92e2b06318ae87': - dependencies: - '@aws-sdk/client-s3': 3.1000.0 - '@aws-sdk/s3-request-presigner': 3.1000.0 - '@urbit/aura': 3.0.0 - '@urbit/nockjs': 1.6.0 - any-ascii: 0.3.3 - big-integer: 1.6.52 - browser-or-node: 3.0.0 - buffer: 6.0.3 - date-fns: 3.6.0 - emoji-regex: 10.6.0 - exponential-backoff: 3.1.3 - libphonenumber-js: 1.12.38 - lodash: 4.17.23 - sorted-btree: 1.8.1 - validator: 13.15.26 - transitivePeerDependencies: - - aws-crt - '@tloncorp/tlon-skill-darwin-arm64@0.2.2': optional: true @@ -10398,8 +10287,6 @@ snapshots: '@urbit/aura@3.0.0': {} - '@urbit/nockjs@1.6.0': {} - '@vitest/browser-playwright@4.1.0(playwright@1.58.2)(vite@8.0.0(@types/node@25.5.0)(esbuild@0.27.3)(jiti@2.6.1)(tsx@4.21.0)(yaml@2.8.2))(vitest@4.1.0)': dependencies: '@vitest/browser': 4.1.0(vite@8.0.0(@types/node@25.5.0)(esbuild@0.27.3)(jiti@2.6.1)(tsx@4.21.0)(yaml@2.8.2))(vitest@4.1.0) @@ -10515,7 +10402,7 @@ snapshots: '@cacheable/node-cache': 1.7.6 '@hapi/boom': 9.1.4 async-mutex: 0.5.0 - libsignal: '@whiskeysockets/libsignal-node@git+https://github.com/whiskeysockets/libsignal-node.git#1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67' + libsignal: '@whiskeysockets/libsignal-node@https://codeload.github.com/whiskeysockets/libsignal-node/tar.gz/1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67' lru-cache: 11.2.7 music-metadata: 11.12.3 p-queue: 9.1.0 @@ -10531,7 +10418,7 @@ snapshots: - supports-color - utf-8-validate - '@whiskeysockets/libsignal-node@git+https://github.com/whiskeysockets/libsignal-node.git#1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67': + '@whiskeysockets/libsignal-node@https://codeload.github.com/whiskeysockets/libsignal-node/tar.gz/1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67': dependencies: curve25519-js: 0.0.4 protobufjs: 6.8.8 @@ -10605,8 +10492,6 @@ snapshots: ansis@4.2.0: {} - any-ascii@0.3.3: {} - any-base@1.1.0: optional: true @@ -10765,8 +10650,6 @@ snapshots: dependencies: require-from-string: 2.0.2 - big-integer@1.6.52: {} - bignumber.js@9.3.1: {} birpc@4.0.0: {} @@ -10807,8 +10690,6 @@ snapshots: dependencies: fill-range: 7.1.1 - browser-or-node@3.0.0: {} - bs58@6.0.0: dependencies: base-x: 5.0.1 @@ -10819,11 +10700,6 @@ snapshots: buffer-from@1.1.2: {} - buffer@6.0.3: - dependencies: - base64-js: 1.5.1 - ieee754: 1.2.1 - bun-types@1.3.9: dependencies: '@types/node': 25.5.0 @@ -11040,8 +10916,6 @@ snapshots: transitivePeerDependencies: - '@noble/hashes' - date-fns@3.6.0: {} - debug@4.4.3: dependencies: ms: 2.1.3 @@ -11250,8 +11124,6 @@ snapshots: expect-type@1.3.0: {} - exponential-backoff@3.1.3: {} - express-rate-limit@8.3.1(express@5.2.1): dependencies: express: 5.2.1 @@ -12012,8 +11884,6 @@ snapshots: koffi@2.15.2: optional: true - libphonenumber-js@1.12.38: {} - lie@3.3.0: dependencies: immediate: 3.0.6 @@ -12127,8 +11997,6 @@ snapshots: lodash.pickby@4.6.0: {} - lodash@4.17.23: {} - log-symbols@7.0.1: dependencies: is-unicode-supported: 2.1.0 @@ -13406,8 +13274,6 @@ snapshots: dependencies: atomic-sleep: 1.0.0 - sorted-btree@1.8.1: {} - source-map-js@1.2.1: {} source-map-support@0.5.21: @@ -13798,8 +13664,6 @@ snapshots: validate-npm-package-name@7.0.2: {} - validator@13.15.26: {} - vary@1.1.2: {} vfile-message@4.0.3: From a245916dcb01e755c5b801c0de6af88663d0e961 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 15:05:56 -0700 Subject: [PATCH 38/69] fix(ci): repair test-parallel heap snapshot parsing --- scripts/test-parallel.mjs | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/scripts/test-parallel.mjs b/scripts/test-parallel.mjs index ed769a0c778..da1d5b4c903 100644 --- a/scripts/test-parallel.mjs +++ b/scripts/test-parallel.mjs @@ -739,9 +739,7 @@ const heapSnapshotIntervalMs = Math.max( ); const heapSnapshotMinIntervalMs = 5000; const heapSnapshotEnabled = - process.platform !== "win32" && - heapSnapshotIntervalMs >= heapSnapshotMinIntervalMs; -const heapSnapshotEnabled = process.platform !== "win32" && heapSnapshotIntervalMs > 0; + process.platform !== "win32" && heapSnapshotIntervalMs >= heapSnapshotMinIntervalMs; const heapSnapshotSignal = process.env.OPENCLAW_TEST_HEAPSNAPSHOT_SIGNAL?.trim() || "SIGUSR2"; const heapSnapshotBaseDir = heapSnapshotEnabled ? path.resolve( @@ -794,7 +792,9 @@ const runOnce = (entry, extraArgs = []) => try { fs.mkdirSync(heapSnapshotDir, { recursive: true }); } catch (err) { - console.error(`[test-parallel] failed to create heap snapshot dir ${heapSnapshotDir}: ${String(err)}`); + console.error( + `[test-parallel] failed to create heap snapshot dir ${heapSnapshotDir}: ${String(err)}`, + ); resolve(1); return; } @@ -809,7 +809,6 @@ const runOnce = (entry, extraArgs = []) => `--heapsnapshot-signal=${heapSnapshotSignal}`, ); } - } let output = ""; let fatalSeen = false; let childError = null; From d80b83e8e34468b2f8095935ec325e03cacdbd98 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 15:06:35 -0700 Subject: [PATCH 39/69] fix(plugins): scope sdk aliases to loaded module paths --- src/plugins/loader.test.ts | 41 ++++++++++++++++++++++++++++++++++++++ src/plugins/loader.ts | 33 ++++++++++++++++++++---------- 2 files changed, 64 insertions(+), 10 deletions(-) diff --git a/src/plugins/loader.test.ts b/src/plugins/loader.test.ts index fc0f6c2f208..c99ccbf41f0 100644 --- a/src/plugins/loader.test.ts +++ b/src/plugins/loader.test.ts @@ -3462,6 +3462,47 @@ module.exports = { expect(subpaths).toEqual(["channel-runtime", "core"]); }); + it("builds plugin-sdk aliases from the module being loaded, not the loader location", () => { + const fixture = createPluginSdkAliasFixture({ + srcFile: "channel-runtime.ts", + distFile: "channel-runtime.js", + packageExports: { + "./plugin-sdk/channel-runtime": { default: "./dist/plugin-sdk/channel-runtime.js" }, + }, + }); + const sourceRootAlias = path.join(fixture.root, "src", "plugin-sdk", "root-alias.cjs"); + const distRootAlias = path.join(fixture.root, "dist", "plugin-sdk", "root-alias.cjs"); + fs.writeFileSync(sourceRootAlias, "module.exports = {};\n", "utf-8"); + fs.writeFileSync(distRootAlias, "module.exports = {};\n", "utf-8"); + const sourcePluginEntry = path.join(fixture.root, "extensions", "demo", "src", "index.ts"); + fs.mkdirSync(path.dirname(sourcePluginEntry), { recursive: true }); + fs.writeFileSync(sourcePluginEntry, 'export const plugin = "demo";\n', "utf-8"); + + const sourceAliases = withEnv({ NODE_ENV: undefined }, () => + __testing.buildPluginLoaderAliasMap(sourcePluginEntry), + ); + expect(fs.realpathSync(sourceAliases["openclaw/plugin-sdk"] ?? "")).toBe( + fs.realpathSync(sourceRootAlias), + ); + expect(fs.realpathSync(sourceAliases["openclaw/plugin-sdk/channel-runtime"] ?? "")).toBe( + fs.realpathSync(path.join(fixture.root, "src", "plugin-sdk", "channel-runtime.ts")), + ); + + const distPluginEntry = path.join(fixture.root, "dist", "extensions", "demo", "index.js"); + fs.mkdirSync(path.dirname(distPluginEntry), { recursive: true }); + fs.writeFileSync(distPluginEntry, 'export const plugin = "demo";\n', "utf-8"); + + const distAliases = withEnv({ NODE_ENV: undefined }, () => + __testing.buildPluginLoaderAliasMap(distPluginEntry), + ); + expect(fs.realpathSync(distAliases["openclaw/plugin-sdk"] ?? "")).toBe( + fs.realpathSync(distRootAlias), + ); + expect(fs.realpathSync(distAliases["openclaw/plugin-sdk/channel-runtime"] ?? "")).toBe( + fs.realpathSync(path.join(fixture.root, "dist", "plugin-sdk", "channel-runtime.js")), + ); + }); + it("does not resolve plugin-sdk alias files from cwd fallback when package root is not an OpenClaw root", () => { const fixture = createPluginSdkAliasFixture({ srcFile: "channel-runtime.ts", diff --git a/src/plugins/loader.ts b/src/plugins/loader.ts index b1aff47073c..68ba5b8403a 100644 --- a/src/plugins/loader.ts +++ b/src/plugins/loader.ts @@ -104,8 +104,20 @@ function resolveLoaderModulePath(params: LoaderModuleResolveParams = {}): string return params.modulePath ?? fileURLToPath(params.moduleUrl ?? import.meta.url); } -const resolvePluginSdkAlias = (): string | null => - resolvePluginSdkAliasFile({ srcFile: "root-alias.cjs", distFile: "root-alias.cjs" }); +const resolvePluginSdkAlias = (params: LoaderModuleResolveParams = {}): string | null => + resolvePluginSdkAliasFile({ + srcFile: "root-alias.cjs", + distFile: "root-alias.cjs", + ...params, + }); + +function buildPluginLoaderAliasMap(modulePath: string): Record { + const pluginSdkAlias = resolvePluginSdkAlias({ modulePath }); + return { + ...(pluginSdkAlias ? { "openclaw/plugin-sdk": pluginSdkAlias } : {}), + ...resolvePluginSdkScopedAliasMap({ modulePath }), + }; +} function resolvePluginRuntimeModulePath(params: LoaderModuleResolveParams = {}): string | null { try { @@ -138,6 +150,7 @@ function resolvePluginRuntimeModulePath(params: LoaderModuleResolveParams = {}): export const __testing = { buildPluginLoaderJitiOptions, + buildPluginLoaderAliasMap, listPluginSdkAliasCandidates, listPluginSdkExportedSubpaths, resolvePluginSdkScopedAliasMap, @@ -704,18 +717,18 @@ export function loadOpenClawPlugins(options: PluginLoadOptions = {}): PluginRegi } // Lazy: avoid creating the Jiti loader when all plugins are disabled (common in unit tests). - const jitiLoaders = new Map>(); + const jitiLoaders = new Map>(); const getJiti = (modulePath: string) => { const tryNative = shouldPreferNativeJiti(modulePath); - const cached = jitiLoaders.get(tryNative); + const aliasMap = buildPluginLoaderAliasMap(modulePath); + const cacheKey = JSON.stringify({ + tryNative, + aliasMap: Object.entries(aliasMap).toSorted(([left], [right]) => left.localeCompare(right)), + }); + const cached = jitiLoaders.get(cacheKey); if (cached) { return cached; } - const pluginSdkAlias = resolvePluginSdkAlias(); - const aliasMap = { - ...(pluginSdkAlias ? { "openclaw/plugin-sdk": pluginSdkAlias } : {}), - ...resolvePluginSdkScopedAliasMap(), - }; const loader = createJiti(import.meta.url, { ...buildPluginLoaderJitiOptions(aliasMap), // Source .ts runtime shims import sibling ".js" specifiers that only exist @@ -724,7 +737,7 @@ export function loadOpenClawPlugins(options: PluginLoadOptions = {}): PluginRegi // loading for the canonical built module graph. tryNative, }); - jitiLoaders.set(tryNative, loader); + jitiLoaders.set(cacheKey, loader); return loader; }; From 14eb49c18a3487bb98abe8fd22e78ca449a84f92 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 15:06:50 -0700 Subject: [PATCH 40/69] test(feishu): fix lifecycle mock typing --- .../src/monitor.broadcast.reply-once.lifecycle.test.ts | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts b/extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts index 295db8659ee..3c1a51a084a 100644 --- a/extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts +++ b/extensions/feishu/src/monitor.broadcast.reply-once.lifecycle.test.ts @@ -10,7 +10,14 @@ const monitorWebSocketMock = vi.hoisted(() => vi.fn(async () => {})); const monitorWebhookMock = vi.hoisted(() => vi.fn(async () => {})); const createFeishuThreadBindingManagerMock = vi.hoisted(() => vi.fn(() => ({ stop: vi.fn() }))); const createFeishuReplyDispatcherMock = vi.hoisted(() => vi.fn()); -const resolveBoundConversationMock = vi.hoisted(() => vi.fn(() => null)); +const resolveBoundConversationMock = vi.hoisted(() => + vi.fn< + () => { + bindingId: string; + targetSessionKey: string; + } | null + >(() => null), +); const touchBindingMock = vi.hoisted(() => vi.fn()); const resolveAgentRouteMock = vi.hoisted(() => vi.fn()); const dispatchReplyFromConfigMock = vi.hoisted(() => vi.fn()); From c3b05fc4d92d2cd33cece86cd9e7db70c82a5c16 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 15:26:09 -0700 Subject: [PATCH 41/69] docs: add missing title, remove stale description fields from frontmatter --- docs/channels/irc.md | 1 - docs/ci.md | 1 - docs/gateway/configuration-reference.md | 1 - docs/gateway/trusted-proxy-auth.md | 1 + docs/install/fly.md | 1 - docs/start/showcase.md | 1 - docs/tools/diffs.md | 1 - docs/tools/lobster.md | 1 - docs/tools/loop-detection.md | 1 - 9 files changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/channels/irc.md b/docs/channels/irc.md index 33c2e47fe29..8475c6a4454 100644 --- a/docs/channels/irc.md +++ b/docs/channels/irc.md @@ -1,6 +1,5 @@ --- title: IRC -description: Connect OpenClaw to IRC channels and direct messages. summary: "IRC plugin setup, access controls, and troubleshooting" read_when: - You want to connect OpenClaw to IRC channels or DMs diff --git a/docs/ci.md b/docs/ci.md index e8710b87cb1..36e5fba0d8c 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -1,6 +1,5 @@ --- title: CI Pipeline -description: How the OpenClaw CI pipeline works summary: "CI job graph, scope gates, and local command equivalents" read_when: - You need to understand why a CI job did or did not run diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 9e3b14c011c..57756608a35 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1,6 +1,5 @@ --- title: "Configuration Reference" -description: "Complete field-by-field reference for ~/.openclaw/openclaw.json" summary: "Complete reference for every OpenClaw config key, defaults, and channel settings" read_when: - You need exact field-level config semantics or defaults diff --git a/docs/gateway/trusted-proxy-auth.md b/docs/gateway/trusted-proxy-auth.md index 7144452b2e6..cff00bb6720 100644 --- a/docs/gateway/trusted-proxy-auth.md +++ b/docs/gateway/trusted-proxy-auth.md @@ -1,4 +1,5 @@ --- +title: "Trusted Proxy Auth" summary: "Delegate gateway authentication to a trusted reverse proxy (Pomerium, Caddy, nginx + OAuth)" read_when: - Running OpenClaw behind an identity-aware proxy diff --git a/docs/install/fly.md b/docs/install/fly.md index aacfa484670..0a5c9b22338 100644 --- a/docs/install/fly.md +++ b/docs/install/fly.md @@ -1,6 +1,5 @@ --- title: Fly.io -description: Deploy OpenClaw on Fly.io summary: "Step-by-step Fly.io deployment for OpenClaw with persistent storage and HTTPS" read_when: - Deploying OpenClaw on Fly.io diff --git a/docs/start/showcase.md b/docs/start/showcase.md index 6ebcbdb2bcb..9b382a0e2f7 100644 --- a/docs/start/showcase.md +++ b/docs/start/showcase.md @@ -1,6 +1,5 @@ --- title: "Showcase" -description: "Real-world OpenClaw projects from the community" summary: "Community-built projects and integrations powered by OpenClaw" read_when: - Looking for real OpenClaw usage examples diff --git a/docs/tools/diffs.md b/docs/tools/diffs.md index 3e0289dd05d..f502fdbccef 100644 --- a/docs/tools/diffs.md +++ b/docs/tools/diffs.md @@ -1,7 +1,6 @@ --- title: "Diffs" summary: "Read-only diff viewer and file renderer for agents (optional plugin tool)" -description: "Use the optional Diffs plugin to render before and after text or unified patches as a gateway-hosted diff view, a file (PNG or PDF), or both." read_when: - You want agents to show code or markdown edits as diffs - You want a canvas-ready viewer URL or a rendered diff file diff --git a/docs/tools/lobster.md b/docs/tools/lobster.md index 5c8a47e4d62..6e502c09c19 100644 --- a/docs/tools/lobster.md +++ b/docs/tools/lobster.md @@ -1,7 +1,6 @@ --- title: Lobster summary: "Typed workflow runtime for OpenClaw with resumable approval gates." -description: Typed workflow runtime for OpenClaw — composable pipelines with approval gates. read_when: - You want deterministic multi-step workflows with explicit approvals - You need to resume a workflow without re-running earlier steps diff --git a/docs/tools/loop-detection.md b/docs/tools/loop-detection.md index 56d843f1276..d0071cf5064 100644 --- a/docs/tools/loop-detection.md +++ b/docs/tools/loop-detection.md @@ -1,6 +1,5 @@ --- title: "Tool-loop detection" -description: "Configure optional guardrails for preventing repetitive or stalled tool-call loops" summary: "How to enable and tune guardrails that detect repetitive tool-call loops" read_when: - A user reports agents getting stuck repeating tool calls From bbfeb0b6f988536318e64fa7ae73c413b057a69d Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 15:38:16 -0700 Subject: [PATCH 42/69] fix(ci): cache node in install smoke image --- scripts/docker/install-sh-nonroot/Dockerfile | 9 +++++++++ scripts/docker/install-sh-nonroot/run.sh | 13 +++++++++++++ 2 files changed, 22 insertions(+) diff --git a/scripts/docker/install-sh-nonroot/Dockerfile b/scripts/docker/install-sh-nonroot/Dockerfile index 8e29715dbfb..f95859beedf 100644 --- a/scripts/docker/install-sh-nonroot/Dockerfile +++ b/scripts/docker/install-sh-nonroot/Dockerfile @@ -21,6 +21,15 @@ RUN --mount=type=cache,id=openclaw-install-sh-nonroot-apt-cache,target=/var/cach python3 \ sudo +# Preinstall the supported Node runtime in a cacheable build layer so the +# non-root smoke covers user-local npm prefixing and missing git without paying +# the full NodeSource bootstrap cost on every container run. +RUN --mount=type=cache,id=openclaw-install-sh-nonroot-apt-cache,target=/var/cache/apt,sharing=locked \ + --mount=type=cache,id=openclaw-install-sh-nonroot-apt-lists,target=/var/lib/apt,sharing=locked \ + set -eux; \ + curl -fsSL https://deb.nodesource.com/setup_24.x | bash -; \ + DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends nodejs + RUN useradd -m -s /bin/bash app \ && echo "app ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/app diff --git a/scripts/docker/install-sh-nonroot/run.sh b/scripts/docker/install-sh-nonroot/run.sh index 787bfc8e809..6c026f34f64 100644 --- a/scripts/docker/install-sh-nonroot/run.sh +++ b/scripts/docker/install-sh-nonroot/run.sh @@ -15,6 +15,19 @@ if command -v git >/dev/null; then exit 1 fi +echo "==> Pre-flight: ensure supported Node is already present" +node -e ' + const version = process.versions.node.split(".").map(Number); + const ok = + version.length >= 2 && + (version[0] > 22 || (version[0] === 22 && version[1] >= 16)); + if (!ok) { + process.stderr.write(`unsupported node ${process.versions.node}\n`); + process.exit(1); + } +' +command -v npm >/dev/null + echo "==> Run installer (non-root user)" curl -fsSL "$INSTALL_URL" | bash From 801e4bede6050e81d332b486ed32381ee7801c8c Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Thu, 19 Mar 2026 17:25:37 -0500 Subject: [PATCH 43/69] Git: run pnpm check in pre-commit hook --- AGENTS.md | 7 +++---- git-hooks/pre-commit | 3 +++ 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 538670892f4..e6c5b1a5e92 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,9 +70,8 @@ - Format check: `pnpm format` (oxfmt --check) - Format fix: `pnpm format:fix` (oxfmt --write) - Tests: `pnpm test` (vitest); coverage: `pnpm test:coverage` -- Default landing bar: before any commit, run `pnpm check` and prefer a passing result for the change being committed. -- For narrowly scoped changes, run narrowly scoped tests that directly validate the touched behavior; this is required proof for the change before commit and push decisions. If no meaningful scoped test exists, say so explicitly and use the next most direct validation available. -- Default landing bar: before any push to `main`, run `pnpm check` and `pnpm test` and prefer a green result. +- For narrowly scoped changes, prefer narrowly scoped tests that directly validate the touched behavior. If no meaningful scoped test exists, say so explicitly and use the next most direct validation available. +- Preferred landing bar for pushes to `main`: `pnpm check` and `pnpm test`, with a green result when feasible. - Scoped tests prove the change itself. `pnpm test` remains the default `main` landing bar; scoped tests do not replace full-suite gates by default. - Hard gate: if the change can affect build output, packaging, lazy-loading/module boundaries, or published surfaces, `pnpm build` MUST be run and MUST pass before pushing `main`. - Default rule: do not commit or push with failing format, lint, type, build, or required test checks when those failures are caused by the change or plausibly related to the touched surface. @@ -82,7 +81,7 @@ ## Coding Style & Naming Conventions - Language: TypeScript (ESM). Prefer strict typing; avoid `any`. -- Formatting/linting via Oxlint and Oxfmt; run `pnpm check` before commits. +- Formatting/linting via Oxlint and Oxfmt. - Never add `@ts-nocheck` and do not disable `no-explicit-any`; fix root causes and update Oxlint/Oxfmt config only when required. - Dynamic import guardrail: do not mix `await import("x")` and static `import ... from "x"` for the same module in production code paths. If you need lazy loading, create a dedicated `*.runtime.ts` boundary (that re-exports from `x`) and dynamically import that boundary from lazy callers only. - Dynamic import verification: after refactors that touch lazy-loading/module boundaries, run `pnpm build` and check for `[INEFFECTIVE_DYNAMIC_IMPORT]` warnings before submitting. diff --git a/git-hooks/pre-commit b/git-hooks/pre-commit index 469ccd28b88..34831d6cf3d 100755 --- a/git-hooks/pre-commit +++ b/git-hooks/pre-commit @@ -47,3 +47,6 @@ if [ "${#format_files[@]}" -gt 0 ]; then fi git add -- "${files[@]}" + +cd "$ROOT_DIR" +pnpm check From 20001a50c524cb89c1c3b1bcee21e64b087bcbc5 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 15:45:39 -0700 Subject: [PATCH 44/69] fix(build): suppress known-safe bottleneck eval warnings --- tsdown.config.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/tsdown.config.ts b/tsdown.config.ts index aafa874a041..746c6e883bc 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -25,6 +25,12 @@ const env = { NODE_ENV: "production", }; +const SUPPRESSED_EVAL_WARNING_PATHS = [ + "@protobufjs/inquire/index.js", + "bottleneck/lib/IORedisConnection.js", + "bottleneck/lib/RedisConnection.js", +] as const; + function buildInputOptions(options: InputOptionsArg): InputOptionsReturn { if (process.env.OPENCLAW_BUILD_VERBOSE === "1") { return undefined; @@ -45,7 +51,7 @@ function buildInputOptions(options: InputOptionsArg): InputOptionsReturn { return false; } const haystack = [log.message, log.id, log.importer].filter(Boolean).join("\n"); - return haystack.includes("@protobufjs/inquire/index.js"); + return SUPPRESSED_EVAL_WARNING_PATHS.some((path) => haystack.includes(path)); } return { From 192151610f3dc4e3d058c110950114c39552588a Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Thu, 19 Mar 2026 18:06:03 -0500 Subject: [PATCH 45/69] fix(status): skip plugin compatibility scan on empty json path --- src/commands/status.scan.fast-json.ts | 11 ++++- src/commands/status.scan.test.ts | 61 +++++++++++++++++++++++++++ src/commands/status.scan.ts | 13 +++++- 3 files changed, 83 insertions(+), 2 deletions(-) diff --git a/src/commands/status.scan.fast-json.ts b/src/commands/status.scan.fast-json.ts index 4a7d60528b2..953e9b9f77a 100644 --- a/src/commands/status.scan.fast-json.ts +++ b/src/commands/status.scan.fast-json.ts @@ -73,6 +73,13 @@ function shouldSkipMissingConfigFastPath(): boolean { ); } +function shouldCollectPluginCompatibility(cfg: OpenClawConfig): boolean { + if (hasPotentialConfiguredChannels(cfg)) { + return true; + } + return existsSync(resolveConfigPath(process.env)); +} + function resolveDefaultMemoryStorePath(agentId: string): string { return path.join(resolveStateDir(process.env, os.homedir), "memory", `${agentId}.sqlite`); } @@ -186,7 +193,9 @@ export async function scanStatusJsonFast( : null; const memoryPlugin = resolveMemoryPluginStatus(cfg); const memory = await resolveMemoryStatusSnapshot({ cfg, agentStatus, memoryPlugin }); - const pluginCompatibility = buildPluginCompatibilityNotices({ config: cfg }); + const pluginCompatibility = shouldCollectPluginCompatibility(cfg) + ? buildPluginCompatibilityNotices({ config: cfg }) + : []; return { cfg, diff --git a/src/commands/status.scan.test.ts b/src/commands/status.scan.test.ts index 269b6dc8097..1098b3d9bc3 100644 --- a/src/commands/status.scan.test.ts +++ b/src/commands/status.scan.test.ts @@ -1,6 +1,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest"; const mocks = vi.hoisted(() => ({ + resolveConfigPath: vi.fn(() => `/tmp/openclaw-status-scan-missing-${process.pid}.json`), hasPotentialConfiguredChannels: vi.fn(), readBestEffortConfig: vi.fn(), resolveCommandSecretRefsViaGateway: vi.fn(), @@ -34,6 +35,14 @@ vi.mock("../config/config.js", () => ({ readBestEffortConfig: mocks.readBestEffortConfig, })); +vi.mock("../config/paths.js", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + resolveConfigPath: mocks.resolveConfigPath, + }; +}); + vi.mock("../cli/command-secret-gateway.js", () => ({ resolveCommandSecretRefsViaGateway: mocks.resolveCommandSecretRefsViaGateway, })); @@ -214,6 +223,58 @@ describe("scanStatus", () => { expect(mocks.ensurePluginRegistryLoaded).not.toHaveBeenCalled(); }); + it("skips plugin compatibility loading for status --json when the config file is missing", async () => { + mocks.readBestEffortConfig.mockResolvedValue({ + session: {}, + plugins: { enabled: true }, + gateway: {}, + }); + mocks.resolveCommandSecretRefsViaGateway.mockResolvedValue({ + resolvedConfig: { + session: {}, + plugins: { enabled: true }, + gateway: {}, + }, + diagnostics: [], + }); + mocks.getUpdateCheckResult.mockResolvedValue({ + installKind: "git", + git: null, + registry: null, + }); + mocks.getAgentLocalStatuses.mockResolvedValue({ + defaultId: "main", + agents: [], + }); + mocks.getStatusSummary.mockResolvedValue({ + linkChannel: undefined, + sessions: { count: 0, paths: [], defaults: {}, recent: [] }, + }); + mocks.buildGatewayConnectionDetails.mockReturnValue({ + url: "ws://127.0.0.1:18789", + urlSource: "default", + }); + mocks.resolveGatewayProbeAuthResolution.mockReturnValue({ + auth: {}, + warning: undefined, + }); + mocks.probeGateway.mockResolvedValue({ + ok: false, + url: "ws://127.0.0.1:18789", + connectLatencyMs: null, + error: "timeout", + close: null, + health: null, + status: null, + presence: null, + configSnapshot: null, + }); + + await scanStatus({ json: true }, {} as never); + + expect(mocks.buildPluginCompatibilityNotices).not.toHaveBeenCalled(); + }); + it("skips memory backend inspection for default memory-core with no existing store", async () => { mocks.readBestEffortConfig.mockResolvedValue({ session: {}, diff --git a/src/commands/status.scan.ts b/src/commands/status.scan.ts index 736c1a8b215..7813f43ba32 100644 --- a/src/commands/status.scan.ts +++ b/src/commands/status.scan.ts @@ -1,3 +1,4 @@ +import { existsSync } from "node:fs"; import { resolveMemorySearchConfig } from "../agents/memory-search.js"; import { hasPotentialConfiguredChannels } from "../channels/config-presence.js"; import { resolveCommandSecretRefsViaGateway } from "../cli/command-secret-gateway.js"; @@ -5,6 +6,7 @@ import { getStatusCommandSecretTargetIds } from "../cli/command-secret-targets.j import { withProgress } from "../cli/progress.js"; import type { OpenClawConfig } from "../config/config.js"; import { readBestEffortConfig } from "../config/config.js"; +import { resolveConfigPath } from "../config/paths.js"; import { callGateway } from "../gateway/call.js"; import type { collectChannelStatusIssues as collectChannelStatusIssuesFn } from "../infra/channels-status-issues.js"; import { resolveOsSummary } from "../infra/os-summary.js"; @@ -66,6 +68,13 @@ function unwrapDeferredResult(result: DeferredResult): T { return result.value; } +function shouldCollectPluginCompatibility(cfg: OpenClawConfig): boolean { + if (hasPotentialConfiguredChannels(cfg)) { + return true; + } + return existsSync(resolveConfigPath(process.env)); +} + async function resolveChannelsStatus(params: { cfg: OpenClawConfig; gatewayReachable: boolean; @@ -197,7 +206,9 @@ async function scanStatusJsonFast(opts: { const memoryPlugin = resolveMemoryPluginStatus(cfg); const memoryPromise = resolveMemoryStatusSnapshot({ cfg, agentStatus, memoryPlugin }); const memory = await memoryPromise; - const pluginCompatibility = buildPluginCompatibilityNotices({ config: cfg }); + const pluginCompatibility = shouldCollectPluginCompatibility(cfg) + ? buildPluginCompatibilityNotices({ config: cfg }) + : []; return { cfg, From 009f494cd94590d4d309d0e1bf5148d4dd6fffb5 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 15:57:22 -0700 Subject: [PATCH 46/69] fix(plugin-sdk): stop library import warmup side effects --- src/agents/context.lookup.test.ts | 43 +++++++++++++++++++------------ src/agents/context.ts | 29 ++++++++++++++++----- src/plugin-sdk/root-alias.cjs | 16 ++++++++++++ src/plugin-sdk/root-alias.test.ts | 11 ++++++++ 4 files changed, 77 insertions(+), 22 deletions(-) diff --git a/src/agents/context.lookup.test.ts b/src/agents/context.lookup.test.ts index df0e67e6c68..31d702c5420 100644 --- a/src/agents/context.lookup.test.ts +++ b/src/agents/context.lookup.test.ts @@ -6,25 +6,27 @@ function mockContextDeps(params: { loadConfig: () => unknown; discoveredModels?: DiscoveredModel[]; }) { + const ensureOpenClawModelsJson = vi.fn(async () => {}); vi.doMock("../config/config.js", () => ({ loadConfig: params.loadConfig, })); vi.doMock("./models-config.js", () => ({ - ensureOpenClawModelsJson: vi.fn(async () => {}), + ensureOpenClawModelsJson, })); vi.doMock("./agent-paths.js", () => ({ resolveOpenClawAgentDir: () => "/tmp/openclaw-agent", })); - vi.doMock("./pi-model-discovery.js", () => ({ + vi.doMock("./pi-model-discovery-runtime.js", () => ({ discoverAuthStorage: vi.fn(() => ({})), discoverModels: vi.fn(() => ({ getAll: () => params.discoveredModels ?? [], })), })); + return { ensureOpenClawModelsJson }; } function mockContextModuleDeps(loadConfigImpl: () => unknown) { - mockContextDeps({ loadConfig: loadConfigImpl }); + return mockContextDeps({ loadConfig: loadConfigImpl }); } // Shared mock setup used by multiple tests. @@ -80,14 +82,18 @@ describe("lookupContextTokens", () => { expect(lookupContextTokens("openrouter/claude-sonnet")).toBe(321_000); }); - it("only warms eagerly for startup commands that need model metadata", async () => { + it("only warms eagerly for real openclaw startup commands that need model metadata", async () => { const argvSnapshot = process.argv; try { for (const scenario of [ { - argv: ["node", "openclaw", "--profile", "--", "config", "validate"], + argv: ["node", "openclaw", "chat"], expectedCalls: 1, }, + { + argv: ["node", "openclaw", "--profile", "--", "config", "validate"], + expectedCalls: 0, + }, { argv: ["node", "openclaw", "logs", "--limit", "5"], expectedCalls: 0, @@ -97,16 +103,18 @@ describe("lookupContextTokens", () => { expectedCalls: 0, }, { - argv: ["node", "openclaw", "gateway", "status", "--json"], + argv: ["node", "scripts/test-built-plugin-singleton.mjs"], expectedCalls: 0, }, ]) { vi.resetModules(); const loadConfigMock = vi.fn(() => ({ models: {} })); - mockContextModuleDeps(loadConfigMock); + const { ensureOpenClawModelsJson } = mockContextModuleDeps(loadConfigMock); process.argv = scenario.argv; await import("./context.js"); + await flushAsyncWarmup(); expect(loadConfigMock).toHaveBeenCalledTimes(scenario.expectedCalls); + expect(ensureOpenClawModelsJson).toHaveBeenCalledTimes(scenario.expectedCalls); } } finally { process.argv = argvSnapshot; @@ -132,8 +140,6 @@ describe("lookupContextTokens", () => { mockContextModuleDeps(loadConfigMock); - const argvSnapshot = process.argv; - process.argv = ["node", "openclaw", "config", "validate"]; try { const { lookupContextTokens } = await import("./context.js"); expect(lookupContextTokens("openrouter/claude-sonnet")).toBeUndefined(); @@ -144,7 +150,6 @@ describe("lookupContextTokens", () => { expect(lookupContextTokens("openrouter/claude-sonnet")).toBe(654_321); expect(loadConfigMock).toHaveBeenCalledTimes(2); } finally { - process.argv = argvSnapshot; vi.useRealTimers(); } }); @@ -156,7 +161,7 @@ describe("lookupContextTokens", () => { ]); const { lookupContextTokens } = await import("./context.js"); - // Trigger async cache population. + lookupContextTokens("gemini-3.1-pro-preview"); await flushAsyncWarmup(); // Conservative minimum: bare-id cache feeds runtime flush/compaction paths. expect(lookupContextTokens("gemini-3.1-pro-preview")).toBe(128_000); @@ -171,7 +176,8 @@ describe("lookupContextTokens", () => { { id: "google-gemini-cli/gemini-3.1-pro-preview", contextWindow: 1_048_576 }, ]); - const { resolveContextTokensForModel } = await import("./context.js"); + const { lookupContextTokens, resolveContextTokensForModel } = await import("./context.js"); + lookupContextTokens("google-gemini-cli/gemini-3.1-pro-preview"); await flushAsyncWarmup(); // With provider specified and no config override, bare lookup finds the @@ -224,7 +230,9 @@ describe("lookupContextTokens", () => { mockDiscoveryDeps([{ id: "google/gemini-2.5-pro", contextWindow: 999_000 }]); const cfg = createContextOverrideConfig("google", "gemini-2.5-pro", 2_000_000); - const resolveContextTokensForModel = await importResolveContextTokensForModel(); + const { lookupContextTokens, resolveContextTokensForModel } = await import("./context.js"); + lookupContextTokens("google/gemini-2.5-pro"); + await flushAsyncWarmup(); // Google with explicit cfg: config direct scan wins before any cache lookup. const googleResult = resolveContextTokensForModel({ @@ -286,7 +294,9 @@ describe("lookupContextTokens", () => { mockDiscoveryDeps([{ id: "google/gemini-2.5-pro", contextWindow: 999_000 }]); const cfg = createContextOverrideConfig("google", "gemini-2.5-pro", 2_000_000); - const resolveContextTokensForModel = await importResolveContextTokensForModel(); + const { lookupContextTokens, resolveContextTokensForModel } = await import("./context.js"); + lookupContextTokens("google/gemini-2.5-pro"); + await flushAsyncWarmup(); // model-only call (no explicit provider) must NOT apply config direct scan. // Falls through to bare cache lookup: "google/gemini-2.5-pro" → 999k ✓. @@ -317,8 +327,9 @@ describe("lookupContextTokens", () => { { id: "google-gemini-cli/gemini-3.1-pro-preview", contextWindow: 1_048_576 }, ]); - const { resolveContextTokensForModel } = await import("./context.js"); - await new Promise((r) => setTimeout(r, 0)); + const { lookupContextTokens, resolveContextTokensForModel } = await import("./context.js"); + lookupContextTokens("google-gemini-cli/gemini-3.1-pro-preview"); + await flushAsyncWarmup(); // Qualified "google-gemini-cli/gemini-3.1-pro-preview" → 1M wins over // bare "gemini-3.1-pro-preview" → 128k (cross-provider minimum). diff --git a/src/agents/context.ts b/src/agents/context.ts index cfeee26cd60..279433f0c76 100644 --- a/src/agents/context.ts +++ b/src/agents/context.ts @@ -1,6 +1,7 @@ // Lazy-load pi-coding-agent model metadata so we can infer context windows when // the agent reports a model id. This includes custom models.json entries. +import path from "node:path"; import { loadConfig } from "../config/config.js"; import type { OpenClawConfig } from "../config/config.js"; import { computeBackoff, type BackoffPolicy } from "../infra/backoff.js"; @@ -84,6 +85,19 @@ let configuredConfig: OpenClawConfig | undefined; let configLoadFailures = 0; let nextConfigLoadAttemptAtMs = 0; +function isLikelyOpenClawCliProcess(argv: string[] = process.argv): boolean { + const entryBasename = path + .basename(argv[1] ?? "") + .trim() + .toLowerCase(); + return ( + entryBasename === "openclaw" || + entryBasename === "openclaw.mjs" || + entryBasename === "entry.js" || + entryBasename === "entry.mjs" + ); +} + function getCommandPathFromArgv(argv: string[]): string[] { const args = argv.slice(2); const tokens: string[] = []; @@ -125,9 +139,12 @@ const SKIP_EAGER_WARMUP_PRIMARY_COMMANDS = new Set([ "webhooks", ]); -function shouldSkipEagerContextWindowWarmup(argv: string[] = process.argv): boolean { +function shouldEagerWarmContextWindowCache(argv: string[] = process.argv): boolean { + if (!isLikelyOpenClawCliProcess(argv)) { + return false; + } const [primary] = getCommandPathFromArgv(argv); - return primary ? SKIP_EAGER_WARMUP_PRIMARY_COMMANDS.has(primary) : false; + return Boolean(primary) && !SKIP_EAGER_WARMUP_PRIMARY_COMMANDS.has(primary); } function primeConfiguredContextWindows(): OpenClawConfig | undefined { @@ -205,14 +222,14 @@ export function lookupContextTokens(modelId?: string): number | undefined { if (!modelId) { return undefined; } - // Best-effort: kick off loading, but don't block. + // Best-effort: kick off loading on demand, but don't block lookups. void ensureContextWindowCacheLoaded(); return MODEL_CACHE.get(modelId); } -if (!shouldSkipEagerContextWindowWarmup()) { - // Keep prior behavior where model limits begin loading during startup. - // This avoids a cold-start miss on the first context token lookup. +if (shouldEagerWarmContextWindowCache()) { + // Keep startup warmth for the real CLI, but avoid import-time side effects + // when this module is pulled in through library/plugin-sdk surfaces. void ensureContextWindowCacheLoaded(); } diff --git a/src/plugin-sdk/root-alias.cjs b/src/plugin-sdk/root-alias.cjs index d9d742c3070..23e583f8c4d 100644 --- a/src/plugin-sdk/root-alias.cjs +++ b/src/plugin-sdk/root-alias.cjs @@ -113,6 +113,13 @@ const fastExports = { const target = { ...fastExports }; let rootExports = null; +function shouldResolveMonolithic(prop) { + if (typeof prop !== "string") { + return false; + } + return prop !== "then"; +} + function getMonolithicSdk() { const loaded = tryLoadMonolithicSdk(); if (loaded && typeof loaded === "object") { @@ -125,6 +132,9 @@ function getExportValue(prop) { if (Reflect.has(target, prop)) { return Reflect.get(target, prop); } + if (!shouldResolveMonolithic(prop)) { + return undefined; + } const monolithic = getMonolithicSdk(); if (!monolithic) { return undefined; @@ -137,6 +147,9 @@ function getExportDescriptor(prop) { if (ownDescriptor) { return ownDescriptor; } + if (!shouldResolveMonolithic(prop)) { + return undefined; + } const monolithic = getMonolithicSdk(); if (!monolithic) { @@ -166,6 +179,9 @@ rootExports = new Proxy(target, { if (Reflect.has(target, prop)) { return true; } + if (!shouldResolveMonolithic(prop)) { + return false; + } const monolithic = getMonolithicSdk(); return monolithic ? Reflect.has(monolithic, prop) : false; }, diff --git a/src/plugin-sdk/root-alias.test.ts b/src/plugin-sdk/root-alias.test.ts index 95565cab89a..83937c34b44 100644 --- a/src/plugin-sdk/root-alias.test.ts +++ b/src/plugin-sdk/root-alias.test.ts @@ -109,6 +109,17 @@ describe("plugin-sdk root alias", () => { expect(lazyModule.jitiLoadCalls).toBe(0); }); + it("does not load the monolithic sdk for promise-like or symbol reflection probes", () => { + const lazyModule = loadRootAliasWithStubs(); + const lazyRootSdk = lazyModule.moduleExports; + + expect("then" in lazyRootSdk).toBe(false); + expect(Reflect.get(lazyRootSdk, Symbol.toStringTag)).toBeUndefined(); + expect(Object.getOwnPropertyDescriptor(lazyRootSdk, Symbol.toStringTag)).toBeUndefined(); + expect(lazyModule.createJitiCalls).toBe(0); + expect(lazyModule.jitiLoadCalls).toBe(0); + }); + it("loads legacy root exports on demand and preserves reflection", () => { const lazyModule = loadRootAliasWithStubs({ monolithicExports: { From f3971571fe2c12267594eac732b40177ad726ad1 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 16:04:19 -0700 Subject: [PATCH 47/69] fix(plugins): fail strict bootstrap on plugin load errors --- src/cli/plugin-registry.test.ts | 8 ++++++-- src/cli/plugin-registry.ts | 1 + src/plugins/loader.test.ts | 29 +++++++++++++++++++++++++++++ src/plugins/loader.ts | 32 ++++++++++++++++++++++++++++++++ 4 files changed, 68 insertions(+), 2 deletions(-) diff --git a/src/cli/plugin-registry.test.ts b/src/cli/plugin-registry.test.ts index 336c720dfdb..30714b8a023 100644 --- a/src/cli/plugin-registry.test.ts +++ b/src/cli/plugin-registry.test.ts @@ -60,6 +60,7 @@ describe("ensurePluginRegistryLoaded", () => { expect(mocks.loadOpenClawPlugins).toHaveBeenCalledWith( expect.objectContaining({ onlyPluginIds: [], + throwOnLoadError: true, }), ); }); @@ -85,11 +86,14 @@ describe("ensurePluginRegistryLoaded", () => { expect(mocks.loadOpenClawPlugins).toHaveBeenCalledTimes(2); expect(mocks.loadOpenClawPlugins).toHaveBeenNthCalledWith( 1, - expect.objectContaining({ onlyPluginIds: [] }), + expect.objectContaining({ onlyPluginIds: [], throwOnLoadError: true }), ); expect(mocks.loadOpenClawPlugins).toHaveBeenNthCalledWith( 2, - expect.objectContaining({ onlyPluginIds: ["telegram", "slack"] }), + expect.objectContaining({ + onlyPluginIds: ["telegram", "slack"], + throwOnLoadError: true, + }), ); }); }); diff --git a/src/cli/plugin-registry.ts b/src/cli/plugin-registry.ts index bff91129204..4656a1d3756 100644 --- a/src/cli/plugin-registry.ts +++ b/src/cli/plugin-registry.ts @@ -55,6 +55,7 @@ export function ensurePluginRegistryLoaded(options?: { scope?: PluginRegistrySco config, workspaceDir, logger, + throwOnLoadError: true, ...(scope === "configured-channels" ? { onlyPluginIds: resolveConfiguredChannelPluginIds({ diff --git a/src/plugins/loader.test.ts b/src/plugins/loader.test.ts index c99ccbf41f0..489ab3ce294 100644 --- a/src/plugins/loader.test.ts +++ b/src/plugins/loader.test.ts @@ -1625,6 +1625,35 @@ module.exports = { id: "skipped-scoped-only", register() { throw new Error("skip expect(registry.diagnostics.some((d) => d.level === "error")).toBe(true); }); + it("throws when strict plugin loading sees plugin errors", () => { + useNoBundledPlugins(); + const plugin = writePlugin({ + id: "configurable", + filename: "configurable.cjs", + body: `module.exports = { id: "configurable", register() {} };`, + }); + + expect(() => + loadOpenClawPlugins({ + cache: false, + throwOnLoadError: true, + config: { + plugins: { + enabled: true, + load: { paths: [plugin.file] }, + allow: ["configurable"], + entries: { + configurable: { + enabled: true, + config: "nope" as unknown as Record, + }, + }, + }, + }, + }), + ).toThrow("plugin load failed: configurable: invalid config: : must be object"); + }); + it("fails when plugin export id mismatches manifest id", () => { useNoBundledPlugins(); const plugin = writePlugin({ diff --git a/src/plugins/loader.ts b/src/plugins/loader.ts index 68ba5b8403a..03a1b0810ff 100644 --- a/src/plugins/loader.ts +++ b/src/plugins/loader.ts @@ -71,8 +71,25 @@ export type PluginLoadOptions = { */ preferSetupRuntimeForChannelPlugins?: boolean; activate?: boolean; + throwOnLoadError?: boolean; }; +export class PluginLoadFailureError extends Error { + readonly pluginIds: string[]; + readonly registry: PluginRegistry; + + constructor(registry: PluginRegistry) { + const failedPlugins = registry.plugins.filter((entry) => entry.status === "error"); + const summary = failedPlugins + .map((entry) => `${entry.id}: ${entry.error ?? "unknown plugin load error"}`) + .join("; "); + super(`plugin load failed: ${summary}`); + this.name = "PluginLoadFailureError"; + this.pluginIds = failedPlugins.map((entry) => entry.id); + this.registry = registry; + } +} + const MAX_PLUGIN_REGISTRY_CACHE_ENTRIES = 128; const registryCache = new Map(); const openAllowlistWarningCache = new Set(); @@ -413,6 +430,19 @@ function pushDiagnostics(diagnostics: PluginDiagnostic[], append: PluginDiagnost diagnostics.push(...append); } +function maybeThrowOnPluginLoadError( + registry: PluginRegistry, + throwOnLoadError: boolean | undefined, +): void { + if (!throwOnLoadError) { + return; + } + if (!registry.plugins.some((entry) => entry.status === "error")) { + return; + } + throw new PluginLoadFailureError(registry); +} + type PathMatcher = { exact: Set; dirs: string[]; @@ -1253,6 +1283,8 @@ export function loadOpenClawPlugins(options: PluginLoadOptions = {}): PluginRegi env, }); + maybeThrowOnPluginLoadError(registry, options.throwOnLoadError); + if (cacheEnabled) { setCachedPluginRegistry(cacheKey, registry); } From 9486f6e37934875acf0ef72eed8f7c1c26114826 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 16:07:39 -0700 Subject: [PATCH 48/69] fix(build): suppress singleton smoke deprecation noise --- scripts/test-built-plugin-singleton.mjs | 35 +++++++++++++++++++++++++ src/agents/context.ts | 7 +++++ 2 files changed, 42 insertions(+) diff --git a/scripts/test-built-plugin-singleton.mjs b/scripts/test-built-plugin-singleton.mjs index 04e11c5f900..070f3b4341d 100644 --- a/scripts/test-built-plugin-singleton.mjs +++ b/scripts/test-built-plugin-singleton.mjs @@ -5,6 +5,41 @@ import path from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; import { stageBundledPluginRuntime } from "./stage-bundled-plugin-runtime.mjs"; +const warningFilterKey = Symbol.for("openclaw.warning-filter"); + +function installProcessWarningFilter() { + if (globalThis[warningFilterKey]?.installed) { + return; + } + + const originalEmitWarning = process.emitWarning.bind(process); + process.emitWarning = (...args) => { + const [warningArg, secondArg, thirdArg] = args; + const warning = + warningArg instanceof Error + ? { + name: warningArg.name, + message: warningArg.message, + code: warningArg.code, + } + : { + name: typeof secondArg === "string" ? secondArg : secondArg?.type, + message: typeof warningArg === "string" ? warningArg : undefined, + code: typeof thirdArg === "string" ? thirdArg : secondArg?.code, + }; + + if (warning.code === "DEP0040" && warning.message?.includes("punycode")) { + return; + } + + return Reflect.apply(originalEmitWarning, process, args); + }; + + globalThis[warningFilterKey] = { installed: true }; +} + +installProcessWarningFilter(); + const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); const smokeEntryPath = path.join(repoRoot, "dist", "plugins", "build-smoke-entry.js"); assert.ok(fs.existsSync(smokeEntryPath), `missing build output: ${smokeEntryPath}`); diff --git a/src/agents/context.ts b/src/agents/context.ts index 279433f0c76..841432e873e 100644 --- a/src/agents/context.ts +++ b/src/agents/context.ts @@ -140,6 +140,13 @@ const SKIP_EAGER_WARMUP_PRIMARY_COMMANDS = new Set([ ]); function shouldEagerWarmContextWindowCache(argv: string[] = process.argv): boolean { + // Keep this gate tied to the real OpenClaw CLI entrypoints. + // + // This module can also land inside shared dist chunks that are imported from + // plugin-sdk/library surfaces during smoke tests and plugin loading. If we do + // eager warmup for those generic Node script imports, merely importing the + // built plugin-sdk can call ensureOpenClawModelsJson(), which cascades into + // plugin discovery and breaks dist/source singleton assumptions. if (!isLikelyOpenClawCliProcess(argv)) { return false; } From 8e132aed6eea42d2010b92fbd93b2df0fae35b9d Mon Sep 17 00:00:00 2001 From: Josh Avant <830519+joshavant@users.noreply.github.com> Date: Thu, 19 Mar 2026 18:26:06 -0500 Subject: [PATCH 49/69] Hardening: refresh stale device pairing requests and pending metadata (#50695) * Docs: clarify device pairing supersede behavior * Device pairing: supersede pending requests on auth changes --- CHANGELOG.md | 1 + docs/channels/pairing.md | 6 +- docs/channels/telegram.md | 8 +- docs/cli/devices.md | 8 + docs/cli/node.md | 4 + docs/nodes/index.md | 7 + docs/platforms/ios.md | 4 + docs/web/control-ui.md | 4 + extensions/device-pair/notify.test.ts | 41 +++++ extensions/device-pair/notify.ts | 29 ++++ src/cli/devices-cli.test.ts | 24 +++ src/cli/devices-cli.ts | 30 +++- ...rver.device-pair-approve-supersede.test.ts | 53 +++++++ src/infra/device-pairing.test.ts | 18 ++- src/infra/device-pairing.ts | 144 ++++++++++++++---- ui/src/ui/controllers/devices.ts | 2 + ui/src/ui/views/nodes.devices.test.ts | 104 +++++++++++++ ui/src/ui/views/nodes.ts | 5 +- vitest.config.ts | 1 + 19 files changed, 452 insertions(+), 41 deletions(-) create mode 100644 extensions/device-pair/notify.test.ts create mode 100644 src/gateway/server.device-pair-approve-supersede.test.ts create mode 100644 ui/src/ui/views/nodes.devices.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 43aff8bd18c..8de5d606931 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -139,6 +139,7 @@ Docs: https://docs.openclaw.ai - Discord: enforce strict DM component allowlist auth (#49997) Thanks @joshavant. - Stabilize plugin loader and Docker extension smoke (#50058) Thanks @joshavant. - Telegram: stabilize pairing/session/forum routing and reply formatting tests (#50155) Thanks @joshavant. +- Hardening: refresh stale device pairing requests and pending metadata (#50695) Thanks @smaeljaish771 and @joshavant. ### Fixes diff --git a/docs/channels/pairing.md b/docs/channels/pairing.md index 1ba3c6c92f2..592ced0f11d 100644 --- a/docs/channels/pairing.md +++ b/docs/channels/pairing.md @@ -67,7 +67,7 @@ If you use the `device-pair` plugin, you can do first-time device pairing entire 2. The bot replies with two messages: an instruction message and a separate **setup code** message (easy to copy/paste in Telegram). 3. On your phone, open the OpenClaw iOS app → Settings → Gateway. 4. Paste the setup code and connect. -5. Back in Telegram: `/pair approve` +5. Back in Telegram: `/pair pending` (review request IDs, role, and scopes), then approve. The setup code is a base64-encoded JSON payload that contains: @@ -84,6 +84,10 @@ openclaw devices approve openclaw devices reject ``` +If the same device retries with different auth details (for example different +role/scopes/public key), the previous pending request is superseded and a new +`requestId` is created. + ### Node pairing state storage Stored under `~/.openclaw/devices/`: diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index 2758982b8d7..91ac3ec4b67 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -346,7 +346,13 @@ curl "https://api.telegram.org/bot/getUpdates" 1. `/pair` generates setup code 2. paste code in iOS app - 3. `/pair approve` approves latest pending request + 3. `/pair pending` lists pending requests (including role/scopes) + 4. approve the request: + - `/pair approve ` for explicit approval + - `/pair approve` when there is only one pending request + - `/pair approve latest` for most recent + + If a device retries with changed auth details (for example role/scopes/public key), the previous pending request is superseded and the new request uses a different `requestId`. Re-run `/pair pending` before approving. More details: [Pairing](/channels/pairing#pair-via-telegram-recommended-for-ios). diff --git a/docs/cli/devices.md b/docs/cli/devices.md index f73f30dfa1d..fa0d53a2401 100644 --- a/docs/cli/devices.md +++ b/docs/cli/devices.md @@ -21,6 +21,9 @@ openclaw devices list openclaw devices list --json ``` +Pending request output includes the requested role and scopes so approvals can +be reviewed before you approve. + ### `openclaw devices remove ` Remove one paired device entry. @@ -45,6 +48,11 @@ openclaw devices clear --yes --pending --json Approve a pending device pairing request. If `requestId` is omitted, OpenClaw automatically approves the most recent pending request. +Note: if a device retries pairing with changed auth details (role/scopes/public +key), OpenClaw supersedes the previous pending entry and issues a new +`requestId`. Run `openclaw devices list` right before approval to use the +current ID. + ``` openclaw devices approve openclaw devices approve diff --git a/docs/cli/node.md b/docs/cli/node.md index baf8c3cd45e..a1f882a7870 100644 --- a/docs/cli/node.md +++ b/docs/cli/node.md @@ -111,6 +111,10 @@ openclaw devices list openclaw devices approve ``` +If the node retries pairing with changed auth details (role/scopes/public key), +the previous pending request is superseded and a new `requestId` is created. +Run `openclaw devices list` again before approval. + The node host stores its node id, token, display name, and gateway connection info in `~/.openclaw/node.json`. diff --git a/docs/nodes/index.md b/docs/nodes/index.md index f23a2c979cf..b333708b16d 100644 --- a/docs/nodes/index.md +++ b/docs/nodes/index.md @@ -36,6 +36,10 @@ openclaw nodes status openclaw nodes describe --node ``` +If a node retries with changed auth details (role/scopes/public key), the prior +pending request is superseded and a new `requestId` is created. Re-run +`openclaw devices list` before approving. + Notes: - `nodes status` marks a node as **paired** when its device pairing role includes `node`. @@ -115,6 +119,9 @@ openclaw devices approve openclaw nodes status ``` +If the node retries with changed auth details, re-run `openclaw devices list` +and approve the current `requestId`. + Naming options: - `--display-name` on `openclaw node run` / `openclaw node install` (persists in `~/.openclaw/node.json` on the node). diff --git a/docs/platforms/ios.md b/docs/platforms/ios.md index f64eba3fed0..fb37ae2d34f 100644 --- a/docs/platforms/ios.md +++ b/docs/platforms/ios.md @@ -42,6 +42,10 @@ openclaw devices list openclaw devices approve ``` +If the app retries pairing with changed auth details (role/scopes/public key), +the previous pending request is superseded and a new `requestId` is created. +Run `openclaw devices list` again before approval. + 4. Verify connection: ```bash diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md index 952f6f71c1d..9de259a7ef4 100644 --- a/docs/web/control-ui.md +++ b/docs/web/control-ui.md @@ -49,6 +49,10 @@ openclaw devices list openclaw devices approve ``` +If the browser retries pairing with changed auth details (role/scopes/public +key), the previous pending request is superseded and a new `requestId` is +created. Re-run `openclaw devices list` before approval. + Once approved, the device is remembered and won't require re-approval unless you revoke it with `openclaw devices revoke --device --role `. See [Devices CLI](/cli/devices) for token rotation and revocation. diff --git a/extensions/device-pair/notify.test.ts b/extensions/device-pair/notify.test.ts new file mode 100644 index 00000000000..f3e226f49f7 --- /dev/null +++ b/extensions/device-pair/notify.test.ts @@ -0,0 +1,41 @@ +import { describe, expect, it } from "vitest"; +import { formatPendingRequests, type PendingPairingRequest } from "./notify.ts"; + +describe("device-pair notify pending formatting", () => { + it("includes role and scopes for pending requests", () => { + const pending: PendingPairingRequest[] = [ + { + requestId: "req-1", + deviceId: "device-1", + displayName: "dev one", + platform: "ios", + role: "operator", + scopes: ["operator.admin", "operator.read"], + remoteIp: "198.51.100.2", + }, + ]; + + const text = formatPendingRequests(pending); + expect(text).toContain("Pending device pairing requests:"); + expect(text).toContain("name=dev one"); + expect(text).toContain("platform=ios"); + expect(text).toContain("role=operator"); + expect(text).toContain("scopes=operator.admin, operator.read"); + expect(text).toContain("ip=198.51.100.2"); + }); + + it("falls back to roles list and no scopes when role/scopes are absent", () => { + const pending: PendingPairingRequest[] = [ + { + requestId: "req-2", + deviceId: "device-2", + roles: ["node", "operator"], + scopes: [], + }, + ]; + + const text = formatPendingRequests(pending); + expect(text).toContain("role=node, operator"); + expect(text).toContain("scopes=none"); + }); +}); diff --git a/extensions/device-pair/notify.ts b/extensions/device-pair/notify.ts index ba45e856372..90e0e1890ab 100644 --- a/extensions/device-pair/notify.ts +++ b/extensions/device-pair/notify.ts @@ -25,10 +25,33 @@ export type PendingPairingRequest = { deviceId: string; displayName?: string; platform?: string; + role?: string; + roles?: string[]; + scopes?: string[]; remoteIp?: string; ts?: number; }; +function formatStringList(values?: readonly string[]): string { + if (!Array.isArray(values) || values.length === 0) { + return "none"; + } + const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0); + return normalized.length > 0 ? normalized.join(", ") : "none"; +} + +function formatRoleList(request: PendingPairingRequest): string { + const role = request.role?.trim(); + if (role) { + return role; + } + return formatStringList(request.roles); +} + +function formatScopeList(request: PendingPairingRequest): string { + return formatStringList(request.scopes); +} + export function formatPendingRequests(pending: PendingPairingRequest[]): string { if (pending.length === 0) { return "No pending device pairing requests."; @@ -42,6 +65,8 @@ export function formatPendingRequests(pending: PendingPairingRequest[]): string `- ${req.requestId}`, label ? `name=${label}` : null, platform ? `platform=${platform}` : null, + `role=${formatRoleList(req)}`, + `scopes=${formatScopeList(req)}`, ip ? `ip=${ip}` : null, ].filter(Boolean); lines.push(parts.join(" · ")); @@ -182,11 +207,15 @@ function buildPairingRequestNotificationText(request: PendingPairingRequest): st const label = request.displayName?.trim() || request.deviceId; const platform = request.platform?.trim(); const ip = request.remoteIp?.trim(); + const role = formatRoleList(request); + const scopes = formatScopeList(request); const lines = [ "📲 New device pairing request", `ID: ${request.requestId}`, `Name: ${label}`, ...(platform ? [`Platform: ${platform}`] : []), + `Role: ${role}`, + `Scopes: ${scopes}`, ...(ip ? [`IP: ${ip}`] : []), "", `Approve: /pair approve ${request.requestId}`, diff --git a/src/cli/devices-cli.test.ts b/src/cli/devices-cli.test.ts index 7d6abba39b0..81ca7d3c37f 100644 --- a/src/cli/devices-cli.test.ts +++ b/src/cli/devices-cli.test.ts @@ -287,6 +287,30 @@ describe("devices cli local fallback", () => { }); }); +describe("devices cli list", () => { + it("renders pending scopes when present", async () => { + callGateway.mockResolvedValueOnce({ + pending: [ + { + requestId: "req-1", + deviceId: "device-1", + displayName: "Device One", + role: "operator", + scopes: ["operator.admin", "operator.read"], + ts: 1, + }, + ], + paired: [], + }); + + await runDevicesCommand(["list"]); + + const output = runtime.log.mock.calls.map((entry) => String(entry[0] ?? "")).join("\n"); + expect(output).toContain("Scopes"); + expect(output).toContain("operator.admin, operator.read"); + }); +}); + afterEach(() => { callGateway.mockClear(); buildGatewayConnectionDetails.mockClear(); diff --git a/src/cli/devices-cli.ts b/src/cli/devices-cli.ts index 143d27b20ff..96b2db3a332 100644 --- a/src/cli/devices-cli.ts +++ b/src/cli/devices-cli.ts @@ -39,6 +39,8 @@ type PendingDevice = { deviceId: string; displayName?: string; role?: string; + roles?: string[]; + scopes?: string[]; remoteIp?: string; isRepair?: boolean; ts?: number; @@ -197,6 +199,30 @@ function formatTokenSummary(tokens: DeviceTokenSummary[] | undefined) { return parts.join(", "); } +function formatPendingRoles(request: PendingDevice): string { + const role = typeof request.role === "string" ? request.role.trim() : ""; + if (role) { + return role; + } + const roles = Array.isArray(request.roles) + ? request.roles.map((item) => item.trim()).filter((item) => item.length > 0) + : []; + if (roles.length === 0) { + return ""; + } + return roles.join(", "); +} + +function formatPendingScopes(request: PendingDevice): string { + const scopes = Array.isArray(request.scopes) + ? request.scopes.map((item) => item.trim()).filter((item) => item.length > 0) + : []; + if (scopes.length === 0) { + return ""; + } + return scopes.join(", "); +} + function resolveRequiredDeviceRole( opts: DevicesRpcOpts, ): { deviceId: string; role: string } | null { @@ -235,6 +261,7 @@ export function registerDevicesCli(program: Command) { { key: "Request", header: "Request", minWidth: 10 }, { key: "Device", header: "Device", minWidth: 16, flex: true }, { key: "Role", header: "Role", minWidth: 8 }, + { key: "Scopes", header: "Scopes", minWidth: 14, flex: true }, { key: "IP", header: "IP", minWidth: 12 }, { key: "Age", header: "Age", minWidth: 8 }, { key: "Flags", header: "Flags", minWidth: 8 }, @@ -242,7 +269,8 @@ export function registerDevicesCli(program: Command) { rows: list.pending.map((req) => ({ Request: req.requestId, Device: req.displayName || req.deviceId, - Role: req.role ?? "", + Role: formatPendingRoles(req), + Scopes: formatPendingScopes(req), IP: req.remoteIp ?? "", Age: typeof req.ts === "number" ? formatTimeAgo(Date.now() - req.ts) : "", Flags: req.isRepair ? "repair" : "", diff --git a/src/gateway/server.device-pair-approve-supersede.test.ts b/src/gateway/server.device-pair-approve-supersede.test.ts new file mode 100644 index 00000000000..310598693e0 --- /dev/null +++ b/src/gateway/server.device-pair-approve-supersede.test.ts @@ -0,0 +1,53 @@ +import { describe, expect, test } from "vitest"; +import { getPairedDevice, requestDevicePairing } from "../infra/device-pairing.js"; +import { + connectOk, + installGatewayTestHooks, + rpcReq, + startServerWithClient, +} from "./test-helpers.js"; + +installGatewayTestHooks({ scope: "suite" }); + +describe("gateway device.pair.approve superseded request ids", () => { + test("rejects approving a superseded request id", async () => { + const started = await startServerWithClient("secret"); + + try { + const first = await requestDevicePairing({ + deviceId: "supersede-device-1", + publicKey: "supersede-public-key", + role: "node", + scopes: ["node.exec"], + }); + const second = await requestDevicePairing({ + deviceId: "supersede-device-1", + publicKey: "supersede-public-key", + role: "operator", + scopes: ["operator.admin"], + }); + + expect(second.request.requestId).not.toBe(first.request.requestId); + await connectOk(started.ws); + + const staleApprove = await rpcReq(started.ws, "device.pair.approve", { + requestId: first.request.requestId, + }); + expect(staleApprove.ok).toBe(false); + expect(staleApprove.error?.message).toBe("unknown requestId"); + + const latestApprove = await rpcReq(started.ws, "device.pair.approve", { + requestId: second.request.requestId, + }); + expect(latestApprove.ok).toBe(true); + + const paired = await getPairedDevice("supersede-device-1"); + expect(paired?.role).toBe("operator"); + expect(paired?.scopes).toEqual(["operator.admin"]); + } finally { + started.ws.close(); + await started.server.close(); + started.envSnapshot.restore(); + } + }); +}); diff --git a/src/infra/device-pairing.test.ts b/src/infra/device-pairing.test.ts index 4deb04a8912..b1805145cf8 100644 --- a/src/infra/device-pairing.test.ts +++ b/src/infra/device-pairing.test.ts @@ -8,6 +8,7 @@ import { clearDevicePairing, ensureDeviceToken, getPairedDevice, + listDevicePairing, removePairedDevice, requestDevicePairing, rotateDeviceToken, @@ -124,7 +125,7 @@ describe("device pairing tokens", () => { expect(second.request.requestId).toBe(first.request.requestId); }); - test("merges pending roles/scopes for the same device before approval", async () => { + test("supersedes pending requests when requested roles/scopes change", async () => { const baseDir = await mkdtemp(join(tmpdir(), "openclaw-device-pairing-")); const first = await requestDevicePairing( { @@ -145,14 +146,19 @@ describe("device pairing tokens", () => { baseDir, ); - expect(second.created).toBe(false); - expect(second.request.requestId).toBe(first.request.requestId); - expect(second.request.roles).toEqual(["node", "operator"]); + expect(second.created).toBe(true); + expect(second.request.requestId).not.toBe(first.request.requestId); + expect(second.request.role).toBe("operator"); + expect(second.request.roles).toEqual(["operator"]); expect(second.request.scopes).toEqual(["operator.read", "operator.write"]); - await approveDevicePairing(first.request.requestId, baseDir); + const list = await listDevicePairing(baseDir); + expect(list.pending).toHaveLength(1); + expect(list.pending[0]?.requestId).toBe(second.request.requestId); + + await approveDevicePairing(second.request.requestId, baseDir); const paired = await getPairedDevice("device-1", baseDir); - expect(paired?.roles).toEqual(["node", "operator"]); + expect(paired?.roles).toEqual(["operator"]); expect(paired?.scopes).toEqual(["operator.read", "operator.write"]); }); diff --git a/src/infra/device-pairing.ts b/src/infra/device-pairing.ts index 063834a17de..b51ae0db67a 100644 --- a/src/infra/device-pairing.ts +++ b/src/infra/device-pairing.ts @@ -175,23 +175,59 @@ function mergeScopes(...items: Array): string[] | undefine return [...scopes]; } -function mergePendingDevicePairingRequest( +function sameStringSet(left: readonly string[], right: readonly string[]): boolean { + if (left.length !== right.length) { + return false; + } + const rightSet = new Set(right); + for (const value of left) { + if (!rightSet.has(value)) { + return false; + } + } + return true; +} + +function resolveRequestedRoles(input: { role?: string; roles?: string[] }): string[] { + return mergeRoles(input.roles, input.role) ?? []; +} + +function resolveRequestedScopes(input: { scopes?: string[] }): string[] { + return normalizeDeviceAuthScopes(input.scopes); +} + +function samePendingApprovalSnapshot( + existing: DevicePairingPendingRequest, + incoming: Omit, +): boolean { + if (existing.publicKey !== incoming.publicKey) { + return false; + } + if (normalizeRole(existing.role) !== normalizeRole(incoming.role)) { + return false; + } + if ( + !sameStringSet(resolveRequestedRoles(existing), resolveRequestedRoles(incoming)) || + !sameStringSet(resolveRequestedScopes(existing), resolveRequestedScopes(incoming)) + ) { + return false; + } + return true; +} + +function refreshPendingDevicePairingRequest( existing: DevicePairingPendingRequest, incoming: Omit, isRepair: boolean, ): DevicePairingPendingRequest { - const existingRole = normalizeRole(existing.role); - const incomingRole = normalizeRole(incoming.role); return { ...existing, + publicKey: incoming.publicKey, displayName: incoming.displayName ?? existing.displayName, platform: incoming.platform ?? existing.platform, deviceFamily: incoming.deviceFamily ?? existing.deviceFamily, clientId: incoming.clientId ?? existing.clientId, clientMode: incoming.clientMode ?? existing.clientMode, - role: existingRole ?? incomingRole ?? undefined, - roles: mergeRoles(existing.roles, existing.role, incoming.role), - scopes: mergeScopes(existing.scopes, incoming.scopes), remoteIp: incoming.remoteIp ?? existing.remoteIp, // If either request is interactive, keep the pending request visible for approval. silent: Boolean(existing.silent && incoming.silent), @@ -200,6 +236,49 @@ function mergePendingDevicePairingRequest( }; } +function buildPendingDevicePairingRequest(params: { + requestId?: string; + deviceId: string; + isRepair: boolean; + req: Omit; +}): DevicePairingPendingRequest { + const role = normalizeRole(params.req.role) ?? undefined; + return { + requestId: params.requestId ?? randomUUID(), + deviceId: params.deviceId, + publicKey: params.req.publicKey, + displayName: params.req.displayName, + platform: params.req.platform, + deviceFamily: params.req.deviceFamily, + clientId: params.req.clientId, + clientMode: params.req.clientMode, + role, + roles: mergeRoles(params.req.roles, role), + scopes: mergeScopes(params.req.scopes), + remoteIp: params.req.remoteIp, + silent: params.req.silent, + isRepair: params.isRepair, + ts: Date.now(), + }; +} + +function resolvePendingApprovalRole(pending: DevicePairingPendingRequest): string | null { + const role = normalizeRole(pending.role); + if (role) { + return role; + } + if (!Array.isArray(pending.roles)) { + return null; + } + for (const candidate of pending.roles) { + const normalized = normalizeRole(candidate); + if (normalized) { + return normalized; + } + } + return null; +} + function newToken() { return generatePairingToken(); } @@ -296,33 +375,37 @@ export async function requestDevicePairing( throw new Error("deviceId required"); } const isRepair = Boolean(state.pairedByDeviceId[deviceId]); - const existing = Object.values(state.pendingById).find( - (pending) => pending.deviceId === deviceId, - ); - if (existing) { - const merged = mergePendingDevicePairingRequest(existing, req, isRepair); - state.pendingById[existing.requestId] = merged; + const pendingForDevice = Object.values(state.pendingById) + .filter((pending) => pending.deviceId === deviceId) + .toSorted((left, right) => right.ts - left.ts); + const latestPending = pendingForDevice[0]; + if (latestPending && pendingForDevice.length === 1) { + if (samePendingApprovalSnapshot(latestPending, req)) { + const refreshed = refreshPendingDevicePairingRequest(latestPending, req, isRepair); + state.pendingById[latestPending.requestId] = refreshed; + await persistState(state, baseDir); + return { status: "pending" as const, request: refreshed, created: false }; + } + } + if (pendingForDevice.length > 0) { + for (const pending of pendingForDevice) { + delete state.pendingById[pending.requestId]; + } + const superseded = buildPendingDevicePairingRequest({ + deviceId, + isRepair, + req, + }); + state.pendingById[superseded.requestId] = superseded; await persistState(state, baseDir); - return { status: "pending" as const, request: merged, created: false }; + return { status: "pending" as const, request: superseded, created: true }; } - const request: DevicePairingPendingRequest = { - requestId: randomUUID(), + const request = buildPendingDevicePairingRequest({ deviceId, - publicKey: req.publicKey, - displayName: req.displayName, - platform: req.platform, - deviceFamily: req.deviceFamily, - clientId: req.clientId, - clientMode: req.clientMode, - role: req.role, - roles: req.role ? [req.role] : undefined, - scopes: req.scopes, - remoteIp: req.remoteIp, - silent: req.silent, isRepair, - ts: Date.now(), - }; + req, + }); state.pendingById[request.requestId] = request; await persistState(state, baseDir); return { status: "pending" as const, request, created: true }; @@ -354,9 +437,10 @@ export async function approveDevicePairing( if (!pending) { return null; } - if (pending.role && options?.callerScopes) { + const approvalRole = resolvePendingApprovalRole(pending); + if (approvalRole && options?.callerScopes) { const missingScope = resolveMissingRequestedScope({ - role: pending.role, + role: approvalRole, requestedScopes: normalizeDeviceAuthScopes(pending.scopes), allowedScopes: options.callerScopes, }); diff --git a/ui/src/ui/controllers/devices.ts b/ui/src/ui/controllers/devices.ts index 16edd8afe43..64095856df0 100644 --- a/ui/src/ui/controllers/devices.ts +++ b/ui/src/ui/controllers/devices.ts @@ -16,6 +16,8 @@ export type PendingDevice = { deviceId: string; displayName?: string; role?: string; + roles?: string[]; + scopes?: string[]; remoteIp?: string; isRepair?: boolean; ts?: number; diff --git a/ui/src/ui/views/nodes.devices.test.ts b/ui/src/ui/views/nodes.devices.test.ts new file mode 100644 index 00000000000..0fb2c6915dd --- /dev/null +++ b/ui/src/ui/views/nodes.devices.test.ts @@ -0,0 +1,104 @@ +/* @vitest-environment jsdom */ +import { render } from "lit"; +import { describe, expect, it } from "vitest"; +import { renderNodes, type NodesProps } from "./nodes.ts"; + +function baseProps(overrides: Partial = {}): NodesProps { + return { + loading: false, + nodes: [], + devicesLoading: false, + devicesError: null, + devicesList: { + pending: [], + paired: [], + }, + configForm: null, + configLoading: false, + configSaving: false, + configDirty: false, + configFormMode: "form", + execApprovalsLoading: false, + execApprovalsSaving: false, + execApprovalsDirty: false, + execApprovalsSnapshot: null, + execApprovalsForm: null, + execApprovalsSelectedAgent: null, + execApprovalsTarget: "gateway", + execApprovalsTargetNodeId: null, + onRefresh: () => undefined, + onDevicesRefresh: () => undefined, + onDeviceApprove: () => undefined, + onDeviceReject: () => undefined, + onDeviceRotate: () => undefined, + onDeviceRevoke: () => undefined, + onLoadConfig: () => undefined, + onLoadExecApprovals: () => undefined, + onBindDefault: () => undefined, + onBindAgent: () => undefined, + onSaveBindings: () => undefined, + onExecApprovalsTargetChange: () => undefined, + onExecApprovalsSelectAgent: () => undefined, + onExecApprovalsPatch: () => undefined, + onExecApprovalsRemove: () => undefined, + onSaveExecApprovals: () => undefined, + ...overrides, + }; +} + +describe("nodes devices pending rendering", () => { + it("shows pending role and scopes from effective pending auth", () => { + const container = document.createElement("div"); + render( + renderNodes( + baseProps({ + devicesList: { + pending: [ + { + requestId: "req-1", + deviceId: "device-1", + displayName: "Device One", + role: "operator", + scopes: ["operator.admin", "operator.read"], + ts: Date.now(), + }, + ], + paired: [], + }, + }), + ), + container, + ); + + const text = container.textContent ?? ""; + expect(text).toContain("role: operator"); + expect(text).toContain("scopes: operator.admin, operator.read"); + }); + + it("falls back to roles when role is absent", () => { + const container = document.createElement("div"); + render( + renderNodes( + baseProps({ + devicesList: { + pending: [ + { + requestId: "req-2", + deviceId: "device-2", + roles: ["node", "operator"], + scopes: ["operator.read"], + ts: Date.now(), + }, + ], + paired: [], + }, + }), + ), + container, + ); + + const text = container.textContent ?? ""; + expect(text).toContain("role: node, operator"); + expect(text).toContain("scopes: operator.read"); + }); +}); diff --git a/ui/src/ui/views/nodes.ts b/ui/src/ui/views/nodes.ts index 8a8413b6d58..ad3b30e7531 100644 --- a/ui/src/ui/views/nodes.ts +++ b/ui/src/ui/views/nodes.ts @@ -128,7 +128,8 @@ function renderDevices(props: NodesProps) { function renderPendingDevice(req: PendingDevice, props: NodesProps) { const name = req.displayName?.trim() || req.deviceId; const age = typeof req.ts === "number" ? formatRelativeTimestamp(req.ts) : "n/a"; - const role = req.role?.trim() ? `role: ${req.role}` : "role: -"; + const roleValue = req.role?.trim() || formatList(req.roles); + const scopesValue = formatList(req.scopes); const repair = req.isRepair ? " · repair" : ""; const ip = req.remoteIp ? ` · ${req.remoteIp}` : ""; return html` @@ -137,7 +138,7 @@ function renderPendingDevice(req: PendingDevice, props: NodesProps) {
${name}
${req.deviceId}${ip}
- ${role} · requested ${age}${repair} + role: ${roleValue} · scopes: ${scopesValue} · requested ${age}${repair}
diff --git a/vitest.config.ts b/vitest.config.ts index 60289881975..f254bcdf0a7 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -40,6 +40,7 @@ export default defineConfig({ "ui/src/ui/app-chat.test.ts", "ui/src/ui/views/agents-utils.test.ts", "ui/src/ui/views/chat.test.ts", + "ui/src/ui/views/nodes.devices.test.ts", "ui/src/ui/views/usage-render-details.test.ts", "ui/src/ui/controllers/agents.test.ts", "ui/src/ui/controllers/chat.test.ts", From 0f69b5c11aba25a05642ea611708c53ba13c99e1 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 16:25:37 -0700 Subject: [PATCH 50/69] fix(status): keep startup paths free of plugin warmup --- src/agents/context.lookup.test.ts | 19 +++++++++++++++++++ src/agents/context.ts | 16 +++++++++++++--- src/commands/status.scan.fast-json.ts | 14 ++++++++++++-- src/commands/status.summary.test.ts | 9 +++++++++ src/commands/status.summary.ts | 4 ++++ 5 files changed, 57 insertions(+), 5 deletions(-) diff --git a/src/agents/context.lookup.test.ts b/src/agents/context.lookup.test.ts index 31d702c5420..aa0ad8bdf56 100644 --- a/src/agents/context.lookup.test.ts +++ b/src/agents/context.lookup.test.ts @@ -82,6 +82,25 @@ describe("lookupContextTokens", () => { expect(lookupContextTokens("openrouter/claude-sonnet")).toBe(321_000); }); + it("can skip async warmup for read-only callers", async () => { + const { ensureOpenClawModelsJson } = mockContextModuleDeps(() => ({ + models: { + providers: { + openrouter: { + models: [{ id: "openrouter/claude-sonnet", contextWindow: 321_000 }], + }, + }, + }, + })); + + const { lookupContextTokens } = await import("./context.js"); + expect( + lookupContextTokens("openrouter/claude-sonnet", { allowAsyncLoad: false }), + ).toBeUndefined(); + await flushAsyncWarmup(); + expect(ensureOpenClawModelsJson).not.toHaveBeenCalled(); + }); + it("only warms eagerly for real openclaw startup commands that need model metadata", async () => { const argvSnapshot = process.argv; try { diff --git a/src/agents/context.ts b/src/agents/context.ts index 841432e873e..030b350e451 100644 --- a/src/agents/context.ts +++ b/src/agents/context.ts @@ -225,12 +225,17 @@ function ensureContextWindowCacheLoaded(): Promise { return loadPromise; } -export function lookupContextTokens(modelId?: string): number | undefined { +export function lookupContextTokens( + modelId?: string, + options?: { allowAsyncLoad?: boolean }, +): number | undefined { if (!modelId) { return undefined; } // Best-effort: kick off loading on demand, but don't block lookups. - void ensureContextWindowCacheLoaded(); + if (options?.allowAsyncLoad !== false) { + void ensureContextWindowCacheLoaded(); + } return MODEL_CACHE.get(modelId); } @@ -354,6 +359,7 @@ export function resolveContextTokensForModel(params: { model?: string; contextTokensOverride?: number; fallbackContextTokens?: number; + allowAsyncLoad?: boolean; }): number | undefined { if (typeof params.contextTokensOverride === "number" && params.contextTokensOverride > 0) { return params.contextTokensOverride; @@ -402,6 +408,7 @@ export function resolveContextTokensForModel(params: { if (params.provider && ref && !ref.model.includes("/")) { const qualifiedResult = lookupContextTokens( `${normalizeProviderId(ref.provider)}/${ref.model}`, + { allowAsyncLoad: params.allowAsyncLoad }, ); if (qualifiedResult !== undefined) { return qualifiedResult; @@ -410,7 +417,9 @@ export function resolveContextTokensForModel(params: { // Bare key fallback. For model-only calls with slash-containing IDs // (e.g. "google/gemini-2.5-pro") this IS the raw discovery cache key. - const bareResult = lookupContextTokens(params.model); + const bareResult = lookupContextTokens(params.model, { + allowAsyncLoad: params.allowAsyncLoad, + }); if (bareResult !== undefined) { return bareResult; } @@ -421,6 +430,7 @@ export function resolveContextTokensForModel(params: { if (!params.provider && ref && !ref.model.includes("/")) { const qualifiedResult = lookupContextTokens( `${normalizeProviderId(ref.provider)}/${ref.model}`, + { allowAsyncLoad: params.allowAsyncLoad }, ); if (qualifiedResult !== undefined) { return qualifiedResult; diff --git a/src/commands/status.scan.fast-json.ts b/src/commands/status.scan.fast-json.ts index 953e9b9f77a..267a7200739 100644 --- a/src/commands/status.scan.fast-json.ts +++ b/src/commands/status.scan.fast-json.ts @@ -5,7 +5,6 @@ import { hasPotentialConfiguredChannels } from "../channels/config-presence.js"; import { resolveConfigPath, resolveStateDir } from "../config/paths.js"; import type { OpenClawConfig } from "../config/types.js"; import { resolveOsSummary } from "../infra/os-summary.js"; -import { buildPluginCompatibilityNotices } from "../plugins/status.js"; import { runExec } from "../process/exec.js"; import type { RuntimeEnv } from "../runtime.js"; import { getAgentLocalStatuses } from "./status.agent-local.js"; @@ -23,6 +22,7 @@ import { getStatusSummary } from "./status.summary.js"; import { getUpdateCheckResult } from "./status.update.js"; let pluginRegistryModulePromise: Promise | undefined; +let pluginStatusModulePromise: Promise | undefined; let configIoModulePromise: Promise | undefined; let commandSecretTargetsModulePromise: | Promise @@ -40,6 +40,11 @@ function loadPluginRegistryModule() { return pluginRegistryModulePromise; } +function loadPluginStatusModule() { + pluginStatusModulePromise ??= import("../plugins/status.js"); + return pluginStatusModulePromise; +} + function loadConfigIoModule() { configIoModulePromise ??= import("../config/io.js"); return configIoModulePromise; @@ -194,7 +199,12 @@ export async function scanStatusJsonFast( const memoryPlugin = resolveMemoryPluginStatus(cfg); const memory = await resolveMemoryStatusSnapshot({ cfg, agentStatus, memoryPlugin }); const pluginCompatibility = shouldCollectPluginCompatibility(cfg) - ? buildPluginCompatibilityNotices({ config: cfg }) + ? await loadPluginStatusModule().then(({ buildPluginCompatibilityNotices }) => + // Keep plugin status loading off the empty-config `status --json` fast path. + // The plugin status module pulls in the full loader graph and materially bloats + // startup RSS even when plugin compatibility is never consulted. + buildPluginCompatibilityNotices({ config: cfg }), + ) : []; return { diff --git a/src/commands/status.summary.test.ts b/src/commands/status.summary.test.ts index 2f4f9ce260f..c441ce1d879 100644 --- a/src/commands/status.summary.test.ts +++ b/src/commands/status.summary.test.ts @@ -78,6 +78,7 @@ vi.mock("./status.link-channel.js", () => ({ })); const { hasPotentialConfiguredChannels } = await import("../channels/config-presence.js"); +const { resolveContextTokensForModel } = await import("../agents/context.js"); const { buildChannelSummary } = await import("../infra/channel-summary.js"); const { resolveLinkChannelContext } = await import("./status.link-channel.js"); const { getStatusSummary } = await import("./status.summary.js"); @@ -105,4 +106,12 @@ describe("getStatusSummary", () => { expect(buildChannelSummary).not.toHaveBeenCalled(); expect(resolveLinkChannelContext).not.toHaveBeenCalled(); }); + + it("does not trigger async context warmup while building status summaries", async () => { + await getStatusSummary(); + + expect(vi.mocked(resolveContextTokensForModel)).toHaveBeenCalledWith( + expect.objectContaining({ allowAsyncLoad: false }), + ); + }); }); diff --git a/src/commands/status.summary.ts b/src/commands/status.summary.ts index c235765b406..8911bee6caf 100644 --- a/src/commands/status.summary.ts +++ b/src/commands/status.summary.ts @@ -219,6 +219,9 @@ export async function getStatusSummary( model: configModel, contextTokensOverride: cfg.agents?.defaults?.contextTokens, fallbackContextTokens: DEFAULT_CONTEXT_TOKENS, + // Keep `status`/`status --json` startup read-only. These summary lookups + // should not kick off background provider discovery or plugin scans. + allowAsyncLoad: false, }) ?? DEFAULT_CONTEXT_TOKENS; const now = Date.now(); @@ -250,6 +253,7 @@ export async function getStatusSummary( model, contextTokensOverride: entry?.contextTokens, fallbackContextTokens: configContextTokens ?? undefined, + allowAsyncLoad: false, }) ?? null; const total = resolveFreshSessionTotalTokens(entry); const totalTokensFresh = From c38295c7a2503f8ddbbb5e954c623fbfed56ade4 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 16:28:00 -0700 Subject: [PATCH 51/69] test(ci): tighten startup memory thresholds --- scripts/check-cli-startup-memory.mjs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/check-cli-startup-memory.mjs b/scripts/check-cli-startup-memory.mjs index f2e8521961e..8f71965c7a4 100644 --- a/scripts/check-cli-startup-memory.mjs +++ b/scripts/check-cli-startup-memory.mjs @@ -32,9 +32,9 @@ writeFileSync( ); const DEFAULT_LIMITS_MB = { - help: 500, - statusJson: 925, - gatewayStatus: 900, + help: 100, + statusJson: 400, + gatewayStatus: 500, }; const cases = [ From aa172f2169aa2e013cf82510fe2debecf18c73fd Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 16:39:27 -0700 Subject: [PATCH 52/69] fix(matrix): keep runtime api import-safe --- extensions/matrix/runtime-api.ts | 4 ++-- extensions/matrix/src/matrix/thread-bindings.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/extensions/matrix/runtime-api.ts b/extensions/matrix/runtime-api.ts index 04957e707c5..1aaee387fc8 100644 --- a/extensions/matrix/runtime-api.ts +++ b/extensions/matrix/runtime-api.ts @@ -1,5 +1,5 @@ // Keep the external runtime API light so Jiti callers can resolve Matrix config -// helpers without traversing the full plugin-sdk/runtime graph. +// helpers without traversing the full plugin-sdk/runtime graph or bootstrapping +// matrix-js-sdk during plain runtime-api import. export * from "./src/auth-precedence.js"; export * from "./helper-api.js"; -export { sendMessageMatrix } from "./src/matrix/send.js"; diff --git a/extensions/matrix/src/matrix/thread-bindings.ts b/extensions/matrix/src/matrix/thread-bindings.ts index 593d88ed7eb..edbbde5d000 100644 --- a/extensions/matrix/src/matrix/thread-bindings.ts +++ b/extensions/matrix/src/matrix/thread-bindings.ts @@ -1,5 +1,4 @@ import path from "node:path"; -import { sendMessageMatrix } from "../../runtime-api.js"; import { readJsonFileWithFallback, registerSessionBindingAdapter, @@ -11,6 +10,7 @@ import { import { resolveMatrixStoragePaths } from "./client/storage.js"; import type { MatrixAuth } from "./client/types.js"; import type { MatrixClient } from "./sdk.js"; +import { sendMessageMatrix } from "./send.js"; import { deleteMatrixThreadBindingManagerEntry, getMatrixThreadBindingManager, From 41628770f5cee78e6247f23ce90d8c19f8127b14 Mon Sep 17 00:00:00 2001 From: Harold Hunt Date: Thu, 19 Mar 2026 19:53:02 -0400 Subject: [PATCH 53/69] Tests: trim command secret gateway imports (#50663) Merged via squash. Prepared head SHA: 7f64fd3ee17c3a7e5b7f26e618816497e94c5243 Co-authored-by: huntharo <5617868+huntharo@users.noreply.github.com> Co-authored-by: huntharo <5617868+huntharo@users.noreply.github.com> Reviewed-by: @huntharo --- CHANGELOG.md | 1 + src/cli/command-secret-gateway.test.ts | 9 +++++++++ 2 files changed, 10 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8de5d606931..0cf9b671096 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -167,6 +167,7 @@ Docs: https://docs.openclaw.ai - Plugins/WhatsApp: share split-load singleton state for plugin command registration and active WhatsApp listeners so duplicate module graphs no longer lose native plugin commands or outbound listener state. (#50418) Thanks @huntharo. - Onboarding/custom providers: keep Azure AI Foundry `*.services.ai.azure.com` custom endpoints on the selected compatibility path instead of forcing Responses, so chat-completions Foundry models still work after setup. Fixes #50528. (#50535) Thanks @obviyus. - Plugins/update: let `openclaw plugins update ` target tracked npm installs by dist-tag or exact version, and preserve the recorded npm spec for later id-based updates. (#49998) Thanks @huntharo. +- Tests/CLI: reduce command-secret gateway test import pressure while keeping the real protocol payload validator in place, so the isolated lane no longer carries the heavier runtime-web and message-channel graphs. (#50663) Thanks @huntharo. ### Breaking diff --git a/src/cli/command-secret-gateway.test.ts b/src/cli/command-secret-gateway.test.ts index a322b1853cd..38cedb54204 100644 --- a/src/cli/command-secret-gateway.test.ts +++ b/src/cli/command-secret-gateway.test.ts @@ -7,6 +7,15 @@ vi.mock("../gateway/call.js", () => ({ callGateway, })); +vi.mock("../secrets/runtime-web-tools.js", () => ({ + resolveRuntimeWebTools: vi.fn(async () => ({})), +})); + +vi.mock("../utils/message-channel.js", () => ({ + GATEWAY_CLIENT_MODES: { CLI: "cli" }, + GATEWAY_CLIENT_NAMES: { CLI: "cli" }, +})); + let resolveCommandSecretRefsViaGateway: typeof import("./command-secret-gateway.js").resolveCommandSecretRefsViaGateway; beforeAll(async () => { From d518260bb8261bb179cfb421a8c166915bb59dd1 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 16:54:16 -0700 Subject: [PATCH 54/69] fix(status): slim json startup path --- src/commands/status-json.test.ts | 118 +++++++++++ src/commands/status-json.ts | 22 +- src/commands/status.scan.fast-json.test.ts | 190 +++++++++++++++++ src/commands/status.scan.fast-json.ts | 6 +- src/commands/status.summary.runtime.ts | 225 ++++++++++++++++++++- src/commands/status.summary.test.ts | 30 +-- 6 files changed, 559 insertions(+), 32 deletions(-) create mode 100644 src/commands/status-json.test.ts create mode 100644 src/commands/status.scan.fast-json.test.ts diff --git a/src/commands/status-json.test.ts b/src/commands/status-json.test.ts new file mode 100644 index 00000000000..c51f073d062 --- /dev/null +++ b/src/commands/status-json.test.ts @@ -0,0 +1,118 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import type { RuntimeEnv } from "../runtime.js"; + +const mocks = vi.hoisted(() => ({ + scanStatusJsonFast: vi.fn(), + runSecurityAudit: vi.fn(), + loadProviderUsageSummary: vi.fn(), + callGateway: vi.fn(), + getDaemonStatusSummary: vi.fn(), + getNodeDaemonStatusSummary: vi.fn(), + normalizeUpdateChannel: vi.fn((value?: string | null) => value ?? null), + resolveUpdateChannelDisplay: vi.fn(() => ({ + channel: "stable", + source: "config", + })), +})); + +vi.mock("./status.scan.fast-json.js", () => ({ + scanStatusJsonFast: mocks.scanStatusJsonFast, +})); + +vi.mock("../security/audit.runtime.js", () => ({ + runSecurityAudit: mocks.runSecurityAudit, +})); + +vi.mock("../infra/provider-usage.js", () => ({ + loadProviderUsageSummary: mocks.loadProviderUsageSummary, +})); + +vi.mock("../gateway/call.js", () => ({ + callGateway: mocks.callGateway, +})); + +vi.mock("./status.daemon.js", () => ({ + getDaemonStatusSummary: mocks.getDaemonStatusSummary, + getNodeDaemonStatusSummary: mocks.getNodeDaemonStatusSummary, +})); + +vi.mock("../infra/update-channels.js", () => ({ + normalizeUpdateChannel: mocks.normalizeUpdateChannel, + resolveUpdateChannelDisplay: mocks.resolveUpdateChannelDisplay, +})); + +const { statusJsonCommand } = await import("./status-json.js"); + +function createRuntimeCapture() { + const logs: string[] = []; + const runtime: RuntimeEnv = { + log: vi.fn((value: unknown) => { + logs.push(String(value)); + }), + error: vi.fn(), + exit: vi.fn() as unknown as RuntimeEnv["exit"], + }; + return { runtime, logs }; +} + +function createScanResult() { + return { + cfg: { update: { channel: "stable" } }, + sourceConfig: {}, + summary: { ok: true, configuredChannels: [] }, + osSummary: { platform: "linux" }, + update: { installKind: "npm", git: { tag: null, branch: null } }, + memory: null, + memoryPlugin: null, + gatewayMode: "local", + gatewayConnection: { url: "ws://127.0.0.1:18789", urlSource: "config" }, + remoteUrlMissing: false, + gatewayReachable: false, + gatewayProbe: null, + gatewaySelf: null, + gatewayProbeAuthWarning: null, + agentStatus: [], + secretDiagnostics: [], + }; +} + +describe("statusJsonCommand", () => { + beforeEach(() => { + vi.clearAllMocks(); + mocks.scanStatusJsonFast.mockResolvedValue(createScanResult()); + mocks.runSecurityAudit.mockResolvedValue({ + summary: { critical: 1, warn: 0, info: 0 }, + findings: [], + }); + mocks.getDaemonStatusSummary.mockResolvedValue({ installed: false }); + mocks.getNodeDaemonStatusSummary.mockResolvedValue({ installed: false }); + mocks.loadProviderUsageSummary.mockResolvedValue({ providers: [] }); + mocks.callGateway.mockResolvedValue({}); + }); + + it("keeps plain status --json off the security audit fast path", async () => { + const { runtime, logs } = createRuntimeCapture(); + + await statusJsonCommand({}, runtime); + + expect(mocks.runSecurityAudit).not.toHaveBeenCalled(); + expect(logs).toHaveLength(1); + expect(JSON.parse(logs[0] ?? "{}")).not.toHaveProperty("securityAudit"); + }); + + it("includes security audit details only when --all is requested", async () => { + const { runtime, logs } = createRuntimeCapture(); + + await statusJsonCommand({ all: true }, runtime); + + expect(mocks.runSecurityAudit).toHaveBeenCalledWith({ + config: expect.any(Object), + sourceConfig: expect.any(Object), + deep: false, + includeFilesystem: true, + includeChannelSecurity: true, + }); + expect(logs).toHaveLength(1); + expect(JSON.parse(logs[0] ?? "{}")).toHaveProperty("securityAudit.summary.critical", 1); + }); +}); diff --git a/src/commands/status-json.ts b/src/commands/status-json.ts index e9221226665..2a004f4a231 100644 --- a/src/commands/status-json.ts +++ b/src/commands/status-json.ts @@ -33,15 +33,17 @@ export async function statusJsonCommand( runtime: RuntimeEnv, ) { const scan = await scanStatusJsonFast({ timeoutMs: opts.timeoutMs, all: opts.all }, runtime); - const securityAudit = await loadSecurityAuditModule().then(({ runSecurityAudit }) => - runSecurityAudit({ - config: scan.cfg, - sourceConfig: scan.sourceConfig, - deep: false, - includeFilesystem: true, - includeChannelSecurity: true, - }), - ); + const securityAudit = opts.all + ? await loadSecurityAuditModule().then(({ runSecurityAudit }) => + runSecurityAudit({ + config: scan.cfg, + sourceConfig: scan.sourceConfig, + deep: false, + includeFilesystem: true, + includeChannelSecurity: true, + }), + ) + : undefined; const usage = opts.usage ? await loadProviderUsage().then(({ loadProviderUsageSummary }) => @@ -105,8 +107,8 @@ export async function statusJsonCommand( gatewayService: daemon, nodeService: nodeDaemon, agents: scan.agentStatus, - securityAudit, secretDiagnostics: scan.secretDiagnostics, + ...(securityAudit ? { securityAudit } : {}), ...(health || usage || lastHeartbeat ? { health, usage, lastHeartbeat } : {}), }, null, diff --git a/src/commands/status.scan.fast-json.test.ts b/src/commands/status.scan.fast-json.test.ts new file mode 100644 index 00000000000..83bc1bd5341 --- /dev/null +++ b/src/commands/status.scan.fast-json.test.ts @@ -0,0 +1,190 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +const mocks = vi.hoisted(() => ({ + hasPotentialConfiguredChannels: vi.fn(), + readBestEffortConfig: vi.fn(), + resolveCommandSecretRefsViaGateway: vi.fn(), + getStatusCommandSecretTargetIds: vi.fn(() => []), + getUpdateCheckResult: vi.fn(), + getAgentLocalStatuses: vi.fn(), + getStatusSummary: vi.fn(), + resolveMemorySearchConfig: vi.fn(), + getMemorySearchManager: vi.fn(), + buildGatewayConnectionDetails: vi.fn(), + probeGateway: vi.fn(), + resolveGatewayProbeAuthResolution: vi.fn(), + ensurePluginRegistryLoaded: vi.fn(), + buildPluginCompatibilityNotices: vi.fn(() => []), +})); + +beforeEach(() => { + vi.clearAllMocks(); + mocks.hasPotentialConfiguredChannels.mockReturnValue(false); + mocks.readBestEffortConfig.mockResolvedValue({ + session: {}, + gateway: {}, + agents: { + defaults: { + memorySearch: { + provider: "local", + local: { modelPath: "/tmp/model.gguf" }, + fallback: "none", + }, + }, + }, + }); + mocks.resolveCommandSecretRefsViaGateway.mockResolvedValue({ + resolvedConfig: { + session: {}, + gateway: {}, + agents: { + defaults: { + memorySearch: { + provider: "local", + local: { modelPath: "/tmp/model.gguf" }, + fallback: "none", + }, + }, + }, + }, + diagnostics: [], + }); + mocks.getUpdateCheckResult.mockResolvedValue({ + installKind: "git", + git: null, + registry: null, + }); + mocks.getAgentLocalStatuses.mockResolvedValue({ + defaultId: "main", + agents: [], + }); + mocks.getStatusSummary.mockResolvedValue({ + linkChannel: undefined, + sessions: { count: 0, paths: [], defaults: {}, recent: [], byAgent: [] }, + }); + mocks.buildGatewayConnectionDetails.mockReturnValue({ + url: "ws://127.0.0.1:18789", + urlSource: "default", + }); + mocks.resolveGatewayProbeAuthResolution.mockReturnValue({ + auth: {}, + warning: undefined, + }); + mocks.probeGateway.mockResolvedValue({ + ok: false, + url: "ws://127.0.0.1:18789", + connectLatencyMs: null, + error: "timeout", + close: null, + health: null, + status: null, + presence: null, + configSnapshot: null, + }); + mocks.resolveMemorySearchConfig.mockReturnValue({ + store: { path: "/tmp/main.sqlite" }, + }); + mocks.getMemorySearchManager.mockResolvedValue({ + manager: { + probeVectorAvailability: vi.fn(async () => true), + status: vi.fn(() => ({ files: 0, chunks: 0, dirty: false })), + close: vi.fn(async () => {}), + }, + }); +}); + +vi.mock("../channels/config-presence.js", () => ({ + hasPotentialConfiguredChannels: mocks.hasPotentialConfiguredChannels, +})); + +vi.mock("../config/io.js", () => ({ + readBestEffortConfig: mocks.readBestEffortConfig, +})); + +vi.mock("../cli/command-secret-gateway.js", () => ({ + resolveCommandSecretRefsViaGateway: mocks.resolveCommandSecretRefsViaGateway, +})); + +vi.mock("../cli/command-secret-targets.js", () => ({ + getStatusCommandSecretTargetIds: mocks.getStatusCommandSecretTargetIds, +})); + +vi.mock("./status.update.js", () => ({ + getUpdateCheckResult: mocks.getUpdateCheckResult, +})); + +vi.mock("./status.agent-local.js", () => ({ + getAgentLocalStatuses: mocks.getAgentLocalStatuses, +})); + +vi.mock("./status.summary.js", () => ({ + getStatusSummary: mocks.getStatusSummary, +})); + +vi.mock("../infra/os-summary.js", () => ({ + resolveOsSummary: vi.fn(() => ({ label: "test-os" })), +})); + +vi.mock("./status.scan.deps.runtime.js", () => ({ + getTailnetHostname: vi.fn(), + getMemorySearchManager: mocks.getMemorySearchManager, +})); + +vi.mock("../agents/memory-search.js", () => ({ + resolveMemorySearchConfig: mocks.resolveMemorySearchConfig, +})); + +vi.mock("../gateway/call.js", () => ({ + buildGatewayConnectionDetails: mocks.buildGatewayConnectionDetails, +})); + +vi.mock("../gateway/probe.js", () => ({ + probeGateway: mocks.probeGateway, +})); + +vi.mock("./status.gateway-probe.js", () => ({ + pickGatewaySelfPresence: vi.fn(() => null), + resolveGatewayProbeAuthResolution: mocks.resolveGatewayProbeAuthResolution, +})); + +vi.mock("../process/exec.js", () => ({ + runExec: vi.fn(), +})); + +vi.mock("../cli/plugin-registry.js", () => ({ + ensurePluginRegistryLoaded: mocks.ensurePluginRegistryLoaded, +})); + +vi.mock("../plugins/status.js", () => ({ + buildPluginCompatibilityNotices: mocks.buildPluginCompatibilityNotices, +})); + +const { scanStatusJsonFast } = await import("./status.scan.fast-json.js"); + +describe("scanStatusJsonFast", () => { + it("skips memory inspection for the lean status --json fast path", async () => { + const result = await scanStatusJsonFast({}, {} as never); + + expect(result.memory).toBeNull(); + expect(mocks.resolveMemorySearchConfig).not.toHaveBeenCalled(); + expect(mocks.getMemorySearchManager).not.toHaveBeenCalled(); + }); + + it("restores memory inspection when --all is requested", async () => { + const result = await scanStatusJsonFast({ all: true }, {} as never); + + expect(result.memory).toEqual(expect.objectContaining({ agentId: "main" })); + expect(mocks.resolveMemorySearchConfig).toHaveBeenCalled(); + expect(mocks.getMemorySearchManager).toHaveBeenCalledWith({ + cfg: expect.objectContaining({ + agents: expect.objectContaining({ + defaults: expect.objectContaining({ + memorySearch: expect.any(Object), + }), + }), + }), + agentId: "main", + purpose: "status", + }); + }); +}); diff --git a/src/commands/status.scan.fast-json.ts b/src/commands/status.scan.fast-json.ts index 267a7200739..2e1788b2b16 100644 --- a/src/commands/status.scan.fast-json.ts +++ b/src/commands/status.scan.fast-json.ts @@ -197,7 +197,11 @@ export async function scanStatusJsonFast( ? pickGatewaySelfPresence(gatewayProbe.presence) : null; const memoryPlugin = resolveMemoryPluginStatus(cfg); - const memory = await resolveMemoryStatusSnapshot({ cfg, agentStatus, memoryPlugin }); + // Keep the lean `status --json` route off the memory manager/runtime graph. + // Deep memory inspection is still available on the explicit `--all` path. + const memory = opts.all + ? await resolveMemoryStatusSnapshot({ cfg, agentStatus, memoryPlugin }) + : null; const pluginCompatibility = shouldCollectPluginCompatibility(cfg) ? await loadPluginStatusModule().then(({ buildPluginCompatibilityNotices }) => // Keep plugin status loading off the empty-config `status --json` fast path. diff --git a/src/commands/status.summary.runtime.ts b/src/commands/status.summary.runtime.ts index e4b08a49856..1c18b907b00 100644 --- a/src/commands/status.summary.runtime.ts +++ b/src/commands/status.summary.runtime.ts @@ -1,5 +1,226 @@ -import { resolveContextTokensForModel } from "../agents/context.js"; -import { classifySessionKey, resolveSessionModelRef } from "../gateway/session-utils.js"; +import { DEFAULT_CONTEXT_TOKENS, DEFAULT_MODEL, DEFAULT_PROVIDER } from "../agents/defaults.js"; +import { resolveAgentModelPrimaryValue } from "../config/model-input.js"; +import type { SessionEntry } from "../config/sessions/types.js"; +import type { OpenClawConfig } from "../config/types.js"; + +function parseStatusModelRef( + raw: string, + defaultProvider: string, +): { provider: string; model: string } | null { + const trimmed = raw.trim(); + if (!trimmed) { + return null; + } + const slash = trimmed.indexOf("/"); + if (slash === -1) { + return { provider: defaultProvider, model: trimmed }; + } + const provider = trimmed.slice(0, slash).trim(); + const model = trimmed.slice(slash + 1).trim(); + if (!provider || !model) { + return null; + } + return { provider, model }; +} + +function resolveStatusModelRefFromRaw(params: { + cfg: OpenClawConfig; + rawModel: string; + defaultProvider: string; +}): { provider: string; model: string } | null { + const trimmed = params.rawModel.trim(); + if (!trimmed) { + return null; + } + const configuredModels = params.cfg.agents?.defaults?.models ?? {}; + if (!trimmed.includes("/")) { + const aliasKey = trimmed.toLowerCase(); + for (const [modelKey, entry] of Object.entries(configuredModels)) { + const aliasValue = (entry as { alias?: unknown } | undefined)?.alias; + const alias = typeof aliasValue === "string" ? aliasValue.trim() : ""; + if (!alias || alias.toLowerCase() !== aliasKey) { + continue; + } + const parsed = parseStatusModelRef(modelKey, params.defaultProvider); + if (parsed) { + return parsed; + } + } + return { provider: "anthropic", model: trimmed }; + } + return parseStatusModelRef(trimmed, params.defaultProvider); +} + +function resolveConfiguredStatusModelRef(params: { + cfg: OpenClawConfig; + defaultProvider: string; + defaultModel: string; + agentId?: string; +}): { provider: string; model: string } { + const agentRawModel = params.agentId + ? resolveAgentModelPrimaryValue( + params.cfg.agents?.list?.find((entry) => entry?.id === params.agentId)?.model, + ) + : undefined; + if (agentRawModel) { + const parsed = resolveStatusModelRefFromRaw({ + cfg: params.cfg, + rawModel: agentRawModel, + defaultProvider: params.defaultProvider, + }); + if (parsed) { + return parsed; + } + } + + const defaultsRawModel = resolveAgentModelPrimaryValue(params.cfg.agents?.defaults?.model); + if (defaultsRawModel) { + const parsed = resolveStatusModelRefFromRaw({ + cfg: params.cfg, + rawModel: defaultsRawModel, + defaultProvider: params.defaultProvider, + }); + if (parsed) { + return parsed; + } + } + + const configuredProviders = params.cfg.models?.providers; + if (configuredProviders && typeof configuredProviders === "object") { + const hasDefaultProvider = Boolean(configuredProviders[params.defaultProvider]); + if (!hasDefaultProvider) { + const availableProvider = Object.entries(configuredProviders).find( + ([, providerCfg]) => + providerCfg && + Array.isArray(providerCfg.models) && + providerCfg.models.length > 0 && + providerCfg.models[0]?.id, + ); + if (availableProvider) { + const [providerName, providerCfg] = availableProvider; + return { provider: providerName, model: providerCfg.models[0].id }; + } + } + } + + return { provider: params.defaultProvider, model: params.defaultModel }; +} + +function resolveConfiguredProviderContextWindow( + cfg: OpenClawConfig | undefined, + provider: string, + model: string, +): number | undefined { + const providers = cfg?.models?.providers; + if (!providers || typeof providers !== "object") { + return undefined; + } + const providerKey = provider.trim().toLowerCase(); + for (const [id, providerConfig] of Object.entries(providers)) { + if (id.trim().toLowerCase() !== providerKey || !Array.isArray(providerConfig?.models)) { + continue; + } + for (const entry of providerConfig.models) { + if ( + typeof entry?.id === "string" && + entry.id === model && + typeof entry.contextWindow === "number" && + entry.contextWindow > 0 + ) { + return entry.contextWindow; + } + } + } + return undefined; +} + +function classifySessionKey(key: string, entry?: SessionEntry) { + if (key === "global") { + return "global"; + } + if (key === "unknown") { + return "unknown"; + } + if (entry?.chatType === "group" || entry?.chatType === "channel") { + return "group"; + } + if (key.includes(":group:") || key.includes(":channel:")) { + return "group"; + } + return "direct"; +} + +function resolveSessionModelRef( + cfg: OpenClawConfig, + entry?: + | SessionEntry + | Pick, + agentId?: string, +): { provider: string; model: string } { + const resolved = resolveConfiguredStatusModelRef({ + cfg, + defaultProvider: DEFAULT_PROVIDER, + defaultModel: DEFAULT_MODEL, + agentId, + }); + + let provider = resolved.provider; + let model = resolved.model; + const runtimeModel = entry?.model?.trim(); + const runtimeProvider = entry?.modelProvider?.trim(); + if (runtimeModel) { + if (runtimeProvider) { + return { provider: runtimeProvider, model: runtimeModel }; + } + const parsedRuntime = parseStatusModelRef(runtimeModel, provider || DEFAULT_PROVIDER); + if (parsedRuntime) { + provider = parsedRuntime.provider; + model = parsedRuntime.model; + } else { + model = runtimeModel; + } + return { provider, model }; + } + + const storedModelOverride = entry?.modelOverride?.trim(); + if (storedModelOverride) { + const overrideProvider = entry?.providerOverride?.trim() || provider || DEFAULT_PROVIDER; + const parsedOverride = parseStatusModelRef(storedModelOverride, overrideProvider); + if (parsedOverride) { + provider = parsedOverride.provider; + model = parsedOverride.model; + } else { + provider = overrideProvider; + model = storedModelOverride; + } + } + return { provider, model }; +} + +function resolveContextTokensForModel(params: { + cfg?: OpenClawConfig; + provider?: string; + model?: string; + contextTokensOverride?: number; + fallbackContextTokens?: number; + allowAsyncLoad?: boolean; +}): number | undefined { + void params.allowAsyncLoad; + if (typeof params.contextTokensOverride === "number" && params.contextTokensOverride > 0) { + return params.contextTokensOverride; + } + if (params.provider && params.model) { + const configuredWindow = resolveConfiguredProviderContextWindow( + params.cfg, + params.provider, + params.model, + ); + if (configuredWindow !== undefined) { + return configuredWindow; + } + } + return params.fallbackContextTokens ?? DEFAULT_CONTEXT_TOKENS; +} export const statusSummaryRuntime = { resolveContextTokensForModel, diff --git a/src/commands/status.summary.test.ts b/src/commands/status.summary.test.ts index c441ce1d879..15ed07afc9f 100644 --- a/src/commands/status.summary.test.ts +++ b/src/commands/status.summary.test.ts @@ -4,8 +4,15 @@ vi.mock("../channels/config-presence.js", () => ({ hasPotentialConfiguredChannels: vi.fn(() => true), })); -vi.mock("../agents/context.js", () => ({ - resolveContextTokensForModel: vi.fn(() => 200_000), +vi.mock("./status.summary.runtime.js", () => ({ + statusSummaryRuntime: { + classifySessionKey: vi.fn(() => "direct"), + resolveSessionModelRef: vi.fn(() => ({ + provider: "openai", + model: "gpt-5.2", + })), + resolveContextTokensForModel: vi.fn(() => 200_000), + }, })); vi.mock("../agents/defaults.js", () => ({ @@ -14,13 +21,6 @@ vi.mock("../agents/defaults.js", () => ({ DEFAULT_PROVIDER: "openai", })); -vi.mock("../agents/model-selection.js", () => ({ - resolveConfiguredModelRef: vi.fn(() => ({ - provider: "openai", - model: "gpt-5.2", - })), -})); - vi.mock("../config/config.js", () => ({ loadConfig: vi.fn(() => ({})), })); @@ -39,14 +39,6 @@ vi.mock("../gateway/agent-list.js", () => ({ })), })); -vi.mock("../gateway/session-utils.js", () => ({ - classifySessionKey: vi.fn(() => "direct"), - resolveSessionModelRef: vi.fn(() => ({ - provider: "openai", - model: "gpt-5.2", - })), -})); - vi.mock("../infra/channel-summary.js", () => ({ buildChannelSummary: vi.fn(async () => ["ok"]), })); @@ -78,9 +70,9 @@ vi.mock("./status.link-channel.js", () => ({ })); const { hasPotentialConfiguredChannels } = await import("../channels/config-presence.js"); -const { resolveContextTokensForModel } = await import("../agents/context.js"); const { buildChannelSummary } = await import("../infra/channel-summary.js"); const { resolveLinkChannelContext } = await import("./status.link-channel.js"); +const { statusSummaryRuntime } = await import("./status.summary.runtime.js"); const { getStatusSummary } = await import("./status.summary.js"); describe("getStatusSummary", () => { @@ -110,7 +102,7 @@ describe("getStatusSummary", () => { it("does not trigger async context warmup while building status summaries", async () => { await getStatusSummary(); - expect(vi.mocked(resolveContextTokensForModel)).toHaveBeenCalledWith( + expect(vi.mocked(statusSummaryRuntime.resolveContextTokensForModel)).toHaveBeenCalledWith( expect.objectContaining({ allowAsyncLoad: false }), ); }); From a953cb5209bac60d369e9261ab017a1e4e17d431 Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Thu, 19 Mar 2026 20:53:35 -0400 Subject: [PATCH 55/69] Matrix: fix runtime API duplicate exports --- extensions/matrix/src/runtime-api.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/extensions/matrix/src/runtime-api.ts b/extensions/matrix/src/runtime-api.ts index 3c447f50e2f..babc32f50c8 100644 --- a/extensions/matrix/src/runtime-api.ts +++ b/extensions/matrix/src/runtime-api.ts @@ -1,2 +1,4 @@ export * from "openclaw/plugin-sdk/matrix"; -export * from "../runtime-api.js"; +// Keep auth-precedence available internally without re-exporting helper-api +// twice through both plugin-sdk/matrix and ../runtime-api.js. +export * from "./auth-precedence.js"; From 6309b1da6c2e1e3eaaf514b8a41ac83436e56e12 Mon Sep 17 00:00:00 2001 From: joshavant <830519+joshavant@users.noreply.github.com> Date: Thu, 19 Mar 2026 19:57:45 -0500 Subject: [PATCH 56/69] Gateway: preserve interactive pairing visibility on supersede --- src/infra/device-pairing.test.ts | 30 ++++++++++++++++++++++++++++++ src/infra/device-pairing.ts | 19 ++++++++++++++++++- 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/src/infra/device-pairing.test.ts b/src/infra/device-pairing.test.ts index b1805145cf8..4f914a51746 100644 --- a/src/infra/device-pairing.test.ts +++ b/src/infra/device-pairing.test.ts @@ -162,6 +162,36 @@ describe("device pairing tokens", () => { expect(paired?.scopes).toEqual(["operator.read", "operator.write"]); }); + test("keeps superseded requests interactive when an existing pending request is interactive", async () => { + const baseDir = await mkdtemp(join(tmpdir(), "openclaw-device-pairing-")); + const first = await requestDevicePairing( + { + deviceId: "device-1", + publicKey: "public-key-1", + role: "node", + scopes: [], + silent: false, + }, + baseDir, + ); + expect(first.request.silent).toBe(false); + + const second = await requestDevicePairing( + { + deviceId: "device-1", + publicKey: "public-key-1", + role: "operator", + scopes: ["operator.read"], + silent: true, + }, + baseDir, + ); + + expect(second.created).toBe(true); + expect(second.request.requestId).not.toBe(first.request.requestId); + expect(second.request.silent).toBe(false); + }); + test("rejects bootstrap token replay before pending scope escalation can be approved", async () => { const baseDir = await mkdtemp(join(tmpdir(), "openclaw-device-pairing-")); const issued = await issueDeviceBootstrapToken({ baseDir }); diff --git a/src/infra/device-pairing.ts b/src/infra/device-pairing.ts index b51ae0db67a..619e88974c9 100644 --- a/src/infra/device-pairing.ts +++ b/src/infra/device-pairing.ts @@ -236,6 +236,15 @@ function refreshPendingDevicePairingRequest( }; } +function resolveSupersededPendingSilent(params: { + existing: readonly DevicePairingPendingRequest[]; + incomingSilent: boolean | undefined; +}): boolean { + return Boolean( + params.incomingSilent && params.existing.every((pending) => pending.silent === true), + ); +} + function buildPendingDevicePairingRequest(params: { requestId?: string; deviceId: string; @@ -394,7 +403,15 @@ export async function requestDevicePairing( const superseded = buildPendingDevicePairingRequest({ deviceId, isRepair, - req, + req: { + ...req, + // Preserve interactive visibility when superseding pending requests: + // if any previous pending request was interactive, keep this one interactive. + silent: resolveSupersededPendingSilent({ + existing: pendingForDevice, + incomingSilent: req.silent, + }), + }, }); state.pendingById[superseded.requestId] = superseded; await persistState(state, baseDir); From c95d1c101b3424db2c8be5ba8d71bf4ddf96e111 Mon Sep 17 00:00:00 2001 From: Shakker Date: Fri, 20 Mar 2026 01:09:45 +0000 Subject: [PATCH 57/69] fix(cron): avoid async context token warmup in isolated runs --- src/cron/isolated-agent/run.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/cron/isolated-agent/run.ts b/src/cron/isolated-agent/run.ts index 3933c9ff7c6..1a122f56864 100644 --- a/src/cron/isolated-agent/run.ts +++ b/src/cron/isolated-agent/run.ts @@ -748,7 +748,9 @@ export async function runCronIsolatedAgentTurn(params: { const modelUsed = finalRunResult.meta?.agentMeta?.model ?? fallbackModel ?? model; const providerUsed = finalRunResult.meta?.agentMeta?.provider ?? fallbackProvider ?? provider; const contextTokens = - agentCfg?.contextTokens ?? lookupContextTokens(modelUsed) ?? DEFAULT_CONTEXT_TOKENS; + agentCfg?.contextTokens ?? + lookupContextTokens(modelUsed, { allowAsyncLoad: false }) ?? + DEFAULT_CONTEXT_TOKENS; setSessionRuntimeModel(cronSession.sessionEntry, { provider: providerUsed, From 55e12bd2365c9e2b61f1694e0c1ffd5aee98c8f6 Mon Sep 17 00:00:00 2001 From: Shakker Date: Fri, 20 Mar 2026 01:10:11 +0000 Subject: [PATCH 58/69] fix(plugins): stabilize bundle MCP path assertions --- src/plugins/bundle-mcp.test.ts | 62 ++++++++++++++++++++++++++-------- 1 file changed, 48 insertions(+), 14 deletions(-) diff --git a/src/plugins/bundle-mcp.test.ts b/src/plugins/bundle-mcp.test.ts index b9d5ca18cf3..7526739701a 100644 --- a/src/plugins/bundle-mcp.test.ts +++ b/src/plugins/bundle-mcp.test.ts @@ -11,6 +11,23 @@ function getServerArgs(value: unknown): unknown[] | undefined { return isRecord(value) && Array.isArray(value.args) ? value.args : undefined; } +function normalizePathForAssertion(value: string | undefined): string | undefined { + if (!value) { + return value; + } + return path.normalize(value).replace(/\\/g, "/"); +} + +async function expectResolvedPathEqual(actual: unknown, expected: string): Promise { + expect(typeof actual).toBe("string"); + if (typeof actual !== "string") { + return; + } + expect(normalizePathForAssertion(await fs.realpath(actual))).toBe( + normalizePathForAssertion(await fs.realpath(expected)), + ); +} + const tempHarness = createBundleMcpTempHarness(); afterEach(async () => { @@ -55,8 +72,10 @@ describe("loadEnabledBundleMcpConfig", () => { if (!loadedServerPath) { throw new Error("expected bundled MCP args to include the server path"); } - expect(await fs.realpath(loadedServerPath)).toBe(resolvedServerPath); - expect(loadedServer.cwd).toBe(resolvedPluginRoot); + expect(normalizePathForAssertion(await fs.realpath(loadedServerPath))).toBe( + normalizePathForAssertion(resolvedServerPath), + ); + await expectResolvedPathEqual(loadedServer.cwd, resolvedPluginRoot); } finally { env.restore(); } @@ -178,20 +197,35 @@ describe("loadEnabledBundleMcpConfig", () => { }, }, }); - const resolvedPluginRoot = await fs.realpath(pluginRoot); + const loadedServer = loaded.config.mcpServers.inlineProbe; + const loadedArgs = getServerArgs(loadedServer); + const loadedCommand = isRecord(loadedServer) ? loadedServer.command : undefined; + const loadedCwd = isRecord(loadedServer) ? loadedServer.cwd : undefined; + const loadedEnv = + isRecord(loadedServer) && isRecord(loadedServer.env) ? loadedServer.env : {}; expect(loaded.diagnostics).toEqual([]); - expect(loaded.config.mcpServers.inlineProbe).toEqual({ - command: path.join(resolvedPluginRoot, "bin", "server.sh"), - args: [ - path.join(resolvedPluginRoot, "servers", "probe.mjs"), - path.join(resolvedPluginRoot, "local-probe.mjs"), - ], - cwd: resolvedPluginRoot, - env: { - PLUGIN_ROOT: resolvedPluginRoot, - }, - }); + await expectResolvedPathEqual(loadedCwd, pluginRoot); + expect(typeof loadedCommand).toBe("string"); + expect(loadedArgs).toHaveLength(2); + expect(typeof loadedEnv.PLUGIN_ROOT).toBe("string"); + if (typeof loadedCommand !== "string" || typeof loadedCwd !== "string") { + throw new Error("expected inline bundled MCP server to expose command and cwd"); + } + expect(normalizePathForAssertion(path.relative(loadedCwd, loadedCommand))).toBe( + normalizePathForAssertion(path.join("bin", "server.sh")), + ); + expect( + loadedArgs?.map((entry) => + typeof entry === "string" + ? normalizePathForAssertion(path.relative(loadedCwd, entry)) + : entry, + ), + ).toEqual([ + normalizePathForAssertion(path.join("servers", "probe.mjs")), + normalizePathForAssertion("local-probe.mjs"), + ]); + await expectResolvedPathEqual(loadedEnv.PLUGIN_ROOT, pluginRoot); } finally { env.restore(); } From ac18a734acb23a9283cba70a6375c0c5db8ece0f Mon Sep 17 00:00:00 2001 From: Shakker Date: Fri, 20 Mar 2026 01:36:12 +0000 Subject: [PATCH 59/69] fix(ci): cap top-level test lane concurrency --- scripts/test-parallel.mjs | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/scripts/test-parallel.mjs b/scripts/test-parallel.mjs index da1d5b4c903..38dea1b2ead 100644 --- a/scripts/test-parallel.mjs +++ b/scripts/test-parallel.mjs @@ -586,6 +586,22 @@ const topLevelParallelEnabled = testProfile !== "serial" && !(!isCI && nodeMajor >= 25) && !isMacMiniProfile; +const defaultTopLevelParallelLimit = + testProfile === "serial" + ? 1 + : testProfile === "low" + ? 2 + : testProfile === "max" + ? 5 + : highMemLocalHost + ? 4 + : lowMemLocalHost + ? 2 + : 3; +const topLevelParallelLimit = Math.max( + 1, + parseEnvNumber("OPENCLAW_TEST_TOP_LEVEL_CONCURRENCY", defaultTopLevelParallelLimit), +); const overrideWorkers = Number.parseInt(process.env.OPENCLAW_TEST_WORKERS ?? "", 10); const resolvedOverride = Number.isFinite(overrideWorkers) && overrideWorkers > 0 ? overrideWorkers : null; @@ -1079,8 +1095,10 @@ const runEntriesWithLimit = async (entries, extraArgs = [], concurrency = 1) => const runEntries = async (entries, extraArgs = []) => { if (topLevelParallelEnabled) { - const codes = await Promise.all(entries.map((entry) => run(entry, extraArgs))); - return codes.find((code) => code !== 0); + // Keep a bounded number of top-level Vitest processes in flight. As the + // singleton lane list grows, unbounded Promise.all scheduling turns + // isolation into cross-process contention and can reintroduce timeouts. + return runEntriesWithLimit(entries, extraArgs, topLevelParallelLimit); } return runEntriesWithLimit(entries, extraArgs); From f91fad1710608e0bbe0520dffe19e1653d7b1aae Mon Sep 17 00:00:00 2001 From: Shakker Date: Fri, 20 Mar 2026 01:36:39 +0000 Subject: [PATCH 60/69] fix(ci): isolate high-heap unit suites from unit-fast --- test/fixtures/test-parallel.behavior.json | 64 +++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/test/fixtures/test-parallel.behavior.json b/test/fixtures/test-parallel.behavior.json index df7b3939027..7c1ba408e08 100644 --- a/test/fixtures/test-parallel.behavior.json +++ b/test/fixtures/test-parallel.behavior.json @@ -110,6 +110,70 @@ { "file": "src/memory/manager.readonly-recovery.test.ts", "reason": "Readonly recovery coverage exercises sqlite reopen flows and is safer outside shared unit-fast forks." + }, + { + "file": "src/acp/persistent-bindings.test.ts", + "reason": "Persistent bindings coverage retained a large unit-fast heap spike on Linux CI and is safer outside the shared lane." + }, + { + "file": "src/channels/plugins/setup-wizard-helpers.test.ts", + "reason": "Setup wizard helper coverage retained the largest shared unit-fast heap spike on Linux Node 24 CI." + }, + { + "file": "src/cli/config-cli.integration.test.ts", + "reason": "Config CLI integration coverage retained a large shared unit-fast heap spike on Linux CI." + }, + { + "file": "src/cli/config-cli.test.ts", + "reason": "Config CLI coverage retained a large shared unit-fast heap spike on Linux Node 24 CI." + }, + { + "file": "src/cli/plugins-cli.test.ts", + "reason": "Plugins CLI coverage retained a broad plugin graph in shared unit-fast forks on Linux CI." + }, + { + "file": "src/config/plugin-auto-enable.test.ts", + "reason": "Plugin auto-enable coverage retained a large shared unit-fast heap spike on Linux Node 22 CI." + }, + { + "file": "src/cron/isolated-agent/run.sandbox-config-preserved.test.ts", + "reason": "Isolated-agent sandbox config coverage retained a large shared unit-fast heap spike on Linux CI." + }, + { + "file": "src/cron/store.test.ts", + "reason": "Cron store coverage retained a large shared unit-fast heap spike on Linux Node 24 CI." + }, + { + "file": "src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts", + "reason": "Heartbeat ack max chars coverage retained a recurring shared unit-fast heap spike across Linux CI lanes." + }, + { + "file": "src/infra/heartbeat-runner.returns-default-unset.test.ts", + "reason": "Heartbeat default-unset coverage retained a large shared unit-fast heap spike on Linux Node 22 CI." + }, + { + "file": "src/infra/outbound/outbound-session.test.ts", + "reason": "Outbound session coverage retained a large shared unit-fast heap spike on Linux Node 22 CI." + }, + { + "file": "src/infra/outbound/payloads.test.ts", + "reason": "Outbound payload coverage retained a large shared unit-fast heap spike on Linux Node 24 CI." + }, + { + "file": "src/memory/manager.mistral-provider.test.ts", + "reason": "Mistral provider coverage retained a large shared unit-fast heap spike on Linux Node 24 CI." + }, + { + "file": "src/memory/qmd-manager.test.ts", + "reason": "QMD manager coverage retained recurring shared unit-fast heap spikes across Linux CI lanes." + }, + { + "file": "src/plugins/contracts/auth.contract.test.ts", + "reason": "Plugin auth contract coverage retained a large shared unit-fast heap spike on Linux Node 24 CI." + }, + { + "file": "src/secrets/apply.test.ts", + "reason": "Secrets apply coverage retained a large shared unit-fast heap spike on Linux Node 22 CI." } ], "threadSingleton": [ From a19f0581459002ae0e496fa4a1982c1ad23932be Mon Sep 17 00:00:00 2001 From: Shakker Date: Fri, 20 Mar 2026 01:45:20 +0000 Subject: [PATCH 61/69] fix(test): mock zalouser runtime in outbound payload contract --- .../outbound-payload.contract.test.ts | 42 ++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/src/channels/plugins/contracts/outbound-payload.contract.test.ts b/src/channels/plugins/contracts/outbound-payload.contract.test.ts index 5faa47893cb..761d1274091 100644 --- a/src/channels/plugins/contracts/outbound-payload.contract.test.ts +++ b/src/channels/plugins/contracts/outbound-payload.contract.test.ts @@ -3,7 +3,6 @@ import { discordOutbound } from "../../../../extensions/discord/src/outbound-ada import { whatsappOutbound } from "../../../../extensions/whatsapp/src/outbound-adapter.js"; import { zaloPlugin } from "../../../../extensions/zalo/src/channel.js"; import { sendMessageZalo } from "../../../../extensions/zalo/src/send.js"; -import "./../../../../extensions/zalouser/src/accounts.test-mocks.js"; import { zalouserPlugin } from "../../../../extensions/zalouser/src/channel.js"; import { setZalouserRuntime } from "../../../../extensions/zalouser/src/runtime.js"; import { sendMessageZalouser } from "../../../../extensions/zalouser/src/send.js"; @@ -19,6 +18,47 @@ vi.mock("../../../../extensions/zalo/src/send.js", () => ({ sendMessageZalo: vi.fn().mockResolvedValue({ ok: true, messageId: "zl-1" }), })); +// This suite only validates payload adaptation. Keep zalouser's runtime-only +// ZCA import graph mocked so local contract runs don't depend on native socket +// deps being resolved through the extension runtime seam. +vi.mock("../../../../extensions/zalouser/src/accounts.js", () => ({ + listZalouserAccountIds: vi.fn(() => ["default"]), + resolveDefaultZalouserAccountId: vi.fn(() => "default"), + resolveZalouserAccountSync: vi.fn(() => ({ + accountId: "default", + profile: "default", + name: "test", + enabled: true, + authenticated: true, + config: {}, + })), + getZcaUserInfo: vi.fn(async () => null), + checkZcaAuthenticated: vi.fn(async () => false), +})); + +vi.mock("../../../../extensions/zalouser/src/zalo-js.js", () => ({ + checkZaloAuthenticated: vi.fn(async () => false), + getZaloUserInfo: vi.fn(async () => null), + listZaloFriendsMatching: vi.fn(async () => []), + listZaloGroupMembers: vi.fn(async () => []), + listZaloGroupsMatching: vi.fn(async () => []), + logoutZaloProfile: vi.fn(async () => {}), + resolveZaloAllowFromEntries: vi.fn(async ({ entries }: { entries: string[] }) => + entries.map((entry) => ({ input: entry, resolved: true, id: entry, note: undefined })), + ), + resolveZaloGroupsByEntries: vi.fn(async ({ entries }: { entries: string[] }) => + entries.map((entry) => ({ input: entry, resolved: true, id: entry, note: undefined })), + ), + startZaloQrLogin: vi.fn(async () => ({ + message: "qr pending", + qrDataUrl: undefined, + })), + waitForZaloQrLogin: vi.fn(async () => ({ + connected: false, + message: "login pending", + })), +})); + vi.mock("../../../../extensions/zalouser/src/send.js", () => ({ sendMessageZalouser: vi.fn().mockResolvedValue({ ok: true, messageId: "zlu-1" }), sendReactionZalouser: vi.fn().mockResolvedValue({ ok: true }), From e0099202564034f60c4ab3ea6f04cf22e776d0cc Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 18:48:29 -0700 Subject: [PATCH 62/69] fix(ci): isolate remaining stale OOM hotspots --- test/fixtures/test-parallel.behavior.json | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/test/fixtures/test-parallel.behavior.json b/test/fixtures/test-parallel.behavior.json index 7c1ba408e08..c7349987f39 100644 --- a/test/fixtures/test-parallel.behavior.json +++ b/test/fixtures/test-parallel.behavior.json @@ -135,6 +135,10 @@ "file": "src/config/plugin-auto-enable.test.ts", "reason": "Plugin auto-enable coverage retained a large shared unit-fast heap spike on Linux Node 22 CI." }, + { + "file": "src/cron/service.runs-one-shot-main-job-disables-it.test.ts", + "reason": "One-shot cron service coverage retained a top shared unit-fast heap spike in the March 19, 2026 Linux Node 22 OOM lane." + }, { "file": "src/cron/isolated-agent/run.sandbox-config-preserved.test.ts", "reason": "Isolated-agent sandbox config coverage retained a large shared unit-fast heap spike on Linux CI." @@ -143,6 +147,10 @@ "file": "src/cron/store.test.ts", "reason": "Cron store coverage retained a large shared unit-fast heap spike on Linux Node 24 CI." }, + { + "file": "src/infra/exec-approval-forwarder.test.ts", + "reason": "Exec approval forwarder coverage retained a top shared unit-fast heap spike in the March 19, 2026 Linux Node 22 OOM lane." + }, { "file": "src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts", "reason": "Heartbeat ack max chars coverage retained a recurring shared unit-fast heap spike across Linux CI lanes." From cf2a66b5087b7fd2da50799bfbb1cb9b7eaf384c Mon Sep 17 00:00:00 2001 From: Shakker Date: Fri, 20 Mar 2026 01:50:53 +0000 Subject: [PATCH 63/69] chore(docs): refresh generated config baseline --- docs/.generated/config-baseline.json | 166 ++++++++++++++++++++++++++ docs/.generated/config-baseline.jsonl | 17 ++- 2 files changed, 182 insertions(+), 1 deletion(-) diff --git a/docs/.generated/config-baseline.json b/docs/.generated/config-baseline.json index ec8c22e0627..17cc0a44d72 100644 --- a/docs/.generated/config-baseline.json +++ b/docs/.generated/config-baseline.json @@ -22101,6 +22101,34 @@ "tags": [], "hasChildren": false }, + { + "path": "channels.matrix.ackReaction", + "kind": "channel", + "type": "string", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, + { + "path": "channels.matrix.ackReactionScope", + "kind": "channel", + "type": "string", + "required": false, + "enumValues": [ + "group-mentions", + "group-all", + "direct", + "all", + "none", + "off" + ], + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, { "path": "channels.matrix.actions", "kind": "channel", @@ -22151,6 +22179,16 @@ "tags": [], "hasChildren": false }, + { + "path": "channels.matrix.actions.profile", + "kind": "channel", + "type": "boolean", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, { "path": "channels.matrix.actions.reactions", "kind": "channel", @@ -22161,6 +22199,16 @@ "tags": [], "hasChildren": false }, + { + "path": "channels.matrix.actions.verification", + "kind": "channel", + "type": "boolean", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, { "path": "channels.matrix.allowlistOnly", "kind": "channel", @@ -22209,6 +22257,16 @@ "tags": [], "hasChildren": false }, + { + "path": "channels.matrix.avatarUrl", + "kind": "channel", + "type": "string", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, { "path": "channels.matrix.chunkMode", "kind": "channel", @@ -22233,6 +22291,16 @@ "tags": [], "hasChildren": false }, + { + "path": "channels.matrix.deviceId", + "kind": "channel", + "type": "string", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, { "path": "channels.matrix.deviceName", "kind": "channel", @@ -22651,6 +22719,20 @@ "tags": [], "hasChildren": false }, + { + "path": "channels.matrix.reactionNotifications", + "kind": "channel", + "type": "string", + "required": false, + "enumValues": [ + "off", + "own" + ], + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, { "path": "channels.matrix.replyToMode", "kind": "channel", @@ -22859,6 +22941,30 @@ "tags": [], "hasChildren": false }, + { + "path": "channels.matrix.startupVerification", + "kind": "channel", + "type": "string", + "required": false, + "enumValues": [ + "off", + "if-unverified" + ], + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, + { + "path": "channels.matrix.startupVerificationCooldownHours", + "kind": "channel", + "type": "number", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, { "path": "channels.matrix.textChunkLimit", "kind": "channel", @@ -22869,6 +22975,66 @@ "tags": [], "hasChildren": false }, + { + "path": "channels.matrix.threadBindings", + "kind": "channel", + "type": "object", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": true + }, + { + "path": "channels.matrix.threadBindings.enabled", + "kind": "channel", + "type": "boolean", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, + { + "path": "channels.matrix.threadBindings.idleHours", + "kind": "channel", + "type": "number", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, + { + "path": "channels.matrix.threadBindings.maxAgeHours", + "kind": "channel", + "type": "number", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, + { + "path": "channels.matrix.threadBindings.spawnAcpSessions", + "kind": "channel", + "type": "boolean", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, + { + "path": "channels.matrix.threadBindings.spawnSubagentSessions", + "kind": "channel", + "type": "boolean", + "required": false, + "deprecated": false, + "sensitive": false, + "tags": [], + "hasChildren": false + }, { "path": "channels.matrix.threadReplies", "kind": "channel", diff --git a/docs/.generated/config-baseline.jsonl b/docs/.generated/config-baseline.jsonl index 8c75f3c5177..665b771caa7 100644 --- a/docs/.generated/config-baseline.jsonl +++ b/docs/.generated/config-baseline.jsonl @@ -1,4 +1,4 @@ -{"generatedBy":"scripts/generate-config-doc-baseline.ts","recordType":"meta","totalPaths":5518} +{"generatedBy":"scripts/generate-config-doc-baseline.ts","recordType":"meta","totalPaths":5533} {"recordType":"path","path":"acp","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"ACP","help":"ACP runtime controls for enabling dispatch, selecting backends, constraining allowed agent targets, and tuning streamed turn projection behavior.","hasChildren":true} {"recordType":"path","path":"acp.allowedAgents","kind":"core","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"ACP Allowed Agents","help":"Allowlist of ACP target agent ids permitted for ACP runtime sessions. Empty means no additional allowlist restriction.","hasChildren":true} {"recordType":"path","path":"acp.allowedAgents.*","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} @@ -1984,18 +1984,24 @@ {"recordType":"path","path":"channels.matrix.accessToken","kind":"channel","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.accounts","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true} {"recordType":"path","path":"channels.matrix.accounts.*","kind":"channel","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.ackReaction","kind":"channel","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.ackReactionScope","kind":"channel","type":"string","required":false,"enumValues":["group-mentions","group-all","direct","all","none","off"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.actions","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true} {"recordType":"path","path":"channels.matrix.actions.channelInfo","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.actions.memberInfo","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.actions.messages","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.actions.pins","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.actions.profile","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.actions.reactions","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.actions.verification","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.allowlistOnly","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.autoJoin","kind":"channel","type":"string","required":false,"enumValues":["always","allowlist","off"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.autoJoinAllowlist","kind":"channel","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true} {"recordType":"path","path":"channels.matrix.autoJoinAllowlist.*","kind":"channel","type":["number","string"],"required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.avatarUrl","kind":"channel","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.chunkMode","kind":"channel","type":"string","required":false,"enumValues":["length","newline"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.defaultAccount","kind":"channel","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.deviceId","kind":"channel","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.deviceName","kind":"channel","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.dm","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true} {"recordType":"path","path":"channels.matrix.dm.allowFrom","kind":"channel","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true} @@ -2035,6 +2041,7 @@ {"recordType":"path","path":"channels.matrix.password.id","kind":"channel","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.password.provider","kind":"channel","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.password.source","kind":"channel","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.reactionNotifications","kind":"channel","type":"string","required":false,"enumValues":["off","own"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.replyToMode","kind":"channel","type":"string","required":false,"enumValues":["off","first","all"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.responsePrefix","kind":"channel","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.rooms","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true} @@ -2055,7 +2062,15 @@ {"recordType":"path","path":"channels.matrix.rooms.*.tools.deny.*","kind":"channel","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.rooms.*.users","kind":"channel","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true} {"recordType":"path","path":"channels.matrix.rooms.*.users.*","kind":"channel","type":["number","string"],"required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.startupVerification","kind":"channel","type":"string","required":false,"enumValues":["off","if-unverified"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.startupVerificationCooldownHours","kind":"channel","type":"number","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.textChunkLimit","kind":"channel","type":"number","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.threadBindings","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true} +{"recordType":"path","path":"channels.matrix.threadBindings.enabled","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.threadBindings.idleHours","kind":"channel","type":"number","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.threadBindings.maxAgeHours","kind":"channel","type":"number","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.threadBindings.spawnAcpSessions","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} +{"recordType":"path","path":"channels.matrix.threadBindings.spawnSubagentSessions","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.threadReplies","kind":"channel","type":"string","required":false,"enumValues":["off","inbound","always"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.matrix.userId","kind":"channel","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false} {"recordType":"path","path":"channels.mattermost","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["channels","network"],"label":"Mattermost","help":"self-hosted Slack-style chat; install the plugin to enable.","hasChildren":true} From a2174f1ff153976e3fafa4259b9f6213ef4cf43b Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 18:56:43 -0700 Subject: [PATCH 64/69] fix(hooks): skip repo check outside workspace --- git-hooks/pre-commit | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/git-hooks/pre-commit b/git-hooks/pre-commit index 34831d6cf3d..11079bc9f22 100755 --- a/git-hooks/pre-commit +++ b/git-hooks/pre-commit @@ -48,5 +48,10 @@ fi git add -- "${files[@]}" -cd "$ROOT_DIR" -pnpm check +# This hook is also exercised from lightweight temp repos in tests, where the +# staged-file safety behavior matters but the full OpenClaw workspace does not +# exist. Only run the repo-wide gate inside a real checkout. +if [[ -f "$ROOT_DIR/package.json" ]] && [[ -f "$ROOT_DIR/pnpm-lock.yaml" ]]; then + cd "$ROOT_DIR" + pnpm check +fi From 1fb30fbf784739576f2d5a286d4641595ebb4272 Mon Sep 17 00:00:00 2001 From: Shakker Date: Fri, 20 Mar 2026 01:57:24 +0000 Subject: [PATCH 65/69] fix(test): stub pnpm in pre-commit hook fixture --- test/git-hooks-pre-commit.test.ts | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/test/git-hooks-pre-commit.test.ts b/test/git-hooks-pre-commit.test.ts index 018fcce7090..5f608e4b9a2 100644 --- a/test/git-hooks-pre-commit.test.ts +++ b/test/git-hooks-pre-commit.test.ts @@ -18,6 +18,13 @@ const run = (cwd: string, cmd: string, args: string[] = [], env?: NodeJS.Process }).trim(); }; +function writeExecutable(dir: string, name: string, contents: string): void { + writeFileSync(path.join(dir, name), contents, { + encoding: "utf8", + mode: 0o755, + }); +} + describe("git-hooks/pre-commit (integration)", () => { it("does not treat staged filenames as git-add flags (e.g. --all)", () => { const dir = mkdtempSync(path.join(os.tmpdir(), "openclaw-pre-commit-")); @@ -45,10 +52,10 @@ describe("git-hooks/pre-commit (integration)", () => { ); const fakeBinDir = path.join(dir, "bin"); mkdirSync(fakeBinDir, { recursive: true }); - writeFileSync(path.join(fakeBinDir, "node"), "#!/usr/bin/env bash\nexit 0\n", { - encoding: "utf8", - mode: 0o755, - }); + writeExecutable(fakeBinDir, "node", "#!/usr/bin/env bash\nexit 0\n"); + // The hook ends with `pnpm check`, but this fixture is only exercising staged-file handling. + // Stub pnpm too so Windows CI does not invoke a real package-manager command in the temp repo. + writeExecutable(fakeBinDir, "pnpm", "#!/usr/bin/env bash\nexit 0\n"); // Create an untracked file that should NOT be staged by the hook. writeFileSync(path.join(dir, "secret.txt"), "do-not-stage\n", "utf8"); From 61ae7e033b9a2881bd6694e499e67f3911ac068b Mon Sep 17 00:00:00 2001 From: Shakker Date: Fri, 20 Mar 2026 01:57:49 +0000 Subject: [PATCH 66/69] fix(ci): isolate remaining unit-fast OOM hotspots --- test/fixtures/test-parallel.behavior.json | 48 +++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/test/fixtures/test-parallel.behavior.json b/test/fixtures/test-parallel.behavior.json index c7349987f39..fcec755d6a3 100644 --- a/test/fixtures/test-parallel.behavior.json +++ b/test/fixtures/test-parallel.behavior.json @@ -143,14 +143,38 @@ "file": "src/cron/isolated-agent/run.sandbox-config-preserved.test.ts", "reason": "Isolated-agent sandbox config coverage retained a large shared unit-fast heap spike on Linux CI." }, + { + "file": "src/cron/isolated-agent.direct-delivery-core-channels.test.ts", + "reason": "Direct-delivery isolated-agent coverage retained a top shared unit-fast heap spike in the March 20, 2026 Linux Node 24 OOM lane." + }, + { + "file": "src/cron/service.issue-regressions.test.ts", + "reason": "Issue regression cron coverage retained the largest shared unit-fast heap spike in the March 20, 2026 Linux Node 22 and Node 24 OOM lanes." + }, { "file": "src/cron/store.test.ts", "reason": "Cron store coverage retained a large shared unit-fast heap spike on Linux Node 24 CI." }, + { + "file": "src/context-engine/context-engine.test.ts", + "reason": "Context-engine coverage retained the largest shared unit-fast heap spike in the March 20, 2026 Linux Node 24 shard 1 OOM lane." + }, + { + "file": "src/acp/control-plane/manager.test.ts", + "reason": "ACP control-plane manager coverage retained a top shared unit-fast heap spike in the March 20, 2026 Linux Node 22 and Node 24 OOM lanes." + }, + { + "file": "src/acp/translator.stop-reason.test.ts", + "reason": "ACP translator stop-reason coverage retained a top shared unit-fast heap spike in the March 20, 2026 Linux Node 24 shard 2 OOM lane." + }, { "file": "src/infra/exec-approval-forwarder.test.ts", "reason": "Exec approval forwarder coverage retained a top shared unit-fast heap spike in the March 19, 2026 Linux Node 22 OOM lane." }, + { + "file": "src/infra/restart-stale-pids.test.ts", + "reason": "Restart-stale-pids coverage retained a top shared unit-fast heap spike in the March 20, 2026 Linux Node 24 shard 1 OOM lane." + }, { "file": "src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts", "reason": "Heartbeat ack max chars coverage retained a recurring shared unit-fast heap spike across Linux CI lanes." @@ -171,17 +195,41 @@ "file": "src/memory/manager.mistral-provider.test.ts", "reason": "Mistral provider coverage retained a large shared unit-fast heap spike on Linux Node 24 CI." }, + { + "file": "src/memory/manager.batch.test.ts", + "reason": "Memory manager batch coverage retained a top shared unit-fast heap spike in the March 20, 2026 Linux Node 22 and Node 24 OOM lanes." + }, { "file": "src/memory/qmd-manager.test.ts", "reason": "QMD manager coverage retained recurring shared unit-fast heap spikes across Linux CI lanes." }, + { + "file": "src/media-understanding/providers/image.test.ts", + "reason": "Image provider coverage retained a top shared unit-fast heap spike in the March 20, 2026 Linux Node 24 shard 2 OOM lane." + }, { "file": "src/plugins/contracts/auth.contract.test.ts", "reason": "Plugin auth contract coverage retained a large shared unit-fast heap spike on Linux Node 24 CI." }, + { + "file": "src/plugins/contracts/discovery.contract.test.ts", + "reason": "Plugin discovery contract coverage retained a top shared unit-fast heap spike in the March 20, 2026 Linux Node 24 shard 1 OOM lane." + }, + { + "file": "src/plugins/hooks.phase-hooks.test.ts", + "reason": "Phase hooks coverage retained a top shared unit-fast heap spike in the March 20, 2026 Linux Node 24 shard 2 OOM lane." + }, + { + "file": "src/channels/plugins/plugins-core.test.ts", + "reason": "Core plugin coverage retained a top shared unit-fast heap spike in the March 20, 2026 Linux Node 22 OOM lane." + }, { "file": "src/secrets/apply.test.ts", "reason": "Secrets apply coverage retained a large shared unit-fast heap spike on Linux Node 22 CI." + }, + { + "file": "src/tui/tui-command-handlers.test.ts", + "reason": "TUI command handler coverage retained a top shared unit-fast heap spike in the March 20, 2026 Linux Node 24 shard 2 OOM lane." } ], "threadSingleton": [ From 65594f972c2cbdaa8fa8d1f2606d3ec2825e1ac1 Mon Sep 17 00:00:00 2001 From: Harold Hunt Date: Thu, 19 Mar 2026 22:09:38 -0400 Subject: [PATCH 67/69] Gateway: unify plugin interactive callback state (#50722) Merged via squash. Prepared head SHA: 7a2740b18a336bc3a58c23cff08953a5c06a6078 Co-authored-by: huntharo <5617868+huntharo@users.noreply.github.com> Co-authored-by: huntharo <5617868+huntharo@users.noreply.github.com> Reviewed-by: @huntharo --- CHANGELOG.md | 1 + extensions/telegram/src/bot.test.ts | 6 +- src/plugins/conversation-binding.test.ts | 113 +++++++++++++++++++++++ src/plugins/conversation-binding.ts | 42 +++++---- src/plugins/interactive.test.ts | 68 ++++++++++++++ src/plugins/interactive.ts | 23 ++++- 6 files changed, 227 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0cf9b671096..7928c21129d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -168,6 +168,7 @@ Docs: https://docs.openclaw.ai - Onboarding/custom providers: keep Azure AI Foundry `*.services.ai.azure.com` custom endpoints on the selected compatibility path instead of forcing Responses, so chat-completions Foundry models still work after setup. Fixes #50528. (#50535) Thanks @obviyus. - Plugins/update: let `openclaw plugins update ` target tracked npm installs by dist-tag or exact version, and preserve the recorded npm spec for later id-based updates. (#49998) Thanks @huntharo. - Tests/CLI: reduce command-secret gateway test import pressure while keeping the real protocol payload validator in place, so the isolated lane no longer carries the heavier runtime-web and message-channel graphs. (#50663) Thanks @huntharo. +- Gateway/plugins: share plugin interactive callback routing and plugin bind approval state across duplicate module graphs so Telegram Codex picker buttons and plugin bind approvals no longer fall through to normal inbound message routing. (#50722) Thanks @huntharo. ### Breaking diff --git a/extensions/telegram/src/bot.test.ts b/extensions/telegram/src/bot.test.ts index 995fe61ed2a..5fe9ff639f7 100644 --- a/extensions/telegram/src/bot.test.ts +++ b/extensions/telegram/src/bot.test.ts @@ -1382,14 +1382,14 @@ describe("createTelegramBot", () => { expect(replySpy).not.toHaveBeenCalled(); }); - it.skip("routes plugin-owned callback namespaces before synthetic command fallback", async () => { + it("routes plugin-owned callback namespaces before synthetic command fallback", async () => { onSpy.mockClear(); replySpy.mockClear(); editMessageTextSpy.mockClear(); sendMessageSpy.mockClear(); registerPluginInteractiveHandler("codex-plugin", { channel: "telegram", - namespace: "codex", + namespace: "codexapp", handler: async ({ respond, callback }: PluginInteractiveTelegramHandlerContext) => { await respond.editMessage({ text: `Handled ${callback.payload}`, @@ -1416,7 +1416,7 @@ describe("createTelegramBot", () => { await callbackHandler({ callbackQuery: { id: "cbq-codex-1", - data: "codex:resume:thread-1", + data: "codexapp:resume:thread-1", from: { id: 9, first_name: "Ada", username: "ada_bot" }, message: { chat: { id: 1234, type: "private" }, diff --git a/src/plugins/conversation-binding.test.ts b/src/plugins/conversation-binding.test.ts index 81371a7ce3d..3cfc8cc2420 100644 --- a/src/plugins/conversation-binding.test.ts +++ b/src/plugins/conversation-binding.test.ts @@ -109,6 +109,17 @@ const { registerSessionBindingAdapter, unregisterSessionBindingAdapter } = await import("../infra/outbound/session-binding-service.js"); type PluginBindingRequest = Awaited>; +type ConversationBindingModule = typeof import("./conversation-binding.js"); + +const conversationBindingModuleUrl = new URL("./conversation-binding.ts", import.meta.url).href; + +async function importConversationBindingModule( + cacheBust: string, +): Promise { + return (await import( + `${conversationBindingModuleUrl}?t=${cacheBust}` + )) as ConversationBindingModule; +} function createAdapter(channel: string, accountId: string): SessionBindingAdapter { return { @@ -290,6 +301,108 @@ describe("plugin conversation binding approvals", () => { expect(differentAccount.status).toBe("pending"); }); + it("shares pending bind approvals across duplicate module instances", async () => { + const first = await importConversationBindingModule(`first-${Date.now()}`); + const second = await importConversationBindingModule(`second-${Date.now()}`); + + first.__testing.reset(); + + const request = await first.requestPluginConversationBinding({ + pluginId: "codex", + pluginName: "Codex App Server", + pluginRoot: "/plugins/codex-a", + requestedBySenderId: "user-1", + conversation: { + channel: "telegram", + accountId: "default", + conversationId: "-10099:topic:77", + parentConversationId: "-10099", + threadId: "77", + }, + binding: { summary: "Bind this conversation to Codex thread abc." }, + }); + + expect(request.status).toBe("pending"); + if (request.status !== "pending") { + throw new Error("expected pending bind request"); + } + + await expect( + second.resolvePluginConversationBindingApproval({ + approvalId: request.approvalId, + decision: "allow-once", + senderId: "user-1", + }), + ).resolves.toMatchObject({ + status: "approved", + binding: expect.objectContaining({ + pluginId: "codex", + pluginRoot: "/plugins/codex-a", + conversationId: "-10099:topic:77", + }), + }); + + second.__testing.reset(); + }); + + it("shares persistent approvals across duplicate module instances", async () => { + const first = await importConversationBindingModule(`first-${Date.now()}`); + const second = await importConversationBindingModule(`second-${Date.now()}`); + + first.__testing.reset(); + + const request = await first.requestPluginConversationBinding({ + pluginId: "codex", + pluginName: "Codex App Server", + pluginRoot: "/plugins/codex-a", + requestedBySenderId: "user-1", + conversation: { + channel: "telegram", + accountId: "default", + conversationId: "-10099:topic:77", + parentConversationId: "-10099", + threadId: "77", + }, + binding: { summary: "Bind this conversation to Codex thread abc." }, + }); + + expect(request.status).toBe("pending"); + if (request.status !== "pending") { + throw new Error("expected pending bind request"); + } + + await expect( + second.resolvePluginConversationBindingApproval({ + approvalId: request.approvalId, + decision: "allow-always", + senderId: "user-1", + }), + ).resolves.toMatchObject({ + status: "approved", + decision: "allow-always", + }); + + const rebound = await first.requestPluginConversationBinding({ + pluginId: "codex", + pluginName: "Codex App Server", + pluginRoot: "/plugins/codex-a", + requestedBySenderId: "user-1", + conversation: { + channel: "telegram", + accountId: "default", + conversationId: "-10099:topic:78", + parentConversationId: "-10099", + threadId: "78", + }, + binding: { summary: "Bind this conversation to Codex thread def." }, + }); + + expect(rebound.status).toBe("bound"); + + first.__testing.reset(); + fs.rmSync(approvalsPath, { force: true }); + }); + it("does not share persistent approvals across plugin roots even with the same plugin id", async () => { const request = await requestPluginConversationBinding({ pluginId: "codex", diff --git a/src/plugins/conversation-binding.ts b/src/plugins/conversation-binding.ts index aef5ec92b40..10ceeeb9fd5 100644 --- a/src/plugins/conversation-binding.ts +++ b/src/plugins/conversation-binding.ts @@ -11,6 +11,7 @@ import { expandHomePrefix } from "../infra/home-dir.js"; import { writeJsonAtomic } from "../infra/json-files.js"; import { type ConversationRef } from "../infra/outbound/session-binding-service.js"; import { createSubsystemLogger } from "../logging/subsystem.js"; +import { resolveGlobalMap, resolveGlobalSingleton } from "../shared/global-singleton.js"; import { getActivePluginRegistry } from "./runtime.js"; import type { PluginConversationBinding, @@ -104,24 +105,26 @@ type PluginBindingResolveResult = status: "expired"; }; -const pendingRequests = new Map(); +const PLUGIN_BINDING_PENDING_REQUESTS_KEY = Symbol.for("openclaw.pluginBindingPendingRequests"); + +const pendingRequests = resolveGlobalMap( + PLUGIN_BINDING_PENDING_REQUESTS_KEY, +); type PluginBindingGlobalState = { fallbackNoticeBindingIds: Set; + approvalsCache: PluginBindingApprovalsFile | null; + approvalsLoaded: boolean; }; const pluginBindingGlobalStateKey = Symbol.for("openclaw.plugins.binding.global-state"); -let approvalsCache: PluginBindingApprovalsFile | null = null; -let approvalsLoaded = false; - function getPluginBindingGlobalState(): PluginBindingGlobalState { - const globalStore = globalThis as typeof globalThis & { - [pluginBindingGlobalStateKey]?: PluginBindingGlobalState; - }; - return (globalStore[pluginBindingGlobalStateKey] ??= { + return resolveGlobalSingleton(pluginBindingGlobalStateKey, () => ({ fallbackNoticeBindingIds: new Set(), - }); + approvalsCache: null, + approvalsLoaded: false, + })); } function resolveApprovalsPath(): string { @@ -297,8 +300,9 @@ function loadApprovalsFromDisk(): PluginBindingApprovalsFile { async function saveApprovals(file: PluginBindingApprovalsFile): Promise { const filePath = resolveApprovalsPath(); fs.mkdirSync(path.dirname(filePath), { recursive: true }); - approvalsCache = file; - approvalsLoaded = true; + const state = getPluginBindingGlobalState(); + state.approvalsCache = file; + state.approvalsLoaded = true; await writeJsonAtomic(filePath, file, { mode: 0o600, trailingNewline: true, @@ -306,11 +310,12 @@ async function saveApprovals(file: PluginBindingApprovalsFile): Promise { } function getApprovals(): PluginBindingApprovalsFile { - if (!approvalsLoaded || !approvalsCache) { - approvalsCache = loadApprovalsFromDisk(); - approvalsLoaded = true; + const state = getPluginBindingGlobalState(); + if (!state.approvalsLoaded || !state.approvalsCache) { + state.approvalsCache = loadApprovalsFromDisk(); + state.approvalsLoaded = true; } - return approvalsCache; + return state.approvalsCache; } function hasPersistentApproval(params: { @@ -836,8 +841,9 @@ export function buildPluginBindingResolvedText(params: PluginBindingResolveResul export const __testing = { reset() { pendingRequests.clear(); - approvalsCache = null; - approvalsLoaded = false; - getPluginBindingGlobalState().fallbackNoticeBindingIds.clear(); + const state = getPluginBindingGlobalState(); + state.approvalsCache = null; + state.approvalsLoaded = false; + state.fallbackNoticeBindingIds.clear(); }, }; diff --git a/src/plugins/interactive.test.ts b/src/plugins/interactive.test.ts index 2b595e856f8..0cc91e7f04f 100644 --- a/src/plugins/interactive.test.ts +++ b/src/plugins/interactive.test.ts @@ -49,6 +49,14 @@ type InteractiveDispatchParams = respond: PluginInteractiveSlackHandlerContext["respond"]; }; +type InteractiveModule = typeof import("./interactive.js"); + +const interactiveModuleUrl = new URL("./interactive.ts", import.meta.url).href; + +async function importInteractiveModule(cacheBust: string): Promise { + return (await import(`${interactiveModuleUrl}?t=${cacheBust}`)) as InteractiveModule; +} + async function expectDedupedInteractiveDispatch(params: { baseParams: InteractiveDispatchParams; handler: ReturnType; @@ -172,6 +180,66 @@ describe("plugin interactive handlers", () => { }); }); + it("shares interactive handlers across duplicate module instances", async () => { + const first = await importInteractiveModule(`first-${Date.now()}`); + const second = await importInteractiveModule(`second-${Date.now()}`); + const handler = vi.fn(async () => ({ handled: true })); + + first.clearPluginInteractiveHandlers(); + + expect( + first.registerPluginInteractiveHandler("codex-plugin", { + channel: "telegram", + namespace: "codexapp", + handler, + }), + ).toEqual({ ok: true }); + + await expect( + second.dispatchPluginInteractiveHandler({ + channel: "telegram", + data: "codexapp:resume:thread-1", + callbackId: "cb-shared-1", + ctx: { + accountId: "default", + callbackId: "cb-shared-1", + conversationId: "-10099:topic:77", + parentConversationId: "-10099", + senderId: "user-1", + senderUsername: "ada", + threadId: 77, + isGroup: true, + isForum: true, + auth: { isAuthorizedSender: true }, + callbackMessage: { + messageId: 55, + chatId: "-10099", + messageText: "Pick a thread", + }, + }, + respond: { + reply: vi.fn(async () => {}), + editMessage: vi.fn(async () => {}), + editButtons: vi.fn(async () => {}), + clearButtons: vi.fn(async () => {}), + deleteMessage: vi.fn(async () => {}), + }, + }), + ).resolves.toEqual({ matched: true, handled: true, duplicate: false }); + + expect(handler).toHaveBeenCalledWith( + expect.objectContaining({ + channel: "telegram", + callback: expect.objectContaining({ + namespace: "codexapp", + payload: "resume:thread-1", + }), + }), + ); + + second.clearPluginInteractiveHandlers(); + }); + it("rejects duplicate namespace registrations", () => { const first = registerPluginInteractiveHandler("plugin-a", { channel: "telegram", diff --git a/src/plugins/interactive.ts b/src/plugins/interactive.ts index 04403c80fa2..424a5c5d0af 100644 --- a/src/plugins/interactive.ts +++ b/src/plugins/interactive.ts @@ -1,4 +1,5 @@ import { createDedupeCache } from "../infra/dedupe.js"; +import { resolveGlobalSingleton } from "../shared/global-singleton.js"; import { dispatchDiscordInteractiveHandler, dispatchSlackInteractiveHandler, @@ -33,11 +34,23 @@ type InteractiveDispatchResult = | { matched: false; handled: false; duplicate: false } | { matched: true; handled: boolean; duplicate: boolean }; -const interactiveHandlers = new Map(); -const callbackDedupe = createDedupeCache({ - ttlMs: 5 * 60_000, - maxSize: 4096, -}); +type InteractiveState = { + interactiveHandlers: Map; + callbackDedupe: ReturnType; +}; + +const PLUGIN_INTERACTIVE_STATE_KEY = Symbol.for("openclaw.pluginInteractiveState"); + +const state = resolveGlobalSingleton(PLUGIN_INTERACTIVE_STATE_KEY, () => ({ + interactiveHandlers: new Map(), + callbackDedupe: createDedupeCache({ + ttlMs: 5 * 60_000, + maxSize: 4096, + }), +})); + +const interactiveHandlers = state.interactiveHandlers; +const callbackDedupe = state.callbackDedupe; function toRegistryKey(channel: string, namespace: string): string { return `${channel.trim().toLowerCase()}:${namespace.trim()}`; From f1ce679929c115def8d4f53e90e5481c41e63d6c Mon Sep 17 00:00:00 2001 From: Harold Hunt Date: Thu, 19 Mar 2026 22:23:21 -0400 Subject: [PATCH 68/69] Discord: reconcile native commands without restart churn (#46597) Merged via squash. Prepared head SHA: 37090daad4b99171a55962101d9998fd452e2739 Co-authored-by: huntharo <5617868+huntharo@users.noreply.github.com> Reviewed-by: @huntharo --- CHANGELOG.md | 1 + extensions/discord/package.json | 2 +- .../discord/src/monitor/provider.test.ts | 26 ++++++++++++++++ extensions/discord/src/monitor/provider.ts | 4 ++- pnpm-lock.yaml | 31 ++++++++++++++++--- 5 files changed, 58 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7928c21129d..70652051c90 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -181,6 +181,7 @@ Docs: https://docs.openclaw.ai - Plugins/message discovery: require `ChannelMessageActionAdapter.describeMessageTool(...)` for shared `message` tool discovery. The legacy `listActions`, `getCapabilities`, and `getToolSchema` adapter methods are removed. Plugin authors should migrate message discovery to `describeMessageTool(...)` and keep channel-specific action runtime code inside the owning plugin package. Thanks @gumadeiras. - Exec/env sandbox: block build-tool JVM injection (`MAVEN_OPTS`, `SBT_OPTS`, `GRADLE_OPTS`, `ANT_OPTS`), glibc tunable exploitation (`GLIBC_TUNABLES`), and .NET dependency resolution hijack (`DOTNET_ADDITIONAL_DEPS`) from the host exec environment, and restrict Gradle init script redirect (`GRADLE_USER_HOME`) as an override-only block so user-configured Gradle homes still propagate. (#49702) - Plugins/Matrix: add a new Matrix plugin backed by the official `matrix-js-sdk`. If you are upgrading from the previous public Matrix plugin, follow the migration guide: https://docs.openclaw.ai/install/migrating-matrix Thanks @gumadeiras. +- Discord/commands: switch native command deployment to Carbon reconcile by default so Discord restarts stop churning slash commands through OpenClaw’s local deploy path. (#46597) Thanks @huntharo and @thewilloftheshadow. ## 2026.3.13 diff --git a/extensions/discord/package.json b/extensions/discord/package.json index 33adc17e6da..589ceed8d21 100644 --- a/extensions/discord/package.json +++ b/extensions/discord/package.json @@ -4,7 +4,7 @@ "description": "OpenClaw Discord channel plugin", "type": "module", "dependencies": { - "@buape/carbon": "0.0.0-beta-20260216184201", + "@buape/carbon": "0.0.0-beta-20260317045421", "@discordjs/voice": "^0.19.2", "discord-api-types": "^0.38.42", "https-proxy-agent": "^8.0.0", diff --git a/extensions/discord/src/monitor/provider.test.ts b/extensions/discord/src/monitor/provider.test.ts index 23c4b394379..2772790878b 100644 --- a/extensions/discord/src/monitor/provider.test.ts +++ b/extensions/discord/src/monitor/provider.test.ts @@ -88,11 +88,25 @@ describe("monitorDiscordProvider", () => { const getConstructedEventQueue = (): { listenerTimeout?: number } | undefined => { expect(clientConstructorOptionsMock).toHaveBeenCalledTimes(1); const opts = clientConstructorOptionsMock.mock.calls[0]?.[0] as { + commandDeploymentMode?: string; eventQueue?: { listenerTimeout?: number }; }; return opts.eventQueue; }; + const getConstructedClientOptions = (): { + commandDeploymentMode?: string; + eventQueue?: { listenerTimeout?: number }; + } => { + expect(clientConstructorOptionsMock).toHaveBeenCalledTimes(1); + return ( + (clientConstructorOptionsMock.mock.calls[0]?.[0] as { + commandDeploymentMode?: string; + eventQueue?: { listenerTimeout?: number }; + }) ?? {} + ); + }; + const getHealthProbe = () => { expect(reconcileAcpThreadBindingsOnStartupMock).toHaveBeenCalledTimes(1); const firstCall = reconcileAcpThreadBindingsOnStartupMock.mock.calls.at(0) as @@ -539,6 +553,18 @@ describe("monitorDiscordProvider", () => { ); }); + it("configures Carbon reconcile deployment by default", async () => { + const { monitorDiscordProvider } = await import("./provider.js"); + + await monitorDiscordProvider({ + config: baseConfig(), + runtime: baseRuntime(), + }); + + expect(clientHandleDeployRequestMock).toHaveBeenCalledTimes(1); + expect(getConstructedClientOptions().commandDeploymentMode).toBe("reconcile"); + }); + it("reports connected status on startup and shutdown", async () => { const { monitorDiscordProvider } = await import("./provider.js"); const setStatus = vi.fn(); diff --git a/extensions/discord/src/monitor/provider.ts b/extensions/discord/src/monitor/provider.ts index 9c766334964..55293357763 100644 --- a/extensions/discord/src/monitor/provider.ts +++ b/extensions/discord/src/monitor/provider.ts @@ -306,6 +306,7 @@ async function deployDiscordCommands(params: { // errors like Discord 30034 fail fast and don't wedge the provider. restClient.options.queueRequests = false; } + params.runtime.log?.("discord: native commands using Carbon reconcile path"); for (let attempt = 1; attempt <= maxAttempts; attempt += 1) { try { await params.client.handleDeployRequest(); @@ -762,6 +763,7 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) { baseUrl: "http://localhost", deploySecret: "a", clientId: applicationId, + commandDeploymentMode: "reconcile", publicKey: "a", token, autoDeploy: false, @@ -805,7 +807,7 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) { phase: "deploy-commands:start", startAt: startupStartedAt, gateway: lifecycleGateway, - details: `native=${nativeEnabled ? "on" : "off"} commandCount=${commands.length}`, + details: `native=${nativeEnabled ? "on" : "off"} reconcile=on commandCount=${commands.length}`, }); await deployDiscordCommands({ client, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 70e7586716b..f0d503f2346 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -309,8 +309,8 @@ importers: extensions/discord: dependencies: '@buape/carbon': - specifier: 0.0.0-beta-20260216184201 - version: 0.0.0-beta-20260216184201(@discordjs/opus@0.10.0)(hono@4.12.8)(opusscript@0.1.1) + specifier: 0.0.0-beta-20260317045421 + version: 0.0.0-beta-20260317045421(@discordjs/opus@0.10.0)(hono@4.12.8)(opusscript@0.1.1) '@discordjs/voice': specifier: ^0.19.2 version: 0.19.2(@discordjs/opus@0.10.0)(opusscript@0.1.1) @@ -991,6 +991,9 @@ packages: '@buape/carbon@0.0.0-beta-20260216184201': resolution: {integrity: sha512-u5mgYcigfPVqT7D9gVTGd+3YSflTreQmrWog7ORbb0z5w9eT8ft4rJOdw9fGwr75zMu9kXpSBaAcY2eZoJFSdA==} + '@buape/carbon@0.0.0-beta-20260317045421': + resolution: {integrity: sha512-yM+r5iSxA/iG8CZ2VhK+EkcBQV+y45WLgF7kuczt2Ul1yixjXSCCcM80GppsklfUv7pqM4Dui+7w1WB3f5p7Kg==} + '@cacheable/memory@2.0.7': resolution: {integrity: sha512-RbxnxAMf89Tp1dLhXMS7ceft/PGsDl1Ip7T20z5nZ+pwIAsQ1p2izPjVG69oCLv/jfQ7HDPHTWK0c9rcAWXN3A==} @@ -7494,7 +7497,27 @@ snapshots: dependencies: css-tree: 3.2.1 - '@buape/carbon@0.0.0-beta-20260216184201(@discordjs/opus@0.10.0)(hono@4.12.8)(opusscript@0.1.1)': + '@buape/carbon@0.0.0-beta-20260216184201(hono@4.12.8)(opusscript@0.1.1)': + dependencies: + '@types/node': 25.5.0 + discord-api-types: 0.38.37 + optionalDependencies: + '@cloudflare/workers-types': 4.20260120.0 + '@discordjs/voice': 0.19.0(@discordjs/opus@0.10.0)(opusscript@0.1.1) + '@hono/node-server': 1.19.10(hono@4.12.8) + '@types/bun': 1.3.9 + '@types/ws': 8.18.1 + ws: 8.19.0 + transitivePeerDependencies: + - '@discordjs/opus' + - bufferutil + - ffmpeg-static + - hono + - node-opus + - opusscript + - utf-8-validate + + '@buape/carbon@0.0.0-beta-20260317045421(@discordjs/opus@0.10.0)(hono@4.12.8)(opusscript@0.1.1)': dependencies: '@types/node': 25.5.0 discord-api-types: 0.38.37 @@ -12415,7 +12438,7 @@ snapshots: dependencies: '@agentclientprotocol/sdk': 0.16.1(zod@4.3.6) '@aws-sdk/client-bedrock': 3.1009.0 - '@buape/carbon': 0.0.0-beta-20260216184201(@discordjs/opus@0.10.0)(hono@4.12.8)(opusscript@0.1.1) + '@buape/carbon': 0.0.0-beta-20260216184201(hono@4.12.8)(opusscript@0.1.1) '@clack/prompts': 1.1.0 '@discordjs/voice': 0.19.2(@discordjs/opus@0.10.0)(opusscript@0.1.1) '@grammyjs/runner': 2.0.3(grammy@1.41.1) From 4f00b3b534f2faca921886ba14c2c4df1655daa7 Mon Sep 17 00:00:00 2001 From: Jinhao Dong Date: Fri, 20 Mar 2026 10:26:47 +0800 Subject: [PATCH 69/69] feat(xiaomi): add MiMo V2 Pro and MiMo V2 Omni models, switch to OpenAI completions API (#49214) Merged via squash. Prepared head SHA: 6b672f36cf0bd4296d3bb2d1b2e6e50d1bb601f1 Co-authored-by: DJjjjhao <50042705+DJjjjhao@users.noreply.github.com> Co-authored-by: grp06 <1573959+grp06@users.noreply.github.com> Reviewed-by: @grp06 --- CHANGELOG.md | 1 + docs/providers/xiaomi.md | 42 ++++++++++++++++++------ docs/zh-CN/providers/xiaomi.md | 46 ++++++++++++++++++++------- extensions/xiaomi/provider-catalog.ts | 22 +++++++++++-- src/commands/onboard-auth.test.ts | 15 ++++++--- 5 files changed, 98 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 70652051c90..ae570f091d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -44,6 +44,7 @@ Docs: https://docs.openclaw.ai - Control UI/chat: add an expand-to-canvas button on assistant chat bubbles and in-app session navigation from Sessions and Cron views. Thanks @BunsDev. - Plugins/context engines: expose `delegateCompactionToRuntime(...)` on the public plugin SDK, refactor the legacy engine to use the shared helper, and clarify `ownsCompaction` delegation semantics for non-owning engines. (#49061) Thanks @jalehman. - Plugins/MiniMax: add MiniMax-M2.7 and MiniMax-M2.7-highspeed models and update the default model from M2.5 to M2.7. (#49691) Thanks @liyuan97. +- Plugins/Xiaomi: switch the bundled Xiaomi provider to the `/v1` OpenAI-compatible endpoint and add MiMo V2 Pro plus MiMo V2 Omni to the built-in catalog. (#49214) thanks @DJjjjhao. ### Fixes diff --git a/docs/providers/xiaomi.md b/docs/providers/xiaomi.md index da1cf7fe38a..aae2ae6d662 100644 --- a/docs/providers/xiaomi.md +++ b/docs/providers/xiaomi.md @@ -1,5 +1,5 @@ --- -summary: "Use Xiaomi MiMo (mimo-v2-flash) with OpenClaw" +summary: "Use Xiaomi MiMo models with OpenClaw" read_when: - You want Xiaomi MiMo models in OpenClaw - You need XIAOMI_API_KEY setup @@ -8,15 +8,18 @@ title: "Xiaomi MiMo" # Xiaomi MiMo -Xiaomi MiMo is the API platform for **MiMo** models. It provides REST APIs compatible with -OpenAI and Anthropic formats and uses API keys for authentication. Create your API key in -the [Xiaomi MiMo console](https://platform.xiaomimimo.com/#/console/api-keys). OpenClaw uses -the `xiaomi` provider with a Xiaomi MiMo API key. +Xiaomi MiMo is the API platform for **MiMo** models. OpenClaw uses the Xiaomi +OpenAI-compatible endpoint with API-key authentication. Create your API key in the +[Xiaomi MiMo console](https://platform.xiaomimimo.com/#/console/api-keys), then configure the +bundled `xiaomi` provider with that key. ## Model overview -- **mimo-v2-flash**: 262144-token context window, Anthropic Messages API compatible. -- Base URL: `https://api.xiaomimimo.com/anthropic` +- **mimo-v2-flash**: default text model, 262144-token context window +- **mimo-v2-pro**: reasoning text model, 1048576-token context window +- **mimo-v2-omni**: reasoning multimodal model with text and image input, 262144-token context window +- Base URL: `https://api.xiaomimimo.com/v1` +- API: `openai-completions` - Authorization: `Bearer $XIAOMI_API_KEY` ## CLI setup @@ -37,8 +40,8 @@ openclaw onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY" mode: "merge", providers: { xiaomi: { - baseUrl: "https://api.xiaomimimo.com/anthropic", - api: "anthropic-messages", + baseUrl: "https://api.xiaomimimo.com/v1", + api: "openai-completions", apiKey: "XIAOMI_API_KEY", models: [ { @@ -50,6 +53,24 @@ openclaw onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY" contextWindow: 262144, maxTokens: 8192, }, + { + id: "mimo-v2-pro", + name: "Xiaomi MiMo V2 Pro", + reasoning: true, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 1048576, + maxTokens: 32000, + }, + { + id: "mimo-v2-omni", + name: "Xiaomi MiMo V2 Omni", + reasoning: true, + input: ["text", "image"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 262144, + maxTokens: 32000, + }, ], }, }, @@ -59,6 +80,7 @@ openclaw onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY" ## Notes -- Model ref: `xiaomi/mimo-v2-flash`. +- Default model ref: `xiaomi/mimo-v2-flash`. +- Additional built-in models: `xiaomi/mimo-v2-pro`, `xiaomi/mimo-v2-omni`. - The provider is injected automatically when `XIAOMI_API_KEY` is set (or an auth profile exists). - See [/concepts/model-providers](/concepts/model-providers) for provider rules. diff --git a/docs/zh-CN/providers/xiaomi.md b/docs/zh-CN/providers/xiaomi.md index 0670f99fa2a..40d5699f7dd 100644 --- a/docs/zh-CN/providers/xiaomi.md +++ b/docs/zh-CN/providers/xiaomi.md @@ -2,28 +2,31 @@ read_when: - 你想在 OpenClaw 中使用 Xiaomi MiMo 模型 - 你需要设置 `XIAOMI_API_KEY` -summary: 在 OpenClaw 中使用 Xiaomi MiMo（`mimo-v2-flash`） +summary: 在 OpenClaw 中使用 Xiaomi MiMo 模型 title: Xiaomi MiMo x-i18n: - generated_at: "2026-03-16T06:27:26Z" + generated_at: "2026-03-20T01:18:00Z" model: gpt-5.4 provider: openai - source_hash: 366fd2297b2caf8c5ad944d7f1b6d233b248fe43aedd22a28352ae7f370d2435 + source_hash: e0abfbe49f438807ce1c5cf5d7910e930c0d670f447f6eb53ca4e9af61cc0843 source_path: providers/xiaomi.md workflow: 15 --- # Xiaomi MiMo -Xiaomi MiMo 是 **MiMo** 模型的 API 平台。它提供与 -OpenAI 和 Anthropic 格式兼容的 REST API，并使用 API key 进行认证。请在 -[Xiaomi MiMo console](https://platform.xiaomimimo.com/#/console/api-keys) 中创建你的 API key。OpenClaw 使用 -`xiaomi` 提供商配合 Xiaomi MiMo API key。 +Xiaomi MiMo 是 **MiMo** 模型的 API 平台。OpenClaw 使用 Xiaomi 提供的 +OpenAI 兼容端点，并通过 API key 认证。请在 +[Xiaomi MiMo console](https://platform.xiaomimimo.com/#/console/api-keys) 中创建你的 API key，然后用它配置内置的 +`xiaomi` 提供商。 ## 模型概览 -- **mimo-v2-flash**：262144-token 上下文窗口，兼容 Anthropic Messages API。 -- Base URL：`https://api.xiaomimimo.com/anthropic` +- **mimo-v2-flash**：默认文本模型，262144-token 上下文窗口 +- **mimo-v2-pro**：支持推理的文本模型，1048576-token 上下文窗口 +- **mimo-v2-omni**：支持推理的多模态模型，支持文本和图像输入，262144-token 上下文窗口 +- Base URL：`https://api.xiaomimimo.com/v1` +- API：`openai-completions` - 认证方式：`Bearer $XIAOMI_API_KEY` ## CLI 设置 @@ -44,8 +47,8 @@ openclaw onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY" mode: "merge", providers: { xiaomi: { - baseUrl: "https://api.xiaomimimo.com/anthropic", - api: "anthropic-messages", + baseUrl: "https://api.xiaomimimo.com/v1", + api: "openai-completions", apiKey: "XIAOMI_API_KEY", models: [ { @@ -57,6 +60,24 @@ openclaw onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY" contextWindow: 262144, maxTokens: 8192, }, + { + id: "mimo-v2-pro", + name: "Xiaomi MiMo V2 Pro", + reasoning: true, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 1048576, + maxTokens: 32000, + }, + { + id: "mimo-v2-omni", + name: "Xiaomi MiMo V2 Omni", + reasoning: true, + input: ["text", "image"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 262144, + maxTokens: 32000, + }, ], }, }, @@ -66,6 +87,7 @@ openclaw onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY" ## 说明 -- 模型引用：`xiaomi/mimo-v2-flash`。 +- 默认模型引用：`xiaomi/mimo-v2-flash`。 +- 额外内置模型：`xiaomi/mimo-v2-pro`、`xiaomi/mimo-v2-omni`。 - 当设置了 `XIAOMI_API_KEY`（或存在凭证配置文件）时，提供商会自动注入。 - 有关提供商规则，请参阅 [/concepts/model-providers](/concepts/model-providers)。 diff --git a/extensions/xiaomi/provider-catalog.ts b/extensions/xiaomi/provider-catalog.ts index 91329eeb87d..53da8f2c00a 100644 --- a/extensions/xiaomi/provider-catalog.ts +++ b/extensions/xiaomi/provider-catalog.ts @@ -1,6 +1,6 @@ import type { ModelProviderConfig } from "openclaw/plugin-sdk/provider-models"; -const XIAOMI_BASE_URL = "https://api.xiaomimimo.com/anthropic"; +const XIAOMI_BASE_URL = "https://api.xiaomimimo.com/v1"; export const XIAOMI_DEFAULT_MODEL_ID = "mimo-v2-flash"; const XIAOMI_DEFAULT_CONTEXT_WINDOW = 262144; const XIAOMI_DEFAULT_MAX_TOKENS = 8192; @@ -14,7 +14,7 @@ const XIAOMI_DEFAULT_COST = { export function buildXiaomiProvider(): ModelProviderConfig { return { baseUrl: XIAOMI_BASE_URL, - api: "anthropic-messages", + api: "openai-completions", models: [ { id: XIAOMI_DEFAULT_MODEL_ID, @@ -25,6 +25,24 @@ export function buildXiaomiProvider(): ModelProviderConfig { contextWindow: XIAOMI_DEFAULT_CONTEXT_WINDOW, maxTokens: XIAOMI_DEFAULT_MAX_TOKENS, }, + { + id: "mimo-v2-pro", + name: "Xiaomi MiMo V2 Pro", + reasoning: true, + input: ["text"], + cost: XIAOMI_DEFAULT_COST, + contextWindow: 1048576, + maxTokens: 32000, + }, + { + id: "mimo-v2-omni", + name: "Xiaomi MiMo V2 Omni", + reasoning: true, + input: ["text", "image"], + cost: XIAOMI_DEFAULT_COST, + contextWindow: XIAOMI_DEFAULT_CONTEXT_WINDOW, + maxTokens: 32000, + }, ], }; } diff --git a/src/commands/onboard-auth.test.ts b/src/commands/onboard-auth.test.ts index 75e0473722d..87a50d23fb6 100644 --- a/src/commands/onboard-auth.test.ts +++ b/src/commands/onboard-auth.test.ts @@ -554,9 +554,14 @@ describe("applyXiaomiConfig", () => { it("adds Xiaomi provider with correct settings", () => { const cfg = applyXiaomiConfig({}); expect(cfg.models?.providers?.xiaomi).toMatchObject({ - baseUrl: "https://api.xiaomimimo.com/anthropic", - api: "anthropic-messages", + baseUrl: "https://api.xiaomimimo.com/v1", + api: "openai-completions", }); + expect(cfg.models?.providers?.xiaomi?.models.map((m) => m.id)).toEqual([ + "mimo-v2-flash", + "mimo-v2-pro", + "mimo-v2-omni", + ]); expect(resolveAgentModelPrimaryValue(cfg.agents?.defaults?.model)).toBe("xiaomi/mimo-v2-flash"); }); @@ -570,12 +575,14 @@ describe("applyXiaomiConfig", () => { }), ); - expect(cfg.models?.providers?.xiaomi?.baseUrl).toBe("https://api.xiaomimimo.com/anthropic"); - expect(cfg.models?.providers?.xiaomi?.api).toBe("anthropic-messages"); + expect(cfg.models?.providers?.xiaomi?.baseUrl).toBe("https://api.xiaomimimo.com/v1"); + expect(cfg.models?.providers?.xiaomi?.api).toBe("openai-completions"); expect(cfg.models?.providers?.xiaomi?.apiKey).toBe("old-key"); expect(cfg.models?.providers?.xiaomi?.models.map((m) => m.id)).toEqual([ "custom-model", "mimo-v2-flash", + "mimo-v2-pro", + "mimo-v2-omni", ]); }); });