From dcbcecfb85e722156e4a9c698ded3972c0da9689 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 09:38:30 -0700 Subject: [PATCH 01/67] fix(ci): resolve Claude marketplace shortcuts from OS home --- src/infra/home-dir.test.ts | 30 +++++++++++++++++++++ src/infra/home-dir.ts | 46 ++++++++++++++++++++++++++++++--- src/plugins/marketplace.test.ts | 4 ++- src/plugins/marketplace.ts | 3 ++- 4 files changed, 77 insertions(+), 6 deletions(-) diff --git a/src/infra/home-dir.test.ts b/src/infra/home-dir.test.ts index 9faeda1dee5..2382b56eaac 100644 --- a/src/infra/home-dir.test.ts +++ b/src/infra/home-dir.test.ts @@ -4,6 +4,8 @@ import { expandHomePrefix, resolveEffectiveHomeDir, resolveHomeRelativePath, + resolveOsHomeDir, + resolveOsHomeRelativePath, resolveRequiredHomeDir, } from "./home-dir.js"; @@ -95,6 +97,21 @@ describe("resolveRequiredHomeDir", () => { }); }); +describe("resolveOsHomeDir", () => { + it("ignores OPENCLAW_HOME and uses HOME", () => { + expect( + resolveOsHomeDir( + { + OPENCLAW_HOME: "/srv/openclaw-home", + HOME: "/home/alice", + USERPROFILE: "C:/Users/alice", + } as NodeJS.ProcessEnv, + () => "/fallback", + ), + ).toBe(path.resolve("/home/alice")); + }); +}); + describe("expandHomePrefix", () => { it.each([ { @@ -158,3 +175,16 @@ describe("resolveHomeRelativePath", () => { ).toBe(path.resolve(process.cwd())); }); }); + +describe("resolveOsHomeRelativePath", () => { + it("expands tilde paths using the OS home instead of OPENCLAW_HOME", () => { + expect( + resolveOsHomeRelativePath("~/docs", { + env: { + OPENCLAW_HOME: "/srv/openclaw-home", + HOME: "/home/alice", + } as NodeJS.ProcessEnv, + }), + ).toBe(path.resolve("/home/alice/docs")); + }); +}); diff --git a/src/infra/home-dir.ts b/src/infra/home-dir.ts index 650cf0cadac..956eeebb278 100644 --- a/src/infra/home-dir.ts +++ b/src/infra/home-dir.ts @@ -14,12 +14,19 @@ export function resolveEffectiveHomeDir( return raw ? path.resolve(raw) : undefined; } +export function resolveOsHomeDir( + env: NodeJS.ProcessEnv = process.env, + homedir: () => string = os.homedir, +): string | undefined { + const raw = resolveRawOsHomeDir(env, homedir); + return raw ? path.resolve(raw) : undefined; +} + function resolveRawHomeDir(env: NodeJS.ProcessEnv, homedir: () => string): string | undefined { const explicitHome = normalize(env.OPENCLAW_HOME); if (explicitHome) { if (explicitHome === "~" || explicitHome.startsWith("~/") || explicitHome.startsWith("~\\")) { - const fallbackHome = - normalize(env.HOME) ?? normalize(env.USERPROFILE) ?? normalizeSafe(homedir); + const fallbackHome = resolveRawOsHomeDir(env, homedir); if (fallbackHome) { return explicitHome.replace(/^~(?=$|[\\/])/, fallbackHome); } @@ -28,16 +35,18 @@ function resolveRawHomeDir(env: NodeJS.ProcessEnv, homedir: () => string): strin return explicitHome; } + return resolveRawOsHomeDir(env, homedir); +} + +function resolveRawOsHomeDir(env: NodeJS.ProcessEnv, homedir: () => string): string | undefined { const envHome = normalize(env.HOME); if (envHome) { return envHome; } - const userProfile = normalize(env.USERPROFILE); if (userProfile) { return userProfile; } - return normalizeSafe(homedir); } @@ -56,6 +65,13 @@ export function resolveRequiredHomeDir( return resolveEffectiveHomeDir(env, homedir) ?? path.resolve(process.cwd()); } +export function resolveRequiredOsHomeDir( + env: NodeJS.ProcessEnv = process.env, + homedir: () => string = os.homedir, +): string { + return resolveOsHomeDir(env, homedir) ?? path.resolve(process.cwd()); +} + export function expandHomePrefix( input: string, opts?: { @@ -97,3 +113,25 @@ export function resolveHomeRelativePath( } return path.resolve(trimmed); } + +export function resolveOsHomeRelativePath( + input: string, + opts?: { + env?: NodeJS.ProcessEnv; + homedir?: () => string; + }, +): string { + const trimmed = input.trim(); + if (!trimmed) { + return trimmed; + } + if (trimmed.startsWith("~")) { + const expanded = expandHomePrefix(trimmed, { + home: resolveRequiredOsHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir), + env: opts?.env, + homedir: opts?.homedir, + }); + return path.resolve(expanded); + } + return path.resolve(trimmed); +} diff --git a/src/plugins/marketplace.test.ts b/src/plugins/marketplace.test.ts index 92918e256d4..6ae2b010556 100644 --- a/src/plugins/marketplace.test.ts +++ b/src/plugins/marketplace.test.ts @@ -111,7 +111,9 @@ describe("marketplace plugins", () => { it("resolves Claude-style plugin@marketplace shortcuts from known_marketplaces.json", async () => { await withTempDir(async (homeDir) => { + const openClawHome = path.join(homeDir, "openclaw-home"); await fs.mkdir(path.join(homeDir, ".claude", "plugins"), { recursive: true }); + await fs.mkdir(openClawHome, { recursive: true }); await fs.writeFile( path.join(homeDir, ".claude", "plugins", "known_marketplaces.json"), JSON.stringify({ @@ -127,7 +129,7 @@ describe("marketplace plugins", () => { const { resolveMarketplaceInstallShortcut } = await import("./marketplace.js"); const shortcut = await withEnvAsync( - { HOME: homeDir }, + { HOME: homeDir, OPENCLAW_HOME: openClawHome }, async () => await resolveMarketplaceInstallShortcut("superpowers@claude-plugins-official"), ); diff --git a/src/plugins/marketplace.ts b/src/plugins/marketplace.ts index 4999c3c8828..24d2fae8ba1 100644 --- a/src/plugins/marketplace.ts +++ b/src/plugins/marketplace.ts @@ -2,6 +2,7 @@ import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; import { resolveArchiveKind } from "../infra/archive.js"; +import { resolveOsHomeRelativePath } from "../infra/home-dir.js"; import { runCommandWithTimeout } from "../process/exec.js"; import { resolveUserPath } from "../utils.js"; import { installPluginFromPath, type InstallPluginResult } from "./install.js"; @@ -299,7 +300,7 @@ async function pathExists(target: string): Promise { } async function readClaudeKnownMarketplaces(): Promise> { - const knownPath = resolveUserPath(CLAUDE_KNOWN_MARKETPLACES_PATH); + const knownPath = resolveOsHomeRelativePath(CLAUDE_KNOWN_MARKETPLACES_PATH); if (!(await pathExists(knownPath))) { return {}; } From 639f78d257f6568ce3c7b5d47e024ceaaf0252f4 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 09:38:35 -0700 Subject: [PATCH 02/67] style(format): restore import order drift --- src/infra/outbound/channel-selection.ts | 2 +- src/plugins/bundle-mcp.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/infra/outbound/channel-selection.ts b/src/infra/outbound/channel-selection.ts index f9c6f558769..569ea343c52 100644 --- a/src/infra/outbound/channel-selection.ts +++ b/src/infra/outbound/channel-selection.ts @@ -1,6 +1,6 @@ +import { listChannelPlugins } from "../../channels/plugins/index.js"; import type { ChannelPlugin } from "../../channels/plugins/types.js"; import type { OpenClawConfig } from "../../config/config.js"; -import { listChannelPlugins } from "../../channels/plugins/index.js"; import { defaultRuntime } from "../../runtime.js"; import { listDeliverableMessageChannels, diff --git a/src/plugins/bundle-mcp.ts b/src/plugins/bundle-mcp.ts index 620eb4a0a1f..ebe1b369f3c 100644 --- a/src/plugins/bundle-mcp.ts +++ b/src/plugins/bundle-mcp.ts @@ -1,7 +1,6 @@ import fs from "node:fs"; import path from "node:path"; import type { OpenClawConfig } from "../config/config.js"; -import type { PluginBundleFormat } from "./types.js"; import { applyMergePatch } from "../config/merge-patch.js"; import { openBoundaryFileSync } from "../infra/boundary-file-read.js"; import { isRecord } from "../utils.js"; @@ -15,6 +14,7 @@ import { 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; From 7fb142d11525ff528539d62398e3843d6d9b0255 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 09:42:13 -0700 Subject: [PATCH 03/67] test(whatsapp): override config-runtime mock exports safely --- extensions/whatsapp/src/test-helpers.ts | 90 +++++++++++++++---------- 1 file changed, 55 insertions(+), 35 deletions(-) diff --git a/extensions/whatsapp/src/test-helpers.ts b/extensions/whatsapp/src/test-helpers.ts index 74c5f8c3584..b71f25f9d63 100644 --- a/extensions/whatsapp/src/test-helpers.ts +++ b/extensions/whatsapp/src/test-helpers.ts @@ -36,44 +36,64 @@ vi.mock("openclaw/plugin-sdk/config-runtime", async (importOriginal) => { const actual = await importOriginal(); const mockModule = Object.create(null) as Record; Object.defineProperties(mockModule, Object.getOwnPropertyDescriptors(actual)); - Object.defineProperty(mockModule, "loadConfig", { - configurable: true, - enumerable: true, - writable: true, - value: () => { - const getter = (globalThis as Record)[CONFIG_KEY]; - if (typeof getter === "function") { - return getter(); - } - return DEFAULT_CONFIG; + Object.defineProperties(mockModule, { + loadConfig: { + configurable: true, + enumerable: true, + writable: true, + value: () => { + const getter = (globalThis as Record)[CONFIG_KEY]; + if (typeof getter === "function") { + return getter(); + } + return DEFAULT_CONFIG; + }, }, - }); - Object.assign(mockModule, { - updateLastRoute: async (params: { - storePath: string; - sessionKey: string; - deliveryContext: { channel: string; to: string; accountId?: string }; - }) => { - const raw = await fs.readFile(params.storePath, "utf8").catch(() => "{}"); - const store = JSON.parse(raw) as Record>; - const current = store[params.sessionKey] ?? {}; - store[params.sessionKey] = { - ...current, - lastChannel: params.deliveryContext.channel, - lastTo: params.deliveryContext.to, - lastAccountId: params.deliveryContext.accountId, - }; - await fs.writeFile(params.storePath, JSON.stringify(store)); + updateLastRoute: { + configurable: true, + enumerable: true, + writable: true, + value: async (params: { + storePath: string; + sessionKey: string; + deliveryContext: { channel: string; to: string; accountId?: string }; + }) => { + const raw = await fs.readFile(params.storePath, "utf8").catch(() => "{}"); + const store = JSON.parse(raw) as Record>; + const current = store[params.sessionKey] ?? {}; + store[params.sessionKey] = { + ...current, + lastChannel: params.deliveryContext.channel, + lastTo: params.deliveryContext.to, + lastAccountId: params.deliveryContext.accountId, + }; + await fs.writeFile(params.storePath, JSON.stringify(store)); + }, }, - loadSessionStore: (storePath: string) => { - try { - return JSON.parse(fsSync.readFileSync(storePath, "utf8")) as Record; - } catch { - return {}; - } + loadSessionStore: { + configurable: true, + enumerable: true, + writable: true, + value: (storePath: string) => { + try { + return JSON.parse(fsSync.readFileSync(storePath, "utf8")) as Record; + } catch { + return {}; + } + }, + }, + recordSessionMetaFromInbound: { + configurable: true, + enumerable: true, + writable: true, + value: async () => undefined, + }, + resolveStorePath: { + configurable: true, + enumerable: true, + writable: true, + value: actual.resolveStorePath, }, - recordSessionMetaFromInbound: async () => undefined, - resolveStorePath: actual.resolveStorePath, }); return mockModule; }); From 401ffb59f538488349664fa42e554dfb36d53a3a Mon Sep 17 00:00:00 2001 From: Harold Hunt Date: Thu, 19 Mar 2026 12:51:10 -0400 Subject: [PATCH 04/67] CLI: support versioned plugin updates (#49998) Merged via squash. Prepared head SHA: 545ea60fa26bb742376237ca83c65665133bcf7c Co-authored-by: huntharo <5617868+huntharo@users.noreply.github.com> Reviewed-by: @huntharo --- CHANGELOG.md | 1 + docs/cli/plugins.md | 14 +++- docs/tools/plugin.md | 2 +- src/cli/plugins-cli.test.ts | 134 ++++++++++++++++++++++++++++++++++++ src/cli/plugins-cli.ts | 59 +++++++++++++++- src/plugins/update.test.ts | 123 +++++++++++++++++++++++++++++++++ src/plugins/update.ts | 24 ++++--- 7 files changed, 345 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 50f4c317fb1..9a37dfe581c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -164,6 +164,7 @@ Docs: https://docs.openclaw.ai - WhatsApp/active-listener: pin the active listener registry to a `globalThis` singleton so split WhatsApp bundle chunks share one listener map and outbound sends stop missing the registered session. (#47433) Thanks @clawdia67. - 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. ### Breaking diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index 47ef4930b8a..3d4c482707f 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -138,14 +138,24 @@ state dir extensions root (`$OPENCLAW_STATE_DIR/extensions/`). Use ### Update ```bash -openclaw plugins update +openclaw plugins update openclaw plugins update --all -openclaw plugins update --dry-run +openclaw plugins update --dry-run +openclaw plugins update @openclaw/voice-call@beta ``` Updates apply to tracked installs in `plugins.installs`, currently npm and marketplace installs. +When you pass a plugin id, OpenClaw reuses the recorded install spec for that +plugin. That means previously stored dist-tags such as `@beta` and exact pinned +versions continue to be used on later `update ` runs. + +For npm installs, you can also pass an explicit npm package spec with a dist-tag +or exact version. OpenClaw resolves that package name back to the tracked plugin +record, updates that installed plugin, and records the new npm spec for future +id-based updates. + When a stored integrity hash exists and the fetched artifact hash changes, OpenClaw prints a warning and asks for confirmation before proceeding. Use global `--yes` to bypass prompts in CI/non-interactive runs. diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 48b60d3fe1d..16291eab32d 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -286,7 +286,7 @@ openclaw plugins install ./plugin.zip # install from a local zip openclaw plugins install -l ./extensions/voice-call # link (no copy) for dev openclaw plugins install @openclaw/voice-call # install from npm openclaw plugins install @openclaw/voice-call --pin # store exact resolved name@version -openclaw plugins update +openclaw plugins update openclaw plugins update --all openclaw plugins enable openclaw plugins disable diff --git a/src/cli/plugins-cli.test.ts b/src/cli/plugins-cli.test.ts index 50bc8633e70..4efb1990354 100644 --- a/src/cli/plugins-cli.test.ts +++ b/src/cli/plugins-cli.test.ts @@ -379,6 +379,140 @@ describe("plugins cli", () => { expect(runtimeLogs.at(-1)).toBe("No tracked plugins to update."); }); + it("maps an explicit unscoped npm dist-tag update to the tracked plugin id", async () => { + const config = { + plugins: { + installs: { + "openclaw-codex-app-server": { + source: "npm", + spec: "openclaw-codex-app-server", + installPath: "/tmp/openclaw-codex-app-server", + resolvedName: "openclaw-codex-app-server", + }, + }, + }, + } as OpenClawConfig; + loadConfig.mockReturnValue(config); + updateNpmInstalledPlugins.mockResolvedValue({ + config, + changed: false, + outcomes: [], + }); + + await runCommand(["plugins", "update", "openclaw-codex-app-server@beta"]); + + expect(updateNpmInstalledPlugins).toHaveBeenCalledWith( + expect.objectContaining({ + config, + pluginIds: ["openclaw-codex-app-server"], + specOverrides: { + "openclaw-codex-app-server": "openclaw-codex-app-server@beta", + }, + }), + ); + }); + + it("maps an explicit scoped npm dist-tag update to the tracked plugin id", async () => { + const config = { + plugins: { + installs: { + "voice-call": { + source: "npm", + spec: "@openclaw/voice-call", + installPath: "/tmp/voice-call", + resolvedName: "@openclaw/voice-call", + }, + }, + }, + } as OpenClawConfig; + loadConfig.mockReturnValue(config); + updateNpmInstalledPlugins.mockResolvedValue({ + config, + changed: false, + outcomes: [], + }); + + await runCommand(["plugins", "update", "@openclaw/voice-call@beta"]); + + expect(updateNpmInstalledPlugins).toHaveBeenCalledWith( + expect.objectContaining({ + config, + pluginIds: ["voice-call"], + specOverrides: { + "voice-call": "@openclaw/voice-call@beta", + }, + }), + ); + }); + + it("maps an explicit npm version update to the tracked plugin id", async () => { + const config = { + plugins: { + installs: { + "openclaw-codex-app-server": { + source: "npm", + spec: "openclaw-codex-app-server", + installPath: "/tmp/openclaw-codex-app-server", + resolvedName: "openclaw-codex-app-server", + }, + }, + }, + } as OpenClawConfig; + loadConfig.mockReturnValue(config); + updateNpmInstalledPlugins.mockResolvedValue({ + config, + changed: false, + outcomes: [], + }); + + await runCommand(["plugins", "update", "openclaw-codex-app-server@0.2.0-beta.4"]); + + expect(updateNpmInstalledPlugins).toHaveBeenCalledWith( + expect.objectContaining({ + config, + pluginIds: ["openclaw-codex-app-server"], + specOverrides: { + "openclaw-codex-app-server": "openclaw-codex-app-server@0.2.0-beta.4", + }, + }), + ); + }); + + it("keeps using the recorded npm tag when update is invoked by plugin id", async () => { + const config = { + plugins: { + installs: { + "openclaw-codex-app-server": { + source: "npm", + spec: "openclaw-codex-app-server@beta", + installPath: "/tmp/openclaw-codex-app-server", + resolvedName: "openclaw-codex-app-server", + }, + }, + }, + } as OpenClawConfig; + loadConfig.mockReturnValue(config); + updateNpmInstalledPlugins.mockResolvedValue({ + config, + changed: false, + outcomes: [], + }); + + await runCommand(["plugins", "update", "openclaw-codex-app-server"]); + + expect(updateNpmInstalledPlugins).toHaveBeenCalledWith( + expect.objectContaining({ + config, + pluginIds: ["openclaw-codex-app-server"], + }), + ); + expect(updateNpmInstalledPlugins).not.toHaveBeenCalledWith( + expect.objectContaining({ + specOverrides: expect.anything(), + }), + ); + }); + it("writes updated config when updater reports changes", async () => { const cfg = { plugins: { diff --git a/src/cli/plugins-cli.ts b/src/cli/plugins-cli.ts index 79fca829281..93e3d22c8d5 100644 --- a/src/cli/plugins-cli.ts +++ b/src/cli/plugins-cli.ts @@ -7,6 +7,7 @@ import { loadConfig, writeConfigFile } from "../config/config.js"; import { resolveStateDir } from "../config/paths.js"; import type { PluginInstallRecord } from "../config/types.plugins.js"; import { resolveArchiveKind } from "../infra/archive.js"; +import { parseRegistryNpmSpec } from "../infra/npm-registry-spec.js"; import { type BundledPluginSource, findBundledPluginSource } from "../plugins/bundled-sources.js"; import { enablePluginInConfig } from "../plugins/enable.js"; import { installPluginFromNpmSpec, installPluginFromPath } from "../plugins/install.js"; @@ -227,6 +228,56 @@ function createPluginInstallLogger(): { info: (msg: string) => void; warn: (msg: }; } +function extractInstalledNpmPackageName(install: PluginInstallRecord): string | undefined { + if (install.source !== "npm") { + return undefined; + } + const resolvedName = install.resolvedName?.trim(); + if (resolvedName) { + return resolvedName; + } + return ( + (install.spec ? parseRegistryNpmSpec(install.spec)?.name : undefined) ?? + (install.resolvedSpec ? parseRegistryNpmSpec(install.resolvedSpec)?.name : undefined) + ); +} + +function resolvePluginUpdateSelection(params: { + installs: Record; + rawId?: string; + all?: boolean; +}): { pluginIds: string[]; specOverrides?: Record } { + if (params.all) { + return { pluginIds: Object.keys(params.installs) }; + } + if (!params.rawId) { + return { pluginIds: [] }; + } + + const parsedSpec = parseRegistryNpmSpec(params.rawId); + if (!parsedSpec || parsedSpec.selectorKind === "none") { + return { pluginIds: [params.rawId] }; + } + + const matches = Object.entries(params.installs).filter(([, install]) => { + return extractInstalledNpmPackageName(install) === parsedSpec.name; + }); + if (matches.length !== 1) { + return { pluginIds: [params.rawId] }; + } + + const [pluginId] = matches[0]; + if (!pluginId) { + return { pluginIds: [params.rawId] }; + } + return { + pluginIds: [pluginId], + specOverrides: { + [pluginId]: parsedSpec.raw, + }, + }; +} + function logSlotWarnings(warnings: string[]) { if (warnings.length === 0) { return; @@ -1032,7 +1083,12 @@ export function registerPluginsCli(program: Command) { .action(async (id: string | undefined, opts: PluginUpdateOptions) => { const cfg = loadConfig(); const installs = cfg.plugins?.installs ?? {}; - const targets = opts.all ? Object.keys(installs) : id ? [id] : []; + const selection = resolvePluginUpdateSelection({ + installs, + rawId: id, + all: opts.all, + }); + const targets = selection.pluginIds; if (targets.length === 0) { if (opts.all) { @@ -1046,6 +1102,7 @@ export function registerPluginsCli(program: Command) { const result = await updateNpmInstalledPlugins({ config: cfg, pluginIds: targets, + specOverrides: selection.specOverrides, dryRun: opts.dryRun, logger: { info: (msg) => defaultRuntime.log(msg), diff --git a/src/plugins/update.test.ts b/src/plugins/update.test.ts index 7e93ab7ba50..96c15443ded 100644 --- a/src/plugins/update.test.ts +++ b/src/plugins/update.test.ts @@ -161,6 +161,129 @@ describe("updateNpmInstalledPlugins", () => { ]); }); + it("reuses a recorded npm dist-tag spec for id-based updates", async () => { + installPluginFromNpmSpecMock.mockResolvedValue({ + ok: true, + pluginId: "openclaw-codex-app-server", + targetDir: "/tmp/openclaw-codex-app-server", + version: "0.2.0-beta.4", + extensions: ["index.ts"], + }); + + const result = await updateNpmInstalledPlugins({ + config: { + plugins: { + installs: { + "openclaw-codex-app-server": { + source: "npm", + spec: "openclaw-codex-app-server@beta", + installPath: "/tmp/openclaw-codex-app-server", + resolvedName: "openclaw-codex-app-server", + resolvedSpec: "openclaw-codex-app-server@0.2.0-beta.3", + }, + }, + }, + }, + pluginIds: ["openclaw-codex-app-server"], + }); + + expect(installPluginFromNpmSpecMock).toHaveBeenCalledWith( + expect.objectContaining({ + spec: "openclaw-codex-app-server@beta", + expectedPluginId: "openclaw-codex-app-server", + }), + ); + expect(result.config.plugins?.installs?.["openclaw-codex-app-server"]).toMatchObject({ + source: "npm", + spec: "openclaw-codex-app-server@beta", + installPath: "/tmp/openclaw-codex-app-server", + version: "0.2.0-beta.4", + }); + }); + + it("uses and persists an explicit npm spec override during updates", async () => { + installPluginFromNpmSpecMock.mockResolvedValue({ + ok: true, + pluginId: "openclaw-codex-app-server", + targetDir: "/tmp/openclaw-codex-app-server", + version: "0.2.0-beta.4", + extensions: ["index.ts"], + npmResolution: { + name: "openclaw-codex-app-server", + version: "0.2.0-beta.4", + resolvedSpec: "openclaw-codex-app-server@0.2.0-beta.4", + }, + }); + + const result = await updateNpmInstalledPlugins({ + config: { + plugins: { + installs: { + "openclaw-codex-app-server": { + source: "npm", + spec: "openclaw-codex-app-server", + installPath: "/tmp/openclaw-codex-app-server", + }, + }, + }, + }, + pluginIds: ["openclaw-codex-app-server"], + specOverrides: { + "openclaw-codex-app-server": "openclaw-codex-app-server@beta", + }, + }); + + expect(installPluginFromNpmSpecMock).toHaveBeenCalledWith( + expect.objectContaining({ + spec: "openclaw-codex-app-server@beta", + expectedPluginId: "openclaw-codex-app-server", + }), + ); + expect(result.config.plugins?.installs?.["openclaw-codex-app-server"]).toMatchObject({ + source: "npm", + spec: "openclaw-codex-app-server@beta", + installPath: "/tmp/openclaw-codex-app-server", + version: "0.2.0-beta.4", + resolvedSpec: "openclaw-codex-app-server@0.2.0-beta.4", + }); + }); + + it("skips recorded integrity checks when an explicit npm version override changes the spec", async () => { + installPluginFromNpmSpecMock.mockResolvedValue({ + ok: true, + pluginId: "openclaw-codex-app-server", + targetDir: "/tmp/openclaw-codex-app-server", + version: "0.2.0-beta.4", + extensions: ["index.ts"], + }); + + await updateNpmInstalledPlugins({ + config: { + plugins: { + installs: { + "openclaw-codex-app-server": { + source: "npm", + spec: "openclaw-codex-app-server@0.2.0-beta.3", + integrity: "sha512-old", + installPath: "/tmp/openclaw-codex-app-server", + }, + }, + }, + }, + pluginIds: ["openclaw-codex-app-server"], + specOverrides: { + "openclaw-codex-app-server": "openclaw-codex-app-server@0.2.0-beta.4", + }, + }); + + expect(installPluginFromNpmSpecMock).toHaveBeenCalledWith( + expect.objectContaining({ + spec: "openclaw-codex-app-server@0.2.0-beta.4", + expectedIntegrity: undefined, + }), + ); + }); + it("migrates legacy unscoped install keys when a scoped npm package updates", async () => { installPluginFromNpmSpecMock.mockResolvedValue({ ok: true, diff --git a/src/plugins/update.ts b/src/plugins/update.ts index 83733159cac..6898135e527 100644 --- a/src/plugins/update.ts +++ b/src/plugins/update.ts @@ -291,6 +291,7 @@ export async function updateNpmInstalledPlugins(params: { pluginIds?: string[]; skipIds?: Set; dryRun?: boolean; + specOverrides?: Record; onIntegrityDrift?: (params: PluginUpdateIntegrityDriftParams) => boolean | Promise; }): Promise { const logger = params.logger ?? {}; @@ -329,7 +330,14 @@ export async function updateNpmInstalledPlugins(params: { continue; } - if (record.source === "npm" && !record.spec) { + const effectiveSpec = + record.source === "npm" ? (params.specOverrides?.[pluginId] ?? record.spec) : undefined; + const expectedIntegrity = + record.source === "npm" && effectiveSpec === record.spec + ? expectedIntegrityForUpdate(record.spec, record.integrity) + : undefined; + + if (record.source === "npm" && !effectiveSpec) { outcomes.push({ pluginId, status: "skipped", @@ -371,11 +379,11 @@ export async function updateNpmInstalledPlugins(params: { probe = record.source === "npm" ? await installPluginFromNpmSpec({ - spec: record.spec!, + spec: effectiveSpec!, mode: "update", dryRun: true, expectedPluginId: pluginId, - expectedIntegrity: expectedIntegrityForUpdate(record.spec, record.integrity), + expectedIntegrity, onIntegrityDrift: createPluginUpdateIntegrityDriftHandler({ pluginId, dryRun: true, @@ -408,7 +416,7 @@ export async function updateNpmInstalledPlugins(params: { record.source === "npm" ? formatNpmInstallFailure({ pluginId, - spec: record.spec!, + spec: effectiveSpec!, phase: "check", result: probe, }) @@ -452,10 +460,10 @@ export async function updateNpmInstalledPlugins(params: { result = record.source === "npm" ? await installPluginFromNpmSpec({ - spec: record.spec!, + spec: effectiveSpec!, mode: "update", expectedPluginId: pluginId, - expectedIntegrity: expectedIntegrityForUpdate(record.spec, record.integrity), + expectedIntegrity, onIntegrityDrift: createPluginUpdateIntegrityDriftHandler({ pluginId, dryRun: false, @@ -487,7 +495,7 @@ export async function updateNpmInstalledPlugins(params: { record.source === "npm" ? formatNpmInstallFailure({ pluginId, - spec: record.spec!, + spec: effectiveSpec!, phase: "update", result: result, }) @@ -512,7 +520,7 @@ export async function updateNpmInstalledPlugins(params: { next = recordPluginInstall(next, { pluginId: resolvedPluginId, source: "npm", - spec: record.spec, + spec: effectiveSpec, installPath: result.targetDir, version: nextVersion, ...buildNpmResolutionInstallFields(result.npmResolution), From 3dfd8eef7f949b640f5f1e21cf7767578458ea46 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 09:55:43 -0700 Subject: [PATCH 05/67] ci(node22): drop duplicate config docs check from compat lane --- .github/workflows/ci.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 96ab35a297e..8f87c816488 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -496,7 +496,9 @@ jobs: run: pnpm test - name: Verify npm pack under Node 22 - run: pnpm release:check + run: | + node scripts/stage-bundled-plugin-runtime-deps.mjs + node --import tsx scripts/release-check.ts skills-python: needs: [docs-scope, changed-scope] From 36f394c299a91301a84c455be2bdb418eeb2d08e Mon Sep 17 00:00:00 2001 From: fuller-stack-dev Date: Thu, 19 Mar 2026 11:16:40 -0600 Subject: [PATCH 06/67] fix(gateway): increase WS handshake timeout from 3s to 10s (#49262) * fix(gateway): increase WS handshake timeout from 3s to 10s The 3-second default is too aggressive when the event loop is under load (concurrent sessions, compaction, agent turns), causing spurious 'gateway closed (1000)' errors on CLI commands like `openclaw cron list`. Changes: - Increase DEFAULT_HANDSHAKE_TIMEOUT_MS from 3_000 to 10_000 - Add OPENCLAW_HANDSHAKE_TIMEOUT_MS env var for user override (no VITEST gate) - Keep OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS as fallback for existing tests Fixes #46892 * fix: restore VITEST guard on test env var, use || for empty-string fallback, fix formatting * fix: cover gateway handshake timeout env override (#49262) (thanks @fuller-stack-dev) --------- Co-authored-by: Wilfred Co-authored-by: Ayaan Zaidi --- CHANGELOG.md | 1 + src/gateway/server-constants.ts | 10 +++++--- .../server.auth.default-token.suite.ts | 23 +++++++++++++++++++ 3 files changed, 31 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a37dfe581c..43aff8bd18c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -118,6 +118,7 @@ Docs: https://docs.openclaw.ai - Slack/startup: harden `@slack/bolt` import interop across current bundled runtime shapes so Slack monitors no longer crash with `App is not a constructor` after plugin-sdk bundling changes. (#45953) Thanks @merc1305. - Windows/gateway status: accept `schtasks` `Last Result` output as an alias for `Last Run Result`, so running scheduled-task installs no longer show `Runtime: unknown`. (#47844) Thanks @MoerAI. - ACP/acpx: resolve the bundled plugin root from the actual plugin directory so plugin-local installs stay under `dist/extensions/acpx` instead of escaping to `dist/extensions` and failing runtime setup. (#47601) Thanks @ngutman. +- Gateway/WS handshake: raise the default pre-auth handshake timeout to 10 seconds and add `OPENCLAW_HANDSHAKE_TIMEOUT_MS` as a runtime override so busy local gateways stop dropping healthy CLI connections at 3 seconds. (#49262) Thanks @fuller-stack-dev. - Gateway/websocket pairing bypass for disabled auth: skip device-pairing enforcement for Control UI operator sessions when `gateway.auth.mode=none`, so reverse-proxied dashboards no longer get stuck on `pairing required` despite auth being explicitly disabled. (#47148) Thanks @ademczuk. - Control UI/model switching: preserve the selected provider prefix when switching models from the chat dropdown, so multi-provider setups no longer send `anthropic/gpt-5.2`-style mismatches when the user picked `openai/gpt-5.2`. (#47581) Thanks @chrishham. - Control UI/storage: scope persisted settings keys by gateway base path, with migration from the legacy shared key, so multiple gateways under one domain stop overwriting each other's dashboard preferences. (#47932) Thanks @bobBot-claw. diff --git a/src/gateway/server-constants.ts b/src/gateway/server-constants.ts index 036ebc5b3fa..54dc3f794b6 100644 --- a/src/gateway/server-constants.ts +++ b/src/gateway/server-constants.ts @@ -21,10 +21,14 @@ export const __setMaxChatHistoryMessagesBytesForTest = (value?: number) => { maxChatHistoryMessagesBytes = value; } }; -export const DEFAULT_HANDSHAKE_TIMEOUT_MS = 3_000; +export const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000; export const getHandshakeTimeoutMs = () => { - if (process.env.VITEST && process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS) { - const parsed = Number(process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS); + // User-facing env var (works in all environments); test-only var gated behind VITEST + const envKey = + process.env.OPENCLAW_HANDSHAKE_TIMEOUT_MS || + (process.env.VITEST && process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS); + if (envKey) { + const parsed = Number(envKey); if (Number.isFinite(parsed) && parsed > 0) { return parsed; } diff --git a/src/gateway/server.auth.default-token.suite.ts b/src/gateway/server.auth.default-token.suite.ts index 4d090b78cb3..ed15150a029 100644 --- a/src/gateway/server.auth.default-token.suite.ts +++ b/src/gateway/server.auth.default-token.suite.ts @@ -93,6 +93,29 @@ export function registerDefaultAuthTokenSuite(): void { } }); + test("prefers OPENCLAW_HANDSHAKE_TIMEOUT_MS and falls back on empty string", () => { + const prevHandshakeTimeout = process.env.OPENCLAW_HANDSHAKE_TIMEOUT_MS; + const prevTestHandshakeTimeout = process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS; + process.env.OPENCLAW_HANDSHAKE_TIMEOUT_MS = "75"; + process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS = "20"; + try { + expect(getHandshakeTimeoutMs()).toBe(75); + process.env.OPENCLAW_HANDSHAKE_TIMEOUT_MS = ""; + expect(getHandshakeTimeoutMs()).toBe(20); + } finally { + if (prevHandshakeTimeout === undefined) { + delete process.env.OPENCLAW_HANDSHAKE_TIMEOUT_MS; + } else { + process.env.OPENCLAW_HANDSHAKE_TIMEOUT_MS = prevHandshakeTimeout; + } + if (prevTestHandshakeTimeout === undefined) { + delete process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS; + } else { + process.env.OPENCLAW_TEST_HANDSHAKE_TIMEOUT_MS = prevTestHandshakeTimeout; + } + } + }); + test("connect (req) handshake returns hello-ok payload", async () => { const { STATE_DIR, createConfigIO } = await import("../config/config.js"); const ws = await openWs(port); From 65a2917c8f741b464e3d883a104c2422a1aa4b95 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 10:27:41 -0700 Subject: [PATCH 07/67] docs: remove pi-mono jargon, fix features list, update Perplexity config path --- docs/concepts/agent.md | 15 ++++++--------- docs/concepts/features.md | 7 +------ docs/providers/perplexity-provider.md | 10 ++++++++-- 3 files changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/concepts/agent.md b/docs/concepts/agent.md index 26d677745e4..57aff200e04 100644 --- a/docs/concepts/agent.md +++ b/docs/concepts/agent.md @@ -1,13 +1,13 @@ --- -summary: "Agent runtime (embedded pi-mono), workspace contract, and session bootstrap" +summary: "Agent runtime, workspace contract, and session bootstrap" read_when: - Changing agent runtime, workspace bootstrap, or session behavior title: "Agent Runtime" --- -# Agent Runtime 🤖 +# Agent Runtime -OpenClaw runs a single embedded agent runtime derived from **pi-mono**. +OpenClaw runs a single embedded agent runtime. ## Workspace (required) @@ -63,12 +63,9 @@ OpenClaw loads skills from three locations (workspace wins on name conflict): Skills can be gated by config/env (see `skills` in [Gateway configuration](/gateway/configuration)). -## pi-mono integration +## Runtime boundaries -OpenClaw reuses pieces of the pi-mono codebase (models/tools), but **session management, discovery, and tool wiring are OpenClaw-owned**. - -- No pi-coding agent runtime. -- No `~/.pi/agent` or `/.pi` settings are consulted. +Session management, discovery, and tool wiring are OpenClaw-owned. ## Sessions @@ -77,7 +74,7 @@ Session transcripts are stored as JSONL at: - `~/.openclaw/agents//sessions/.jsonl` The session ID is stable and chosen by OpenClaw. -Legacy Pi/Tau session folders are **not** read. +Legacy session folders from other tools are not read. ## Steering while streaming diff --git a/docs/concepts/features.md b/docs/concepts/features.md index 03528032b40..47e0d804c5d 100644 --- a/docs/concepts/features.md +++ b/docs/concepts/features.md @@ -37,7 +37,7 @@ title: "Features" - Discord bot support (channels.discord.js) - Mattermost bot support (plugin) - iMessage integration via local imsg CLI (macOS) -- Agent bridge for Pi in RPC mode with tool streaming +- Embedded agent runtime with tool streaming - Streaming and chunking for long responses - Multi-agent routing for isolated sessions per workspace or sender - Subscription auth for Anthropic and OpenAI via OAuth @@ -48,8 +48,3 @@ title: "Features" - WebChat and macOS menu bar app - iOS node with pairing, Canvas, camera, screen recording, location, and voice features - Android node with pairing, Connect tab, chat sessions, voice tab, Canvas/camera, plus device, notifications, contacts/calendar, motion, photos, and SMS commands - - -Legacy Claude, Codex, Gemini, and Opencode paths have been removed. Pi is the only -coding agent path. - diff --git a/docs/providers/perplexity-provider.md b/docs/providers/perplexity-provider.md index c0945627e39..63880385353 100644 --- a/docs/providers/perplexity-provider.md +++ b/docs/providers/perplexity-provider.md @@ -18,14 +18,20 @@ This page covers the Perplexity **provider** setup. For the Perplexity - Type: web search provider (not a model provider) - Auth: `PERPLEXITY_API_KEY` (direct) or `OPENROUTER_API_KEY` (via OpenRouter) -- Config path: `tools.web.search.perplexity.apiKey` +- Config path: `plugins.entries.perplexity.config.webSearch.apiKey` ## Quick start 1. Set the API key: ```bash -openclaw config set tools.web.search.perplexity.apiKey "pplx-xxxxxxxxxxxx" +openclaw configure --section web +``` + +Or set it directly: + +```bash +openclaw config set plugins.entries.perplexity.config.webSearch.apiKey "pplx-xxxxxxxxxxxx" ``` 2. The agent will automatically use Perplexity for web searches when configured. From 1dd857f6a6a43b0f47999ec0b8d9021e1c009909 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 10:28:44 -0700 Subject: [PATCH 08/67] docs: add API key prereq, first-message step, fix landing page quick start --- docs/index.md | 12 +++++++---- docs/start/getting-started.md | 39 +++++++++++++---------------------- 2 files changed, 22 insertions(+), 29 deletions(-) diff --git a/docs/index.md b/docs/index.md index 25162bc9676..270f0835287 100644 --- a/docs/index.md +++ b/docs/index.md @@ -106,15 +106,19 @@ The Gateway is the single source of truth for sessions, routing, and channel con openclaw onboard --install-daemon ``` - + + Open the Control UI in your browser and send a message: + ```bash - openclaw channels login - openclaw gateway --port 18789 + openclaw dashboard ``` + + Or connect a channel ([Telegram](/channels/telegram) is fastest) and chat from your phone. + -Need the full install and dev setup? See [Quick start](/start/quickstart). +Need the full install and dev setup? See [Getting Started](/start/getting-started). ## Dashboard diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md index bd3f554cdc4..fa719093739 100644 --- a/docs/start/getting-started.md +++ b/docs/start/getting-started.md @@ -20,9 +20,11 @@ Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui). ## Prereqs - Node 24 recommended (Node 22 LTS, currently `22.16+`, still supported for compatibility) +- An API key from a model provider (Anthropic, OpenAI, Google, etc.) — onboarding will prompt you for this Check your Node version with `node --version` if you are unsure. +Windows users: WSL2 is strongly recommended. See [Windows](/platforms/windows). ## Quick setup (CLI) @@ -73,34 +75,21 @@ Check your Node version with `node --version` if you are unsure. ```bash openclaw dashboard ``` + + If the Control UI loads, your Gateway is ready. + + + + The fastest way to chat is directly in the Control UI browser tab. + Type a message and you should get an AI reply. + + Want to chat from a messaging app instead? The fastest channel setup + is usually [Telegram](/channels/telegram) (just a bot token, no QR + pairing). See [Channels](/channels) for all options. + - -If the Control UI loads, your Gateway is ready for use. - - -## Optional checks and extras - - - - Useful for quick tests or troubleshooting. - - ```bash - openclaw gateway --port 18789 - ``` - - - - Requires a configured channel. - - ```bash - openclaw message send --target +15555550123 --message "Hello from OpenClaw" - ``` - - - - ## Useful environment variables If you run OpenClaw as a service account or want custom config/state locations: From 624d5365513eb230545ac2c5ef9270f69025dcf5 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 10:29:57 -0700 Subject: [PATCH 09/67] docs: remove quickstart stub from hubs, add redirect to getting-started --- docs/docs.json | 11 ++++++++++- docs/start/hubs.md | 1 - 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index e80697ac63d..772a8a476cd 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -47,6 +47,10 @@ ] }, "redirects": [ + { + "source": "/start/quickstart", + "destination": "/start/getting-started" + }, { "source": "/messages", "destination": "/concepts/messages" @@ -880,6 +884,7 @@ "group": "Hosting and deployment", "pages": [ "vps", + "install/docker-vm-runtime", "install/kubernetes", "install/fly", "install/hetzner", @@ -1024,7 +1029,8 @@ "pages": [ "tools/browser", "tools/browser-login", - "tools/browser-linux-troubleshooting" + "tools/browser-linux-troubleshooting", + "tools/browser-wsl2-windows-remote-cdp-troubleshooting" ] }, { @@ -1211,6 +1217,7 @@ "gateway/heartbeat", "gateway/doctor", "gateway/logging", + "logging", "gateway/gateway-lock", "gateway/background-process", "gateway/multiple-gateways", @@ -1241,6 +1248,7 @@ { "group": "Networking and discovery", "pages": [ + "network", "gateway/network-model", "gateway/pairing", "gateway/discovery", @@ -1278,6 +1286,7 @@ "cli/agent", "cli/agents", "cli/approvals", + "cli/backup", "cli/browser", "cli/channels", "cli/clawbot", diff --git a/docs/start/hubs.md b/docs/start/hubs.md index 260ec771de1..7e530f769b5 100644 --- a/docs/start/hubs.md +++ b/docs/start/hubs.md @@ -17,7 +17,6 @@ Use these hubs to discover every page, including deep dives and reference docs t - [Index](/) - [Getting Started](/start/getting-started) -- [Quick start](/start/quickstart) - [Onboarding](/start/onboarding) - [Onboarding (CLI)](/start/wizard) - [Setup](/start/setup) From 0b11ee48f81daa087b335e134a4b7f948ae6534e Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 19 Mar 2026 10:31:20 -0700 Subject: [PATCH 10/67] docs: fix 26 broken anchor links across 18 files --- docs/automation/hooks.md | 2 +- docs/channels/groups.md | 2 +- docs/channels/matrix.md | 2 ++ docs/channels/signal.md | 2 +- docs/channels/troubleshooting.md | 4 ++-- docs/concepts/memory.md | 2 +- docs/concepts/messages.md | 2 +- docs/concepts/models.md | 6 +++--- docs/concepts/oauth.md | 2 +- docs/gateway/configuration.md | 6 +++--- docs/gateway/sandboxing.md | 2 +- docs/gateway/security/index.md | 4 ++-- docs/help/environment.md | 2 +- docs/help/faq.md | 22 +++++++++++----------- docs/help/index.md | 2 +- docs/install/docker.md | 2 +- docs/providers/anthropic.md | 4 ++-- docs/tools/browser.md | 2 +- docs/tools/multi-agent-sandbox-tools.md | 2 +- 19 files changed, 37 insertions(+), 35 deletions(-) diff --git a/docs/automation/hooks.md b/docs/automation/hooks.md index a470bef8540..4d7dbd02533 100644 --- a/docs/automation/hooks.md +++ b/docs/automation/hooks.md @@ -1046,4 +1046,4 @@ node -e "import('./path/to/handler.ts').then(console.log)" - [CLI Reference: hooks](/cli/hooks) - [Bundled Hooks README](https://github.com/openclaw/openclaw/tree/main/src/hooks/bundled) - [Webhook Hooks](/automation/webhook) -- [Configuration](/gateway/configuration#hooks) +- [Configuration](/gateway/configuration-reference#hooks) diff --git a/docs/channels/groups.md b/docs/channels/groups.md index a6bd8621784..8895cdd18f9 100644 --- a/docs/channels/groups.md +++ b/docs/channels/groups.md @@ -116,7 +116,7 @@ Want “groups can only see folder X” instead of “no host access”? Keep `w Related: -- Configuration keys and defaults: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox) +- Configuration keys and defaults: [Gateway configuration](/gateway/configuration-reference#agents-defaults-sandbox) - Debugging why a tool is blocked: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) - Bind mounts details: [Sandboxing](/gateway/sandboxing#custom-bind-mounts) diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md index d6ec40ff4db..360bc706748 100644 --- a/docs/channels/matrix.md +++ b/docs/channels/matrix.md @@ -204,6 +204,8 @@ Bootstrap cross-signing and verification state: openclaw matrix verify bootstrap ``` +Multi-account support: use `channels.matrix.accounts` with per-account credentials and optional `name`. See [Configuration reference](/gateway/configuration-reference#multi-account-all-channels) for the shared pattern. + Verbose bootstrap diagnostics: ```bash diff --git a/docs/channels/signal.md b/docs/channels/signal.md index cfc050b6e75..fb5747dc417 100644 --- a/docs/channels/signal.md +++ b/docs/channels/signal.md @@ -99,7 +99,7 @@ Example: } ``` -Multi-account support: use `channels.signal.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern. +Multi-account support: use `channels.signal.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration-reference#multi-account-all-channels) for the shared pattern. ## Setup path B: register dedicated bot number (SMS, Linux) diff --git a/docs/channels/troubleshooting.md b/docs/channels/troubleshooting.md index a7850801948..106710ca926 100644 --- a/docs/channels/troubleshooting.md +++ b/docs/channels/troubleshooting.md @@ -38,7 +38,7 @@ Healthy baseline: | Group messages ignored | Check `requireMention` + mention patterns in config | Mention the bot or relax mention policy for that group. | | Random disconnect/relogin loops | `openclaw channels status --probe` + logs | Re-login and verify credentials directory is healthy. | -Full troubleshooting: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick) +Full troubleshooting: [/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting) ## Telegram @@ -90,7 +90,7 @@ Full troubleshooting: [/channels/slack#troubleshooting](/channels/slack#troubles Full troubleshooting: -- [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc) +- [/channels/imessage#troubleshooting](/channels/imessage#troubleshooting) - [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting) ## Signal diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md index 2649125dc45..e020d4a9a49 100644 --- a/docs/concepts/memory.md +++ b/docs/concepts/memory.md @@ -208,7 +208,7 @@ out to QMD for retrieval. Key points: `commandTimeoutMs`, `updateTimeoutMs`, `embedTimeoutMs`). - `limits`: clamp recall payload (`maxResults`, `maxSnippetChars`, `maxInjectedChars`, `timeoutMs`). -- `scope`: same schema as [`session.sendPolicy`](/gateway/configuration#session). +- `scope`: same schema as [`session.sendPolicy`](/gateway/configuration-reference#session). Default is DM-only (`deny` all, `allow` direct chats); loosen it to surface QMD hits in groups/channels. - `match.keyPrefix` matches the **normalized** session key (lowercased, with any diff --git a/docs/concepts/messages.md b/docs/concepts/messages.md index 4930002187e..e94092e7bbc 100644 --- a/docs/concepts/messages.md +++ b/docs/concepts/messages.md @@ -151,4 +151,4 @@ Outbound message formatting is centralized in `messages`: - `messages.responsePrefix`, `channels..responsePrefix`, and `channels..accounts..responsePrefix` (outbound prefix cascade), plus `channels.whatsapp.messagePrefix` (WhatsApp inbound prefix) - Reply threading via `replyToMode` and per-channel defaults -Details: [Configuration](/gateway/configuration#messages) and channel docs. +Details: [Configuration](/gateway/configuration-reference#messages) and channel docs. diff --git a/docs/concepts/models.md b/docs/concepts/models.md index 0a32e1b5d8b..d9a76cabc64 100644 --- a/docs/concepts/models.md +++ b/docs/concepts/models.md @@ -58,7 +58,7 @@ Model refs are normalized to lowercase. Provider aliases like `z.ai/*` normalize to `zai/*`. Provider configuration examples (including OpenCode) live in -[/gateway/configuration](/gateway/configuration#opencode). +[/providers/opencode](/providers/opencode). ## "Model is not allowed" (and why replies stop) @@ -82,9 +82,9 @@ Example allowlist config: ```json5 { agent: { - model: { primary: "anthropic/claude-sonnet-4-5" }, + model: { primary: "anthropic/claude-sonnet-4-6" }, models: { - "anthropic/claude-sonnet-4-5": { alias: "Sonnet" }, + "anthropic/claude-sonnet-4-6": { alias: "Sonnet" }, "anthropic/claude-opus-4-6": { alias: "Opus" }, }, }, diff --git a/docs/concepts/oauth.md b/docs/concepts/oauth.md index 4766687ad51..2589dcaa8f9 100644 --- a/docs/concepts/oauth.md +++ b/docs/concepts/oauth.md @@ -50,7 +50,7 @@ Legacy import-only file (still supported, but not the main store): - `~/.openclaw/credentials/oauth.json` (imported into `auth-profiles.json` on first use) -All of the above also respect `$OPENCLAW_STATE_DIR` (state dir override). Full reference: [/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys) +All of the above also respect `$OPENCLAW_STATE_DIR` (state dir override). Full reference: [/gateway/configuration](/gateway/configuration-reference#auth-storage) For static secret refs and runtime snapshot activation behavior, see [Secrets Management](/gateway/secrets). diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index b8977ca10ac..42977c2b6f1 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -112,11 +112,11 @@ When validation fails: agents: { defaults: { model: { - primary: "anthropic/claude-sonnet-4-5", + primary: "anthropic/claude-sonnet-4-6", fallbacks: ["openai/gpt-5.2"], }, models: { - "anthropic/claude-sonnet-4-5": { alias: "Sonnet" }, + "anthropic/claude-sonnet-4-6": { alias: "Sonnet" }, "openai/gpt-5.2": { alias: "GPT" }, }, }, @@ -251,7 +251,7 @@ When validation fails: Build the image first: `scripts/sandbox-setup.sh` - See [Sandboxing](/gateway/sandboxing) for the full guide and [full reference](/gateway/configuration-reference#sandbox) for all options. + See [Sandboxing](/gateway/sandboxing) for the full guide and [full reference](/gateway/configuration-reference#agents-defaults-sandbox) for all options. diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md index 736dc7c6261..12650357724 100644 --- a/docs/gateway/sandboxing.md +++ b/docs/gateway/sandboxing.md @@ -463,7 +463,7 @@ See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for preceden ## Related docs - [OpenShell](/gateway/openshell) -- managed sandbox backend setup, workspace modes, and config reference -- [Sandbox Configuration](/gateway/configuration#agentsdefaults-sandbox) +- [Sandbox Configuration](/gateway/configuration-reference#agents-defaults-sandbox) - [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) -- debugging "why is this blocked?" - [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) -- per-agent overrides and precedence - [Security](/gateway/security) diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index 8cea1b42766..26cfbc4d6df 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -5,7 +5,7 @@ read_when: title: "Security" --- -# Security 🔒 +# Security > [!WARNING] > **Personal assistant trust model:** this guidance assumes one trusted operator boundary per gateway (single-user/personal assistant model). @@ -25,7 +25,7 @@ This page explains hardening **within that model**. It does not claim hostile mu ## Quick check: `openclaw security audit` -See also: [Formal Verification (Security Models)](/security/formal-verification/) +See also: [Formal Verification (Security Models)](/security/formal-verification) Run this regularly (especially after changing config or exposing network surfaces): diff --git a/docs/help/environment.md b/docs/help/environment.md index 860129bde37..45faad7c66c 100644 --- a/docs/help/environment.md +++ b/docs/help/environment.md @@ -90,7 +90,7 @@ You can reference env vars directly in config string values using `${VAR_NAME}` } ``` -See [Configuration: Env var substitution](/gateway/configuration#env-var-substitution-in-config) for full details. +See [Configuration: Env var substitution](/gateway/configuration-reference#env-var-substitution) for full details. ## Secret refs vs `${ENV}` strings diff --git a/docs/help/faq.md b/docs/help/faq.md index 5e892da6a7b..9122af6119e 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -13,7 +13,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ## 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) + - [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) @@ -449,7 +449,7 @@ section is the latest shipped version. Entries are grouped by **Highlights**, ** 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/troubleshooting#docsopenclawai-shows-an-ssl-error-comcastxfinity). +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). If you still can't reach the site, the docs are mirrored on GitHub: @@ -497,7 +497,7 @@ Rough guide: - **Onboarding:** 5-15 minutes depending on how many channels/models you configure 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). +and the fast debug loop in [I am stuck](/help/faq#i-am-stuck-fastest-way-to-get-unstuck). ### How do I try the latest bits @@ -858,7 +858,7 @@ Third-party (less private): - DM `@userinfobot` or `@getidsbot`. -See [/channels/telegram](/channels/telegram#access-control-dms--groups). +See [/channels/telegram](/channels/telegram#access-control-and-activation). ### Can multiple people use one WhatsApp number with different OpenClaw instances @@ -1259,7 +1259,7 @@ Use `agents.defaults.sandbox.mode: "non-main"` so group/channel sessions (non-ma 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#agentsdefaultssandbox) +Key config reference: [Gateway configuration](/gateway/configuration-reference#agents-defaults-sandbox) ### How do I bind a host folder into the sandbox @@ -2293,7 +2293,7 @@ Aliases come from `agents.defaults.models..alias`. Example: model: { primary: "anthropic/claude-opus-4-6" }, models: { "anthropic/claude-opus-4-6": { alias: "opus" }, - "anthropic/claude-sonnet-4-5": { alias: "sonnet" }, + "anthropic/claude-sonnet-4-6": { alias: "sonnet" }, "anthropic/claude-haiku-4-5": { alias: "haiku" }, }, }, @@ -2311,8 +2311,8 @@ OpenRouter (pay-per-token; many models): { agents: { defaults: { - model: { primary: "openrouter/anthropic/claude-sonnet-4-5" }, - models: { "openrouter/anthropic/claude-sonnet-4-5": {} }, + model: { primary: "openrouter/anthropic/claude-sonnet-4-6" }, + models: { "openrouter/anthropic/claude-sonnet-4-6": {} }, }, }, env: { OPENROUTER_API_KEY: "sk-or-..." }, @@ -2635,7 +2635,7 @@ Service/supervisor logs (when the gateway runs via launchd/systemd): - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` -See [Troubleshooting](/gateway/troubleshooting#log-locations) for more. +See [Troubleshooting](/gateway/troubleshooting) for more. ### How do I start/stop/restart the Gateway service @@ -2917,7 +2917,7 @@ If it is still noisy, check the session settings in the Control UI and set verbo 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 @@ -3000,7 +3000,7 @@ You can add options like `debounce:2s cap:25 drop:summarize` for followup modes. **Q: "What's the default model for Anthropic with an API key?"** -**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-5` 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. +**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. --- diff --git a/docs/help/index.md b/docs/help/index.md index 80aa5d304e8..5d0942909b6 100644 --- a/docs/help/index.md +++ b/docs/help/index.md @@ -11,7 +11,7 @@ title: "Help" If you want a quick “get unstuck” flow, start here: - **Troubleshooting:** [Start here](/help/troubleshooting) -- **Install sanity (Node/npm/PATH):** [Install](/install#nodejs--npm-path-sanity) +- **Install sanity (Node/npm/PATH):** [Install](/install/node#troubleshooting) - **Gateway issues:** [Gateway troubleshooting](/gateway/troubleshooting) - **Logs:** [Logging](/logging) and [Gateway logging](/gateway/logging) - **Repairs:** [Doctor](/gateway/doctor) diff --git a/docs/install/docker.md b/docs/install/docker.md index f4913a5138a..f80d0809fc8 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -29,7 +29,7 @@ Sandboxing details: [Sandboxing](/gateway/sandboxing) - At least 2 GB RAM for image build (`pnpm install` may be OOM-killed on 1 GB hosts with exit 137) - Enough disk for images + logs - If running on a VPS/public host, review - [Security hardening for network exposure](/gateway/security#04-network-exposure-bind--port--firewall), + [Security hardening for network exposure](/gateway/security#0-4-network-exposure-bind-port-firewall), especially Docker `DOCKER-USER` firewall policy. ## Containerized Gateway (Docker Compose) diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md index d16d76f6315..a1f2e212463 100644 --- a/docs/providers/anthropic.md +++ b/docs/providers/anthropic.md @@ -57,7 +57,7 @@ OpenClaw's shared `/fast` toggle also supports direct Anthropic API-key traffic. agents: { defaults: { models: { - "anthropic/claude-sonnet-4-5": { + "anthropic/claude-sonnet-4-6": { params: { fastMode: true }, }, }, @@ -228,7 +228,7 @@ openclaw onboard --auth-choice setup-token ## Notes - Generate the setup-token with `claude setup-token` and paste it, or run `openclaw models auth setup-token` on the gateway host. -- If you see “OAuth token refresh failed …” on a Claude subscription, re-auth with a setup-token. See [/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription](/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription). +- If you see “OAuth token refresh failed …” on a Claude subscription, re-auth with a setup-token. See [/gateway/troubleshooting](/gateway/troubleshooting). - Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth). ## Troubleshooting diff --git a/docs/tools/browser.md b/docs/tools/browser.md index dc044450742..4797bc7409b 100644 --- a/docs/tools/browser.md +++ b/docs/tools/browser.md @@ -581,7 +581,7 @@ Notes: - `--format ai` (default when Playwright is installed): returns an AI snapshot with numeric refs (`aria-ref=""`). - `--format aria`: returns the accessibility tree (no refs; inspection only). - `--efficient` (or `--mode efficient`): compact role snapshot preset (interactive + compact + depth + lower maxChars). - - Config default (tool/CLI only): set `browser.snapshotDefaults.mode: "efficient"` to use efficient snapshots when the caller does not pass a mode (see [Gateway configuration](/gateway/configuration#browser-openclaw-managed-browser)). + - Config default (tool/CLI only): set `browser.snapshotDefaults.mode: "efficient"` to use efficient snapshots when the caller does not pass a mode (see [Gateway configuration](/gateway/configuration-reference#browser)). - Role snapshot options (`--interactive`, `--compact`, `--depth`, `--selector`) force a role-based snapshot with refs like `ref=e12`. - `--frame "