Merge branch 'main' into fix/token-usage-input-output-breakdown
This commit is contained in:
jiarung
GitHub
commit
347976bad8
59
.agents/skills/parallels-discord-roundtrip/SKILL.md
Normal file
59
.agents/skills/parallels-discord-roundtrip/SKILL.md
Normal file
@ -0,0 +1,59 @@
|
||||
---
|
||||
name: parallels-discord-roundtrip
|
||||
description: Run the macOS Parallels smoke harness with Discord end-to-end roundtrip verification, including guest send, host verification, host reply, and guest readback.
|
||||
---
|
||||
|
||||
# Parallels Discord Roundtrip
|
||||
|
||||
Use when macOS Parallels smoke must prove Discord two-way delivery end to end.
|
||||
|
||||
## Goal
|
||||
|
||||
Cover:
|
||||
|
||||
- install on fresh macOS snapshot
|
||||
- onboard + gateway health
|
||||
- guest `message send` to Discord
|
||||
- host sees that message on Discord
|
||||
- host posts a new Discord message
|
||||
- guest `message read` sees that new message
|
||||
|
||||
## Inputs
|
||||
|
||||
- host env var with Discord bot token
|
||||
- Discord guild ID
|
||||
- Discord channel ID
|
||||
- `OPENAI_API_KEY`
|
||||
|
||||
## Preferred run
|
||||
|
||||
```bash
|
||||
export OPENCLAW_PARALLELS_DISCORD_TOKEN="$(
|
||||
ssh peters-mac-studio-1 'jq -r ".channels.discord.token" ~/.openclaw/openclaw.json' | tr -d '\n'
|
||||
)"
|
||||
|
||||
pnpm test:parallels:macos \
|
||||
--discord-token-env OPENCLAW_PARALLELS_DISCORD_TOKEN \
|
||||
--discord-guild-id 1456350064065904867 \
|
||||
--discord-channel-id 1456744319972282449 \
|
||||
--json
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Snapshot target: closest to `macOS 26.3.1 fresh`.
|
||||
- Harness configures Discord inside the guest; no checked-in token/config.
|
||||
- Use the `openclaw` wrapper for guest `message send/read`; `node openclaw.mjs message ...` does not expose the lazy message subcommands the same way.
|
||||
- Write `channels.discord.guilds` in one JSON object (`--strict-json`), not dotted `config set channels.discord.guilds.<snowflake>...` paths; numeric snowflakes get treated like array indexes.
|
||||
- Avoid `prlctl enter` / expect for long Discord setup scripts; it line-wraps/corrupts long commands. Use `prlctl exec --current-user /bin/sh -lc ...` for the Discord config phase.
|
||||
- Harness cleanup deletes the temporary Discord smoke messages at exit.
|
||||
- Per-phase logs: `/tmp/openclaw-parallels-smoke.*`
|
||||
- Machine summary: pass `--json`
|
||||
- If roundtrip flakes, inspect `fresh.discord-roundtrip.log` and `discord-last-readback.json` in the run dir first.
|
||||
|
||||
## Pass criteria
|
||||
|
||||
- fresh lane or upgrade lane requested passes
|
||||
- summary reports `discord=pass` for that lane
|
||||
- guest outbound nonce appears in channel history
|
||||
- host inbound nonce appears in `openclaw message read` output
|
||||
@ -1 +1,2 @@
|
||||
**/node_modules/
|
||||
docs/.generated/
|
||||
|
||||
@ -212,6 +212,11 @@
|
||||
- `prlctl exec` is fine for deterministic repo commands, but it can misrepresent interactive shell behavior (`PATH`, `HOME`, `curl | bash`, shebang resolution). For installer parity or shell-sensitive repros, prefer the guest Terminal or `prlctl enter`.
|
||||
- Fresh Tahoe snapshot current reality: `brew` exists, `node` may not be on `PATH` in noninteractive guest exec. Use absolute `/opt/homebrew/bin/node` for repo/CLI runs when needed.
|
||||
- Preferred automation entrypoint: `pnpm test:parallels:macos`. It restores the snapshot most closely matching `macOS 26.3.1 fresh`, serves the current `main` tarball from the host, then runs fresh-install and latest-release-to-main smoke lanes.
|
||||
- Discord roundtrip smoke is opt-in. Pass `--discord-token-env <VAR> --discord-guild-id <guild> --discord-channel-id <channel>`; the harness will configure Discord in-guest, post a guest message, verify host-side visibility via the Discord REST API, post a fresh host-side message back into the channel, then verify `openclaw message read` sees it in-guest.
|
||||
- Keep the Discord token in a host env var only. For Peter’s Mac Studio bot, fetch it into a temp env var from `~/.openclaw/openclaw.json` over SSH instead of hardcoding it in repo files/shell history.
|
||||
- For Discord smoke on this snapshot: use `openclaw message send/read` via the installed wrapper, not `node openclaw.mjs message ...`; lazy `message` subcommands do not resolve the same way through the direct module entrypoint.
|
||||
- For Discord guild allowlists: set `channels.discord.guilds` as one JSON object. Do not use dotted `config set channels.discord.guilds.<snowflake>...` paths; numeric snowflakes get treated as array indexes.
|
||||
- Avoid `prlctl enter` / expect for the Discord config phase; long lines get mangled. Use `prlctl exec --current-user /bin/sh -lc ...` with short commands or temp files.
|
||||
- Gateway verification in smoke runs should use `openclaw gateway status --deep --require-rpc`, not plain `--deep`, so probe failures go non-zero.
|
||||
- Latest-release pre-upgrade diagnostics still need compatibility fallback: stable `2026.3.12` does not know `--require-rpc`, so precheck status dumps should fall back to plain `gateway status --deep` until the guest is upgraded.
|
||||
- Harness output: pass `--json` for machine-readable summary; per-phase logs land under `/tmp/openclaw-parallels-smoke.*`.
|
||||
|
||||
134
CHANGELOG.md
134
CHANGELOG.md
@ -6,78 +6,92 @@ Docs: https://docs.openclaw.ai
|
||||
|
||||
### Changes
|
||||
|
||||
- Android/mobile: add a system-aware dark theme across onboarding and post-onboarding screens so the app follows the device theme through setup, chat, and voice flows. (#46249) Thanks @sibbl.
|
||||
- Commands/btw: add `/btw` side questions for quick tool-less answers about the current session without changing future session context, with dismissible in-session TUI answers and explicit BTW replies on external channels. (#45444) Thanks @ngutman.
|
||||
- Gateway/health monitor: add configurable stale-event thresholds and restart limits, plus per-channel and per-account `healthMonitor.enabled` overrides, while keeping the existing global disable path on `gateway.channelHealthCheckMinutes=0`. (#42107) Thanks @rstar327.
|
||||
- Feishu/cards: add identity-aware structured card headers and note footers for Feishu replies and direct sends, while keeping that presentation wired through the shared outbound identity path. (#29938) Thanks @nszhsl.
|
||||
- Feishu/streaming: add `onReasoningStream` and `onReasoningEnd` support to streaming cards, so `/reasoning stream` renders thinking tokens as markdown blockquotes in the same card — matching the Telegram channel's reasoning lane behavior. (#46029)
|
||||
- Web tools/Firecrawl: add Firecrawl as an `onboard`/configure search provider via a bundled plugin, expose explicit `firecrawl_search` and `firecrawl_scrape` tools, and align core `web_fetch` fallback behavior with Firecrawl base-URL/env fallback plus guarded endpoint fetches.
|
||||
- Refactor/channels: remove the legacy channel shim directories and point channel-specific imports directly at the extension-owned implementations. (#45967) thanks @scoootscooob.
|
||||
- Android/nodes: add `callLog.search` plus shared Call Log permission wiring so Android nodes can search recent call history through the gateway. (#44073) Thanks @lxk7280.
|
||||
- Docs/Zalo: clarify the Marketplace-bot support matrix and config guidance so the Zalo channel docs match current Bot Creator behavior more closely. (#47552) Thanks @No898.
|
||||
- Install/update: allow package-manager installs from GitHub `main` via `openclaw update --tag main`, installer `--version main`, or direct npm/pnpm git specs.
|
||||
- Plugins/providers: move OpenRouter, GitHub Copilot, and OpenAI Codex provider/runtime logic into bundled plugins, including dynamic model fallback, runtime auth exchange, stream wrappers, capability hints, and cache-TTL policy.
|
||||
- Plugins/MiniMax: merge the bundled MiniMax API and MiniMax OAuth plugin surfaces into a single default-on `minimax` plugin, while keeping legacy `minimax-portal-auth` config ids aliased for compatibility.
|
||||
- Plugins/bundles: add compatible Codex, Claude, and Cursor bundle discovery/install support, map bundle skills into OpenClaw skills, and apply Claude bundle `settings.json` defaults to embedded Pi with shell overrides sanitized.
|
||||
- Plugins/agent integrations: broaden the plugin surface for app-server integrations with channel-aware commands, interactive callbacks, inbound claims, and Discord/Telegram conversation binding support. (#45318) Thanks @huntharo and @vincentkoc.
|
||||
- Telegram/actions: add `topic-edit` for forum-topic renames and icon updates while sharing the same Telegram topic-edit transport used by the plugin runtime. (#47798) Thanks @obviyus.
|
||||
- secrets: harden read-only SecretRef command paths and diagnostics. (#47794) Thanks @joshavant.
|
||||
- Sandbox/runtime: add pluggable sandbox backends, ship an OpenShell backend with `mirror` and `remote` workspace modes, and make sandbox list/recreate/prune backend-aware instead of Docker-only.
|
||||
- Sandbox/SSH: add a core SSH sandbox backend with secret-backed key, certificate, and known_hosts inputs, move shared remote exec/filesystem tooling into core, and keep OpenShell focused on sandbox lifecycle plus optional `mirror` mode.
|
||||
- Web tools/Firecrawl: add Firecrawl as an `onboard`/configure search provider via a bundled plugin, expose explicit `firecrawl_search` and `firecrawl_scrape` tools, and align core `web_fetch` fallback behavior with Firecrawl base-URL/env fallback plus guarded endpoint fetches.
|
||||
- Plugins/bundles: add compatible Codex, Claude, and Cursor bundle discovery/install support, map bundle skills into OpenClaw skills, and apply Claude bundle `settings.json` defaults to embedded Pi with shell overrides sanitized.
|
||||
- Plugins/providers: move OpenRouter, GitHub Copilot, and OpenAI Codex provider/runtime logic into bundled plugins, including dynamic model fallback, runtime auth exchange, stream wrappers, capability hints, and cache-TTL policy.
|
||||
- Plugins/agent integrations: broaden the plugin surface for app-server integrations with channel-aware commands, interactive callbacks, inbound claims, and Discord/Telegram conversation binding support. (#45318) Thanks @huntharo and @vincentkoc.
|
||||
- Install/update: allow package-manager installs from GitHub `main` via `openclaw update --tag main`, installer `--version main`, or direct npm/pnpm git specs.
|
||||
- Gateway/health monitor: add configurable stale-event thresholds and restart limits, plus per-channel and per-account `healthMonitor.enabled` overrides, while keeping the existing global disable path on `gateway.channelHealthCheckMinutes=0`. (#42107) Thanks @rstar327.
|
||||
- Android/mobile: add a system-aware dark theme across onboarding and post-onboarding screens so the app follows the device theme through setup, chat, and voice flows. (#46249) Thanks @sibbl.
|
||||
- Feishu/ACP: add current-conversation ACP and subagent session binding for supported DMs and topic conversations, including completion delivery back to the originating Feishu conversation. (#46819)
|
||||
- Plugins/marketplaces: add Claude marketplace registry resolution, `plugin@marketplace` installs, marketplace listing, and update support, plus Docker E2E coverage for local and official marketplace flows. Thanks @vincentkoc.
|
||||
- Feishu/cards: add structured interactive approval and quick-action launcher cards, preserve callback user and conversation context through routing, and keep legacy card-action fallback behavior so common actions can run without typing raw commands. (#47873)
|
||||
- Feishu/streaming: add `onReasoningStream` and `onReasoningEnd` support to streaming cards, so `/reasoning stream` renders thinking tokens as markdown blockquotes in the same card — matching the Telegram channel's reasoning lane behavior. (#46029)
|
||||
- Feishu/cards: add identity-aware structured card headers and note footers for Feishu replies and direct sends, while keeping that presentation wired through the shared outbound identity path. (#29938) Thanks @nszhsl.
|
||||
- Android/nodes: add `callLog.search` plus shared Call Log permission wiring so Android nodes can search recent call history through the gateway. (#44073) Thanks @lxk7280.
|
||||
- Plugins/MiniMax: merge the bundled MiniMax API and MiniMax OAuth plugin surfaces into a single default-on `minimax` plugin, while keeping legacy `minimax-portal-auth` config ids aliased for compatibility.
|
||||
- Telegram/actions: add `topic-edit` for forum-topic renames and icon updates while sharing the same Telegram topic-edit transport used by the plugin runtime. (#47798) Thanks @obviyus.
|
||||
- Refactor/channels: remove the legacy channel shim directories and point channel-specific imports directly at the extension-owned implementations. (#45967) thanks @scoootscooob.
|
||||
- Docs/Zalo: clarify the Marketplace-bot support matrix and config guidance so the Zalo channel docs match current Bot Creator behavior more closely. (#47552) Thanks @No898.
|
||||
- secrets: harden read-only SecretRef command paths and diagnostics. (#47794) Thanks @joshavant.
|
||||
|
||||
### Breaking
|
||||
|
||||
- Browser/Chrome MCP: remove the legacy Chrome extension relay path, bundled extension assets, `driver: "extension"`, and `browser.relayBindHost`. Run `openclaw doctor --fix` to migrate host-local browser config to `existing-session` / `user`; Docker, headless, sandbox, and remote browser flows still use raw CDP. Thanks @vincentkoc.
|
||||
|
||||
### Fixes
|
||||
|
||||
- Group mention gating: reject invalid and unsafe nested-repetition `mentionPatterns`, reuse the shared safe config-regex compiler across mention stripping and detection, and cache strip-time regex compilation so noisy groups avoid repeated recompiles.
|
||||
- Control UI/chat sessions: show human-readable labels in the grouped session dropdown again, keep unique scoped fallbacks when metadata is missing, and disambiguate duplicate labels only when needed. (#45130) thanks @luzhidong.
|
||||
- Control UI: scope persisted session selection per gateway, prevent stale session bleed across tokenized gateway opens, and cap stored gateway session history. (#47453) Thanks @sallyom.
|
||||
- Slack/interactive replies: preserve `channelData.slack.blocks` through live DM delivery and preview-finalized edits so Block Kit button and select directives render instead of falling back to raw text. (#45890) Thanks @vincentkoc.
|
||||
- Feishu/topic threads: fetch full thread context, including prior bot replies, when starting a topic-thread session so follow-up turns in Feishu topics keep the right conversation state. (#45254) Thanks @Coobiw.
|
||||
- Configure/startup: move outbound send-deps resolution into a lightweight helper so `openclaw configure` no longer stalls after the banner while eagerly loading channel plugins. (#46301) thanks @scoootscooob.
|
||||
- Control UI/dashboard: preserve structured gateway shutdown reasons across restart disconnects so config-triggered restarts no longer fall back to `disconnected (1006): no reason`. (#46532) Thanks @vincentkoc.
|
||||
- Android/chat: theme the thinking dropdown and TLS trust dialogs explicitly so popup surfaces match the active app theme instead of falling back to mismatched Material defaults.
|
||||
- Z.AI/onboarding: detect a working default model even for explicit `zai-coding-*` endpoint choices, so Coding Plan setup can keep the selected endpoint while defaulting to `glm-5` when available or `glm-4.7` as fallback. (#45969)
|
||||
- Models/OpenRouter runtime capabilities: fetch uncatalogued OpenRouter model metadata on first use so newly added vision models keep image input instead of silently degrading to text-only, with top-level capability field fallbacks for `/api/v1/models`. (#45824) Thanks @DJjjjhao.
|
||||
- Z.AI/onboarding: add `glm-5-turbo` to the default Z.AI provider catalog so onboarding-generated configs expose the new model alongside the existing GLM defaults. (#46670) Thanks @tomsun28.
|
||||
- Zalo Personal/group gating: stop reapplying `dmPolicy.allowFrom` as a sender gate for already-allowlisted groups when `groupAllowFrom` is unset, so any member of an allowed group can trigger replies while DMs stay restricted. (#40146)
|
||||
- Google auth/Node 25: patch `gaxios` to use native fetch without injecting `globalThis.window`, while translating proxy and mTLS transport settings so Google Vertex and Google Chat auth keep working on Node 25. (#47914) Thanks @pdd-cli.
|
||||
- Gateway/startup: load bundled channel plugins from compiled `dist/extensions` entries in built installs, so gateway boot no longer recompiles bundled extension TypeScript on every startup and WhatsApp-class cold starts drop back to seconds instead of tens of seconds or worse.
|
||||
- Plugins/context engines: enforce owner-aware context-engine registration on both loader and public SDK paths so plugins cannot spoof privileged ownership, claim the core `legacy` engine id, or overwrite an existing engine id through direct SDK imports. (#47595) Thanks @vincentkoc.
|
||||
- Browser/remote CDP: honor strict browser SSRF policy during remote CDP reachability and `/json/version` discovery checks, redact sensitive `cdpUrl` tokens from status output, and warn when remote CDP targets private/internal hosts.
|
||||
- Plugins/install precedence: keep bundled plugins ahead of auto-discovered globals by default, but let an explicitly installed plugin record win its own duplicate-id tie so installed channel plugins load from `~/.openclaw/extensions` after `openclaw plugins install`.
|
||||
- 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.
|
||||
- Gateway/plugins: pin runtime webhook routes to the gateway startup registry so channel webhooks keep working across plugin-registry churn, and make plugin auth + dispatch resolve routes from the same live HTTP-route registry. Fixes #46924 and #47041.
|
||||
- Gateway/auth: ignore spoofed loopback hops in trusted forwarding chains and block device approvals that request scopes above the caller session. Thanks @vincentkoc.
|
||||
- Gateway/config views: strip embedded credentials from URL-based endpoint fields before returning read-only account and config snapshots. Thanks @vincentkoc.
|
||||
- Tools/apply-patch: revalidate workspace-only delete and directory targets immediately before mutating host paths. Thanks @vincentkoc.
|
||||
- Webhooks/runtime: move auth earlier and tighten pre-auth body limits and timeouts across bundled webhook handlers, including slow-body handling for Mattermost slash commands. Thanks @vincentkoc.
|
||||
- Subagents/follow-ups: require the same controller ownership checks for `/subagents send` as other control actions, so leaf sessions cannot message nested child runs they do not control. Thanks @vincentkoc.
|
||||
- Inbound policy hardening: tighten callback and webhook sender checks across Mattermost and Google Chat, match Nextcloud Talk rooms by stable room token, and treat explicit empty Twitch allowlists as deny-all. (#46787) Thanks @zpbrent, @ijxpwastaken and @vincentkoc.
|
||||
- macOS/canvas actions: keep unattended local agent actions on trusted in-app canvas surfaces only, and stop exposing the deep-link fallback key to arbitrary page scripts. (#46790) Thanks @vincentkoc.
|
||||
- Agents/compaction: extend the enclosing run deadline once while compaction is actively in flight, and abort the underlying SDK compaction on timeout/cancel so large-session compactions stop freezing mid-run. (#46889) Thanks @asyncjason.
|
||||
- Models/openai-completions: default non-native OpenAI-compatible providers to omit tool-definition `strict` fields unless users explicitly opt back in, so tool calling keeps working on providers that reject that option. (#45497) Thanks @sahancava.
|
||||
- WhatsApp/reconnect: restore the append recency filter in the extension inbox monitor and handle protobuf `Long` timestamps correctly, so fresh post-reconnect append messages are processed while stale history sync stays suppressed. (#42588) thanks @MonkeyLeeT.
|
||||
- WhatsApp/login: wait for pending creds writes before reopening after Baileys `515` pairing restarts in both QR login and `channels login` flows, and keep the restart coverage pinned to the real wrapped error shape plus per-account creds queues. (#27910) Thanks @asyncjason.
|
||||
- Agents/openai-compatible tool calls: deduplicate repeated tool call ids across live assistant messages and replayed history so OpenAI-compatible backends no longer reject duplicate `tool_call_id` values with HTTP 400. (#40996) Thanks @xaeon2026.
|
||||
- Security/device pairing: harden `device.token.rotate` deny handling by keeping public failures generic while logging internal deny reasons and preserving approved-baseline enforcement. (`GHSA-7jrw-x62h-64p8`)
|
||||
- Slack/interactive replies: preserve `channelData.slack.blocks` through live DM delivery and preview-finalized edits so Block Kit button and select directives render instead of falling back to raw text. (#45890) Thanks @vincentkoc.
|
||||
- Zalo/plugin runtime: export `resolveClientIp` from `openclaw/plugin-sdk/zalo` so installed builds no longer crash on startup when the webhook monitor loads from the packaged extension instead of the monorepo source tree. (#46549) Thanks @No898.
|
||||
- CI/channel test routing: move the built-in channel suites into `test:channels` and keep them out of `test:extensions`, so extension CI no longer fails after the channel migration while targeted test routing still sends Slack, Signal, and iMessage suites to the right lane. (#46066) Thanks @scoootscooob.
|
||||
- Browser/profiles: drop the auto-created `chrome-relay` browser profile; users who need the Chrome extension relay must now create their own profile via `openclaw browser create-profile`. (#45777) Thanks @odysseus0.
|
||||
- Docs/Mintlify: fix MDX marker syntax on Perplexity, Model Providers, Moonshot, and exec approvals pages so local docs preview no longer breaks rendering or leaves stale pages unpublished. (#46695) Thanks @velvet-shark.
|
||||
- Email/webhook wrapping: sanitize sender and subject metadata before external-content wrapping so metadata fields cannot break the wrapper structure. Thanks @vincentkoc.
|
||||
- Node/startup: remove leftover debug `console.log("node host PATH: ...")` that printed the resolved PATH on every `openclaw node run` invocation. (#46411)
|
||||
- Nodes/pending actions: re-check queued foreground actions against the current node command policy before returning them to the node. (#46815) Thanks @zpbrent and @vincentkoc.
|
||||
- ACP/approvals: use canonical tool identity for prompting decisions and fail closed when conflicting tool identity hints are present. (#46817) Thanks @zpbrent and @vincentkoc.
|
||||
- Telegram/message send: forward `--force-document` through the `sendPayload` path as well as `sendMedia`, so Telegram payload sends with `channelData` keep uploading images as documents instead of silently falling back to compressed photo sends. (#47119) Thanks @thepagent.
|
||||
- Telegram/message chunking: preserve spaces, paragraph separators, and word boundaries when HTML overflow rechunking splits formatted replies. (#47274)
|
||||
- Plugins/scoped ids: preserve scoped plugin ids during install and config keying, and keep bundled plugins ahead of discovered duplicate ids by default so `@scope/name` plugins no longer collide with unscoped installs. Thanks @vincentkoc.
|
||||
- CLI: avoid loading provider discovery during startup model normalization. (#46522) Thanks @ItsAditya-xyz and @vincentkoc.
|
||||
- Tlon: honor explicit empty allowlists and defer cite expansion. (#46788) Thanks @zpbrent and @vincentkoc.
|
||||
- ACP: require admin scope for mutating internal actions. (#46789) Thanks @tdjackey and @vincentkoc.
|
||||
- Gateway/config validation: stop treating the implicit default memory slot as a required explicit plugin config, so startup no longer fails with `plugins.slots.memory: plugin not found: memory-core` when `memory-core` was only inferred. (#47494) Thanks @ngutman.
|
||||
- Gateway/restart: defer externally signaled unmanaged restarts through the in-process idle drain, and preserve the restored subagent run as remap fallback during orphan recovery so resumed sessions do not duplicate work. (#47719) Thanks @joeykrug.
|
||||
- Control UI/session routing: preserve established external delivery routes when webchat views or sends in externally originated sessions, so subagent completions still return to the original channel instead of the dashboard. (#47797) Thanks @brokemac79.
|
||||
- Configure/startup: move outbound send-deps resolution into a lightweight helper so `openclaw configure` no longer stalls after the banner while eagerly loading channel plugins. (#46301) thanks @scoootscooob.
|
||||
- CLI/startup: lazy-load channel add and root help startup paths to trim avoidable RSS and help latency on constrained hosts. (#46784) Thanks @vincentkoc.
|
||||
- CLI/onboarding: import static provider definitions directly for onboarding model/config helpers so those paths no longer pull provider discovery just for built-in defaults. (#47467) Thanks @vincentkoc.
|
||||
- CLI/auth choice: lazy-load plugin/provider fallback resolution so mapped auth choices stay on the static path and only unknown choices pay the heavy provider load. (#47495) Thanks @vincentkoc.
|
||||
- CLI/completion: reduce recursive completion-script string churn and fix nested PowerShell command-path matching so generated nested completions resolve on PowerShell too. (#45537) Thanks @yiShanXin and @vincentkoc.
|
||||
- Gateway/startup: load bundled channel plugins from compiled `dist/extensions` entries in built installs, so gateway boot no longer recompiles bundled extension TypeScript on every startup and WhatsApp-class cold starts drop back to seconds instead of tens of seconds or worse.
|
||||
- CLI: avoid loading provider discovery during startup model normalization. (#46522) Thanks @ItsAditya-xyz and @vincentkoc.
|
||||
- Security/device pairing: harden `device.token.rotate` deny handling by keeping public failures generic while logging internal deny reasons and preserving approved-baseline enforcement. (`GHSA-7jrw-x62h-64p8`)
|
||||
- Inbound policy hardening: tighten callback and webhook sender checks across Mattermost and Google Chat, match Nextcloud Talk rooms by stable room token, and treat explicit empty Twitch allowlists as deny-all. (#46787) Thanks @zpbrent, @ijxpwastaken and @vincentkoc.
|
||||
- Webhooks/runtime: move auth earlier and tighten pre-auth body limits and timeouts across bundled webhook handlers, including slow-body handling for Mattermost slash commands. Thanks @vincentkoc.
|
||||
- Email/webhook wrapping: sanitize sender and subject metadata before external-content wrapping so metadata fields cannot break the wrapper structure. Thanks @vincentkoc.
|
||||
- Tools/apply-patch: revalidate workspace-only delete and directory targets immediately before mutating host paths. Thanks @vincentkoc.
|
||||
- Gateway/config views: strip embedded credentials from URL-based endpoint fields before returning read-only account and config snapshots. Thanks @vincentkoc.
|
||||
- ACP/approvals: use canonical tool identity for prompting decisions and fail closed when conflicting tool identity hints are present. (#46817) Thanks @zpbrent and @vincentkoc.
|
||||
- ACP: require admin scope for mutating internal actions. (#46789) Thanks @tdjackey and @vincentkoc.
|
||||
- Subagents/follow-ups: require the same controller ownership checks for `/subagents send` as other control actions, so leaf sessions cannot message nested child runs they do not control. Thanks @vincentkoc.
|
||||
- macOS/canvas actions: keep unattended local agent actions on trusted in-app canvas surfaces only, and stop exposing the deep-link fallback key to arbitrary page scripts. (#46790) Thanks @vincentkoc.
|
||||
- Agents/compaction: extend the enclosing run deadline once while compaction is actively in flight, and abort the underlying SDK compaction on timeout/cancel so large-session compactions stop freezing mid-run. (#46889) Thanks @asyncjason.
|
||||
- Agents/openai-compatible tool calls: deduplicate repeated tool call ids across live assistant messages and replayed history so OpenAI-compatible backends no longer reject duplicate `tool_call_id` values with HTTP 400. (#40996) Thanks @xaeon2026.
|
||||
- Models/openai-completions: default non-native OpenAI-compatible providers to omit tool-definition `strict` fields unless users explicitly opt back in, so tool calling keeps working on providers that reject that option. (#45497) Thanks @sahancava.
|
||||
- Models/OpenRouter runtime capabilities: fetch uncatalogued OpenRouter model metadata on first use so newly added vision models keep image input instead of silently degrading to text-only, with top-level capability field fallbacks for `/api/v1/models`. (#45824) Thanks @DJjjjhao.
|
||||
- Channels/plugins: keep shared interactive payloads merge-ready by fixing Slack custom callback routing and repeat-click dedupe, allowing interactive-only sends, and preserving ordered Discord shared text blocks. (#47715) Thanks @vincentkoc.
|
||||
- Slack/interactive replies: preserve `channelData.slack.blocks` through live DM delivery and preview-finalized edits so Block Kit button and select directives render instead of falling back to raw text. (#45890) Thanks @vincentkoc.
|
||||
- Slack/interactive replies: preserve `channelData.slack.blocks` through live DM delivery and preview-finalized edits so Block Kit button and select directives render instead of falling back to raw text. (#45890) Thanks @vincentkoc.
|
||||
- Feishu/actions: expand the runtime action surface with message read/edit, explicit thread replies, pinning, and operator-facing chat/member inspection so Feishu can operate more of the workspace directly.
|
||||
- Feishu/topic threads: fetch full thread context, including prior bot replies, when starting a topic-thread session so follow-up turns in Feishu topics keep the right conversation state. (#45254) Thanks @Coobiw.
|
||||
- Feishu/media: keep native image, file, audio, and video/media handling aligned across outbound sends, inbound downloads, thread replies, directory/action aliases, and capability docs so unsupported areas are explicit instead of implied.
|
||||
- WhatsApp/reconnect: restore the append recency filter in the extension inbox monitor and handle protobuf `Long` timestamps correctly, so fresh post-reconnect append messages are processed while stale history sync stays suppressed. (#42588) thanks @MonkeyLeeT.
|
||||
- WhatsApp/login: wait for pending creds writes before reopening after Baileys `515` pairing restarts in both QR login and `channels login` flows, and keep the restart coverage pinned to the real wrapped error shape plus per-account creds queues. (#27910) Thanks @asyncjason.
|
||||
- Telegram/message send: forward `--force-document` through the `sendPayload` path as well as `sendMedia`, so Telegram payload sends with `channelData` keep uploading images as documents instead of silently falling back to compressed photo sends. (#47119) Thanks @thepagent.
|
||||
- Telegram/message chunking: preserve spaces, paragraph separators, and word boundaries when HTML overflow rechunking splits formatted replies. (#47274)
|
||||
- Z.AI/onboarding: detect a working default model even for explicit `zai-coding-*` endpoint choices, so Coding Plan setup can keep the selected endpoint while defaulting to `glm-5` when available or `glm-4.7` as fallback. (#45969)
|
||||
- Z.AI/onboarding: add `glm-5-turbo` to the default Z.AI provider catalog so onboarding-generated configs expose the new model alongside the existing GLM defaults. (#46670) Thanks @tomsun28.
|
||||
- Zalo Personal/group gating: stop reapplying `dmPolicy.allowFrom` as a sender gate for already-allowlisted groups when `groupAllowFrom` is unset, so any member of an allowed group can trigger replies while DMs stay restricted. (#40146)
|
||||
- Zalo/plugin runtime: export `resolveClientIp` from `openclaw/plugin-sdk/zalo` so installed builds no longer crash on startup when the webhook monitor loads from the packaged extension instead of the monorepo source tree. (#46549) Thanks @No898.
|
||||
- Plugins/install precedence: keep bundled plugins ahead of auto-discovered globals by default, but let an explicitly installed plugin record win its own duplicate-id tie so installed channel plugins load from `~/.openclaw/extensions` after `openclaw plugins install`.
|
||||
- Plugins/scoped ids: preserve scoped plugin ids during install and config keying, and keep bundled plugins ahead of discovered duplicate ids by default so `@scope/name` plugins no longer collide with unscoped installs. Thanks @vincentkoc.
|
||||
- Gateway/watch mode: restart on bundled-plugin package and manifest metadata changes, rebuild `dist` for extension source and `tsdown.config.ts` changes, and still ignore extension docs. (#47571) thanks @gumadeiras.
|
||||
- Gateway/watch mode: recreate bundled plugin runtime metadata after clean or stale `dist` states, so `pnpm gateway:watch` no longer fails on missing `dist/extensions/*/openclaw.plugin.json` manifests after a rebuild. Thanks @gumadeiras.
|
||||
- Plugins/context engines: enforce owner-aware context-engine registration on both loader and public SDK paths so plugins cannot spoof privileged ownership, claim the core `legacy` engine id, or overwrite an existing engine id through direct SDK imports. (#47595) Thanks @vincentkoc.
|
||||
- Control UI/chat sessions: show human-readable labels in the grouped session dropdown again, keep unique scoped fallbacks when metadata is missing, and disambiguate duplicate labels only when needed. (#45130) thanks @luzhidong.
|
||||
- Control UI: scope persisted session selection per gateway, prevent stale session bleed across tokenized gateway opens, and cap stored gateway session history. (#47453) Thanks @sallyom.
|
||||
- Control UI/dashboard: preserve structured gateway shutdown reasons across restart disconnects so config-triggered restarts no longer fall back to `disconnected (1006): no reason`. (#46532) Thanks @vincentkoc.
|
||||
- Android/chat: theme the thinking dropdown and TLS trust dialogs explicitly so popup surfaces match the active app theme instead of falling back to mismatched Material defaults.
|
||||
- Group mention gating: reject invalid and unsafe nested-repetition `mentionPatterns`, reuse the shared safe config-regex compiler across mention stripping and detection, and cache strip-time regex compilation so noisy groups avoid repeated recompiles.
|
||||
- Browser/profiles: drop the auto-created `chrome-relay` browser profile; users who need the Chrome extension relay must now create their own profile via `openclaw browser create-profile`. (#45777) Thanks @odysseus0.
|
||||
- CI/channel test routing: move the built-in channel suites into `test:channels` and keep them out of `test:extensions`, so extension CI no longer fails after the channel migration while targeted test routing still sends Slack, Signal, and iMessage suites to the right lane. (#46066) Thanks @scoootscooob.
|
||||
- Docs/Mintlify: fix MDX marker syntax on Perplexity, Model Providers, Moonshot, and exec approvals pages so local docs preview no longer breaks rendering or leaves stale pages unpublished. (#46695) Thanks @velvet-shark.
|
||||
- Gateway/config validation: stop treating the implicit default memory slot as a required explicit plugin config, so startup no longer fails with `plugins.slots.memory: plugin not found: memory-core` when `memory-core` was only inferred. (#47494) Thanks @ngutman.
|
||||
- Tlon: honor explicit empty allowlists and defer cite expansion. (#46788) Thanks @zpbrent and @vincentkoc.
|
||||
- Nodes/pending actions: re-check queued foreground actions against the current node command policy before returning them to the node. (#46815) Thanks @zpbrent and @vincentkoc.
|
||||
- Node/startup: remove leftover debug `console.log("node host PATH: ...")` that printed the resolved PATH on every `openclaw node run` invocation. (#46411)
|
||||
- CLI/completion: reduce recursive completion-script string churn and fix nested PowerShell command-path matching so generated nested completions resolve on PowerShell too. (#45537) Thanks @yiShanXin and @vincentkoc.
|
||||
|
||||
## 2026.3.13
|
||||
|
||||
|
||||
@ -8,6 +8,24 @@ final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHandler {
|
||||
static let messageName = "openclawCanvasA2UIAction"
|
||||
static let allMessageNames = [messageName]
|
||||
|
||||
// Compatibility helper for debug/test shims. Runtime dispatch remains
|
||||
// limited to in-app canvas schemes in `didReceive`.
|
||||
static func isLocalNetworkCanvasURL(_ url: URL) -> Bool {
|
||||
guard let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https" else {
|
||||
return false
|
||||
}
|
||||
guard let host = url.host?.lowercased(), !host.isEmpty else {
|
||||
return false
|
||||
}
|
||||
if host == "localhost" {
|
||||
return true
|
||||
}
|
||||
guard let ip = Self.parseIPv4(host) else {
|
||||
return false
|
||||
}
|
||||
return Self.isLocalNetworkIPv4(ip)
|
||||
}
|
||||
|
||||
private let sessionKey: String
|
||||
|
||||
init(sessionKey: String) {
|
||||
@ -104,5 +122,24 @@ final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHandler {
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private static func parseIPv4(_ host: String) -> (UInt8, UInt8, UInt8, UInt8)? {
|
||||
let parts = host.split(separator: ".", omittingEmptySubsequences: false)
|
||||
guard parts.count == 4 else { return nil }
|
||||
let bytes = parts.compactMap { UInt8($0) }
|
||||
guard bytes.count == 4 else { return nil }
|
||||
return (bytes[0], bytes[1], bytes[2], bytes[3])
|
||||
}
|
||||
|
||||
private static func isLocalNetworkIPv4(_ ip: (UInt8, UInt8, UInt8, UInt8)) -> Bool {
|
||||
let (a, b, _, _) = ip
|
||||
if a == 10 { return true }
|
||||
if a == 172, (16...31).contains(Int(b)) { return true }
|
||||
if a == 192, b == 168 { return true }
|
||||
if a == 127 { return true }
|
||||
if a == 169, b == 254 { return true }
|
||||
if a == 100, (64...127).contains(Int(b)) { return true }
|
||||
return false
|
||||
}
|
||||
// Formatting helpers live in OpenClawKit (`OpenClawCanvasA2UIAction`).
|
||||
}
|
||||
|
||||
@ -254,6 +254,71 @@ struct CronJob: Identifiable, Codable, Equatable {
|
||||
case state
|
||||
}
|
||||
|
||||
init(
|
||||
id: String,
|
||||
agentId: String?,
|
||||
name: String,
|
||||
description: String?,
|
||||
enabled: Bool,
|
||||
deleteAfterRun: Bool?,
|
||||
createdAtMs: Int,
|
||||
updatedAtMs: Int,
|
||||
schedule: CronSchedule,
|
||||
sessionTarget: CronSessionTarget,
|
||||
wakeMode: CronWakeMode,
|
||||
payload: CronPayload,
|
||||
delivery: CronDelivery?,
|
||||
state: CronJobState)
|
||||
{
|
||||
self.init(
|
||||
id: id,
|
||||
agentId: agentId,
|
||||
name: name,
|
||||
description: description,
|
||||
enabled: enabled,
|
||||
deleteAfterRun: deleteAfterRun,
|
||||
createdAtMs: createdAtMs,
|
||||
updatedAtMs: updatedAtMs,
|
||||
schedule: schedule,
|
||||
sessionTarget: .predefined(sessionTarget),
|
||||
wakeMode: wakeMode,
|
||||
payload: payload,
|
||||
delivery: delivery,
|
||||
state: state)
|
||||
}
|
||||
|
||||
init(
|
||||
id: String,
|
||||
agentId: String?,
|
||||
name: String,
|
||||
description: String?,
|
||||
enabled: Bool,
|
||||
deleteAfterRun: Bool?,
|
||||
createdAtMs: Int,
|
||||
updatedAtMs: Int,
|
||||
schedule: CronSchedule,
|
||||
sessionTarget: CronCustomSessionTarget,
|
||||
wakeMode: CronWakeMode,
|
||||
payload: CronPayload,
|
||||
delivery: CronDelivery?,
|
||||
state: CronJobState)
|
||||
{
|
||||
self.id = id
|
||||
self.agentId = agentId
|
||||
self.name = name
|
||||
self.description = description
|
||||
self.enabled = enabled
|
||||
self.deleteAfterRun = deleteAfterRun
|
||||
self.createdAtMs = createdAtMs
|
||||
self.updatedAtMs = updatedAtMs
|
||||
self.schedule = schedule
|
||||
self.sessionTargetRaw = sessionTarget.rawValue
|
||||
self.wakeMode = wakeMode
|
||||
self.payload = payload
|
||||
self.delivery = delivery
|
||||
self.state = state
|
||||
}
|
||||
|
||||
/// Parsed session target (predefined or custom session ID)
|
||||
var parsedSessionTarget: CronCustomSessionTarget {
|
||||
CronCustomSessionTarget.from(self.sessionTargetRaw)
|
||||
|
||||
@ -1,23 +0,0 @@
|
||||
# OpenClaw Chrome Extension (Browser Relay)
|
||||
|
||||
Purpose: attach OpenClaw to an existing Chrome tab so the Gateway can automate it (via the local CDP relay server).
|
||||
|
||||
## Dev / load unpacked
|
||||
|
||||
1. Build/run OpenClaw Gateway with browser control enabled.
|
||||
2. Ensure the relay server is reachable at `http://127.0.0.1:18792/` (default).
|
||||
3. Install the extension to a stable path:
|
||||
|
||||
```bash
|
||||
openclaw browser extension install
|
||||
openclaw browser extension path
|
||||
```
|
||||
|
||||
4. Chrome → `chrome://extensions` → enable “Developer mode”.
|
||||
5. “Load unpacked” → select the path printed above.
|
||||
6. Pin the extension. Click the icon on a tab to attach/detach.
|
||||
|
||||
## Options
|
||||
|
||||
- `Relay port`: defaults to `18792`.
|
||||
- `Gateway token`: required. Set this to `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).
|
||||
@ -1,64 +0,0 @@
|
||||
export function reconnectDelayMs(
|
||||
attempt,
|
||||
opts = { baseMs: 1000, maxMs: 30000, jitterMs: 1000, random: Math.random },
|
||||
) {
|
||||
const baseMs = Number.isFinite(opts.baseMs) ? opts.baseMs : 1000;
|
||||
const maxMs = Number.isFinite(opts.maxMs) ? opts.maxMs : 30000;
|
||||
const jitterMs = Number.isFinite(opts.jitterMs) ? opts.jitterMs : 1000;
|
||||
const random = typeof opts.random === "function" ? opts.random : Math.random;
|
||||
const safeAttempt = Math.max(0, Number.isFinite(attempt) ? attempt : 0);
|
||||
const backoff = Math.min(baseMs * 2 ** safeAttempt, maxMs);
|
||||
return backoff + Math.max(0, jitterMs) * random();
|
||||
}
|
||||
|
||||
export async function deriveRelayToken(gatewayToken, port) {
|
||||
const enc = new TextEncoder();
|
||||
const key = await crypto.subtle.importKey(
|
||||
"raw",
|
||||
enc.encode(gatewayToken),
|
||||
{ name: "HMAC", hash: "SHA-256" },
|
||||
false,
|
||||
["sign"],
|
||||
);
|
||||
const sig = await crypto.subtle.sign(
|
||||
"HMAC",
|
||||
key,
|
||||
enc.encode(`openclaw-extension-relay-v1:${port}`),
|
||||
);
|
||||
return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
|
||||
}
|
||||
|
||||
export async function buildRelayWsUrl(port, gatewayToken) {
|
||||
const token = String(gatewayToken || "").trim();
|
||||
if (!token) {
|
||||
throw new Error(
|
||||
"Missing gatewayToken in extension settings (chrome.storage.local.gatewayToken)",
|
||||
);
|
||||
}
|
||||
const relayToken = await deriveRelayToken(token, port);
|
||||
return `ws://127.0.0.1:${port}/extension?token=${encodeURIComponent(relayToken)}`;
|
||||
}
|
||||
|
||||
export function isRetryableReconnectError(err) {
|
||||
const message = err instanceof Error ? err.message : String(err || "");
|
||||
if (message.includes("Missing gatewayToken")) {
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
export function isMissingTabError(err) {
|
||||
const message = (err instanceof Error ? err.message : String(err || "")).toLowerCase();
|
||||
return (
|
||||
message.includes("no tab with id") ||
|
||||
message.includes("no tab with given id") ||
|
||||
message.includes("tab not found")
|
||||
);
|
||||
}
|
||||
|
||||
export function isLastRemainingTab(allTabs, tabIdToClose) {
|
||||
if (!Array.isArray(allTabs)) {
|
||||
return true;
|
||||
}
|
||||
return allTabs.filter((tab) => tab && tab.id !== tabIdToClose).length === 0;
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,25 +0,0 @@
|
||||
{
|
||||
"manifest_version": 3,
|
||||
"name": "OpenClaw Browser Relay",
|
||||
"version": "0.1.0",
|
||||
"description": "Attach OpenClaw to your existing Chrome tab via a local CDP relay server.",
|
||||
"icons": {
|
||||
"16": "icons/icon16.png",
|
||||
"32": "icons/icon32.png",
|
||||
"48": "icons/icon48.png",
|
||||
"128": "icons/icon128.png"
|
||||
},
|
||||
"permissions": ["debugger", "tabs", "activeTab", "storage", "alarms", "webNavigation"],
|
||||
"host_permissions": ["http://127.0.0.1/*", "http://localhost/*"],
|
||||
"background": { "service_worker": "background.js", "type": "module" },
|
||||
"action": {
|
||||
"default_title": "OpenClaw Browser Relay (click to attach/detach)",
|
||||
"default_icon": {
|
||||
"16": "icons/icon16.png",
|
||||
"32": "icons/icon32.png",
|
||||
"48": "icons/icon48.png",
|
||||
"128": "icons/icon128.png"
|
||||
}
|
||||
},
|
||||
"options_ui": { "page": "options.html", "open_in_tab": true }
|
||||
}
|
||||
@ -1,57 +0,0 @@
|
||||
const PORT_GUIDANCE = 'Use gateway port + 3 (for gateway 18789, relay is 18792).'
|
||||
|
||||
function hasCdpVersionShape(data) {
|
||||
return !!data && typeof data === 'object' && 'Browser' in data && 'Protocol-Version' in data
|
||||
}
|
||||
|
||||
export function classifyRelayCheckResponse(res, port) {
|
||||
if (!res) {
|
||||
return { action: 'throw', error: 'No response from service worker' }
|
||||
}
|
||||
|
||||
if (res.status === 401) {
|
||||
return { action: 'status', kind: 'error', message: 'Gateway token rejected. Check token and save again.' }
|
||||
}
|
||||
|
||||
if (res.error) {
|
||||
return { action: 'throw', error: res.error }
|
||||
}
|
||||
|
||||
if (!res.ok) {
|
||||
return { action: 'throw', error: `HTTP ${res.status}` }
|
||||
}
|
||||
|
||||
const contentType = String(res.contentType || '')
|
||||
if (!contentType.includes('application/json')) {
|
||||
return {
|
||||
action: 'status',
|
||||
kind: 'error',
|
||||
message: `Wrong port: this is likely the gateway, not the relay. ${PORT_GUIDANCE}`,
|
||||
}
|
||||
}
|
||||
|
||||
if (!hasCdpVersionShape(res.json)) {
|
||||
return {
|
||||
action: 'status',
|
||||
kind: 'error',
|
||||
message: `Wrong port: expected relay /json/version response. ${PORT_GUIDANCE}`,
|
||||
}
|
||||
}
|
||||
|
||||
return { action: 'status', kind: 'ok', message: `Relay reachable and authenticated at http://127.0.0.1:${port}/` }
|
||||
}
|
||||
|
||||
export function classifyRelayCheckException(err, port) {
|
||||
const message = String(err || '').toLowerCase()
|
||||
if (message.includes('json') || message.includes('syntax')) {
|
||||
return {
|
||||
kind: 'error',
|
||||
message: `Wrong port: this is not a relay endpoint. ${PORT_GUIDANCE}`,
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
kind: 'error',
|
||||
message: `Relay not reachable/authenticated at http://127.0.0.1:${port}/. Start OpenClaw browser relay and verify token.`,
|
||||
}
|
||||
}
|
||||
@ -1,200 +0,0 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>OpenClaw Browser Relay</title>
|
||||
<style>
|
||||
:root {
|
||||
color-scheme: light dark;
|
||||
--accent: #ff5a36;
|
||||
--panel: color-mix(in oklab, canvas 92%, canvasText 8%);
|
||||
--border: color-mix(in oklab, canvasText 18%, transparent);
|
||||
--muted: color-mix(in oklab, canvasText 70%, transparent);
|
||||
--shadow: 0 10px 30px color-mix(in oklab, canvasText 18%, transparent);
|
||||
font-family: ui-rounded, system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Rounded",
|
||||
"SF Pro Display", "Segoe UI", sans-serif;
|
||||
line-height: 1.4;
|
||||
}
|
||||
body {
|
||||
margin: 0;
|
||||
min-height: 100vh;
|
||||
background:
|
||||
radial-gradient(1000px 500px at 10% 0%, color-mix(in oklab, var(--accent) 30%, transparent), transparent 70%),
|
||||
radial-gradient(900px 450px at 90% 0%, color-mix(in oklab, var(--accent) 18%, transparent), transparent 75%),
|
||||
canvas;
|
||||
color: canvasText;
|
||||
}
|
||||
.wrap {
|
||||
max-width: 820px;
|
||||
margin: 36px auto;
|
||||
padding: 0 24px 48px 24px;
|
||||
}
|
||||
header {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 12px;
|
||||
margin-bottom: 18px;
|
||||
}
|
||||
.logo {
|
||||
width: 44px;
|
||||
height: 44px;
|
||||
border-radius: 14px;
|
||||
background: color-mix(in oklab, var(--accent) 18%, transparent);
|
||||
border: 1px solid color-mix(in oklab, var(--accent) 35%, transparent);
|
||||
box-shadow: var(--shadow);
|
||||
display: grid;
|
||||
place-items: center;
|
||||
}
|
||||
.logo img {
|
||||
width: 28px;
|
||||
height: 28px;
|
||||
image-rendering: pixelated;
|
||||
}
|
||||
h1 {
|
||||
font-size: 20px;
|
||||
margin: 0;
|
||||
letter-spacing: -0.01em;
|
||||
}
|
||||
.subtitle {
|
||||
margin: 2px 0 0 0;
|
||||
color: var(--muted);
|
||||
font-size: 13px;
|
||||
}
|
||||
.grid {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr;
|
||||
gap: 14px;
|
||||
}
|
||||
.card {
|
||||
background: var(--panel);
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 16px;
|
||||
padding: 16px;
|
||||
box-shadow: var(--shadow);
|
||||
}
|
||||
.card h2 {
|
||||
margin: 0 0 10px 0;
|
||||
font-size: 14px;
|
||||
letter-spacing: 0.01em;
|
||||
}
|
||||
.card p {
|
||||
margin: 8px 0 0 0;
|
||||
color: var(--muted);
|
||||
font-size: 13px;
|
||||
}
|
||||
.row {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
label {
|
||||
display: block;
|
||||
font-size: 12px;
|
||||
color: var(--muted);
|
||||
margin-bottom: 6px;
|
||||
}
|
||||
input {
|
||||
width: 160px;
|
||||
padding: 10px 12px;
|
||||
border-radius: 12px;
|
||||
border: 1px solid var(--border);
|
||||
background: color-mix(in oklab, canvas 92%, canvasText 8%);
|
||||
color: canvasText;
|
||||
outline: none;
|
||||
}
|
||||
input:focus {
|
||||
border-color: color-mix(in oklab, var(--accent) 70%, transparent);
|
||||
box-shadow: 0 0 0 4px color-mix(in oklab, var(--accent) 20%, transparent);
|
||||
}
|
||||
button {
|
||||
padding: 10px 14px;
|
||||
border-radius: 12px;
|
||||
border: 1px solid color-mix(in oklab, var(--accent) 55%, transparent);
|
||||
background: linear-gradient(
|
||||
180deg,
|
||||
color-mix(in oklab, var(--accent) 80%, white 20%),
|
||||
var(--accent)
|
||||
);
|
||||
color: white;
|
||||
font-weight: 650;
|
||||
letter-spacing: 0.01em;
|
||||
cursor: pointer;
|
||||
}
|
||||
button:active {
|
||||
transform: translateY(1px);
|
||||
}
|
||||
.hint {
|
||||
margin-top: 10px;
|
||||
font-size: 12px;
|
||||
color: var(--muted);
|
||||
}
|
||||
code {
|
||||
font-family: ui-monospace, Menlo, Monaco, Consolas, "SF Mono", monospace;
|
||||
font-size: 12px;
|
||||
}
|
||||
a {
|
||||
color: color-mix(in oklab, var(--accent) 85%, canvasText 15%);
|
||||
}
|
||||
.status {
|
||||
margin-top: 10px;
|
||||
font-size: 12px;
|
||||
color: color-mix(in oklab, var(--accent) 70%, canvasText 30%);
|
||||
min-height: 16px;
|
||||
}
|
||||
.status[data-kind='ok'] {
|
||||
color: color-mix(in oklab, #16a34a 75%, canvasText 25%);
|
||||
}
|
||||
.status[data-kind='error'] {
|
||||
color: color-mix(in oklab, #ef4444 75%, canvasText 25%);
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="wrap">
|
||||
<header>
|
||||
<div class="logo" aria-hidden="true">
|
||||
<img src="icons/icon128.png" alt="" />
|
||||
</div>
|
||||
<div>
|
||||
<h1>OpenClaw Browser Relay</h1>
|
||||
<p class="subtitle">Click the toolbar button on a tab to attach / detach.</p>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<div class="grid">
|
||||
<div class="card">
|
||||
<h2>Getting started</h2>
|
||||
<p>
|
||||
If you see a red <code>!</code> badge on the extension icon, the relay server is not reachable.
|
||||
Start OpenClaw’s browser relay on this machine (Gateway or node host), then click the toolbar button again.
|
||||
</p>
|
||||
<p>
|
||||
Full guide (install, remote Gateway, security): <a href="https://docs.openclaw.ai/tools/chrome-extension" target="_blank" rel="noreferrer">docs.openclaw.ai/tools/chrome-extension</a>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>Relay connection</h2>
|
||||
<label for="port">Port</label>
|
||||
<div class="row">
|
||||
<input id="port" inputmode="numeric" pattern="[0-9]*" />
|
||||
</div>
|
||||
<label for="token" style="margin-top: 10px">Gateway token</label>
|
||||
<div class="row">
|
||||
<input id="token" type="password" autocomplete="off" style="width: min(520px, 100%)" />
|
||||
<button id="save" type="button">Save</button>
|
||||
</div>
|
||||
<div class="hint">
|
||||
Default port: <code>18792</code>. Extension connects to: <code id="relay-url">http://127.0.0.1:<port>/</code>.
|
||||
Gateway token must match <code>gateway.auth.token</code> (or <code>OPENCLAW_GATEWAY_TOKEN</code>).
|
||||
</div>
|
||||
<div class="status" id="status"></div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<script type="module" src="options.js"></script>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,74 +0,0 @@
|
||||
import { deriveRelayToken } from './background-utils.js'
|
||||
import { classifyRelayCheckException, classifyRelayCheckResponse } from './options-validation.js'
|
||||
|
||||
const DEFAULT_PORT = 18792
|
||||
|
||||
function clampPort(value) {
|
||||
const n = Number.parseInt(String(value || ''), 10)
|
||||
if (!Number.isFinite(n)) return DEFAULT_PORT
|
||||
if (n <= 0 || n > 65535) return DEFAULT_PORT
|
||||
return n
|
||||
}
|
||||
|
||||
function updateRelayUrl(port) {
|
||||
const el = document.getElementById('relay-url')
|
||||
if (!el) return
|
||||
el.textContent = `http://127.0.0.1:${port}/`
|
||||
}
|
||||
|
||||
function setStatus(kind, message) {
|
||||
const status = document.getElementById('status')
|
||||
if (!status) return
|
||||
status.dataset.kind = kind || ''
|
||||
status.textContent = message || ''
|
||||
}
|
||||
|
||||
async function checkRelayReachable(port, token) {
|
||||
const url = `http://127.0.0.1:${port}/json/version`
|
||||
const trimmedToken = String(token || '').trim()
|
||||
if (!trimmedToken) {
|
||||
setStatus('error', 'Gateway token required. Save your gateway token to connect.')
|
||||
return
|
||||
}
|
||||
try {
|
||||
const relayToken = await deriveRelayToken(trimmedToken, port)
|
||||
// Delegate the fetch to the background service worker to bypass
|
||||
// CORS preflight on the custom x-openclaw-relay-token header.
|
||||
const res = await chrome.runtime.sendMessage({
|
||||
type: 'relayCheck',
|
||||
url,
|
||||
token: relayToken,
|
||||
})
|
||||
const result = classifyRelayCheckResponse(res, port)
|
||||
if (result.action === 'throw') throw new Error(result.error)
|
||||
setStatus(result.kind, result.message)
|
||||
} catch (err) {
|
||||
const result = classifyRelayCheckException(err, port)
|
||||
setStatus(result.kind, result.message)
|
||||
}
|
||||
}
|
||||
|
||||
async function load() {
|
||||
const stored = await chrome.storage.local.get(['relayPort', 'gatewayToken'])
|
||||
const port = clampPort(stored.relayPort)
|
||||
const token = String(stored.gatewayToken || '').trim()
|
||||
document.getElementById('port').value = String(port)
|
||||
document.getElementById('token').value = token
|
||||
updateRelayUrl(port)
|
||||
await checkRelayReachable(port, token)
|
||||
}
|
||||
|
||||
async function save() {
|
||||
const portInput = document.getElementById('port')
|
||||
const tokenInput = document.getElementById('token')
|
||||
const port = clampPort(portInput.value)
|
||||
const token = String(tokenInput.value || '').trim()
|
||||
await chrome.storage.local.set({ relayPort: port, gatewayToken: token })
|
||||
portInput.value = String(port)
|
||||
tokenInput.value = token
|
||||
updateRelayUrl(port)
|
||||
await checkRelayReachable(port, token)
|
||||
}
|
||||
|
||||
document.getElementById('save').addEventListener('click', () => void save())
|
||||
void load()
|
||||
@ -3550,6 +3550,234 @@
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh",
|
||||
"kind": "core",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.certificateData",
|
||||
"kind": "core",
|
||||
"type": [
|
||||
"object",
|
||||
"string"
|
||||
],
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": true,
|
||||
"tags": [
|
||||
"security",
|
||||
"storage"
|
||||
],
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.certificateData.id",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.certificateData.provider",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.certificateData.source",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.certificateFile",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.command",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.identityData",
|
||||
"kind": "core",
|
||||
"type": [
|
||||
"object",
|
||||
"string"
|
||||
],
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": true,
|
||||
"tags": [
|
||||
"security",
|
||||
"storage"
|
||||
],
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.identityData.id",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.identityData.provider",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.identityData.source",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.identityFile",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.knownHostsData",
|
||||
"kind": "core",
|
||||
"type": [
|
||||
"object",
|
||||
"string"
|
||||
],
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": true,
|
||||
"tags": [
|
||||
"security",
|
||||
"storage"
|
||||
],
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.knownHostsData.id",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.knownHostsData.provider",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.knownHostsData.source",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.knownHostsFile",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.strictHostKeyChecking",
|
||||
"kind": "core",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.target",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.updateHostKeys",
|
||||
"kind": "core",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.ssh.workspaceRoot",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.defaults.sandbox.workspaceAccess",
|
||||
"kind": "core",
|
||||
@ -5652,6 +5880,234 @@
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh",
|
||||
"kind": "core",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.certificateData",
|
||||
"kind": "core",
|
||||
"type": [
|
||||
"object",
|
||||
"string"
|
||||
],
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": true,
|
||||
"tags": [
|
||||
"security",
|
||||
"storage"
|
||||
],
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.certificateData.id",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.certificateData.provider",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.certificateData.source",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.certificateFile",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.command",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.identityData",
|
||||
"kind": "core",
|
||||
"type": [
|
||||
"object",
|
||||
"string"
|
||||
],
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": true,
|
||||
"tags": [
|
||||
"security",
|
||||
"storage"
|
||||
],
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.identityData.id",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.identityData.provider",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.identityData.source",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.identityFile",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.knownHostsData",
|
||||
"kind": "core",
|
||||
"type": [
|
||||
"object",
|
||||
"string"
|
||||
],
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": true,
|
||||
"tags": [
|
||||
"security",
|
||||
"storage"
|
||||
],
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.knownHostsData.id",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.knownHostsData.provider",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.knownHostsData.source",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.knownHostsFile",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.strictHostKeyChecking",
|
||||
"kind": "core",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.target",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.updateHostKeys",
|
||||
"kind": "core",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.ssh.workspaceRoot",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "agents.list.*.sandbox.workspaceAccess",
|
||||
"kind": "core",
|
||||
@ -7579,21 +8035,7 @@
|
||||
"storage"
|
||||
],
|
||||
"label": "Browser Profile Driver",
|
||||
"help": "Per-profile browser driver mode: \"openclaw\" (or legacy \"clawd\") or \"extension\" depending on connection/runtime strategy. Use the driver that matches your browser control stack to avoid protocol mismatches.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "browser.relayBindHost",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "Browser Relay Bind Address",
|
||||
"help": "Bind IP address for the Chrome extension relay listener. Leave unset for loopback-only access, or set an explicit non-loopback IP such as 0.0.0.0 only when the relay must be reachable across network namespaces (for example WSL2) and the surrounding network is already trusted.",
|
||||
"help": "Per-profile browser driver mode. Use \"openclaw\" (or legacy \"clawd\") for CDP-based profiles, or use \"existing-session\" for host-local Chrome MCP attachment.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
@ -39810,6 +40252,22 @@
|
||||
"help": "Debounce window (ms) before applying config changes.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "gateway.reload.deferralTimeoutMs",
|
||||
"kind": "core",
|
||||
"type": "integer",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"network",
|
||||
"performance",
|
||||
"reliability"
|
||||
],
|
||||
"label": "Restart Deferral Timeout (ms)",
|
||||
"help": "Maximum time (ms) to wait for in-flight operations to complete before forcing a SIGUSR1 restart. Default: 300000 (5 minutes). Lower values risk aborting active subagent LLM calls.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "gateway.reload.mode",
|
||||
"kind": "core",
|
||||
@ -44537,6 +44995,75 @@
|
||||
"help": "Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.amazon-bedrock",
|
||||
"kind": "plugin",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "@openclaw/amazon-bedrock-provider",
|
||||
"help": "OpenClaw Amazon Bedrock provider plugin (plugin: amazon-bedrock)",
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.amazon-bedrock.config",
|
||||
"kind": "plugin",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "@openclaw/amazon-bedrock-provider Config",
|
||||
"help": "Plugin-defined config payload for amazon-bedrock.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.amazon-bedrock.enabled",
|
||||
"kind": "plugin",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "Enable @openclaw/amazon-bedrock-provider",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.amazon-bedrock.hooks",
|
||||
"kind": "plugin",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "Plugin Hook Policy",
|
||||
"help": "Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.",
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.amazon-bedrock.hooks.allowPromptInjection",
|
||||
"kind": "plugin",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"access"
|
||||
],
|
||||
"label": "Allow Prompt Injection Hooks",
|
||||
"help": "Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.anthropic",
|
||||
"kind": "plugin",
|
||||
@ -45647,6 +46174,75 @@
|
||||
"help": "Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.firecrawl",
|
||||
"kind": "plugin",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "@openclaw/firecrawl-plugin",
|
||||
"help": "OpenClaw Firecrawl plugin (plugin: firecrawl)",
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.firecrawl.config",
|
||||
"kind": "plugin",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "@openclaw/firecrawl-plugin Config",
|
||||
"help": "Plugin-defined config payload for firecrawl.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.firecrawl.enabled",
|
||||
"kind": "plugin",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "Enable @openclaw/firecrawl-plugin",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.firecrawl.hooks",
|
||||
"kind": "plugin",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "Plugin Hook Policy",
|
||||
"help": "Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.",
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.firecrawl.hooks.allowPromptInjection",
|
||||
"kind": "plugin",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"access"
|
||||
],
|
||||
"label": "Allow Prompt Injection Hooks",
|
||||
"help": "Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.entries.github-copilot",
|
||||
"kind": "plugin",
|
||||
@ -51342,6 +51938,48 @@
|
||||
"help": "Resolved npm dist integrity hash for the fetched artifact (if reported by npm).",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.installs.*.marketplaceName",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "Plugin Marketplace Name",
|
||||
"help": "Marketplace display name recorded for marketplace-backed plugin installs (if available).",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.installs.*.marketplacePlugin",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "Plugin Marketplace Plugin",
|
||||
"help": "Plugin entry name inside the source marketplace, used for later updates.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.installs.*.marketplaceSource",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"advanced"
|
||||
],
|
||||
"label": "Plugin Marketplace Source",
|
||||
"help": "Original marketplace source used to resolve the install (for example a repo path or Git URL).",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "plugins.installs.*.resolvedAt",
|
||||
"kind": "core",
|
||||
@ -57513,6 +58151,79 @@
|
||||
"help": "Enable the web_search tool (requires a provider API key).",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "tools.web.search.firecrawl",
|
||||
"kind": "core",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "tools.web.search.firecrawl.apiKey",
|
||||
"kind": "core",
|
||||
"type": [
|
||||
"object",
|
||||
"string"
|
||||
],
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": true,
|
||||
"tags": [
|
||||
"auth",
|
||||
"security",
|
||||
"tools"
|
||||
],
|
||||
"label": "Firecrawl Search API Key",
|
||||
"help": "Firecrawl API key for web search (fallback: FIRECRAWL_API_KEY env var).",
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
"path": "tools.web.search.firecrawl.apiKey.id",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "tools.web.search.firecrawl.apiKey.provider",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "tools.web.search.firecrawl.apiKey.source",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [],
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "tools.web.search.firecrawl.baseUrl",
|
||||
"kind": "core",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"deprecated": false,
|
||||
"sensitive": false,
|
||||
"tags": [
|
||||
"tools"
|
||||
],
|
||||
"label": "Firecrawl Search Base URL",
|
||||
"help": "Firecrawl Search base URL override (default: \"https://api.firecrawl.dev\").",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
"path": "tools.web.search.gemini",
|
||||
"kind": "core",
|
||||
@ -57873,7 +58584,7 @@
|
||||
"tools"
|
||||
],
|
||||
"label": "Web Search Provider",
|
||||
"help": "Search provider (\"brave\", \"gemini\", \"grok\", \"kimi\", or \"perplexity\"). Auto-detected from available API keys if omitted.",
|
||||
"help": "Search provider (\"brave\", \"firecrawl\", \"gemini\", \"grok\", \"kimi\", or \"perplexity\"). Auto-detected from available API keys if omitted.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
@ -58206,7 +58917,7 @@
|
||||
"advanced"
|
||||
],
|
||||
"label": "Setup Wizard State",
|
||||
"help": "Setup wizard state tracking fields that record the most recent guided onboarding run details. Keep these fields for observability and troubleshooting of setup flows across upgrades.",
|
||||
"help": "Setup wizard state tracking fields that record the most recent guided setup run details. Keep these fields for observability and troubleshooting of setup flows across upgrades.",
|
||||
"hasChildren": true
|
||||
},
|
||||
{
|
||||
@ -58220,7 +58931,7 @@
|
||||
"advanced"
|
||||
],
|
||||
"label": "Wizard Last Run Timestamp",
|
||||
"help": "ISO timestamp for when the setup wizard most recently completed on this host. Use this to confirm onboarding recency during support and operational audits.",
|
||||
"help": "ISO timestamp for when the setup wizard most recently completed on this host. Use this to confirm setup recency during support and operational audits.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
@ -58234,7 +58945,7 @@
|
||||
"advanced"
|
||||
],
|
||||
"label": "Wizard Last Run Command",
|
||||
"help": "Command invocation recorded for the latest wizard run to preserve execution context. Use this to reproduce onboarding steps when verifying setup regressions.",
|
||||
"help": "Command invocation recorded for the latest wizard run to preserve execution context. Use this to reproduce setup steps when verifying setup regressions.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
@ -58248,7 +58959,7 @@
|
||||
"advanced"
|
||||
],
|
||||
"label": "Wizard Last Run Commit",
|
||||
"help": "Source commit identifier recorded for the last wizard execution in development builds. Use this to correlate onboarding behavior with exact source state during debugging.",
|
||||
"help": "Source commit identifier recorded for the last wizard execution in development builds. Use this to correlate setup behavior with exact source state during debugging.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
@ -58262,7 +58973,7 @@
|
||||
"advanced"
|
||||
],
|
||||
"label": "Wizard Last Run Mode",
|
||||
"help": "Wizard execution mode recorded as \"local\" or \"remote\" for the most recent onboarding flow. Use this to understand whether setup targeted direct local runtime or remote gateway topology.",
|
||||
"help": "Wizard execution mode recorded as \"local\" or \"remote\" for the most recent setup flow. Use this to understand whether setup targeted direct local runtime or remote gateway topology.",
|
||||
"hasChildren": false
|
||||
},
|
||||
{
|
||||
@ -58276,7 +58987,7 @@
|
||||
"advanced"
|
||||
],
|
||||
"label": "Wizard Last Run Version",
|
||||
"help": "OpenClaw version recorded at the time of the most recent wizard run on this config. Use this when diagnosing behavior differences across version-to-version onboarding changes.",
|
||||
"help": "OpenClaw version recorded at the time of the most recent wizard run on this config. Use this when diagnosing behavior differences across version-to-version setup changes.",
|
||||
"hasChildren": false
|
||||
}
|
||||
]
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
{"generatedBy":"scripts/generate-config-doc-baseline.ts","recordType":"meta","totalPaths":5040}
|
||||
{"generatedBy":"scripts/generate-config-doc-baseline.ts","recordType":"meta","totalPaths":5101}
|
||||
{"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}
|
||||
@ -302,6 +302,27 @@
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.prune.maxAgeDays","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.scope","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.sessionToolsVisibility","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.certificateData","kind":"core","type":["object","string"],"required":false,"deprecated":false,"sensitive":true,"tags":["security","storage"],"hasChildren":true}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.certificateData.id","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.certificateData.provider","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.certificateData.source","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.certificateFile","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.command","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.identityData","kind":"core","type":["object","string"],"required":false,"deprecated":false,"sensitive":true,"tags":["security","storage"],"hasChildren":true}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.identityData.id","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.identityData.provider","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.identityData.source","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.identityFile","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.knownHostsData","kind":"core","type":["object","string"],"required":false,"deprecated":false,"sensitive":true,"tags":["security","storage"],"hasChildren":true}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.knownHostsData.id","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.knownHostsData.provider","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.knownHostsData.source","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.knownHostsFile","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.strictHostKeyChecking","kind":"core","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.target","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.updateHostKeys","kind":"core","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.ssh.workspaceRoot","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.workspaceAccess","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.sandbox.workspaceRoot","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.defaults.skipBootstrap","kind":"core","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
@ -503,6 +524,27 @@
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.prune.maxAgeDays","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.scope","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.sessionToolsVisibility","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.certificateData","kind":"core","type":["object","string"],"required":false,"deprecated":false,"sensitive":true,"tags":["security","storage"],"hasChildren":true}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.certificateData.id","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.certificateData.provider","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.certificateData.source","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.certificateFile","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.command","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.identityData","kind":"core","type":["object","string"],"required":false,"deprecated":false,"sensitive":true,"tags":["security","storage"],"hasChildren":true}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.identityData.id","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.identityData.provider","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.identityData.source","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.identityFile","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.knownHostsData","kind":"core","type":["object","string"],"required":false,"deprecated":false,"sensitive":true,"tags":["security","storage"],"hasChildren":true}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.knownHostsData.id","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.knownHostsData.provider","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.knownHostsData.source","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.knownHostsFile","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.strictHostKeyChecking","kind":"core","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.target","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.updateHostKeys","kind":"core","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.ssh.workspaceRoot","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.workspaceAccess","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.sandbox.workspaceRoot","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"agents.list.*.skills","kind":"core","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Agent Skill Filter","help":"Optional allowlist of skills for this agent (omit = all skills; empty = no skills).","hasChildren":true}
|
||||
@ -665,8 +707,7 @@
|
||||
{"recordType":"path","path":"browser.profiles.*.cdpPort","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Browser Profile CDP Port","help":"Per-profile local CDP port used when connecting to browser instances by port instead of URL. Use unique ports per profile to avoid connection collisions.","hasChildren":false}
|
||||
{"recordType":"path","path":"browser.profiles.*.cdpUrl","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Browser Profile CDP URL","help":"Per-profile CDP websocket URL used for explicit remote browser routing by profile name. Use this when profile connections terminate on remote hosts or tunnels.","hasChildren":false}
|
||||
{"recordType":"path","path":"browser.profiles.*.color","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Browser Profile Accent Color","help":"Per-profile accent color for visual differentiation in dashboards and browser-related UI hints. Use distinct colors for high-signal operator recognition of active profiles.","hasChildren":false}
|
||||
{"recordType":"path","path":"browser.profiles.*.driver","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Browser Profile Driver","help":"Per-profile browser driver mode: \"openclaw\" (or legacy \"clawd\") or \"extension\" depending on connection/runtime strategy. Use the driver that matches your browser control stack to avoid protocol mismatches.","hasChildren":false}
|
||||
{"recordType":"path","path":"browser.relayBindHost","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Browser Relay Bind Address","help":"Bind IP address for the Chrome extension relay listener. Leave unset for loopback-only access, or set an explicit non-loopback IP such as 0.0.0.0 only when the relay must be reachable across network namespaces (for example WSL2) and the surrounding network is already trusted.","hasChildren":false}
|
||||
{"recordType":"path","path":"browser.profiles.*.driver","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Browser Profile Driver","help":"Per-profile browser driver mode. Use \"openclaw\" (or legacy \"clawd\") for CDP-based profiles, or use \"existing-session\" for host-local Chrome MCP attachment.","hasChildren":false}
|
||||
{"recordType":"path","path":"browser.remoteCdpHandshakeTimeoutMs","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["performance"],"label":"Remote CDP Handshake Timeout (ms)","help":"Timeout in milliseconds for post-connect CDP handshake readiness checks against remote browser targets. Raise this for slow-start remote browsers and lower to fail fast in automation loops.","hasChildren":false}
|
||||
{"recordType":"path","path":"browser.remoteCdpTimeoutMs","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["performance"],"label":"Remote CDP Timeout (ms)","help":"Timeout in milliseconds for connecting to a remote CDP endpoint before failing the browser attach attempt. Increase for high-latency tunnels, or lower for faster failure detection.","hasChildren":false}
|
||||
{"recordType":"path","path":"browser.snapshotDefaults","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Browser Snapshot Defaults","help":"Default snapshot capture configuration used when callers do not provide explicit snapshot options. Tune this for consistent capture behavior across channels and automation paths.","hasChildren":true}
|
||||
@ -3562,6 +3603,7 @@
|
||||
{"recordType":"path","path":"gateway.push.apns.relay.timeoutMs","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["network","performance"],"label":"Gateway APNs Relay Timeout (ms)","help":"Timeout in milliseconds for relay send requests from the gateway to the APNs relay (default: 10000). Increase for slower relays or networks, or lower to fail wake attempts faster.","hasChildren":false}
|
||||
{"recordType":"path","path":"gateway.reload","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["network","reliability"],"label":"Config Reload","help":"Live config-reload policy for how edits are applied and when full restarts are triggered. Keep hybrid behavior for safest operational updates unless debugging reload internals.","hasChildren":true}
|
||||
{"recordType":"path","path":"gateway.reload.debounceMs","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["network","performance","reliability"],"label":"Config Reload Debounce (ms)","help":"Debounce window (ms) before applying config changes.","hasChildren":false}
|
||||
{"recordType":"path","path":"gateway.reload.deferralTimeoutMs","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["network","performance","reliability"],"label":"Restart Deferral Timeout (ms)","help":"Maximum time (ms) to wait for in-flight operations to complete before forcing a SIGUSR1 restart. Default: 300000 (5 minutes). Lower values risk aborting active subagent LLM calls.","hasChildren":false}
|
||||
{"recordType":"path","path":"gateway.reload.mode","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["network","reliability"],"label":"Config Reload Mode","help":"Controls how config edits are applied: \"off\" ignores live edits, \"restart\" always restarts, \"hot\" applies in-process, and \"hybrid\" tries hot then restarts if required. Keep \"hybrid\" for safest routine updates.","hasChildren":false}
|
||||
{"recordType":"path","path":"gateway.remote","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["network"],"label":"Remote Gateway","help":"Remote gateway connection settings for direct or SSH transport when this instance proxies to another runtime host. Use remote mode only when split-host operation is intentionally configured.","hasChildren":true}
|
||||
{"recordType":"path","path":"gateway.remote.password","kind":"core","type":["object","string"],"required":false,"deprecated":false,"sensitive":true,"tags":["auth","network","security"],"label":"Remote Gateway Password","help":"Password credential used for remote gateway authentication when password mode is enabled. Keep this secret managed externally and avoid plaintext values in committed config.","hasChildren":true}
|
||||
@ -3944,6 +3986,11 @@
|
||||
{"recordType":"path","path":"plugins.entries.acpx.enabled","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Enable ACPX Runtime","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.acpx.hooks","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Hook Policy","help":"Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.","hasChildren":true}
|
||||
{"recordType":"path","path":"plugins.entries.acpx.hooks.allowPromptInjection","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"Allow Prompt Injection Hooks","help":"Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.amazon-bedrock","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/amazon-bedrock-provider","help":"OpenClaw Amazon Bedrock provider plugin (plugin: amazon-bedrock)","hasChildren":true}
|
||||
{"recordType":"path","path":"plugins.entries.amazon-bedrock.config","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/amazon-bedrock-provider Config","help":"Plugin-defined config payload for amazon-bedrock.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.amazon-bedrock.enabled","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Enable @openclaw/amazon-bedrock-provider","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.amazon-bedrock.hooks","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Hook Policy","help":"Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.","hasChildren":true}
|
||||
{"recordType":"path","path":"plugins.entries.amazon-bedrock.hooks.allowPromptInjection","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"Allow Prompt Injection Hooks","help":"Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.anthropic","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/anthropic-provider","help":"OpenClaw Anthropic provider plugin (plugin: anthropic)","hasChildren":true}
|
||||
{"recordType":"path","path":"plugins.entries.anthropic.config","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/anthropic-provider Config","help":"Plugin-defined config payload for anthropic.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.anthropic.enabled","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Enable @openclaw/anthropic-provider","hasChildren":false}
|
||||
@ -4022,6 +4069,11 @@
|
||||
{"recordType":"path","path":"plugins.entries.feishu.enabled","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Enable @openclaw/feishu","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.feishu.hooks","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Hook Policy","help":"Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.","hasChildren":true}
|
||||
{"recordType":"path","path":"plugins.entries.feishu.hooks.allowPromptInjection","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"Allow Prompt Injection Hooks","help":"Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.firecrawl","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/firecrawl-plugin","help":"OpenClaw Firecrawl plugin (plugin: firecrawl)","hasChildren":true}
|
||||
{"recordType":"path","path":"plugins.entries.firecrawl.config","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/firecrawl-plugin Config","help":"Plugin-defined config payload for firecrawl.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.firecrawl.enabled","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Enable @openclaw/firecrawl-plugin","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.firecrawl.hooks","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Hook Policy","help":"Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.","hasChildren":true}
|
||||
{"recordType":"path","path":"plugins.entries.firecrawl.hooks.allowPromptInjection","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"Allow Prompt Injection Hooks","help":"Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.github-copilot","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/github-copilot-provider","help":"OpenClaw GitHub Copilot provider plugin (plugin: github-copilot)","hasChildren":true}
|
||||
{"recordType":"path","path":"plugins.entries.github-copilot.config","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/github-copilot-provider Config","help":"Plugin-defined config payload for github-copilot.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.entries.github-copilot.enabled","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Enable @openclaw/github-copilot-provider","hasChildren":false}
|
||||
@ -4454,6 +4506,9 @@
|
||||
{"recordType":"path","path":"plugins.installs.*.installedAt","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Install Time","help":"ISO timestamp of last install/update.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.installs.*.installPath","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Plugin Install Path","help":"Resolved install directory (usually ~/.openclaw/extensions/<id>).","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.installs.*.integrity","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Resolved Integrity","help":"Resolved npm dist integrity hash for the fetched artifact (if reported by npm).","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.installs.*.marketplaceName","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Marketplace Name","help":"Marketplace display name recorded for marketplace-backed plugin installs (if available).","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.installs.*.marketplacePlugin","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Marketplace Plugin","help":"Plugin entry name inside the source marketplace, used for later updates.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.installs.*.marketplaceSource","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Marketplace Source","help":"Original marketplace source used to resolve the install (for example a repo path or Git URL).","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.installs.*.resolvedAt","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Resolution Time","help":"ISO timestamp when npm package metadata was last resolved for this install record.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.installs.*.resolvedName","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Resolved Package Name","help":"Resolved npm package name from the fetched artifact.","hasChildren":false}
|
||||
{"recordType":"path","path":"plugins.installs.*.resolvedSpec","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Resolved Package Spec","help":"Resolved exact npm spec (<name>@<version>) from the fetched artifact.","hasChildren":false}
|
||||
@ -4981,6 +5036,12 @@
|
||||
{"recordType":"path","path":"tools.web.search.brave.mode","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["tools"],"label":"Brave Search Mode","help":"Brave Search mode: \"web\" (URL results) or \"llm-context\" (pre-extracted page content for LLM grounding).","hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.cacheTtlMinutes","kind":"core","type":"number","required":false,"deprecated":false,"sensitive":false,"tags":["performance","storage","tools"],"label":"Web Search Cache TTL (min)","help":"Cache TTL in minutes for web_search results.","hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.enabled","kind":"core","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["tools"],"label":"Enable Web Search Tool","help":"Enable the web_search tool (requires a provider API key).","hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.firecrawl","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
|
||||
{"recordType":"path","path":"tools.web.search.firecrawl.apiKey","kind":"core","type":["object","string"],"required":false,"deprecated":false,"sensitive":true,"tags":["auth","security","tools"],"label":"Firecrawl Search API Key","help":"Firecrawl API key for web search (fallback: FIRECRAWL_API_KEY env var).","hasChildren":true}
|
||||
{"recordType":"path","path":"tools.web.search.firecrawl.apiKey.id","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.firecrawl.apiKey.provider","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.firecrawl.apiKey.source","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.firecrawl.baseUrl","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["tools"],"label":"Firecrawl Search Base URL","help":"Firecrawl Search base URL override (default: \"https://api.firecrawl.dev\").","hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.gemini","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
|
||||
{"recordType":"path","path":"tools.web.search.gemini.apiKey","kind":"core","type":["object","string"],"required":false,"deprecated":false,"sensitive":true,"tags":["auth","security","tools"],"label":"Gemini Search API Key","help":"Gemini API key for Google Search grounding (fallback: GEMINI_API_KEY env var).","hasChildren":true}
|
||||
{"recordType":"path","path":"tools.web.search.gemini.apiKey.id","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
@ -5009,7 +5070,7 @@
|
||||
{"recordType":"path","path":"tools.web.search.perplexity.apiKey.source","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.perplexity.baseUrl","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["tools"],"label":"Perplexity Base URL","help":"Optional Perplexity/OpenRouter chat-completions base URL override. Setting this opts Perplexity into the legacy Sonar/OpenRouter compatibility path.","hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.perplexity.model","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["models","tools"],"label":"Perplexity Model","help":"Optional Sonar/OpenRouter model override (default: \"perplexity/sonar-pro\"). Setting this opts Perplexity into the legacy chat-completions compatibility path.","hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.provider","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["tools"],"label":"Web Search Provider","help":"Search provider (\"brave\", \"gemini\", \"grok\", \"kimi\", or \"perplexity\"). Auto-detected from available API keys if omitted.","hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.provider","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["tools"],"label":"Web Search Provider","help":"Search provider (\"brave\", \"firecrawl\", \"gemini\", \"grok\", \"kimi\", or \"perplexity\"). Auto-detected from available API keys if omitted.","hasChildren":false}
|
||||
{"recordType":"path","path":"tools.web.search.timeoutSeconds","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["performance","tools"],"label":"Web Search Timeout (sec)","help":"Timeout in seconds for web_search requests.","hasChildren":false}
|
||||
{"recordType":"path","path":"ui","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"UI","help":"UI presentation settings for accenting and assistant identity shown in control surfaces. Use this for branding and readability customization without changing runtime behavior.","hasChildren":true}
|
||||
{"recordType":"path","path":"ui.assistant","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Assistant Appearance","help":"Assistant display identity settings for name and avatar shown in UI surfaces. Keep these values aligned with your operator-facing persona and support expectations.","hasChildren":true}
|
||||
@ -5033,9 +5094,9 @@
|
||||
{"recordType":"path","path":"web.reconnect.jitter","kind":"core","type":"number","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Web Reconnect Jitter","help":"Randomization factor (0-1) applied to reconnect delays to desynchronize clients after outage events. Keep non-zero jitter in multi-client deployments to reduce synchronized spikes.","hasChildren":false}
|
||||
{"recordType":"path","path":"web.reconnect.maxAttempts","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["performance"],"label":"Web Reconnect Max Attempts","help":"Maximum reconnect attempts before giving up for the current failure sequence (0 means no retries). Use finite caps for controlled failure handling in automation-sensitive environments.","hasChildren":false}
|
||||
{"recordType":"path","path":"web.reconnect.maxMs","kind":"core","type":"number","required":false,"deprecated":false,"sensitive":false,"tags":["performance"],"label":"Web Reconnect Max Delay (ms)","help":"Maximum reconnect backoff cap in milliseconds to bound retry delay growth over repeated failures. Use a reasonable cap so recovery remains timely after prolonged outages.","hasChildren":false}
|
||||
{"recordType":"path","path":"wizard","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Setup Wizard State","help":"Setup wizard state tracking fields that record the most recent guided onboarding run details. Keep these fields for observability and troubleshooting of setup flows across upgrades.","hasChildren":true}
|
||||
{"recordType":"path","path":"wizard.lastRunAt","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Wizard Last Run Timestamp","help":"ISO timestamp for when the setup wizard most recently completed on this host. Use this to confirm onboarding recency during support and operational audits.","hasChildren":false}
|
||||
{"recordType":"path","path":"wizard.lastRunCommand","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Wizard Last Run Command","help":"Command invocation recorded for the latest wizard run to preserve execution context. Use this to reproduce onboarding steps when verifying setup regressions.","hasChildren":false}
|
||||
{"recordType":"path","path":"wizard.lastRunCommit","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Wizard Last Run Commit","help":"Source commit identifier recorded for the last wizard execution in development builds. Use this to correlate onboarding behavior with exact source state during debugging.","hasChildren":false}
|
||||
{"recordType":"path","path":"wizard.lastRunMode","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Wizard Last Run Mode","help":"Wizard execution mode recorded as \"local\" or \"remote\" for the most recent onboarding flow. Use this to understand whether setup targeted direct local runtime or remote gateway topology.","hasChildren":false}
|
||||
{"recordType":"path","path":"wizard.lastRunVersion","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Wizard Last Run Version","help":"OpenClaw version recorded at the time of the most recent wizard run on this config. Use this when diagnosing behavior differences across version-to-version onboarding changes.","hasChildren":false}
|
||||
{"recordType":"path","path":"wizard","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Setup Wizard State","help":"Setup wizard state tracking fields that record the most recent guided setup run details. Keep these fields for observability and troubleshooting of setup flows across upgrades.","hasChildren":true}
|
||||
{"recordType":"path","path":"wizard.lastRunAt","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Wizard Last Run Timestamp","help":"ISO timestamp for when the setup wizard most recently completed on this host. Use this to confirm setup recency during support and operational audits.","hasChildren":false}
|
||||
{"recordType":"path","path":"wizard.lastRunCommand","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Wizard Last Run Command","help":"Command invocation recorded for the latest wizard run to preserve execution context. Use this to reproduce setup steps when verifying setup regressions.","hasChildren":false}
|
||||
{"recordType":"path","path":"wizard.lastRunCommit","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Wizard Last Run Commit","help":"Source commit identifier recorded for the last wizard execution in development builds. Use this to correlate setup behavior with exact source state during debugging.","hasChildren":false}
|
||||
{"recordType":"path","path":"wizard.lastRunMode","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Wizard Last Run Mode","help":"Wizard execution mode recorded as \"local\" or \"remote\" for the most recent setup flow. Use this to understand whether setup targeted direct local runtime or remote gateway topology.","hasChildren":false}
|
||||
{"recordType":"path","path":"wizard.lastRunVersion","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Wizard Last Run Version","help":"OpenClaw version recorded at the time of the most recent wizard run on this config. Use this when diagnosing behavior differences across version-to-version setup changes.","hasChildren":false}
|
||||
|
||||
@ -47,6 +47,18 @@
|
||||
"source": "Quick Start",
|
||||
"target": "快速开始"
|
||||
},
|
||||
{
|
||||
"source": "Setup Wizard Reference",
|
||||
"target": "设置向导参考"
|
||||
},
|
||||
{
|
||||
"source": "CLI Setup Reference",
|
||||
"target": "CLI 设置参考"
|
||||
},
|
||||
{
|
||||
"source": "Setup Wizard (CLI)",
|
||||
"target": "设置向导（CLI）"
|
||||
},
|
||||
{
|
||||
"source": "Docs directory",
|
||||
"target": "文档目录"
|
||||
|
||||
@ -711,7 +711,7 @@ Key options:
|
||||
- ✅ Images
|
||||
- ✅ Files
|
||||
- ✅ Audio
|
||||
- ✅ Video
|
||||
- ✅ Video/media
|
||||
- ✅ Stickers
|
||||
|
||||
### Send
|
||||
@ -720,4 +720,28 @@ Key options:
|
||||
- ✅ Images
|
||||
- ✅ Files
|
||||
- ✅ Audio
|
||||
- ⚠️ Rich text (partial support)
|
||||
- ✅ Video/media
|
||||
- ✅ Interactive cards
|
||||
- ⚠️ Rich text (post-style formatting and cards, not arbitrary Feishu authoring features)
|
||||
|
||||
### Threads and replies
|
||||
|
||||
- ✅ Inline replies
|
||||
- ✅ Topic-thread replies where Feishu exposes `reply_in_thread`
|
||||
- ✅ Media replies stay thread-aware when replying to a thread/topic message
|
||||
|
||||
## Runtime action surface
|
||||
|
||||
Feishu currently exposes these runtime actions:
|
||||
|
||||
- `send`
|
||||
- `read`
|
||||
- `edit`
|
||||
- `thread-reply`
|
||||
- `pin`
|
||||
- `list-pins`
|
||||
- `unpin`
|
||||
- `member-info`
|
||||
- `channel-info`
|
||||
- `channel-list`
|
||||
- `react` and `reactions` when reactions are enabled in config
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
---
|
||||
summary: "CLI reference for `openclaw browser` (profiles, tabs, actions, extension relay)"
|
||||
summary: "CLI reference for `openclaw browser` (profiles, tabs, actions, Chrome MCP, and CDP)"
|
||||
read_when:
|
||||
- You use `openclaw browser` and want examples for common tasks
|
||||
- You want to control a browser running on another machine via a node host
|
||||
- You want to use the Chrome extension relay (attach/detach via toolbar button)
|
||||
- You want to attach to your local signed-in Chrome via Chrome MCP
|
||||
title: "browser"
|
||||
---
|
||||
|
||||
@ -14,7 +14,6 @@ Manage OpenClaw’s browser control server and run browser actions (tabs, snapsh
|
||||
Related:
|
||||
|
||||
- Browser tool + API: [Browser tool](/tools/browser)
|
||||
- Chrome extension relay: [Chrome extension](/tools/chrome-extension)
|
||||
|
||||
## Common flags
|
||||
|
||||
@ -37,13 +36,14 @@ openclaw browser --browser-profile openclaw snapshot
|
||||
|
||||
Profiles are named browser routing configs. In practice:
|
||||
|
||||
- `openclaw`: launches/attaches to a dedicated OpenClaw-managed Chrome instance (isolated user data dir).
|
||||
- `openclaw`: launches or attaches to a dedicated OpenClaw-managed Chrome instance (isolated user data dir).
|
||||
- `user`: controls your existing signed-in Chrome session via Chrome DevTools MCP.
|
||||
- `chrome-relay`: controls your existing Chrome tab(s) via the Chrome extension relay.
|
||||
- custom CDP profiles: point at a local or remote CDP endpoint.
|
||||
|
||||
```bash
|
||||
openclaw browser profiles
|
||||
openclaw browser create-profile --name work --color "#FF5A36"
|
||||
openclaw browser create-profile --name chrome-live --driver existing-session
|
||||
openclaw browser delete-profile --name work
|
||||
```
|
||||
|
||||
@ -84,20 +84,17 @@ openclaw browser click <ref>
|
||||
openclaw browser type <ref> "hello"
|
||||
```
|
||||
|
||||
## Chrome extension relay (attach via toolbar button)
|
||||
## Existing Chrome via MCP
|
||||
|
||||
This mode lets the agent control an existing Chrome tab that you attach manually (it does not auto-attach).
|
||||
|
||||
Install the unpacked extension to a stable path:
|
||||
Use the built-in `user` profile, or create your own `existing-session` profile:
|
||||
|
||||
```bash
|
||||
openclaw browser extension install
|
||||
openclaw browser extension path
|
||||
openclaw browser --browser-profile user tabs
|
||||
openclaw browser create-profile --name chrome-live --driver existing-session
|
||||
openclaw browser --browser-profile chrome-live tabs
|
||||
```
|
||||
|
||||
Then Chrome → `chrome://extensions` → enable “Developer mode” → “Load unpacked” → select the printed folder.
|
||||
|
||||
Full guide: [Chrome extension](/tools/chrome-extension)
|
||||
This path is host-only. For Docker, headless servers, Browserless, or other remote setups, use a CDP profile instead.
|
||||
|
||||
## Remote browser control (node host proxy)
|
||||
|
||||
|
||||
@ -10,6 +10,6 @@ title: "docs"
|
||||
Search the live docs index.
|
||||
|
||||
```bash
|
||||
openclaw docs browser extension
|
||||
openclaw docs browser existing-session
|
||||
openclaw docs sandbox allowHostControl
|
||||
```
|
||||
|
||||
@ -284,7 +284,8 @@ Manage extensions and their config:
|
||||
|
||||
- `openclaw plugins list` — discover plugins (use `--json` for machine output).
|
||||
- `openclaw plugins info <id>` — show details for a plugin.
|
||||
- `openclaw plugins install <path|.tgz|npm-spec>` — install a plugin (or add a plugin path to `plugins.load.paths`).
|
||||
- `openclaw plugins install <path|.tgz|npm-spec|plugin@marketplace>` — install a plugin (or add a plugin path to `plugins.load.paths`).
|
||||
- `openclaw plugins marketplace list <marketplace>` — list marketplace entries before install.
|
||||
- `openclaw plugins enable <id>` / `disable <id>` — toggle `plugins.entries.<id>.enabled`.
|
||||
- `openclaw plugins doctor` — report plugin load errors.
|
||||
|
||||
@ -317,7 +318,7 @@ Initialize config + workspace.
|
||||
Options:
|
||||
|
||||
- `--workspace <dir>`: agent workspace path (default `~/.openclaw/workspace`).
|
||||
- `--wizard`: run the onboarding wizard.
|
||||
- `--wizard`: run the setup wizard.
|
||||
- `--non-interactive`: run wizard without prompts.
|
||||
- `--mode <local|remote>`: wizard mode.
|
||||
- `--remote-url <url>`: remote Gateway URL.
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
summary: "CLI reference for `openclaw onboard` (interactive onboarding wizard)"
|
||||
summary: "CLI reference for `openclaw onboard` (interactive setup wizard)"
|
||||
read_when:
|
||||
- You want guided setup for gateway, workspace, auth, channels, and skills
|
||||
title: "onboard"
|
||||
@ -7,13 +7,13 @@ title: "onboard"
|
||||
|
||||
# `openclaw onboard`
|
||||
|
||||
Interactive onboarding wizard (local or remote Gateway setup).
|
||||
Interactive setup wizard (local or remote Gateway setup).
|
||||
|
||||
## Related guides
|
||||
|
||||
- CLI onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
|
||||
- CLI onboarding hub: [Setup Wizard (CLI)](/start/wizard)
|
||||
- Onboarding overview: [Onboarding Overview](/start/onboarding-overview)
|
||||
- CLI onboarding reference: [CLI Onboarding Reference](/start/wizard-cli-reference)
|
||||
- CLI onboarding reference: [CLI Setup Reference](/start/wizard-cli-reference)
|
||||
- CLI automation: [CLI Automation](/start/wizard-cli-automation)
|
||||
- macOS onboarding: [Onboarding (macOS App)](/start/onboarding)
|
||||
|
||||
@ -140,7 +140,7 @@ Flow notes:
|
||||
|
||||
- `quickstart`: minimal prompts, auto-generates a gateway token.
|
||||
- `manual`: full prompts for port/bind/auth (alias of `advanced`).
|
||||
- Local onboarding DM scope behavior: [CLI Onboarding Reference](/start/wizard-cli-reference#outputs-and-internals).
|
||||
- Local onboarding DM scope behavior: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals).
|
||||
- Fastest first chat: `openclaw dashboard` (Control UI, no channel setup).
|
||||
- Custom Provider: connect any OpenAI or Anthropic compatible endpoint,
|
||||
including hosted providers not listed. Use Unknown to auto-detect.
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
summary: "CLI reference for `openclaw plugins` (list, install, uninstall, enable/disable, doctor)"
|
||||
summary: "CLI reference for `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)"
|
||||
read_when:
|
||||
- You want to install or manage Gateway plugins or compatible bundles
|
||||
- You want to debug plugin load failures
|
||||
@ -28,6 +28,7 @@ openclaw plugins uninstall <id>
|
||||
openclaw plugins doctor
|
||||
openclaw plugins update <id>
|
||||
openclaw plugins update --all
|
||||
openclaw plugins marketplace list <marketplace>
|
||||
```
|
||||
|
||||
Bundled plugins ship with OpenClaw but start disabled. Use `plugins enable` to
|
||||
@ -46,6 +47,8 @@ capabilities.
|
||||
```bash
|
||||
openclaw plugins install <path-or-spec>
|
||||
openclaw plugins install <npm-spec> --pin
|
||||
openclaw plugins install <plugin>@<marketplace>
|
||||
openclaw plugins install <plugin> --marketplace <marketplace>
|
||||
```
|
||||
|
||||
Security note: treat plugin installs like running code. Prefer pinned versions.
|
||||
@ -65,6 +68,31 @@ name, use an explicit scoped spec (for example `@scope/diffs`).
|
||||
|
||||
Supported archives: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
|
||||
|
||||
Claude marketplace installs are also supported.
|
||||
|
||||
Use `plugin@marketplace` shorthand when the marketplace name exists in Claude's
|
||||
local registry cache at `~/.claude/plugins/known_marketplaces.json`:
|
||||
|
||||
```bash
|
||||
openclaw plugins marketplace list <marketplace-name>
|
||||
openclaw plugins install <plugin-name>@<marketplace-name>
|
||||
```
|
||||
|
||||
Use `--marketplace` when you want to pass the marketplace source explicitly:
|
||||
|
||||
```bash
|
||||
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
|
||||
openclaw plugins install <plugin-name> --marketplace <owner/repo>
|
||||
openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
```
|
||||
|
||||
Marketplace sources can be:
|
||||
|
||||
- a Claude known-marketplace name from `~/.claude/plugins/known_marketplaces.json`
|
||||
- a local marketplace root or `marketplace.json` path
|
||||
- a GitHub repo shorthand such as `owner/repo`
|
||||
- a git URL
|
||||
|
||||
For local paths and archives, OpenClaw auto-detects:
|
||||
|
||||
- native OpenClaw plugins (`openclaw.plugin.json`)
|
||||
@ -114,7 +142,8 @@ openclaw plugins update --all
|
||||
openclaw plugins update <id> --dry-run
|
||||
```
|
||||
|
||||
Updates only apply to plugins installed from npm (tracked in `plugins.installs`).
|
||||
Updates apply to tracked installs in `plugins.installs`, currently npm and
|
||||
marketplace installs.
|
||||
|
||||
When a stored integrity hash exists and the fetched artifact hash changes,
|
||||
OpenClaw prints a warning and asks for confirmation before proceeding. Use
|
||||
|
||||
@ -16,8 +16,15 @@ OpenClaw can run agents in isolated sandbox runtimes for security. The `sandbox`
|
||||
Today that usually means:
|
||||
|
||||
- Docker sandbox containers
|
||||
- SSH sandbox runtimes when `agents.defaults.sandbox.backend = "ssh"`
|
||||
- OpenShell sandbox runtimes when `agents.defaults.sandbox.backend = "openshell"`
|
||||
|
||||
For `ssh` and OpenShell `remote`, recreate matters more than with Docker:
|
||||
|
||||
- the remote workspace is canonical after the initial seed
|
||||
- `openclaw sandbox recreate` deletes that canonical remote workspace for the selected scope
|
||||
- next use seeds it again from the current local workspace
|
||||
|
||||
## Commands
|
||||
|
||||
### `openclaw sandbox explain`
|
||||
@ -97,6 +104,22 @@ openclaw sandbox recreate --all
|
||||
openclaw sandbox recreate --all
|
||||
```
|
||||
|
||||
### After changing SSH target or SSH auth material
|
||||
|
||||
```bash
|
||||
# Edit config:
|
||||
# - agents.defaults.sandbox.backend
|
||||
# - agents.defaults.sandbox.ssh.target
|
||||
# - agents.defaults.sandbox.ssh.workspaceRoot
|
||||
# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
|
||||
# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData
|
||||
|
||||
openclaw sandbox recreate --all
|
||||
```
|
||||
|
||||
For the core `ssh` backend, recreate deletes the per-scope remote workspace root
|
||||
on the SSH target. The next run seeds it again from the local workspace.
|
||||
|
||||
### After changing OpenShell source, policy, or mode
|
||||
|
||||
```bash
|
||||
@ -150,7 +173,7 @@ Sandbox settings live in `~/.openclaw/openclaw.json` under `agents.defaults.sand
|
||||
"defaults": {
|
||||
"sandbox": {
|
||||
"mode": "all", // off, non-main, all
|
||||
"backend": "docker", // docker, openshell
|
||||
"backend": "docker", // docker, ssh, openshell
|
||||
"scope": "agent", // session, agent, shared
|
||||
"docker": {
|
||||
"image": "openclaw-sandbox:bookworm-slim",
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
summary: "CLI reference for `openclaw setup` (initialize config + workspace)"
|
||||
read_when:
|
||||
- You’re doing first-run setup without the full onboarding wizard
|
||||
- You’re doing first-run setup without the full setup wizard
|
||||
- You want to set the default workspace path
|
||||
title: "setup"
|
||||
---
|
||||
|
||||
@ -20,10 +20,13 @@ For model selection rules, see [/concepts/models](/concepts/models).
|
||||
OpenClaw merges that output into `models.providers` before writing
|
||||
`models.json`.
|
||||
- Provider manifests can declare `providerAuthEnvVars` so generic env-based
|
||||
auth probes do not need to load plugin runtime.
|
||||
auth probes do not need to load plugin runtime. The remaining core env-var
|
||||
map is now just for non-plugin/core providers and a few generic-precedence
|
||||
cases such as Anthropic API-key-first onboarding.
|
||||
- Provider plugins can also own provider runtime behavior via
|
||||
`resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`,
|
||||
`capabilities`, `prepareExtraParams`, `wrapStreamFn`,
|
||||
`capabilities`, `prepareExtraParams`, `wrapStreamFn`, `formatApiKey`,
|
||||
`refreshOAuth`, `buildAuthDoctorHint`,
|
||||
`isCacheTtlEligible`, `buildMissingAuthMessage`,
|
||||
`suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`,
|
||||
`supportsXHighThinking`, `resolveDefaultThinkingLevel`,
|
||||
@ -37,6 +40,10 @@ the generic inference loop.
|
||||
|
||||
Typical split:
|
||||
|
||||
- `auth[].run` / `auth[].runNonInteractive`: provider owns onboarding/login
|
||||
flows for `openclaw onboard`, `openclaw models auth`, and headless setup
|
||||
- `wizard.setup` / `wizard.modelPicker`: provider owns auth-choice labels,
|
||||
legacy aliases, onboarding allowlist hints, and setup entries in onboarding/model pickers
|
||||
- `catalog`: provider appears in `models.providers`
|
||||
- `resolveDynamicModel`: provider accepts model ids not present in the local
|
||||
static catalog yet
|
||||
@ -46,6 +53,12 @@ Typical split:
|
||||
- `capabilities`: provider publishes transcript/tooling/provider-family quirks
|
||||
- `prepareExtraParams`: provider defaults or normalizes per-model request params
|
||||
- `wrapStreamFn`: provider applies request headers/body/model compat wrappers
|
||||
- `formatApiKey`: provider formats stored auth profiles into the runtime
|
||||
`apiKey` string expected by the transport
|
||||
- `refreshOAuth`: provider owns OAuth refresh when the shared `pi-ai`
|
||||
refreshers are not enough
|
||||
- `buildAuthDoctorHint`: provider appends repair guidance when OAuth refresh
|
||||
fails
|
||||
- `isCacheTtlEligible`: provider decides which upstream model ids support prompt-cache TTL
|
||||
- `buildMissingAuthMessage`: provider replaces the generic auth-store error
|
||||
with a provider-specific recovery hint
|
||||
@ -67,19 +80,21 @@ Typical split:
|
||||
|
||||
Current bundled examples:
|
||||
|
||||
- `anthropic`: Claude 4.6 forward-compat fallback, usage endpoint fetching,
|
||||
and cache-TTL/provider-family metadata
|
||||
- `anthropic`: Claude 4.6 forward-compat fallback, auth repair hints, usage
|
||||
endpoint fetching, and cache-TTL/provider-family metadata
|
||||
- `openrouter`: pass-through model ids, request wrappers, provider capability
|
||||
hints, and cache-TTL policy
|
||||
- `github-copilot`: forward-compat model fallback, Claude-thinking transcript
|
||||
hints, runtime token exchange, and usage endpoint fetching
|
||||
- `github-copilot`: onboarding/device login, forward-compat model fallback,
|
||||
Claude-thinking transcript hints, runtime token exchange, and usage endpoint
|
||||
fetching
|
||||
- `openai`: GPT-5.4 forward-compat fallback, direct OpenAI transport
|
||||
normalization, Codex-aware missing-auth hints, Spark suppression, synthetic
|
||||
OpenAI/Codex catalog rows, thinking/live-model policy, and
|
||||
provider-family metadata
|
||||
- `google` and `google-gemini-cli`: Gemini 3.1 forward-compat fallback and
|
||||
modern-model matching; Gemini CLI OAuth also owns usage-token parsing and
|
||||
quota endpoint fetching for usage surfaces
|
||||
modern-model matching; Gemini CLI OAuth also owns auth-profile token
|
||||
formatting, usage-token parsing, and quota endpoint fetching for usage
|
||||
surfaces
|
||||
- `moonshot`: shared transport, plugin-owned thinking payload normalization
|
||||
- `kilocode`: shared transport, plugin-owned request headers, reasoning payload
|
||||
normalization, Gemini transcript hints, and cache-TTL policy
|
||||
@ -87,9 +102,9 @@ Current bundled examples:
|
||||
policy, binary-thinking/live-model policy, and usage auth + quota fetching
|
||||
- `mistral`, `opencode`, and `opencode-go`: plugin-owned capability metadata
|
||||
- `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`,
|
||||
`minimax-portal`, `modelstudio`, `nvidia`, `qianfan`, `qwen-portal`,
|
||||
`synthetic`, `together`, `venice`, `vercel-ai-gateway`, and `volcengine`:
|
||||
plugin-owned catalogs only
|
||||
`modelstudio`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`,
|
||||
`vercel-ai-gateway`, and `volcengine`: plugin-owned catalogs only
|
||||
- `qwen-portal`: plugin-owned catalog, OAuth login, and OAuth refresh
|
||||
- `minimax` and `xiaomi`: plugin-owned catalogs plus usage auth/snapshot logic
|
||||
|
||||
The bundled `openai` plugin now owns both provider ids: `openai` and
|
||||
|
||||
@ -36,7 +36,7 @@ Related:
|
||||
|
||||
## Setup wizard (recommended)
|
||||
|
||||
If you don’t want to hand-edit config, run the onboarding wizard:
|
||||
If you don’t want to hand-edit config, run the setup wizard:
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
|
||||
@ -492,8 +492,8 @@ const needsNonImageSanitize =
|
||||
- Test `resolveEnvApiKey("kilocode")` returns correct env var
|
||||
|
||||
2. **Integration Tests:**
|
||||
- Test onboarding flow with `--auth-choice kilocode-api-key`
|
||||
- Test non-interactive onboarding with `--kilocode-api-key`
|
||||
- Test setup flow with `--auth-choice kilocode-api-key`
|
||||
- Test non-interactive setup with `--kilocode-api-key`
|
||||
- Test model selection with `kilocode/` prefix
|
||||
|
||||
3. **E2E Tests:**
|
||||
|
||||
@ -1018,7 +1018,6 @@
|
||||
"pages": [
|
||||
"tools/browser",
|
||||
"tools/browser-login",
|
||||
"tools/chrome-extension",
|
||||
"tools/browser-linux-troubleshooting"
|
||||
]
|
||||
},
|
||||
@ -1613,7 +1612,6 @@
|
||||
"pages": [
|
||||
"zh-CN/tools/browser",
|
||||
"zh-CN/tools/browser-login",
|
||||
"zh-CN/tools/chrome-extension",
|
||||
"zh-CN/tools/browser-linux-troubleshooting"
|
||||
]
|
||||
},
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
summary: "RPC protocol notes for onboarding wizard and config schema"
|
||||
read_when: "Changing onboarding wizard steps or config schema endpoints"
|
||||
summary: "RPC protocol notes for setup wizard and config schema"
|
||||
read_when: "Changing setup wizard steps or config schema endpoints"
|
||||
title: "Onboarding and Config Protocol"
|
||||
---
|
||||
|
||||
|
||||
@ -49,7 +49,7 @@ openclaw models status
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
If you’d rather not manage env vars yourself, the onboarding wizard can store
|
||||
If you’d rather not manage env vars yourself, the setup wizard can store
|
||||
API keys for daemon use: `openclaw onboard`.
|
||||
|
||||
See [Help](/help) for details on env inheritance (`env.shellEnv`,
|
||||
|
||||
@ -1125,7 +1125,7 @@ Optional sandboxing for the embedded agent. See [Sandboxing](/gateway/sandboxing
|
||||
defaults: {
|
||||
sandbox: {
|
||||
mode: "non-main", // off | non-main | all
|
||||
backend: "docker", // docker | openshell
|
||||
backend: "docker", // docker | ssh | openshell
|
||||
scope: "agent", // session | agent | shared
|
||||
workspaceAccess: "none", // none | ro | rw
|
||||
workspaceRoot: "~/.openclaw/sandboxes",
|
||||
@ -1154,6 +1154,20 @@ Optional sandboxing for the embedded agent. See [Sandboxing](/gateway/sandboxing
|
||||
extraHosts: ["internal.service:10.0.0.5"],
|
||||
binds: ["/home/user/source:/source:rw"],
|
||||
},
|
||||
ssh: {
|
||||
target: "user@gateway-host:22",
|
||||
command: "ssh",
|
||||
workspaceRoot: "/tmp/openclaw-sandboxes",
|
||||
strictHostKeyChecking: true,
|
||||
updateHostKeys: true,
|
||||
identityFile: "~/.ssh/id_ed25519",
|
||||
certificateFile: "~/.ssh/id_ed25519-cert.pub",
|
||||
knownHostsFile: "~/.ssh/known_hosts",
|
||||
// SecretRefs / inline contents also supported:
|
||||
// identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
|
||||
// certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
|
||||
// knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
|
||||
},
|
||||
browser: {
|
||||
enabled: false,
|
||||
image: "openclaw-sandbox-browser:bookworm-slim",
|
||||
@ -1203,11 +1217,36 @@ Optional sandboxing for the embedded agent. See [Sandboxing](/gateway/sandboxing
|
||||
**Backend:**
|
||||
|
||||
- `docker`: local Docker runtime (default)
|
||||
- `ssh`: generic SSH-backed remote runtime
|
||||
- `openshell`: OpenShell runtime
|
||||
|
||||
When `backend: "openshell"` is selected, runtime-specific settings move to
|
||||
`plugins.entries.openshell.config`.
|
||||
|
||||
**SSH backend config:**
|
||||
|
||||
- `target`: SSH target in `user@host[:port]` form
|
||||
- `command`: SSH client command (default: `ssh`)
|
||||
- `workspaceRoot`: absolute remote root used for per-scope workspaces
|
||||
- `identityFile` / `certificateFile` / `knownHostsFile`: existing local files passed to OpenSSH
|
||||
- `identityData` / `certificateData` / `knownHostsData`: inline contents or SecretRefs that OpenClaw materializes into temp files at runtime
|
||||
- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH host-key policy knobs
|
||||
|
||||
**SSH auth precedence:**
|
||||
|
||||
- `identityData` wins over `identityFile`
|
||||
- `certificateData` wins over `certificateFile`
|
||||
- `knownHostsData` wins over `knownHostsFile`
|
||||
- SecretRef-backed `*Data` values are resolved from the active secrets runtime snapshot before the sandbox session starts
|
||||
|
||||
**SSH backend behavior:**
|
||||
|
||||
- seeds the remote workspace once after create or recreate
|
||||
- then keeps the remote SSH workspace canonical
|
||||
- routes `exec`, file tools, and media paths over SSH
|
||||
- does not sync remote changes back to the host automatically
|
||||
- does not support sandbox browser containers
|
||||
|
||||
**Workspace access:**
|
||||
|
||||
- `none`: per-scope sandbox workspace under `~/.openclaw/sandboxes`
|
||||
@ -1252,6 +1291,7 @@ When `backend: "openshell"` is selected, runtime-specific settings move to
|
||||
- `remote`: seed remote once when the sandbox is created, then keep the remote workspace canonical
|
||||
|
||||
In `remote` mode, host-local edits made outside OpenClaw are not synced into the sandbox automatically after the seed step.
|
||||
Transport is SSH into the OpenShell sandbox, but the plugin owns sandbox lifecycle and optional mirror sync.
|
||||
|
||||
**`setupCommand`** runs once after container creation (via `sh -lc`). Needs network egress, writable root, root user.
|
||||
|
||||
@ -2402,13 +2442,13 @@ See [Plugins](/tools/plugin).
|
||||
profiles: {
|
||||
openclaw: { cdpPort: 18800, color: "#FF4500" },
|
||||
work: { cdpPort: 18801, color: "#0066CC" },
|
||||
user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
|
||||
remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
|
||||
},
|
||||
color: "#FF4500",
|
||||
// headless: false,
|
||||
// noSandbox: false,
|
||||
// extraArgs: [],
|
||||
// relayBindHost: "0.0.0.0", // only when the extension relay must be reachable across namespaces (for example WSL2)
|
||||
// executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
|
||||
// attachOnly: false,
|
||||
},
|
||||
@ -2422,11 +2462,11 @@ See [Plugins](/tools/plugin).
|
||||
- `ssrfPolicy.allowPrivateNetwork` remains supported as a legacy alias.
|
||||
- In strict mode, use `ssrfPolicy.hostnameAllowlist` and `ssrfPolicy.allowedHostnames` for explicit exceptions.
|
||||
- Remote profiles are attach-only (start/stop/reset disabled).
|
||||
- `existing-session` profiles are host-only and use Chrome MCP instead of CDP.
|
||||
- Auto-detect order: default browser if Chromium-based → Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- Control service: loopback only (port derived from `gateway.port`, default `18791`).
|
||||
- `extraArgs` appends extra launch flags to local Chromium startup (for example
|
||||
`--disable-gpu`, window sizing, or debug flags).
|
||||
- `relayBindHost` changes where the Chrome extension relay listens. Leave unset for loopback-only access; set an explicit non-loopback bind address such as `0.0.0.0` only when the relay must cross a namespace boundary (for example WSL2) and the host network is already trusted.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -63,6 +63,7 @@ cat ~/.openclaw/openclaw.json
|
||||
- Health check + restart prompt.
|
||||
- Skills status summary (eligible/missing/blocked).
|
||||
- Config normalization for legacy values.
|
||||
- Browser migration checks for legacy Chrome extension configs and Chrome MCP readiness.
|
||||
- OpenCode provider override warnings (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
|
||||
- Legacy cron store migration (`jobId`, `schedule.cron`, top-level delivery/payload fields, payload `provider`, simple `notify: true` webhook fallback jobs).
|
||||
@ -128,6 +129,8 @@ Current migrations:
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
|
||||
→ `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- remove `browser.relayBindHost` (legacy extension relay setting)
|
||||
|
||||
Doctor warnings also include account-default guidance for multi-account channels:
|
||||
|
||||
@ -141,6 +144,33 @@ manually, it overrides the built-in OpenCode catalog from `@mariozechner/pi-ai`.
|
||||
That can force models onto the wrong API or zero out costs. Doctor warns so you
|
||||
can remove the override and restore per-model API routing + costs.
|
||||
|
||||
### 2c) Browser migration and Chrome MCP readiness
|
||||
|
||||
If your browser config still points at the removed Chrome extension path, doctor
|
||||
normalizes it to the current host-local Chrome MCP attach model:
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` becomes `"existing-session"`
|
||||
- `browser.relayBindHost` is removed
|
||||
|
||||
Doctor also audits the host-local Chrome MCP path when you use `defaultProfile:
|
||||
"user"` or a configured `existing-session` profile:
|
||||
|
||||
- checks whether Google Chrome is installed on the same host
|
||||
- checks the detected Chrome version and warns when it is below Chrome 144
|
||||
- reminds you to enable remote debugging in Chrome at
|
||||
`chrome://inspect/#remote-debugging`
|
||||
|
||||
Doctor cannot enable the Chrome-side setting for you. Host-local Chrome MCP
|
||||
still requires:
|
||||
|
||||
- Google Chrome 144+ on the gateway/node host
|
||||
- Chrome running locally
|
||||
- remote debugging enabled in Chrome
|
||||
- approving the first attach consent prompt in Chrome
|
||||
|
||||
This check does **not** apply to Docker, sandbox, remote-browser, or other
|
||||
headless flows. Those continue to use raw CDP.
|
||||
|
||||
### 3) Legacy state migrations (disk layout)
|
||||
|
||||
Doctor can migrate older on-disk layouts into the current structure:
|
||||
|
||||
@ -70,7 +70,7 @@ openclaw --profile rescue onboard
|
||||
# better choose completely different base port, like 19789,
|
||||
# - rest of the onboarding is the same as normal
|
||||
|
||||
# To install the service (if not happened automatically during onboarding)
|
||||
# To install the service (if not happened automatically during setup)
|
||||
openclaw --profile rescue gateway install
|
||||
```
|
||||
|
||||
|
||||
@ -59,10 +59,67 @@ Not sandboxed:
|
||||
`agents.defaults.sandbox.backend` controls **which runtime** provides the sandbox:
|
||||
|
||||
- `"docker"` (default): local Docker-backed sandbox runtime.
|
||||
- `"ssh"`: generic SSH-backed remote sandbox runtime.
|
||||
- `"openshell"`: OpenShell-backed sandbox runtime.
|
||||
|
||||
SSH-specific config lives under `agents.defaults.sandbox.ssh`.
|
||||
OpenShell-specific config lives under `plugins.entries.openshell.config`.
|
||||
|
||||
### SSH backend
|
||||
|
||||
Use `backend: "ssh"` when you want OpenClaw to sandbox `exec`, file tools, and media reads on
|
||||
an arbitrary SSH-accessible machine.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
mode: "all",
|
||||
backend: "ssh",
|
||||
scope: "session",
|
||||
workspaceAccess: "rw",
|
||||
ssh: {
|
||||
target: "user@gateway-host:22",
|
||||
workspaceRoot: "/tmp/openclaw-sandboxes",
|
||||
strictHostKeyChecking: true,
|
||||
updateHostKeys: true,
|
||||
identityFile: "~/.ssh/id_ed25519",
|
||||
certificateFile: "~/.ssh/id_ed25519-cert.pub",
|
||||
knownHostsFile: "~/.ssh/known_hosts",
|
||||
// Or use SecretRefs / inline contents instead of local files:
|
||||
// identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
|
||||
// certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
|
||||
// knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
How it works:
|
||||
|
||||
- OpenClaw creates a per-scope remote root under `sandbox.ssh.workspaceRoot`.
|
||||
- On first use after create or recreate, OpenClaw seeds that remote workspace from the local workspace once.
|
||||
- After that, `exec`, `read`, `write`, `edit`, `apply_patch`, prompt media reads, and inbound media staging run directly against the remote workspace over SSH.
|
||||
- OpenClaw does not sync remote changes back to the local workspace automatically.
|
||||
|
||||
Authentication material:
|
||||
|
||||
- `identityFile`, `certificateFile`, `knownHostsFile`: use existing local files and pass them through OpenSSH config.
|
||||
- `identityData`, `certificateData`, `knownHostsData`: use inline strings or SecretRefs. OpenClaw resolves them through the normal secrets runtime snapshot, writes them to temp files with `0600`, and deletes them when the SSH session ends.
|
||||
- If both `*File` and `*Data` are set for the same item, `*Data` wins for that SSH session.
|
||||
|
||||
This is a **remote-canonical** model. The remote SSH workspace becomes the real sandbox state after the initial seed.
|
||||
|
||||
Important consequences:
|
||||
|
||||
- Host-local edits made outside OpenClaw after the seed step are not visible remotely until you recreate the sandbox.
|
||||
- `openclaw sandbox recreate` deletes the per-scope remote root and seeds again from local on next use.
|
||||
- Browser sandboxing is not supported on the SSH backend.
|
||||
- `sandbox.docker.*` settings do not apply to the SSH backend.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -96,6 +153,15 @@ OpenShell modes:
|
||||
- `mirror` (default): local workspace stays canonical. OpenClaw syncs local files into OpenShell before exec and syncs the remote workspace back after exec.
|
||||
- `remote`: OpenShell workspace is canonical after the sandbox is created. OpenClaw seeds the remote workspace once from the local workspace, then file tools and exec run directly against the remote sandbox without syncing changes back.
|
||||
|
||||
OpenShell reuses the same core SSH transport and remote filesystem bridge as the generic SSH backend.
|
||||
The plugin adds OpenShell-specific lifecycle (`sandbox create/get/delete`, `sandbox ssh-config`) and the optional `mirror` mode.
|
||||
|
||||
Remote transport details:
|
||||
|
||||
- OpenClaw asks OpenShell for sandbox-specific SSH config via `openshell sandbox ssh-config <name>`.
|
||||
- Core writes that SSH config to a temp file, opens the SSH session, and reuses the same remote filesystem bridge used by `backend: "ssh"`.
|
||||
- In `mirror` mode only the lifecycle differs: sync local to remote before exec, then sync back after exec.
|
||||
|
||||
Current OpenShell limitations:
|
||||
|
||||
- sandbox browser is not supported yet
|
||||
@ -136,6 +202,7 @@ Behavior:
|
||||
- After that, `exec`, `read`, `write`, `edit`, and `apply_patch` operate directly against the remote OpenShell workspace.
|
||||
- OpenClaw does **not** sync remote changes back into the local workspace after exec.
|
||||
- Prompt-time media reads still work because file and media tools read through the sandbox bridge instead of assuming a local host path.
|
||||
- Transport is SSH into the OpenShell sandbox returned by `openshell sandbox ssh-config`.
|
||||
|
||||
Important consequences:
|
||||
|
||||
|
||||
@ -41,6 +41,9 @@ Examples of inactive surfaces:
|
||||
- Web search provider-specific keys that are not selected by `tools.web.search.provider`.
|
||||
In auto mode (provider unset), keys are consulted by precedence for provider auto-detection until one resolves.
|
||||
After selection, non-selected provider keys are treated as inactive until selected.
|
||||
- Sandbox SSH auth material (`agents.defaults.sandbox.ssh.identityData`,
|
||||
`certificateData`, `knownHostsData`, plus per-agent overrides) is active only
|
||||
when the effective sandbox backend is `ssh` for the default agent or an enabled agent.
|
||||
- `gateway.remote.token` / `gateway.remote.password` SecretRefs are active if one of these is true:
|
||||
- `gateway.mode=remote`
|
||||
- `gateway.remote.url` is configured
|
||||
@ -67,7 +70,7 @@ active-surface policy, so you can see why a credential was treated as active or
|
||||
|
||||
When onboarding runs in interactive mode and you choose SecretRef storage, OpenClaw runs preflight validation before saving:
|
||||
|
||||
- Env refs: validates env var name and confirms a non-empty value is visible during onboarding.
|
||||
- Env refs: validates env var name and confirms a non-empty value is visible during setup.
|
||||
- Provider refs (`file` or `exec`): validates provider selection, resolves `id`, and checks resolved value type.
|
||||
- Quickstart reuse path: when `gateway.auth.token` is already a SecretRef, onboarding resolves it before probe/dashboard bootstrap (for `env`, `file`, and `exec` refs) using the same fail-fast gate.
|
||||
|
||||
@ -285,6 +288,35 @@ Optional per-id errors:
|
||||
}
|
||||
```
|
||||
|
||||
## Sandbox SSH auth material
|
||||
|
||||
The core `ssh` sandbox backend also supports SecretRefs for SSH auth material:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
mode: "all",
|
||||
backend: "ssh",
|
||||
ssh: {
|
||||
target: "user@gateway-host:22",
|
||||
identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
|
||||
certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
|
||||
knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Runtime behavior:
|
||||
|
||||
- OpenClaw resolves these refs during sandbox activation, not lazily during each SSH call.
|
||||
- Resolved values are written to temp files with restrictive permissions and used in generated SSH config.
|
||||
- If the effective sandbox backend is not `ssh`, these refs stay inactive and do not block startup.
|
||||
|
||||
## Supported credential surface
|
||||
|
||||
Canonical supported and unsupported credentials are listed in:
|
||||
|
||||
@ -738,7 +738,7 @@ In minimal mode, the Gateway still broadcasts enough for device discovery (`role
|
||||
Gateway auth is **required by default**. If no token/password is configured,
|
||||
the Gateway refuses WebSocket connections (fail‑closed).
|
||||
|
||||
The onboarding wizard generates a token by default (even for loopback) so
|
||||
The setup wizard generates a token by default (even for loopback) so
|
||||
local clients must authenticate.
|
||||
|
||||
Set a token so **all** WS clients must authenticate:
|
||||
@ -990,10 +990,9 @@ access those accounts and data. Treat browser profiles as **sensitive state**:
|
||||
- Treat browser downloads as untrusted input; prefer an isolated downloads directory.
|
||||
- Disable browser sync/password managers in the agent profile if possible (reduces blast radius).
|
||||
- For remote gateways, assume “browser control” is equivalent to “operator access” to whatever that profile can reach.
|
||||
- Keep the Gateway and node hosts tailnet-only; avoid exposing relay/control ports to LAN or public Internet.
|
||||
- The Chrome extension relay’s CDP endpoint is auth-gated; only OpenClaw clients can connect.
|
||||
- Keep the Gateway and node hosts tailnet-only; avoid exposing browser control ports to LAN or public Internet.
|
||||
- Disable browser proxy routing when you don’t need it (`gateway.nodes.browser.mode="off"`).
|
||||
- Chrome extension relay mode is **not** “safer”; it can take over your existing Chrome tabs. Assume it can act as you in whatever that tab/profile can reach.
|
||||
- Chrome MCP existing-session mode is **not** “safer”; it can act as you in whatever that host Chrome profile can reach.
|
||||
|
||||
### Browser SSRF policy (trusted-network default)
|
||||
|
||||
|
||||
@ -289,19 +289,18 @@ Look for:
|
||||
|
||||
- Valid browser executable path.
|
||||
- CDP profile reachability.
|
||||
- Extension relay tab attachment (if an extension relay profile is configured).
|
||||
- Local Chrome availability for `existing-session` / `user` profiles.
|
||||
|
||||
Common signatures:
|
||||
|
||||
- `Failed to start Chrome CDP on port` → browser process failed to launch.
|
||||
- `browser.executablePath not found` → configured path is invalid.
|
||||
- `Chrome extension relay is running, but no tab is connected` → extension relay not attached.
|
||||
- `No Chrome tabs found for profile="user"` → the Chrome MCP attach profile has no open local Chrome tabs.
|
||||
- `Browser attachOnly is enabled ... not reachable` → attach-only profile has no reachable target.
|
||||
|
||||
Related:
|
||||
|
||||
- [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
|
||||
- [/tools/chrome-extension](/tools/chrome-extension)
|
||||
- [/tools/browser](/tools/browser)
|
||||
|
||||
## If you upgraded and something suddenly broke
|
||||
|
||||
@ -36,7 +36,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
|
||||
- [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 the onboarding wizard actually do?](#what-does-the-onboarding-wizard-actually-do)
|
||||
- [What does the setup wizard actually do?](#what-does-the-setup-wizard-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)
|
||||
@ -80,7 +80,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
|
||||
- [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 install the Chrome extension for browser takeover?](#how-do-i-install-the-chrome-extension-for-browser-takeover)
|
||||
- [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)
|
||||
@ -317,7 +317,7 @@ Install docs: [Install](/install), [Installer flags](/install/installer), [Updat
|
||||
|
||||
### What's the recommended way to install and set up OpenClaw
|
||||
|
||||
The repo recommends running from source and using the onboarding wizard:
|
||||
The repo recommends running from source and using the setup wizard:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
@ -627,7 +627,7 @@ More detail: [Install](/install) and [Installer flags](/install/installer).
|
||||
|
||||
### How do I install OpenClaw on Linux
|
||||
|
||||
Short answer: follow the Linux guide, then run the onboarding wizard.
|
||||
Short answer: follow the Linux guide, then run the setup wizard.
|
||||
|
||||
- Linux quick path + service install: [Linux](/platforms/linux).
|
||||
- Full walkthrough: [Getting Started](/start/getting-started).
|
||||
@ -685,7 +685,7 @@ openclaw gateway restart
|
||||
|
||||
Docs: [Update](/cli/update), [Updating](/install/updating).
|
||||
|
||||
### What does the onboarding wizard actually do
|
||||
### What does the setup wizard actually do
|
||||
|
||||
`openclaw onboard` is the recommended setup path. In **local mode** it walks you through:
|
||||
|
||||
@ -773,7 +773,7 @@ OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). The wizar
|
||||
|
||||
Yes. OpenClaw fully supports **OpenAI Code (Codex) subscription OAuth**.
|
||||
OpenAI explicitly allows subscription OAuth usage in external tools/workflows
|
||||
like OpenClaw. The onboarding wizard can run the OAuth flow for you.
|
||||
like OpenClaw. The setup wizard can run the OAuth flow for you.
|
||||
|
||||
See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Wizard](/start/wizard).
|
||||
|
||||
@ -844,7 +844,7 @@ without WhatsApp/Telegram.
|
||||
|
||||
`channels.telegram.allowFrom` is **the human sender's Telegram user ID** (numeric). It is not the bot username.
|
||||
|
||||
The onboarding wizard accepts `@username` input and resolves it to a numeric ID, but OpenClaw authorization uses numeric IDs only.
|
||||
The setup wizard accepts `@username` input and resolves it to a numeric ID, but OpenClaw authorization uses numeric IDs only.
|
||||
|
||||
Safer (no third-party bot):
|
||||
|
||||
@ -1214,22 +1214,23 @@ clawhub update --all
|
||||
|
||||
ClawHub installs into `./skills` under your current directory (or falls back to your configured OpenClaw workspace); OpenClaw treats that as `<workspace>/skills` on the next session. For shared skills across agents, place them in `~/.openclaw/skills/<name>/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).
|
||||
|
||||
### How do I install the Chrome extension for browser takeover
|
||||
### How do I use my existing signed-in Chrome with OpenClaw
|
||||
|
||||
Use the built-in installer, then load the unpacked extension in Chrome:
|
||||
Use the built-in `user` browser profile, which attaches through Chrome DevTools MCP:
|
||||
|
||||
```bash
|
||||
openclaw browser extension install
|
||||
openclaw browser extension path
|
||||
openclaw browser --browser-profile user tabs
|
||||
openclaw browser --browser-profile user snapshot
|
||||
```
|
||||
|
||||
Then Chrome → `chrome://extensions` → enable "Developer mode" → "Load unpacked" → pick that folder.
|
||||
If you want a custom name, create an explicit MCP profile:
|
||||
|
||||
Full guide (including remote Gateway + security notes): [Chrome extension](/tools/chrome-extension)
|
||||
```bash
|
||||
openclaw browser create-profile --name chrome-live --driver existing-session
|
||||
openclaw browser --browser-profile chrome-live tabs
|
||||
```
|
||||
|
||||
If the Gateway runs on the same machine as Chrome (default setup), you usually **do not** need anything extra.
|
||||
If the Gateway runs elsewhere, run a node host on the browser machine so the Gateway can proxy browser actions.
|
||||
You still need to click the extension button on the tab you want to control (it doesn't auto-attach).
|
||||
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
|
||||
|
||||
@ -1665,13 +1666,12 @@ 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 and relay control
|
||||
with the Chrome extension + a node host on the laptop.
|
||||
- **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.
|
||||
|
||||
Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Chrome extension](/tools/chrome-extension).
|
||||
Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Browser](/tools/browser).
|
||||
|
||||
### Should I install on a second laptop or just add a node
|
||||
|
||||
@ -1901,7 +1901,7 @@ Non-interactive full reset:
|
||||
openclaw reset --scope full --yes --non-interactive
|
||||
```
|
||||
|
||||
Then re-run onboarding:
|
||||
Then re-run setup:
|
||||
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
@ -1909,7 +1909,7 @@ openclaw onboard --install-daemon
|
||||
|
||||
Notes:
|
||||
|
||||
- The onboarding wizard also offers **Reset** if it sees an existing config. See [Wizard](/start/wizard).
|
||||
- The setup wizard also offers **Reset** if it sees an existing config. See [Wizard](/start/wizard).
|
||||
- If you used profiles (`--profile` / `OPENCLAW_PROFILE`), reset each state dir (defaults are `~/.openclaw-<profile>`).
|
||||
- Dev reset: `openclaw gateway --dev --reset` (dev-only; wipes dev config + credentials + sessions + workspace).
|
||||
|
||||
@ -2039,18 +2039,18 @@ Yes. Use **Multi-Agent Routing** to run multiple isolated agents and route inbou
|
||||
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 the Chrome extension relay
|
||||
on the machine that runs the browser (and keep the Gateway anywhere).
|
||||
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 extension relay (or a node) when needed.
|
||||
- Local browser via Chrome MCP or a node when needed.
|
||||
|
||||
Docs: [Multi-Agent Routing](/concepts/multi-agent), [Slack](/channels/slack),
|
||||
[Browser](/tools/browser), [Chrome extension](/tools/chrome-extension), [Nodes](/nodes).
|
||||
[Browser](/tools/browser), [Nodes](/nodes).
|
||||
|
||||
## Models: defaults, selection, aliases, switching
|
||||
|
||||
|
||||
@ -61,7 +61,7 @@ Think of the suites as “increasing realism” (and increasing flakiness/cost):
|
||||
|
||||
- Command: `pnpm test:e2e`
|
||||
- Config: `vitest.e2e.config.ts`
|
||||
- Files: `src/**/*.e2e.test.ts`
|
||||
- Files: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts`
|
||||
- Runtime defaults:
|
||||
- Uses Vitest `vmForks` for faster file startup.
|
||||
- Uses adaptive workers (CI: 2-4, local: 4-8).
|
||||
@ -77,6 +77,23 @@ Think of the suites as “increasing realism” (and increasing flakiness/cost):
|
||||
- No real keys required
|
||||
- More moving parts than unit tests (can be slower)
|
||||
|
||||
### E2E: OpenShell backend smoke
|
||||
|
||||
- Command: `pnpm test:e2e:openshell`
|
||||
- File: `test/openshell-sandbox.e2e.test.ts`
|
||||
- Scope:
|
||||
- Starts an isolated OpenShell gateway on the host via Docker
|
||||
- Creates a sandbox from a temporary local Dockerfile
|
||||
- Exercises OpenClaw's OpenShell backend over real `sandbox ssh-config` + SSH exec
|
||||
- Verifies remote-canonical filesystem behavior through the sandbox fs bridge
|
||||
- Expectations:
|
||||
- Opt-in only; not part of the default `pnpm test:e2e` run
|
||||
- Requires a local `openshell` CLI plus a working Docker daemon
|
||||
- Uses isolated `HOME` / `XDG_CONFIG_HOME`, then destroys the test gateway and sandbox
|
||||
- Useful overrides:
|
||||
- `OPENCLAW_E2E_OPENSHELL=1` to enable the test when running the broader e2e suite manually
|
||||
- `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` to point at a non-default CLI binary or wrapper script
|
||||
|
||||
### Live (real providers + real models)
|
||||
|
||||
- Command: `pnpm test:live`
|
||||
@ -345,7 +362,7 @@ If you want to rely on env keys (e.g. exported in your `~/.profile`), run local
|
||||
|
||||
## Docker runners (optional “works in Linux” checks)
|
||||
|
||||
These run `pnpm test:live` inside the repo Docker image, mounting your local config dir and workspace (and sourcing `~/.profile` if mounted):
|
||||
These run `pnpm test:live` inside the repo Docker image, mounting your local config dir and workspace (and sourcing `~/.profile` if mounted). They also bind-mount CLI auth homes like `~/.codex`, `~/.claude`, `~/.qwen`, and `~/.minimax` when present so external-CLI OAuth stays available in-container:
|
||||
|
||||
- Direct models: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`)
|
||||
- Gateway + dev agent: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`)
|
||||
@ -367,6 +384,7 @@ Useful env vars:
|
||||
- `OPENCLAW_CONFIG_DIR=...` (default: `~/.openclaw`) mounted to `/home/node/.openclaw`
|
||||
- `OPENCLAW_WORKSPACE_DIR=...` (default: `~/.openclaw/workspace`) mounted to `/home/node/.openclaw/workspace`
|
||||
- `OPENCLAW_PROFILE_FILE=...` (default: `~/.profile`) mounted to `/home/node/.profile` and sourced before running tests
|
||||
- External CLI auth dirs under `$HOME` (`.codex`, `.claude`, `.qwen`, `.minimax`) are mounted read-only to the matching `/home/node/...` paths when present
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` to narrow the run
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` to ensure creds come from the profile store (not env)
|
||||
|
||||
|
||||
@ -278,13 +278,13 @@ flowchart TD
|
||||
Good output looks like:
|
||||
|
||||
- Browser status shows `running: true` and a chosen browser/profile.
|
||||
- `openclaw` profile starts or `chrome` relay has an attached tab.
|
||||
- `openclaw` starts, or `user` can see local Chrome tabs.
|
||||
|
||||
Common log signatures:
|
||||
|
||||
- `Failed to start Chrome CDP on port` → local browser launch failed.
|
||||
- `browser.executablePath not found` → configured binary path is wrong.
|
||||
- `Chrome extension relay is running, but no tab is connected` → extension not attached.
|
||||
- `No Chrome tabs found for profile="user"` → the Chrome MCP attach profile has no open local Chrome tabs.
|
||||
- `Browser attachOnly is enabled ... not reachable` → attach-only profile has no live CDP target.
|
||||
|
||||
Deep pages:
|
||||
@ -292,7 +292,6 @@ flowchart TD
|
||||
- [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails)
|
||||
- [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
|
||||
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
|
||||
- [/tools/chrome-extension](/tools/chrome-extension)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -51,7 +51,7 @@ From repo root:
|
||||
This script:
|
||||
|
||||
- builds the gateway image locally (or pulls a remote image if `OPENCLAW_IMAGE` is set)
|
||||
- runs the onboarding wizard
|
||||
- runs the setup wizard
|
||||
- prints optional provider setup hints
|
||||
- starts the gateway via Docker Compose
|
||||
- generates a gateway token and writes it to `.env`
|
||||
@ -713,6 +713,7 @@ an optional noVNC observer (headful via Xvfb).
|
||||
|
||||
Notes:
|
||||
|
||||
- Docker and other headless/container browser flows stay on raw CDP. Chrome MCP `existing-session` is for host-local Chrome, not container takeover.
|
||||
- Headful (Xvfb) reduces bot blocking vs headless.
|
||||
- Headless can still be used by setting `agents.defaults.sandbox.browser.headless=true`.
|
||||
- No full desktop environment (GNOME) is needed; Xvfb provides the display.
|
||||
|
||||
@ -33,7 +33,7 @@ For VPS/cloud hosts, avoid third-party "1-click" marketplace images when possibl
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Installer script" icon="rocket" defaultOpen>
|
||||
Downloads the CLI, installs it globally via npm, and launches the onboarding wizard.
|
||||
Downloads the CLI, installs it globally via npm, and launches the setup wizard.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="macOS / Linux / WSL2">
|
||||
|
||||
@ -22,7 +22,7 @@ curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
|
||||
Notes:
|
||||
|
||||
- Add `--no-onboard` if you don’t want the onboarding wizard to run again.
|
||||
- Add `--no-onboard` if you don’t want the setup wizard to run again.
|
||||
- For **source installs**, use:
|
||||
|
||||
```bash
|
||||
|
||||
@ -321,7 +321,7 @@ Since the Pi is just the Gateway (models run in the cloud), use API-based models
|
||||
|
||||
## Auto-Start on Boot
|
||||
|
||||
The onboarding wizard sets this up, but to verify:
|
||||
The setup wizard sets this up, but to verify:
|
||||
|
||||
```bash
|
||||
# Check service is enabled
|
||||
|
||||
@ -259,12 +259,19 @@ openclaw plugins install ./my-codex-bundle
|
||||
openclaw plugins install ./my-claude-bundle
|
||||
openclaw plugins install ./my-cursor-bundle
|
||||
openclaw plugins install ./my-bundle.tgz
|
||||
openclaw plugins marketplace list <marketplace-name>
|
||||
openclaw plugins install <plugin-name>@<marketplace-name>
|
||||
openclaw plugins info my-bundle
|
||||
```
|
||||
|
||||
If the directory is a native OpenClaw plugin/package, the native install path
|
||||
still wins.
|
||||
|
||||
For Claude marketplace names, OpenClaw reads the local Claude known-marketplace
|
||||
registry at `~/.claude/plugins/known_marketplaces.json`. Marketplace entries
|
||||
can resolve to bundle-compatible directories/archives or to native plugin
|
||||
sources; after resolution, the normal install rules still apply.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bundle is detected but capabilities do not run
|
||||
|
||||
@ -59,12 +59,49 @@ Optional keys:
|
||||
- `providerAuthEnvVars` (object): auth env vars keyed by provider id. Use this
|
||||
when OpenClaw should resolve provider credentials from env without loading
|
||||
plugin runtime first.
|
||||
- `providerAuthChoices` (array): cheap onboarding/auth-choice metadata keyed by
|
||||
provider + auth method. Use this when OpenClaw should show a provider in
|
||||
auth-choice pickers, preferred-provider resolution, and CLI help without
|
||||
loading plugin runtime first.
|
||||
- `skills` (array): skill directories to load (relative to the plugin root).
|
||||
- `name` (string): display name for the plugin.
|
||||
- `description` (string): short plugin summary.
|
||||
- `uiHints` (object): config field labels/placeholders/sensitive flags for UI rendering.
|
||||
- `version` (string): plugin version (informational).
|
||||
|
||||
### `providerAuthChoices` shape
|
||||
|
||||
Each entry can declare:
|
||||
|
||||
- `provider`: provider id
|
||||
- `method`: auth method id
|
||||
- `choiceId`: stable onboarding/auth-choice id
|
||||
- `choiceLabel` / `choiceHint`: picker label + short hint
|
||||
- `groupId` / `groupLabel` / `groupHint`: grouped onboarding bucket metadata
|
||||
- `optionKey` / `cliFlag` / `cliOption` / `cliDescription`: optional one-flag
|
||||
CLI wiring for simple auth flows such as API keys
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"providerAuthChoices": [
|
||||
{
|
||||
"provider": "openrouter",
|
||||
"method": "api-key",
|
||||
"choiceId": "openrouter-api-key",
|
||||
"choiceLabel": "OpenRouter API key",
|
||||
"groupId": "openrouter",
|
||||
"groupLabel": "OpenRouter",
|
||||
"optionKey": "openrouterApiKey",
|
||||
"cliFlag": "--openrouter-api-key",
|
||||
"cliOption": "--openrouter-api-key <key>",
|
||||
"cliDescription": "OpenRouter API key"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## JSON Schema requirements
|
||||
|
||||
- **Every plugin must ship a JSON Schema**, even if it accepts no config.
|
||||
@ -90,6 +127,9 @@ Optional keys:
|
||||
- `providerAuthEnvVars` is the cheap metadata path for auth probes, env-marker
|
||||
validation, and similar provider-auth surfaces that should not boot plugin
|
||||
runtime just to inspect env names.
|
||||
- `providerAuthChoices` is the cheap metadata path for auth-choice pickers,
|
||||
`--auth-choice` resolution, preferred-provider mapping, and simple onboarding
|
||||
CLI flag registration before provider runtime loads.
|
||||
- Exclusive plugin kinds are selected through `plugins.slots.*`.
|
||||
- `kind: "memory"` is selected by `plugins.slots.memory`.
|
||||
- `kind: "context-engine"` is selected by `plugins.slots.contextEngine`
|
||||
|
||||
@ -213,7 +213,7 @@ openclaw models auth paste-token --provider anthropic
|
||||
### CLI setup (setup-token)
|
||||
|
||||
```bash
|
||||
# Paste a setup-token during onboarding
|
||||
# Paste a setup-token during setup
|
||||
openclaw onboard --auth-choice setup-token
|
||||
```
|
||||
|
||||
|
||||
@ -64,7 +64,7 @@ GET https://router.huggingface.co/v1/models
|
||||
|
||||
(Optional: send `Authorization: Bearer $HUGGINGFACE_HUB_TOKEN` or `$HF_TOKEN` for the full list; some endpoints return a subset without auth.) The response is OpenAI-style `{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }`.
|
||||
|
||||
When you configure a Hugging Face API key (via onboarding, `HUGGINGFACE_HUB_TOKEN`, or `HF_TOKEN`), OpenClaw uses this GET to discover available chat-completion models. During **interactive onboarding**, after you enter your token you see a **Default Hugging Face model** dropdown populated from that list (or the built-in catalog if the request fails). At runtime (e.g. Gateway startup), when a key is present, OpenClaw again calls **GET** `https://router.huggingface.co/v1/models` to refresh the catalog. The list is merged with a built-in catalog (for metadata like context window and cost). If the request fails or no key is set, only the built-in catalog is used.
|
||||
When you configure a Hugging Face API key (via onboarding, `HUGGINGFACE_HUB_TOKEN`, or `HF_TOKEN`), OpenClaw uses this GET to discover available chat-completion models. During **interactive setup**, after you enter your token you see a **Default Hugging Face model** dropdown populated from that list (or the built-in catalog if the request fails). At runtime (e.g. Gateway startup), when a key is present, OpenClaw again calls **GET** `https://router.huggingface.co/v1/models` to refresh the catalog. The list is merged with a built-in catalog (for metadata like context window and cost). If the request fails or no key is set, only the built-in catalog is used.
|
||||
|
||||
## Model names and editable options
|
||||
|
||||
|
||||
@ -18,7 +18,7 @@ Ollama is a local LLM runtime that makes it easy to run open-source models on yo
|
||||
|
||||
### Onboarding wizard (recommended)
|
||||
|
||||
The fastest way to set up Ollama is through the onboarding wizard:
|
||||
The fastest way to set up Ollama is through the setup wizard:
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
@ -231,7 +231,7 @@ Once configured, all your Ollama models are available:
|
||||
|
||||
Cloud models let you run cloud-hosted models (for example `kimi-k2.5:cloud`, `minimax-m2.5:cloud`, `glm-5:cloud`) alongside your local models.
|
||||
|
||||
To use cloud models, select **Cloud + Local** mode during onboarding. The wizard checks whether you are signed in and opens a browser sign-in flow when needed. If authentication cannot be verified, the wizard falls back to local model defaults.
|
||||
To use cloud models, select **Cloud + Local** mode during setup. The wizard checks whether you are signed in and opens a browser sign-in flow when needed. If authentication cannot be verified, the wizard falls back to local model defaults.
|
||||
|
||||
You can also sign in directly at [ollama.com/signin](https://ollama.com/signin).
|
||||
|
||||
|
||||
@ -59,6 +59,6 @@ openclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
|
||||
## Notes
|
||||
|
||||
- `OPENCODE_ZEN_API_KEY` is also supported.
|
||||
- Entering one OpenCode key during onboarding stores credentials for both runtime providers.
|
||||
- Entering one OpenCode key during setup stores credentials for both runtime providers.
|
||||
- You sign in to OpenCode, add billing details, and copy your API key.
|
||||
- Billing and catalog availability are managed from the OpenCode dashboard.
|
||||
|
||||
@ -87,11 +87,11 @@ Risk:
|
||||
|
||||
- Low
|
||||
|
||||
## 3. Onboarding prompt and config-patch steps
|
||||
## 3. Setup prompt and config-patch steps
|
||||
|
||||
Large surface area.
|
||||
|
||||
Many onboarding files repeat:
|
||||
Many setup files repeat:
|
||||
|
||||
- resolve account id
|
||||
- prompt allowlist entries
|
||||
@ -102,18 +102,18 @@ Many onboarding files repeat:
|
||||
|
||||
Strong examples:
|
||||
|
||||
- `extensions/bluebubbles/src/onboarding.ts`
|
||||
- `extensions/googlechat/src/onboarding.ts`
|
||||
- `extensions/msteams/src/onboarding.ts`
|
||||
- `extensions/zalo/src/onboarding.ts`
|
||||
- `extensions/zalouser/src/onboarding.ts`
|
||||
- `extensions/nextcloud-talk/src/onboarding.ts`
|
||||
- `extensions/matrix/src/onboarding.ts`
|
||||
- `extensions/irc/src/onboarding.ts`
|
||||
- `extensions/bluebubbles/src/setup-surface.ts`
|
||||
- `extensions/googlechat/src/setup-surface.ts`
|
||||
- `extensions/msteams/src/setup-surface.ts`
|
||||
- `extensions/zalo/src/setup-surface.ts`
|
||||
- `extensions/zalouser/src/setup-surface.ts`
|
||||
- `extensions/nextcloud-talk/src/setup-surface.ts`
|
||||
- `extensions/matrix/src/setup-surface.ts`
|
||||
- `extensions/irc/src/setup-surface.ts`
|
||||
|
||||
Existing helper seam:
|
||||
|
||||
- `src/channels/plugins/onboarding/helpers.ts`
|
||||
- `src/channels/plugins/setup-wizard-helpers.ts`
|
||||
|
||||
Likely extraction shape:
|
||||
|
||||
|
||||
@ -212,3 +212,27 @@ Notes:
|
||||
- External plugins can be developed and updated without core source access.
|
||||
|
||||
Related docs: [Plugins](/tools/plugin), [Channels](/channels/index), [Configuration](/gateway/configuration).
|
||||
|
||||
## Implemented channel-owned seams
|
||||
|
||||
Recent refactor work widened the channel plugin contract so core can stop owning
|
||||
channel-specific UX and routing behavior:
|
||||
|
||||
- `messaging.buildCrossContextComponents`: channel-owned cross-context UI markers
|
||||
(for example Discord components v2 containers)
|
||||
- `messaging.enableInteractiveReplies`: channel-owned reply normalization toggles
|
||||
(for example Slack interactive replies)
|
||||
- `messaging.resolveOutboundSessionRoute`: channel-owned outbound session routing
|
||||
- `status.formatCapabilitiesProbe` / `status.buildCapabilitiesDiagnostics`: channel-owned
|
||||
`/channels capabilities` probe display and extra audits/scopes
|
||||
- `threading.resolveAutoThreadId`: channel-owned same-conversation auto-threading
|
||||
- `threading.resolveReplyTransport`: channel-owned reply-vs-thread delivery mapping
|
||||
- `actions.requiresTrustedRequesterSender`: channel-owned privileged action trust gates
|
||||
- `execApprovals.*`: channel-owned exec approval surface state, forwarding suppression,
|
||||
pending payload UX, and pre-delivery hooks
|
||||
- `lifecycle.onAccountConfigChanged` / `lifecycle.onAccountRemoved`: channel-owned cleanup on
|
||||
config mutation/removal
|
||||
- `allowlist.supportsScope`: channel-owned allowlist scope advertisement
|
||||
|
||||
These hooks should be preferred over new `channel === "discord"` / `telegram`
|
||||
branches in shared core flows.
|
||||
|
||||
@ -1,17 +1,17 @@
|
||||
---
|
||||
summary: "Full reference for the CLI onboarding wizard: every step, flag, and config field"
|
||||
summary: "Full reference for the CLI setup wizard: every step, flag, and config field"
|
||||
read_when:
|
||||
- Looking up a specific wizard step or flag
|
||||
- Automating onboarding with non-interactive mode
|
||||
- Debugging wizard behavior
|
||||
title: "Onboarding Wizard Reference"
|
||||
title: "Setup Wizard Reference"
|
||||
sidebarTitle: "Wizard Reference"
|
||||
---
|
||||
|
||||
# Onboarding Wizard Reference
|
||||
# Setup Wizard Reference
|
||||
|
||||
This is the full reference for the `openclaw onboard` CLI wizard.
|
||||
For a high-level overview, see [Onboarding Wizard](/start/wizard).
|
||||
For a high-level overview, see [Setup Wizard](/start/wizard).
|
||||
|
||||
## Flow details (local mode)
|
||||
|
||||
@ -73,12 +73,12 @@ For a high-level overview, see [Onboarding Wizard](/start/wizard).
|
||||
<Step title="Gateway">
|
||||
- Port, bind, auth mode, tailscale exposure.
|
||||
- Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate.
|
||||
- In token mode, interactive onboarding offers:
|
||||
- In token mode, interactive setup offers:
|
||||
- **Generate/store plaintext token** (default)
|
||||
- **Use SecretRef** (opt-in)
|
||||
- Quickstart reuses existing `gateway.auth.token` SecretRefs across `env`, `file`, and `exec` providers for onboarding probe/dashboard bootstrap.
|
||||
- If that SecretRef is configured but cannot be resolved, onboarding fails early with a clear fix message instead of silently degrading runtime auth.
|
||||
- In password mode, interactive onboarding also supports plaintext or SecretRef storage.
|
||||
- In password mode, interactive setup also supports plaintext or SecretRef storage.
|
||||
- Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
|
||||
- Requires a non-empty env var in the onboarding process environment.
|
||||
- Cannot be combined with `--gateway-token`.
|
||||
@ -208,7 +208,7 @@ Typical fields in `~/.openclaw/openclaw.json`:
|
||||
- `agents.defaults.model` / `models.providers` (if Minimax chosen)
|
||||
- `tools.profile` (local onboarding defaults to `"coding"` when unset; existing explicit values are preserved)
|
||||
- `gateway.*` (mode, bind, auth, tailscale)
|
||||
- `session.dmScope` (behavior details: [CLI Onboarding Reference](/start/wizard-cli-reference#outputs-and-internals))
|
||||
- `session.dmScope` (behavior details: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals))
|
||||
- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
|
||||
- Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).
|
||||
- `skills.install.nodeManager`
|
||||
@ -223,12 +223,12 @@ Typical fields in `~/.openclaw/openclaw.json`:
|
||||
WhatsApp credentials go under `~/.openclaw/credentials/whatsapp/<accountId>/`.
|
||||
Sessions are stored under `~/.openclaw/agents/<agentId>/sessions/`.
|
||||
|
||||
Some channels are delivered as plugins. When you pick one during onboarding, the wizard
|
||||
Some channels are delivered as plugins. When you pick one during setup, the wizard
|
||||
will prompt to install it (npm or a local path) before it can be configured.
|
||||
|
||||
## Related docs
|
||||
|
||||
- Wizard overview: [Onboarding Wizard](/start/wizard)
|
||||
- Wizard overview: [Setup Wizard](/start/wizard)
|
||||
- macOS app onboarding: [Onboarding](/start/onboarding)
|
||||
- Config reference: [Gateway configuration](/gateway/configuration)
|
||||
- Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Google Chat](/channels/googlechat), [Signal](/channels/signal), [BlueBubbles](/channels/bluebubbles) (iMessage), [iMessage](/channels/imessage) (legacy)
|
||||
|
||||
@ -52,13 +52,13 @@ Check your Node version with `node --version` if you are unsure.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
<Step title="Run the onboarding wizard">
|
||||
<Step title="Run the setup wizard">
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
The wizard configures auth, gateway settings, and optional channels.
|
||||
See [Onboarding Wizard](/start/wizard) for details.
|
||||
See [Setup Wizard](/start/wizard) for details.
|
||||
|
||||
</Step>
|
||||
<Step title="Check the Gateway">
|
||||
@ -114,7 +114,7 @@ Full environment variable reference: [Environment vars](/help/environment).
|
||||
## Go deeper
|
||||
|
||||
<Columns>
|
||||
<Card title="Onboarding Wizard (details)" href="/start/wizard">
|
||||
<Card title="Setup Wizard (details)" href="/start/wizard">
|
||||
Full CLI wizard reference and advanced options.
|
||||
</Card>
|
||||
<Card title="macOS app onboarding" href="/start/onboarding">
|
||||
|
||||
@ -17,7 +17,7 @@ and how you prefer to configure providers.
|
||||
- **CLI wizard** for macOS, Linux, and Windows (via WSL2).
|
||||
- **macOS app** for a guided first run on Apple silicon or Intel Macs.
|
||||
|
||||
## CLI onboarding wizard
|
||||
## CLI setup wizard
|
||||
|
||||
Run the wizard in a terminal:
|
||||
|
||||
@ -28,7 +28,7 @@ openclaw onboard
|
||||
Use the CLI wizard when you want full control of the Gateway, workspace,
|
||||
channels, and skills. Docs:
|
||||
|
||||
- [Onboarding Wizard (CLI)](/start/wizard)
|
||||
- [Setup Wizard (CLI)](/start/wizard)
|
||||
- [`openclaw onboard` command](/cli/onboard)
|
||||
|
||||
## macOS app onboarding
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
summary: "First-run onboarding flow for OpenClaw (macOS app)"
|
||||
summary: "First-run setup flow for OpenClaw (macOS app)"
|
||||
read_when:
|
||||
- Designing the macOS onboarding assistant
|
||||
- Implementing auth or identity setup
|
||||
@ -9,7 +9,7 @@ sidebarTitle: "Onboarding: macOS App"
|
||||
|
||||
# Onboarding (macOS App)
|
||||
|
||||
This doc describes the **current** first‑run onboarding flow. The goal is a
|
||||
This doc describes the **current** first‑run setup flow. The goal is a
|
||||
smooth “day 0” experience: pick where the Gateway runs, connect auth, run the
|
||||
wizard, and let the agent bootstrap itself.
|
||||
For a general overview of onboarding paths, see [Onboarding Overview](/start/onboarding-overview).
|
||||
|
||||
@ -33,7 +33,7 @@ openclaw onboard --non-interactive \
|
||||
Add `--json` for a machine-readable summary.
|
||||
|
||||
Use `--secret-input-mode ref` to store env-backed refs in auth profiles instead of plaintext values.
|
||||
Interactive selection between env refs and configured provider refs (`file` or `exec`) is available in the onboarding wizard flow.
|
||||
Interactive selection between env refs and configured provider refs (`file` or `exec`) is available in the setup wizard flow.
|
||||
|
||||
In non-interactive `ref` mode, provider env vars must be set in the process environment.
|
||||
Passing inline key flags without the matching env var now fails fast.
|
||||
@ -210,6 +210,6 @@ Notes:
|
||||
|
||||
## Related docs
|
||||
|
||||
- Onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
|
||||
- Full reference: [CLI Onboarding Reference](/start/wizard-cli-reference)
|
||||
- Onboarding hub: [Setup Wizard (CLI)](/start/wizard)
|
||||
- Full reference: [CLI Setup Reference](/start/wizard-cli-reference)
|
||||
- Command reference: [`openclaw onboard`](/cli/onboard)
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
---
|
||||
summary: "Complete reference for CLI onboarding flow, auth/model setup, outputs, and internals"
|
||||
summary: "Complete reference for CLI setup flow, auth/model setup, outputs, and internals"
|
||||
read_when:
|
||||
- You need detailed behavior for openclaw onboard
|
||||
- You are debugging onboarding results or integrating onboarding clients
|
||||
title: "CLI Onboarding Reference"
|
||||
title: "CLI Setup Reference"
|
||||
sidebarTitle: "CLI reference"
|
||||
---
|
||||
|
||||
# CLI Onboarding Reference
|
||||
# CLI Setup Reference
|
||||
|
||||
This page is the full reference for `openclaw onboard`.
|
||||
For the short guide, see [Onboarding Wizard (CLI)](/start/wizard).
|
||||
For the short guide, see [Setup Wizard (CLI)](/start/wizard).
|
||||
|
||||
## What the wizard does
|
||||
|
||||
@ -51,10 +51,10 @@ It does not install or modify anything on the remote host.
|
||||
<Step title="Gateway">
|
||||
- Prompts for port, bind, auth mode, and tailscale exposure.
|
||||
- Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
|
||||
- In token mode, interactive onboarding offers:
|
||||
- In token mode, interactive setup offers:
|
||||
- **Generate/store plaintext token** (default)
|
||||
- **Use SecretRef** (opt-in)
|
||||
- In password mode, interactive onboarding also supports plaintext or SecretRef storage.
|
||||
- In password mode, interactive setup also supports plaintext or SecretRef storage.
|
||||
- Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
|
||||
- Requires a non-empty env var in the onboarding process environment.
|
||||
- Cannot be combined with `--gateway-token`.
|
||||
@ -222,7 +222,7 @@ Credential storage mode:
|
||||
|
||||
- Default onboarding behavior persists API keys as plaintext values in auth profiles.
|
||||
- `--secret-input-mode ref` enables reference mode instead of plaintext key storage.
|
||||
In interactive onboarding, you can choose either:
|
||||
In interactive setup, you can choose either:
|
||||
- environment variable ref (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`)
|
||||
- configured provider ref (`file` or `exec`) with provider alias + id
|
||||
- Interactive reference mode runs a fast preflight validation before saving.
|
||||
@ -234,7 +234,7 @@ Credential storage mode:
|
||||
- Inline key flags (for example `--openai-api-key`) require that env var to be set; otherwise onboarding fails fast.
|
||||
- For custom providers, non-interactive `ref` mode stores `models.providers.<id>.apiKey` as `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`.
|
||||
- In that custom-provider case, `--custom-api-key` requires `CUSTOM_API_KEY` to be set; otherwise onboarding fails fast.
|
||||
- Gateway auth credentials support plaintext and SecretRef choices in interactive onboarding:
|
||||
- Gateway auth credentials support plaintext and SecretRef choices in interactive setup:
|
||||
- Token mode: **Generate/store plaintext token** (default) or **Use SecretRef**.
|
||||
- Password mode: plaintext or SecretRef.
|
||||
- Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
|
||||
@ -270,7 +270,7 @@ WhatsApp credentials go under `~/.openclaw/credentials/whatsapp/<accountId>/`.
|
||||
Sessions are stored under `~/.openclaw/agents/<agentId>/sessions/`.
|
||||
|
||||
<Note>
|
||||
Some channels are delivered as plugins. When selected during onboarding, the wizard
|
||||
Some channels are delivered as plugins. When selected during setup, the wizard
|
||||
prompts to install the plugin (npm or local path) before channel configuration.
|
||||
</Note>
|
||||
|
||||
@ -294,6 +294,6 @@ Signal setup behavior:
|
||||
|
||||
## Related docs
|
||||
|
||||
- Onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
|
||||
- Onboarding hub: [Setup Wizard (CLI)](/start/wizard)
|
||||
- Automation and scripts: [CLI Automation](/start/wizard-cli-automation)
|
||||
- Command reference: [`openclaw onboard`](/cli/onboard)
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
summary: "CLI onboarding wizard: guided setup for gateway, workspace, channels, and skills"
|
||||
summary: "CLI setup wizard: guided setup for gateway, workspace, channels, and skills"
|
||||
read_when:
|
||||
- Running or configuring the onboarding wizard
|
||||
- Running or configuring the setup wizard
|
||||
- Setting up a new machine
|
||||
title: "Onboarding Wizard (CLI)"
|
||||
title: "Setup Wizard (CLI)"
|
||||
sidebarTitle: "Onboarding: CLI"
|
||||
---
|
||||
|
||||
# Onboarding Wizard (CLI)
|
||||
# Setup Wizard (CLI)
|
||||
|
||||
The onboarding wizard is the **recommended** way to set up OpenClaw on macOS,
|
||||
The setup wizard is the **recommended** way to set up OpenClaw on macOS,
|
||||
Linux, or Windows (via WSL2; strongly recommended).
|
||||
It configures a local Gateway or a remote Gateway connection, plus channels, skills,
|
||||
and workspace defaults in one guided flow.
|
||||
@ -35,7 +35,7 @@ openclaw agents add <name>
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
The onboarding wizard includes a web search step where you can pick a provider
|
||||
The setup wizard includes a web search step where you can pick a provider
|
||||
(Perplexity, Brave, Gemini, Grok, or Kimi) and paste your API key so the agent
|
||||
can use `web_search`. You can also configure this later with
|
||||
`openclaw configure --section web`. Docs: [Web tools](/tools/web).
|
||||
@ -52,7 +52,7 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
|
||||
- Gateway port **18789**
|
||||
- Gateway auth **Token** (auto‑generated, even on loopback)
|
||||
- Tool policy default for new local setups: `tools.profile: "coding"` (existing explicit profile is preserved)
|
||||
- DM isolation default: local onboarding writes `session.dmScope: "per-channel-peer"` when unset. Details: [CLI Onboarding Reference](/start/wizard-cli-reference#outputs-and-internals)
|
||||
- DM isolation default: local onboarding writes `session.dmScope: "per-channel-peer"` when unset. Details: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals)
|
||||
- Tailscale exposure **Off**
|
||||
- Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)
|
||||
</Tab>
|
||||
@ -112,7 +112,7 @@ Notes:
|
||||
## Full reference
|
||||
|
||||
For detailed step-by-step breakdowns and config outputs, see
|
||||
[CLI Onboarding Reference](/start/wizard-cli-reference).
|
||||
[CLI Setup Reference](/start/wizard-cli-reference).
|
||||
For non-interactive examples, see [CLI Automation](/start/wizard-cli-automation).
|
||||
For the deeper technical reference, including RPC details, see
|
||||
[Wizard Reference](/reference/wizard).
|
||||
|
||||
@ -121,19 +121,18 @@ curl -s http://127.0.0.1:18791/tabs
|
||||
| `browser.attachOnly` | Don't launch browser, only attach to existing | `false` |
|
||||
| `browser.cdpPort` | Chrome DevTools Protocol port | `18800` |
|
||||
|
||||
### Problem: "Chrome extension relay is running, but no tab is connected"
|
||||
### Problem: "No Chrome tabs found for profile=\"user\""
|
||||
|
||||
You're using an extension relay profile. It expects the OpenClaw
|
||||
browser extension to be attached to a live tab.
|
||||
You're using an `existing-session` / Chrome MCP profile. OpenClaw can see local Chrome,
|
||||
but there are no open tabs available to attach to.
|
||||
|
||||
Fix options:
|
||||
|
||||
1. **Use the managed browser:** `openclaw browser start --browser-profile openclaw`
|
||||
(or set `browser.defaultProfile: "openclaw"`).
|
||||
2. **Use the extension relay:** install the extension, open a tab, and click the
|
||||
OpenClaw extension icon to attach it.
|
||||
2. **Use Chrome MCP:** make sure local Chrome is running with at least one open tab, then retry with `--browser-profile user`.
|
||||
|
||||
Notes:
|
||||
|
||||
- The `chrome-relay` profile uses your **system default Chromium browser** when possible.
|
||||
- `user` is host-only. For Linux servers, containers, or remote hosts, prefer CDP profiles.
|
||||
- Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl`; only set those for remote CDP.
|
||||
|
||||
@ -24,7 +24,6 @@ For agent browser tool calls:
|
||||
|
||||
- Default choice: the agent should use its isolated `openclaw` browser.
|
||||
- Use `profile="user"` only when existing logged-in sessions matter and the user is at the computer to click/approve any attach prompt.
|
||||
- Use `profile="chrome-relay"` only for the Chrome extension / toolbar-button attach flow.
|
||||
- If you have multiple user-browser profiles, specify the profile explicitly instead of guessing.
|
||||
|
||||
Two easy ways to access it:
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
---
|
||||
summary: "Troubleshoot WSL2 Gateway + Windows Chrome remote CDP and extension-relay setups in layers"
|
||||
summary: "Troubleshoot WSL2 Gateway + Windows Chrome remote CDP in layers"
|
||||
read_when:
|
||||
- Running OpenClaw Gateway in WSL2 while Chrome lives on Windows
|
||||
- Seeing overlapping browser/control-ui errors across WSL2 and Windows
|
||||
- Deciding between raw remote CDP and the Chrome extension relay in split-host setups
|
||||
- Deciding between host-local Chrome MCP and raw remote CDP in split-host setups
|
||||
title: "WSL2 + Windows + remote Chrome CDP troubleshooting"
|
||||
---
|
||||
|
||||
@ -21,27 +21,27 @@ It also covers the layered failure pattern from [issue #39369](https://github.co
|
||||
|
||||
You have two valid patterns:
|
||||
|
||||
### Option 1: Raw remote CDP
|
||||
### Option 1: Raw remote CDP from WSL2 to Windows
|
||||
|
||||
Use a remote browser profile that points from WSL2 to a Windows Chrome CDP endpoint.
|
||||
|
||||
Choose this when:
|
||||
|
||||
- you only need browser control
|
||||
- you are comfortable exposing Chrome remote debugging to WSL2
|
||||
- you do not need the Chrome extension relay
|
||||
- the Gateway stays inside WSL2
|
||||
- Chrome runs on Windows
|
||||
- you need browser control to cross the WSL2/Windows boundary
|
||||
|
||||
### Option 2: Chrome extension relay
|
||||
### Option 2: Host-local Chrome MCP
|
||||
|
||||
Use the built-in `chrome-relay` profile plus the OpenClaw Chrome extension.
|
||||
Use `existing-session` / `user` only when the Gateway itself runs on the same host as Chrome.
|
||||
|
||||
Choose this when:
|
||||
|
||||
- you want to attach to an existing Windows Chrome tab with the toolbar button
|
||||
- you want extension-based control instead of raw `--remote-debugging-port`
|
||||
- the relay itself must be reachable across the WSL2/Windows boundary
|
||||
- OpenClaw and Chrome are on the same machine
|
||||
- you want the local signed-in browser state
|
||||
- you do not need cross-host browser transport
|
||||
|
||||
If you use the extension relay across namespaces, `browser.relayBindHost` is the important setting introduced in [Browser](/tools/browser) and [Chrome extension](/tools/chrome-extension).
|
||||
For WSL2 Gateway + Windows Chrome, prefer raw remote CDP. Chrome MCP is host-local, not a WSL2-to-Windows bridge.
|
||||
|
||||
## Working architecture
|
||||
|
||||
@ -62,7 +62,6 @@ Several failures can overlap:
|
||||
- `gateway.controlUi.allowedOrigins` does not match the page origin
|
||||
- token or pairing is missing
|
||||
- the browser profile points at the wrong address
|
||||
- the extension relay is still loopback-only when you actually need cross-namespace access
|
||||
|
||||
Because of that, fixing one layer can still leave a different error visible.
|
||||
|
||||
@ -145,31 +144,7 @@ Notes:
|
||||
- keep `attachOnly: true` for externally managed browsers
|
||||
- test the same URL with `curl` before expecting OpenClaw to succeed
|
||||
|
||||
### Layer 4: If you use the Chrome extension relay instead
|
||||
|
||||
If the browser machine and the Gateway are separated by a namespace boundary, the relay may need a non-loopback bind address.
|
||||
|
||||
Example:
|
||||
|
||||
```json5
|
||||
{
|
||||
browser: {
|
||||
enabled: true,
|
||||
defaultProfile: "chrome-relay",
|
||||
relayBindHost: "0.0.0.0",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Use this only when needed:
|
||||
|
||||
- default behavior is safer because the relay stays loopback-only
|
||||
- `0.0.0.0` expands exposure surface
|
||||
- keep Gateway auth, node pairing, and the surrounding network private
|
||||
|
||||
If you do not need the extension relay, prefer the raw remote CDP profile above.
|
||||
|
||||
### Layer 5: Verify the Control UI layer separately
|
||||
### Layer 4: Verify the Control UI layer separately
|
||||
|
||||
Open the UI from Windows:
|
||||
|
||||
@ -185,7 +160,7 @@ Helpful page:
|
||||
|
||||
- [Control UI](/web/control-ui)
|
||||
|
||||
### Layer 6: Verify end-to-end browser control
|
||||
### Layer 5: Verify end-to-end browser control
|
||||
|
||||
From WSL2:
|
||||
|
||||
@ -194,12 +169,6 @@ openclaw browser open https://example.com --browser-profile remote
|
||||
openclaw browser tabs --browser-profile remote
|
||||
```
|
||||
|
||||
For the extension relay:
|
||||
|
||||
```bash
|
||||
openclaw browser tabs --browser-profile chrome-relay
|
||||
```
|
||||
|
||||
Good result:
|
||||
|
||||
- the tab opens in Windows Chrome
|
||||
@ -220,8 +189,8 @@ Treat each message as a layer-specific clue:
|
||||
- WSL2 cannot reach the configured `cdpUrl`
|
||||
- `gateway timeout after 1500ms`
|
||||
- often still CDP reachability or a slow/unreachable remote endpoint
|
||||
- `Chrome extension relay is running, but no tab is connected`
|
||||
- extension relay profile selected, but no attached tab exists yet
|
||||
- `No Chrome tabs found for profile="user"`
|
||||
- local Chrome MCP profile selected where no host-local tabs are available
|
||||
|
||||
## Fast triage checklist
|
||||
|
||||
@ -229,11 +198,11 @@ Treat each message as a layer-specific clue:
|
||||
2. WSL2: does `curl http://WINDOWS_HOST_OR_IP:9222/json/version` work?
|
||||
3. OpenClaw config: does `browser.profiles.<name>.cdpUrl` use that exact WSL2-reachable address?
|
||||
4. Control UI: are you opening `http://127.0.0.1:18789/` instead of a LAN IP?
|
||||
5. Extension relay only: do you actually need `browser.relayBindHost`, and if so is it set explicitly?
|
||||
5. Are you trying to use `existing-session` across WSL2 and Windows instead of raw remote CDP?
|
||||
|
||||
## Practical takeaway
|
||||
|
||||
The setup is usually viable. The hard part is that browser transport, Control UI origin security, token/pairing, and extension-relay topology can each fail independently while looking similar from the user side.
|
||||
The setup is usually viable. The hard part is that browser transport, Control UI origin security, and token/pairing can each fail independently while looking similar from the user side.
|
||||
|
||||
When in doubt:
|
||||
|
||||
|
||||
@ -18,8 +18,7 @@ Beginner view:
|
||||
- Think of it as a **separate, agent-only browser**.
|
||||
- The `openclaw` profile does **not** touch your personal browser profile.
|
||||
- The agent can **open tabs, read pages, click, and type** in a safe lane.
|
||||
- The built-in `user` profile attaches to your real signed-in Chrome session;
|
||||
`chrome-relay` is the explicit extension-relay profile.
|
||||
- The built-in `user` profile attaches to your real signed-in Chrome session via Chrome MCP.
|
||||
|
||||
## What you get
|
||||
|
||||
@ -43,21 +42,17 @@ openclaw browser --browser-profile openclaw snapshot
|
||||
If you get “Browser disabled”, enable it in config (see below) and restart the
|
||||
Gateway.
|
||||
|
||||
## Profiles: `openclaw` vs `user` vs `chrome-relay`
|
||||
## Profiles: `openclaw` vs `user`
|
||||
|
||||
- `openclaw`: managed, isolated browser (no extension required).
|
||||
- `user`: built-in Chrome MCP attach profile for your **real signed-in Chrome**
|
||||
session.
|
||||
- `chrome-relay`: extension relay to your **system browser** (requires the
|
||||
OpenClaw extension to be attached to a tab).
|
||||
|
||||
For agent browser tool calls:
|
||||
|
||||
- Default: use the isolated `openclaw` browser.
|
||||
- Prefer `profile="user"` when existing logged-in sessions matter and the user
|
||||
is at the computer to click/approve any attach prompt.
|
||||
- Use `profile="chrome-relay"` only when the user explicitly wants the Chrome
|
||||
extension / toolbar-button attach flow.
|
||||
- `profile` is the explicit override when you want a specific browser mode.
|
||||
|
||||
Set `browser.defaultProfile: "openclaw"` if you want managed mode by default.
|
||||
@ -93,11 +88,6 @@ Browser settings live in `~/.openclaw/openclaw.json`.
|
||||
attachOnly: true,
|
||||
color: "#00AA00",
|
||||
},
|
||||
"chrome-relay": {
|
||||
driver: "extension",
|
||||
cdpUrl: "http://127.0.0.1:18792",
|
||||
color: "#00AA00",
|
||||
},
|
||||
remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
|
||||
},
|
||||
},
|
||||
@ -107,10 +97,10 @@ Browser settings live in `~/.openclaw/openclaw.json`.
|
||||
Notes:
|
||||
|
||||
- The browser control service binds to loopback on a port derived from `gateway.port`
|
||||
(default: `18791`, which is gateway + 2). The relay uses the next port (`18792`).
|
||||
(default: `18791`, which is gateway + 2).
|
||||
- If you override the Gateway port (`gateway.port` or `OPENCLAW_GATEWAY_PORT`),
|
||||
the derived browser ports shift to stay in the same “family”.
|
||||
- `cdpUrl` defaults to the relay port when unset.
|
||||
- `cdpUrl` defaults to the managed local CDP port when unset.
|
||||
- `remoteCdpTimeoutMs` applies to remote (non-loopback) CDP reachability checks.
|
||||
- `remoteCdpHandshakeTimeoutMs` applies to remote CDP WebSocket reachability checks.
|
||||
- Browser navigation/open-tab is SSRF-guarded before navigation and best-effort re-checked on final `http(s)` URL after navigation.
|
||||
@ -119,7 +109,7 @@ Notes:
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` remains supported as a legacy alias for compatibility.
|
||||
- `attachOnly: true` means “never launch a local browser; only attach if it is already running.”
|
||||
- `color` + per-profile `color` tint the browser UI so you can see which profile is active.
|
||||
- Default profile is `openclaw` (OpenClaw-managed standalone browser). Use `defaultProfile: "user"` to opt into the signed-in user browser, or `defaultProfile: "chrome-relay"` for the extension relay.
|
||||
- Default profile is `openclaw` (OpenClaw-managed standalone browser). Use `defaultProfile: "user"` to opt into the signed-in user browser.
|
||||
- Auto-detect order: system default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl` — set those only for remote CDP.
|
||||
- `driver: "existing-session"` uses Chrome DevTools MCP instead of raw CDP. Do
|
||||
@ -287,77 +277,18 @@ OpenClaw supports multiple named profiles (routing configs). Profiles can be:
|
||||
|
||||
- **openclaw-managed**: a dedicated Chromium-based browser instance with its own user data directory + CDP port
|
||||
- **remote**: an explicit CDP URL (Chromium-based browser running elsewhere)
|
||||
- **extension relay**: your existing Chrome tab(s) via the local relay + Chrome extension
|
||||
- **existing session**: your existing Chrome profile via Chrome DevTools MCP auto-connect
|
||||
|
||||
Defaults:
|
||||
|
||||
- The `openclaw` profile is auto-created if missing.
|
||||
- The `chrome-relay` profile is built-in for the Chrome extension relay (points at `http://127.0.0.1:18792` by default).
|
||||
- Existing-session profiles are opt-in; create them with `--driver existing-session`.
|
||||
- The `user` profile is built-in for Chrome MCP existing-session attach.
|
||||
- Existing-session profiles are opt-in beyond `user`; create them with `--driver existing-session`.
|
||||
- Local CDP ports allocate from **18800–18899** by default.
|
||||
- Deleting a profile moves its local data directory to Trash.
|
||||
|
||||
All control endpoints accept `?profile=<name>`; the CLI uses `--browser-profile`.
|
||||
|
||||
## Chrome extension relay (use your existing Chrome)
|
||||
|
||||
OpenClaw can also drive **your existing Chrome tabs** (no separate “openclaw” Chrome instance) via a local CDP relay + a Chrome extension.
|
||||
|
||||
Full guide: [Chrome extension](/tools/chrome-extension)
|
||||
|
||||
Flow:
|
||||
|
||||
- The Gateway runs locally (same machine) or a node host runs on the browser machine.
|
||||
- A local **relay server** listens at a loopback `cdpUrl` (default: `http://127.0.0.1:18792`).
|
||||
- You click the **OpenClaw Browser Relay** extension icon on a tab to attach (it does not auto-attach).
|
||||
- The agent controls that tab via the normal `browser` tool, by selecting the right profile.
|
||||
|
||||
If the Gateway runs elsewhere, run a node host on the browser machine so the Gateway can proxy browser actions.
|
||||
|
||||
### Sandboxed sessions
|
||||
|
||||
If the agent session is sandboxed, the `browser` tool may default to `target="sandbox"` (sandbox browser).
|
||||
Chrome extension relay takeover requires host browser control, so either:
|
||||
|
||||
- run the session unsandboxed, or
|
||||
- set `agents.defaults.sandbox.browser.allowHostControl: true` and use `target="host"` when calling the tool.
|
||||
|
||||
### Setup
|
||||
|
||||
1. Load the extension (dev/unpacked):
|
||||
|
||||
```bash
|
||||
openclaw browser extension install
|
||||
```
|
||||
|
||||
- Chrome → `chrome://extensions` → enable “Developer mode”
|
||||
- “Load unpacked” → select the directory printed by `openclaw browser extension path`
|
||||
- Pin the extension, then click it on the tab you want to control (badge shows `ON`).
|
||||
|
||||
2. Use it:
|
||||
|
||||
- CLI: `openclaw browser --browser-profile chrome-relay tabs`
|
||||
- Agent tool: `browser` with `profile="chrome-relay"`
|
||||
|
||||
Optional: if you want a different name or relay port, create your own profile:
|
||||
|
||||
```bash
|
||||
openclaw browser create-profile \
|
||||
--name my-chrome \
|
||||
--driver extension \
|
||||
--cdp-url http://127.0.0.1:18792 \
|
||||
--color "#00AA00"
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- This mode relies on Playwright-on-CDP for most operations (screenshots/snapshots/actions).
|
||||
- Detach by clicking the extension icon again.
|
||||
- Agent use: prefer `profile="user"` for logged-in sites. Use `profile="chrome-relay"`
|
||||
only when you specifically want the extension flow. The user must be present
|
||||
to click the extension and attach the tab.
|
||||
|
||||
## Chrome existing-session via MCP
|
||||
|
||||
OpenClaw can also attach to a running Chrome profile through the official
|
||||
@ -404,13 +335,14 @@ What to check if attach does not work:
|
||||
- Chrome is version `144+`
|
||||
- remote debugging is enabled at `chrome://inspect/#remote-debugging`
|
||||
- Chrome showed and you accepted the attach consent prompt
|
||||
- `openclaw doctor` migrates old extension-based browser config and checks that
|
||||
Chrome is installed locally with a compatible version, but it cannot enable
|
||||
Chrome-side remote debugging for you
|
||||
|
||||
Agent use:
|
||||
|
||||
- Use `profile="user"` when you need the user’s logged-in browser state.
|
||||
- If you use a custom existing-session profile, pass that explicit profile name.
|
||||
- Prefer `profile="user"` over `profile="chrome-relay"` unless the user
|
||||
explicitly wants the extension / attach-tab flow.
|
||||
- Only choose this mode when the user is at the computer to approve the attach
|
||||
prompt.
|
||||
- the Gateway or node host can spawn `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
@ -427,21 +359,10 @@ Notes:
|
||||
captures from snapshots, but not CSS `--element` selectors.
|
||||
- Existing-session `wait --url` supports exact, substring, and glob patterns
|
||||
like other browser drivers. `wait --load networkidle` is not supported yet.
|
||||
- Some features still require the extension relay or managed browser path, such
|
||||
as PDF export and download interception.
|
||||
- Leave the relay loopback-only by default. If the relay must be reachable from a different network namespace (for example Gateway in WSL2, Chrome on Windows), set `browser.relayBindHost` to an explicit bind address such as `0.0.0.0` while keeping the surrounding network private and authenticated.
|
||||
|
||||
WSL2 / cross-namespace example:
|
||||
|
||||
```json5
|
||||
{
|
||||
browser: {
|
||||
enabled: true,
|
||||
relayBindHost: "0.0.0.0",
|
||||
defaultProfile: "chrome-relay",
|
||||
},
|
||||
}
|
||||
```
|
||||
- Some features still require the managed browser path, such as PDF export and
|
||||
download interception.
|
||||
- Existing-session is host-local. If Chrome lives on a different machine or a
|
||||
different network namespace, use remote CDP or a node host instead.
|
||||
|
||||
## Isolation guarantees
|
||||
|
||||
@ -496,7 +417,6 @@ If gateway auth is configured, browser HTTP routes require auth too:
|
||||
Some features (navigate/act/AI snapshot/role snapshot, element screenshots, PDF) require
|
||||
Playwright. If Playwright isn’t installed, those endpoints return a clear 501
|
||||
error. ARIA snapshots and basic screenshots still work for openclaw-managed Chrome.
|
||||
For the Chrome extension relay driver, ARIA snapshots and screenshots require Playwright.
|
||||
|
||||
If you see `Playwright is not available in this gateway build`, install the full
|
||||
Playwright package (not `playwright-core`) and restart the gateway, or reinstall
|
||||
|
||||
@ -1,203 +0,0 @@
|
||||
---
|
||||
summary: "Chrome extension: let OpenClaw drive your existing Chrome tab"
|
||||
read_when:
|
||||
- You want the agent to drive an existing Chrome tab (toolbar button)
|
||||
- You need remote Gateway + local browser automation via Tailscale
|
||||
- You want to understand the security implications of browser takeover
|
||||
title: "Chrome Extension"
|
||||
---
|
||||
|
||||
# Chrome extension (browser relay)
|
||||
|
||||
The OpenClaw Chrome extension lets the agent control your **existing Chrome tabs** (your normal Chrome window) instead of launching a separate openclaw-managed Chrome profile.
|
||||
|
||||
Attach/detach happens via a **single Chrome toolbar button**.
|
||||
|
||||
If you want Chrome’s official DevTools MCP attach flow instead of the OpenClaw
|
||||
extension relay, use an `existing-session` browser profile instead. See
|
||||
[Browser](/tools/browser#chrome-existing-session-via-mcp). For Chrome’s own
|
||||
setup docs, see [Chrome for Developers: Use Chrome DevTools MCP with your
|
||||
browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
|
||||
and the [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp).
|
||||
|
||||
## What it is (concept)
|
||||
|
||||
There are three parts:
|
||||
|
||||
- **Browser control service** (Gateway or node): the API the agent/tool calls (via the Gateway)
|
||||
- **Local relay server** (loopback CDP): bridges between the control server and the extension (`http://127.0.0.1:18792` by default)
|
||||
- **Chrome MV3 extension**: attaches to the active tab using `chrome.debugger` and pipes CDP messages to the relay
|
||||
|
||||
OpenClaw then controls the attached tab through the normal `browser` tool surface (selecting the right profile).
|
||||
|
||||
## Install / load (unpacked)
|
||||
|
||||
1. Install the extension to a stable local path:
|
||||
|
||||
```bash
|
||||
openclaw browser extension install
|
||||
```
|
||||
|
||||
2. Print the installed extension directory path:
|
||||
|
||||
```bash
|
||||
openclaw browser extension path
|
||||
```
|
||||
|
||||
3. Chrome → `chrome://extensions`
|
||||
|
||||
- Enable “Developer mode”
|
||||
- “Load unpacked” → select the directory printed above
|
||||
|
||||
4. Pin the extension.
|
||||
|
||||
## Updates (no build step)
|
||||
|
||||
The extension ships inside the OpenClaw release (npm package) as static files. There is no separate “build” step.
|
||||
|
||||
After upgrading OpenClaw:
|
||||
|
||||
- Re-run `openclaw browser extension install` to refresh the installed files under your OpenClaw state directory.
|
||||
- Chrome → `chrome://extensions` → click “Reload” on the extension.
|
||||
|
||||
## Use it (set gateway token once)
|
||||
|
||||
To use the extension relay, create a browser profile for it:
|
||||
|
||||
Before first attach, open extension Options and set:
|
||||
|
||||
- `Port` (default `18792`)
|
||||
- `Gateway token` (must match `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN`)
|
||||
|
||||
Then create a profile:
|
||||
|
||||
```bash
|
||||
openclaw browser create-profile \
|
||||
--name my-chrome \
|
||||
--driver extension \
|
||||
--cdp-url http://127.0.0.1:18792 \
|
||||
--color "#00AA00"
|
||||
```
|
||||
|
||||
Use it:
|
||||
|
||||
- CLI: `openclaw browser --browser-profile my-chrome tabs`
|
||||
- Agent tool: `browser` with `profile="my-chrome"`
|
||||
|
||||
### Custom Gateway ports
|
||||
|
||||
If you're using a custom gateway port, the extension relay port is automatically derived:
|
||||
|
||||
**Extension Relay Port = Gateway Port + 3**
|
||||
|
||||
Example: if `gateway.port: 19001`, then:
|
||||
|
||||
- Extension relay port: `19004` (gateway + 3)
|
||||
|
||||
Configure the extension to use the derived relay port in the extension Options page.
|
||||
|
||||
## Attach / detach (toolbar button)
|
||||
|
||||
- Open the tab you want OpenClaw to control.
|
||||
- Click the extension icon.
|
||||
- Badge shows `ON` when attached.
|
||||
- Click again to detach.
|
||||
|
||||
## Which tab does it control?
|
||||
|
||||
- It does **not** automatically control “whatever tab you’re looking at”.
|
||||
- It controls **only the tab(s) you explicitly attached** by clicking the toolbar button.
|
||||
- To switch: open the other tab and click the extension icon there.
|
||||
|
||||
## Badge + common errors
|
||||
|
||||
- `ON`: attached; OpenClaw can drive that tab.
|
||||
- `…`: connecting to the local relay.
|
||||
- `!`: relay not reachable/authenticated (most common: relay server not running, or gateway token missing/wrong).
|
||||
|
||||
If you see `!`:
|
||||
|
||||
- Make sure the Gateway is running locally (default setup), or run a node host on this machine if the Gateway runs elsewhere.
|
||||
- Open the extension Options page; it validates relay reachability + gateway-token auth.
|
||||
|
||||
## Remote Gateway (use a node host)
|
||||
|
||||
### Local Gateway (same machine as Chrome) — usually **no extra steps**
|
||||
|
||||
If the Gateway runs on the same machine as Chrome, it starts the browser control service on loopback
|
||||
and auto-starts the relay server. The extension talks to the local relay; the CLI/tool calls go to the Gateway.
|
||||
|
||||
### Remote Gateway (Gateway runs elsewhere) — **run a node host**
|
||||
|
||||
If your Gateway runs on another machine, start a node host on the machine that runs Chrome.
|
||||
The Gateway will proxy browser actions to that node; the extension + relay stay local to the browser machine.
|
||||
|
||||
If multiple nodes are connected, pin one with `gateway.nodes.browser.node` or set `gateway.nodes.browser.mode`.
|
||||
|
||||
## Sandboxing (tool containers)
|
||||
|
||||
If your agent session is sandboxed (`agents.defaults.sandbox.mode != "off"`), the `browser` tool can be restricted:
|
||||
|
||||
- By default, sandboxed sessions often target the **sandbox browser** (`target="sandbox"`), not your host Chrome.
|
||||
- Chrome extension relay takeover requires controlling the **host** browser control server.
|
||||
|
||||
Options:
|
||||
|
||||
- Easiest: use the extension from a **non-sandboxed** session/agent.
|
||||
- Or allow host browser control for sandboxed sessions:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
browser: {
|
||||
allowHostControl: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Then ensure the tool isn’t denied by tool policy, and (if needed) call `browser` with `target="host"`.
|
||||
|
||||
Debugging: `openclaw sandbox explain`
|
||||
|
||||
## Remote access tips
|
||||
|
||||
- Keep the Gateway and node host on the same tailnet; avoid exposing relay ports to LAN or public Internet.
|
||||
- Pair nodes intentionally; disable browser proxy routing if you don’t want remote control (`gateway.nodes.browser.mode="off"`).
|
||||
- Leave the relay on loopback unless you have a real cross-namespace need. For WSL2 or similar split-host setups, set `browser.relayBindHost` to an explicit bind address such as `0.0.0.0`, then keep access constrained with Gateway auth, node pairing, and a private network.
|
||||
|
||||
## How “extension path” works
|
||||
|
||||
`openclaw browser extension path` prints the **installed** on-disk directory containing the extension files.
|
||||
|
||||
The CLI intentionally does **not** print a `node_modules` path. Always run `openclaw browser extension install` first to copy the extension to a stable location under your OpenClaw state directory.
|
||||
|
||||
If you move or delete that install directory, Chrome will mark the extension as broken until you reload it from a valid path.
|
||||
|
||||
## Security implications (read this)
|
||||
|
||||
This is powerful and risky. Treat it like giving the model “hands on your browser”.
|
||||
|
||||
- The extension uses Chrome’s debugger API (`chrome.debugger`). When attached, the model can:
|
||||
- click/type/navigate in that tab
|
||||
- read page content
|
||||
- access whatever the tab’s logged-in session can access
|
||||
- **This is not isolated** like the dedicated openclaw-managed profile.
|
||||
- If you attach to your daily-driver profile/tab, you’re granting access to that account state.
|
||||
|
||||
Recommendations:
|
||||
|
||||
- Prefer a dedicated Chrome profile (separate from your personal browsing) for extension relay usage.
|
||||
- Keep the Gateway and any node hosts tailnet-only; rely on Gateway auth + node pairing.
|
||||
- Avoid exposing relay ports over LAN (`0.0.0.0`) and avoid Funnel (public).
|
||||
- The relay blocks non-extension origins and requires gateway-token auth for both `/cdp` and `/extension`.
|
||||
|
||||
Related:
|
||||
|
||||
- Browser tool overview: [Browser](/tools/browser)
|
||||
- Security audit: [Security](/gateway/security)
|
||||
- Tailscale setup: [Tailscale](/gateway/tailscale)
|
||||
@ -318,8 +318,7 @@ Common parameters:
|
||||
- All actions accept optional `profile` parameter for multi-instance support.
|
||||
- Omit `profile` for the safe default: isolated OpenClaw-managed browser (`openclaw`).
|
||||
- Use `profile="user"` for the real local host browser when existing logins/cookies matter and the user is present to click/approve any attach prompt.
|
||||
- Use `profile="chrome-relay"` only for the Chrome extension / toolbar-button attach flow.
|
||||
- `profile="user"` and `profile="chrome-relay"` are host-only; do not combine them with sandbox/node targets.
|
||||
- `profile="user"` is host-only; do not combine it with sandbox/node targets.
|
||||
- When `profile` is omitted, uses `browser.defaultProfile` (defaults to `openclaw`).
|
||||
- Profile names: lowercase alphanumeric + hyphens only (max 64 chars).
|
||||
- Port range: 18800-18899 (~100 profiles max).
|
||||
|
||||
@ -57,6 +57,18 @@ openclaw plugins install ./my-bundle
|
||||
openclaw plugins install ./my-bundle.tgz
|
||||
```
|
||||
|
||||
For Claude marketplace installs, list the marketplace first, then install by
|
||||
marketplace entry name:
|
||||
|
||||
```bash
|
||||
openclaw plugins marketplace list <marketplace-name>
|
||||
openclaw plugins install <plugin-name>@<marketplace-name>
|
||||
```
|
||||
|
||||
OpenClaw resolves known Claude marketplace names from
|
||||
`~/.claude/plugins/known_marketplaces.json`. You can also pass an explicit
|
||||
marketplace source with `--marketplace`.
|
||||
|
||||
## Architecture
|
||||
|
||||
OpenClaw's plugin system has four layers:
|
||||
@ -94,6 +106,10 @@ OpenClaw also recognizes two compatible external bundle layouts:
|
||||
component layout without a manifest
|
||||
- Cursor-style bundles: `.cursor-plugin/plugin.json`
|
||||
|
||||
Claude marketplace entries can point at any of these compatible bundles, or at
|
||||
native OpenClaw plugin sources. OpenClaw resolves the marketplace entry first,
|
||||
then runs the normal install path for the resolved source.
|
||||
|
||||
They are shown in the plugin list as `format=bundle`, with a subtype of
|
||||
`codex` or `claude` in verbose/info output.
|
||||
|
||||
@ -218,9 +234,10 @@ Tool authoring guide: [Plugin agent tools](/plugins/agent-tools).
|
||||
Provider plugins now have two layers:
|
||||
|
||||
- manifest metadata: `providerAuthEnvVars` for cheap env-auth lookup before
|
||||
runtime load
|
||||
runtime load, plus `providerAuthChoices` for cheap onboarding/auth-choice
|
||||
labels and CLI flag metadata before runtime load
|
||||
- config-time hooks: `catalog` / legacy `discovery`
|
||||
- runtime hooks: `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`, `capabilities`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`
|
||||
- runtime hooks: `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`, `capabilities`, `prepareExtraParams`, `wrapStreamFn`, `formatApiKey`, `refreshOAuth`, `buildAuthDoctorHint`, `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`
|
||||
|
||||
OpenClaw still owns the generic agent loop, failover, transcript handling, and
|
||||
tool policy. These hooks are the seam for provider-specific behavior without
|
||||
@ -228,8 +245,11 @@ needing a whole custom inference transport.
|
||||
|
||||
Use manifest `providerAuthEnvVars` when the provider has env-based credentials
|
||||
that generic auth/status/model-picker paths should see without loading plugin
|
||||
runtime. Keep provider runtime `envVars` for operator-facing hints such as
|
||||
onboarding labels or OAuth client-id/client-secret setup vars.
|
||||
runtime. Use manifest `providerAuthChoices` when onboarding/auth-choice CLI
|
||||
surfaces should know the provider's choice id, group labels, and simple
|
||||
one-flag auth wiring without loading provider runtime. Keep provider runtime
|
||||
`envVars` for operator-facing hints such as onboarding labels or OAuth
|
||||
client-id/client-secret setup vars.
|
||||
|
||||
### Hook order
|
||||
|
||||
@ -254,31 +274,39 @@ For model/provider plugins, OpenClaw uses hooks in this rough order:
|
||||
Provider-owned request-param normalization before generic stream option wrappers.
|
||||
8. `wrapStreamFn`
|
||||
Provider-owned stream wrapper after generic wrappers are applied.
|
||||
9. `isCacheTtlEligible`
|
||||
Provider-owned prompt-cache policy for proxy/backhaul providers.
|
||||
10. `buildMissingAuthMessage`
|
||||
9. `formatApiKey`
|
||||
Provider-owned auth-profile formatter used when a stored auth profile needs
|
||||
to become the runtime `apiKey` string.
|
||||
10. `refreshOAuth`
|
||||
Provider-owned OAuth refresh override for custom refresh endpoints or
|
||||
refresh-failure policy.
|
||||
11. `buildAuthDoctorHint`
|
||||
Provider-owned repair hint appended when OAuth refresh fails.
|
||||
12. `isCacheTtlEligible`
|
||||
Provider-owned prompt-cache policy for proxy/backhaul providers.
|
||||
13. `buildMissingAuthMessage`
|
||||
Provider-owned replacement for the generic missing-auth recovery message.
|
||||
11. `suppressBuiltInModel`
|
||||
14. `suppressBuiltInModel`
|
||||
Provider-owned stale upstream model suppression plus optional user-facing
|
||||
error hint.
|
||||
12. `augmentModelCatalog`
|
||||
15. `augmentModelCatalog`
|
||||
Provider-owned synthetic/final catalog rows appended after discovery.
|
||||
13. `isBinaryThinking`
|
||||
16. `isBinaryThinking`
|
||||
Provider-owned on/off reasoning toggle for binary-thinking providers.
|
||||
14. `supportsXHighThinking`
|
||||
17. `supportsXHighThinking`
|
||||
Provider-owned `xhigh` reasoning support for selected models.
|
||||
15. `resolveDefaultThinkingLevel`
|
||||
18. `resolveDefaultThinkingLevel`
|
||||
Provider-owned default `/think` level for a specific model family.
|
||||
16. `isModernModelRef`
|
||||
19. `isModernModelRef`
|
||||
Provider-owned modern-model matcher used by live profile filters and smoke
|
||||
selection.
|
||||
17. `prepareRuntimeAuth`
|
||||
20. `prepareRuntimeAuth`
|
||||
Exchanges a configured credential into the actual runtime token/key just
|
||||
before inference.
|
||||
18. `resolveUsageAuth`
|
||||
21. `resolveUsageAuth`
|
||||
Resolves usage/billing credentials for `/usage` and related status
|
||||
surfaces.
|
||||
19. `fetchUsageSnapshot`
|
||||
22. `fetchUsageSnapshot`
|
||||
Fetches and normalizes provider-specific usage/quota snapshots after auth
|
||||
is resolved.
|
||||
|
||||
@ -291,6 +319,9 @@ For model/provider plugins, OpenClaw uses hooks in this rough order:
|
||||
- `capabilities`: publish provider-family and transcript/tooling quirks without hardcoding provider ids in core
|
||||
- `prepareExtraParams`: set provider defaults or normalize provider-specific per-model params before generic stream wrapping
|
||||
- `wrapStreamFn`: add provider-specific headers/payload/model compat patches while still using the normal `pi-ai` execution path
|
||||
- `formatApiKey`: turn a stored auth profile into the runtime `apiKey` string without hardcoding provider token blobs in core
|
||||
- `refreshOAuth`: own OAuth refresh for providers that do not fit the shared `pi-ai` refreshers
|
||||
- `buildAuthDoctorHint`: append provider-owned auth repair guidance when refresh fails
|
||||
- `isCacheTtlEligible`: decide whether provider/model pairs should use cache TTL metadata
|
||||
- `buildMissingAuthMessage`: replace the generic auth-store error with a provider-specific recovery hint
|
||||
- `suppressBuiltInModel`: hide stale upstream rows and optionally return a provider-owned error for direct resolution failures
|
||||
@ -312,6 +343,9 @@ Rule of thumb:
|
||||
- provider needs transcript/provider-family quirks: use `capabilities`
|
||||
- provider needs default request params or per-provider param cleanup: use `prepareExtraParams`
|
||||
- provider needs request headers/body/model compat wrappers without a custom transport: use `wrapStreamFn`
|
||||
- provider stores extra metadata in auth profiles and needs a custom runtime token shape: use `formatApiKey`
|
||||
- provider needs a custom OAuth refresh endpoint or refresh failure policy: use `refreshOAuth`
|
||||
- provider needs provider-owned auth repair guidance after refresh failure: use `buildAuthDoctorHint`
|
||||
- provider needs proxy-specific cache TTL gating: use `isCacheTtlEligible`
|
||||
- provider needs a provider-specific missing-auth recovery hint: use `buildMissingAuthMessage`
|
||||
- provider needs to hide stale upstream rows or replace them with a vendor hint: use `suppressBuiltInModel`
|
||||
@ -384,11 +418,12 @@ api.registerProvider({
|
||||
|
||||
### Built-in examples
|
||||
|
||||
- Anthropic uses `resolveDynamicModel`, `capabilities`, `resolveUsageAuth`,
|
||||
`fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`,
|
||||
and `isModernModelRef` because it owns Claude 4.6 forward-compat,
|
||||
provider-family hints, usage endpoint integration, prompt-cache
|
||||
eligibility, and Claude default/adaptive thinking policy.
|
||||
- Anthropic uses `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`,
|
||||
`resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`,
|
||||
`resolveDefaultThinkingLevel`, and `isModernModelRef` because it owns Claude
|
||||
4.6 forward-compat, provider-family hints, auth repair guidance, usage
|
||||
endpoint integration, prompt-cache eligibility, and Claude default/adaptive
|
||||
thinking policy.
|
||||
- OpenAI uses `resolveDynamicModel`, `normalizeResolvedModel`, and
|
||||
`capabilities` plus `buildMissingAuthMessage`, `suppressBuiltInModel`,
|
||||
`augmentModelCatalog`, `supportsXHighThinking`, and `isModernModelRef`
|
||||
@ -399,20 +434,22 @@ api.registerProvider({
|
||||
- OpenRouter uses `catalog` plus `resolveDynamicModel` and
|
||||
`prepareDynamicModel` because the provider is pass-through and may expose new
|
||||
model ids before OpenClaw's static catalog updates.
|
||||
- GitHub Copilot uses `catalog`, `resolveDynamicModel`, and
|
||||
- GitHub Copilot uses `catalog`, `auth`, `resolveDynamicModel`, and
|
||||
`capabilities` plus `prepareRuntimeAuth` and `fetchUsageSnapshot` because it
|
||||
needs model fallback behavior, Claude transcript quirks, a GitHub token ->
|
||||
Copilot token exchange, and a provider-owned usage endpoint.
|
||||
needs provider-owned device login, model fallback behavior, Claude transcript
|
||||
quirks, a GitHub token -> Copilot token exchange, and a provider-owned usage
|
||||
endpoint.
|
||||
- OpenAI Codex uses `catalog`, `resolveDynamicModel`,
|
||||
`normalizeResolvedModel`, and `augmentModelCatalog` plus
|
||||
`normalizeResolvedModel`, `refreshOAuth`, and `augmentModelCatalog` plus
|
||||
`prepareExtraParams`, `resolveUsageAuth`, and `fetchUsageSnapshot` because it
|
||||
still runs on core OpenAI transports but owns its transport/base URL
|
||||
normalization, default transport choice, synthetic Codex catalog rows, and
|
||||
ChatGPT usage endpoint integration.
|
||||
normalization, OAuth refresh fallback policy, default transport choice,
|
||||
synthetic Codex catalog rows, and ChatGPT usage endpoint integration.
|
||||
- Google AI Studio and Gemini CLI OAuth use `resolveDynamicModel` and
|
||||
`isModernModelRef` because they own Gemini 3.1 forward-compat fallback and
|
||||
modern-model matching; Gemini CLI OAuth also uses `resolveUsageAuth` and
|
||||
`fetchUsageSnapshot` for token parsing and quota endpoint wiring.
|
||||
modern-model matching; Gemini CLI OAuth also uses `formatApiKey`,
|
||||
`resolveUsageAuth`, and `fetchUsageSnapshot` for token formatting, token
|
||||
parsing, and quota endpoint wiring.
|
||||
- OpenRouter uses `capabilities`, `wrapStreamFn`, and `isCacheTtlEligible`
|
||||
to keep provider-specific request headers, routing metadata, reasoning
|
||||
patches, and prompt-cache policy out of core.
|
||||
@ -430,9 +467,10 @@ api.registerProvider({
|
||||
- Mistral, OpenCode Zen, and OpenCode Go use `capabilities` only to keep
|
||||
transcript/tooling quirks out of core.
|
||||
- Catalog-only bundled providers such as `byteplus`, `cloudflare-ai-gateway`,
|
||||
`huggingface`, `kimi-coding`, `minimax-portal`, `modelstudio`, `nvidia`,
|
||||
`qianfan`, `qwen-portal`, `synthetic`, `together`, `venice`,
|
||||
`vercel-ai-gateway`, and `volcengine` use `catalog` only.
|
||||
`huggingface`, `kimi-coding`, `modelstudio`, `nvidia`, `qianfan`,
|
||||
`synthetic`, `together`, `venice`, `vercel-ai-gateway`, and `volcengine` use
|
||||
`catalog` only.
|
||||
- Qwen portal uses `catalog`, `auth`, and `refreshOAuth`.
|
||||
- MiniMax and Xiaomi use `catalog` plus usage hooks because their `/usage`
|
||||
behavior is plugin-owned even though inference still runs through the shared
|
||||
transports.
|
||||
@ -549,14 +587,14 @@ Notes:
|
||||
Use SDK subpaths instead of the monolithic `openclaw/plugin-sdk` import when
|
||||
authoring plugins:
|
||||
|
||||
- `openclaw/plugin-sdk/core` for generic plugin APIs, provider auth types, and shared helpers.
|
||||
- `openclaw/plugin-sdk/core` for generic plugin APIs, provider auth types, and shared helpers such as routing/session utilities and logger-backed runtimes.
|
||||
- `openclaw/plugin-sdk/compat` for bundled/internal plugin code that needs broader shared runtime helpers than `core`.
|
||||
- `openclaw/plugin-sdk/telegram` for Telegram channel plugins.
|
||||
- `openclaw/plugin-sdk/discord` for Discord channel plugins.
|
||||
- `openclaw/plugin-sdk/slack` for Slack channel plugins.
|
||||
- `openclaw/plugin-sdk/signal` for Signal channel plugins.
|
||||
- `openclaw/plugin-sdk/imessage` for iMessage channel plugins.
|
||||
- `openclaw/plugin-sdk/whatsapp` for WhatsApp channel plugins.
|
||||
- `openclaw/plugin-sdk/telegram` for Telegram channel plugin types and shared channel-facing helpers. Built-in Telegram implementation internals stay private to the bundled extension.
|
||||
- `openclaw/plugin-sdk/discord` for Discord channel plugin types and shared channel-facing helpers. Built-in Discord implementation internals stay private to the bundled extension.
|
||||
- `openclaw/plugin-sdk/slack` for Slack channel plugin types and shared channel-facing helpers. Built-in Slack implementation internals stay private to the bundled extension.
|
||||
- `openclaw/plugin-sdk/signal` for Signal channel plugin types and shared channel-facing helpers. Built-in Signal implementation internals stay private to the bundled extension.
|
||||
- `openclaw/plugin-sdk/imessage` for iMessage channel plugin types and shared channel-facing helpers. Built-in iMessage implementation internals stay private to the bundled extension.
|
||||
- `openclaw/plugin-sdk/whatsapp` for WhatsApp channel plugin types and shared channel-facing helpers. Built-in WhatsApp implementation internals stay private to the bundled extension.
|
||||
- `openclaw/plugin-sdk/line` for LINE channel plugins.
|
||||
- `openclaw/plugin-sdk/msteams` for the bundled Microsoft Teams plugin surface.
|
||||
- Bundled extension-specific subpaths are also available:
|
||||
@ -1181,7 +1219,7 @@ A provider plugin can participate in five distinct phases:
|
||||
without prompts. Use this when the provider needs custom headless setup
|
||||
beyond the built-in simple API-key paths.
|
||||
3. **Wizard integration**
|
||||
`wizard.onboarding` adds an entry to `openclaw onboard`.
|
||||
`wizard.setup` adds an entry to `openclaw onboard`.
|
||||
`wizard.modelPicker` adds a setup entry to the model picker.
|
||||
4. **Implicit discovery**
|
||||
`discovery.run(ctx)` can contribute provider config automatically during
|
||||
@ -1230,7 +1268,8 @@ The non-interactive context includes:
|
||||
- the current and base config
|
||||
- parsed onboarding CLI options
|
||||
- runtime logging/error helpers
|
||||
- agent/workspace dirs
|
||||
- agent/workspace dirs so the provider can persist auth into the same scoped
|
||||
store used by the rest of onboarding
|
||||
- `resolveApiKey(...)` to read provider keys from flags, env, or existing auth
|
||||
profiles while honoring `--secret-input-mode`
|
||||
- `toApiKeyCredential(...)` to convert a resolved key into an auth-profile
|
||||
@ -1247,7 +1286,17 @@ errors instead.
|
||||
|
||||
### Provider wizard metadata
|
||||
|
||||
`wizard.onboarding` controls how the provider appears in grouped onboarding:
|
||||
Provider auth/onboarding metadata can live in two layers:
|
||||
|
||||
- manifest `providerAuthChoices`: cheap labels, grouping, `--auth-choice`
|
||||
ids, and simple CLI flag metadata available before runtime load
|
||||
- runtime `wizard.setup` / `auth[].wizard`: richer behavior that depends on
|
||||
loaded provider code
|
||||
|
||||
Use manifest metadata for static labels/flags. Use runtime wizard metadata when
|
||||
setup depends on dynamic auth methods, method fallback, or runtime validation.
|
||||
|
||||
`wizard.setup` controls how the provider appears in grouped onboarding:
|
||||
|
||||
- `choiceId`: auth-choice value
|
||||
- `choiceLabel`: option label
|
||||
@ -1256,6 +1305,7 @@ errors instead.
|
||||
- `groupLabel`: group label
|
||||
- `groupHint`: group hint
|
||||
- `methodId`: auth method to run
|
||||
- `modelAllowlist`: optional post-auth allowlist policy (`allowedKeys`, `initialSelections`, `message`)
|
||||
|
||||
`wizard.modelPicker` controls how a provider appears as a "set this up now"
|
||||
entry in model selection:
|
||||
@ -1377,7 +1427,7 @@ api.registerProvider({
|
||||
},
|
||||
],
|
||||
wizard: {
|
||||
onboarding: {
|
||||
setup: {
|
||||
choiceId: "acme",
|
||||
choiceLabel: "AcmeAI",
|
||||
groupId: "acme",
|
||||
@ -1407,14 +1457,22 @@ api.registerProvider({
|
||||
Notes:
|
||||
|
||||
- `run` receives a `ProviderAuthContext` with `prompter`, `runtime`,
|
||||
`openUrl`, and `oauth.createVpsAwareHandlers` helpers.
|
||||
`openUrl`, `oauth.createVpsAwareHandlers`, `secretInputMode`, and
|
||||
`allowSecretRefPrompt` helpers/state. Onboarding/configure flows can use
|
||||
these to honor `--secret-input-mode` or offer env/file/exec secret-ref
|
||||
capture, while `openclaw models auth` keeps a tighter prompt surface.
|
||||
- `runNonInteractive` receives a `ProviderAuthMethodNonInteractiveContext`
|
||||
with `opts`, `resolveApiKey`, and `toApiKeyCredential` helpers for
|
||||
headless onboarding.
|
||||
with `opts`, `agentDir`, `resolveApiKey`, and `toApiKeyCredential` helpers
|
||||
for headless onboarding.
|
||||
- Return `configPatch` when you need to add default models or provider config.
|
||||
- Return `defaultModel` so `--set-default` can update agent defaults.
|
||||
- `wizard.onboarding` adds a provider choice to `openclaw onboard`.
|
||||
- `wizard.setup` adds a provider choice to onboarding surfaces such as
|
||||
`openclaw onboard` / `openclaw setup --wizard`.
|
||||
- `wizard.setup.modelAllowlist` lets the provider narrow the follow-up model
|
||||
allowlist prompt during onboarding/configure.
|
||||
- `wizard.modelPicker` adds a “setup this provider” entry to the model picker.
|
||||
- `deprecatedProfileIds` lets the provider own `openclaw doctor` cleanup for
|
||||
retired auth-profile ids.
|
||||
- `discovery.run` returns either `{ provider }` for the plugin’s own provider id
|
||||
or `{ providers }` for multi-provider discovery.
|
||||
- `discovery.order` controls when the provider runs relative to built-in
|
||||
|
||||
@ -28,7 +28,7 @@ Auth is supplied during the WebSocket handshake via:
|
||||
- `connect.params.auth.token`
|
||||
- `connect.params.auth.password`
|
||||
The dashboard settings panel keeps a token for the current browser tab session and selected gateway URL; passwords are not persisted.
|
||||
The onboarding wizard generates a gateway token by default, so paste it here on first connect.
|
||||
The setup wizard generates a gateway token by default, so paste it here on first connect.
|
||||
|
||||
## Device pairing (first connection)
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -6,34 +6,35 @@ read_when:
|
||||
summary: 通过 BlueBubbles macOS 服务器使用 iMessage（REST 发送/接收、输入状态、回应、配对、高级操作）。
|
||||
title: BlueBubbles
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T10:04:52Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 3aae277a8bec479800a7f6268bfbca912c65a4aadc6e513694057fb873597b69
|
||||
generated_at: "2026-03-16T06:21:08Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 877592bf7b9b06abdddd7567d56e756eff229d6ffa5056ef33fa3356086aa580
|
||||
source_path: channels/bluebubbles.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# BlueBubbles（macOS REST）
|
||||
|
||||
状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。由于其更丰富的 API 和更简便的设置，**推荐用于 iMessage 集成**，优于旧版 imsg 渠道。
|
||||
状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。由于其 API 更丰富且设置比旧版 imsg 渠道更简单，**推荐用于 iMessage 集成**。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
- 通过 BlueBubbles 辅助应用在 macOS 上运行（[bluebubbles.app](https://bluebubbles.app)）。
|
||||
- 推荐/已测试版本：macOS Sequoia (15)。macOS Tahoe (26) 可用；但在 Tahoe 上编辑功能目前不可用，群组图标更新可能显示成功但实际未同步。
|
||||
- OpenClaw 通过其 REST API 与之通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。
|
||||
- 传入消息通过 webhook 到达；发出的回复、输入指示器、已读回执和 tapback 均为 REST 调用。
|
||||
- 附件和贴纸作为入站媒体被接收（并在可能时呈现给智能体）。
|
||||
- 配对/白名单的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
|
||||
- 回应作为系统事件呈现，与 Slack/Telegram 类似，智能体可以在回复前"提及"它们。
|
||||
- 推荐/已测试：macOS Sequoia（15）。macOS Tahoe（26）可用；目前编辑功能在 Tahoe 上已损坏，群组图标更新可能会报告成功但不会同步。
|
||||
- OpenClaw 通过其 REST API 与其通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。
|
||||
- 传入消息通过 webhook 到达；传出回复、输入状态指示、已读回执和 tapback 都通过 REST 调用完成。
|
||||
- 附件和贴纸会作为入站媒体接收（并在可能时展示给智能体）。
|
||||
- 配对/allowlist 的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
|
||||
- 回应会像 Slack/Telegram 一样作为系统事件呈现，因此智能体可以在回复前“提及”它们。
|
||||
- 高级功能：编辑、撤回、回复线程、消息效果、群组管理。
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. 在你的 Mac 上安装 BlueBubbles 服务器（按照 [bluebubbles.app/install](https://bluebubbles.app/install) 的说明操作）。
|
||||
2. 在 BlueBubbles 配置中，启用 web API 并设置密码。
|
||||
1. 在你的 Mac 上安装 BlueBubbles 服务器（按照 [bluebubbles.app/install](https://bluebubbles.app/install) 上的说明操作）。
|
||||
2. 在 BlueBubbles 配置中启用 Web API 并设置密码。
|
||||
3. 运行 `openclaw onboard` 并选择 BlueBubbles，或手动配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
@ -46,8 +47,89 @@ x-i18n:
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
4. 将 BlueBubbles webhook 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）。
|
||||
5. 启动 Gateway 网关；它将注册 webhook 处理程序并开始配对。
|
||||
5. 启动 Gateway 网关；它会注册 webhook 处理器并开始配对。
|
||||
|
||||
安全说明：
|
||||
|
||||
- 始终设置 webhook 密码。
|
||||
- 始终要求进行 webhook 身份验证。无论 loopback/代理拓扑如何，除非 BlueBubbles webhook 请求包含与 `channels.bluebubbles.password` 匹配的 password/guid（例如 `?password=<password>` 或 `x-password`），否则 OpenClaw 会拒绝该请求。
|
||||
- 在读取/解析完整 webhook 请求体之前就会检查密码身份验证。
|
||||
|
||||
## 保持 Messages.app 处于活动状态（VM / 无头设置）
|
||||
|
||||
某些 macOS VM / 常开设置可能会导致 Messages.app 进入“空闲”状态（传入事件会停止，直到应用被打开/切到前台）。一个简单的解决方法是使用 AppleScript + LaunchAgent **每 5 分钟“触碰”一次 Messages**。
|
||||
|
||||
### 1）保存 AppleScript
|
||||
|
||||
将以下内容保存为：
|
||||
|
||||
- `~/Scripts/poke-messages.scpt`
|
||||
|
||||
示例脚本（非交互式；不会抢占焦点）：
|
||||
|
||||
```applescript
|
||||
try
|
||||
tell application "Messages"
|
||||
if not running then
|
||||
launch
|
||||
end if
|
||||
|
||||
-- Touch the scripting interface to keep the process responsive.
|
||||
set _chatCount to (count of chats)
|
||||
end tell
|
||||
on error
|
||||
-- Ignore transient failures (first-run prompts, locked session, etc).
|
||||
end try
|
||||
```
|
||||
|
||||
### 2）安装 LaunchAgent
|
||||
|
||||
将以下内容保存为：
|
||||
|
||||
- `~/Library/LaunchAgents/com.user.poke-messages.plist`
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>com.user.poke-messages</string>
|
||||
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/bin/bash</string>
|
||||
<string>-lc</string>
|
||||
<string>/usr/bin/osascript "$HOME/Scripts/poke-messages.scpt"</string>
|
||||
</array>
|
||||
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
|
||||
<key>StartInterval</key>
|
||||
<integer>300</integer>
|
||||
|
||||
<key>StandardOutPath</key>
|
||||
<string>/tmp/poke-messages.log</string>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/tmp/poke-messages.err</string>
|
||||
</dict>
|
||||
</plist>
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 这会**每 300 秒**运行一次，并且**在登录时**运行。
|
||||
- 首次运行可能会触发 macOS 的**自动化**权限提示（`osascript` → Messages）。请在运行该 LaunchAgent 的同一用户会话中批准这些提示。
|
||||
|
||||
加载它：
|
||||
|
||||
```bash
|
||||
launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
|
||||
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
|
||||
```
|
||||
|
||||
## 新手引导
|
||||
|
||||
@ -60,10 +142,10 @@ openclaw onboard
|
||||
向导会提示输入：
|
||||
|
||||
- **服务器 URL**（必填）：BlueBubbles 服务器地址（例如 `http://192.168.1.100:1234`）
|
||||
- **密码**（必填）：来自 BlueBubbles 服务器设置的 API 密码
|
||||
- **密码**（必填）：来自 BlueBubbles Server 设置的 API 密码
|
||||
- **Webhook 路径**（可选）：默认为 `/bluebubbles-webhook`
|
||||
- **私信策略**：配对、白名单、开放或禁用
|
||||
- **白名单**：电话号码、电子邮件或聊天目标
|
||||
- **私信策略**：pairing、allowlist、open 或 disabled
|
||||
- **允许列表**：电话号码、电子邮件或聊天目标
|
||||
|
||||
你也可以通过 CLI 添加 BlueBubbles：
|
||||
|
||||
@ -75,12 +157,12 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
|
||||
|
||||
私信：
|
||||
|
||||
- 默认：`channels.bluebubbles.dmPolicy = "pairing"`。
|
||||
- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。
|
||||
- 批准方式：
|
||||
- 默认值：`channels.bluebubbles.dmPolicy = "pairing"`。
|
||||
- 未知发送者会收到一个配对码；在获得批准前，消息会被忽略（代码 1 小时后过期）。
|
||||
- 通过以下方式批准：
|
||||
- `openclaw pairing list bluebubbles`
|
||||
- `openclaw pairing approve bluebubbles <CODE>`
|
||||
- 配对是默认的令牌交换方式。详情：[配对](/channels/pairing)
|
||||
- 配对是默认的令牌交换方式。详情见：[配对](/channels/pairing)
|
||||
|
||||
群组：
|
||||
|
||||
@ -89,13 +171,13 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
|
||||
|
||||
### 提及门控（群组）
|
||||
|
||||
BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
|
||||
BlueBubbles 支持群聊中的提及门控，与 iMessage/WhatsApp 的行为一致：
|
||||
|
||||
- 使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）检测提及。
|
||||
- 当群组启用 `requireMention` 时，智能体仅在被提及时响应。
|
||||
- 当某个群组启用 `requireMention` 时，智能体只有在被提及时才会响应。
|
||||
- 来自授权发送者的控制命令会绕过提及门控。
|
||||
|
||||
单群组配置：
|
||||
每群组配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -104,8 +186,8 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
|
||||
groupPolicy: "allowlist",
|
||||
groupAllowFrom: ["+15555550123"],
|
||||
groups: {
|
||||
"*": { requireMention: true }, // 所有群组的默认设置
|
||||
"iMessage;-;chat123": { requireMention: false }, // 特定群组的覆盖设置
|
||||
"*": { requireMention: true }, // 所有群组的默认值
|
||||
"iMessage;-;chat123": { requireMention: false }, // 对特定群组覆盖
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -115,14 +197,14 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
|
||||
### 命令门控
|
||||
|
||||
- 控制命令（例如 `/config`、`/model`）需要授权。
|
||||
- 使用 `allowFrom` 和 `groupAllowFrom` 确定命令授权。
|
||||
- 授权发送者即使在群组中未被提及也可以运行控制命令。
|
||||
- 使用 `allowFrom` 和 `groupAllowFrom` 来判断命令授权。
|
||||
- 授权发送者即使在群组中未提及，也可以运行控制命令。
|
||||
|
||||
## 输入状态 + 已读回执
|
||||
|
||||
- **输入指示器**：在响应生成前和生成期间自动发送。
|
||||
- **输入状态指示**：会在生成响应之前和期间自动发送。
|
||||
- **已读回执**：由 `channels.bluebubbles.sendReadReceipts` 控制（默认：`true`）。
|
||||
- **输入指示器**：OpenClaw 发送输入开始事件；BlueBubbles 在发送或超时时自动清除输入状态（通过 DELETE 手动停止不可靠）。
|
||||
- **输入状态指示**：OpenClaw 会发送输入开始事件；BlueBubbles 会在发送后或超时后自动清除输入状态（通过 DELETE 手动停止并不可靠）。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -136,7 +218,7 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
|
||||
|
||||
## 高级操作
|
||||
|
||||
BlueBubbles 在配置中启用时支持高级消息操作：
|
||||
在配置中启用后，BlueBubbles 支持高级消息操作：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -144,15 +226,15 @@ BlueBubbles 在配置中启用时支持高级消息操作：
|
||||
bluebubbles: {
|
||||
actions: {
|
||||
reactions: true, // tapback（默认：true）
|
||||
edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上不可用）
|
||||
edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上已损坏）
|
||||
unsend: true, // 撤回消息（macOS 13+）
|
||||
reply: true, // 通过消息 GUID 进行回复线程
|
||||
reply: true, // 按消息 GUID 回复线程
|
||||
sendWithEffect: true, // 消息效果（slam、loud 等）
|
||||
renameGroup: true, // 重命名群聊
|
||||
setGroupIcon: true, // 设置群聊图标/照片（在 macOS 26 Tahoe 上不稳定）
|
||||
addParticipant: true, // 将参与者添加到群组
|
||||
addParticipant: true, // 向群组添加参与者
|
||||
removeParticipant: true, // 从群组移除参与者
|
||||
leaveGroup: true, // 离开群聊
|
||||
leaveGroup: true, // 退出群聊
|
||||
sendAttachment: true, // 发送附件/媒体
|
||||
},
|
||||
},
|
||||
@ -163,37 +245,37 @@ BlueBubbles 在配置中启用时支持高级消息操作：
|
||||
可用操作：
|
||||
|
||||
- **react**：添加/移除 tapback 回应（`messageId`、`emoji`、`remove`）
|
||||
- **edit**：编辑已发送的消息（`messageId`、`text`）
|
||||
- **edit**：编辑已发送消息（`messageId`、`text`）
|
||||
- **unsend**：撤回消息（`messageId`）
|
||||
- **reply**：回复特定消息（`messageId`、`text`、`to`）
|
||||
- **sendWithEffect**：带 iMessage 效果发送（`text`、`to`、`effectId`）
|
||||
- **renameGroup**：重命名群聊（`chatGuid`、`displayName`）
|
||||
- **setGroupIcon**：设置群聊图标/照片（`chatGuid`、`media`）— 在 macOS 26 Tahoe 上不稳定（API 可能返回成功但图标未同步）。
|
||||
- **addParticipant**：将某人添加到群组（`chatGuid`、`address`）
|
||||
- **removeParticipant**：将某人从群组移除（`chatGuid`、`address`）
|
||||
- **leaveGroup**：离开群聊（`chatGuid`）
|
||||
- **setGroupIcon**：设置群聊图标/照片（`chatGuid`、`media`）——在 macOS 26 Tahoe 上不稳定（API 可能返回成功，但图标不会同步）。
|
||||
- **addParticipant**：向群组添加某人（`chatGuid`、`address`）
|
||||
- **removeParticipant**：从群组移除某人（`chatGuid`、`address`）
|
||||
- **leaveGroup**：退出群聊（`chatGuid`）
|
||||
- **sendAttachment**：发送媒体/文件（`to`、`buffer`、`filename`、`asVoice`）
|
||||
- 语音备忘录：将 `asVoice: true` 与 **MP3** 或 **CAF** 音频一起设置，以 iMessage 语音消息形式发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。
|
||||
- 语音备忘录：将 `asVoice: true` 与 **MP3** 或 **CAF** 音频一起设置，即可作为 iMessage 语音消息发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。
|
||||
|
||||
### 消息 ID（短格式 vs 完整格式）
|
||||
### 消息 ID（短 ID 与完整 ID）
|
||||
|
||||
OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
|
||||
|
||||
- `MessageSid` / `ReplyToId` 可以是短 ID。
|
||||
- `MessageSidFull` / `ReplyToIdFull` 包含提供商的完整 ID。
|
||||
- 短 ID 存储在内存中；它们可能在重启或缓存清除后过期。
|
||||
- 操作接受短或完整的 `messageId`，但如果短 ID 不再可用将会报错。
|
||||
- 短 ID 存在于内存中；它们可能会在重启或缓存清除后失效。
|
||||
- 操作接受短或完整 `messageId`，但如果短 ID 不再可用，就会报错。
|
||||
|
||||
对于持久化自动化和存储，请使用完整 ID：
|
||||
|
||||
- 模板：`{{MessageSidFull}}`、`{{ReplyToIdFull}}`
|
||||
- 上下文：入站负载中的 `MessageSidFull` / `ReplyToIdFull`
|
||||
|
||||
参见[配置](/gateway/configuration)了解模板变量。
|
||||
模板变量请参见[配置](/gateway/configuration)。
|
||||
|
||||
## 分块流式传输
|
||||
|
||||
控制响应是作为单条消息发送还是分块流式传输：
|
||||
控制响应是作为单条消息发送，还是按块流式发送：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -208,8 +290,8 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
|
||||
## 媒体 + 限制
|
||||
|
||||
- 入站附件会被下载并存储在媒体缓存中。
|
||||
- 媒体上限通过 `channels.bluebubbles.mediaMaxMb` 设置（默认：8 MB）。
|
||||
- 出站文本按 `channels.bluebubbles.textChunkLimit` 分块（默认：4000 字符）。
|
||||
- 通过 `channels.bluebubbles.mediaMaxMb` 控制入站和出站媒体大小上限（默认：8 MB）。
|
||||
- 出站文本会按 `channels.bluebubbles.textChunkLimit` 分块（默认：4000 个字符）。
|
||||
|
||||
## 配置参考
|
||||
|
||||
@ -217,22 +299,23 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
|
||||
|
||||
提供商选项：
|
||||
|
||||
- `channels.bluebubbles.enabled`：启用/禁用渠道。
|
||||
- `channels.bluebubbles.enabled`：启用/禁用该渠道。
|
||||
- `channels.bluebubbles.serverUrl`：BlueBubbles REST API 基础 URL。
|
||||
- `channels.bluebubbles.password`：API 密码。
|
||||
- `channels.bluebubbles.webhookPath`：Webhook 端点路径（默认：`/bluebubbles-webhook`）。
|
||||
- `channels.bluebubbles.dmPolicy`：`pairing | allowlist | open | disabled`（默认：`pairing`）。
|
||||
- `channels.bluebubbles.allowFrom`：私信白名单（句柄、电子邮件、E.164 号码、`chat_id:*`、`chat_guid:*`）。
|
||||
- `channels.bluebubbles.allowFrom`：私信 allowlist（handle、电子邮件、E.164 号码、`chat_id:*`、`chat_guid:*`）。
|
||||
- `channels.bluebubbles.groupPolicy`：`open | allowlist | disabled`（默认：`allowlist`）。
|
||||
- `channels.bluebubbles.groupAllowFrom`：群组发送者白名单。
|
||||
- `channels.bluebubbles.groups`：单群组配置（`requireMention` 等）。
|
||||
- `channels.bluebubbles.groupAllowFrom`：群组发送者 allowlist。
|
||||
- `channels.bluebubbles.groups`：每群组配置（`requireMention` 等）。
|
||||
- `channels.bluebubbles.sendReadReceipts`：发送已读回执（默认：`true`）。
|
||||
- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`false`；流式回复必需）。
|
||||
- `channels.bluebubbles.textChunkLimit`：出站分块大小（字符）（默认：4000）。
|
||||
- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在长度分块前先按空行（段落边界）分割。
|
||||
- `channels.bluebubbles.mediaMaxMb`：入站媒体上限（MB）（默认：8）。
|
||||
- `channels.bluebubbles.historyLimit`：上下文的最大群组消息数（0 表示禁用）。
|
||||
- `channels.bluebubbles.dmHistoryLimit`：私信历史限制。
|
||||
- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`false`；流式回复所必需）。
|
||||
- `channels.bluebubbles.textChunkLimit`：出站分块大小（按字符计，默认：4000）。
|
||||
- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时拆分；`newline` 会先按空行（段落边界）拆分，再按长度分块。
|
||||
- `channels.bluebubbles.mediaMaxMb`：入站/出站媒体大小上限（MB，默认：8）。
|
||||
- `channels.bluebubbles.mediaLocalRoots`：允许用于出站本地媒体路径的绝对本地目录显式 allowlist。默认情况下，本地路径发送会被拒绝，除非配置了此项。每账户覆盖：`channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`。
|
||||
- `channels.bluebubbles.historyLimit`：用于上下文的最大群组消息数（0 表示禁用）。
|
||||
- `channels.bluebubbles.dmHistoryLimit`：私信历史记录上限。
|
||||
- `channels.bluebubbles.actions`：启用/禁用特定操作。
|
||||
- `channels.bluebubbles.accounts`：多账户配置。
|
||||
|
||||
@ -241,31 +324,31 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
|
||||
- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）。
|
||||
- `messages.responsePrefix`。
|
||||
|
||||
## 地址 / 投递目标
|
||||
## 寻址 / 送达目标
|
||||
|
||||
优先使用 `chat_guid` 以获得稳定的路由：
|
||||
优先使用 `chat_guid` 以获得稳定路由：
|
||||
|
||||
- `chat_guid:iMessage;-;+15555550123`（群组推荐）
|
||||
- `chat_guid:iMessage;-;+15555550123`（群组首选）
|
||||
- `chat_id:123`
|
||||
- `chat_identifier:...`
|
||||
- 直接句柄：`+15555550123`、`user@example.com`
|
||||
- 如果直接句柄没有现有的私信聊天，OpenClaw 将通过 `POST /api/v1/chat/new` 创建一个。这需要启用 BlueBubbles Private API。
|
||||
- 直接 handle：`+15555550123`、`user@example.com`
|
||||
- 如果某个直接 handle 没有现有私信聊天，OpenClaw 会通过 `POST /api/v1/chat/new` 创建一个。这要求启用 BlueBubbles Private API。
|
||||
|
||||
## 安全性
|
||||
## 安全
|
||||
|
||||
- Webhook 请求通过比较 `guid`/`password` 查询参数或头部与 `channels.bluebubbles.password` 进行身份验证。来自 `localhost` 的请求也会被接受。
|
||||
- 保持 API 密码和 webhook 端点的机密性（将它们视为凭证）。
|
||||
- localhost 信任意味着同主机的反向代理可能无意中绕过密码验证。如果你使用代理 Gateway 网关，请在代理处要求身份验证并配置 `gateway.trustedProxies`。参见 [Gateway 网关安全性](/gateway/security#reverse-proxy-configuration)。
|
||||
- 如果将 BlueBubbles 服务器暴露在局域网之外，请启用 HTTPS + 防火墙规则。
|
||||
- 通过将查询参数或请求头中的 `guid`/`password` 与 `channels.bluebubbles.password` 进行比较来验证 webhook 请求。来自 `localhost` 的请求也会被接受。
|
||||
- 请妥善保管 API 密码和 webhook 端点（将它们视为凭证）。
|
||||
- 对 localhost 的信任意味着同主机上的反向代理可能会无意中绕过密码。如果你对 Gateway 网关进行了代理，请在代理层要求身份验证，并配置 `gateway.trustedProxies`。请参见 [Gateway 网关安全](/gateway/security#reverse-proxy-configuration)。
|
||||
- 如果要在局域网外暴露 BlueBubbles 服务器，请启用 HTTPS + 防火墙规则。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- 如果输入/已读事件停止工作，请检查 BlueBubbles webhook 日志并验证 Gateway 网关路径是否与 `channels.bluebubbles.webhookPath` 匹配。
|
||||
- 配对码在一小时后过期；使用 `openclaw pairing list bluebubbles` 和 `openclaw pairing approve bluebubbles <code>`。
|
||||
- 回应需要 BlueBubbles private API（`POST /api/v1/message/react`）；确保服务器版本支持它。
|
||||
- 编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑功能目前不可用。
|
||||
- 在 macOS 26（Tahoe）上群组图标更新可能不稳定：API 可能返回成功但新图标未同步。
|
||||
- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果在 macOS 26（Tahoe）上编辑仍然显示，请使用 `channels.bluebubbles.actions.edit=false` 手动禁用。
|
||||
- 查看状态/健康信息：`openclaw status --all` 或 `openclaw status --deep`。
|
||||
- 如果输入状态/已读事件停止工作，请检查 BlueBubbles webhook 日志，并验证 Gateway 网关路径与 `channels.bluebubbles.webhookPath` 一致。
|
||||
- 配对码会在一小时后过期；使用 `openclaw pairing list bluebubbles` 和 `openclaw pairing approve bluebubbles <code>`。
|
||||
- 回应需要 BlueBubbles private API（`POST /api/v1/message/react`）；请确保服务器版本提供该接口。
|
||||
- 编辑/撤回需要 macOS 13+ 以及兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑功能目前已损坏。
|
||||
- 群组图标更新在 macOS 26（Tahoe）上可能不稳定：API 可能返回成功，但新图标不会同步。
|
||||
- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知损坏的操作。如果在 macOS 26（Tahoe）上仍显示编辑操作，请手动使用 `channels.bluebubbles.actions.edit=false` 禁用它。
|
||||
- 状态/健康信息请使用：`openclaw status --all` 或 `openclaw status --deep`。
|
||||
|
||||
有关通用渠道工作流参考，请参阅[渠道](/channels)和[插件](/tools/plugin)指南。
|
||||
有关通用渠道工作流程参考，请参见 [Channels](/channels) 和 [Plugins](/tools/plugin) 指南。
|
||||
|
||||
@ -1,22 +1,29 @@
|
||||
---
|
||||
summary: "飞书机器人支持状态、功能和配置"
|
||||
read_when:
|
||||
- 您想要连接飞书机器人
|
||||
- 您正在配置飞书渠道
|
||||
- 你想连接一个飞书/Lark 机器人
|
||||
- 你正在配置飞书渠道
|
||||
summary: 飞书机器人概览、功能和配置
|
||||
title: 飞书
|
||||
x-i18n:
|
||||
generated_at: "2026-03-16T06:21:11Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 951e78c5c7264471382f863fa896a15ddeaf0717ef782da20d0f1b3eb23396ba
|
||||
source_path: channels/feishu.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 飞书机器人
|
||||
|
||||
状态：生产就绪，支持机器人私聊和群组。使用 WebSocket 长连接模式接收消息。
|
||||
飞书（Lark）是企业用于消息沟通与协作的团队聊天平台。此插件通过平台的 WebSocket 事件订阅将 OpenClaw 连接到飞书/Lark 机器人，因此无需暴露公共 webhook URL 即可接收消息。
|
||||
|
||||
---
|
||||
|
||||
## 内置插件
|
||||
## 捆绑插件
|
||||
|
||||
当前版本的 OpenClaw 已内置 Feishu 插件，因此通常不需要单独安装。
|
||||
飞书随当前的 OpenClaw 版本一同捆绑提供，因此无需单独安装插件。
|
||||
|
||||
如果你使用的是较旧版本，或是没有内置 Feishu 的自定义安装，可手动安装：
|
||||
如果你使用的是较旧版本，或使用了不包含捆绑飞书的自定义安装，请手动安装：
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/feishu
|
||||
@ -26,75 +33,75 @@ openclaw plugins install @openclaw/feishu
|
||||
|
||||
## 快速开始
|
||||
|
||||
添加飞书渠道有两种方式：
|
||||
有两种方式可添加飞书渠道：
|
||||
|
||||
### 方式一：通过安装向导添加（推荐）
|
||||
### 方法 1：设置向导（推荐）
|
||||
|
||||
如果您刚安装完 OpenClaw，可以直接运行向导，根据提示添加飞书：
|
||||
如果你刚安装 OpenClaw，请运行设置向导：
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
向导会引导您完成：
|
||||
向导会引导你完成以下步骤：
|
||||
|
||||
1. 创建飞书应用并获取凭证
|
||||
2. 配置应用凭证
|
||||
3. 启动网关
|
||||
1. 创建飞书应用并收集凭证
|
||||
2. 在 OpenClaw 中配置应用凭证
|
||||
3. 启动 Gateway 网关
|
||||
|
||||
✅ **完成配置后**，您可以使用以下命令检查网关状态：
|
||||
✅ **配置完成后**，检查 Gateway 网关状态：
|
||||
|
||||
- `openclaw gateway status` - 查看网关运行状态
|
||||
- `openclaw logs --follow` - 查看实时日志
|
||||
- `openclaw gateway status`
|
||||
- `openclaw logs --follow`
|
||||
|
||||
### 方式二：通过命令行添加
|
||||
### 方法 2：CLI 设置
|
||||
|
||||
如果您已经完成了初始安装，可以用以下命令添加飞书渠道：
|
||||
如果你已经完成初始安装，可通过 CLI 添加该渠道：
|
||||
|
||||
```bash
|
||||
openclaw channels add
|
||||
```
|
||||
|
||||
然后根据交互式提示选择 Feishu，输入 App ID 和 App Secret 即可。
|
||||
选择 **Feishu**，然后输入 App ID 和 App Secret。
|
||||
|
||||
✅ **完成配置后**，您可以使用以下命令管理网关：
|
||||
✅ **配置完成后**，管理 Gateway 网关：
|
||||
|
||||
- `openclaw gateway status` - 查看网关运行状态
|
||||
- `openclaw gateway restart` - 重启网关以应用新配置
|
||||
- `openclaw logs --follow` - 查看实时日志
|
||||
- `openclaw gateway status`
|
||||
- `openclaw gateway restart`
|
||||
- `openclaw logs --follow`
|
||||
|
||||
---
|
||||
|
||||
## 第一步：创建飞书应用
|
||||
## 第 1 步：创建飞书应用
|
||||
|
||||
### 1. 打开飞书开放平台
|
||||
|
||||
访问 [飞书开放平台](https://open.feishu.cn/app)，使用飞书账号登录。
|
||||
访问 [Feishu Open Platform](https://open.feishu.cn/app) 并登录。
|
||||
|
||||
Lark（国际版）请使用 https://open.larksuite.com/app，并在配置中设置 `domain: "lark"`。
|
||||
Lark（国际版）租户应使用 [https://open.larksuite.com/app](https://open.larksuite.com/app)，并在飞书配置中设置 `domain: "lark"`。
|
||||
|
||||
### 2. 创建应用
|
||||
|
||||
1. 点击 **创建企业自建应用**
|
||||
1. 点击 **Create enterprise app**
|
||||
2. 填写应用名称和描述
|
||||
3. 选择应用图标
|
||||
|
||||
|
||||
|
||||
|
||||
### 3. 获取应用凭证
|
||||
### 3. 复制凭证
|
||||
|
||||
在应用的 **凭证与基础信息** 页面，复制：
|
||||
在 **Credentials & Basic Info** 中，复制：
|
||||
|
||||
- **App ID**（格式如 `cli_xxx`）
|
||||
- **App ID**（格式：`cli_xxx`）
|
||||
- **App Secret**
|
||||
|
||||
❗ **重要**：请妥善保管 App Secret，不要分享给他人。
|
||||
❗ **重要：**请将 App Secret 妥善保密。
|
||||
|
||||
|
||||
|
||||
|
||||
### 4. 配置应用权限
|
||||
### 4. 配置权限
|
||||
|
||||
在 **权限管理** 页面，点击 **批量导入** 按钮，粘贴以下 JSON 配置一键导入所需权限：
|
||||
在 **Permissions** 中，点击 **Batch import** 并粘贴：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -105,81 +112,71 @@ Lark（国际版）请使用 https://open.larksuite.com/app，并在配置中设
|
||||
"application:application.app_message_stats.overview:readonly",
|
||||
"application:application:self_manage",
|
||||
"application:bot.menu:write",
|
||||
"cardkit:card:read",
|
||||
"cardkit:card:write",
|
||||
"contact:user.employee_id:readonly",
|
||||
"corehr:file:download",
|
||||
"docs:document.content:read",
|
||||
"event:ip_list",
|
||||
"im:chat",
|
||||
"im:chat.access_event.bot_p2p_chat:read",
|
||||
"im:chat.members:bot_access",
|
||||
"im:message",
|
||||
"im:message.group_at_msg:readonly",
|
||||
"im:message.group_msg",
|
||||
"im:message.p2p_msg:readonly",
|
||||
"im:message:readonly",
|
||||
"im:message:send_as_bot",
|
||||
"im:resource",
|
||||
"sheets:spreadsheet",
|
||||
"wiki:wiki:readonly"
|
||||
"im:resource"
|
||||
],
|
||||
"user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
### 5. 启用机器人能力
|
||||
|
||||
在 **应用能力** > **机器人** 页面：
|
||||
在 **App Capability** > **Bot** 中：
|
||||
|
||||
1. 开启机器人能力
|
||||
2. 配置机器人名称
|
||||
1. 启用机器人能力
|
||||
2. 设置机器人名称
|
||||
|
||||
|
||||
|
||||
|
||||
### 6. 配置事件订阅
|
||||
|
||||
⚠️ **重要提醒**：在配置事件订阅前，请务必确保已完成以下步骤：
|
||||
⚠️ **重要：**在设置事件订阅前，请确保：
|
||||
|
||||
1. 运行 `openclaw channels add` 添加了 Feishu 渠道
|
||||
2. 网关处于启动状态（可通过 `openclaw gateway status` 检查状态）
|
||||
1. 你已经为飞书运行过 `openclaw channels add`
|
||||
2. Gateway 网关正在运行（`openclaw gateway status`）
|
||||
|
||||
在 **事件订阅** 页面：
|
||||
在 **Event Subscription** 中：
|
||||
|
||||
1. 选择 **使用长连接接收事件**（WebSocket 模式）
|
||||
2. 添加事件：
|
||||
- `im.message.receive_v1`
|
||||
- `im.message.reaction.created_v1`
|
||||
- `im.message.reaction.deleted_v1`
|
||||
- `application.bot.menu_v6`
|
||||
1. 选择 **Use long connection to receive events**（WebSocket）
|
||||
2. 添加事件：`im.message.receive_v1`
|
||||
|
||||
⚠️ **注意**：如果网关未启动或渠道未添加，长连接设置将保存失败。
|
||||
⚠️ 如果 Gateway 网关未运行，长连接设置可能无法保存。
|
||||
|
||||
|
||||
|
||||
|
||||
### 7. 发布应用
|
||||
|
||||
1. 在 **版本管理与发布** 页面创建版本
|
||||
1. 在 **Version Management & Release** 中创建版本
|
||||
2. 提交审核并发布
|
||||
3. 等待管理员审批（企业自建应用通常自动通过）
|
||||
3. 等待管理员批准（企业应用通常会自动批准）
|
||||
|
||||
---
|
||||
|
||||
## 第二步：配置 OpenClaw
|
||||
## 第 2 步：配置 OpenClaw
|
||||
|
||||
### 通过向导配置（推荐）
|
||||
|
||||
运行以下命令，根据提示粘贴 App ID 和 App Secret：
|
||||
### 使用向导配置（推荐）
|
||||
|
||||
```bash
|
||||
openclaw channels add
|
||||
```
|
||||
|
||||
选择 **Feishu**，然后输入您在第一步获取的凭证即可。
|
||||
选择 **Feishu**，然后粘贴你的 App ID 和 App Secret。
|
||||
|
||||
### 通过配置文件配置
|
||||
### 通过配置文件进行配置
|
||||
|
||||
编辑 `~/.openclaw/openclaw.json`：
|
||||
|
||||
@ -193,7 +190,7 @@ openclaw channels add
|
||||
main: {
|
||||
appId: "cli_xxx",
|
||||
appSecret: "xxx",
|
||||
botName: "我的AI助手",
|
||||
botName: "My AI assistant",
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -201,18 +198,20 @@ openclaw channels add
|
||||
}
|
||||
```
|
||||
|
||||
若使用 `connectionMode: "webhook"`，需设置 `verificationToken`。飞书 Webhook 服务默认绑定 `127.0.0.1`；仅在需要不同监听地址时设置 `webhookHost`。
|
||||
如果你使用 `connectionMode: "webhook"`，请同时设置 `verificationToken` 和 `encryptKey`。飞书 webhook 服务器默认绑定到 `127.0.0.1`；只有在你明确需要不同绑定地址时，才设置 `webhookHost`。
|
||||
|
||||
#### 获取 Verification Token（仅 Webhook 模式）
|
||||
#### Verification Token 和 Encrypt Key（webhook 模式）
|
||||
|
||||
使用 Webhook 模式时，需在配置中设置 `channels.feishu.verificationToken`。获取方式：
|
||||
使用 webhook 模式时，请在配置中同时设置 `channels.feishu.verificationToken` 和 `channels.feishu.encryptKey`。获取这些值的方法如下：
|
||||
|
||||
1. 在飞书开放平台打开您的应用
|
||||
2. 进入 **开发配置** → **事件与回调**
|
||||
3. 打开 **加密策略** 选项卡
|
||||
4. 复制 **Verification Token**（校验令牌）
|
||||
1. 在飞书开放平台中，打开你的应用
|
||||
2. 前往 **Development** → **Events & Callbacks**（开发配置 → 事件与回调）
|
||||
3. 打开 **Encryption** 标签页（加密策略）
|
||||
4. 复制 **Verification Token** 和 **Encrypt Key**
|
||||
|
||||
|
||||
下图展示了 **Verification Token** 的位置。**Encrypt Key** 位于同一个 **Encryption** 区域中。
|
||||
|
||||
|
||||
|
||||
### 通过环境变量配置
|
||||
|
||||
@ -223,7 +222,7 @@ export FEISHU_APP_SECRET="xxx"
|
||||
|
||||
### Lark（国际版）域名
|
||||
|
||||
如果您的租户在 Lark（国际版），请设置域名为 `lark`（或完整域名），可配置 `channels.feishu.domain` 或 `channels.feishu.accounts.<id>.domain`：
|
||||
如果你的租户位于 Lark（国际版），请将域名设置为 `lark`（或完整域名字串）。你可以在 `channels.feishu.domain` 设置，也可以按账户设置（`channels.feishu.accounts.<id>.domain`）。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -241,14 +240,14 @@ export FEISHU_APP_SECRET="xxx"
|
||||
}
|
||||
```
|
||||
|
||||
### 配额优化
|
||||
### 配额优化标志
|
||||
|
||||
可通过以下可选配置减少飞书 API 调用：
|
||||
你可以使用两个可选标志来减少飞书 API 使用量：
|
||||
|
||||
- `typingIndicator`（默认 `true`）：设为 `false` 时不发送“正在输入”状态。
|
||||
- `resolveSenderNames`（默认 `true`）：设为 `false` 时不拉取发送者资料。
|
||||
- `typingIndicator`（默认 `true`）：设为 `false` 时，跳过“正在输入”反应调用。
|
||||
- `resolveSenderNames`（默认 `true`）：设为 `false` 时，跳过发送者资料查询调用。
|
||||
|
||||
可在渠道级或账号级配置：
|
||||
你可以在顶层或按账户进行设置：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -271,9 +270,9 @@ export FEISHU_APP_SECRET="xxx"
|
||||
|
||||
---
|
||||
|
||||
## 第三步：启动并测试
|
||||
## 第 3 步：启动并测试
|
||||
|
||||
### 1. 启动网关
|
||||
### 1. 启动 Gateway 网关
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -281,74 +280,74 @@ openclaw gateway
|
||||
|
||||
### 2. 发送测试消息
|
||||
|
||||
在飞书中找到您创建的机器人，发送一条消息。
|
||||
在飞书中找到你的机器人并发送一条消息。
|
||||
|
||||
### 3. 配对授权
|
||||
### 3. 批准配对
|
||||
|
||||
默认情况下，机器人会回复一个 **配对码**。您需要批准此代码：
|
||||
默认情况下，机器人会回复一个配对码。批准它：
|
||||
|
||||
```bash
|
||||
openclaw pairing approve feishu <配对码>
|
||||
openclaw pairing approve feishu <CODE>
|
||||
```
|
||||
|
||||
批准后即可正常对话。
|
||||
批准后，你就可以正常聊天了。
|
||||
|
||||
---
|
||||
|
||||
## 介绍
|
||||
## 概览
|
||||
|
||||
- **飞书机器人渠道**：由网关管理的飞书机器人
|
||||
- **确定性路由**：回复始终返回飞书，模型不会选择渠道
|
||||
- **会话隔离**：私聊共享主会话；群组独立隔离
|
||||
- **WebSocket 连接**：使用飞书 SDK 的长连接模式，无需公网 URL
|
||||
- **飞书机器人渠道**：由 Gateway 网关管理的飞书机器人
|
||||
- **确定性路由**：回复始终返回到飞书
|
||||
- **会话隔离**：私信共享主会话；群组彼此隔离
|
||||
- **WebSocket 连接**：通过飞书 SDK 建立长连接，无需公共 URL
|
||||
|
||||
---
|
||||
|
||||
## 访问控制
|
||||
|
||||
### 私聊访问
|
||||
### 私信
|
||||
|
||||
- **默认**：`dmPolicy: "pairing"`，陌生用户会收到配对码
|
||||
- **默认**：`dmPolicy: "pairing"`（未知用户会收到配对码）
|
||||
- **批准配对**：
|
||||
```bash
|
||||
openclaw pairing list feishu # 查看待审批列表
|
||||
openclaw pairing approve feishu <CODE> # 批准
|
||||
```
|
||||
- **白名单模式**：通过 `channels.feishu.allowFrom` 配置允许的用户 Open ID
|
||||
|
||||
### 群组访问
|
||||
```bash
|
||||
openclaw pairing list feishu
|
||||
openclaw pairing approve feishu <CODE>
|
||||
```
|
||||
|
||||
- **Allowlist 模式**：设置 `channels.feishu.allowFrom`，填入允许的 Open ID
|
||||
|
||||
### 群聊
|
||||
|
||||
**1. 群组策略**（`channels.feishu.groupPolicy`）：
|
||||
|
||||
- `"open"` = 允许群组中所有人（默认）
|
||||
- `"allowlist"` = 仅允许 `groupAllowFrom` 中的群组
|
||||
- `"disabled"` = 禁用群组消息
|
||||
- `"open"` = 允许群组中的所有人（默认）
|
||||
- `"allowlist"` = 仅允许 `groupAllowFrom`
|
||||
- `"disabled"` = 禁用群消息
|
||||
|
||||
**2. @提及要求**（`channels.feishu.groups.<chat_id>.requireMention`）：
|
||||
**2. 提及要求**（`channels.feishu.groups.<chat_id>.requireMention`）：
|
||||
|
||||
- `true` = 需要 @机器人才响应（默认）
|
||||
- `false` = 无需 @也响应
|
||||
- `true` = 需要 @ 提及（默认）
|
||||
- `false` = 无需提及也会回复
|
||||
|
||||
---
|
||||
|
||||
## 群组配置示例
|
||||
|
||||
### 允许所有群组，需要 @提及（默认行为）
|
||||
### 允许所有群组，要求 @ 提及（默认）
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
groupPolicy: "open",
|
||||
// 默认 requireMention: true
|
||||
// Default requireMention: true
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 允许所有群组，无需 @提及
|
||||
|
||||
需要为特定群组配置：
|
||||
### 允许所有群组，无需 @ 提及
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -369,16 +368,16 @@ openclaw pairing approve feishu <配对码>
|
||||
channels: {
|
||||
feishu: {
|
||||
groupPolicy: "allowlist",
|
||||
// 群组 ID 格式为 oc_xxx
|
||||
// Feishu group IDs (chat_id) look like: oc_xxx
|
||||
groupAllowFrom: ["oc_xxx", "oc_yyy"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 仅允许特定成员在群组中发信（发送者白名单）
|
||||
### 限制哪些发送者可以在群组中发消息（发送者 allowlist）
|
||||
|
||||
除群组白名单外，该群组内**所有消息**均按发送者 open_id 校验：仅 `groups.<chat_id>.allowFrom` 中列出的用户消息会被处理，其他成员的消息会被忽略（此为发送者级白名单，不仅针对 /reset、/new 等控制命令）。
|
||||
除了允许群组本身外，该群组中的**所有消息**还会按发送者 `open_id` 进行限制：只有列在 `groups.<chat_id>.allowFrom` 中的用户，其消息才会被处理；其他成员发送的消息会被忽略（这是完整的发送者级限制，而不只是对 `/reset` 或 `/new` 等控制命令生效）。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -388,7 +387,7 @@ openclaw pairing approve feishu <配对码>
|
||||
groupAllowFrom: ["oc_xxx"],
|
||||
groups: {
|
||||
oc_xxx: {
|
||||
// 用户 open_id 格式为 ou_xxx
|
||||
// Feishu user IDs (open_id) look like: ou_xxx
|
||||
allowFrom: ["ou_user1", "ou_user2"],
|
||||
},
|
||||
},
|
||||
@ -401,29 +400,31 @@ openclaw pairing approve feishu <配对码>
|
||||
|
||||
## 获取群组/用户 ID
|
||||
|
||||
### 获取群组 ID（chat_id）
|
||||
### 群组 ID（`chat_id`）
|
||||
|
||||
群组 ID 格式为 `oc_xxx`，可以通过以下方式获取：
|
||||
群组 ID 看起来像 `oc_xxx`。
|
||||
|
||||
**方法一**（推荐）：
|
||||
**方法 1（推荐）**
|
||||
|
||||
1. 启动网关并在群组中 @机器人发消息
|
||||
2. 运行 `openclaw logs --follow` 查看日志中的 `chat_id`
|
||||
1. 启动 Gateway 网关并在群里 @ 提及机器人
|
||||
2. 运行 `openclaw logs --follow` 并查找 `chat_id`
|
||||
|
||||
**方法二**：
|
||||
使用飞书 API 调试工具获取机器人所在群组列表。
|
||||
**方法 2**
|
||||
|
||||
### 获取用户 ID（open_id）
|
||||
使用飞书 API 调试器列出群聊。
|
||||
|
||||
用户 ID 格式为 `ou_xxx`，可以通过以下方式获取：
|
||||
### 用户 ID（`open_id`）
|
||||
|
||||
**方法一**（推荐）：
|
||||
用户 ID 看起来像 `ou_xxx`。
|
||||
|
||||
1. 启动网关并给机器人发消息
|
||||
2. 运行 `openclaw logs --follow` 查看日志中的 `open_id`
|
||||
**方法 1（推荐）**
|
||||
|
||||
**方法二**：
|
||||
查看配对请求列表，其中包含用户的 Open ID：
|
||||
1. 启动 Gateway 网关并向机器人发送私信
|
||||
2. 运行 `openclaw logs --follow` 并查找 `open_id`
|
||||
|
||||
**方法 2**
|
||||
|
||||
检查配对请求中的用户 Open ID：
|
||||
|
||||
```bash
|
||||
openclaw pairing list feishu
|
||||
@ -433,65 +434,61 @@ openclaw pairing list feishu
|
||||
|
||||
## 常用命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
| Command | Description |
|
||||
| --------- | -------------- |
|
||||
| `/status` | 查看机器人状态 |
|
||||
| `/reset` | 重置对话会话 |
|
||||
| `/model` | 查看/切换模型 |
|
||||
| `/status` | 显示机器人状态 |
|
||||
| `/reset` | 重置会话 |
|
||||
| `/model` | 显示/切换模型 |
|
||||
|
||||
飞书机器人菜单建议直接在飞书开放平台的机器人能力页面配置。OpenClaw 当前支持接收 `application.bot.menu_v6` 事件，并把点击事件转换成普通文本命令（例如 `/menu <eventKey>`）继续走现有消息路由，但不通过渠道配置自动创建或同步菜单。
|
||||
> 注意：飞书暂不支持原生命令菜单，因此命令必须以文本形式发送。
|
||||
|
||||
## 网关管理命令
|
||||
## Gateway 网关管理命令
|
||||
|
||||
在配置和使用飞书渠道时，您可能需要使用以下网关管理命令：
|
||||
|
||||
| 命令 | 说明 |
|
||||
| -------------------------- | ----------------- |
|
||||
| `openclaw gateway status` | 查看网关运行状态 |
|
||||
| `openclaw gateway install` | 安装/启动网关服务 |
|
||||
| `openclaw gateway stop` | 停止网关服务 |
|
||||
| `openclaw gateway restart` | 重启网关服务 |
|
||||
| `openclaw logs --follow` | 实时查看日志输出 |
|
||||
| Command | Description |
|
||||
| -------------------------- | -------------------------- |
|
||||
| `openclaw gateway status` | 显示 Gateway 网关状态 |
|
||||
| `openclaw gateway install` | 安装/启动 Gateway 网关服务 |
|
||||
| `openclaw gateway stop` | 停止 Gateway 网关服务 |
|
||||
| `openclaw gateway restart` | 重启 Gateway 网关服务 |
|
||||
| `openclaw logs --follow` | 跟踪 Gateway 网关日志 |
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 机器人在群组中不响应
|
||||
### 机器人在群聊中没有响应
|
||||
|
||||
1. 检查机器人是否已添加到群组
|
||||
2. 检查是否 @了机器人（默认需要 @提及）
|
||||
3. 检查 `groupPolicy` 是否为 `"disabled"`
|
||||
4. 查看日志：`openclaw logs --follow`
|
||||
1. 确保机器人已加入群组
|
||||
2. 确保你 @ 提及了机器人（默认行为）
|
||||
3. 检查 `groupPolicy` 未设置为 `"disabled"`
|
||||
4. 检查日志：`openclaw logs --follow`
|
||||
|
||||
### 机器人收不到消息
|
||||
### 机器人未接收到消息
|
||||
|
||||
1. 检查应用是否已发布并审批通过
|
||||
2. 检查事件订阅是否配置正确（`im.message.receive_v1`）
|
||||
3. 检查是否选择了 **长连接** 模式
|
||||
4. 检查应用权限是否完整
|
||||
5. 检查网关是否正在运行：`openclaw gateway status`
|
||||
6. 查看实时日志：`openclaw logs --follow`
|
||||
1. 确保应用已发布并获批准
|
||||
2. 确保事件订阅包含 `im.message.receive_v1`
|
||||
3. 确保已启用**长连接**
|
||||
4. 确保应用权限完整
|
||||
5. 确保 Gateway 网关正在运行：`openclaw gateway status`
|
||||
6. 检查日志：`openclaw logs --follow`
|
||||
|
||||
### App Secret 泄露怎么办
|
||||
### App Secret 泄露
|
||||
|
||||
1. 在飞书开放平台重置 App Secret
|
||||
2. 更新配置文件中的 App Secret
|
||||
3. 重启网关
|
||||
1. 在飞书开放平台中重置 App Secret
|
||||
2. 在你的配置中更新 App Secret
|
||||
3. 重启 Gateway 网关
|
||||
|
||||
### 发送消息失败
|
||||
### 消息发送失败
|
||||
|
||||
1. 检查应用是否有 `im:message:send_as_bot` 权限
|
||||
2. 检查应用是否已发布
|
||||
3. 查看日志获取详细错误信息
|
||||
1. 确保应用具有 `im:message:send_as_bot` 权限
|
||||
2. 确保应用已发布
|
||||
3. 查看日志以获取详细错误信息
|
||||
|
||||
---
|
||||
|
||||
## 高级配置
|
||||
|
||||
### 多账号配置
|
||||
|
||||
如果需要管理多个飞书机器人，可配置 `defaultAccount` 指定出站未显式指定 `accountId` 时使用的账号：
|
||||
### 多账户
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -502,13 +499,13 @@ openclaw pairing list feishu
|
||||
main: {
|
||||
appId: "cli_xxx",
|
||||
appSecret: "xxx",
|
||||
botName: "主机器人",
|
||||
botName: "Primary bot",
|
||||
},
|
||||
backup: {
|
||||
appId: "cli_yyy",
|
||||
appSecret: "yyy",
|
||||
botName: "备用机器人",
|
||||
enabled: false, // 暂时禁用
|
||||
botName: "Backup bot",
|
||||
enabled: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -516,104 +513,102 @@ openclaw pairing list feishu
|
||||
}
|
||||
```
|
||||
|
||||
`defaultAccount` 用于控制当出站 API 未显式指定 `accountId` 时，使用哪个飞书账户。
|
||||
|
||||
### 消息限制
|
||||
|
||||
- `textChunkLimit`：出站文本分块大小（默认 2000 字符）
|
||||
- `mediaMaxMb`：媒体上传/下载限制（默认 30MB）
|
||||
- `textChunkLimit`：出站文本分块大小（默认：2000 个字符）
|
||||
- `mediaMaxMb`：媒体上传/下载限制（默认：30 MB）
|
||||
|
||||
### 流式输出
|
||||
### 流式传输
|
||||
|
||||
飞书支持通过交互式卡片实现流式输出，机器人会实时更新卡片内容显示生成进度。默认配置：
|
||||
飞书通过交互式卡片支持流式回复。启用后，机器人会在生成文本时更新卡片。
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
streaming: true, // 启用流式卡片输出（默认 true）
|
||||
blockStreamingCoalesce: {
|
||||
enabled: true,
|
||||
minDelayMs: 50,
|
||||
maxDelayMs: 250,
|
||||
},
|
||||
blockStreaming: true, // 启用分块流式传输（默认 true）
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
如需禁用流式输出（等待完整回复后一次性发送），可设置 `streaming: false`。
|
||||
将 `streaming: false` 设为等待完整回复生成后再发送。
|
||||
|
||||
### 交互式卡片
|
||||
### ACP 会话
|
||||
|
||||
OpenClaw 默认会在需要时发送 Markdown 卡片；如果你需要完整的 Feishu 原生交互式卡片，也可以显式发送原始 `card` payload。
|
||||
飞书支持以下 ACP 场景：
|
||||
|
||||
- 默认路径：文本自动渲染或 Markdown 卡片
|
||||
- 显式卡片：通过消息动作的 `card` 参数发送原始交互卡片
|
||||
- 更新卡片：同一消息支持后续 patch/update
|
||||
- 私信
|
||||
- 群组话题会话
|
||||
|
||||
卡片按钮回调当前走文本回退路径：
|
||||
飞书 ACP 由文本命令驱动。没有原生斜杠命令菜单，因此请直接在会话中使用 `/acp ...` 消息。
|
||||
|
||||
- 若 `action.value.text` 存在，则作为入站文本继续处理
|
||||
- 若 `action.value.command` 存在，则作为命令文本继续处理
|
||||
- 其他对象值会序列化为 JSON 文本
|
||||
#### 持久化 ACP 绑定
|
||||
|
||||
这样可以保持与现有消息/命令路由兼容，而不要求下游先理解 Feishu 专有的交互 payload。
|
||||
|
||||
### 表情反应
|
||||
|
||||
飞书渠道现已完整支持表情反应生命周期：
|
||||
|
||||
- 接收 `reaction created`
|
||||
- 接收 `reaction deleted`
|
||||
- 主动添加反应
|
||||
- 主动删除自身反应
|
||||
- 查询消息上的反应列表
|
||||
|
||||
是否把入站反应转成内部消息，可通过 `reactionNotifications` 控制：
|
||||
|
||||
| 值 | 行为 |
|
||||
| ----- | ---------------------------- |
|
||||
| `off` | 不生成反应通知 |
|
||||
| `own` | 仅当反应发生在机器人消息上时 |
|
||||
| `all` | 所有可验证的反应都生成通知 |
|
||||
|
||||
### 消息引用
|
||||
|
||||
在群聊中，机器人的回复可以引用用户发送的原始消息，让对话上下文更加清晰。
|
||||
|
||||
配置选项：
|
||||
使用顶层类型化 ACP 绑定，将飞书私信或话题会话固定到持久化 ACP 会话。
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
// 账户级别配置（默认 "all"）
|
||||
replyToMode: "all",
|
||||
groups: {
|
||||
oc_xxx: {
|
||||
// 特定群组可以覆盖
|
||||
replyToMode: "first",
|
||||
agents: {
|
||||
list: [
|
||||
{
|
||||
id: "codex",
|
||||
runtime: {
|
||||
type: "acp",
|
||||
acp: {
|
||||
agent: "codex",
|
||||
backend: "acpx",
|
||||
mode: "persistent",
|
||||
cwd: "/workspace/openclaw",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
bindings: [
|
||||
{
|
||||
type: "acp",
|
||||
agentId: "codex",
|
||||
match: {
|
||||
channel: "feishu",
|
||||
accountId: "default",
|
||||
peer: { kind: "direct", id: "ou_1234567890" },
|
||||
},
|
||||
},
|
||||
{
|
||||
type: "acp",
|
||||
agentId: "codex",
|
||||
match: {
|
||||
channel: "feishu",
|
||||
accountId: "default",
|
||||
peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
|
||||
},
|
||||
acp: { label: "codex-feishu-topic" },
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
`replyToMode` 值说明：
|
||||
#### 从聊天中按线程绑定 ACP 生成
|
||||
|
||||
| 值 | 行为 |
|
||||
| --------- | ---------------------------------- |
|
||||
| `"off"` | 不引用原消息（私聊默认值） |
|
||||
| `"first"` | 仅在第一条回复时引用原消息 |
|
||||
| `"all"` | 所有回复都引用原消息（群聊默认值） |
|
||||
在飞书私信或话题会话中，你可以就地生成并绑定一个 ACP 会话：
|
||||
|
||||
> 注意：消息引用功能与流式卡片输出（`streaming: true`）不能同时使用。当启用流式输出时，回复会以卡片形式呈现，不会显示引用。
|
||||
```text
|
||||
/acp spawn codex --thread here
|
||||
```
|
||||
|
||||
### 多 Agent 路由
|
||||
说明：
|
||||
|
||||
通过 `bindings` 配置，您可以用一个飞书机器人对接多个不同功能或性格的 Agent。系统会根据用户 ID 或群组 ID 自动将对话分发到对应的 Agent。
|
||||
- `--thread here` 适用于私信和飞书话题。
|
||||
- 绑定后的私信/话题中的后续消息会直接路由到该 ACP 会话。
|
||||
- v1 不支持针对通用的非话题群聊。
|
||||
|
||||
配置示例：
|
||||
### 多智能体路由
|
||||
|
||||
使用 `bindings` 将飞书私信或群组路由到不同的智能体。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -634,91 +629,81 @@ OpenClaw 默认会在需要时发送 Markdown 卡片；如果你需要完整的
|
||||
},
|
||||
bindings: [
|
||||
{
|
||||
// 用户 A 的私聊 → main agent
|
||||
agentId: "main",
|
||||
match: {
|
||||
channel: "feishu",
|
||||
peer: { kind: "dm", id: "ou_28b31a88..." },
|
||||
peer: { kind: "direct", id: "ou_xxx" },
|
||||
},
|
||||
},
|
||||
{
|
||||
// 用户 B 的私聊 → clawd-fan agent
|
||||
agentId: "clawd-fan",
|
||||
match: {
|
||||
channel: "feishu",
|
||||
peer: { kind: "dm", id: "ou_0fe6b1c9..." },
|
||||
peer: { kind: "direct", id: "ou_yyy" },
|
||||
},
|
||||
},
|
||||
{
|
||||
// 某个群组 → clawd-xi agent
|
||||
agentId: "clawd-xi",
|
||||
match: {
|
||||
channel: "feishu",
|
||||
peer: { kind: "group", id: "oc_xxx..." },
|
||||
peer: { kind: "group", id: "oc_zzz" },
|
||||
},
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
匹配规则说明：
|
||||
路由字段：
|
||||
|
||||
| 字段 | 说明 |
|
||||
| ----------------- | --------------------------------------------- |
|
||||
| `agentId` | 目标 Agent 的 ID，需要在 `agents.list` 中定义 |
|
||||
| `match.channel` | 渠道类型，这里固定为 `"feishu"` |
|
||||
| `match.peer.kind` | 对话类型：`"dm"`（私聊）或 `"group"`（群组） |
|
||||
| `match.peer.id` | 用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`） |
|
||||
- `match.channel`：`"feishu"`
|
||||
- `match.peer.kind`：`"direct"` 或 `"group"`
|
||||
- `match.peer.id`：用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`）
|
||||
|
||||
> 获取 ID 的方法：参见上文 [获取群组/用户 ID](#获取群组用户-id) 章节。
|
||||
查找提示请参见 [获取群组/用户 ID](#get-groupuser-ids)。
|
||||
|
||||
---
|
||||
|
||||
## 配置参考
|
||||
|
||||
完整配置请参考：[网关配置](/gateway/configuration)
|
||||
完整配置：[Gateway 网关配置](/gateway/configuration)
|
||||
|
||||
主要选项：
|
||||
关键选项：
|
||||
|
||||
| 配置项 | 说明 | 默认值 |
|
||||
| ------------------------------------------------- | --------------------------------- | ---------------- |
|
||||
| `channels.feishu.enabled` | 启用/禁用渠道 | `true` |
|
||||
| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` |
|
||||
| `channels.feishu.connectionMode` | 事件传输模式（websocket/webhook） | `websocket` |
|
||||
| `channels.feishu.defaultAccount` | 出站路由默认账号 ID | `default` |
|
||||
| `channels.feishu.verificationToken` | Webhook 模式必填 | - |
|
||||
| `channels.feishu.webhookPath` | Webhook 路由路径 | `/feishu/events` |
|
||||
| `channels.feishu.webhookHost` | Webhook 监听地址 | `127.0.0.1` |
|
||||
| `channels.feishu.webhookPort` | Webhook 监听端口 | `3000` |
|
||||
| `channels.feishu.accounts.<id>.appId` | 应用 App ID | - |
|
||||
| `channels.feishu.accounts.<id>.appSecret` | 应用 App Secret | - |
|
||||
| `channels.feishu.accounts.<id>.domain` | 单账号 API 域名覆盖 | `feishu` |
|
||||
| `channels.feishu.dmPolicy` | 私聊策略 | `pairing` |
|
||||
| `channels.feishu.allowFrom` | 私聊白名单（open_id 列表） | - |
|
||||
| `channels.feishu.groupPolicy` | 群组策略 | `allowlist` |
|
||||
| `channels.feishu.groupAllowFrom` | 群组白名单 | - |
|
||||
| `channels.feishu.groups.<chat_id>.requireMention` | 是否需要 @提及 | `true` |
|
||||
| `channels.feishu.groups.<chat_id>.enabled` | 是否启用该群组 | `true` |
|
||||
| `channels.feishu.replyInThread` | 群聊回复是否进入飞书话题线程 | `disabled` |
|
||||
| `channels.feishu.groupSessionScope` | 群聊会话隔离粒度 | `group` |
|
||||
| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` |
|
||||
| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` |
|
||||
| `channels.feishu.streaming` | 启用流式卡片输出 | `true` |
|
||||
| `channels.feishu.blockStreamingCoalesce.enabled` | 启用块级流式合并 | `true` |
|
||||
| `channels.feishu.typingIndicator` | 发送“正在输入”状态 | `true` |
|
||||
| `channels.feishu.resolveSenderNames` | 拉取发送者名称 | `true` |
|
||||
| `channels.feishu.reactionNotifications` | 入站反应通知策略 | `own` |
|
||||
| Setting | Description | Default |
|
||||
| ------------------------------------------------- | -------------------------------- | ---------------- |
|
||||
| `channels.feishu.enabled` | 启用/禁用渠道 | `true` |
|
||||
| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` |
|
||||
| `channels.feishu.connectionMode` | 事件传输模式 | `websocket` |
|
||||
| `channels.feishu.defaultAccount` | 出站路由的默认账户 ID | `default` |
|
||||
| `channels.feishu.verificationToken` | webhook 模式必填 | - |
|
||||
| `channels.feishu.encryptKey` | webhook 模式必填 | - |
|
||||
| `channels.feishu.webhookPath` | webhook 路由路径 | `/feishu/events` |
|
||||
| `channels.feishu.webhookHost` | webhook 绑定主机 | `127.0.0.1` |
|
||||
| `channels.feishu.webhookPort` | webhook 绑定端口 | `3000` |
|
||||
| `channels.feishu.accounts.<id>.appId` | App ID | - |
|
||||
| `channels.feishu.accounts.<id>.appSecret` | App Secret | - |
|
||||
| `channels.feishu.accounts.<id>.domain` | 按账户覆盖 API 域名 | `feishu` |
|
||||
| `channels.feishu.dmPolicy` | 私信策略 | `pairing` |
|
||||
| `channels.feishu.allowFrom` | 私信 allowlist（`open_id` 列表） | - |
|
||||
| `channels.feishu.groupPolicy` | 群组策略 | `open` |
|
||||
| `channels.feishu.groupAllowFrom` | 群组 allowlist | - |
|
||||
| `channels.feishu.groups.<chat_id>.requireMention` | 要求 @ 提及 | `true` |
|
||||
| `channels.feishu.groups.<chat_id>.enabled` | 启用群组 | `true` |
|
||||
| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` |
|
||||
| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` |
|
||||
| `channels.feishu.streaming` | 启用流式卡片输出 | `true` |
|
||||
| `channels.feishu.blockStreaming` | 启用分块流式传输 | `true` |
|
||||
|
||||
---
|
||||
|
||||
## dmPolicy 策略说明
|
||||
## dmPolicy 参考
|
||||
|
||||
| 值 | 行为 |
|
||||
| ------------- | -------------------------------------------------- |
|
||||
| `"pairing"` | **默认**。未知用户收到配对码，管理员批准后才能对话 |
|
||||
| `"allowlist"` | 仅 `allowFrom` 列表中的用户可对话，其他静默忽略 |
|
||||
| `"open"` | 允许所有人对话（需在 allowFrom 中加 `"*"`） |
|
||||
| `"disabled"` | 完全禁止私聊 |
|
||||
| Value | Behavior |
|
||||
| ------------- | ---------------------------------------------------- |
|
||||
| `"pairing"` | **默认。**未知用户会收到配对码；必须获批准后才能使用 |
|
||||
| `"allowlist"` | 只有 `allowFrom` 中的用户可以聊天 |
|
||||
| `"open"` | 允许所有用户（要求 `allowFrom` 中有 `"*"`） |
|
||||
| `"disabled"` | 禁用私信 |
|
||||
|
||||
---
|
||||
|
||||
@ -726,17 +711,17 @@ OpenClaw 默认会在需要时发送 Markdown 卡片；如果你需要完整的
|
||||
|
||||
### 接收
|
||||
|
||||
- ✅ 文本消息
|
||||
- ✅ 富文本（帖子）
|
||||
- ✅ 文本
|
||||
- ✅ 富文本（post）
|
||||
- ✅ 图片
|
||||
- ✅ 文件
|
||||
- ✅ 音频
|
||||
- ✅ 视频
|
||||
- ✅ 表情包
|
||||
- ✅ 贴纸
|
||||
|
||||
### 发送
|
||||
|
||||
- ✅ 文本消息
|
||||
- ✅ 文本
|
||||
- ✅ 图片
|
||||
- ✅ 文件
|
||||
- ✅ 音频
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 你希望 OpenClaw 通过 Nostr 接收私信
|
||||
- 你正在设置去中心化消息
|
||||
summary: 通过 NIP-04 加密消息的 Nostr 私信渠道
|
||||
- 你想让 OpenClaw 通过 Nostr 接收私信
|
||||
- 你正在设置去中心化消息传递
|
||||
summary: 通过 NIP-04 加密消息实现的 Nostr 私信渠道
|
||||
title: Nostr
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:44:13Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 6b9fe4c74bf5e7c0f59bbaa129ec5270fd29a248551a8a9a7dde6cff8fb46111
|
||||
generated_at: "2026-03-16T06:20:37Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fcce57da49256971420c4bb099aebb7944f8c7e8619b17b163da685add225001
|
||||
source_path: channels/nostr.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,21 +17,21 @@ x-i18n:
|
||||
|
||||
**状态：** 可选插件（默认禁用）。
|
||||
|
||||
Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信（DMs）。
|
||||
Nostr 是一种用于社交网络的去中心化协议。此渠道使 OpenClaw 能够通过 NIP-04 接收并回复加密私信。
|
||||
|
||||
## 安装（按需）
|
||||
|
||||
### 新手引导（推荐）
|
||||
|
||||
- 新手引导向导（`openclaw onboard`）和 `openclaw channels add` 会列出可选的渠道插件。
|
||||
- 选择 Nostr 会提示你按需安装插件。
|
||||
- 设置向导（`openclaw onboard`）和 `openclaw channels add` 会列出可选渠道插件。
|
||||
- 选择 Nostr 时，系统会提示你按需安装该插件。
|
||||
|
||||
安装默认值：
|
||||
安装默认行为：
|
||||
|
||||
- **Dev 渠道 + git checkout 可用：** 使用本地插件路径。
|
||||
- **Stable/Beta：** 从 npm 下载。
|
||||
- **Dev 渠道 + 可用的 git 检出：** 使用本地插件路径。
|
||||
- **稳定版 / Beta：** 从 npm 下载。
|
||||
|
||||
你可以随时在提示中覆盖选择。
|
||||
你始终可以在提示中覆盖该选择。
|
||||
|
||||
### 手动安装
|
||||
|
||||
@ -39,24 +39,33 @@ Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够
|
||||
openclaw plugins install @openclaw/nostr
|
||||
```
|
||||
|
||||
使用本地 checkout（开发工作流）：
|
||||
使用本地检出（dev 工作流）：
|
||||
|
||||
```bash
|
||||
openclaw plugins install --link <path-to-openclaw>/extensions/nostr
|
||||
```
|
||||
|
||||
安装或启用插件后重启 Gateway 网关。
|
||||
安装或启用插件后，重启 Gateway 网关。
|
||||
|
||||
### 非交互式设置
|
||||
|
||||
```bash
|
||||
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
|
||||
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net"
|
||||
```
|
||||
|
||||
使用 `--use-env` 可将 `NOSTR_PRIVATE_KEY` 保留在环境中，而不是将密钥存储在配置里。
|
||||
|
||||
## 快速设置
|
||||
|
||||
1. 生成 Nostr 密钥对（如需要）：
|
||||
1. 生成一个 Nostr 密钥对（如有需要）：
|
||||
|
||||
```bash
|
||||
# 使用 nak
|
||||
# Using nak
|
||||
nak key generate
|
||||
```
|
||||
|
||||
2. 添加到配置：
|
||||
2. 添加到配置中：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -78,19 +87,19 @@ export NOSTR_PRIVATE_KEY="nsec1..."
|
||||
|
||||
## 配置参考
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------ | -------- | ------------------------------------------- | --------------------------- |
|
||||
| `privateKey` | string | 必填 | `nsec` 或十六进制格式的私钥 |
|
||||
| `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | 中继 URL（WebSocket） |
|
||||
| `dmPolicy` | string | `pairing` | 私信访问策略 |
|
||||
| `allowFrom` | string[] | `[]` | 允许的发送者公钥 |
|
||||
| `enabled` | boolean | `true` | 启用/禁用渠道 |
|
||||
| `allowFrom` | string[] | `[]` | 允许的发送方公钥 |
|
||||
| `enabled` | boolean | `true` | 启用 / 禁用渠道 |
|
||||
| `name` | string | - | 显示名称 |
|
||||
| `profile` | object | - | NIP-01 个人资料元数据 |
|
||||
| `profile` | object | - | NIP-01 资料元数据 |
|
||||
|
||||
## 个人资料元数据
|
||||
## 资料元数据
|
||||
|
||||
个人资料数据作为 NIP-01 `kind:0` 事件发布。你可以从控制界面（Channels -> Nostr -> Profile）管理它，或直接在配置中设置。
|
||||
资料数据会作为 NIP-01 `kind:0` 事件发布。你可以在控制 UI 中管理它（Channels -> Nostr -> Profile），也可以直接在配置中设置。
|
||||
|
||||
示例：
|
||||
|
||||
@ -114,19 +123,19 @@ export NOSTR_PRIVATE_KEY="nsec1..."
|
||||
}
|
||||
```
|
||||
|
||||
注意事项：
|
||||
注意：
|
||||
|
||||
- 个人资料 URL 必须使用 `https://`。
|
||||
- 从中继导入会合并字段并保留本地覆盖。
|
||||
- 资料 URL 必须使用 `https://`。
|
||||
- 从中继导入时会合并字段，并保留本地覆盖项。
|
||||
|
||||
## 访问控制
|
||||
|
||||
### 私信策略
|
||||
|
||||
- **pairing**（默认）：未知发送者会收到配对码。
|
||||
- **pairing**（默认）：未知发送方会收到一个配对码。
|
||||
- **allowlist**：只有 `allowFrom` 中的公钥可以发送私信。
|
||||
- **open**：公开接收私信（需要 `allowFrom: ["*"]`）。
|
||||
- **disabled**：忽略接收的私信。
|
||||
- **open**：公开接收入站私信（要求 `allowFrom: ["*"]`）。
|
||||
- **disabled**：忽略入站私信。
|
||||
|
||||
### 允许列表示例
|
||||
|
||||
@ -166,26 +175,26 @@ export NOSTR_PRIVATE_KEY="nsec1..."
|
||||
|
||||
提示：
|
||||
|
||||
- 使用 2-3 个中继以实现冗余。
|
||||
- 使用 2 到 3 个中继以实现冗余。
|
||||
- 避免使用过多中继（延迟、重复）。
|
||||
- 付费中继可以提高可靠性。
|
||||
- 本地中继适合测试（`ws://localhost:7777`）。
|
||||
- 本地中继也适合测试（`ws://localhost:7777`）。
|
||||
|
||||
## 协议支持
|
||||
|
||||
| NIP | 状态 | 描述 |
|
||||
| ------ | ------ | ----------------------------- |
|
||||
| NIP-01 | 已支持 | 基本事件格式 + 个人资料元数据 |
|
||||
| NIP-04 | 已支持 | 加密私信（`kind:4`） |
|
||||
| NIP-17 | 计划中 | 礼物包装私信 |
|
||||
| NIP-44 | 计划中 | 版本化加密 |
|
||||
| NIP | 状态 | 说明 |
|
||||
| ------ | ------ | ------------------------- |
|
||||
| NIP-01 | 已支持 | 基础事件格式 + 资料元数据 |
|
||||
| NIP-04 | 已支持 | 加密私信（`kind:4`） |
|
||||
| NIP-17 | 计划中 | Gift-wrapped 私信 |
|
||||
| NIP-44 | 计划中 | 版本化加密 |
|
||||
|
||||
## 测试
|
||||
|
||||
### 本地中继
|
||||
|
||||
```bash
|
||||
# 启动 strfry
|
||||
# Start strfry
|
||||
docker run -p 7777:7777 ghcr.io/hoytech/strfry
|
||||
```
|
||||
|
||||
@ -203,38 +212,38 @@ docker run -p 7777:7777 ghcr.io/hoytech/strfry
|
||||
### 手动测试
|
||||
|
||||
1. 从日志中记下机器人公钥（npub）。
|
||||
2. 打开 Nostr 客户端（Damus、Amethyst 等）。
|
||||
3. 向机器人公钥发送私信。
|
||||
4. 验证响应。
|
||||
2. 打开一个 Nostr 客户端（Damus、Amethyst 等）。
|
||||
3. 向该机器人公钥发送私信。
|
||||
4. 验证回复。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 未收到消息
|
||||
### 未接收到消息
|
||||
|
||||
- 验证私钥是否有效。
|
||||
- 确保中继 URL 可访问并使用 `wss://`（本地使用 `ws://`）。
|
||||
- 验证私钥有效。
|
||||
- 确保中继 URL 可访问，并使用 `wss://`（本地则使用 `ws://`）。
|
||||
- 确认 `enabled` 不是 `false`。
|
||||
- 检查 Gateway 网关日志中的中继连接错误。
|
||||
|
||||
### 未发送响应
|
||||
### 未发送回复
|
||||
|
||||
- 检查中继是否接受写入。
|
||||
- 验证出站连接。
|
||||
- 验证出站连接性。
|
||||
- 注意中继速率限制。
|
||||
|
||||
### 重复响应
|
||||
### 重复回复
|
||||
|
||||
- 使用多个中继时属于正常现象。
|
||||
- 消息按事件 ID 去重；只有首次投递会触发响应。
|
||||
- 使用多个中继时这是预期行为。
|
||||
- 消息会按事件 ID 去重；只有首次投递会触发回复。
|
||||
|
||||
## 安全
|
||||
## 安全性
|
||||
|
||||
- 切勿提交私钥。
|
||||
- 使用环境变量存储密钥。
|
||||
- 生产环境机器人考虑使用 `allowlist`。
|
||||
- 对密钥使用环境变量。
|
||||
- 对生产机器人考虑使用 `allowlist`。
|
||||
|
||||
## 限制（MVP）
|
||||
|
||||
- 仅支持私信（不支持群聊）。
|
||||
- 不支持媒体附件。
|
||||
- 仅支持 NIP-04（计划支持 NIP-17 礼物包装）。
|
||||
- 仅支持 NIP-04（计划支持 NIP-17 gift-wrap）。
|
||||
|
||||
138
docs/zh-CN/channels/synology-chat.md
Normal file
138
docs/zh-CN/channels/synology-chat.md
Normal file
@ -0,0 +1,138 @@
|
||||
---
|
||||
read_when:
|
||||
- 设置 OpenClaw 与 Synology Chat
|
||||
- 调试 Synology Chat webhook 路由
|
||||
summary: Synology Chat webhook 设置与 OpenClaw 配置
|
||||
title: Synology Chat
|
||||
x-i18n:
|
||||
generated_at: "2026-03-16T06:20:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 7d77598ea759f89873a1edf0a3a7e7fedc1e4a7067709aaca6b999056a89eb1a
|
||||
source_path: channels/synology-chat.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Synology Chat（插件）
|
||||
|
||||
状态：通过插件支持，作为使用 Synology Chat webhook 的私信渠道。
|
||||
该插件接受来自 Synology Chat 出站 webhook 的入站消息，并通过 Synology Chat 入站 webhook 发送回复。
|
||||
|
||||
## 需要插件
|
||||
|
||||
Synology Chat 基于插件，不属于默认的核心渠道安装内容。
|
||||
|
||||
从本地检出安装：
|
||||
|
||||
```bash
|
||||
openclaw plugins install ./extensions/synology-chat
|
||||
```
|
||||
|
||||
详情：[插件](/tools/plugin)
|
||||
|
||||
## 快速设置
|
||||
|
||||
1. 安装并启用 Synology Chat 插件。
|
||||
- `openclaw onboard` 现在会在与 `openclaw channels add` 相同的渠道设置列表中显示 Synology Chat。
|
||||
- 非交互式设置：`openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
|
||||
2. 在 Synology Chat 集成中：
|
||||
- 创建一个入站 webhook 并复制其 URL。
|
||||
- 使用你的 secret token 创建一个出站 webhook。
|
||||
3. 将出站 webhook URL 指向你的 OpenClaw Gateway 网关：
|
||||
- 默认是 `https://gateway-host/webhook/synology`。
|
||||
- 或者使用你自定义的 `channels.synology-chat.webhookPath`。
|
||||
4. 在 OpenClaw 中完成设置。
|
||||
- 引导式：`openclaw onboard`
|
||||
- 直接设置：`openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
|
||||
5. 重启 Gateway 网关，并向 Synology Chat 机器人发送一条私信。
|
||||
|
||||
最小配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
"synology-chat": {
|
||||
enabled: true,
|
||||
token: "synology-outgoing-token",
|
||||
incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...",
|
||||
webhookPath: "/webhook/synology",
|
||||
dmPolicy: "allowlist",
|
||||
allowedUserIds: ["123456"],
|
||||
rateLimitPerMinute: 30,
|
||||
allowInsecureSsl: false,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 环境变量
|
||||
|
||||
对于默认账户，你可以使用环境变量：
|
||||
|
||||
- `SYNOLOGY_CHAT_TOKEN`
|
||||
- `SYNOLOGY_CHAT_INCOMING_URL`
|
||||
- `SYNOLOGY_NAS_HOST`
|
||||
- `SYNOLOGY_ALLOWED_USER_IDS`（逗号分隔）
|
||||
- `SYNOLOGY_RATE_LIMIT`
|
||||
- `OPENCLAW_BOT_NAME`
|
||||
|
||||
配置值会覆盖环境变量。
|
||||
|
||||
## 私信策略与访问控制
|
||||
|
||||
- 推荐的默认值是 `dmPolicy: "allowlist"`。
|
||||
- `allowedUserIds` 接受 Synology 用户 ID 列表（或逗号分隔字符串）。
|
||||
- 在 `allowlist` 模式下，空的 `allowedUserIds` 列表会被视为配置错误，webhook 路由将不会启动（如需允许所有人，请使用 `dmPolicy: "open"`）。
|
||||
- `dmPolicy: "open"` 允许任何发送方。
|
||||
- `dmPolicy: "disabled"` 会阻止私信。
|
||||
- 配对批准可配合以下命令使用：
|
||||
- `openclaw pairing list synology-chat`
|
||||
- `openclaw pairing approve synology-chat <CODE>`
|
||||
|
||||
## 出站投递
|
||||
|
||||
使用数字形式的 Synology Chat 用户 ID 作为目标。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw"
|
||||
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
|
||||
```
|
||||
|
||||
支持通过基于 URL 的文件投递发送媒体。
|
||||
|
||||
## 多账户
|
||||
|
||||
支持在 `channels.synology-chat.accounts` 下配置多个 Synology Chat 账户。
|
||||
每个账户都可以覆盖 token、入站 URL、webhook 路径、私信策略和限制。
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
"synology-chat": {
|
||||
enabled: true,
|
||||
accounts: {
|
||||
default: {
|
||||
token: "token-a",
|
||||
incomingUrl: "https://nas-a.example.com/...token=...",
|
||||
},
|
||||
alerts: {
|
||||
token: "token-b",
|
||||
incomingUrl: "https://nas-b.example.com/...token=...",
|
||||
webhookPath: "/webhook/synology-alerts",
|
||||
dmPolicy: "allowlist",
|
||||
allowedUserIds: ["987654"],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 安全说明
|
||||
|
||||
- 妥善保管 `token`，如果泄露请轮换。
|
||||
- 除非你明确可信任本地 NAS 的自签名证书，否则请保持 `allowInsecureSsl: false`。
|
||||
- 入站 webhook 请求会按 token 验证，并按发送方进行速率限制。
|
||||
- 生产环境优先使用 `dmPolicy: "allowlist"`。
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 添加或修改 CLI 命令或选项
|
||||
- 为新命令界面编写文档
|
||||
summary: OpenClaw `openclaw` 命令、子命令和选项的 CLI 参考
|
||||
- 添加或修改 CLI 命令或选项时
|
||||
- 为新的命令界面编写文档时
|
||||
summary: "`openclaw` 命令、子命令和选项的 OpenClaw CLI 参考"
|
||||
title: CLI 参考
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:47:54Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a73923763d7b89d4b183f569d543927ffbfd1f3e02f9e66639913f6daf226850
|
||||
generated_at: "2026-03-16T06:22:35Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a2bca34fca64558a8d91fc640ad3880e79677e81d0f605083edc6cbe86bfba53
|
||||
source_path: cli/index.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -23,8 +23,10 @@ x-i18n:
|
||||
- [`onboard`](/cli/onboard)
|
||||
- [`configure`](/cli/configure)
|
||||
- [`config`](/cli/config)
|
||||
- [`completion`](/cli/completion)
|
||||
- [`doctor`](/cli/doctor)
|
||||
- [`dashboard`](/cli/dashboard)
|
||||
- [`backup`](/cli/backup)
|
||||
- [`reset`](/cli/reset)
|
||||
- [`uninstall`](/cli/uninstall)
|
||||
- [`update`](/cli/update)
|
||||
@ -40,6 +42,7 @@ x-i18n:
|
||||
- [`system`](/cli/system)
|
||||
- [`models`](/cli/models)
|
||||
- [`memory`](/cli/memory)
|
||||
- [`directory`](/cli/directory)
|
||||
- [`nodes`](/cli/nodes)
|
||||
- [`devices`](/cli/devices)
|
||||
- [`node`](/cli/node)
|
||||
@ -53,42 +56,46 @@ x-i18n:
|
||||
- [`hooks`](/cli/hooks)
|
||||
- [`webhooks`](/cli/webhooks)
|
||||
- [`pairing`](/cli/pairing)
|
||||
- [`qr`](/cli/qr)
|
||||
- [`plugins`](/cli/plugins)（插件命令）
|
||||
- [`channels`](/cli/channels)
|
||||
- [`security`](/cli/security)
|
||||
- [`secrets`](/cli/secrets)
|
||||
- [`skills`](/cli/skills)
|
||||
- [`daemon`](/cli/daemon)（Gateway 网关服务命令的旧别名）
|
||||
- [`clawbot`](/cli/clawbot)（旧别名命名空间）
|
||||
- [`voicecall`](/cli/voicecall)（插件；如已安装）
|
||||
|
||||
## 全局标志
|
||||
|
||||
- `--dev`：将状态隔离到 `~/.openclaw-dev` 下并调整默认端口。
|
||||
- `--dev`：将状态隔离到 `~/.openclaw-dev` 下，并变更默认端口。
|
||||
- `--profile <name>`：将状态隔离到 `~/.openclaw-<name>` 下。
|
||||
- `--no-color`：禁用 ANSI 颜色。
|
||||
- `--update`：`openclaw update` 的简写（仅限源码安装）。
|
||||
- `-V`、`--version`、`-v`：打印版本并退出。
|
||||
- `--update`：`openclaw update` 的简写（仅适用于源码安装）。
|
||||
- `-V`, `--version`, `-v`：打印版本并退出。
|
||||
|
||||
## 输出样式
|
||||
|
||||
- ANSI 颜色和进度指示器仅在 TTY 会话中渲染。
|
||||
- OSC-8 超链接在支持的终端中渲染为可点击链接；否则回退到纯 URL。
|
||||
- `--json`（以及支持的地方使用 `--plain`）禁用样式以获得干净输出。
|
||||
- `--no-color` 禁用 ANSI 样式；也支持 `NO_COLOR=1`。
|
||||
- 长时间运行的命令显示进度指示器（支持时使用 OSC 9;4）。
|
||||
- OSC-8 超链接会在受支持的终端中显示为可点击链接；否则会回退为纯 URL。
|
||||
- `--json`（以及在支持处的 `--plain`）会禁用样式，以获得干净输出。
|
||||
- `--no-color` 会禁用 ANSI 样式；同时也支持 `NO_COLOR=1`。
|
||||
- 长时间运行的命令会显示进度指示器（支持时使用 OSC 9;4）。
|
||||
|
||||
## 颜色调色板
|
||||
## 调色板
|
||||
|
||||
OpenClaw 在 CLI 输出中使用龙虾调色板。
|
||||
OpenClaw 在 CLI 输出中使用龙虾色调调色板。
|
||||
|
||||
- `accent`（#FF5A2D）：标题、标签、主要高亮。
|
||||
- `accentBright`（#FF7A3D）：命令名称、强调。
|
||||
- `accentDim`（#D14A22）：次要高亮文本。
|
||||
- `info`（#FF8A5B）：信息性值。
|
||||
- `success`（#2FBF71）：成功状态。
|
||||
- `warn`（#FFB020）：警告、回退、注意。
|
||||
- `error`（#E23D2D）：错误、失败。
|
||||
- `muted`（#8B7F77）：弱化、元数据。
|
||||
- `accent` (#FF5A2D)：标题、标签、主要高亮。
|
||||
- `accentBright` (#FF7A3D)：命令名称、强调。
|
||||
- `accentDim` (#D14A22)：次级高亮文本。
|
||||
- `info` (#FF8A5B)：信息性值。
|
||||
- `success` (#2FBF71)：成功状态。
|
||||
- `warn` (#FFB020)：警告、回退、注意事项。
|
||||
- `error` (#E23D2D)：错误、失败。
|
||||
- `muted` (#8B7F77)：弱化显示、元数据。
|
||||
|
||||
调色板权威来源：`src/terminal/palette.ts`（又名"lobster seam"）。
|
||||
调色板唯一来源：`src/terminal/palette.ts`（也称为 “lobster seam”）。
|
||||
|
||||
## 命令树
|
||||
|
||||
@ -101,9 +108,17 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
get
|
||||
set
|
||||
unset
|
||||
completion
|
||||
doctor
|
||||
dashboard
|
||||
backup
|
||||
create
|
||||
verify
|
||||
security
|
||||
audit
|
||||
secrets
|
||||
reload
|
||||
migrate
|
||||
reset
|
||||
uninstall
|
||||
update
|
||||
@ -115,6 +130,7 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
remove
|
||||
login
|
||||
logout
|
||||
directory
|
||||
skills
|
||||
list
|
||||
info
|
||||
@ -152,6 +168,13 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
stop
|
||||
restart
|
||||
run
|
||||
daemon
|
||||
status
|
||||
install
|
||||
uninstall
|
||||
start
|
||||
stop
|
||||
restart
|
||||
logs
|
||||
system
|
||||
event
|
||||
@ -238,49 +261,59 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
pairing
|
||||
list
|
||||
approve
|
||||
qr
|
||||
clawbot
|
||||
qr
|
||||
docs
|
||||
dns
|
||||
setup
|
||||
tui
|
||||
```
|
||||
|
||||
注意：插件可以添加额外的顶级命令（例如 `openclaw voicecall`）。
|
||||
注意：插件可以添加额外的顶层命令（例如 `openclaw voicecall`）。
|
||||
|
||||
## 安全
|
||||
|
||||
- `openclaw security audit` — 审计配置 + 本地状态中常见的安全隐患。
|
||||
- `openclaw security audit` — 审计配置 + 本地状态中常见的安全陷阱。
|
||||
- `openclaw security audit --deep` — 尽力进行实时 Gateway 网关探测。
|
||||
- `openclaw security audit --fix` — 收紧安全默认值并 chmod 状态/配置。
|
||||
- `openclaw security audit --fix` — 收紧安全默认值并对状态 / 配置执行 chmod。
|
||||
|
||||
## 密钥
|
||||
|
||||
- `openclaw secrets reload` — 重新解析引用，并以原子方式替换运行时快照。
|
||||
- `openclaw secrets audit` — 扫描明文残留、未解析引用和优先级漂移。
|
||||
- `openclaw secrets configure` — 用于提供商设置 + SecretRef 映射 + 预检 / 应用的交互式助手。
|
||||
- `openclaw secrets apply --from <plan.json>` — 应用先前生成的计划（支持 `--dry-run`）。
|
||||
|
||||
## 插件
|
||||
|
||||
管理扩展及其配置：
|
||||
|
||||
- `openclaw plugins list` — 发现插件（使用 `--json` 获取机器可读输出）。
|
||||
- `openclaw plugins list` — 发现插件（机器输出请使用 `--json`）。
|
||||
- `openclaw plugins info <id>` — 显示插件详情。
|
||||
- `openclaw plugins install <path|.tgz|npm-spec>` — 安装插件（或将插件路径添加到 `plugins.load.paths`）。
|
||||
- `openclaw plugins enable <id>` / `disable <id>` — 切换 `plugins.entries.<id>.enabled`。
|
||||
- `openclaw plugins doctor` — 报告插件加载错误。
|
||||
|
||||
大多数插件更改需要重启 Gateway 网关。参见 [/plugin](/tools/plugin)。
|
||||
大多数插件更改都需要重启 gateway。参见 [/plugin](/tools/plugin)。
|
||||
|
||||
## 记忆
|
||||
## 内存
|
||||
|
||||
对 `MEMORY.md` + `memory/*.md` 进行向量搜索：
|
||||
对 `MEMORY.md` + `memory/*.md` 执行向量搜索：
|
||||
|
||||
- `openclaw memory status` — 显示索引统计。
|
||||
- `openclaw memory index` — 重新索引记忆文件。
|
||||
- `openclaw memory search "<query>"` — 对记忆进行语义搜索。
|
||||
- `openclaw memory status` — 显示索引统计信息。
|
||||
- `openclaw memory index` — 重新索引内存文件。
|
||||
- `openclaw memory search "<query>"`（或 `--query "<query>"`）— 对内存执行语义搜索。
|
||||
|
||||
## 聊天斜杠命令
|
||||
|
||||
聊天消息支持 `/...` 命令（文本和原生）。参见 [/tools/slash-commands](/tools/slash-commands)。
|
||||
|
||||
亮点：
|
||||
重点：
|
||||
|
||||
- `/status` 用于快速诊断。
|
||||
- `/config` 用于持久化配置更改。
|
||||
- `/debug` 用于仅运行时的配置覆盖（内存中，不写入磁盘；需要 `commands.debug: true`）。
|
||||
- `/debug` 用于仅运行时的配置覆盖（内存中，不写磁盘；要求 `commands.debug: true`）。
|
||||
|
||||
## 设置 + 新手引导
|
||||
|
||||
@ -291,32 +324,35 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
选项：
|
||||
|
||||
- `--workspace <dir>`：智能体工作区路径（默认 `~/.openclaw/workspace`）。
|
||||
- `--wizard`：运行新手引导向导。
|
||||
- `--wizard`：运行设置向导。
|
||||
- `--non-interactive`：无提示运行向导。
|
||||
- `--mode <local|remote>`：向导模式。
|
||||
- `--remote-url <url>`：远程 Gateway 网关 URL。
|
||||
- `--remote-token <token>`：远程 Gateway 网关令牌。
|
||||
- `--remote-token <token>`：远程 Gateway 网关 token。
|
||||
|
||||
当存在任何向导标志（`--non-interactive`、`--mode`、`--remote-url`、`--remote-token`）时，向导自动运行。
|
||||
只要存在任意向导标志（`--non-interactive`, `--mode`, `--remote-url`, `--remote-token`），就会自动运行向导。
|
||||
|
||||
### `onboard`
|
||||
|
||||
交互式向导，用于设置 Gateway 网关、工作区和 Skills。
|
||||
用于设置 gateway、工作区和 Skills 的交互式向导。
|
||||
|
||||
选项：
|
||||
|
||||
- `--workspace <dir>`
|
||||
- `--reset`（在向导之前重置配置 + 凭证 + 会话 + 工作区）
|
||||
- `--reset`（在运行向导前重置配置 + 凭据 + 会话）
|
||||
- `--reset-scope <config|config+creds+sessions|full>`（默认 `config+creds+sessions`；使用 `full` 还会删除工作区）
|
||||
- `--non-interactive`
|
||||
- `--mode <local|remote>`
|
||||
- `--flow <quickstart|advanced|manual>`（manual 是 advanced 的别名）
|
||||
- `--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip>`
|
||||
- `--token-provider <id>`（非交互式；与 `--auth-choice token` 配合使用）
|
||||
- `--token <token>`（非交互式；与 `--auth-choice token` 配合使用）
|
||||
- `--flow <quickstart|advanced|manual>`（`manual` 是 `advanced` 的别名）
|
||||
- `--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ollama|ai-gateway-api-key|moonshot-api-key|moonshot-api-key-cn|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|mistral-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|opencode-go|custom-api-key|skip>`
|
||||
- `--token-provider <id>`（非交互式；与 `--auth-choice token` 一起使用）
|
||||
- `--token <token>`（非交互式；与 `--auth-choice token` 一起使用）
|
||||
- `--token-profile-id <id>`（非交互式；默认：`<provider>:manual`）
|
||||
- `--token-expires-in <duration>`（非交互式；例如 `365d`、`12h`）
|
||||
- `--secret-input-mode <plaintext|ref>`（默认 `plaintext`；使用 `ref` 可存储提供商默认环境引用，而非明文密钥）
|
||||
- `--anthropic-api-key <key>`
|
||||
- `--openai-api-key <key>`
|
||||
- `--mistral-api-key <key>`
|
||||
- `--openrouter-api-key <key>`
|
||||
- `--ai-gateway-api-key <key>`
|
||||
- `--moonshot-api-key <key>`
|
||||
@ -325,10 +361,17 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
- `--zai-api-key <key>`
|
||||
- `--minimax-api-key <key>`
|
||||
- `--opencode-zen-api-key <key>`
|
||||
- `--opencode-go-api-key <key>`
|
||||
- `--custom-base-url <url>`（非交互式；与 `--auth-choice custom-api-key` 或 `--auth-choice ollama` 一起使用）
|
||||
- `--custom-model-id <id>`（非交互式；与 `--auth-choice custom-api-key` 或 `--auth-choice ollama` 一起使用）
|
||||
- `--custom-api-key <key>`（非交互式；可选；与 `--auth-choice custom-api-key` 一起使用；省略时回退到 `CUSTOM_API_KEY`）
|
||||
- `--custom-provider-id <id>`（非交互式；可选自定义提供商 id）
|
||||
- `--custom-compatibility <openai|anthropic>`（非交互式；可选；默认 `openai`）
|
||||
- `--gateway-port <port>`
|
||||
- `--gateway-bind <loopback|lan|tailnet|auto|custom>`
|
||||
- `--gateway-auth <token|password>`
|
||||
- `--gateway-token <token>`
|
||||
- `--gateway-token-ref-env <name>`（非交互式；将 `gateway.auth.token` 存储为环境 SecretRef；要求该环境变量已设置；不能与 `--gateway-token` 一起使用）
|
||||
- `--gateway-password <password>`
|
||||
- `--remote-url <url>`
|
||||
- `--remote-token <token>`
|
||||
@ -341,35 +384,39 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
- `--skip-skills`
|
||||
- `--skip-health`
|
||||
- `--skip-ui`
|
||||
- `--node-manager <npm|pnpm|bun>`（推荐 pnpm；不建议将 bun 用于 Gateway 网关运行时）
|
||||
- `--node-manager <npm|pnpm|bun>`（推荐 pnpm；不推荐将 bun 用作 Gateway 网关运行时）
|
||||
- `--json`
|
||||
|
||||
### `configure`
|
||||
|
||||
交互式配置向导（模型、渠道、Skills、Gateway 网关）。
|
||||
交互式配置向导（模型、渠道、Skills、gateway）。
|
||||
|
||||
### `config`
|
||||
|
||||
非交互式配置辅助工具（get/set/unset）。不带子命令运行 `openclaw config` 会启动向导。
|
||||
非交互式配置助手（get/set/unset/file/validate）。直接运行 `openclaw config` 而不带
|
||||
子命令会启动向导。
|
||||
|
||||
子命令：
|
||||
|
||||
- `config get <path>`：打印配置值（点/括号路径）。
|
||||
- `config set <path> <value>`：设置值（JSON5 或原始字符串）。
|
||||
- `config unset <path>`：删除值。
|
||||
- `config get <path>`：打印一个配置值（点 / 方括号路径）。
|
||||
- `config set <path> <value>`：设置一个值（JSON5 或原始字符串）。
|
||||
- `config unset <path>`：移除一个值。
|
||||
- `config file`：打印当前活动配置文件路径。
|
||||
- `config validate`：根据 schema 验证当前配置，而不启动 gateway。
|
||||
- `config validate --json`：输出机器可读的 JSON。
|
||||
|
||||
### `doctor`
|
||||
|
||||
健康检查 + 快速修复（配置 + Gateway 网关 + 旧版服务）。
|
||||
健康检查 + 快速修复（配置 + gateway + 旧版服务）。
|
||||
|
||||
选项：
|
||||
|
||||
- `--no-workspace-suggestions`：禁用工作区记忆提示。
|
||||
- `--yes`：无提示接受默认值（无头模式）。
|
||||
- `--no-workspace-suggestions`：禁用工作区内存提示。
|
||||
- `--yes`：接受默认值而不提示（无头）。
|
||||
- `--non-interactive`：跳过提示；仅应用安全迁移。
|
||||
- `--deep`：扫描系统服务以查找额外的 Gateway 网关安装。
|
||||
- `--deep`：扫描系统服务以查找额外的 gateway 安装。
|
||||
|
||||
## 渠道辅助工具
|
||||
## 渠道助手
|
||||
|
||||
### `channels`
|
||||
|
||||
@ -378,19 +425,21 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
子命令：
|
||||
|
||||
- `channels list`：显示已配置的渠道和认证配置文件。
|
||||
- `channels status`：检查 Gateway 网关可达性和渠道健康状况（`--probe` 运行额外检查；使用 `openclaw health` 或 `openclaw status --deep` 进行 Gateway 网关健康探测）。
|
||||
- 提示：`channels status` 在检测到常见配置错误时会打印带有建议修复的警告（然后指向 `openclaw doctor`）。
|
||||
- `channels logs`：显示 Gateway 网关日志文件中最近的渠道日志。
|
||||
- `channels add`：不传标志时使用向导式设置；标志切换到非交互模式。
|
||||
- `channels remove`：默认禁用；传 `--delete` 可无提示删除配置条目。
|
||||
- `channels login`：交互式渠道登录（仅限 WhatsApp Web）。
|
||||
- `channels logout`：登出渠道会话（如支持）。
|
||||
- `channels status`：检查 gateway 可达性和渠道健康状态（`--probe` 会运行额外检查；gateway 健康探测请使用 `openclaw health` 或 `openclaw status --deep`）。
|
||||
- 提示：如果能够检测到常见配置错误，`channels status` 会打印带建议修复方式的警告（随后指向 `openclaw doctor`）。
|
||||
- `channels logs`：显示 gateway 日志文件中的最近渠道日志。
|
||||
- `channels add`：未传入任何标志时为向导式设置；传入标志后切换为非交互模式。
|
||||
- 当向仍使用单账户顶层配置的渠道添加非默认账户时，OpenClaw 会先将账户作用域值移动到 `channels.<channel>.accounts.default`，再写入新账户。
|
||||
- 非交互式 `channels add` 不会自动创建 / 升级绑定；仅渠道绑定会继续匹配默认账户。
|
||||
- `channels remove`：默认执行禁用；传入 `--delete` 可在无提示下删除配置项。
|
||||
- `channels login`：交互式渠道登录（仅 WhatsApp Web）。
|
||||
- `channels logout`：登出某个渠道会话（如支持）。
|
||||
|
||||
通用选项：
|
||||
|
||||
- `--channel <name>`：`whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams`
|
||||
- `--account <id>`：渠道账户 id（默认 `default`）
|
||||
- `--name <label>`：账户的显示名称
|
||||
- `--name <label>`：账户显示名称
|
||||
|
||||
`channels login` 选项：
|
||||
|
||||
@ -405,8 +454,8 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
|
||||
`channels list` 选项：
|
||||
|
||||
- `--no-usage`：跳过模型提供商用量/配额快照（仅限 OAuth/API 支持的）。
|
||||
- `--json`：输出 JSON（除非设置 `--no-usage`，否则包含用量）。
|
||||
- `--no-usage`：跳过模型提供商用量 / 配额快照（仅 OAuth / API 支持）。
|
||||
- `--json`：输出 JSON（除非设置了 `--no-usage`，否则包含用量）。
|
||||
|
||||
`channels logs` 选项：
|
||||
|
||||
@ -414,7 +463,7 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
- `--lines <n>`（默认 `200`）
|
||||
- `--json`
|
||||
|
||||
更多详情：[/concepts/oauth](/concepts/oauth)
|
||||
更多细节：[/concepts/oauth](/concepts/oauth)
|
||||
|
||||
示例：
|
||||
|
||||
@ -428,19 +477,19 @@ openclaw status --deep
|
||||
|
||||
### `skills`
|
||||
|
||||
列出和检查可用的 Skills 及就绪信息。
|
||||
列出并检查可用 Skills，以及就绪信息。
|
||||
|
||||
子命令：
|
||||
|
||||
- `skills list`：列出 Skills（无子命令时的默认行为）。
|
||||
- `skills list`：列出 Skills（未指定子命令时的默认行为）。
|
||||
- `skills info <name>`：显示单个 Skill 的详情。
|
||||
- `skills check`：就绪与缺失需求的摘要。
|
||||
- `skills check`：汇总已就绪与缺失的要求。
|
||||
|
||||
选项：
|
||||
|
||||
- `--eligible`：仅显示就绪的 Skills。
|
||||
- `--eligible`：仅显示已就绪的 Skills。
|
||||
- `--json`：输出 JSON（无样式）。
|
||||
- `-v`、`--verbose`：包含缺失需求详情。
|
||||
- `-v`, `--verbose`：包含缺失要求的详细信息。
|
||||
|
||||
提示：使用 `npx clawhub` 搜索、安装和同步 Skills。
|
||||
|
||||
@ -450,31 +499,46 @@ openclaw status --deep
|
||||
|
||||
子命令：
|
||||
|
||||
- `pairing list <channel> [--json]`
|
||||
- `pairing approve <channel> <code> [--notify]`
|
||||
- `pairing list [channel] [--channel <channel>] [--account <id>] [--json]`
|
||||
- `pairing approve <channel> <code> [--account <id>] [--notify]`
|
||||
- `pairing approve --channel <channel> [--account <id>] <code> [--notify]`
|
||||
|
||||
### `webhooks gmail`
|
||||
### `devices`
|
||||
|
||||
Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/automation/gmail-pubsub)。
|
||||
管理 gateway 设备配对条目和按角色划分的设备 token。
|
||||
|
||||
子命令：
|
||||
|
||||
- `webhooks gmail setup`（需要 `--account <email>`；支持 `--project`、`--topic`、`--subscription`、`--label`、`--hook-url`、`--hook-token`、`--push-token`、`--bind`、`--port`、`--path`、`--include-body`、`--max-bytes`、`--renew-minutes`、`--tailscale`、`--tailscale-path`、`--tailscale-target`、`--push-endpoint`、`--json`）
|
||||
- `webhooks gmail run`（相同标志的运行时覆盖）
|
||||
- `devices list [--json]`
|
||||
- `devices approve [requestId] [--latest]`
|
||||
- `devices reject <requestId>`
|
||||
- `devices remove <deviceId>`
|
||||
- `devices clear --yes [--pending]`
|
||||
- `devices rotate --device <id> --role <role> [--scope <scope...>]`
|
||||
- `devices revoke --device <id> --role <role>`
|
||||
|
||||
### `webhooks gmail`
|
||||
|
||||
Gmail Pub/Sub hook 设置 + 运行器。参见 [/automation/gmail-pubsub](/automation/gmail-pubsub)。
|
||||
|
||||
子命令：
|
||||
|
||||
- `webhooks gmail setup`（要求 `--account <email>`；支持 `--project`, `--topic`, `--subscription`, `--label`, `--hook-url`, `--hook-token`, `--push-token`, `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes`, `--tailscale`, `--tailscale-path`, `--tailscale-target`, `--push-endpoint`, `--json`）
|
||||
- `webhooks gmail run`（对相同标志进行运行时覆盖）
|
||||
|
||||
### `dns setup`
|
||||
|
||||
广域发现 DNS 辅助工具（CoreDNS + Tailscale）。参见 [/gateway/discovery](/gateway/discovery)。
|
||||
广域设备发现 DNS 助手（CoreDNS + Tailscale）。参见 [/gateway/discovery](/gateway/discovery)。
|
||||
|
||||
选项：
|
||||
|
||||
- `--apply`：安装/更新 CoreDNS 配置（需要 sudo；仅限 macOS）。
|
||||
- `--apply`：安装 / 更新 CoreDNS 配置（需要 sudo；仅 macOS）。
|
||||
|
||||
## 消息 + 智能体
|
||||
|
||||
### `message`
|
||||
|
||||
统一的出站消息 + 渠道操作。
|
||||
统一的出站消息发送 + 渠道操作。
|
||||
|
||||
参见：[/cli/message](/cli/message)
|
||||
|
||||
@ -497,17 +561,17 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
|
||||
### `agent`
|
||||
|
||||
通过 Gateway 网关运行一个智能体回合（或使用 `--local` 嵌入式运行）。
|
||||
通过 Gateway 网关（或 `--local` 嵌入模式）运行一次智能体轮次。
|
||||
|
||||
必需：
|
||||
必需项：
|
||||
|
||||
- `--message <text>`
|
||||
|
||||
选项：
|
||||
|
||||
- `--to <dest>`（用于会话键和可选发送）
|
||||
- `--to <dest>`（用于会话键以及可选投递）
|
||||
- `--session-id <id>`
|
||||
- `--thinking <off|minimal|low|medium|high|xhigh>`（仅限 GPT-5.2 + Codex 模型）
|
||||
- `--thinking <off|minimal|low|medium|high|xhigh>`（仅适用于 GPT-5.2 + Codex 模型）
|
||||
- `--verbose <on|full|off>`
|
||||
- `--channel <whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams>`
|
||||
- `--local`
|
||||
@ -530,7 +594,7 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
|
||||
#### `agents add [name]`
|
||||
|
||||
添加新的隔离智能体。除非传入标志（或 `--non-interactive`），否则运行引导向导；非交互模式下 `--workspace` 是必需的。
|
||||
添加一个新的隔离智能体。除非传入标志（或 `--non-interactive`），否则会运行引导式向导；在非交互模式下必须提供 `--workspace`。
|
||||
|
||||
选项：
|
||||
|
||||
@ -541,11 +605,41 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
- `--non-interactive`
|
||||
- `--json`
|
||||
|
||||
绑定规范使用 `channel[:accountId]`。对于 WhatsApp，省略 `accountId` 时使用默认账户 id。
|
||||
绑定规范使用 `channel[:accountId]`。省略 `accountId` 时，OpenClaw 可能通过渠道默认值 / 插件 hook 解析账户作用域；否则这就是不带显式账户作用域的渠道绑定。
|
||||
|
||||
#### `agents bindings`
|
||||
|
||||
列出路由绑定。
|
||||
|
||||
选项：
|
||||
|
||||
- `--agent <id>`
|
||||
- `--json`
|
||||
|
||||
#### `agents bind`
|
||||
|
||||
为智能体添加路由绑定。
|
||||
|
||||
选项：
|
||||
|
||||
- `--agent <id>`
|
||||
- `--bind <channel[:accountId]>`（可重复）
|
||||
- `--json`
|
||||
|
||||
#### `agents unbind`
|
||||
|
||||
移除智能体的路由绑定。
|
||||
|
||||
选项：
|
||||
|
||||
- `--agent <id>`
|
||||
- `--bind <channel[:accountId]>`（可重复）
|
||||
- `--all`
|
||||
- `--json`
|
||||
|
||||
#### `agents delete <id>`
|
||||
|
||||
删除智能体并清理其工作区 + 状态。
|
||||
删除一个智能体并清理其工作区 + 状态。
|
||||
|
||||
选项：
|
||||
|
||||
@ -554,44 +648,44 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
|
||||
### `acp`
|
||||
|
||||
运行连接 IDE 到 Gateway 网关的 ACP 桥接。
|
||||
运行将 IDE 连接到 Gateway 网关的 ACP 桥接器。
|
||||
|
||||
完整选项和示例参见 [`acp`](/cli/acp)。
|
||||
完整选项和示例请参见 [`acp`](/cli/acp)。
|
||||
|
||||
### `status`
|
||||
|
||||
显示关联会话健康状况和最近的收件人。
|
||||
显示已链接会话的健康状态和最近收件人。
|
||||
|
||||
选项：
|
||||
|
||||
- `--json`
|
||||
- `--all`（完整诊断；只读，可粘贴）
|
||||
- `--all`（完整诊断；只读、可粘贴）
|
||||
- `--deep`（探测渠道）
|
||||
- `--usage`（显示模型提供商用量/配额）
|
||||
- `--usage`（显示模型提供商用量 / 配额）
|
||||
- `--timeout <ms>`
|
||||
- `--verbose`
|
||||
- `--debug`（`--verbose` 的别名）
|
||||
|
||||
说明：
|
||||
|
||||
- 概览包含 Gateway 网关 + 节点主机服务状态（如可用）。
|
||||
- 概览中会在可用时包含 Gateway 网关 + node host 服务状态。
|
||||
|
||||
### 用量跟踪
|
||||
|
||||
当 OAuth/API 凭证可用时，OpenClaw 可以显示提供商用量/配额。
|
||||
在 OAuth / API 凭据可用时，OpenClaw 可以显示提供商用量 / 配额。
|
||||
|
||||
显示位置：
|
||||
展示位置：
|
||||
|
||||
- `/status`（可用时添加简短的提供商用量行）
|
||||
- `/status`（可用时添加一行简短的提供商用量信息）
|
||||
- `openclaw status --usage`（打印完整的提供商明细）
|
||||
- macOS 菜单栏（上下文下的用量部分）
|
||||
- macOS 菜单栏（Context 下的 Usage 部分）
|
||||
|
||||
说明：
|
||||
|
||||
- 数据直接来自提供商用量端点（非估算）。
|
||||
- 提供商：Anthropic、GitHub Copilot、OpenAI Codex OAuth，以及通过捆绑 `google` 插件提供的 Gemini CLI 和已配置的 Antigravity。
|
||||
- 如果没有匹配的凭证，用量会被隐藏。
|
||||
- 详情：参见[用量跟踪](/concepts/usage-tracking)。
|
||||
- 数据直接来自提供商用量端点（不是估算值）。
|
||||
- 提供商：Anthropic、GitHub Copilot、OpenAI Codex OAuth，以及打包的 `google` 插件所提供的 Gemini CLI 和在已配置情况下的 Antigravity。
|
||||
- 如果不存在匹配的凭据，则不会显示用量。
|
||||
- 详情：参见 [用量跟踪](/concepts/usage-tracking)。
|
||||
|
||||
### `health`
|
||||
|
||||
@ -605,7 +699,7 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
|
||||
### `sessions`
|
||||
|
||||
列出存储的对话会话。
|
||||
列出已存储的对话会话。
|
||||
|
||||
选项：
|
||||
|
||||
@ -614,11 +708,11 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
- `--store <path>`
|
||||
- `--active <minutes>`
|
||||
|
||||
## 重置/卸载
|
||||
## 重置 / 卸载
|
||||
|
||||
### `reset`
|
||||
|
||||
重置本地配置/状态（保留 CLI 安装）。
|
||||
重置本地配置 / 状态（保留已安装的 CLI）。
|
||||
|
||||
选项：
|
||||
|
||||
@ -629,11 +723,11 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
|
||||
说明：
|
||||
|
||||
- `--non-interactive` 需要 `--scope` 和 `--yes`。
|
||||
- `--non-interactive` 要求同时提供 `--scope` 和 `--yes`。
|
||||
|
||||
### `uninstall`
|
||||
|
||||
卸载 Gateway 网关服务 + 本地数据（CLI 保留）。
|
||||
卸载 gateway 服务 + 本地数据（CLI 保留）。
|
||||
|
||||
选项：
|
||||
|
||||
@ -648,7 +742,7 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
|
||||
说明：
|
||||
|
||||
- `--non-interactive` 需要 `--yes` 和明确的范围（或 `--all`）。
|
||||
- `--non-interactive` 要求 `--yes` 和显式作用域（或 `--all`）。
|
||||
|
||||
## Gateway 网关
|
||||
|
||||
@ -663,12 +757,13 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
- `--token <token>`
|
||||
- `--auth <token|password>`
|
||||
- `--password <password>`
|
||||
- `--password-file <path>`
|
||||
- `--tailscale <off|serve|funnel>`
|
||||
- `--tailscale-reset-on-exit`
|
||||
- `--allow-unconfigured`
|
||||
- `--dev`
|
||||
- `--reset`（重置 dev 配置 + 凭证 + 会话 + 工作区）
|
||||
- `--force`（终止端口上的现有监听器）
|
||||
- `--reset`（重置 dev 配置 + 凭据 + 会话 + 工作区）
|
||||
- `--force`（杀掉端口上的现有监听器）
|
||||
- `--verbose`
|
||||
- `--claude-cli-logs`
|
||||
- `--ws-log <auto|full|compact>`
|
||||
@ -683,7 +778,7 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
子命令：
|
||||
|
||||
- `gateway status`（默认探测 Gateway 网关 RPC）
|
||||
- `gateway install`（服务安装）
|
||||
- `gateway install`（安装服务）
|
||||
- `gateway uninstall`
|
||||
- `gateway start`
|
||||
- `gateway stop`
|
||||
@ -691,12 +786,14 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
|
||||
说明：
|
||||
|
||||
- `gateway status` 默认使用服务解析的端口/配置探测 Gateway 网关 RPC（使用 `--url/--token/--password` 覆盖）。
|
||||
- `gateway status` 支持 `--no-probe`、`--deep` 和 `--json` 用于脚本化。
|
||||
- `gateway status` 在检测到旧版或额外的 Gateway 网关服务时也会显示（`--deep` 添加系统级扫描）。配置文件命名的 OpenClaw 服务被视为一等公民，不会被标记为"额外"。
|
||||
- `gateway status` 打印 CLI 使用的配置路径与服务可能使用的配置（服务环境），以及解析的探测目标 URL。
|
||||
- `gateway install|uninstall|start|stop|restart` 支持 `--json` 用于脚本化（默认输出保持人类友好）。
|
||||
- `gateway install` 默认使用 Node 运行时；**不建议**使用 bun（WhatsApp/Telegram bug）。
|
||||
- `gateway status` 默认使用服务解析出的端口 / 配置来探测 Gateway 网关 RPC（可用 `--url/--token/--password` 覆盖）。
|
||||
- `gateway status` 支持 `--no-probe`、`--deep`、`--require-rpc` 和 `--json`，便于脚本化。
|
||||
- `gateway status` 还能在检测到时显示旧版或额外的 gateway 服务（`--deep` 会增加系统级扫描）。带 profile 名称的 OpenClaw 服务会被视为一等公民，不会标记为“额外”。
|
||||
- `gateway status` 会打印 CLI 使用的是哪个配置路径、服务可能使用的是哪个配置（服务环境），以及解析出的探测目标 URL。
|
||||
- 如果 gateway 认证 SecretRef 在当前命令路径中未解析，`gateway status --json` 仅会在探测连接 / 认证失败时报告 `rpc.authWarning`（探测成功时会抑制警告）。
|
||||
- 在 Linux systemd 安装中，状态 token 漂移检查同时包括 `Environment=` 和 `EnvironmentFile=` 单元来源。
|
||||
- `gateway install|uninstall|start|stop|restart` 支持 `--json`，便于脚本化（默认输出仍然更适合人类阅读）。
|
||||
- `gateway install` 默认使用 Node 运行时；**不推荐** bun（存在 WhatsApp / Telegram bug）。
|
||||
- `gateway install` 选项：`--port`、`--runtime`、`--token`、`--force`、`--json`。
|
||||
|
||||
### `logs`
|
||||
@ -705,8 +802,8 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
|
||||
|
||||
说明：
|
||||
|
||||
- TTY 会话渲染彩色、结构化视图；非 TTY 回退到纯文本。
|
||||
- `--json` 输出行分隔的 JSON（每行一个日志事件）。
|
||||
- TTY 会话会渲染彩色的结构化视图；非 TTY 会回退为纯文本。
|
||||
- `--json` 会输出逐行 JSON（每行一个日志事件）。
|
||||
|
||||
示例：
|
||||
|
||||
@ -720,7 +817,9 @@ openclaw logs --no-color
|
||||
|
||||
### `gateway <subcommand>`
|
||||
|
||||
Gateway 网关 CLI 辅助工具（RPC 子命令使用 `--url`、`--token`、`--password`、`--timeout`、`--expect-final`）。
|
||||
Gateway 网关 CLI 助手（RPC 子命令可使用 `--url`、`--token`、`--password`、`--timeout`、`--expect-final`）。
|
||||
当你传入 `--url` 时，CLI 不会自动应用配置或环境凭据。
|
||||
请显式包含 `--token` 或 `--password`。缺少显式凭据会报错。
|
||||
|
||||
子命令：
|
||||
|
||||
@ -738,13 +837,14 @@ Gateway 网关 CLI 辅助工具（RPC 子命令使用 `--url`、`--token`、`--p
|
||||
- `config.patch`（合并部分更新 + 重启 + 唤醒）
|
||||
- `update.run`（运行更新 + 重启 + 唤醒）
|
||||
|
||||
提示：直接调用 `config.set`/`config.apply`/`config.patch` 时，如果配置已存在，请传入来自 `config.get` 的 `baseHash`。
|
||||
提示：直接调用 `config.set`/`config.apply`/`config.patch` 时，如果配置已存在，请从
|
||||
`config.get` 传入 `baseHash`。
|
||||
|
||||
## 模型
|
||||
|
||||
回退行为和扫描策略参见 [/concepts/models](/concepts/models)。
|
||||
关于回退行为和扫描策略，请参见 [/concepts/models](/concepts/models)。
|
||||
|
||||
首选 Anthropic 认证（setup-token）：
|
||||
Anthropic setup-token（已支持）：
|
||||
|
||||
```bash
|
||||
claude setup-token
|
||||
@ -752,6 +852,10 @@ openclaw models auth setup-token --provider anthropic
|
||||
openclaw models status
|
||||
```
|
||||
|
||||
策略说明：这是技术兼容性。Anthropic 过去曾阻止某些
|
||||
Claude Code 之外的订阅使用；在生产环境依赖 setup-token 之前，请确认当前的 Anthropic
|
||||
条款。
|
||||
|
||||
### `models`（根命令）
|
||||
|
||||
`openclaw models` 是 `models status` 的别名。
|
||||
@ -777,15 +881,16 @@ openclaw models status
|
||||
|
||||
- `--json`
|
||||
- `--plain`
|
||||
- `--check`（退出码 1=过期/缺失，2=即将过期）
|
||||
- `--check`（退出码 1=已过期 / 缺失，2=即将过期）
|
||||
- `--probe`（对已配置认证配置文件进行实时探测）
|
||||
- `--probe-provider <name>`
|
||||
- `--probe-profile <id>`（重复或逗号分隔）
|
||||
- `--probe-profile <id>`（可重复或逗号分隔）
|
||||
- `--probe-timeout <ms>`
|
||||
- `--probe-concurrency <n>`
|
||||
- `--probe-max-tokens <n>`
|
||||
|
||||
始终包含认证概览和认证存储中配置文件的 OAuth 过期状态。`--probe` 运行实时请求（可能消耗令牌并触发速率限制）。
|
||||
始终包含认证总览以及认证存储中配置文件的 OAuth 过期状态。
|
||||
`--probe` 会发起实时请求（可能消耗 token 并触发速率限制）。
|
||||
|
||||
### `models set <model>`
|
||||
|
||||
@ -842,7 +947,7 @@ openclaw models status
|
||||
|
||||
选项：
|
||||
|
||||
- `add`：交互式认证辅助工具
|
||||
- `add`：交互式认证助手
|
||||
- `setup-token`：`--provider <name>`（默认 `anthropic`）、`--yes`
|
||||
- `paste-token`：`--provider <name>`、`--profile-id <id>`、`--expires-in <duration>`
|
||||
|
||||
@ -858,9 +963,9 @@ openclaw models status
|
||||
|
||||
### `system event`
|
||||
|
||||
将系统事件加入队列并可选触发心跳（Gateway 网关 RPC）。
|
||||
将一个系统事件加入队列，并可选择触发一次 heartbeat（Gateway 网关 RPC）。
|
||||
|
||||
必需：
|
||||
必需项：
|
||||
|
||||
- `--text <text>`
|
||||
|
||||
@ -868,47 +973,48 @@ openclaw models status
|
||||
|
||||
- `--mode <now|next-heartbeat>`
|
||||
- `--json`
|
||||
- `--url`、`--token`、`--timeout`、`--expect-final`
|
||||
- `--url`, `--token`, `--timeout`, `--expect-final`
|
||||
|
||||
### `system heartbeat last|enable|disable`
|
||||
|
||||
心跳控制（Gateway 网关 RPC）。
|
||||
heartbeat 控制（Gateway 网关 RPC）。
|
||||
|
||||
选项：
|
||||
|
||||
- `--json`
|
||||
- `--url`、`--token`、`--timeout`、`--expect-final`
|
||||
- `--url`, `--token`, `--timeout`, `--expect-final`
|
||||
|
||||
### `system presence`
|
||||
|
||||
列出系统存在条目（Gateway 网关 RPC）。
|
||||
列出系统 presence 条目（Gateway 网关 RPC）。
|
||||
|
||||
选项：
|
||||
|
||||
- `--json`
|
||||
- `--url`、`--token`、`--timeout`、`--expect-final`
|
||||
- `--url`, `--token`, `--timeout`, `--expect-final`
|
||||
|
||||
## 定时任务
|
||||
## Cron
|
||||
|
||||
管理计划任务（Gateway 网关 RPC）。参见 [/automation/cron-jobs](/automation/cron-jobs)。
|
||||
|
||||
子命令：
|
||||
|
||||
- `cron status [--json]`
|
||||
- `cron list [--all] [--json]`（默认表格输出；使用 `--json` 获取原始数据）
|
||||
- `cron add`（别名：`create`；需要 `--name` 和 `--at` | `--every` | `--cron` 三选一，以及 `--system-event` | `--message` 负载二选一）
|
||||
- `cron edit <id>`（补丁字段）
|
||||
- `cron rm <id>`（别名：`remove`、`delete`）
|
||||
- `cron list [--all] [--json]`（默认输出表格；原始输出请使用 `--json`）
|
||||
- `cron add`（别名：`create`；要求 `--name`，并且必须且只能提供 `--at` | `--every` | `--cron` 之一，以及 `--system-event` | `--message` 之一作为负载）
|
||||
- `cron edit <id>`（修补字段）
|
||||
- `cron rm <id>`（别名：`remove`, `delete`）
|
||||
- `cron enable <id>`
|
||||
- `cron disable <id>`
|
||||
- `cron runs --id <id> [--limit <n>]`
|
||||
- `cron run <id> [--force]`
|
||||
|
||||
所有 `cron` 命令接受 `--url`、`--token`、`--timeout`、`--expect-final`。
|
||||
所有 `cron` 命令都接受 `--url`、`--token`、`--timeout`、`--expect-final`。
|
||||
|
||||
## 节点主机
|
||||
## Node 主机
|
||||
|
||||
`node` 运行**无头节点主机**或将其作为后台服务管理。参见 [`openclaw node`](/cli/node)。
|
||||
`node` 运行一个**无头 node host**，或将其作为后台服务进行管理。参见
|
||||
[`openclaw node`](/cli/node)。
|
||||
|
||||
子命令：
|
||||
|
||||
@ -919,13 +1025,18 @@ openclaw models status
|
||||
- `node stop`
|
||||
- `node restart`
|
||||
|
||||
## 节点
|
||||
认证说明：
|
||||
|
||||
`nodes` 与 Gateway 网关通信并针对已配对的节点。参见 [/nodes](/nodes)。
|
||||
- `node` 从环境 / 配置解析 gateway 认证（不支持 `--token`/`--password` 标志）：`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`，然后是 `gateway.auth.*`。在本地模式下，node host 会有意忽略 `gateway.remote.*`；在 `gateway.mode=remote` 时，`gateway.remote.*` 会根据远程优先级规则参与解析。
|
||||
- 旧版 `CLAWDBOT_GATEWAY_*` 环境变量会被有意忽略，不用于 node-host 认证解析。
|
||||
|
||||
## Nodes
|
||||
|
||||
`nodes` 与 Gateway 网关通信，并以已配对节点为目标。参见 [/nodes](/nodes)。
|
||||
|
||||
通用选项：
|
||||
|
||||
- `--url`、`--token`、`--timeout`、`--json`
|
||||
- `--url`, `--token`, `--timeout`, `--json`
|
||||
|
||||
子命令：
|
||||
|
||||
@ -937,8 +1048,8 @@ openclaw models status
|
||||
- `nodes reject <requestId>`
|
||||
- `nodes rename --node <id|name|ip> --name <displayName>`
|
||||
- `nodes invoke --node <id|name|ip> --command <command> [--params <json>] [--invoke-timeout <ms>] [--idempotency-key <key>]`
|
||||
- `nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>`（mac 节点或无头节点主机）
|
||||
- `nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>]`（仅限 mac）
|
||||
- `nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>`（mac 节点或无头 node host）
|
||||
- `nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>]`（仅 mac）
|
||||
|
||||
相机：
|
||||
|
||||
@ -946,7 +1057,7 @@ openclaw models status
|
||||
- `nodes camera snap --node <id|name|ip> [--facing front|back|both] [--device-id <id>] [--max-width <px>] [--quality <0-1>] [--delay-ms <ms>] [--invoke-timeout <ms>]`
|
||||
- `nodes camera clip --node <id|name|ip> [--facing front|back] [--device-id <id>] [--duration <ms|10s|1m>] [--no-audio] [--invoke-timeout <ms>]`
|
||||
|
||||
画布 + 屏幕：
|
||||
Canvas + 屏幕：
|
||||
|
||||
- `nodes canvas snapshot --node <id|name|ip> [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--invoke-timeout <ms>]`
|
||||
- `nodes canvas present --node <id|name|ip> [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>] [--invoke-timeout <ms>]`
|
||||
@ -963,11 +1074,11 @@ openclaw models status
|
||||
|
||||
## 浏览器
|
||||
|
||||
浏览器控制 CLI（专用 Chrome/Brave/Edge/Chromium）。参见 [`openclaw browser`](/cli/browser) 和[浏览器工具](/tools/browser)。
|
||||
浏览器控制 CLI（专用 Chrome/Brave/Edge/Chromium）。参见 [`openclaw browser`](/cli/browser) 和 [Browser 工具](/tools/browser)。
|
||||
|
||||
通用选项：
|
||||
|
||||
- `--url`、`--token`、`--timeout`、`--json`
|
||||
- `--url`, `--token`, `--timeout`, `--json`
|
||||
- `--browser-profile <name>`
|
||||
|
||||
管理：
|
||||
@ -1011,7 +1122,7 @@ openclaw models status
|
||||
|
||||
### `docs [query...]`
|
||||
|
||||
搜索在线文档索引。
|
||||
搜索实时文档索引。
|
||||
|
||||
## TUI
|
||||
|
||||
@ -1028,5 +1139,5 @@ openclaw models status
|
||||
- `--deliver`
|
||||
- `--thinking <level>`
|
||||
- `--message <text>`
|
||||
- `--timeout-ms <ms>`（默认为 `agents.defaults.timeoutSeconds`）
|
||||
- `--timeout-ms <ms>`（默认值为 `agents.defaults.timeoutSeconds`）
|
||||
- `--history-limit <n>`
|
||||
|
||||
@ -1,24 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想要 Gateway 网关、工作区、认证、渠道和 Skills 的引导式设置
|
||||
summary: "`openclaw onboard` 的 CLI 参考（交互式新手引导向导）"
|
||||
- 你想通过引导式设置来配置 Gateway 网关、工作区、身份验证、渠道和 Skills
|
||||
summary: "`openclaw onboard` 的 CLI 参考（交互式设置向导）"
|
||||
title: onboard
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:45:00Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a661049a6983233986a880a68440a3bcc6869ee2c4c6f5e9f3ab8ff973e22f60
|
||||
generated_at: "2026-03-16T06:21:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 04d7747342c582abcfcafff28847b4297f65ada665157d9cfbe3dbb258ee31d9
|
||||
source_path: cli/onboard.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw onboard`
|
||||
|
||||
交互式新手引导向导（本地或远程 Gateway 网关设置）。
|
||||
交互式设置向导（本地或远程 Gateway 网关设置）。
|
||||
|
||||
相关内容：
|
||||
## 相关指南
|
||||
|
||||
- 向导指南：[新手引导](/start/onboarding)
|
||||
- CLI 新手引导中心：[设置向导（CLI）](/start/wizard)
|
||||
- 新手引导概览：[新手引导概览](/start/onboarding-overview)
|
||||
- CLI 新手引导参考：[CLI 设置参考](/start/wizard-cli-reference)
|
||||
- CLI 自动化：[CLI 自动化](/start/wizard-cli-automation)
|
||||
- macOS 新手引导：[新手引导（macOS 应用）](/start/onboarding)
|
||||
|
||||
## 示例
|
||||
|
||||
@ -26,11 +30,135 @@ x-i18n:
|
||||
openclaw onboard
|
||||
openclaw onboard --flow quickstart
|
||||
openclaw onboard --flow manual
|
||||
openclaw onboard --mode remote --remote-url ws://gateway-host:18789
|
||||
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
|
||||
```
|
||||
|
||||
对于明文私有网络 `ws://` 目标（仅限受信任网络），请在新手引导进程环境中设置
|
||||
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`。
|
||||
|
||||
非交互式自定义提供商：
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--auth-choice custom-api-key \
|
||||
--custom-base-url "https://llm.example.com/v1" \
|
||||
--custom-model-id "foo-large" \
|
||||
--custom-api-key "$CUSTOM_API_KEY" \
|
||||
--secret-input-mode plaintext \
|
||||
--custom-compatibility openai
|
||||
```
|
||||
|
||||
在非交互式模式下，`--custom-api-key` 是可选的。如果省略，新手引导会检查 `CUSTOM_API_KEY`。
|
||||
|
||||
非交互式 Ollama：
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--auth-choice ollama \
|
||||
--custom-base-url "http://ollama-host:11434" \
|
||||
--custom-model-id "qwen3.5:27b" \
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
`--custom-base-url` 默认为 `http://127.0.0.1:11434`。`--custom-model-id` 是可选的；如果省略，新手引导会使用 Ollama 建议的默认值。像 `kimi-k2.5:cloud` 这样的云端模型 ID 在这里也可用。
|
||||
|
||||
将提供商密钥存储为引用而不是明文：
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--auth-choice openai-api-key \
|
||||
--secret-input-mode ref \
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
使用 `--secret-input-mode ref` 时，新手引导会写入由环境变量支持的引用，而不是明文密钥值。
|
||||
对于由 auth-profile 支持的提供商，这会写入 `keyRef` 条目；对于自定义提供商，这会将 `models.providers.<id>.apiKey` 写为环境变量引用（例如 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`）。
|
||||
|
||||
非交互式 `ref` 模式约定：
|
||||
|
||||
- 在新手引导进程环境中设置提供商环境变量（例如 `OPENAI_API_KEY`）。
|
||||
- 不要传递内联密钥标志（例如 `--openai-api-key`），除非该环境变量也已设置。
|
||||
- 如果传递了内联密钥标志但未设置所需环境变量，新手引导会快速失败并提供指引。
|
||||
|
||||
非交互式模式中的 Gateway 网关令牌选项：
|
||||
|
||||
- `--gateway-auth token --gateway-token <token>` 存储明文令牌。
|
||||
- `--gateway-auth token --gateway-token-ref-env <name>` 将 `gateway.auth.token` 存储为环境变量 SecretRef。
|
||||
- `--gateway-token` 和 `--gateway-token-ref-env` 互斥。
|
||||
- `--gateway-token-ref-env` 要求在新手引导进程环境中存在一个非空环境变量。
|
||||
- 使用 `--install-daemon` 时，当令牌身份验证需要令牌时，由 SecretRef 管理的 Gateway 网关令牌会被验证，但不会以已解析的明文形式持久化到 supervisor 服务环境元数据中。
|
||||
- 使用 `--install-daemon` 时，如果令牌模式需要令牌，而配置的令牌 SecretRef 未解析，新手引导会以封闭失败方式终止，并提供修复指引。
|
||||
- 使用 `--install-daemon` 时，如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，新手引导会阻止安装，直到显式设置 mode。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_GATEWAY_TOKEN="your-token"
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice skip \
|
||||
--gateway-auth token \
|
||||
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
非交互式本地 Gateway 网关健康检查：
|
||||
|
||||
- 除非你传递 `--skip-health`，否则新手引导会等待本地 Gateway 网关可访问后才成功退出。
|
||||
- `--install-daemon` 会先启动受管 Gateway 网关安装路径。不使用它时，你必须已经有一个正在运行的本地 Gateway 网关，例如 `openclaw gateway run`。
|
||||
- 如果你只想在自动化中写入配置/工作区/bootstrap，请使用 `--skip-health`。
|
||||
- 在原生 Windows 上，`--install-daemon` 会先尝试 Scheduled Tasks；如果任务创建被拒绝，则回退到每用户 Startup 文件夹登录项。
|
||||
|
||||
带引用模式的交互式新手引导行为：
|
||||
|
||||
- 出现提示时，选择**使用密钥引用**。
|
||||
- 然后选择以下之一：
|
||||
- 环境变量
|
||||
- 已配置的密钥提供商（`file` 或 `exec`）
|
||||
- 新手引导会在保存引用前执行快速预检验证。
|
||||
- 如果验证失败，新手引导会显示错误并让你重试。
|
||||
|
||||
非交互式 Z.AI 端点选择：
|
||||
|
||||
注意：`--auth-choice zai-api-key` 现在会为你的密钥自动检测最佳 Z.AI 端点（优先使用通用 API 搭配 `zai/glm-5`）。
|
||||
如果你明确想使用 GLM Coding Plan 端点，请选择 `zai-coding-global` 或 `zai-coding-cn`。
|
||||
|
||||
```bash
|
||||
# 无提示端点选择
|
||||
openclaw onboard --non-interactive \
|
||||
--auth-choice zai-coding-global \
|
||||
--zai-api-key "$ZAI_API_KEY"
|
||||
|
||||
# 其他 Z.AI 端点选择：
|
||||
# --auth-choice zai-coding-cn
|
||||
# --auth-choice zai-global
|
||||
# --auth-choice zai-cn
|
||||
```
|
||||
|
||||
非交互式 Mistral 示例：
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--auth-choice mistral-api-key \
|
||||
--mistral-api-key "$MISTRAL_API_KEY"
|
||||
```
|
||||
|
||||
流程说明：
|
||||
|
||||
- `quickstart`：最少提示，自动生成 Gateway 网关令牌。
|
||||
- `manual`：完整的端口/绑定/认证提示（`advanced` 的别名）。
|
||||
- 最快开始聊天：`openclaw dashboard`（控制 UI，无需渠道设置）。
|
||||
- `manual`：提供端口/绑定/身份验证的完整提示（`advanced` 的别名）。
|
||||
- 本地新手引导私信范围行为：[CLI 设置参考](/start/wizard-cli-reference#outputs-and-internals)。
|
||||
- 最快开始第一次聊天：`openclaw dashboard`（控制 UI，无需设置渠道）。
|
||||
- 自定义提供商：连接任何兼容 OpenAI 或 Anthropic 的端点，
|
||||
包括未列出的托管提供商。使用 Unknown 进行自动检测。
|
||||
|
||||
## 常见后续命令
|
||||
|
||||
```bash
|
||||
openclaw configure
|
||||
openclaw agents add <name>
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--json` 不代表非交互式模式。脚本请使用 `--non-interactive`。
|
||||
</Note>
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
---
|
||||
read_when:
|
||||
- 你在不使用完整新手引导向导的情况下进行首次设置
|
||||
- 你正在进行首次运行设置，但不使用完整的设置向导
|
||||
- 你想设置默认工作区路径
|
||||
summary: "`openclaw setup` 的 CLI 参考（初始化配置 + 工作区）"
|
||||
title: setup
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T20:21:26Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 7f3fc8b246924edf48501785be2c0d356bd31bfbb133e75a139a5ee41dbf57f4
|
||||
generated_at: "2026-03-16T06:21:20Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b6d6fef6642a4fdf9880ea4f752981b5ed0404289274ee3429ee31702873e3ea
|
||||
source_path: cli/setup.md
|
||||
workflow: 14
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw setup`
|
||||
@ -19,7 +19,7 @@ x-i18n:
|
||||
|
||||
相关内容：
|
||||
|
||||
- 快速开始：[快速开始](/start/getting-started)
|
||||
- 入门指南：[入门指南](/start/getting-started)
|
||||
- 向导：[新手引导](/start/onboarding)
|
||||
|
||||
## 示例
|
||||
|
||||
@ -5,28 +5,26 @@ read_when:
|
||||
summary: 智能体工作区：位置、布局和备份策略
|
||||
title: 智能体工作区
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:45:49Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 84c550fd89b5f2474aeae586795485fd29d36effbb462f13342b31540fc18b82
|
||||
generated_at: "2026-03-16T06:21:45Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6854ddbebe2d21da08c4e1773da6a44f02c815070677821996dab4c91cfb9cd4
|
||||
source_path: concepts/agent-workspace.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 智能体工作区
|
||||
|
||||
工作区是智能体的家。它是文件工具和工作区上下文使用的唯一工作目录。请保持其私密性并将其视为记忆。
|
||||
工作区是智能体的“家”。它是文件工具和工作区上下文所使用的唯一工作目录。请将其保持为私有，并将其视为记忆。
|
||||
|
||||
这与 `~/.openclaw/` 是分开的，后者存储配置、凭证和会话。
|
||||
这与存储配置、凭证和会话的 `~/.openclaw/` 是分开的。
|
||||
|
||||
**重要：** 工作区是**默认 cwd**，而不是硬性沙箱。工具会根据工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱隔离。如果你需要隔离，请使用
|
||||
[`agents.defaults.sandbox`](/gateway/sandboxing)（和/或每智能体沙箱配置）。
|
||||
当启用沙箱隔离且 `workspaceAccess` 不是 `"rw"` 时，工具在 `~/.openclaw/sandboxes` 下的沙箱工作区内操作，而不是你的主机工作区。
|
||||
**重要：**工作区是**默认 cwd**，而不是硬性沙箱。工具会相对于工作区解析相对路径，但除非启用沙箱隔离，否则绝对路径仍然可以访问主机上的其他位置。如果你需要隔离，请使用 [`agents.defaults.sandbox`](/gateway/sandboxing)（和/或按智能体配置的沙箱）。启用沙箱隔离后，如果 `workspaceAccess` 不是 `"rw"`，工具会在 `~/.openclaw/sandboxes` 下的沙箱工作区中运行，而不是在你的主机工作区中运行。
|
||||
|
||||
## 默认位置
|
||||
|
||||
- 默认：`~/.openclaw/workspace`
|
||||
- 如果设置了 `OPENCLAW_PROFILE` 且不是 `"default"`，默认值变为
|
||||
- 默认值：`~/.openclaw/workspace`
|
||||
- 如果设置了 `OPENCLAW_PROFILE` 且其值不是 `"default"`，默认值将变为
|
||||
`~/.openclaw/workspace-<profile>`。
|
||||
- 在 `~/.openclaw/openclaw.json` 中覆盖：
|
||||
|
||||
@ -38,9 +36,10 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 将创建工作区并在缺失时填充引导文件。
|
||||
`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 会在工作区缺失时创建工作区并植入引导文件。
|
||||
沙箱种子复制仅接受工作区内的常规文件；解析到源工作区外部的符号链接/硬链接别名会被忽略。
|
||||
|
||||
如果你已经自己管理工作区文件，可以禁用引导文件创建：
|
||||
如果你已经自行管理工作区文件，可以禁用引导文件创建：
|
||||
|
||||
```json5
|
||||
{ agent: { skipBootstrap: true } }
|
||||
@ -48,91 +47,92 @@ x-i18n:
|
||||
|
||||
## 额外的工作区文件夹
|
||||
|
||||
旧版安装可能创建了 `~/openclaw`。保留多个工作区目录可能会导致混乱的认证或状态漂移，因为同一时间只有一个工作区是活动的。
|
||||
较旧的安装可能创建过 `~/openclaw`。保留多个工作区目录可能会导致令人困惑的凭证或状态漂移，因为同一时间只有一个工作区处于活动状态。
|
||||
|
||||
**建议：** 保持单个活动工作区。如果你不再使用额外的文件夹，请归档或移至废纸篓（例如 `trash ~/openclaw`）。
|
||||
如果你有意保留多个工作区，请确保 `agents.defaults.workspace` 指向活动的那个。
|
||||
**建议：**只保留一个活动工作区。如果你不再使用额外的文件夹，请将其归档或移到废纸篓（例如 `trash ~/openclaw`）。
|
||||
如果你有意保留多个工作区，请确保
|
||||
`agents.defaults.workspace` 指向当前活动的那个。
|
||||
|
||||
`openclaw doctor` 在检测到额外工作区目录时会发出警告。
|
||||
当 `openclaw doctor` 检测到额外的工作区目录时，会发出警告。
|
||||
|
||||
## 工作区文件映射（每个文件的含义）
|
||||
|
||||
这些是 OpenClaw 在工作区内期望的标准文件：
|
||||
以下是 OpenClaw 在工作区内预期的标准文件：
|
||||
|
||||
- `AGENTS.md`
|
||||
- 智能体的操作指南以及它应该如何使用记忆。
|
||||
- 在每个会话开始时加载。
|
||||
- 适合放置规则、优先级和"如何行为"的详细信息。
|
||||
- 智能体的操作说明，以及它应如何使用记忆。
|
||||
- 每次会话开始时加载。
|
||||
- 很适合放置规则、优先级和“如何表现”之类的细节。
|
||||
|
||||
- `SOUL.md`
|
||||
- 人设、语气和边界。
|
||||
- 每个会话加载。
|
||||
- 每次会话都会加载。
|
||||
|
||||
- `USER.md`
|
||||
- 用户是谁以及如何称呼他们。
|
||||
- 每个会话加载。
|
||||
- 用户是谁，以及应如何称呼他们。
|
||||
- 每次会话都会加载。
|
||||
|
||||
- `IDENTITY.md`
|
||||
- 智能体的名称、风格和表情符号。
|
||||
- 智能体的名称、风格和 emoji。
|
||||
- 在引导仪式期间创建/更新。
|
||||
|
||||
- `TOOLS.md`
|
||||
- 关于你本地工具和惯例的注释。
|
||||
- 不控制工具可用性；仅作为指导。
|
||||
- 关于你的本地工具和约定的说明。
|
||||
- 它不控制工具可用性；仅提供指导。
|
||||
|
||||
- `HEARTBEAT.md`
|
||||
- 可选的心跳运行小型检查清单。
|
||||
- 保持简短以避免 token 消耗。
|
||||
- 可选的心跳运行微型检查清单。
|
||||
- 保持简短以避免消耗过多 token。
|
||||
|
||||
- `BOOT.md`
|
||||
- 当启用内部 hooks 时，在 Gateway 网关重启时执行的可选启动检查清单。
|
||||
- 保持简短；使用 message 工具进行出站发送。
|
||||
- 可选的启动检查清单；当启用内部 hooks 时，会在 Gateway 网关重启时执行。
|
||||
- 保持简短；出站发送请使用消息工具。
|
||||
|
||||
- `BOOTSTRAP.md`
|
||||
- 一次性首次运行仪式。
|
||||
- 仅为全新工作区创建。
|
||||
- 仪式完成后删除它。
|
||||
- 一次性的首次运行仪式。
|
||||
- 仅为全新的工作区创建。
|
||||
- 仪式完成后请将其删除。
|
||||
|
||||
- `memory/YYYY-MM-DD.md`
|
||||
- 每日记忆日志（每天一个文件）。
|
||||
- 建议在会话开始时读取今天 + 昨天的内容。
|
||||
- 建议在会话开始时阅读今天和昨天的内容。
|
||||
|
||||
- `MEMORY.md`（可选）
|
||||
- 精选的长期记忆。
|
||||
- 仅在主私密会话中加载（不在共享/群组上下文中）。
|
||||
- 仅在主私有会话中加载（不在共享/群组上下文中加载）。
|
||||
|
||||
参见 [记忆](/concepts/memory) 了解工作流程和自动记忆刷新。
|
||||
有关工作流和自动记忆刷新，请参见[记忆](/concepts/memory)。
|
||||
|
||||
- `skills/`（可选）
|
||||
- 工作区特定的 Skills。
|
||||
- 当名称冲突时覆盖托管/捆绑的 Skills。
|
||||
- 工作区专用技能。
|
||||
- 名称冲突时会覆盖托管/捆绑的 Skills。
|
||||
|
||||
- `canvas/`（可选）
|
||||
- 用于节点显示的 Canvas UI 文件（例如 `canvas/index.html`）。
|
||||
|
||||
如果任何引导文件缺失，OpenClaw 会在会话中注入"缺失文件"标记并继续。大型引导文件在注入时会被截断；使用 `agents.defaults.bootstrapMaxChars` 调整限制（默认：20000）。
|
||||
`openclaw setup` 可以重新创建缺失的默认值而不覆盖现有文件。
|
||||
如果任何引导文件缺失，OpenClaw 会在会话中注入一个“缺失文件”标记并继续执行。注入时，大型引导文件会被截断；可使用 `agents.defaults.bootstrapMaxChars`（默认：20000）和 `agents.defaults.bootstrapTotalMaxChars`（默认：150000）调整限制。
|
||||
`openclaw setup` 可以重新创建缺失的默认文件，而不会覆盖现有文件。
|
||||
|
||||
## 工作区中不包含的内容
|
||||
## 不在工作区中的内容
|
||||
|
||||
这些位于 `~/.openclaw/` 下，不应提交到工作区仓库：
|
||||
这些内容位于 `~/.openclaw/` 下，**不应**提交到工作区仓库：
|
||||
|
||||
- `~/.openclaw/openclaw.json`（配置）
|
||||
- `~/.openclaw/credentials/`（OAuth token、API 密钥）
|
||||
- `~/.openclaw/agents/<agentId>/sessions/`（会话记录 + 元数据）
|
||||
- `~/.openclaw/skills/`（托管的 Skills）
|
||||
- `~/.openclaw/credentials/`（OAuth 令牌、API 密钥）
|
||||
- `~/.openclaw/agents/<agentId>/sessions/`（会话记录和元数据）
|
||||
- `~/.openclaw/skills/`（托管 Skills）
|
||||
|
||||
如果你需要迁移会话或配置，请单独复制它们并将它们排除在版本控制之外。
|
||||
如果你需要迁移会话或配置，请单独复制它们，并确保不要将其纳入版本控制。
|
||||
|
||||
## Git 备份（推荐，私有）
|
||||
|
||||
将工作区视为私密记忆。将其放入**私有** git 仓库以便备份和恢复。
|
||||
将工作区视为私有记忆。把它放进一个**私有** git 仓库，以便备份并可恢复。
|
||||
|
||||
在运行 Gateway 网关的机器上执行这些步骤（工作区就在那里）。
|
||||
请在 Gateway 网关运行的机器上执行这些步骤（工作区就位于那里）。
|
||||
|
||||
### 1）初始化仓库
|
||||
|
||||
如果安装了 git，全新工作区会自动初始化。如果此工作区还不是仓库，请运行：
|
||||
如果已安装 git，全新工作区会自动初始化。如果这个工作区还不是仓库，请运行：
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace
|
||||
@ -141,14 +141,14 @@ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
|
||||
git commit -m "Add agent workspace"
|
||||
```
|
||||
|
||||
### 2）添加私有远程（适合初学者的选项）
|
||||
### 2）添加私有远程仓库（适合新手的选项）
|
||||
|
||||
选项 A：GitHub 网页界面
|
||||
选项 A：GitHub Web UI
|
||||
|
||||
1. 在 GitHub 上创建新的**私有**仓库。
|
||||
2. 不要用 README 初始化（避免合并冲突）。
|
||||
1. 在 GitHub 上创建一个新的**私有**仓库。
|
||||
2. 不要使用 README 初始化（以避免合并冲突）。
|
||||
3. 复制 HTTPS 远程 URL。
|
||||
4. 添加远程并推送：
|
||||
4. 添加远程仓库并推送：
|
||||
|
||||
```bash
|
||||
git branch -M main
|
||||
@ -163,12 +163,12 @@ gh auth login
|
||||
gh repo create openclaw-workspace --private --source . --remote origin --push
|
||||
```
|
||||
|
||||
选项 C：GitLab 网页界面
|
||||
选项 C：GitLab Web UI
|
||||
|
||||
1. 在 GitLab 上创建新的**私有**仓库。
|
||||
2. 不要用 README 初始化（避免合并冲突）。
|
||||
1. 在 GitLab 上创建一个新的**私有**仓库。
|
||||
2. 不要使用 README 初始化（以避免合并冲突）。
|
||||
3. 复制 HTTPS 远程 URL。
|
||||
4. 添加远程并推送：
|
||||
4. 添加远程仓库并推送：
|
||||
|
||||
```bash
|
||||
git branch -M main
|
||||
@ -187,15 +187,15 @@ git push
|
||||
|
||||
## 不要提交密钥
|
||||
|
||||
即使在私有仓库中，也要避免在工作区中存储密钥：
|
||||
即使在私有仓库中，也应避免在工作区中存储密钥：
|
||||
|
||||
- API 密钥、OAuth token、密码或私有凭证。
|
||||
- API 密钥、OAuth 令牌、密码或私有凭证。
|
||||
- `~/.openclaw/` 下的任何内容。
|
||||
- 聊天的原始转储或敏感附件。
|
||||
- 聊天原始转储或敏感附件。
|
||||
|
||||
如果你必须存储敏感引用，请使用占位符并将真正的密钥保存在其他地方（密码管理器、环境变量或 `~/.openclaw/`）。
|
||||
如果你必须存储敏感引用，请使用占位符，并将真实密钥保存在其他地方（密码管理器、环境变量或 `~/.openclaw/`）。
|
||||
|
||||
建议的 `.gitignore` 起始配置：
|
||||
建议的 `.gitignore` 起始内容：
|
||||
|
||||
```gitignore
|
||||
.DS_Store
|
||||
@ -207,13 +207,13 @@ git push
|
||||
|
||||
## 将工作区迁移到新机器
|
||||
|
||||
1. 将仓库克隆到所需路径（默认 `~/.openclaw/workspace`）。
|
||||
1. 将仓库克隆到所需路径（默认是 `~/.openclaw/workspace`）。
|
||||
2. 在 `~/.openclaw/openclaw.json` 中将 `agents.defaults.workspace` 设置为该路径。
|
||||
3. 运行 `openclaw setup --workspace <path>` 来填充任何缺失的文件。
|
||||
4. 如果你需要会话，请单独从旧机器复制 `~/.openclaw/agents/<agentId>/sessions/`。
|
||||
3. 运行 `openclaw setup --workspace <path>` 以植入任何缺失的文件。
|
||||
4. 如果你需要会话，请将旧机器上的 `~/.openclaw/agents/<agentId>/sessions/` 单独复制过来。
|
||||
|
||||
## 高级注意事项
|
||||
## 高级说明
|
||||
|
||||
- 多智能体路由可以为每个智能体使用不同的工作区。参见
|
||||
[渠道路由](/channels/channel-routing) 了解路由配置。
|
||||
- 如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用每会话沙箱工作区。
|
||||
- 多智能体路由可以为不同智能体使用不同的工作区。有关路由配置，请参见
|
||||
[渠道路由](/channels/channel-routing)。
|
||||
- 如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用按会话划分的沙箱工作区。
|
||||
|
||||
@ -1,107 +1,155 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要一份逐提供商的模型设置参考
|
||||
- 你需要模型提供商的示例配置或 CLI 新手引导命令
|
||||
summary: 模型提供商概览，包含示例配置和 CLI 流程
|
||||
- 你需要按提供商划分的模型设置参考
|
||||
- 你想要模型提供商的示例配置或 CLI 新手引导命令
|
||||
summary: 模型提供商概览，包含示例配置 + CLI 流程
|
||||
title: 模型提供商
|
||||
x-i18n:
|
||||
generated_at: "2026-03-16T02:12:40Z"
|
||||
model: claude-opus-4-6
|
||||
provider: pi
|
||||
source_hash: 978798c80c5809c162f9807072ab48fdf99bfe0db39b2b3c245ce8b4e5451603
|
||||
generated_at: "2026-03-16T06:22:52Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 1b84eea0103a59e77571f82c800c9c0ad9fc554e8c9b2c1fd15c2cc121e7f6b4
|
||||
source_path: concepts/model-providers.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 模型提供商
|
||||
|
||||
本页涵盖 **LLM/模型提供商** （不是 WhatsApp/Telegram 等聊天渠道）。
|
||||
有关模型选择规则，请参阅 [/concepts/models](/concepts/models)。
|
||||
本页介绍的是 **LLM/模型提供商**（而不是像 WhatsApp/Telegram 这样的聊天渠道）。
|
||||
有关模型选择规则，请参见 [/concepts/models](/concepts/models)。
|
||||
|
||||
## 快速规则
|
||||
|
||||
- 模型引用使用 `provider/model` （例如： `opencode/claude-opus-4-6`）。
|
||||
- 如果你设置了 `agents.defaults.models`，它将成为允许列表。
|
||||
- CLI 辅助命令： `openclaw onboard`， `openclaw models list`， `openclaw models set <provider/model>`。
|
||||
- 提供商插件可以通过以下方式注入模型目录 `registerProvider({ catalog })`；
|
||||
OpenClaw 将该输出合并到 `models.providers` 之后再写入
|
||||
`models.json`。
|
||||
- 提供商插件还可以通过以下方式控制提供商的运行时行为
|
||||
`resolveDynamicModel`， `prepareDynamicModel`， `normalizeResolvedModel`，
|
||||
`capabilities`， `prepareExtraParams`， `wrapStreamFn`，
|
||||
`isCacheTtlEligible`， `prepareRuntimeAuth`， `resolveUsageAuth`，以及
|
||||
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
|
||||
- 如果你设置了 `agents.defaults.models`，它就会成为 allowlist。
|
||||
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
|
||||
- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；
|
||||
OpenClaw 会在写入
|
||||
`models.json` 之前将该输出合并到 `models.providers` 中。
|
||||
- 提供商清单可以声明 `providerAuthEnvVars`，这样基于通用环境变量的
|
||||
身份验证探测就不需要加载插件运行时。其余的核心环境变量映射
|
||||
现在只用于非插件/核心提供商，以及少数通用优先级场景，
|
||||
例如 Anthropic 以 API 密钥优先的新手引导。
|
||||
- 提供商插件还可以通过以下机制接管提供商运行时行为：
|
||||
`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、
|
||||
`capabilities`、`prepareExtraParams`、`wrapStreamFn`、`formatApiKey`、
|
||||
`refreshOAuth`、`buildAuthDoctorHint`、
|
||||
`isCacheTtlEligible`、`buildMissingAuthMessage`、
|
||||
`suppressBuiltInModel`、`augmentModelCatalog`、`isBinaryThinking`、
|
||||
`supportsXHighThinking`、`resolveDefaultThinkingLevel`、
|
||||
`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`，以及
|
||||
`fetchUsageSnapshot`。
|
||||
|
||||
## 插件管理的提供商行为
|
||||
## 插件接管的提供商行为
|
||||
|
||||
提供商插件现在可以管理大部分提供商特定逻辑，而 OpenClaw 负责维护通用推理循环。
|
||||
提供商插件现在可以接管大多数提供商特定逻辑，而 OpenClaw 保留
|
||||
通用推理循环。
|
||||
|
||||
典型分工：
|
||||
典型划分：
|
||||
|
||||
- `catalog`：提供商出现在 `models.providers`
|
||||
- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 ID
|
||||
- `prepareDynamicModel`：提供商在重试动态解析之前需要刷新元数据
|
||||
- `normalizeResolvedModel`：提供商需要传输层或基础 URL 重写
|
||||
- `capabilities`：提供商发布会话记录/工具/提供商系列的特殊行为
|
||||
- `prepareExtraParams`：提供商默认或规范化每个模型的请求参数
|
||||
- `wrapStreamFn`：提供商应用请求头/请求体/模型兼容性封装
|
||||
- `auth[].run` / `auth[].runNonInteractive`：提供商接管 `openclaw onboard`、`openclaw models auth` 和无头设置的
|
||||
新手引导/登录流程
|
||||
- `wizard.onboarding` / `wizard.modelPicker`：提供商接管新手引导/模型选择器中的身份验证选项标签、
|
||||
提示和设置条目
|
||||
- `catalog`：提供商出现在 `models.providers` 中
|
||||
- `resolveDynamicModel`：提供商接受尚未出现在本地静态
|
||||
目录中的模型 ID
|
||||
- `prepareDynamicModel`：提供商在重试
|
||||
动态解析之前需要刷新元数据
|
||||
- `normalizeResolvedModel`：提供商需要重写传输或基础 URL
|
||||
- `capabilities`：提供商发布 transcript/工具/提供商家族的特殊行为
|
||||
- `prepareExtraParams`：提供商为每个模型请求参数提供默认值或进行标准化
|
||||
- `wrapStreamFn`：提供商应用请求头/请求体/模型兼容包装器
|
||||
- `formatApiKey`：提供商将存储的 auth profile 格式化为
|
||||
传输层预期的运行时 `apiKey` 字符串
|
||||
- `refreshOAuth`：当共享的 `pi-ai`
|
||||
刷新器不足时，由提供商接管 OAuth 刷新
|
||||
- `buildAuthDoctorHint`：当 OAuth 刷新
|
||||
失败时，提供商附加修复指引
|
||||
- `isCacheTtlEligible`：提供商决定哪些上游模型 ID 支持 prompt-cache TTL
|
||||
- `prepareRuntimeAuth`：提供商将配置的凭证转换为短期运行时令牌
|
||||
- `resolveUsageAuth`：提供商为以下用途解析使用量/配额凭证 `/usage`
|
||||
以及相关的状态/报告界面
|
||||
- `fetchUsageSnapshot`：提供商负责使用量端点的获取/解析，而核心仍负责摘要外壳和格式化
|
||||
- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示
|
||||
替换通用 auth-store 错误
|
||||
- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以在直接解析失败时返回
|
||||
供应商自有错误
|
||||
- `augmentModelCatalog`：提供商在
|
||||
发现和配置合并后追加合成/最终目录条目
|
||||
- `isBinaryThinking`：提供商接管二元开/关 thinking UX
|
||||
- `supportsXHighThinking`：提供商让选定模型支持 `xhigh`
|
||||
- `resolveDefaultThinkingLevel`：提供商接管某个
|
||||
模型家族默认 `/think` 策略
|
||||
- `isModernModelRef`：提供商接管 live/smoke 首选模型匹配
|
||||
- `prepareRuntimeAuth`：提供商将已配置凭证转换为短期
|
||||
运行时令牌
|
||||
- `resolveUsageAuth`：提供商为 `/usage`
|
||||
以及相关状态/报告界面解析使用量/配额凭证
|
||||
- `fetchUsageSnapshot`：提供商接管使用量端点的获取/解析，而核心仍负责摘要外壳和格式化
|
||||
|
||||
当前内置示例：
|
||||
|
||||
- `anthropic`：Claude 4.6 向前兼容回退、使用量端点获取，以及 cache-TTL/提供商系列元数据
|
||||
- `openrouter`：直通模型 ID、请求封装、提供商能力提示，以及 cache-TTL 策略
|
||||
- `github-copilot`：向前兼容模型回退、Claude-thinking 会话记录提示、运行时令牌交换，以及使用量端点获取
|
||||
- `openai`：GPT-5.4 向前兼容回退、直接 OpenAI 传输规范化，以及提供商系列元数据
|
||||
- `openai-codex`：向前兼容模型回退、传输规范化，以及默认传输参数和使用量端点获取
|
||||
- `google-gemini-cli`：Gemini 3.1 向前兼容回退，以及使用量界面的 usage-token 解析和配额端点获取
|
||||
- `moonshot`：共享传输、插件管理的 thinking 负载规范化
|
||||
- `kilocode`：共享传输、插件管理的请求头、推理负载规范化、Gemini 会话记录提示，以及 cache-TTL 策略
|
||||
- `zai`：GLM-5 向前兼容回退， `tool_stream` 默认值、cache-TTL 策略，以及使用量认证和配额获取
|
||||
- `mistral`， `opencode`，以及`opencode-go`：插件管理的能力元数据
|
||||
- `byteplus`， `cloudflare-ai-gateway`， `huggingface`， `kimi-coding`，
|
||||
`minimax-portal`， `modelstudio`， `nvidia`， `qianfan`， `qwen-portal`，
|
||||
`synthetic`， `together`， `venice`， `vercel-ai-gateway`，以及`volcengine`：仅限插件管理的目录
|
||||
- `minimax` 和 `xiaomi`：插件管理的目录以及使用量认证/快照逻辑
|
||||
- `anthropic`：Claude 4.6 前向兼容回退、身份验证修复提示、使用量
|
||||
端点获取，以及 cache-TTL/提供商家族元数据
|
||||
- `openrouter`：直通模型 ID、请求包装器、提供商能力
|
||||
提示，以及 cache-TTL 策略
|
||||
- `github-copilot`：新手引导/设备登录、前向兼容模型回退、
|
||||
Claude-thinking transcript 提示、运行时令牌交换，以及使用量端点
|
||||
获取
|
||||
- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输
|
||||
标准化、Codex 感知的缺失身份验证提示、Spark 抑制、合成
|
||||
OpenAI/Codex 目录条目、thinking/live-model 策略，以及
|
||||
提供商家族元数据
|
||||
- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退和
|
||||
现代模型匹配；Gemini CLI OAuth 还接管 auth-profile 令牌
|
||||
格式化、usage-token 解析，以及面向使用量界面的配额端点获取
|
||||
- `moonshot`：共享传输、插件接管的 thinking 负载标准化
|
||||
- `kilocode`：共享传输、插件接管的请求头、reasoning 负载
|
||||
标准化、Gemini transcript 提示，以及 cache-TTL 策略
|
||||
- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、cache-TTL
|
||||
策略、二元 thinking/live-model 策略，以及使用量身份验证 + 配额获取
|
||||
- `mistral`、`opencode` 和 `opencode-go`：插件接管的能力元数据
|
||||
- `byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi-coding`、
|
||||
`modelstudio`、`nvidia`、`qianfan`、`synthetic`、`together`、`venice`、
|
||||
`vercel-ai-gateway` 和 `volcengine`：仅插件接管的目录
|
||||
- `qwen-portal`：插件接管的目录、OAuth 登录和 OAuth 刷新
|
||||
- `minimax` 和 `xiaomi`：插件接管的目录，以及使用量身份验证/快照逻辑
|
||||
|
||||
以上涵盖了仍然适用于 OpenClaw 常规传输层的提供商。如果某个提供商需要完全自定义的请求执行器，则属于一个独立的、更深层的扩展层面。
|
||||
内置的 `openai` 插件现在接管两个提供商 ID：`openai` 和
|
||||
`openai-codex`。
|
||||
|
||||
以上涵盖了仍适合 OpenClaw 常规传输的提供商。若某个提供商
|
||||
需要完全自定义的请求执行器，那就是另一个更深层的扩展接口。
|
||||
|
||||
## API 密钥轮换
|
||||
|
||||
- 支持对选定提供商的通用提供商轮换。
|
||||
- 支持为选定提供商进行通用提供商轮换。
|
||||
- 通过以下方式配置多个密钥：
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY` （单个实时覆盖，最高优先级）
|
||||
- `<PROVIDER>_API_KEYS` （逗号或分号分隔的列表）
|
||||
- `<PROVIDER>_API_KEY` （主密钥）
|
||||
- `<PROVIDER>_API_KEY_*` （编号列表，例如 `<PROVIDER>_API_KEY_1`）
|
||||
- 对于 Google 提供商， `GOOGLE_API_KEY` 也作为备选项包含在内。
|
||||
- 密钥选择顺序按优先级排列并去除重复值。
|
||||
- 仅在速率限制响应时使用下一个密钥重试请求（例如 `429`， `rate_limit`， `quota`， `resource exhausted`）。
|
||||
- 非速率限制的失败会立即报错；不会尝试密钥轮换。
|
||||
- 当所有候选密钥均失败时，返回最后一次尝试的错误。
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个 live 覆盖，最高优先级）
|
||||
- `<PROVIDER>_API_KEYS`（逗号或分号分隔列表）
|
||||
- `<PROVIDER>_API_KEY`（主密钥）
|
||||
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
|
||||
- 对于 Google 提供商，还会包含 `GOOGLE_API_KEY` 作为回退。
|
||||
- 密钥选择顺序会保留优先级并对值去重。
|
||||
- 仅在速率限制响应时才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`）。
|
||||
- 非速率限制失败会立即失败；不会尝试密钥轮换。
|
||||
- 当所有候选密钥都失败时，将返回最后一次尝试的最终错误。
|
||||
|
||||
## 内置提供商（pi-ai 目录）
|
||||
|
||||
OpenClaw 附带 pi-ai 目录。这些提供商需要 **无需**
|
||||
`models.providers` 配置；只需设置认证并选择一个模型。
|
||||
OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
|
||||
`models.providers` 配置；只需设置身份验证 + 选择一个模型。
|
||||
|
||||
### OpenAI
|
||||
|
||||
- 提供商： `openai`
|
||||
- 认证： `OPENAI_API_KEY`
|
||||
- 可选轮换： `OPENAI_API_KEYS`， `OPENAI_API_KEY_1`， `OPENAI_API_KEY_2`，加上 `OPENCLAW_LIVE_OPENAI_KEY` （单个覆盖）
|
||||
- 示例模型： `openai/gpt-5.4`， `openai/gpt-5.4-pro`
|
||||
- CLI： `openclaw onboard --auth-choice openai-api-key`
|
||||
- 默认传输为 `auto` （WebSocket 优先，SSE 备选）
|
||||
- 通过以下方式覆盖每个模型 `agents.defaults.models["openai/<model>"].params.transport` （`"sse"`， `"websocket"`，或 `"auto"`）
|
||||
- OpenAI Responses WebSocket 预热默认通过以下方式启用 `params.openaiWsWarmup` （`true`/`false`）
|
||||
- OpenAI 优先处理可以通过以下方式启用 `agents.defaults.models["openai/<model>"].params.serviceTier`
|
||||
- OpenAI 快速模式可以通过以下方式为每个模型启用 `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为 OpenAI 实时 API 会拒绝它；Spark 被视为仅限 Codex 使用
|
||||
- 提供商：`openai`
|
||||
- 身份验证：`OPENAI_API_KEY`
|
||||
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
|
||||
- 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-pro`
|
||||
- CLI：`openclaw onboard --auth-choice openai-api-key`
|
||||
- 默认传输为 `auto`（优先 WebSocket，SSE 回退）
|
||||
- 通过 `agents.defaults.models["openai/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
|
||||
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`）
|
||||
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先处理
|
||||
- 可通过 `agents.defaults.models["<provider>/<model>"].params.fastMode` 为每个模型启用 OpenAI 快速模式
|
||||
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -111,14 +159,14 @@ OpenClaw 附带 pi-ai 目录。这些提供商需要 **无需**
|
||||
|
||||
### Anthropic
|
||||
|
||||
- 提供商： `anthropic`
|
||||
- 认证： `ANTHROPIC_API_KEY` 或 `claude setup-token`
|
||||
- 可选轮换： `ANTHROPIC_API_KEYS`， `ANTHROPIC_API_KEY_1`， `ANTHROPIC_API_KEY_2`，加上 `OPENCLAW_LIVE_ANTHROPIC_KEY` （单个覆盖）
|
||||
- 示例模型： `anthropic/claude-opus-4-6`
|
||||
- CLI： `openclaw onboard --auth-choice token` （粘贴 setup-token）或 `openclaw models auth paste-token --provider anthropic`
|
||||
- 直接 API 密钥模型支持共享的 `/fast` 切换和 `params.fastMode`；OpenClaw 将其映射到 Anthropic 的 `service_tier` （`auto` 与 `standard_only`）
|
||||
- 策略说明：setup-token 支持属于技术兼容性；Anthropic 过去曾阻止部分订阅在 Claude Code 之外的使用。请核实当前 Anthropic 条款，并根据你的风险承受能力做出决定。
|
||||
- 建议：Anthropic API 密钥认证是比订阅 setup-token 认证更安全的推荐方式。
|
||||
- 提供商：`anthropic`
|
||||
- 身份验证：`ANTHROPIC_API_KEY` 或 `claude setup-token`
|
||||
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖）
|
||||
- 示例模型：`anthropic/claude-opus-4-6`
|
||||
- CLI：`openclaw onboard --auth-choice token`（粘贴 setup-token）或 `openclaw models auth paste-token --provider anthropic`
|
||||
- 直接 API 密钥模型支持共享的 `/fast` 开关和 `params.fastMode`；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
|
||||
- 策略说明：setup-token 支持属于技术兼容性；Anthropic 过去曾阻止某些在 Claude Code 之外的订阅用法。请核实当前 Anthropic 条款，并根据你的风险承受能力做出决定。
|
||||
- 建议：相比订阅 setup-token 身份验证，Anthropic API 密钥身份验证是更安全、也更推荐的路径。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -126,17 +174,17 @@ OpenClaw 附带 pi-ai 目录。这些提供商需要 **无需**
|
||||
}
|
||||
```
|
||||
|
||||
### OpenAI Code (Codex)
|
||||
### OpenAI Code（Codex）
|
||||
|
||||
- 提供商： `openai-codex`
|
||||
- 认证：OAuth (ChatGPT)
|
||||
- 示例模型： `openai-codex/gpt-5.4`
|
||||
- CLI： `openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
|
||||
- 默认传输为 `auto` （WebSocket 优先，SSE 备选）
|
||||
- 通过以下方式覆盖每个模型 `agents.defaults.models["openai-codex/<model>"].params.transport` （`"sse"`， `"websocket"`，或 `"auto"`）
|
||||
- 与相同的 `/fast` 切换和 `params.fastMode` 配置共享，如同直接的 `openai/*`
|
||||
- `openai-codex/gpt-5.3-codex-spark` 当 Codex OAuth 目录公开时仍然可用；取决于授权资格
|
||||
- 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 等外部工具/工作流。
|
||||
- 提供商：`openai-codex`
|
||||
- 身份验证：OAuth（ChatGPT）
|
||||
- 示例模型：`openai-codex/gpt-5.4`
|
||||
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
|
||||
- 默认传输为 `auto`（优先 WebSocket，SSE 回退）
|
||||
- 通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
|
||||
- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置
|
||||
- 当 Codex OAuth 目录暴露它时，`openai-codex/gpt-5.3-codex-spark` 仍然可用；取决于 entitlement
|
||||
- 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 这样的外部工具/工作流。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -146,11 +194,11 @@ OpenClaw 附带 pi-ai 目录。这些提供商需要 **无需**
|
||||
|
||||
### OpenCode
|
||||
|
||||
- 认证： `OPENCODE_API_KEY` （或 `OPENCODE_ZEN_API_KEY`）
|
||||
- Zen 运行时提供商： `opencode`
|
||||
- Go 运行时提供商： `opencode-go`
|
||||
- 示例模型： `opencode/claude-opus-4-6`， `opencode-go/kimi-k2.5`
|
||||
- CLI： `openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`
|
||||
- 身份验证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
|
||||
- Zen 运行时提供商：`opencode`
|
||||
- Go 运行时提供商：`opencode-go`
|
||||
- 示例模型：`opencode/claude-opus-4-6`、`opencode-go/kimi-k2.5`
|
||||
- CLI：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -160,94 +208,97 @@ OpenClaw 附带 pi-ai 目录。这些提供商需要 **无需**
|
||||
|
||||
### Google Gemini（API 密钥）
|
||||
|
||||
- 提供商： `google`
|
||||
- 认证： `GEMINI_API_KEY`
|
||||
- 可选轮换： `GEMINI_API_KEYS`， `GEMINI_API_KEY_1`， `GEMINI_API_KEY_2`， `GOOGLE_API_KEY` 备选，以及 `OPENCLAW_LIVE_GEMINI_KEY` （单个覆盖）
|
||||
- 示例模型： `google/gemini-3.1-pro-preview`， `google/gemini-3-flash-preview`
|
||||
- 兼容性：使用旧版 OpenClaw 配置的 `google/gemini-3.1-flash-preview` 会被规范化为 `google/gemini-3-flash-preview`
|
||||
- CLI： `openclaw onboard --auth-choice gemini-api-key`
|
||||
- 提供商：`google`
|
||||
- 身份验证：`GEMINI_API_KEY`
|
||||
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
|
||||
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
|
||||
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被标准化为 `google/gemini-3-flash-preview`
|
||||
- CLI：`openclaw onboard --auth-choice gemini-api-key`
|
||||
|
||||
### Google Vertex 和 Gemini CLI
|
||||
|
||||
- 提供商： `google-vertex`， `google-gemini-cli`
|
||||
- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
|
||||
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。部分用户报告称在使用第三方客户端后 Google 账户受到限制。请查阅 Google 条款，如果你选择继续，建议使用非关键账户。
|
||||
- Gemini CLI OAuth 作为内置的 `google` 插件的一部分提供。
|
||||
- 启用： `openclaw plugins enable google`
|
||||
- 登录： `openclaw models auth login --provider google-gemini-cli --set-default`
|
||||
- 注意：你确实 **不** 需要将 client ID 或 secret 粘贴到 `openclaw.json`中。CLI 登录流程将令牌存储在 Gateway 网关主机的认证配置文件中。
|
||||
- 提供商：`google-vertex`、`google-gemini-cli`
|
||||
- 身份验证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
|
||||
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告在使用第三方客户端后遭遇 Google 账号限制。请查看 Google 条款，如果你决定继续，建议使用非关键账号。
|
||||
- Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
|
||||
- 启用：`openclaw plugins enable google`
|
||||
- 登录：`openclaw models auth login --provider google-gemini-cli --set-default`
|
||||
- 注意：你**不需要**将客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会将
|
||||
令牌存储在 Gateway 网关主机上的 auth profile 中。
|
||||
|
||||
### Z.AI (GLM)
|
||||
### Z.AI（GLM）
|
||||
|
||||
- 提供商： `zai`
|
||||
- 认证： `ZAI_API_KEY`
|
||||
- 示例模型： `zai/glm-5`
|
||||
- CLI： `openclaw onboard --auth-choice zai-api-key`
|
||||
- 别名： `z.ai/*` 和 `z-ai/*` 规范化为 `zai/*`
|
||||
- 提供商：`zai`
|
||||
- 身份验证：`ZAI_API_KEY`
|
||||
- 示例模型：`zai/glm-5`
|
||||
- CLI：`openclaw onboard --auth-choice zai-api-key`
|
||||
- 别名：`z.ai/*` 和 `z-ai/*` 会标准化为 `zai/*`
|
||||
|
||||
### Vercel AI Gateway
|
||||
|
||||
- 提供商： `vercel-ai-gateway`
|
||||
- 认证： `AI_GATEWAY_API_KEY`
|
||||
- 示例模型： `vercel-ai-gateway/anthropic/claude-opus-4.6`
|
||||
- CLI： `openclaw onboard --auth-choice ai-gateway-api-key`
|
||||
- 提供商：`vercel-ai-gateway`
|
||||
- 身份验证：`AI_GATEWAY_API_KEY`
|
||||
- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6`
|
||||
- CLI：`openclaw onboard --auth-choice ai-gateway-api-key`
|
||||
|
||||
### Kilo Gateway
|
||||
|
||||
- 提供商： `kilocode`
|
||||
- 认证： `KILOCODE_API_KEY`
|
||||
- 示例模型： `kilocode/anthropic/claude-opus-4.6`
|
||||
- CLI： `openclaw onboard --kilocode-api-key <key>`
|
||||
- 基础 URL： `https://api.kilo.ai/api/gateway/`
|
||||
- 扩展的内置目录包括 GLM-5 Free、MiniMax M2.5 Free、GPT-5.2、Gemini 3 Pro Preview、Gemini 3 Flash Preview、Grok Code Fast 1 和 Kimi K2.5。
|
||||
- 提供商：`kilocode`
|
||||
- 身份验证：`KILOCODE_API_KEY`
|
||||
- 示例模型：`kilocode/anthropic/claude-opus-4.6`
|
||||
- CLI：`openclaw onboard --kilocode-api-key <key>`
|
||||
- 基础 URL：`https://api.kilo.ai/api/gateway/`
|
||||
- 扩展后的内置目录包括 GLM-5 Free、MiniMax M2.5 Free、GPT-5.2、Gemini 3 Pro Preview、Gemini 3 Flash Preview、Grok Code Fast 1 和 Kimi K2.5。
|
||||
|
||||
参阅 [/providers/kilocode](/providers/kilocode) 了解详情。
|
||||
设置详情请参见 [/providers/kilocode](/providers/kilocode)。
|
||||
|
||||
### 其他内置提供商插件
|
||||
|
||||
- OpenRouter： `openrouter` （`OPENROUTER_API_KEY`）
|
||||
- 示例模型： `openrouter/anthropic/claude-sonnet-4-5`
|
||||
- Kilo Gateway： `kilocode` （`KILOCODE_API_KEY`）
|
||||
- 示例模型： `kilocode/anthropic/claude-opus-4.6`
|
||||
- MiniMax： `minimax` （`MINIMAX_API_KEY`）
|
||||
- Moonshot： `moonshot` （`MOONSHOT_API_KEY`）
|
||||
- Kimi Coding： `kimi-coding` （`KIMI_API_KEY` 或 `KIMICODE_API_KEY`）
|
||||
- Qianfan： `qianfan` （`QIANFAN_API_KEY`）
|
||||
- Model Studio： `modelstudio` （`MODELSTUDIO_API_KEY`）
|
||||
- NVIDIA： `nvidia` （`NVIDIA_API_KEY`）
|
||||
- Together： `together` （`TOGETHER_API_KEY`）
|
||||
- Venice： `venice` （`VENICE_API_KEY`）
|
||||
- Xiaomi： `xiaomi` （`XIAOMI_API_KEY`）
|
||||
- Vercel AI Gateway： `vercel-ai-gateway` （`AI_GATEWAY_API_KEY`）
|
||||
- Hugging Face Inference： `huggingface` （`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`）
|
||||
- Cloudflare AI Gateway： `cloudflare-ai-gateway` （`CLOUDFLARE_AI_GATEWAY_API_KEY`）
|
||||
- Volcengine： `volcengine` （`VOLCANO_ENGINE_API_KEY`）
|
||||
- BytePlus： `byteplus` （`BYTEPLUS_API_KEY`）
|
||||
- xAI： `xai` （`XAI_API_KEY`）
|
||||
- Mistral： `mistral` （`MISTRAL_API_KEY`）
|
||||
- 示例模型： `mistral/mistral-large-latest`
|
||||
- CLI： `openclaw onboard --auth-choice mistral-api-key`
|
||||
- Groq： `groq` （`GROQ_API_KEY`）
|
||||
- Cerebras： `cerebras` （`CEREBRAS_API_KEY`）
|
||||
- OpenRouter：`openrouter`（`OPENROUTER_API_KEY`）
|
||||
- 示例模型：`openrouter/anthropic/claude-sonnet-4-5`
|
||||
- Kilo Gateway：`kilocode`（`KILOCODE_API_KEY`）
|
||||
- 示例模型：`kilocode/anthropic/claude-opus-4.6`
|
||||
- MiniMax：`minimax`（`MINIMAX_API_KEY`）
|
||||
- Moonshot：`moonshot`（`MOONSHOT_API_KEY`）
|
||||
- Kimi Coding：`kimi-coding`（`KIMI_API_KEY` 或 `KIMICODE_API_KEY`）
|
||||
- Qianfan：`qianfan`（`QIANFAN_API_KEY`）
|
||||
- Model Studio：`modelstudio`（`MODELSTUDIO_API_KEY`）
|
||||
- NVIDIA：`nvidia`（`NVIDIA_API_KEY`）
|
||||
- Together：`together`（`TOGETHER_API_KEY`）
|
||||
- Venice：`venice`（`VENICE_API_KEY`）
|
||||
- Xiaomi：`xiaomi`（`XIAOMI_API_KEY`）
|
||||
- Vercel AI Gateway：`vercel-ai-gateway`（`AI_GATEWAY_API_KEY`）
|
||||
- Hugging Face Inference：`huggingface`（`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`）
|
||||
- Cloudflare AI Gateway：`cloudflare-ai-gateway`（`CLOUDFLARE_AI_GATEWAY_API_KEY`）
|
||||
- Volcengine：`volcengine`（`VOLCANO_ENGINE_API_KEY`）
|
||||
- BytePlus：`byteplus`（`BYTEPLUS_API_KEY`）
|
||||
- xAI：`xai`（`XAI_API_KEY`）
|
||||
- Mistral：`mistral`（`MISTRAL_API_KEY`）
|
||||
- 示例模型：`mistral/mistral-large-latest`
|
||||
- CLI：`openclaw onboard --auth-choice mistral-api-key`
|
||||
- Groq：`groq`（`GROQ_API_KEY`）
|
||||
- Cerebras：`cerebras`（`CEREBRAS_API_KEY`）
|
||||
- Cerebras 上的 GLM 模型使用 ID `zai-glm-4.7` 和 `zai-glm-4.6`。
|
||||
- 兼容 OpenAI 的基础 URL： `https://api.cerebras.ai/v1`。
|
||||
- GitHub Copilot： `github-copilot` （`COPILOT_GITHUB_TOKEN`/`GH_TOKEN`/`GITHUB_TOKEN`）
|
||||
- Hugging Face Inference 示例模型： `huggingface/deepseek-ai/DeepSeek-R1`；CLI： `openclaw onboard --auth-choice huggingface-api-key`。参阅 [Hugging Face (Inference)](/providers/huggingface)。
|
||||
- OpenAI 兼容基础 URL：`https://api.cerebras.ai/v1`。
|
||||
- GitHub Copilot：`github-copilot`（`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`）
|
||||
- Hugging Face Inference 示例模型：`huggingface/deepseek-ai/DeepSeek-R1`；CLI：`openclaw onboard --auth-choice huggingface-api-key`。请参见 [Hugging Face（Inference）](/providers/huggingface)。
|
||||
|
||||
## 通过以下方式提供的提供商 `models.providers` （自定义/基础 URL）
|
||||
## 通过 `models.providers` 配置的提供商（自定义/基础 URL）
|
||||
|
||||
使用 `models.providers` （或 `models.json`）来添加 **自定义** 提供商或 OpenAI/Anthropic 兼容代理。
|
||||
使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或
|
||||
兼容 OpenAI/Anthropic 的代理。
|
||||
|
||||
下方许多内置提供商插件已经发布了默认目录。
|
||||
使用显式的 `models.providers.<id>` 条目仅在你需要覆盖默认基础 URL、请求头或模型列表时使用。
|
||||
下面许多内置提供商插件已经发布了默认目录。
|
||||
只有在你希望覆盖默认
|
||||
基础 URL、请求头或模型列表时，才使用显式 `models.providers.<id>` 条目。
|
||||
|
||||
### Moonshot AI (Kimi)
|
||||
### Moonshot AI（Kimi）
|
||||
|
||||
Moonshot 使用兼容 OpenAI 的端点，因此将其配置为自定义提供商：
|
||||
|
||||
- 提供商： `moonshot`
|
||||
- 认证： `MOONSHOT_API_KEY`
|
||||
- 示例模型： `moonshot/kimi-k2.5`
|
||||
- 提供商：`moonshot`
|
||||
- 身份验证：`MOONSHOT_API_KEY`
|
||||
- 示例模型：`moonshot/kimi-k2.5`
|
||||
|
||||
Kimi K2 模型 ID：
|
||||
|
||||
@ -284,9 +335,9 @@ Kimi K2 模型 ID：
|
||||
|
||||
Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
|
||||
|
||||
- 提供商： `kimi-coding`
|
||||
- 认证： `KIMI_API_KEY`
|
||||
- 示例模型： `kimi-coding/k2p5`
|
||||
- 提供商：`kimi-coding`
|
||||
- 身份验证：`KIMI_API_KEY`
|
||||
- 示例模型：`kimi-coding/k2p5`
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -297,10 +348,10 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
|
||||
}
|
||||
```
|
||||
|
||||
### Qwen OAuth（免费套餐）
|
||||
### Qwen OAuth（免费层）
|
||||
|
||||
Qwen 通过设备码流程提供对 Qwen Coder + Vision 的 OAuth 访问。
|
||||
内置提供商插件默认启用，只需登录：
|
||||
Qwen 通过设备代码流程提供对 Qwen Coder + Vision 的 OAuth 访问。
|
||||
内置提供商插件默认启用，因此只需登录：
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider qwen-portal --set-default
|
||||
@ -311,16 +362,16 @@ openclaw models auth login --provider qwen-portal --set-default
|
||||
- `qwen-portal/coder-model`
|
||||
- `qwen-portal/vision-model`
|
||||
|
||||
参阅 [/providers/qwen](/providers/qwen) 了解详情和注意事项。
|
||||
设置详情和说明请参见 [/providers/qwen](/providers/qwen)。
|
||||
|
||||
### 火山引擎（豆包）
|
||||
### Volcano Engine（Doubao）
|
||||
|
||||
火山引擎提供对豆包及中国其他模型的访问。
|
||||
Volcano Engine（火山引擎）为中国用户提供对 Doubao 和其他模型的访问。
|
||||
|
||||
- 提供商： `volcengine` （编码： `volcengine-plan`）
|
||||
- 认证： `VOLCANO_ENGINE_API_KEY`
|
||||
- 示例模型： `volcengine/doubao-seed-1-8-251228`
|
||||
- CLI： `openclaw onboard --auth-choice volcengine-api-key`
|
||||
- 提供商：`volcengine`（编码：`volcengine-plan`）
|
||||
- 身份验证：`VOLCANO_ENGINE_API_KEY`
|
||||
- 示例模型：`volcengine/doubao-seed-1-8-251228`
|
||||
- CLI：`openclaw onboard --auth-choice volcengine-api-key`
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -332,11 +383,11 @@ openclaw models auth login --provider qwen-portal --set-default
|
||||
|
||||
可用模型：
|
||||
|
||||
- `volcengine/doubao-seed-1-8-251228` （豆包 Seed 1.8）
|
||||
- `volcengine/doubao-seed-1-8-251228`（Doubao Seed 1.8）
|
||||
- `volcengine/doubao-seed-code-preview-251028`
|
||||
- `volcengine/kimi-k2-5-260127` （Kimi K2.5）
|
||||
- `volcengine/glm-4-7-251222` （GLM 4.7）
|
||||
- `volcengine/deepseek-v3-2-251201` （DeepSeek V3.2 128K）
|
||||
- `volcengine/kimi-k2-5-260127`（Kimi K2.5）
|
||||
- `volcengine/glm-4-7-251222`（GLM 4.7）
|
||||
- `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K）
|
||||
|
||||
编码模型（`volcengine-plan`）：
|
||||
|
||||
@ -348,12 +399,12 @@ openclaw models auth login --provider qwen-portal --set-default
|
||||
|
||||
### BytePlus（国际版）
|
||||
|
||||
BytePlus ARK 为国际用户提供与火山引擎相同的模型访问。
|
||||
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。
|
||||
|
||||
- 提供商： `byteplus` （编码： `byteplus-plan`）
|
||||
- 认证： `BYTEPLUS_API_KEY`
|
||||
- 示例模型： `byteplus/seed-1-8-251228`
|
||||
- CLI： `openclaw onboard --auth-choice byteplus-api-key`
|
||||
- 提供商：`byteplus`（编码：`byteplus-plan`）
|
||||
- 身份验证：`BYTEPLUS_API_KEY`
|
||||
- 示例模型：`byteplus/seed-1-8-251228`
|
||||
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -365,9 +416,9 @@ BytePlus ARK 为国际用户提供与火山引擎相同的模型访问。
|
||||
|
||||
可用模型：
|
||||
|
||||
- `byteplus/seed-1-8-251228` （Seed 1.8）
|
||||
- `byteplus/kimi-k2-5-260127` （Kimi K2.5）
|
||||
- `byteplus/glm-4-7-251222` （GLM 4.7）
|
||||
- `byteplus/seed-1-8-251228`（Seed 1.8）
|
||||
- `byteplus/kimi-k2-5-260127`（Kimi K2.5）
|
||||
- `byteplus/glm-4-7-251222`（GLM 4.7）
|
||||
|
||||
编码模型（`byteplus-plan`）：
|
||||
|
||||
@ -379,12 +430,12 @@ BytePlus ARK 为国际用户提供与火山引擎相同的模型访问。
|
||||
|
||||
### Synthetic
|
||||
|
||||
Synthetic 提供 Anthropic 兼容模型，位于 `synthetic` 提供商背后：
|
||||
Synthetic 通过 `synthetic` 提供商提供兼容 Anthropic 的模型：
|
||||
|
||||
- 提供商： `synthetic`
|
||||
- 认证： `SYNTHETIC_API_KEY`
|
||||
- 示例模型： `synthetic/hf:MiniMaxAI/MiniMax-M2.5`
|
||||
- CLI： `openclaw onboard --auth-choice synthetic-api-key`
|
||||
- 提供商：`synthetic`
|
||||
- 身份验证：`SYNTHETIC_API_KEY`
|
||||
- 示例模型：`synthetic/hf:MiniMaxAI/MiniMax-M2.5`
|
||||
- CLI：`openclaw onboard --auth-choice synthetic-api-key`
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -407,24 +458,24 @@ Synthetic 提供 Anthropic 兼容模型，位于 `synthetic` 提供商背后：
|
||||
|
||||
### MiniMax
|
||||
|
||||
MiniMax 通过以下方式配置 `models.providers` ，因为它使用自定义端点：
|
||||
MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
|
||||
|
||||
- MiniMax（Anthropic 兼容）： `--auth-choice minimax-api`
|
||||
- 认证： `MINIMAX_API_KEY`
|
||||
- MiniMax（兼容 Anthropic）：`--auth-choice minimax-api`
|
||||
- 身份验证：`MINIMAX_API_KEY`
|
||||
|
||||
参阅 [/providers/minimax](/providers/minimax) 了解详情、模型选项和配置代码片段。
|
||||
设置详情、模型选项和配置片段请参见 [/providers/minimax](/providers/minimax)。
|
||||
|
||||
### Ollama
|
||||
|
||||
Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API：
|
||||
|
||||
- 提供商： `ollama`
|
||||
- 认证：无需（本地服务器）
|
||||
- 示例模型： `ollama/llama3.3`
|
||||
- 安装： [https://ollama.com/download](https://ollama.com/download)
|
||||
- 提供商：`ollama`
|
||||
- 身份验证：无需（本地服务器）
|
||||
- 示例模型：`ollama/llama3.3`
|
||||
- 安装：[https://ollama.com/download](https://ollama.com/download)
|
||||
|
||||
```bash
|
||||
# Install Ollama, then pull a model:
|
||||
# 安装 Ollama，然后拉取一个模型：
|
||||
ollama pull llama3.3
|
||||
```
|
||||
|
||||
@ -436,26 +487,26 @@ ollama pull llama3.3
|
||||
}
|
||||
```
|
||||
|
||||
Ollama 在本地通过以下地址检测 `http://127.0.0.1:11434` 当你通过以下方式选择启用时
|
||||
`OLLAMA_API_KEY`，内置提供商插件会将 Ollama 直接添加到
|
||||
`openclaw onboard` 和模型选择器中。参阅 [/providers/ollama](/providers/ollama)
|
||||
了解新手引导、云端/本地模式和自定义配置。
|
||||
当你通过
|
||||
`OLLAMA_API_KEY` 选择加入时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到，内置提供商插件会将 Ollama 直接添加到
|
||||
`openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/providers/ollama)。
|
||||
|
||||
### vLLM
|
||||
|
||||
vLLM 作为内置提供商插件提供，用于本地/自托管的兼容 OpenAI 服务器：
|
||||
vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容
|
||||
服务器：
|
||||
|
||||
- 提供商： `vllm`
|
||||
- 认证：可选（取决于你的服务器）
|
||||
- 默认基础 URL： `http://127.0.0.1:8000/v1`
|
||||
- 提供商：`vllm`
|
||||
- 身份验证：可选（取决于你的服务器）
|
||||
- 默认基础 URL：`http://127.0.0.1:8000/v1`
|
||||
|
||||
要在本地选择启用自动发现（如果你的服务器不强制认证，任何值均可）：
|
||||
要选择加入本地自动发现（如果你的服务器不强制身份验证，则任意值均可）：
|
||||
|
||||
```bash
|
||||
export VLLM_API_KEY="vllm-local"
|
||||
```
|
||||
|
||||
然后设置一个模型（替换为由 `/v1/models`）：
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -465,23 +516,25 @@ export VLLM_API_KEY="vllm-local"
|
||||
}
|
||||
```
|
||||
|
||||
参阅 [/providers/vllm](/providers/vllm) 了解详情。
|
||||
详情请参见 [/providers/vllm](/providers/vllm)。
|
||||
|
||||
### SGLang
|
||||
|
||||
SGLang 作为内置提供商插件提供，用于快速自托管的兼容 OpenAI 服务器：
|
||||
SGLang 作为内置提供商插件提供，用于高速自托管
|
||||
OpenAI 兼容服务器：
|
||||
|
||||
- 提供商： `sglang`
|
||||
- 认证：可选（取决于你的服务器）
|
||||
- 默认基础 URL： `http://127.0.0.1:30000/v1`
|
||||
- 提供商：`sglang`
|
||||
- 身份验证：可选（取决于你的服务器）
|
||||
- 默认基础 URL：`http://127.0.0.1:30000/v1`
|
||||
|
||||
要在本地选择启用自动发现（如果你的服务器不强制认证，任何值均可）：
|
||||
要选择加入本地自动发现（如果你的服务器不
|
||||
强制身份验证，则任意值均可）：
|
||||
|
||||
```bash
|
||||
export SGLANG_API_KEY="sglang-local"
|
||||
```
|
||||
|
||||
然后设置一个模型（替换为由 `/v1/models`）：
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -491,7 +544,7 @@ export SGLANG_API_KEY="sglang-local"
|
||||
}
|
||||
```
|
||||
|
||||
参阅 [/providers/sglang](/providers/sglang) 了解详情。
|
||||
详情请参见 [/providers/sglang](/providers/sglang)。
|
||||
|
||||
### 本地代理（LM Studio、vLLM、LiteLLM 等）
|
||||
|
||||
@ -528,19 +581,19 @@ export SGLANG_API_KEY="sglang-local"
|
||||
}
|
||||
```
|
||||
|
||||
注意事项：
|
||||
说明：
|
||||
|
||||
- 对于自定义提供商， `reasoning`， `input`， `cost`， `contextWindow`，以及`maxTokens` 是可选的。
|
||||
省略时，OpenClaw 默认为：
|
||||
- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 是可选的。
|
||||
如果省略，OpenClaw 默认使用：
|
||||
- `reasoning: false`
|
||||
- `input: ["text"]`
|
||||
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
|
||||
- `contextWindow: 200000`
|
||||
- `maxTokens: 8192`
|
||||
- 建议：设置与你的代理/模型限制相匹配的显式值。
|
||||
- 对于 `api: "openai-completions"` 在非原生端点上（任何非空的 `baseUrl` 且主机不是 `api.openai.com`），OpenClaw 强制使用 `compat.supportsDeveloperRole: false` 以避免提供商对不支持的 `developer` 角色返回 400 错误。
|
||||
- 如果 `baseUrl` 为空/省略，OpenClaw 保持默认的 OpenAI 行为（解析为 `api.openai.com`）。
|
||||
- 为安全起见，显式的 `compat.supportsDeveloperRole: true` 在非原生 `openai-completions` 端点上仍会被覆盖。
|
||||
- 建议：设置与你的代理/模型限制匹配的显式值。
|
||||
- 对于非原生端点上的 `api: "openai-completions"`（任何主机不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
|
||||
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（即解析为 `api.openai.com`）。
|
||||
- 出于安全考虑，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。
|
||||
|
||||
## CLI 示例
|
||||
|
||||
@ -550,4 +603,4 @@ openclaw models set opencode/claude-opus-4-6
|
||||
openclaw models list
|
||||
```
|
||||
|
||||
另请参阅： [/gateway/configuration](/gateway/configuration) 查看完整配置示例。
|
||||
另请参见：[/gateway/configuration](/gateway/configuration) 了解完整配置示例。
|
||||
|
||||
@ -1,79 +1,85 @@
|
||||
---
|
||||
read_when:
|
||||
- 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks）
|
||||
- 更改模型回退行为或选择用户体验
|
||||
- 更新模型扫描探测（工具/图像）
|
||||
summary: 模型 CLI：列表、设置、别名、回退、扫描、状态
|
||||
title: 模型 CLI
|
||||
- 添加或修改 models CLI（models list/set/scan/aliases/fallbacks）
|
||||
- 更改模型回退行为或选择 UX
|
||||
- 更新模型扫描探测（tools/images）
|
||||
summary: Models CLI：列出、设置、别名、回退、扫描、状态
|
||||
title: Models CLI
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T10:05:42Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: e8b54bb370b4f63a9b917594fb0f6ff48192e168196d30c713b8bbe72b78fef6
|
||||
generated_at: "2026-03-16T06:22:01Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 26150aef638bc3375866dec736b98eac32384466a8ef2b0a471fb7ff7729b13c
|
||||
source_path: concepts/models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 模型 CLI
|
||||
# Models CLI
|
||||
|
||||
参见 [/concepts/model-failover](/concepts/model-failover) 了解认证配置文件轮换、冷却时间及其与回退的交互。
|
||||
快速提供商概述 + 示例：[/concepts/model-providers](/concepts/model-providers)。
|
||||
关于凭证配置轮换、冷却时间以及它们如何与回退交互，请参阅 [/concepts/model-failover](/concepts/model-failover)。
|
||||
快速提供商概览 + 示例：[/concepts/model-providers](/concepts/model-providers)。
|
||||
|
||||
## 模型选择工作原理
|
||||
## 模型选择的工作方式
|
||||
|
||||
OpenClaw 按以下顺序选择模型：
|
||||
|
||||
1. **主要**模型（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
|
||||
2. `agents.defaults.model.fallbacks` 中的**回退**（按顺序）。
|
||||
3. **提供商认证故障转移**在移动到下一个模型之前在提供商内部发生。
|
||||
1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
|
||||
2. `agents.defaults.model.fallbacks` 中的 **回退模型**（按顺序）。
|
||||
3. **提供商凭证故障切换** 会在单个提供商内部发生，然后才会移动到下一个模型。
|
||||
|
||||
相关：
|
||||
相关内容：
|
||||
|
||||
- `agents.defaults.models` 是 OpenClaw 可使用的模型白名单/目录（加上别名）。
|
||||
- `agents.defaults.imageModel` **仅在**主要模型无法接受图像时使用。
|
||||
- 每个智能体的默认值可以通过 `agents.list[].model` 加绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/concepts/multi-agent)）。
|
||||
- `agents.defaults.models` 是 OpenClaw 可使用的模型允许列表/目录（以及别名）。
|
||||
- `agents.defaults.imageModel` **仅在** 主模型无法接受图像时使用。
|
||||
- 每个智能体的默认值可以通过 `agents.list[].model` 加上绑定来覆盖 `agents.defaults.model`（见 [/concepts/multi-agent](/concepts/multi-agent)）。
|
||||
|
||||
## 快速模型推荐（经验之谈）
|
||||
## 快速模型策略
|
||||
|
||||
- **GLM**：在编程/工具调用方面稍好。
|
||||
- **MiniMax**：在写作和氛围方面更好。
|
||||
- 将你的主模型设置为你可用的、最新一代中最强的模型。
|
||||
- 对于对成本/延迟敏感的任务和风险较低的聊天，使用回退模型。
|
||||
- 对于启用了工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。
|
||||
|
||||
## 设置向导（推荐）
|
||||
|
||||
如果你不想手动编辑配置，请运行新手引导向导：
|
||||
如果你不想手动编辑配置，请运行设置向导：
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
它可以为常见提供商设置模型 + 认证，包括 **OpenAI Code（Codex）订阅**（OAuth）和 **Anthropic**（推荐使用 API 密钥；也支持 `claude setup-token`）。
|
||||
它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code (Codex)**
|
||||
订阅（OAuth）和 **Anthropic**（API key 或 `claude setup-token`）。
|
||||
|
||||
## 配置键（概述）
|
||||
## 配置键（概览）
|
||||
|
||||
- `agents.defaults.model.primary` 和 `agents.defaults.model.fallbacks`
|
||||
- `agents.defaults.imageModel.primary` 和 `agents.defaults.imageModel.fallbacks`
|
||||
- `agents.defaults.models`（白名单 + 别名 + 提供商参数）
|
||||
- `agents.defaults.models`（允许列表 + 别名 + 提供商参数）
|
||||
- `models.providers`（写入 `models.json` 的自定义提供商）
|
||||
|
||||
模型引用会规范化为小写。提供商别名如 `z.ai/*` 会规范化为 `zai/*`。
|
||||
模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会被规范化
|
||||
为 `zai/*`。
|
||||
|
||||
提供商配置示例（包括 OpenCode Zen）在 [/gateway/configuration](/gateway/configuration#opencode-zen-multi-model-proxy)。
|
||||
提供商配置示例（包括 OpenCode）位于
|
||||
[/gateway/configuration](/gateway/configuration#opencode)。
|
||||
|
||||
## "Model is not allowed"（以及为什么回复停止）
|
||||
## “Model is not allowed”（以及为什么回复会停止）
|
||||
|
||||
如果设置了 `agents.defaults.models`，它将成为 `/model` 和会话覆盖的**白名单**。当用户选择不在该白名单中的模型时，OpenClaw 返回：
|
||||
如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的 **允许列表**。当用户选择了不在该允许列表中的模型时，
|
||||
OpenClaw 会返回：
|
||||
|
||||
```
|
||||
Model "provider/model" is not allowed. Use /model to list available models.
|
||||
```
|
||||
|
||||
这发生在正常回复生成**之前**，所以消息可能感觉像"没有响应"。修复方法是：
|
||||
这会在生成正常回复 **之前** 发生，因此消息可能会让人觉得
|
||||
它“没有响应”。修复方法是：
|
||||
|
||||
- 将模型添加到 `agents.defaults.models`，或
|
||||
- 清除白名单（删除 `agents.defaults.models`），或
|
||||
- 将该模型添加到 `agents.defaults.models`，或者
|
||||
- 清除允许列表（移除 `agents.defaults.models`），或者
|
||||
- 从 `/model list` 中选择一个模型。
|
||||
|
||||
白名单配置示例：
|
||||
允许列表示例配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -81,7 +87,7 @@ Model "provider/model" is not allowed. Use /model to list available models.
|
||||
model: { primary: "anthropic/claude-sonnet-4-5" },
|
||||
models: {
|
||||
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
|
||||
"anthropic/claude-opus-4-5": { alias: "Opus" },
|
||||
"anthropic/claude-opus-4-6": { alias: "Opus" },
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -89,7 +95,7 @@ Model "provider/model" is not allowed. Use /model to list available models.
|
||||
|
||||
## 在聊天中切换模型（`/model`）
|
||||
|
||||
你可以在不重启的情况下切换当前会话的模型：
|
||||
你可以在不重启的情况下为当前会话切换模型：
|
||||
|
||||
```
|
||||
/model
|
||||
@ -99,16 +105,17 @@ Model "provider/model" is not allowed. Use /model to list available models.
|
||||
/model status
|
||||
```
|
||||
|
||||
注意事项：
|
||||
说明：
|
||||
|
||||
- `/model`（和 `/model list`）是紧凑的编号选择器（模型系列 + 可用提供商）。
|
||||
- `/model <#>` 从该选择器中选择。
|
||||
- `/model status` 是详细视图（认证候选项，以及配置时的提供商端点 `baseUrl` + `api` 模式）。
|
||||
- 模型引用通过在**第一个** `/` 处分割来解析。输入 `/model <ref>` 时使用 `provider/model`。
|
||||
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。
|
||||
- 如果省略提供商，OpenClaw 将输入视为别名或**默认提供商**的模型（仅在模型 ID 中没有 `/` 时有效）。
|
||||
- `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。
|
||||
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个 Submit 步骤。
|
||||
- `/model <#>` 会从该选择器中进行选择。
|
||||
- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` + `api` 模式）。
|
||||
- 模型引用是通过按 **第一个** `/` 进行分割来解析的。输入 `/model <ref>` 时请使用 `provider/model`。
|
||||
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。
|
||||
- 如果你省略提供商，OpenClaw 会将输入视为别名或 **默认提供商** 的模型（仅在模型 ID 中没有 `/` 时有效）。
|
||||
|
||||
完整命令行为/配置：[斜杠命令](/tools/slash-commands)。
|
||||
完整命令行为/配置： [Slash commands](/tools/slash-commands)。
|
||||
|
||||
## CLI 命令
|
||||
|
||||
@ -137,7 +144,7 @@ openclaw models image-fallbacks clear
|
||||
|
||||
### `models list`
|
||||
|
||||
默认显示已配置的模型。有用的标志：
|
||||
默认显示已配置的模型。常用标志：
|
||||
|
||||
- `--all`：完整目录
|
||||
- `--local`：仅本地提供商
|
||||
@ -147,12 +154,18 @@ openclaw models image-fallbacks clear
|
||||
|
||||
### `models status`
|
||||
|
||||
显示已解析的主要模型、回退、图像模型，以及已配置提供商的认证概述。它还显示认证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内警告）。`--plain` 仅打印已解析的主要模型。
|
||||
OAuth 状态始终显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印 **Missing auth** 部分。
|
||||
JSON 包括 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效认证）。
|
||||
使用 `--check` 进行自动化（缺失/过期时退出 `1`，即将过期时退出 `2`）。
|
||||
显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示凭证存储中找到的配置文件的 OAuth 过期状态
|
||||
（默认会在 24 小时内到期时警告）。`--plain` 仅打印已解析的
|
||||
主模型。
|
||||
OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置的
|
||||
提供商没有凭证，`models status` 会打印一个 **Missing auth** 部分。
|
||||
JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`
|
||||
（每个提供商的有效凭证）。
|
||||
自动化场景请使用 `--check`（缺失/已过期时退出码为 `1`，即将过期时为 `2`）。
|
||||
|
||||
首选的 Anthropic 认证是 Claude Code CLI setup-token（在任何地方运行；如需要在 Gateway 网关主机上粘贴）：
|
||||
凭证选择取决于提供商/账号。对于始终在线的 Gateway 网关主机，API key 通常最可预测；也支持订阅 token 流程。
|
||||
|
||||
示例（Anthropic setup-token）：
|
||||
|
||||
```bash
|
||||
claude setup-token
|
||||
@ -161,21 +174,23 @@ openclaw models status
|
||||
|
||||
## 扫描（OpenRouter 免费模型）
|
||||
|
||||
`openclaw models scan` 检查 OpenRouter 的**免费模型目录**，并可选择性地探测模型的工具和图像支持。
|
||||
`openclaw models scan` 会检查 OpenRouter 的 **免费模型目录**，并且可以
|
||||
选择性地探测模型对工具和图像的支持。
|
||||
|
||||
关键标志：
|
||||
|
||||
- `--no-probe`：跳过实时探测（仅元数据）
|
||||
- `--min-params <b>`：最小参数量（十亿）
|
||||
- `--max-age-days <days>`：跳过较旧的模型
|
||||
- `--min-params <b>`：最小参数规模（十亿）
|
||||
- `--max-age-days <days>`：跳过较旧模型
|
||||
- `--provider <name>`：提供商前缀筛选
|
||||
- `--max-candidates <n>`：回退列表大小
|
||||
- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择
|
||||
- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择
|
||||
- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择项
|
||||
- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择项
|
||||
|
||||
探测需要 OpenRouter API 密钥（来自认证配置文件或 `OPENROUTER_API_KEY`）。没有密钥时，使用 `--no-probe` 仅列出候选项。
|
||||
探测需要 OpenRouter API key（来自凭证配置文件或
|
||||
`OPENROUTER_API_KEY`）。如果没有 key，请使用 `--no-probe` 仅列出候选项。
|
||||
|
||||
扫描结果按以下顺序排名：
|
||||
扫描结果按以下顺序排序：
|
||||
|
||||
1. 图像支持
|
||||
2. 工具延迟
|
||||
@ -185,12 +200,26 @@ openclaw models status
|
||||
输入
|
||||
|
||||
- OpenRouter `/models` 列表（筛选 `:free`）
|
||||
- 需要来自认证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/help/environment)）
|
||||
- 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API key（见 [/environment](/help/environment)）
|
||||
- 可选筛选器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
|
||||
- 探测控制：`--timeout`、`--concurrency`
|
||||
|
||||
在 TTY 中运行时，你可以交互式选择回退。在非交互模式下，传递 `--yes` 接受默认值。
|
||||
在 TTY 中运行时，你可以交互式选择回退模型。在非交互
|
||||
模式下，传入 `--yes` 以接受默认值。
|
||||
|
||||
## 模型注册表（`models.json`）
|
||||
|
||||
`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认 `~/.openclaw/agents/<agentId>/models.json`）。除非 `models.mode` 设置为 `replace`，否则此文件默认会被合并。
|
||||
`models.providers` 中的自定义提供商会写入
|
||||
智能体目录下的 `models.json`（默认是 `~/.openclaw/agents/<agentId>/agent/models.json`）。默认会合并此文件，除非将 `models.mode` 设置为 `replace`。
|
||||
|
||||
匹配提供商 ID 时的合并模式优先级：
|
||||
|
||||
- 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。
|
||||
- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中不是 SecretRef 管理时才优先。
|
||||
- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）刷新，而不是持久化已解析的 secret。
|
||||
- 由 SecretRef 管理的提供商 header 值会从源标记（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）刷新。
|
||||
- 智能体中为空或缺失的 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
|
||||
- 其他提供商字段会从配置和规范化后的目录数据中刷新。
|
||||
|
||||
标记持久化以源为准：OpenClaw 会根据活动源配置快照（预解析）写入标记，而不是根据运行时已解析的 secret 值写入。
|
||||
这适用于 OpenClaw 重新生成 `models.json` 的所有情况，包括像 `openclaw agent` 这样的命令驱动路径。
|
||||
|
||||
@ -1,69 +1,80 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想全面了解 OpenClaw 的 OAuth 流程
|
||||
- 你想端到端了解 OpenClaw OAuth
|
||||
- 你遇到了令牌失效/登出问题
|
||||
- 你想了解 setup-token 或 OAuth 认证流程
|
||||
- 你想使用多账户或配置文件路由
|
||||
- 你想使用 setup-token 或 OAuth 认证流程
|
||||
- 你想使用多个账户或配置文件路由
|
||||
summary: OpenClaw 中的 OAuth：令牌交换、存储和多账户模式
|
||||
title: OAuth
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T20:23:29Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: af714bdadc4a89295a18da1eba5f5b857c8d533ebabe9b0758b722fe60c36124
|
||||
generated_at: "2026-03-16T06:22:05Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 976668c3e02ee50500fcaaa585a89af718398dc41988318ec3a583c2d5449df3
|
||||
source_path: concepts/oauth.md
|
||||
workflow: 14
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# OAuth
|
||||
|
||||
OpenClaw 支持通过 OAuth 进行"订阅认证"，适用于提供此功能的提供商（特别是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic 订阅，请使用 **setup-token** 流程。本页说明：
|
||||
OpenClaw 通过 OAuth 支持提供商提供的“订阅认证”，适用于支持此方式的提供商（尤其是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic 订阅，请使用 **setup-token** 流程。过去有些用户在 Claude Code 之外使用 Anthropic 订阅时曾受限，因此这应视为用户自行选择承担的风险，你应自行核实 Anthropic 当前的政策。OpenAI Codex OAuth 明确支持在 OpenClaw 这样的外部工具中使用。本页说明：
|
||||
|
||||
- OAuth **令牌交换**的工作原理（PKCE）
|
||||
- 令牌**存储**在哪里（以及原因）
|
||||
- 如何处理**多账户**（配置文件 + 按会话覆盖）
|
||||
对于生产环境中的 Anthropic，相比订阅 setup-token 认证，API 密钥认证是更安全、也更推荐的路径。
|
||||
|
||||
OpenClaw 还支持**提供商插件**，它们自带 OAuth 或 API 密钥流程。通过以下命令运行：
|
||||
- OAuth **令牌交换** 如何工作（PKCE）
|
||||
- 令牌**存储**在哪里（以及为什么）
|
||||
- 如何处理**多个账户**（配置文件 + 按会话覆盖）
|
||||
|
||||
OpenClaw 也支持自带 OAuth 或 API 密钥流程的**提供商插件**。运行方式如下：
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider <id>
|
||||
```
|
||||
|
||||
## 令牌汇聚点（为什么需要它）
|
||||
## 令牌汇点（为什么需要它）
|
||||
|
||||
OAuth 提供商通常在登录/刷新流程中发放**新的刷新令牌**。某些提供商（或 OAuth 客户端）在为同一用户/应用发放新令牌时，可能会使旧的刷新令牌失效。
|
||||
OAuth 提供商通常会在登录/刷新流程中签发一个**新的刷新令牌**。某些提供商（或 OAuth 客户端）会在为同一用户/应用签发新令牌时使旧的刷新令牌失效。
|
||||
|
||||
实际症状：
|
||||
|
||||
- 你通过 OpenClaw _和_ Claude Code / Codex CLI 登录 → 其中一个稍后会随机"登出"
|
||||
- 你同时通过 OpenClaw _和_ Claude Code / Codex CLI 登录 → 之后其中一个会随机“被登出”
|
||||
|
||||
为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为**令牌汇聚点**：
|
||||
为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为一个**令牌汇点**：
|
||||
|
||||
- 运行时从**同一个位置**读取凭据
|
||||
- 我们可以保留多个配置文件并确定性地路由它们
|
||||
- 运行时从**同一个地方**读取凭证
|
||||
- 我们可以保留多个配置文件，并进行确定性路由
|
||||
|
||||
## 存储（令牌存放位置）
|
||||
|
||||
密钥按**智能体**存储：
|
||||
密钥按**每个智能体**存储：
|
||||
|
||||
- 认证配置文件（OAuth + API 密钥）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- 运行时缓存（自动管理；请勿编辑）：`~/.openclaw/agents/<agentId>/agent/auth.json`
|
||||
- 认证配置文件（OAuth + API 密钥 + 可选的值级引用）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- 旧版兼容文件：`~/.openclaw/agents/<agentId>/agent/auth.json`
|
||||
（发现静态 `api_key` 条目时会进行清理）
|
||||
|
||||
仅用于导入的旧版文件（仍然支持，但不是主存储）：
|
||||
仅用于旧版导入的文件（仍受支持，但不是主存储）：
|
||||
|
||||
- `~/.openclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`）
|
||||
- `~/.openclaw/credentials/oauth.json`（首次使用时会导入到 `auth-profiles.json`）
|
||||
|
||||
以上所有路径也遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys)
|
||||
以上所有位置也都遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys)
|
||||
|
||||
有关静态密钥引用和运行时快照激活行为，请参见 [Secrets Management](/gateway/secrets)。
|
||||
|
||||
## Anthropic setup-token（订阅认证）
|
||||
|
||||
<Warning>
|
||||
Anthropic setup-token 支持是技术兼容性，并非策略保证。
|
||||
Anthropic 过去曾阻止过某些在 Claude Code 之外的订阅使用。
|
||||
是否使用订阅认证由你自行决定，并请核实 Anthropic 当前的条款。
|
||||
</Warning>
|
||||
|
||||
在任意机器上运行 `claude setup-token`，然后将其粘贴到 OpenClaw 中：
|
||||
|
||||
```bash
|
||||
openclaw models auth setup-token --provider anthropic
|
||||
```
|
||||
|
||||
如果你在其他地方生成了令牌，可以手动粘贴：
|
||||
如果你是在其他地方生成的令牌，可手动粘贴：
|
||||
|
||||
```bash
|
||||
openclaw models auth paste-token --provider anthropic
|
||||
@ -75,77 +86,79 @@ openclaw models auth paste-token --provider anthropic
|
||||
openclaw models status
|
||||
```
|
||||
|
||||
## OAuth 交换（登录工作原理）
|
||||
## OAuth 交换（登录如何工作）
|
||||
|
||||
OpenClaw 的交互式登录流程在 `@mariozechner/pi-ai` 中实现，并集成到向导/命令中。
|
||||
OpenClaw 的交互式登录流程在 `@mariozechner/pi-ai` 中实现，并接入到各类向导/命令中。
|
||||
|
||||
### Anthropic（Claude Pro/Max）setup-token
|
||||
### Anthropic setup-token
|
||||
|
||||
流程概要：
|
||||
流程形态：
|
||||
|
||||
1. 运行 `claude setup-token`
|
||||
2. 将令牌粘贴到 OpenClaw
|
||||
3. 作为令牌认证配置文件存储（无刷新）
|
||||
3. 存储为令牌认证配置文件（不刷新）
|
||||
|
||||
向导路径为 `openclaw onboard` → 认证选择 `setup-token`（Anthropic）。
|
||||
|
||||
### OpenAI Codex（ChatGPT OAuth）
|
||||
|
||||
流程概要（PKCE）：
|
||||
OpenAI Codex OAuth 明确支持在 Codex CLI 之外使用，包括 OpenClaw 工作流。
|
||||
|
||||
1. 生成 PKCE 验证器/质询 + 随机 `state`
|
||||
流程形态（PKCE）：
|
||||
|
||||
1. 生成 PKCE verifier/challenge 和随机 `state`
|
||||
2. 打开 `https://auth.openai.com/oauth/authorize?...`
|
||||
3. 尝试在 `http://127.0.0.1:1455/auth/callback` 捕获回调
|
||||
4. 如果回调无法绑定（或你在远程/无头环境中），手动粘贴重定向 URL/代码
|
||||
5. 在 `https://auth.openai.com/oauth/token` 进行交换
|
||||
4. 如果回调无法绑定（或你是在远程/无头环境中），则粘贴重定向 URL/code
|
||||
5. 在 `https://auth.openai.com/oauth/token` 交换令牌
|
||||
6. 从访问令牌中提取 `accountId` 并存储 `{ access, refresh, expires, accountId }`
|
||||
|
||||
向导路径为 `openclaw onboard` → 认证选择 `openai-codex`。
|
||||
|
||||
## 刷新 + 过期
|
||||
## 刷新和过期
|
||||
|
||||
配置文件存储 `expires` 时间戳。
|
||||
配置文件会存储一个 `expires` 时间戳。
|
||||
|
||||
运行时：
|
||||
在运行时：
|
||||
|
||||
- 如果 `expires` 在未来 → 使用已存储的访问令牌
|
||||
- 如果已过期 → 刷新（在文件锁下）并覆盖已存储的凭据
|
||||
- 如果 `expires` 尚未到期 → 使用已存储的访问令牌
|
||||
- 如果已过期 → 在文件锁下刷新，并覆盖已存储的凭证
|
||||
|
||||
刷新流程是自动的；你通常不需要手动管理令牌。
|
||||
刷新流程是自动的；通常你不需要手动管理令牌。
|
||||
|
||||
## 多账户（配置文件）+ 路由
|
||||
## 多个账户（配置文件）+ 路由
|
||||
|
||||
两种模式：
|
||||
有两种模式：
|
||||
|
||||
### 1）推荐：独立智能体
|
||||
### 1）推荐：分离的智能体
|
||||
|
||||
如果你希望"个人"和"工作"永远不交叉，请使用隔离的智能体（独立的会话 + 凭据 + 工作区）：
|
||||
如果你希望“个人”和“工作”永不交叉，请使用隔离的智能体（独立的会话 + 凭证 + 工作区）：
|
||||
|
||||
```bash
|
||||
openclaw agents add work
|
||||
openclaw agents add personal
|
||||
```
|
||||
|
||||
然后按智能体配置认证（向导），并将聊天路由到正确的智能体。
|
||||
然后按智能体配置认证（使用向导），并将聊天路由到正确的智能体。
|
||||
|
||||
### 2）高级：单个智能体中的多个配置文件
|
||||
|
||||
`auth-profiles.json` 支持同一提供商的多个配置文件 ID。
|
||||
`auth-profiles.json` 支持同一提供商下的多个配置文件 ID。
|
||||
|
||||
选择使用哪个配置文件：
|
||||
|
||||
- 通过配置顺序全局设置（`auth.order`）
|
||||
- 通过 `/model ...@<profileId>` 按会话设置
|
||||
- 通过配置排序全局选择（`auth.order`）
|
||||
- 通过 `/model ...@<profileId>` 按会话选择
|
||||
|
||||
示例（会话覆盖）：
|
||||
|
||||
- `/model Opus@anthropic:work`
|
||||
|
||||
如何查看存在哪些配置文件 ID：
|
||||
查看现有配置文件 ID 的方法：
|
||||
|
||||
- `openclaw channels list --json`（显示 `auth[]`）
|
||||
|
||||
相关文档：
|
||||
|
||||
- [/concepts/model-failover](/concepts/model-failover)（轮换 + 冷却规则）
|
||||
- [/tools/slash-commands](/tools/slash-commands)（命令界面）
|
||||
- [/tools/slash-commands](/tools/slash-commands)（命令入口）
|
||||
|
||||
@ -1,41 +1,50 @@
|
||||
---
|
||||
read_when:
|
||||
- 调试模型认证或 OAuth 过期
|
||||
- 记录认证或凭证存储
|
||||
summary: 模型认证：OAuth、API 密钥和 setup-token
|
||||
- 编写有关认证或凭证存储的文档
|
||||
summary: 模型认证：OAuth、API key 和 setup-token
|
||||
title: 认证
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:47:32Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 66fa2c64ff374c9cfcdb4e7a951b0d164d512295e65513eb682f12191b75e557
|
||||
generated_at: "2026-03-16T06:22:17Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 219ac1acd7d192a5a12779e204cca65dae77a852fdc668271c45c01e0c69b7c9
|
||||
source_path: gateway/authentication.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 认证
|
||||
|
||||
OpenClaw 支持模型提供商的 OAuth 和 API 密钥。对于 Anthropic 账户，我们推荐使用 **API 密钥**。对于 Claude 订阅访问，使用 `claude setup-token` 创建的长期令牌。
|
||||
OpenClaw 支持模型提供商使用 OAuth 和 API key。对于始终在线的 Gateway 网关
|
||||
主机，API key 通常是最可预测的选项。当它们与你的提供商账号模型匹配时，
|
||||
也支持订阅/OAuth 流程。
|
||||
|
||||
参阅 [/concepts/oauth](/concepts/oauth) 了解完整的 OAuth 流程和存储布局。
|
||||
完整的 OAuth 流程和存储布局，请参阅 [/concepts/oauth](/concepts/oauth)。
|
||||
关于基于 SecretRef 的认证（`env`/`file`/`exec` 提供商），请参阅 [Secrets Management](/gateway/secrets)。
|
||||
关于 `models status --probe` 使用的凭证资格/原因码规则，请参阅
|
||||
[Auth Credential Semantics](/auth-credential-semantics)。
|
||||
|
||||
## 推荐的 Anthropic 设置（API 密钥）
|
||||
## 推荐设置（API key，任意提供商）
|
||||
|
||||
如果你直接使用 Anthropic，请使用 API 密钥。
|
||||
如果你正在运行长期存活的 Gateway 网关，请先为你选择的
|
||||
提供商配置一个 API key。
|
||||
对于 Anthropic，API key 认证是更稳妥的方式，推荐优先于
|
||||
订阅 setup-token 认证。
|
||||
|
||||
1. 在 Anthropic 控制台创建 API 密钥。
|
||||
2. 将其放在 **Gateway 网关主机**（运行 `openclaw gateway` 的机器）上。
|
||||
1. 在你的提供商控制台中创建一个 API key。
|
||||
2. 将它放在 **Gateway 网关主机** 上（运行 `openclaw gateway` 的机器）。
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="..."
|
||||
export <PROVIDER>_API_KEY="..."
|
||||
openclaw models status
|
||||
```
|
||||
|
||||
3. 如果 Gateway 网关在 systemd/launchd 下运行，最好将密钥放在 `~/.openclaw/.env` 中以便守护进程可以读取：
|
||||
3. 如果 Gateway 通过 systemd/launchd 运行，建议将 key 放入
|
||||
`~/.openclaw/.env`，这样守护进程就可以读取它：
|
||||
|
||||
```bash
|
||||
cat >> ~/.openclaw/.env <<'EOF'
|
||||
ANTHROPIC_API_KEY=...
|
||||
<PROVIDER>_API_KEY=...
|
||||
EOF
|
||||
```
|
||||
|
||||
@ -46,25 +55,28 @@ openclaw models status
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
如果你不想自己管理环境变量，新手引导向导可以为守护进程使用存储 API 密钥：`openclaw onboard`。
|
||||
如果你不想自己管理环境变量，设置向导可以为守护进程使用场景存储
|
||||
API key：`openclaw onboard`。
|
||||
|
||||
参阅[帮助](/help)了解环境变量继承的详情（`env.shellEnv`、`~/.openclaw/.env`、systemd/launchd）。
|
||||
有关环境继承（`env.shellEnv`、
|
||||
`~/.openclaw/.env`、systemd/launchd）的详细信息，请参阅 [Help](/help)。
|
||||
|
||||
## Anthropic：setup-token（订阅认证）
|
||||
|
||||
对于 Anthropic，推荐的路径是 **API 密钥**。如果你使用 Claude 订阅，也支持 setup-token 流程。在 **Gateway 网关主机**上运行：
|
||||
如果你使用的是 Claude 订阅，则支持 setup-token 流程。请在
|
||||
**Gateway 网关主机** 上运行：
|
||||
|
||||
```bash
|
||||
claude setup-token
|
||||
```
|
||||
|
||||
然后将其粘贴到 OpenClaw：
|
||||
然后将它粘贴到 OpenClaw 中：
|
||||
|
||||
```bash
|
||||
openclaw models auth setup-token --provider anthropic
|
||||
```
|
||||
|
||||
如果令牌是在另一台机器上创建的，手动粘贴：
|
||||
如果 token 是在另一台机器上创建的，请手动粘贴：
|
||||
|
||||
```bash
|
||||
openclaw models auth paste-token --provider anthropic
|
||||
@ -76,22 +88,34 @@ openclaw models auth paste-token --provider anthropic
|
||||
This credential is only authorized for use with Claude Code and cannot be used for other API requests.
|
||||
```
|
||||
|
||||
…请改用 Anthropic API 密钥。
|
||||
……请改用 Anthropic API key。
|
||||
|
||||
手动令牌输入（任何提供商；写入 `auth-profiles.json` + 更新配置）：
|
||||
<Warning>
|
||||
Anthropic setup-token 支持仅是技术兼容性。Anthropic 过去曾阻止
|
||||
Claude Code 之外的某些订阅用法。只有在你认为相关策略风险可接受时才使用它，
|
||||
并请你自行核实 Anthropic 当前的条款。
|
||||
</Warning>
|
||||
|
||||
手动输入 token（任意提供商；会写入 `auth-profiles.json` + 更新配置）：
|
||||
|
||||
```bash
|
||||
openclaw models auth paste-token --provider anthropic
|
||||
openclaw models auth paste-token --provider openrouter
|
||||
```
|
||||
|
||||
自动化友好检查（过期/缺失时退出 `1`，即将过期时退出 `2`）：
|
||||
静态凭证也支持凭证配置文件引用：
|
||||
|
||||
- `api_key` 凭证可以使用 `keyRef: { source, provider, id }`
|
||||
- `token` 凭证可以使用 `tokenRef: { source, provider, id }`
|
||||
|
||||
适合自动化的检查（已过期/缺失时退出码为 `1`，即将过期时为 `2`）：
|
||||
|
||||
```bash
|
||||
openclaw models status --check
|
||||
```
|
||||
|
||||
可选的运维脚本（systemd/Termux）在此处记录：[/automation/auth-monitoring](/automation/auth-monitoring)
|
||||
可选的运维脚本（systemd/Termux）记录在这里：
|
||||
[/automation/auth-monitoring](/automation/auth-monitoring)
|
||||
|
||||
> `claude setup-token` 需要交互式 TTY。
|
||||
|
||||
@ -102,17 +126,33 @@ openclaw models status
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
## API key 轮换行为（Gateway 网关）
|
||||
|
||||
某些提供商支持在 API 调用触发提供商限流时，使用替代 key 重试请求。
|
||||
|
||||
- 优先级顺序：
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个覆盖值）
|
||||
- `<PROVIDER>_API_KEYS`
|
||||
- `<PROVIDER>_API_KEY`
|
||||
- `<PROVIDER>_API_KEY_*`
|
||||
- Google 提供商还将 `GOOGLE_API_KEY` 作为额外回退项。
|
||||
- 使用前会对同一组 key 列表去重。
|
||||
- 仅当出现限流错误时，OpenClaw 才会使用下一个 key 重试（例如
|
||||
`429`、`rate_limit`、`quota`、`resource exhausted`）。
|
||||
- 非限流错误不会使用替代 key 重试。
|
||||
- 如果所有 key 都失败，则返回最后一次尝试的最终错误。
|
||||
|
||||
## 控制使用哪个凭证
|
||||
|
||||
### 每会话（聊天命令）
|
||||
### 每个会话（聊天命令）
|
||||
|
||||
使用 `/model <alias-or-id>@<profileId>` 为当前会话固定特定的提供商凭证（示例配置文件 ID：`anthropic:default`、`anthropic:work`）。
|
||||
使用 `/model <alias-or-id>@<profileId>` 为当前会话固定使用特定的提供商凭证（示例配置文件 id：`anthropic:default`、`anthropic:work`）。
|
||||
|
||||
使用 `/model`（或 `/model list`）获取紧凑的选择器；使用 `/model status` 获取完整视图（候选项 + 下一个认证配置文件，以及配置时的提供商端点详情）。
|
||||
使用 `/model`（或 `/model list`）查看紧凑选择器；使用 `/model status` 查看完整视图（候选项 + 下一个凭证配置文件，以及在已配置时显示提供商端点详情）。
|
||||
|
||||
### 每智能体（CLI 覆盖）
|
||||
### 每个智能体（CLI 覆盖）
|
||||
|
||||
为智能体设置显式的认证配置文件顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）：
|
||||
为智能体设置显式的凭证配置文件顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）：
|
||||
|
||||
```bash
|
||||
openclaw models auth order get --provider anthropic
|
||||
@ -120,23 +160,25 @@ openclaw models auth order set --provider anthropic anthropic:default
|
||||
openclaw models auth order clear --provider anthropic
|
||||
```
|
||||
|
||||
使用 `--agent <id>` 指定特定智能体；省略它则使用配置的默认智能体。
|
||||
使用 `--agent <id>` 指定特定智能体；省略它则使用已配置的默认智能体。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### "No credentials found"
|
||||
### “No credentials found”
|
||||
|
||||
如果 Anthropic 令牌配置文件缺失，在 **Gateway 网关主机**上运行 `claude setup-token`，然后重新检查：
|
||||
如果缺少 Anthropic token 配置文件，请在
|
||||
**Gateway 网关主机** 上运行 `claude setup-token`，然后重新检查：
|
||||
|
||||
```bash
|
||||
openclaw models status
|
||||
```
|
||||
|
||||
### 令牌即将过期/已过期
|
||||
### Token 即将过期/已过期
|
||||
|
||||
运行 `openclaw models status` 确认哪个配置文件即将过期。如果配置文件缺失，重新运行 `claude setup-token` 并再次粘贴令牌。
|
||||
运行 `openclaw models status` 以确认哪个配置文件即将过期。如果该配置文件
|
||||
缺失，请重新运行 `claude setup-token` 并再次粘贴 token。
|
||||
|
||||
## 要求
|
||||
|
||||
- Claude Max 或 Pro 订阅（用于 `claude setup-token`）
|
||||
- Anthropic 订阅账号（用于 `claude setup-token`）
|
||||
- 已安装 Claude Code CLI（`claude` 命令可用）
|
||||
|
||||
3103
docs/zh-CN/gateway/configuration-reference.md
Normal file
3103
docs/zh-CN/gateway/configuration-reference.md
Normal file
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -1,35 +1,37 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想从自己的 GPU 机器提供模型服务
|
||||
- 你正在配置 LM Studio 或 OpenAI 兼容代理
|
||||
- 你想从自己的 GPU 主机提供模型服务
|
||||
- 你正在接入 LM Studio 或兼容 OpenAI 的代理
|
||||
- 你需要最安全的本地模型指南
|
||||
summary: 在本地 LLM 上运行 OpenClaw（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点）
|
||||
title: 本地模型
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:48:15Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: f72b424c3d8986319868dc4c552596bcd599cc79fab5a57c14bf4f0695c39690
|
||||
generated_at: "2026-03-16T06:22:54Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 43ad6b91216e12be4d0c9395c981e0b5d8bd16ba4952efd02b7261052304a4ce
|
||||
source_path: gateway/local-models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 本地模型
|
||||
|
||||
本地运行是可行的，但 OpenClaw 期望大上下文 + 强大的提示注入防御。小显存会截断上下文并泄露安全性。目标要高：**≥2 台满配 Mac Studio 或同等 GPU 配置（约 $30k+）**。单张 **24 GB** GPU 仅适用于较轻的提示，且延迟更高。使用**你能运行的最大/完整尺寸模型变体**；激进量化或"小型"检查点会增加提示注入风险（参见[安全](/gateway/security)）。
|
||||
本地部署是可行的，但 OpenClaw 需要大上下文和对提示注入的强防御能力。小显卡会截断上下文并削弱安全性。目标要高：**至少 2 台满配 Mac Studio 或同等 GPU 设备（约 3 万美元以上）**。单张 **24 GB** GPU 仅适用于较轻的提示，且延迟更高。请使用**你能运行的最大 / 完整尺寸模型变体**；激进量化或“small”检查点会提高提示注入风险（见 [安全](/gateway/security)）。
|
||||
|
||||
## 推荐：LM Studio + MiniMax M2.1（Responses API，完整尺寸）
|
||||
如果你想要摩擦最小的本地设置，请从 [Ollama](/providers/ollama) 和 `openclaw onboard` 开始。本页是面向更高端本地栈和自定义兼容 OpenAI 的本地服务器的偏好型指南。
|
||||
|
||||
当前最佳本地堆栈。在 LM Studio 中加载 MiniMax M2.1，启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 将推理与最终文本分开。
|
||||
## 推荐：LM Studio + MiniMax M2.5（Responses API，完整尺寸）
|
||||
|
||||
当前最佳的本地栈。先在 LM Studio 中加载 MiniMax M2.5，启用本地服务器（默认 `http://127.0.0.1:1234`），然后使用 Responses API 将推理与最终文本分离。
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "lmstudio/minimax-m2.1-gs32" },
|
||||
model: { primary: "lmstudio/minimax-m2.5-gs32" },
|
||||
models: {
|
||||
"anthropic/claude-opus-4-5": { alias: "Opus" },
|
||||
"lmstudio/minimax-m2.1-gs32": { alias: "Minimax" },
|
||||
"anthropic/claude-opus-4-6": { alias: "Opus" },
|
||||
"lmstudio/minimax-m2.5-gs32": { alias: "Minimax" },
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -42,8 +44,8 @@ x-i18n:
|
||||
api: "openai-responses",
|
||||
models: [
|
||||
{
|
||||
id: "minimax-m2.1-gs32",
|
||||
name: "MiniMax M2.1 GS32",
|
||||
id: "minimax-m2.5-gs32",
|
||||
name: "MiniMax M2.5 GS32",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
@ -59,15 +61,15 @@ x-i18n:
|
||||
|
||||
**设置清单**
|
||||
|
||||
- 安装 LM Studio：https://lmstudio.ai
|
||||
- 在 LM Studio 中，下载**可用的最大 MiniMax M2.1 构建**（避免"小型"/重度量化变体），启动服务器，确认 `http://127.0.0.1:1234/v1/models` 列出了它。
|
||||
- 保持模型加载；冷加载会增加启动延迟。
|
||||
- 如果你的 LM Studio 构建不同，调整 `contextWindow`/`maxTokens`。
|
||||
- 对于 WhatsApp，坚持使用 Responses API，这样只发送最终文本。
|
||||
- 安装 LM Studio：[https://lmstudio.ai](https://lmstudio.ai)
|
||||
- 在 LM Studio 中，下载**可用的最大 MiniMax M2.5 构建版本**（避免 “small” / 重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 中列出了它。
|
||||
- 保持模型处于已加载状态；冷加载会增加启动延迟。
|
||||
- 如果你的 LM Studio 构建不同，请调整 `contextWindow` / `maxTokens`。
|
||||
- 对于 WhatsApp，请坚持使用 Responses API，这样只会发送最终文本。
|
||||
|
||||
即使运行本地模型也要保持托管模型的配置；使用 `models.mode: "merge"` 以便备用方案保持可用。
|
||||
即使在本地运行时，也要保留托管模型配置；使用 `models.mode: "merge"`，以便回退模型始终可用。
|
||||
|
||||
### 混合配置：托管为主，本地备用
|
||||
### 混合配置：托管主模型，本地回退
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -75,12 +77,12 @@ x-i18n:
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "anthropic/claude-sonnet-4-5",
|
||||
fallbacks: ["lmstudio/minimax-m2.1-gs32", "anthropic/claude-opus-4-5"],
|
||||
fallbacks: ["lmstudio/minimax-m2.5-gs32", "anthropic/claude-opus-4-6"],
|
||||
},
|
||||
models: {
|
||||
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
|
||||
"lmstudio/minimax-m2.1-gs32": { alias: "MiniMax Local" },
|
||||
"anthropic/claude-opus-4-5": { alias: "Opus" },
|
||||
"lmstudio/minimax-m2.5-gs32": { alias: "MiniMax Local" },
|
||||
"anthropic/claude-opus-4-6": { alias: "Opus" },
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -93,8 +95,8 @@ x-i18n:
|
||||
api: "openai-responses",
|
||||
models: [
|
||||
{
|
||||
id: "minimax-m2.1-gs32",
|
||||
name: "MiniMax M2.1 GS32",
|
||||
id: "minimax-m2.5-gs32",
|
||||
name: "MiniMax M2.5 GS32",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
@ -108,18 +110,18 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
### 本地优先，托管作为安全网
|
||||
### 本地优先，并保留托管安全网
|
||||
|
||||
交换主要和备用的顺序；保持相同的 providers 块和 `models.mode: "merge"`，这样当本地机器宕机时可以回退到 Sonnet 或 Opus。
|
||||
交换主模型与回退模型的顺序；保留相同的 providers 块和 `models.mode: "merge"`，这样当本地主机不可用时，你仍然可以回退到 Sonnet 或 Opus。
|
||||
|
||||
### 区域托管/数据路由
|
||||
### 区域托管 / 数据路由
|
||||
|
||||
- 托管的 MiniMax/Kimi/GLM 变体也存在于 OpenRouter 上，带有区域固定端点（例如，美国托管）。在那里选择区域变体以将流量保持在你选择的管辖区内，同时仍使用 `models.mode: "merge"` 作为 Anthropic/OpenAI 备用。
|
||||
- 纯本地仍然是最强的隐私路径；当你需要提供商功能但又想控制数据流时，托管区域路由是折中方案。
|
||||
- OpenRouter 上也提供托管版 MiniMax / Kimi / GLM 变体，并带有区域固定端点（例如托管在美国）。可以在那里选择区域变体，将流量保留在你选定的司法辖区内，同时继续使用 `models.mode: "merge"` 作为 Anthropic / OpenAI 回退。
|
||||
- 纯本地仍然是最强的隐私方案；当你需要提供商功能但又想控制数据流向时，托管区域路由是折中方案。
|
||||
|
||||
## 其他 OpenAI 兼容本地代理
|
||||
## 其他兼容 OpenAI 的本地代理
|
||||
|
||||
vLLM、LiteLLM、OAI-proxy 或自定义网关都可以工作，只要它们暴露 OpenAI 风格的 `/v1` 端点。用你的端点和模型 ID 替换上面的 provider 块：
|
||||
只要暴露兼容 OpenAI 风格的 `/v1` 端点，vLLM、LiteLLM、OAI-proxy 或自定义网关都可以工作。将上面的 provider 块替换为你的端点和模型 ID：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -147,11 +149,11 @@ vLLM、LiteLLM、OAI-proxy 或自定义网关都可以工作，只要它们暴
|
||||
}
|
||||
```
|
||||
|
||||
保持 `models.mode: "merge"` 以便托管模型作为备用保持可用。
|
||||
保留 `models.mode: "merge"`，这样托管模型仍可作为回退使用。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- Gateway 网关能访问代理吗？`curl http://127.0.0.1:1234/v1/models`。
|
||||
- LM Studio 模型卸载了？重新加载；冷启动是常见的"卡住"原因。
|
||||
- 上下文错误？降低 `contextWindow` 或提高服务器限制。
|
||||
- 安全：本地模型跳过提供商端过滤器；保持智能体范围窄并开启压缩以限制提示注入的影响范围。
|
||||
- Gateway 网关能连接到代理吗？`curl http://127.0.0.1:1234/v1/models`
|
||||
- LM Studio 模型已卸载？重新加载；冷启动是常见的“卡住”原因。
|
||||
- 上下文错误？降低 `contextWindow` 或提高你的服务器限制。
|
||||
- 安全性：本地模型会跳过提供商侧过滤；请保持智能体职责范围狭窄，并开启压缩，以限制提示注入的影响范围。
|
||||
|
||||
@ -1,35 +1,35 @@
|
||||
---
|
||||
read_when:
|
||||
- 在同一台机器上运行多个 Gateway 网关
|
||||
- 你需要每个 Gateway 网关有隔离的配置/状态/端口
|
||||
summary: 在同一主机上运行多个 OpenClaw Gateway 网关（隔离、端口和配置文件）
|
||||
title: 多 Gateway 网关
|
||||
- 你需要为每个 Gateway 网关隔离配置/状态/端口
|
||||
summary: 在一台主机上运行多个 OpenClaw Gateway 网关（隔离、端口和配置档案）
|
||||
title: 多个 Gateway 网关
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:48:13Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 09b5035d4e5fb97c8d4596f7e23dea67224dad3b6d9e2c37ecb99840f28bd77d
|
||||
generated_at: "2026-03-16T06:23:07Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 98c14bed7b7447481325d60ac379846ae379326400c4b0ed7f8d320ad8c50080
|
||||
source_path: gateway/multiple-gateways.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 多 Gateway 网关（同一主机）
|
||||
# 多个 Gateway 网关（同一主机）
|
||||
|
||||
大多数设置应该使用单个 Gateway 网关，因为一个 Gateway 网关可以处理多个消息连接和智能体。如果你需要更强的隔离或冗余（例如，救援机器人），请使用隔离的配置文件/端口运行多个 Gateway 网关。
|
||||
大多数设置应使用一个 Gateway 网关，因为单个 Gateway 网关可以处理多个消息连接和智能体。如果你需要更强的隔离或冗余（例如救援机器人），请运行使用隔离配置档案/端口的独立 Gateway 网关。
|
||||
|
||||
## 隔离检查清单（必需）
|
||||
|
||||
- `OPENCLAW_CONFIG_PATH` — 每个实例的配置文件
|
||||
- `OPENCLAW_STATE_DIR` — 每个实例的会话、凭证、缓存
|
||||
- `agents.defaults.workspace` — 每个实例的工作区根目录
|
||||
- `OPENCLAW_CONFIG_PATH` — 每个实例单独的配置文件
|
||||
- `OPENCLAW_STATE_DIR` — 每个实例单独的会话、凭证、缓存
|
||||
- `agents.defaults.workspace` — 每个实例单独的工作区根目录
|
||||
- `gateway.port`（或 `--port`）— 每个实例唯一
|
||||
- 派生端口（浏览器/画布）不得重叠
|
||||
- 派生端口（browser/canvas）不得重叠
|
||||
|
||||
如果这些是共享的，你将遇到配置竞争和端口冲突。
|
||||
如果这些被共享，你会遇到配置竞争和端口冲突。
|
||||
|
||||
## 推荐：配置文件（`--profile`）
|
||||
## 推荐：配置档案（`--profile`）
|
||||
|
||||
配置文件自动限定 `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH` 范围并为服务名称添加后缀。
|
||||
配置档案会自动限定 `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH`，并为服务名称添加后缀。
|
||||
|
||||
```bash
|
||||
# main
|
||||
@ -41,7 +41,7 @@ openclaw --profile rescue setup
|
||||
openclaw --profile rescue gateway --port 19001
|
||||
```
|
||||
|
||||
按配置文件的服务：
|
||||
每个配置档案的服务：
|
||||
|
||||
```bash
|
||||
openclaw --profile main gateway install
|
||||
@ -50,34 +50,34 @@ openclaw --profile rescue gateway install
|
||||
|
||||
## 救援机器人指南
|
||||
|
||||
在同一主机上运行第二个 Gateway 网关，使用独立的：
|
||||
在同一主机上运行第二个 Gateway 网关，并为它单独设置：
|
||||
|
||||
- 配置文件/配置
|
||||
- 配置档案/配置
|
||||
- 状态目录
|
||||
- 工作区
|
||||
- 基础端口（加上派生端口）
|
||||
- 基础端口（以及派生端口）
|
||||
|
||||
这使救援机器人与主机器人隔离，以便在主机器人宕机时可以调试或应用配置更改。
|
||||
这样可以将救援机器人与主机器人隔离，因此当主机器人宕机时，它仍可用于调试或应用配置更改。
|
||||
|
||||
端口间距：在基础端口之间至少留出 20 个端口，这样派生的浏览器/画布/CDP 端口永远不会冲突。
|
||||
端口间距：基础端口之间至少保留 20 个端口，以确保派生的 browser/canvas/CDP 端口永不冲突。
|
||||
|
||||
### 如何安装（救援机器人）
|
||||
|
||||
```bash
|
||||
# 主机器人（现有或新建，不带 --profile 参数）
|
||||
# Main bot（现有或全新，不带 --profile 参数）
|
||||
# 运行在端口 18789 + Chrome CDC/Canvas/... 端口
|
||||
openclaw onboard
|
||||
openclaw gateway install
|
||||
|
||||
# 救援机器人（隔离的配置文件 + 端口）
|
||||
# Rescue bot（隔离的配置档案 + 端口）
|
||||
openclaw --profile rescue onboard
|
||||
# 注意：
|
||||
# - 工作区名称默认会添加 -rescue 后缀
|
||||
# - 端口应至少为 18789 + 20 个端口，
|
||||
# 最好选择完全不同的基础端口，如 19789，
|
||||
# - 其余的新手引导与正常相同
|
||||
# 说明：
|
||||
# - 工作区名称默认会追加 -rescue 后缀
|
||||
# - 端口至少应为 18789 + 20 个端口，
|
||||
# 最好选择完全不同的基础端口，例如 19789，
|
||||
# - 其余新手引导与正常情况相同
|
||||
|
||||
# 安装服务（如果在新手引导期间没有自动完成）
|
||||
# 安装服务（如果设置期间未自动完成）
|
||||
openclaw --profile rescue gateway install
|
||||
```
|
||||
|
||||
@ -85,18 +85,18 @@ openclaw --profile rescue gateway install
|
||||
|
||||
基础端口 = `gateway.port`（或 `OPENCLAW_GATEWAY_PORT` / `--port`）。
|
||||
|
||||
- 浏览器控制服务端口 = 基础 + 2（仅 loopback）
|
||||
- `canvasHost.port = 基础 + 4`
|
||||
- 浏览器配置文件 CDP 端口从 `browser.controlPort + 9 .. + 108` 自动分配
|
||||
- browser 控制服务端口 = 基础端口 + 2（仅 loopback）
|
||||
- canvas host 由 Gateway 网关 HTTP 服务器提供（与 `gateway.port` 使用相同端口）
|
||||
- Browser profile CDP 端口会从 `browser.controlPort + 9 .. + 108` 自动分配
|
||||
|
||||
如果你在配置或环境变量中覆盖了这些，必须确保每个实例都唯一。
|
||||
如果你在配置或环境变量中覆盖了其中任何一个，必须确保它们在每个实例之间保持唯一。
|
||||
|
||||
## 浏览器/CDP 注意事项（常见陷阱）
|
||||
## Browser/CDP 说明（常见陷阱）
|
||||
|
||||
- **不要**在多个实例上将 `browser.cdpUrl` 固定为相同的值。
|
||||
- 每个实例需要自己的浏览器控制端口和 CDP 范围（从其 Gateway 网关端口派生）。
|
||||
- 如果你需要显式的 CDP 端口，请为每个实例设置 `browser.profiles.<name>.cdpPort`。
|
||||
- 远程 Chrome：使用 `browser.profiles.<name>.cdpUrl`（每个配置文件，每个实例）。
|
||||
- **不要**在多个实例上将 `browser.cdpUrl` 固定为相同值。
|
||||
- 每个实例都需要自己的 browser 控制端口和 CDP 范围（从其 Gateway 网关端口派生）。
|
||||
- 如果你需要显式 CDP 端口，请为每个实例设置 `browser.profiles.<name>.cdpPort`。
|
||||
- 远程 Chrome：使用 `browser.profiles.<name>.cdpUrl`（按配置档案、按实例设置）。
|
||||
|
||||
## 手动环境变量示例
|
||||
|
||||
|
||||
@ -2,10 +2,10 @@
|
||||
summary: 关于 OpenClaw 安装、配置和使用的常见问题
|
||||
title: 常见问题
|
||||
x-i18n:
|
||||
generated_at: "2026-03-16T01:39:16Z"
|
||||
generated_at: "2026-03-16T06:52:18Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 6e6a4a63fb73dca24dbe77928b51c6b2e5d51ec883fb36c64e2e40ef027050e9
|
||||
source_hash: 94f7c6ea1024d5606379ce80d65a006b3acc12a963d57ca2333fcee3e5a31872
|
||||
source_path: help/faq.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
@ -1,50 +1,51 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想要一个便宜的常驻 Linux 主机来运行 Gateway 网关
|
||||
- 你想要远程控制 UI 访问而无需运行自己的 VPS
|
||||
- 你想为 Gateway 网关使用一台便宜且始终在线的 Linux 主机
|
||||
- 你想在不自行运行 VPS 的情况下远程访问控制 UI
|
||||
summary: 在 exe.dev 上运行 OpenClaw Gateway 网关（VM + HTTPS 代理）以实现远程访问
|
||||
title: exe.dev
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:51:36Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 8d57ee7dd6029f0b778465c147092b824a0f1b0680af13032aaf116ff3d4d671
|
||||
source_path: platforms/exe-dev.md
|
||||
generated_at: "2026-03-16T06:23:23Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3c90f57e37145333429328477a3e12306586aa53283127daec75e065dbb85e39
|
||||
source_path: install/exe-dev.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# exe.dev
|
||||
|
||||
目标：OpenClaw Gateway 网关运行在 exe.dev VM 上，可从你的笔记本电脑通过以下地址访问：`https://<vm-name>.exe.xyz`
|
||||
目标：让 OpenClaw Gateway 网关运行在 exe.dev VM 上，并且可通过你的笔记本电脑访问：`https://<vm-name>.exe.xyz`
|
||||
|
||||
本页假设使用 exe.dev 的默认 **exeuntu** 镜像。如果你选择了不同的发行版，请相应地映射软件包。
|
||||
本页假设你使用的是 exe.dev 默认的 **exeuntu** 镜像。如果你选择了不同的发行版，请相应调整软件包。
|
||||
|
||||
## 新手快速路径
|
||||
## 面向初学者的快速路径
|
||||
|
||||
1. [https://exe.new/openclaw](https://exe.new/openclaw)
|
||||
2. 根据需要填写你的认证密钥/令牌
|
||||
3. 点击 VM 旁边的"Agent"，然后等待...
|
||||
2. 根据需要填写你的身份验证密钥/令牌
|
||||
3. 点击你的 VM 旁边的 “Agent”，然后等待……
|
||||
4. ???
|
||||
5. 完成
|
||||
5. 成功
|
||||
|
||||
## 你需要什么
|
||||
## 你需要准备的内容
|
||||
|
||||
- exe.dev 账户
|
||||
- `ssh exe.dev` 访问 [exe.dev](https://exe.dev) 虚拟机（可选）
|
||||
- 对 [exe.dev](https://exe.dev) 虚拟机的 `ssh exe.dev` 访问权限（可选）
|
||||
|
||||
## 使用 Shelley 自动安装
|
||||
|
||||
Shelley，[exe.dev](https://exe.dev) 的智能体，可以使用我们的提示立即安装 OpenClaw。使用的提示如下：
|
||||
Shelley 是 [exe.dev](https://exe.dev) 的智能体，可以使用我们的提示词立即安装 OpenClaw。
|
||||
使用的提示词如下：
|
||||
|
||||
```
|
||||
Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-interactive and accept-risk flags for openclaw onboarding. Add the supplied auth or token as needed. Configure nginx to forward from the default port 18789 to the root location on the default enabled site config, making sure to enable Websocket support. Pairing is done by "openclaw devices list" and "openclaw device approve <request id>". Make sure the dashboard shows that OpenClaw's health is OK. exe.dev handles forwarding from port 8000 to port 80/443 and HTTPS for us, so the final "reachable" should be <vm-name>.exe.xyz, without port specification.
|
||||
Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-interactive and accept-risk flags for openclaw onboarding. Add the supplied auth or token as needed. Configure nginx to forward from the default port 18789 to the root location on the default enabled site config, making sure to enable Websocket support. Pairing is done by "openclaw devices list" and "openclaw devices approve <request id>". Make sure the dashboard shows that OpenClaw's health is OK. exe.dev handles forwarding from port 8000 to port 80/443 and HTTPS for us, so the final "reachable" should be <vm-name>.exe.xyz, without port specification.
|
||||
```
|
||||
|
||||
## 手动安装
|
||||
|
||||
## 1) 创建 VM
|
||||
## 1）创建 VM
|
||||
|
||||
从你的设备：
|
||||
在你的设备上运行：
|
||||
|
||||
```bash
|
||||
ssh exe.dev new
|
||||
@ -56,16 +57,16 @@ ssh exe.dev new
|
||||
ssh <vm-name>.exe.xyz
|
||||
```
|
||||
|
||||
提示：保持此 VM **有状态**。OpenClaw 在 `~/.openclaw/` 和 `~/.openclaw/workspace/` 下存储状态。
|
||||
提示：请让这个 VM 保持**有状态**。OpenClaw 会将状态存储在 `~/.openclaw/` 和 `~/.openclaw/workspace/` 下。
|
||||
|
||||
## 2) 安装先决条件（在 VM 上）
|
||||
## 2）安装前置依赖（在 VM 上）
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y git curl jq ca-certificates openssl
|
||||
```
|
||||
|
||||
## 3) 安装 OpenClaw
|
||||
## 3）安装 OpenClaw
|
||||
|
||||
运行 OpenClaw 安装脚本：
|
||||
|
||||
@ -73,9 +74,9 @@ sudo apt-get install -y git curl jq ca-certificates openssl
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
## 4) 设置 nginx 将 OpenClaw 代理到端口 8000
|
||||
## 4）设置 nginx，将 OpenClaw 代理到端口 8000
|
||||
|
||||
编辑 `/etc/nginx/sites-enabled/default`：
|
||||
编辑 `/etc/nginx/sites-enabled/default`，内容如下：
|
||||
|
||||
```
|
||||
server {
|
||||
@ -90,30 +91,35 @@ server {
|
||||
proxy_pass http://127.0.0.1:18789;
|
||||
proxy_http_version 1.1;
|
||||
|
||||
# WebSocket 支持
|
||||
# WebSocket support
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
|
||||
# 标准代理头
|
||||
# Standard proxy headers
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# 长连接超时设置
|
||||
# Timeout settings for long-lived connections
|
||||
proxy_read_timeout 86400s;
|
||||
proxy_send_timeout 86400s;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5) 访问 OpenClaw 并授予权限
|
||||
## 5）访问 OpenClaw 并授予权限
|
||||
|
||||
访问 `https://<vm-name>.exe.xyz/?token=YOUR-TOKEN-FROM-TERMINAL`（参阅新手引导中的控制 UI 输出）。使用 `openclaw devices list` 和 `openclaw devices approve <requestId>` 批准设备。如有疑问，从浏览器使用 Shelley！
|
||||
访问 `https://<vm-name>.exe.xyz/`（请查看新手引导输出中的控制 UI）。如果提示进行身份验证，请粘贴 VM 上的
|
||||
`gateway.auth.token` 中的令牌（可通过 `openclaw config get gateway.auth.token` 获取，或使用
|
||||
`openclaw doctor --generate-gateway-token` 生成）。使用 `openclaw devices list` 和
|
||||
`openclaw devices approve <requestId>` 批准设备。如果拿不准，请在浏览器中使用 Shelley！
|
||||
|
||||
## 远程访问
|
||||
|
||||
远程访问由 [exe.dev](https://exe.dev) 的认证处理。默认情况下，来自端口 8000 的 HTTP 流量通过电子邮件认证转发到 `https://<vm-name>.exe.xyz`。
|
||||
远程访问由 [exe.dev](https://exe.dev) 的身份验证处理。默认情况下，
|
||||
来自端口 8000 的 HTTP 流量会被转发到 `https://<vm-name>.exe.xyz`，
|
||||
并使用电子邮件身份验证。
|
||||
|
||||
## 更新
|
||||
|
||||
@ -124,4 +130,4 @@ openclaw gateway restart
|
||||
openclaw health
|
||||
```
|
||||
|
||||
指南：[更新](/install/updating)
|
||||
指南：[Updating](/install/updating)
|
||||
|
||||
@ -1,170 +1,204 @@
|
||||
---
|
||||
read_when:
|
||||
- 安装 OpenClaw
|
||||
- 你想从 GitHub 安装
|
||||
summary: 安装 OpenClaw（推荐安装器、全局安装或从源代码安装）
|
||||
- 你需要一种不同于“入门指南”快速开始的安装方式
|
||||
- 你想部署到云平台
|
||||
- 你需要更新、迁移或卸载
|
||||
summary: 安装 OpenClaw —— 安装脚本、npm/pnpm、从源码、Docker 等
|
||||
title: 安装
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T10:07:43Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: b26f48c116c26c163ee0090fb4c3e29622951bd427ecaeccba7641d97cfdf17a
|
||||
generated_at: "2026-03-16T06:23:36Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 14b80b6176b2a4ff5c60aad2db88460d8d980bd416faaa3103b38d90521496af
|
||||
source_path: install/index.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 安装
|
||||
|
||||
除非有特殊原因，否则请使用安装器。它会设置 CLI 并运行新手引导。
|
||||
|
||||
## 快速安装（推荐）
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
Windows（PowerShell）：
|
||||
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex
|
||||
```
|
||||
|
||||
下一步（如果你跳过了新手引导）：
|
||||
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
已经按照 [入门指南](/start/getting-started) 操作过了吗？那你已经准备好了 —— 本页适用于其他安装方法、特定平台说明以及维护操作。
|
||||
|
||||
## 系统要求
|
||||
|
||||
- **Node >=22**
|
||||
- macOS、Linux 或通过 WSL2 的 Windows
|
||||
- `pnpm` 仅在从源代码构建时需要
|
||||
- **[Node 24（推荐）](/install/node)**（出于兼容性考虑，仍支持 Node 22 LTS，目前为 `22.16+`；如果缺失，[安装脚本](#install-methods) 会安装 Node 24）
|
||||
- macOS、Linux 或 Windows
|
||||
- 仅当你从源码构建时需要 `pnpm`
|
||||
|
||||
## 选择安装路径
|
||||
<Note>
|
||||
在 Windows 上，我们强烈建议你在 [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) 下运行 OpenClaw。
|
||||
</Note>
|
||||
|
||||
### 1）安装器脚本（推荐）
|
||||
## 安装方法
|
||||
|
||||
通过 npm 全局安装 `openclaw` 并运行新手引导。
|
||||
<Tip>
|
||||
**安装脚本** 是安装 OpenClaw 的推荐方式。它会一步完成 Node 检测、安装和新手引导。
|
||||
</Tip>
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
<Warning>
|
||||
对于 VPS/云主机，尽量避免使用第三方“一键式”市场镜像。优先选择干净的基础 OS 镜像（例如 Ubuntu LTS），然后使用安装脚本自行安装 OpenClaw。
|
||||
</Warning>
|
||||
|
||||
安装器标志：
|
||||
<AccordionGroup>
|
||||
<Accordion title="安装脚本" icon="rocket" defaultOpen>
|
||||
下载 CLI，通过 npm 全局安装，并启动设置向导。
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
|
||||
```
|
||||
<Tabs>
|
||||
<Tab title="macOS / Linux / WSL2">
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Windows (PowerShell)">
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
详情：[安装器内部原理](/install/installer)。
|
||||
就这样 —— 脚本会处理 Node 检测、安装和新手引导。
|
||||
|
||||
非交互式（跳过新手引导）：
|
||||
如果要跳过新手引导，只安装二进制文件：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
|
||||
```
|
||||
<Tabs>
|
||||
<Tab title="macOS / Linux / WSL2">
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Windows (PowerShell)">
|
||||
```powershell
|
||||
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 2）全局安装（手动）
|
||||
所有标志、环境变量以及 CI/自动化选项，请参阅 [Installer internals](/install/installer)。
|
||||
|
||||
如果你已经有 Node：
|
||||
</Accordion>
|
||||
|
||||
```bash
|
||||
npm install -g openclaw@latest
|
||||
```
|
||||
<Accordion title="npm / pnpm" icon="package">
|
||||
如果你已经自行管理 Node，我们推荐使用 Node 24。出于兼容性考虑，OpenClaw 仍支持 Node 22 LTS，目前为 `22.16+`：
|
||||
|
||||
如果你全局安装了 libvips（macOS 上通过 Homebrew 安装很常见）且 `sharp` 安装失败，请强制使用预构建二进制文件：
|
||||
<Tabs>
|
||||
<Tab title="npm">
|
||||
```bash
|
||||
npm install -g openclaw@latest
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
```bash
|
||||
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
|
||||
```
|
||||
<Accordion title="sharp 构建错误？">
|
||||
如果你全局安装了 libvips（在 macOS 上通过 Homebrew 很常见），并且 `sharp` 失败，请强制使用预构建二进制文件：
|
||||
|
||||
如果你看到 `sharp: Please add node-gyp to your dependencies`，要么安装构建工具（macOS：Xcode CLT + `npm install -g node-gyp`），要么使用上面的 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 变通方法来跳过原生构建。
|
||||
```bash
|
||||
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
|
||||
```
|
||||
|
||||
或使用 pnpm：
|
||||
如果你看到 `sharp: Please add node-gyp to your dependencies`，请安装构建工具链（macOS：Xcode CLT + `npm install -g node-gyp`），或者使用上面的环境变量。
|
||||
</Accordion>
|
||||
</Tab>
|
||||
<Tab title="pnpm">
|
||||
```bash
|
||||
pnpm add -g openclaw@latest
|
||||
pnpm approve-builds -g # 批准 openclaw、node-llama-cpp、sharp 等
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
```bash
|
||||
pnpm add -g openclaw@latest
|
||||
pnpm approve-builds -g # 批准 openclaw、node-llama-cpp、sharp 等
|
||||
pnpm add -g openclaw@latest # 重新运行以执行 postinstall 脚本
|
||||
```
|
||||
<Note>
|
||||
`pnpm` 要求对带有构建脚本的包进行显式批准。首次安装出现 “Ignored build scripts” 警告后，运行 `pnpm approve-builds -g` 并选择列出的包。
|
||||
</Note>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
pnpm 需要显式批准带有构建脚本的包。在首次安装显示"Ignored build scripts"警告后，运行 `pnpm approve-builds -g` 并选择列出的包，然后重新运行安装以执行 postinstall 脚本。
|
||||
想通过包管理器安装当前 GitHub `main` 分支最新版本？
|
||||
|
||||
然后：
|
||||
```bash
|
||||
npm install -g github:openclaw/openclaw#main
|
||||
```
|
||||
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
```bash
|
||||
pnpm add -g github:openclaw/openclaw#main
|
||||
```
|
||||
|
||||
### 3）从源代码（贡献者/开发）
|
||||
</Accordion>
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
cd openclaw
|
||||
pnpm install
|
||||
pnpm ui:build # 首次运行时自动安装 UI 依赖
|
||||
pnpm build
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
<Accordion title="从源码" icon="github">
|
||||
适用于贡献者或任何想从本地检出运行的人。
|
||||
|
||||
提示：如果你还没有全局安装，请通过 `pnpm openclaw ...` 运行仓库命令。
|
||||
<Steps>
|
||||
<Step title="克隆并构建">
|
||||
克隆 [OpenClaw 仓库](https://github.com/openclaw/openclaw) 并构建：
|
||||
|
||||
### 4）其他安装选项
|
||||
```bash
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
cd openclaw
|
||||
pnpm install
|
||||
pnpm ui:build
|
||||
pnpm build
|
||||
```
|
||||
</Step>
|
||||
<Step title="链接 CLI">
|
||||
让 `openclaw` 命令在全局可用：
|
||||
|
||||
- Docker：[Docker](/install/docker)
|
||||
- Nix：[Nix](/install/nix)
|
||||
- Ansible：[Ansible](/install/ansible)
|
||||
- Bun（仅 CLI）：[Bun](/install/bun)
|
||||
```bash
|
||||
pnpm link --global
|
||||
```
|
||||
|
||||
或者，你也可以跳过链接，直接在仓库内通过 `pnpm openclaw ...` 运行命令。
|
||||
</Step>
|
||||
<Step title="运行新手引导">
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
更深入的开发工作流请参阅 [Setup](/start/setup)。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 其他安装方法
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Docker" href="/install/docker" icon="container">
|
||||
容器化或无头部署。
|
||||
</Card>
|
||||
<Card title="Podman" href="/install/podman" icon="container">
|
||||
无 root 容器：先运行一次 `setup-podman.sh`，然后运行启动脚本。
|
||||
</Card>
|
||||
<Card title="Nix" href="/install/nix" icon="snowflake">
|
||||
通过 Nix 进行声明式安装。
|
||||
</Card>
|
||||
<Card title="Ansible" href="/install/ansible" icon="server">
|
||||
自动化批量配置。
|
||||
</Card>
|
||||
<Card title="Bun" href="/install/bun" icon="zap">
|
||||
通过 Bun 运行时进行仅 CLI 使用。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 安装后
|
||||
|
||||
- 运行新手引导：`openclaw onboard --install-daemon`
|
||||
- 快速检查：`openclaw doctor`
|
||||
- 检查 Gateway 网关健康状态：`openclaw status` + `openclaw health`
|
||||
- 打开仪表板：`openclaw dashboard`
|
||||
|
||||
## 安装方式：npm vs git（安装器）
|
||||
|
||||
安装器支持两种方式：
|
||||
|
||||
- `npm`（默认）：`npm install -g openclaw@latest`
|
||||
- `git`：从 GitHub 克隆/构建并从源代码 checkout 运行
|
||||
|
||||
### CLI 标志
|
||||
验证一切是否正常工作：
|
||||
|
||||
```bash
|
||||
# 显式 npm
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
|
||||
|
||||
# 从 GitHub 安装（源代码 checkout）
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
|
||||
openclaw doctor # 检查配置问题
|
||||
openclaw status # Gateway 网关状态
|
||||
openclaw dashboard # 打开浏览器 UI
|
||||
```
|
||||
|
||||
常用标志：
|
||||
如果你需要自定义运行时路径，请使用：
|
||||
|
||||
- `--install-method npm|git`
|
||||
- `--git-dir <path>`（默认：`~/openclaw`）
|
||||
- `--no-git-update`（使用现有 checkout 时跳过 `git pull`）
|
||||
- `--no-prompt`（禁用提示；CI/自动化中必需）
|
||||
- `--dry-run`（打印将要执行的操作；不做任何更改）
|
||||
- `--no-onboard`（跳过新手引导）
|
||||
- `OPENCLAW_HOME` 用于基于主目录的内部路径
|
||||
- `OPENCLAW_STATE_DIR` 用于可变状态位置
|
||||
- `OPENCLAW_CONFIG_PATH` 用于配置文件位置
|
||||
|
||||
### 环境变量
|
||||
有关优先级和完整细节，请参阅 [Environment vars](/help/environment)。
|
||||
|
||||
等效的环境变量（对自动化有用）：
|
||||
## 故障排除：找不到 `openclaw`
|
||||
|
||||
- `OPENCLAW_INSTALL_METHOD=git|npm`
|
||||
- `OPENCLAW_GIT_DIR=...`
|
||||
- `OPENCLAW_GIT_UPDATE=0|1`
|
||||
- `OPENCLAW_NO_PROMPT=1`
|
||||
- `OPENCLAW_DRY_RUN=1`
|
||||
- `OPENCLAW_NO_ONBOARD=1`
|
||||
- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1`（默认：`1`；避免 `sharp` 针对系统 libvips 构建）
|
||||
|
||||
## 故障排除：找不到 `openclaw`（PATH）
|
||||
|
||||
快速诊断：
|
||||
<Accordion title="PATH 诊断与修复">
|
||||
快速诊断：
|
||||
|
||||
```bash
|
||||
node -v
|
||||
@ -173,21 +207,29 @@ npm prefix -g
|
||||
echo "$PATH"
|
||||
```
|
||||
|
||||
如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不**在 `echo "$PATH"` 的输出中，你的 shell 无法找到全局 npm 二进制文件（包括 `openclaw`）。
|
||||
如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不在**你的 `$PATH` 中，那么你的 shell 就找不到全局 npm 二进制文件（包括 `openclaw`）。
|
||||
|
||||
修复：将其添加到你的 shell 启动文件（zsh：`~/.zshrc`，bash：`~/.bashrc`）：
|
||||
修复方法 —— 将其添加到你的 shell 启动文件（`~/.zshrc` 或 `~/.bashrc`）中：
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
export PATH="$(npm prefix -g)/bin:$PATH"
|
||||
```
|
||||
|
||||
在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH。
|
||||
在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH 中。
|
||||
|
||||
然后打开新终端（或在 zsh 中执行 `rehash` / 在 bash 中执行 `hash -r`）。
|
||||
然后打开一个新的终端（或者在 zsh 中运行 `rehash`，在 bash 中运行 `hash -r`）。
|
||||
</Accordion>
|
||||
|
||||
## 更新/卸载
|
||||
## 更新 / 卸载
|
||||
|
||||
- 更新：[更新](/install/updating)
|
||||
- 迁移到新机器：[迁移](/install/migrating)
|
||||
- 卸载：[卸载](/install/uninstall)
|
||||
<CardGroup cols={3}>
|
||||
<Card title="更新" href="/install/updating" icon="refresh-cw">
|
||||
让 OpenClaw 保持最新。
|
||||
</Card>
|
||||
<Card title="迁移" href="/install/migrating" icon="arrow-right">
|
||||
迁移到新机器。
|
||||
</Card>
|
||||
<Card title="卸载" href="/install/uninstall" icon="trash-2">
|
||||
完全移除 OpenClaw。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,128 +1,422 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想了解 `openclaw.ai/install.sh` 的工作机制
|
||||
- 你想自动化安装（CI / 无头环境）
|
||||
- 你想了解 `openclaw.ai/install.sh`
|
||||
- 你想自动化安装（CI / 无头）
|
||||
- 你想从 GitHub 检出安装
|
||||
summary: 安装器脚本的工作原理（install.sh + install-cli.sh）、参数和自动化
|
||||
summary: 安装脚本的工作原理（install.sh、install-cli.sh、install.ps1）、标志和自动化
|
||||
title: 安装器内部机制
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:07:55Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 9e0a19ecb5da0a395030e1ccf0d4bedf16b83946b3432c5399d448fe5d298391
|
||||
generated_at: "2026-03-16T06:24:11Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e389fa04140ecc98b7e83330d0d467165b23bd22e31807bbd36963c87394ddc4
|
||||
source_path: install/installer.md
|
||||
workflow: 14
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 安装器内部机制
|
||||
|
||||
OpenClaw 提供两个安装器脚本（托管在 `openclaw.ai`）：
|
||||
OpenClaw 提供三个安装脚本，由 `openclaw.ai` 提供。
|
||||
|
||||
- `https://openclaw.ai/install.sh` — "推荐"安装器（默认全局 npm 安装；也可从 GitHub 检出安装）
|
||||
- `https://openclaw.ai/install-cli.sh` — 无需 root 权限的 CLI 安装器（安装到带有独立 Node 的前缀目录）
|
||||
- `https://openclaw.ai/install.ps1` — Windows PowerShell 安装器（默认 npm；可选 git 安装）
|
||||
| 脚本 | 平台 | 功能 |
|
||||
| ---------------------------------- | --------------------- | ----------------------------------------------------------------------------- |
|
||||
| [`install.sh`](#installsh) | macOS / Linux / WSL | 如有需要则安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行新手引导。 |
|
||||
| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL | 将 Node + OpenClaw 安装到本地前缀（`~/.openclaw`）中。无需 root。 |
|
||||
| [`install.ps1`](#installps1) | Windows（PowerShell） | 如有需要则安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行新手引导。 |
|
||||
|
||||
查看当前参数/行为，运行：
|
||||
## 快速命令
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
|
||||
```
|
||||
<Tabs>
|
||||
<Tab title="install.sh">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
Windows (PowerShell) 帮助：
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help
|
||||
```
|
||||
|
||||
```powershell
|
||||
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -?
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="install-cli.sh">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
|
||||
```
|
||||
|
||||
如果安装器完成但在新终端中找不到 `openclaw`，通常是 Node/npm PATH 问题。参见：[安装](/install#nodejs--npm-path-sanity)。
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help
|
||||
```
|
||||
|
||||
## install.sh（推荐）
|
||||
</Tab>
|
||||
<Tab title="install.ps1">
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex
|
||||
```
|
||||
|
||||
功能概述：
|
||||
```powershell
|
||||
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
|
||||
```
|
||||
|
||||
- 检测操作系统（macOS / Linux / WSL）。
|
||||
- 确保 Node.js **22+**（macOS 通过 Homebrew；Linux 通过 NodeSource）。
|
||||
- 选择安装方式：
|
||||
- `npm`（默认）：`npm install -g openclaw@latest`
|
||||
- `git`：克隆/构建源码检出并安装包装脚本
|
||||
- 在 Linux 上：必要时将 npm 前缀切换到 `~/.npm-global`，以避免全局 npm 权限错误。
|
||||
- 如果是升级现有安装：运行 `openclaw doctor --non-interactive`（尽力执行）。
|
||||
- 对于 git 安装：安装/更新后运行 `openclaw doctor --non-interactive`（尽力执行）。
|
||||
- 通过默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 来缓解 `sharp` 原生安装问题（避免使用系统 libvips 编译）。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
如果你*希望* `sharp` 链接到全局安装的 libvips（或你正在调试），请设置：
|
||||
<Note>
|
||||
如果安装成功但在新终端中找不到 `openclaw`，请参见 [Node.js 故障排除](/install/node#troubleshooting)。
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
---
|
||||
|
||||
### 可发现性 / "git 安装"提示
|
||||
## install.sh
|
||||
|
||||
如果你在**已有的 OpenClaw 源码检出目录中**运行安装器（通过 `package.json` + `pnpm-workspace.yaml` 检测），它会提示：
|
||||
<Tip>
|
||||
推荐用于大多数 macOS/Linux/WSL 上的交互式安装。
|
||||
</Tip>
|
||||
|
||||
- 更新并使用此检出（`git`）
|
||||
- 或迁移到全局 npm 安装（`npm`）
|
||||
### 流程（install.sh）
|
||||
|
||||
在非交互式上下文中（无 TTY / `--no-prompt`），你必须传入 `--install-method git|npm`（或设置 `OPENCLAW_INSTALL_METHOD`），否则脚本将以退出码 `2` 退出。
|
||||
<Steps>
|
||||
<Step title="检测操作系统">
|
||||
支持 macOS 和 Linux（包括 WSL）。如果检测到 macOS，则会在缺少 Homebrew 时安装它。
|
||||
</Step>
|
||||
<Step title="默认确保使用 Node.js 24">
|
||||
检查 Node 版本，并在需要时安装 Node 24（macOS 上使用 Homebrew，Linux apt/dnf/yum 上使用 NodeSource 设置脚本）。为了兼容性，OpenClaw 仍支持 Node 22 LTS，目前为 `22.16+`。
|
||||
</Step>
|
||||
<Step title="确保安装 Git">
|
||||
如果缺少 Git，则安装它。
|
||||
</Step>
|
||||
<Step title="安装 OpenClaw">
|
||||
- `npm` 方法（默认）：全局 npm 安装
|
||||
- `git` 方法：克隆/更新仓库，使用 pnpm 安装依赖，构建，然后将包装器安装到 `~/.local/bin/openclaw`
|
||||
</Step>
|
||||
<Step title="安装后任务">
|
||||
- 在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力而为）
|
||||
- 在适当情况下尝试运行新手引导（有 TTY、未禁用新手引导，并且 bootstrap/配置检查通过）
|
||||
- 默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1`
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 为什么需要 Git
|
||||
### 源码检出检测
|
||||
|
||||
`--install-method git` 路径（克隆 / 拉取）需要 Git。
|
||||
如果在 OpenClaw 检出目录中运行（`package.json` + `pnpm-workspace.yaml`），脚本会提供：
|
||||
|
||||
对于 `npm` 安装，Git *通常*不是必需的，但某些环境仍然需要它（例如通过 git URL 获取软件包或依赖时）。安装器目前会确保 Git 存在，以避免在全新发行版上出现 `spawn git ENOENT` 错误。
|
||||
- 使用检出目录（`git`），或
|
||||
- 使用全局安装（`npm`）
|
||||
|
||||
### 为什么在全新 Linux 上 npm 会报 `EACCES`
|
||||
如果没有可用 TTY 且未设置安装方法，它将默认使用 `npm` 并发出警告。
|
||||
|
||||
在某些 Linux 设置中（尤其是通过系统包管理器或 NodeSource 安装 Node 后），npm 的全局前缀指向 root 拥有的位置。此时 `npm install -g ...` 会报 `EACCES` / `mkdir` 权限错误。
|
||||
对于无效的方法选择或无效的 `--install-method` 值，脚本会以退出码 `2` 退出。
|
||||
|
||||
`install.sh` 通过将前缀切换到以下位置来缓解此问题：
|
||||
### 示例（install.sh）
|
||||
|
||||
- `~/.npm-global`（并在存在时将其添加到 `~/.bashrc` / `~/.zshrc` 的 `PATH` 中）
|
||||
<Tabs>
|
||||
<Tab title="默认">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="跳过新手引导">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Git 安装">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="通过 npm 安装 GitHub main">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --version main
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="试运行">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## install-cli.sh（无需 root 权限的 CLI 安装器）
|
||||
<AccordionGroup>
|
||||
<Accordion title="标志参考">
|
||||
|
||||
此脚本将 `openclaw` 安装到前缀目录（默认：`~/.openclaw`），同时在该前缀下安装专用的 Node 运行时，因此可以在不想改动系统 Node/npm 的机器上使用。
|
||||
| 标志 | 说明 |
|
||||
| ------------------------------------- | ------------------------------------------------- |
|
||||
| `--install-method npm\|git` | 选择安装方法（默认：`npm`）。别名：`--method` |
|
||||
| `--npm` | npm 方法快捷方式 |
|
||||
| `--git` | git 方法快捷方式。别名：`--github` |
|
||||
| `--version <version\|dist-tag\|spec>` | npm 版本、dist-tag 或包规范（默认：`latest`） |
|
||||
| `--beta` | 如有可用则使用 beta dist-tag，否则回退到 `latest` |
|
||||
| `--git-dir <path>` | 检出目录（默认：`~/openclaw`）。别名：`--dir` |
|
||||
| `--no-git-update` | 对现有检出跳过 `git pull` |
|
||||
| `--no-prompt` | 禁用提示 |
|
||||
| `--no-onboard` | 跳过新手引导 |
|
||||
| `--onboard` | 启用新手引导 |
|
||||
| `--dry-run` | 打印操作但不应用更改 |
|
||||
| `--verbose` | 启用调试输出（`set -x`、npm notice 级别日志） |
|
||||
| `--help` | 显示用法（`-h`） |
|
||||
|
||||
帮助：
|
||||
</Accordion>
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help
|
||||
```
|
||||
<Accordion title="环境变量参考">
|
||||
|
||||
## install.ps1（Windows PowerShell）
|
||||
| 变量 | 说明 |
|
||||
| ------------------------------------------------------- | ------------------------------------ |
|
||||
| `OPENCLAW_INSTALL_METHOD=git\|npm` | 安装方法 |
|
||||
| `OPENCLAW_VERSION=latest\|next\|main\|<semver>\|<spec>` | npm 版本、dist-tag 或包规范 |
|
||||
| `OPENCLAW_BETA=0\|1` | 如有可用则使用 beta |
|
||||
| `OPENCLAW_GIT_DIR=<path>` | 检出目录 |
|
||||
| `OPENCLAW_GIT_UPDATE=0\|1` | 切换 git 更新 |
|
||||
| `OPENCLAW_NO_PROMPT=1` | 禁用提示 |
|
||||
| `OPENCLAW_NO_ONBOARD=1` | 跳过新手引导 |
|
||||
| `OPENCLAW_DRY_RUN=1` | 试运行模式 |
|
||||
| `OPENCLAW_VERBOSE=1` | 调试模式 |
|
||||
| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm 日志级别 |
|
||||
| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | 控制 sharp/libvips 行为（默认：`1`） |
|
||||
|
||||
功能概述：
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
- 确保 Node.js **22+**（winget/Chocolatey/Scoop 或手动安装）。
|
||||
- 选择安装方式：
|
||||
- `npm`（默认）：`npm install -g openclaw@latest`
|
||||
- `git`：克隆/构建源码检出并安装包装脚本
|
||||
- 在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力执行）。
|
||||
---
|
||||
|
||||
示例：
|
||||
## install-cli.sh
|
||||
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex
|
||||
```
|
||||
<Info>
|
||||
适用于你希望所有内容都放在本地前缀（默认 `~/.openclaw`）下，并且不依赖系统 Node 的环境。
|
||||
</Info>
|
||||
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git
|
||||
```
|
||||
### 流程（install-cli.sh）
|
||||
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw"
|
||||
```
|
||||
<Steps>
|
||||
<Step title="安装本地 Node 运行时">
|
||||
将固定的受支持 Node tarball（当前默认 `22.22.0`）下载到 `<prefix>/tools/node-v<version>`，并验证 SHA-256。
|
||||
</Step>
|
||||
<Step title="确保安装 Git">
|
||||
如果缺少 Git，则尝试在 Linux 上通过 apt/dnf/yum 安装，或在 macOS 上通过 Homebrew 安装。
|
||||
</Step>
|
||||
<Step title="在前缀下安装 OpenClaw">
|
||||
使用 `--prefix <prefix>` 通过 npm 安装，然后将包装器写入 `<prefix>/bin/openclaw`。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
环境变量：
|
||||
### 示例（install-cli.sh）
|
||||
|
||||
- `OPENCLAW_INSTALL_METHOD=git|npm`
|
||||
- `OPENCLAW_GIT_DIR=...`
|
||||
<Tabs>
|
||||
<Tab title="默认">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="自定义前缀 + 版本">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="自动化 JSON 输出">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="运行新手引导">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Git 要求：
|
||||
<AccordionGroup>
|
||||
<Accordion title="标志参考">
|
||||
|
||||
如果你选择 `-InstallMethod git` 但未安装 Git，安装器会打印 Git for Windows 的链接（`https://git-scm.com/download/win`）并退出。
|
||||
| 标志 | 说明 |
|
||||
| ---------------------- | ---------------------------------------------------------------------- |
|
||||
| `--prefix <path>` | 安装前缀（默认：`~/.openclaw`） |
|
||||
| `--version <ver>` | OpenClaw 版本或 dist-tag（默认：`latest`） |
|
||||
| `--node-version <ver>` | Node 版本（默认：`22.22.0`） |
|
||||
| `--json` | 输出 NDJSON 事件 |
|
||||
| `--onboard` | 安装后运行 `openclaw onboard` |
|
||||
| `--no-onboard` | 跳过新手引导（默认） |
|
||||
| `--set-npm-prefix` | 在 Linux 上，如果当前前缀不可写，则强制将 npm 前缀设为 `~/.npm-global` |
|
||||
| `--help` | 显示用法（`-h`） |
|
||||
|
||||
常见 Windows 问题：
|
||||
</Accordion>
|
||||
|
||||
- **npm error spawn git / ENOENT**：安装 Git for Windows 并重新打开 PowerShell，然后重新运行安装器。
|
||||
- **"openclaw" 不是可识别的命令**：你的 npm 全局 bin 文件夹不在 PATH 中。大多数系统使用 `%AppData%\\npm`。你也可以运行 `npm config get prefix` 并将 `\\bin` 添加到 PATH，然后重新打开 PowerShell。
|
||||
<Accordion title="环境变量参考">
|
||||
|
||||
| 变量 | 说明 |
|
||||
| ------------------------------------------- | ------------------------------------------------------ |
|
||||
| `OPENCLAW_PREFIX=<path>` | 安装前缀 |
|
||||
| `OPENCLAW_VERSION=<ver>` | OpenClaw 版本或 dist-tag |
|
||||
| `OPENCLAW_NODE_VERSION=<ver>` | Node 版本 |
|
||||
| `OPENCLAW_NO_ONBOARD=1` | 跳过新手引导 |
|
||||
| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm 日志级别 |
|
||||
| `OPENCLAW_GIT_DIR=<path>` | 旧版清理查找路径（用于删除旧的 `Peekaboo` 子模块检出） |
|
||||
| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | 控制 sharp/libvips 行为（默认：`1`） |
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
---
|
||||
|
||||
## install.ps1
|
||||
|
||||
### 流程（install.ps1）
|
||||
|
||||
<Steps>
|
||||
<Step title="确保 PowerShell + Windows 环境">
|
||||
需要 PowerShell 5+。
|
||||
</Step>
|
||||
<Step title="默认确保使用 Node.js 24">
|
||||
如果缺少，则依次尝试通过 winget、Chocolatey、Scoop 安装。为了兼容性，Node 22 LTS（当前为 `22.16+`）仍然受支持。
|
||||
</Step>
|
||||
<Step title="安装 OpenClaw">
|
||||
- `npm` 方法（默认）：使用所选 `-Tag` 进行全局 npm 安装
|
||||
- `git` 方法：克隆/更新仓库，使用 pnpm 安装/构建，并将包装器安装到 `%USERPROFILE%\.local\bin\openclaw.cmd`
|
||||
</Step>
|
||||
<Step title="安装后任务">
|
||||
在可能情况下将所需 bin 目录添加到用户 PATH，然后在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力而为）。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 示例（install.ps1）
|
||||
|
||||
<Tabs>
|
||||
<Tab title="默认">
|
||||
```powershell
|
||||
iwr -useb https://openclaw.ai/install.ps1 | iex
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Git 安装">
|
||||
```powershell
|
||||
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="通过 npm 安装 GitHub main">
|
||||
```powershell
|
||||
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag main
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="自定义 git 目录">
|
||||
```powershell
|
||||
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="试运行">
|
||||
```powershell
|
||||
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="调试跟踪">
|
||||
```powershell
|
||||
# install.ps1 目前还没有专门的 -Verbose 标志。
|
||||
Set-PSDebug -Trace 1
|
||||
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
|
||||
Set-PSDebug -Trace 0
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="标志参考">
|
||||
|
||||
| 标志 | 说明 |
|
||||
| --------------------------- | -------------------------------------------- |
|
||||
| `-InstallMethod npm\|git` | 安装方法（默认：`npm`） |
|
||||
| `-Tag <tag\|version\|spec>` | npm dist-tag、版本或包规范（默认：`latest`） |
|
||||
| `-GitDir <path>` | 检出目录（默认：`%USERPROFILE%\openclaw`） |
|
||||
| `-NoOnboard` | 跳过新手引导 |
|
||||
| `-NoGitUpdate` | 跳过 `git pull` |
|
||||
| `-DryRun` | 仅打印操作 |
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="环境变量参考">
|
||||
|
||||
| 变量 | 说明 |
|
||||
| ---------------------------------- | ------------- |
|
||||
| `OPENCLAW_INSTALL_METHOD=git\|npm` | 安装方法 |
|
||||
| `OPENCLAW_GIT_DIR=<path>` | 检出目录 |
|
||||
| `OPENCLAW_NO_ONBOARD=1` | 跳过新手引导 |
|
||||
| `OPENCLAW_GIT_UPDATE=0` | 禁用 git pull |
|
||||
| `OPENCLAW_DRY_RUN=1` | 试运行模式 |
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
如果使用 `-InstallMethod git` 且缺少 Git，脚本会退出并打印 Git for Windows 链接。
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## CI 和自动化
|
||||
|
||||
使用非交互式标志/环境变量以实现可预测的运行。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="install.sh（非交互式 npm）">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="install.sh（非交互式 git）">
|
||||
```bash
|
||||
OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="install-cli.sh（JSON）">
|
||||
```bash
|
||||
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="install.ps1（跳过新手引导）">
|
||||
```powershell
|
||||
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="为什么需要 Git？">
|
||||
`git` 安装方法需要 Git。对于 `npm` 安装，仍然会检查/安装 Git，以避免当依赖使用 git URL 时出现 `spawn git ENOENT` 失败。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="为什么 npm 在 Linux 上会遇到 EACCES？">
|
||||
某些 Linux 设置会将 npm 全局前缀指向 root 拥有的路径。`install.sh` 可以将前缀切换到 `~/.npm-global`，并将 PATH 导出追加到 shell rc 文件中（如果这些文件存在）。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="sharp/libvips 问题">
|
||||
这些脚本默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1`，以避免 sharp 针对系统 libvips 进行构建。若要覆盖：
|
||||
|
||||
```bash
|
||||
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='Windows：“npm error spawn git / ENOENT”'>
|
||||
安装 Git for Windows，重新打开 PowerShell，然后重新运行安装器。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title='Windows：“openclaw is not recognized”'>
|
||||
运行 `npm config get prefix`，并将该目录添加到你的用户 PATH（Windows 上不需要 `\bin` 后缀），然后重新打开 PowerShell。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Windows：如何获取详细安装器输出">
|
||||
`install.ps1` 目前没有提供 `-Verbose` 开关。
|
||||
对于脚本级诊断，请使用 PowerShell 跟踪：
|
||||
|
||||
```powershell
|
||||
Set-PSDebug -Trace 1
|
||||
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
|
||||
Set-PSDebug -Trace 0
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="安装后找不到 openclaw">
|
||||
通常是 PATH 问题。请参见 [Node.js 故障排除](/install/node#troubleshooting)。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -1,75 +1,75 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想让 OpenClaw 与你的主 macOS 环境隔离
|
||||
- 你想在沙箱中集成 iMessage（BlueBubbles）
|
||||
- 你想要一个可重置、可克隆的 macOS 环境
|
||||
- 你想比较本地与托管 macOS VM 选项
|
||||
summary: 在沙箱隔离的 macOS VM（本地或托管）中运行 OpenClaw，当你需要隔离或 iMessage 时
|
||||
title: macOS 虚拟机
|
||||
- 你希望 OpenClaw 与你的主 macOS 环境隔离
|
||||
- 你希望在沙箱中集成 iMessage（BlueBubbles）
|
||||
- 你希望拥有一个可重置且可克隆的 macOS 环境
|
||||
- 你希望比较本地与托管 macOS VM 选项
|
||||
summary: 在沙箱化的 macOS VM（本地或托管）中运行 OpenClaw，适用于你需要隔离或 iMessage 的场景
|
||||
title: macOS VM
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:53:09Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
generated_at: "2026-03-16T06:23:59Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4d1c85a5e4945f9f0796038cd5960edecb71ec4dffb6f9686be50adb75180716
|
||||
source_path: platforms/macos-vm.md
|
||||
source_path: install/macos-vm.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 在 macOS 虚拟机上运行 OpenClaw（沙箱隔离）
|
||||
# 在 macOS VM 上运行 OpenClaw（沙箱隔离）
|
||||
|
||||
## 推荐默认方案（大多数用户）
|
||||
## 推荐默认方案（适用于大多数用户）
|
||||
|
||||
- **小型 Linux VPS** 用于永久在线的 Gateway 网关，成本低。参见 [VPS 托管](/vps)。
|
||||
- **专用硬件**（Mac mini 或 Linux 机器）如果你想要完全控制和**住宅 IP** 用于浏览器自动化。许多网站会屏蔽数据中心 IP，所以本地浏览通常效果更好。
|
||||
- **混合方案：** 将 Gateway 网关保持在廉价 VPS 上，当你需要浏览器/UI 自动化时，将你的 Mac 作为**节点**连接。参见[节点](/nodes)和 [Gateway 网关远程](/gateway/remote)。
|
||||
- **小型 Linux VPS**：适合始终在线的 Gateway 网关，且成本较低。参见 [VPS hosting](/vps)。
|
||||
- **专用硬件**（Mac mini 或 Linux 主机）：如果你希望完全控制，并为浏览器自动化获得一个**住宅 IP**。许多网站会屏蔽数据中心 IP，因此本地浏览通常效果更好。
|
||||
- **混合方案：** 将 Gateway 网关放在便宜的 VPS 上，当你需要浏览器/UI 自动化时，再将你的 Mac 作为一个 **node** 连接进来。参见 [Nodes](/nodes) 和 [Gateway remote](/gateway/remote)。
|
||||
|
||||
当你特别需要 macOS 独有功能（iMessage/BlueBubbles）或想要与日常 Mac 严格隔离时，使用 macOS VM。
|
||||
当你明确需要 macOS 独有能力（iMessage/BlueBubbles），或希望与你的日常 Mac 严格隔离时，再使用 macOS VM。
|
||||
|
||||
## macOS VM 选项
|
||||
|
||||
### 在你的 Apple Silicon Mac 上运行本地 VM（Lume）
|
||||
|
||||
使用 [Lume](https://cua.ai/docs/lume) 在你现有的 Apple Silicon Mac 上的沙箱 macOS VM 中运行 OpenClaw。
|
||||
使用 [Lume](https://cua.ai/docs/lume) 在你现有的 Apple Silicon Mac 上的沙箱化 macOS VM 中运行 OpenClaw。
|
||||
|
||||
这为你提供：
|
||||
这样你将获得：
|
||||
|
||||
- 隔离的完整 macOS 环境（你的主机保持干净）
|
||||
- 通过 BlueBubbles 支持 iMessage（在 Linux/Windows 上不可能）
|
||||
- 通过克隆 VM 即时重置
|
||||
- 完全隔离的 macOS 环境（你的宿主机保持干净）
|
||||
- 通过 BlueBubbles 获得 iMessage 支持（在 Linux/Windows 上无法实现）
|
||||
- 通过克隆 VM 实现即时重置
|
||||
- 无需额外硬件或云成本
|
||||
|
||||
### 托管 Mac 提供商（云）
|
||||
### 托管 Mac 提供商（云端）
|
||||
|
||||
如果你想要云端的 macOS，托管 Mac 提供商也可以：
|
||||
如果你希望在云中使用 macOS，托管 Mac 提供商同样可行：
|
||||
|
||||
- [MacStadium](https://www.macstadium.com/)（托管 Mac）
|
||||
- 其他托管 Mac 供应商也可以；按照他们的 VM + SSH 文档操作
|
||||
- 其他托管 Mac 供应商也可以；请遵循它们的 VM + SSH 文档
|
||||
|
||||
一旦你有了 macOS VM 的 SSH 访问权限，继续下面的步骤 6。
|
||||
一旦你获得了对 macOS VM 的 SSH 访问权限，就继续执行下面的第 6 步。
|
||||
|
||||
---
|
||||
|
||||
## 快速路径（Lume，有经验的用户）
|
||||
## 快速路径（Lume，适合有经验的用户）
|
||||
|
||||
1. 安装 Lume
|
||||
2. `lume create openclaw --os macos --ipsw latest`
|
||||
3. 完成设置助手，启用远程登录（SSH）
|
||||
3. 完成设置助理，启用远程登录（SSH）
|
||||
4. `lume run openclaw --no-display`
|
||||
5. SSH 进入，安装 OpenClaw，配置渠道
|
||||
5. SSH 登录，安装 OpenClaw，配置渠道
|
||||
6. 完成
|
||||
|
||||
---
|
||||
|
||||
## 你需要什么（Lume）
|
||||
## 你需要准备的内容（Lume）
|
||||
|
||||
- Apple Silicon Mac（M1/M2/M3/M4）
|
||||
- 主机上安装 macOS Sequoia 或更高版本
|
||||
- 每个 VM 约 60 GB 可用磁盘空间
|
||||
- 宿主机运行 macOS Sequoia 或更高版本
|
||||
- 每个 VM 大约 60 GB 可用磁盘空间
|
||||
- 约 20 分钟
|
||||
|
||||
---
|
||||
|
||||
## 1) 安装 Lume
|
||||
## 1）安装 Lume
|
||||
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
|
||||
@ -87,11 +87,11 @@ echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
|
||||
lume --version
|
||||
```
|
||||
|
||||
文档：[Lume 安装](https://cua.ai/docs/lume/guide/getting-started/installation)
|
||||
文档： [Lume Installation](https://cua.ai/docs/lume/guide/getting-started/installation)
|
||||
|
||||
---
|
||||
|
||||
## 2) 创建 macOS VM
|
||||
## 2）创建 macOS VM
|
||||
|
||||
```bash
|
||||
lume create openclaw --os macos --ipsw latest
|
||||
@ -99,47 +99,47 @@ lume create openclaw --os macos --ipsw latest
|
||||
|
||||
这会下载 macOS 并创建 VM。VNC 窗口会自动打开。
|
||||
|
||||
注意：下载可能需要一段时间，取决于你的网络连接。
|
||||
注意：下载可能需要一些时间，具体取决于你的网络连接。
|
||||
|
||||
---
|
||||
|
||||
## 3) 完成设置助手
|
||||
## 3）完成设置助理
|
||||
|
||||
在 VNC 窗口中：
|
||||
|
||||
1. 选择语言和地区
|
||||
2. 跳过 Apple ID（或者如果你以后想要 iMessage 就登录）
|
||||
3. 创建用户账户（记住用户名和密码）
|
||||
2. 跳过 Apple ID（或者如果你之后想使用 iMessage，也可以登录）
|
||||
3. 创建一个用户账号（记住用户名和密码）
|
||||
4. 跳过所有可选功能
|
||||
|
||||
设置完成后，启用 SSH：
|
||||
|
||||
1. 打开系统设置 → 通用 → 共享
|
||||
2. 启用"远程登录"
|
||||
1. 打开“系统设置”→“通用”→“共享”
|
||||
2. 启用“远程登录”
|
||||
|
||||
---
|
||||
|
||||
## 4) 获取 VM 的 IP 地址
|
||||
## 4）获取 VM 的 IP 地址
|
||||
|
||||
```bash
|
||||
lume get openclaw
|
||||
```
|
||||
|
||||
查找 IP 地址（通常是 `192.168.64.x`）。
|
||||
查找 IP 地址（通常为 `192.168.64.x`）。
|
||||
|
||||
---
|
||||
|
||||
## 5) SSH 进入 VM
|
||||
## 5）通过 SSH 连接到 VM
|
||||
|
||||
```bash
|
||||
ssh youruser@192.168.64.X
|
||||
```
|
||||
|
||||
将 `youruser` 替换为你创建的账户，IP 替换为你 VM 的 IP。
|
||||
将 `youruser` 替换为你创建的账号，并将 IP 替换为你的 VM IP。
|
||||
|
||||
---
|
||||
|
||||
## 6) 安装 OpenClaw
|
||||
## 6）安装 OpenClaw
|
||||
|
||||
在 VM 内：
|
||||
|
||||
@ -152,7 +152,7 @@ openclaw onboard --install-daemon
|
||||
|
||||
---
|
||||
|
||||
## 7) 配置渠道
|
||||
## 7）配置渠道
|
||||
|
||||
编辑配置文件：
|
||||
|
||||
@ -176,7 +176,7 @@ nano ~/.openclaw/openclaw.json
|
||||
}
|
||||
```
|
||||
|
||||
然后登录 WhatsApp（扫描二维码）：
|
||||
然后登录 WhatsApp（扫描 QR 码）：
|
||||
|
||||
```bash
|
||||
openclaw channels login
|
||||
@ -184,16 +184,16 @@ openclaw channels login
|
||||
|
||||
---
|
||||
|
||||
## 8) 无头运行 VM
|
||||
## 8）以无界面方式运行 VM
|
||||
|
||||
停止 VM 并在无显示器模式下重启：
|
||||
停止 VM，然后在无显示模式下重启：
|
||||
|
||||
```bash
|
||||
lume stop openclaw
|
||||
lume run openclaw --no-display
|
||||
```
|
||||
|
||||
VM 在后台运行。OpenClaw 的守护进程保持 Gateway 网关运行。
|
||||
VM 会在后台运行。OpenClaw 的守护进程会保持 Gateway 网关持续运行。
|
||||
|
||||
检查状态：
|
||||
|
||||
@ -203,18 +203,18 @@ ssh youruser@192.168.64.X "openclaw status"
|
||||
|
||||
---
|
||||
|
||||
## 额外：iMessage 集成
|
||||
## 加分项：iMessage 集成
|
||||
|
||||
这是在 macOS 上运行的杀手级功能。使用 [BlueBubbles](https://bluebubbles.app) 将 iMessage 添加到 OpenClaw。
|
||||
这是在 macOS 上运行的杀手级特性。使用 [BlueBubbles](https://bluebubbles.app) 将 iMessage 添加到 OpenClaw。
|
||||
|
||||
在 VM 内：
|
||||
|
||||
1. 从 bluebubbles.app 下载 BlueBubbles
|
||||
2. 用你的 Apple ID 登录
|
||||
3. 启用 Web API 并设置密码
|
||||
4. 将 BlueBubbles webhooks 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）
|
||||
2. 使用你的 Apple ID 登录
|
||||
3. 启用 Web API 并设置一个密码
|
||||
4. 将 BlueBubbles webhook 指向你的 gateway（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）
|
||||
|
||||
添加到你的 OpenClaw 配置：
|
||||
添加到你的 OpenClaw 配置中：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -228,15 +228,15 @@ ssh youruser@192.168.64.X "openclaw status"
|
||||
}
|
||||
```
|
||||
|
||||
重启 Gateway 网关。现在你的智能体可以发送和接收 iMessage 了。
|
||||
重启 Gateway 网关。现在你的智能体就可以发送和接收 iMessage 了。
|
||||
|
||||
完整设置详情：[BlueBubbles 渠道](/channels/bluebubbles)
|
||||
完整设置细节： [BlueBubbles channel](/channels/bluebubbles)
|
||||
|
||||
---
|
||||
|
||||
## 保存黄金镜像
|
||||
|
||||
在进一步自定义之前，快照你的干净状态：
|
||||
在进一步自定义之前，为你的干净状态创建快照：
|
||||
|
||||
```bash
|
||||
lume stop openclaw
|
||||
@ -253,36 +253,36 @@ lume run openclaw --no-display
|
||||
|
||||
---
|
||||
|
||||
## 24/7 运行
|
||||
## 7×24 运行
|
||||
|
||||
通过以下方式保持 VM 运行：
|
||||
通过以下方式保持 VM 持续运行：
|
||||
|
||||
- 保持你的 Mac 插电
|
||||
- 在系统设置 → 节能中禁用睡眠
|
||||
- 如需要使用 `caffeinate`
|
||||
- 让你的 Mac 保持通电
|
||||
- 在“系统设置”→“节能”中禁用睡眠
|
||||
- 如有需要，使用 `caffeinate`
|
||||
|
||||
对于真正的永久在线，考虑专用 Mac mini 或小型 VPS。参见 [VPS 托管](/vps)。
|
||||
如果你需要真正始终在线，请考虑使用专用 Mac mini 或小型 VPS。参见 [VPS hosting](/vps)。
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
| 问题 | 解决方案 |
|
||||
| ----------------------- | ---------------------------------------------------------------- |
|
||||
| 无法 SSH 进入 VM | 检查 VM 的系统设置中是否启用了"远程登录" |
|
||||
| VM IP 未显示 | 等待 VM 完全启动，再次运行 `lume get openclaw` |
|
||||
| 找不到 Lume 命令 | 将 `~/.local/bin` 添加到你的 PATH |
|
||||
| WhatsApp 二维码扫描失败 | 确保运行 `openclaw channels login` 时你是登录到 VM（而不是主机） |
|
||||
| 问题 | 解决方案 |
|
||||
| ----------------------- | ----------------------------------------------------------------- |
|
||||
| 无法通过 SSH 连接到 VM | 检查 VM 的“系统设置”中是否已启用“远程登录” |
|
||||
| 未显示 VM IP | 等待 VM 完全启动后，再次运行 `lume get openclaw` |
|
||||
| 找不到 `lume` 命令 | 将 `~/.local/bin` 添加到你的 PATH |
|
||||
| 无法扫描 WhatsApp QR 码 | 运行 `openclaw channels login` 时，确保你登录的是 VM 而不是宿主机 |
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [VPS 托管](/vps)
|
||||
- [节点](/nodes)
|
||||
- [Gateway 网关远程](/gateway/remote)
|
||||
- [BlueBubbles 渠道](/channels/bluebubbles)
|
||||
- [Lume 快速入门](https://cua.ai/docs/lume/guide/getting-started/quickstart)
|
||||
- [Lume CLI 参考](https://cua.ai/docs/lume/reference/cli-reference)
|
||||
- [无人值守 VM 设置](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup)（高级）
|
||||
- [Docker 沙箱隔离](/install/docker)（替代隔离方案）
|
||||
- [VPS hosting](/vps)
|
||||
- [Nodes](/nodes)
|
||||
- [Gateway remote](/gateway/remote)
|
||||
- [BlueBubbles channel](/channels/bluebubbles)
|
||||
- [Lume Quickstart](https://cua.ai/docs/lume/guide/getting-started/quickstart)
|
||||
- [Lume CLI Reference](https://cua.ai/docs/lume/reference/cli-reference)
|
||||
- [Unattended VM Setup](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup)（高级）
|
||||
- [Docker Sandboxing](/install/docker)（另一种隔离方案）
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 在 DigitalOcean 上设置 OpenClaw
|
||||
- 寻找便宜的 VPS 托管来运行 OpenClaw
|
||||
- 寻找适合 OpenClaw 的低价 VPS 托管
|
||||
summary: 在 DigitalOcean 上运行 OpenClaw（简单的付费 VPS 选项）
|
||||
title: DigitalOcean
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:51:55Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: d60559b8751da37413e5364e83c88254b476b2283386a0b07b2ca6b4e16157fc
|
||||
generated_at: "2026-03-16T06:24:23Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f7cbbee2bdc2df08d2c255ee55fdf822c27924b41c4f4717cafb7e6e015d0966
|
||||
source_path: platforms/digitalocean.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,137 +17,141 @@ x-i18n:
|
||||
|
||||
## 目标
|
||||
|
||||
以 **$6/月**（或使用预留定价 $4/月）在 DigitalOcean 上运行持久的 OpenClaw Gateway 网关。
|
||||
在 DigitalOcean 上以 **每月 6 美元**（或预留定价时每月 4 美元）运行一个持久化的 OpenClaw Gateway 网关。
|
||||
|
||||
如果你想要 $0/月的选项且不介意 ARM + 特定提供商的设置，请参阅 [Oracle Cloud 指南](/platforms/oracle)。
|
||||
如果你想要每月 0 美元的方案，并且不介意 ARM + 提供商特定设置，请参阅 [Oracle Cloud 指南](/platforms/oracle)。
|
||||
|
||||
## 成本比较（2026）
|
||||
## 成本对比（2026）
|
||||
|
||||
| 提供商 | 方案 | 配置 | 价格/月 | 备注 |
|
||||
| ------------ | --------------- | --------------------- | ----------- | ------------------------ |
|
||||
| Oracle Cloud | Always Free ARM | 最高 4 OCPU、24GB RAM | $0 | ARM，容量有限 / 注册有坑 |
|
||||
| Hetzner | CX22 | 2 vCPU、4GB RAM | €3.79 (~$4) | 最便宜的付费选项 |
|
||||
| DigitalOcean | Basic | 1 vCPU、1GB RAM | $6 | 界面简单，文档完善 |
|
||||
| Vultr | Cloud Compute | 1 vCPU、1GB RAM | $6 | 多地区可选 |
|
||||
| Linode | Nanode | 1 vCPU、1GB RAM | $5 | 现为 Akamai 旗下 |
|
||||
| 提供商 | 套餐 | 规格 | 每月价格 | 说明 |
|
||||
| ------------ | --------------- | ---------------------- | -------------- | -------------------------------- |
|
||||
| Oracle Cloud | Always Free ARM | 最多 4 OCPU，24 GB RAM | $0 | ARM，容量有限 / 注册流程有些麻烦 |
|
||||
| Hetzner | CX22 | 2 vCPU，4 GB RAM | €3.79（约 $4） | 最便宜的付费选项 |
|
||||
| DigitalOcean | Basic | 1 vCPU，1 GB RAM | $6 | UI 简单，文档完善 |
|
||||
| Vultr | Cloud Compute | 1 vCPU，1 GB RAM | $6 | 机房位置多 |
|
||||
| Linode | Nanode | 1 vCPU，1 GB RAM | $5 | 现已并入 Akamai |
|
||||
|
||||
**选择提供商：**
|
||||
**如何选择提供商：**
|
||||
|
||||
- DigitalOcean：最简单的用户体验 + 可预测的设置（本指南）
|
||||
- Hetzner：性价比高（参见 [Hetzner 指南](/install/hetzner)）
|
||||
- Oracle Cloud：可以 $0/月，但更麻烦且仅限 ARM（参见 [Oracle 指南](/platforms/oracle)）
|
||||
- DigitalOcean：最简单的 UX + 可预测的设置（本指南）
|
||||
- Hetzner：性价比不错（见 [Hetzner guide](/install/hetzner)）
|
||||
- Oracle Cloud：可能做到每月 0 美元，但更挑环境且仅支持 ARM（见 [Oracle guide](/platforms/oracle)）
|
||||
|
||||
---
|
||||
|
||||
## 前提条件
|
||||
|
||||
- DigitalOcean 账户（[注册可获 $200 免费额度](https://m.do.co/c/signup)）
|
||||
- DigitalOcean 账号（[注册可获 200 美元免费额度](https://m.do.co/c/signup)）
|
||||
- SSH 密钥对（或愿意使用密码认证）
|
||||
- 约 20 分钟
|
||||
|
||||
## 1) 创建 Droplet
|
||||
## 1）创建 Droplet
|
||||
|
||||
<Warning>
|
||||
请使用干净的基础镜像（Ubuntu 24.04 LTS）。除非你已经检查过其启动脚本和防火墙默认设置，否则请避免使用第三方 Marketplace 一键镜像。
|
||||
</Warning>
|
||||
|
||||
1. 登录 [DigitalOcean](https://cloud.digitalocean.com/)
|
||||
2. 点击 **Create → Droplets**
|
||||
3. 选择：
|
||||
- **Region：** 离你（或你的用户）最近的地区
|
||||
- **Region：** 离你（或你的用户）最近
|
||||
- **Image：** Ubuntu 24.04 LTS
|
||||
- **Size：** Basic → Regular → **$6/mo**（1 vCPU、1GB RAM、25GB SSD）
|
||||
- **Authentication：** SSH 密钥（推荐）或密码
|
||||
- **Size：** Basic → Regular → **$6/mo**（1 vCPU、1 GB RAM、25 GB SSD）
|
||||
- **Authentication：** SSH key（推荐）或密码
|
||||
4. 点击 **Create Droplet**
|
||||
5. 记下 IP 地址
|
||||
|
||||
## 2) 通过 SSH 连接
|
||||
## 2）通过 SSH 连接
|
||||
|
||||
```bash
|
||||
ssh root@YOUR_DROPLET_IP
|
||||
```
|
||||
|
||||
## 3) 安装 OpenClaw
|
||||
## 3）安装 OpenClaw
|
||||
|
||||
```bash
|
||||
# Update system
|
||||
# 更新系统
|
||||
apt update && apt upgrade -y
|
||||
|
||||
# Install Node.js 22
|
||||
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
|
||||
# 安装 Node.js 24
|
||||
curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
|
||||
apt install -y nodejs
|
||||
|
||||
# Install OpenClaw
|
||||
# 安装 OpenClaw
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
|
||||
# Verify
|
||||
# 验证
|
||||
openclaw --version
|
||||
```
|
||||
|
||||
## 4) 运行新手引导
|
||||
## 4）运行新手引导
|
||||
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
向导将引导你完成：
|
||||
向导会带你完成以下设置：
|
||||
|
||||
- 模型认证（API 密钥或 OAuth）
|
||||
- 模型认证（API key 或 OAuth）
|
||||
- 渠道设置（Telegram、WhatsApp、Discord 等）
|
||||
- Gateway 网关令牌（自动生成）
|
||||
- Gateway 网关 token（自动生成）
|
||||
- 守护进程安装（systemd）
|
||||
|
||||
## 5) 验证 Gateway 网关
|
||||
## 5）验证 Gateway 网关
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
# 检查状态
|
||||
openclaw status
|
||||
|
||||
# Check service
|
||||
# 检查服务
|
||||
systemctl --user status openclaw-gateway.service
|
||||
|
||||
# View logs
|
||||
# 查看日志
|
||||
journalctl --user -u openclaw-gateway.service -f
|
||||
```
|
||||
|
||||
## 6) 访问控制面板
|
||||
## 6）访问 Dashboard
|
||||
|
||||
Gateway 网关默认绑定到 loopback。要访问控制界面：
|
||||
Gateway 网关默认绑定到 loopback。要访问 Control UI：
|
||||
|
||||
**选项 A：SSH 隧道（推荐）**
|
||||
|
||||
```bash
|
||||
# From your local machine
|
||||
# 在你的本地机器上
|
||||
ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP
|
||||
|
||||
# Then open: http://localhost:18789
|
||||
# 然后打开：http://localhost:18789
|
||||
```
|
||||
|
||||
**选项 B：Tailscale Serve（HTTPS，仅 loopback）**
|
||||
|
||||
```bash
|
||||
# On the droplet
|
||||
# 在 droplet 上
|
||||
curl -fsSL https://tailscale.com/install.sh | sh
|
||||
tailscale up
|
||||
|
||||
# Configure Gateway to use Tailscale Serve
|
||||
# 将 Gateway 网关配置为使用 Tailscale Serve
|
||||
openclaw config set gateway.tailscale.mode serve
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
打开：`https://<magicdns>/`
|
||||
|
||||
注意事项：
|
||||
说明：
|
||||
|
||||
- Serve 保持 Gateway 网关仅 loopback 并通过 Tailscale 身份头进行认证。
|
||||
- 要改为需要令牌/密码，请设置 `gateway.auth.allowTailscale: false` 或使用 `gateway.auth.mode: "password"`。
|
||||
- Serve 会让 Gateway 网关保持仅 loopback，并通过 Tailscale 身份头对 Control UI/WebSocket 流量进行认证（无 token 认证假定 Gateway 网关主机可信；HTTP API 仍然需要 token/password）。
|
||||
- 如果你想强制要求 token/password，请设置 `gateway.auth.allowTailscale: false` 或使用 `gateway.auth.mode: "password"`。
|
||||
|
||||
**选项 C：Tailnet 绑定（不使用 Serve）**
|
||||
**选项 C：绑定到 tailnet（不使用 Serve）**
|
||||
|
||||
```bash
|
||||
openclaw config set gateway.bind tailnet
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
打开：`http://<tailscale-ip>:18789`（需要令牌）。
|
||||
打开：`http://<tailscale-ip>:18789`（需要 token）。
|
||||
|
||||
## 7) 连接你的渠道
|
||||
## 7）连接你的渠道
|
||||
|
||||
### Telegram
|
||||
|
||||
@ -160,16 +164,16 @@ openclaw pairing approve telegram <CODE>
|
||||
|
||||
```bash
|
||||
openclaw channels login whatsapp
|
||||
# Scan QR code
|
||||
# 扫描 QR 码
|
||||
```
|
||||
|
||||
参见[渠道](/channels)了解其他提供商。
|
||||
其他提供商请参阅 [Channels](/channels)。
|
||||
|
||||
---
|
||||
|
||||
## 1GB RAM 的优化
|
||||
## 针对 1 GB RAM 的优化
|
||||
|
||||
$6 的 droplet 只有 1GB RAM。为了保持运行流畅：
|
||||
6 美元的 droplet 只有 1 GB RAM。为了保持运行顺畅：
|
||||
|
||||
### 添加 swap（推荐）
|
||||
|
||||
@ -183,9 +187,9 @@ echo '/swapfile none swap sw 0 0' >> /etc/fstab
|
||||
|
||||
### 使用更轻量的模型
|
||||
|
||||
如果遇到 OOM，考虑：
|
||||
如果你遇到 OOM，可以考虑：
|
||||
|
||||
- 使用基于 API 的模型（Claude、GPT）而不是本地模型
|
||||
- 使用基于 API 的模型（Claude、GPT），而不是本地模型
|
||||
- 将 `agents.defaults.model.primary` 设置为更小的模型
|
||||
|
||||
### 监控内存
|
||||
@ -199,12 +203,12 @@ htop
|
||||
|
||||
## 持久化
|
||||
|
||||
所有状态存储在：
|
||||
所有状态都存储在：
|
||||
|
||||
- `~/.openclaw/` — 配置、凭证、会话数据
|
||||
- `~/.openclaw/workspace/` — 工作区（SOUL.md、记忆等）
|
||||
- `~/.openclaw/workspace/` — 工作区（`SOUL.md`、memory 等）
|
||||
|
||||
这些在重启后保留。定期备份：
|
||||
这些内容在重启后仍会保留。请定期备份：
|
||||
|
||||
```bash
|
||||
tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace
|
||||
@ -214,21 +218,21 @@ tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace
|
||||
|
||||
## Oracle Cloud 免费替代方案
|
||||
|
||||
Oracle Cloud 提供 **Always Free** ARM 实例，比这里任何付费选项都强大得多 — 每月 $0。
|
||||
Oracle Cloud 提供 **Always Free** ARM 实例，性能显著强于这里列出的任何付费选项 —— 且每月 0 美元。
|
||||
|
||||
| 你将获得 | 配置 |
|
||||
| -------------- | ---------------- |
|
||||
| **4 OCPUs** | ARM Ampere A1 |
|
||||
| **24GB RAM** | 绰绰有余 |
|
||||
| **200GB 存储** | 块存储卷 |
|
||||
| **永久免费** | 不收取信用卡费用 |
|
||||
| 你将获得 | 规格 |
|
||||
| --------------- | ------------------ |
|
||||
| **4 OCPU** | ARM Ampere A1 |
|
||||
| **24 GB RAM** | 完全足够 |
|
||||
| **200 GB 存储** | 块存储卷 |
|
||||
| **永久免费** | 不会产生信用卡费用 |
|
||||
|
||||
**注意事项：**
|
||||
|
||||
- 注册可能有点麻烦（失败了就重试）
|
||||
- ARM 架构 — 大多数东西都能工作，但有些二进制文件需要 ARM 构建
|
||||
- 注册过程可能比较挑剔（如果失败请重试）
|
||||
- ARM 架构 —— 大多数东西都能运行，但某些二进制文件需要 ARM 构建版本
|
||||
|
||||
完整设置指南请参阅 [Oracle Cloud](/platforms/oracle)。关于注册技巧和注册流程故障排除，请参阅此[社区指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)。
|
||||
完整设置指南请参阅 [Oracle Cloud](/platforms/oracle)。关于注册技巧和注册流程故障排除，请参阅这篇[社区指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)。
|
||||
|
||||
---
|
||||
|
||||
@ -242,7 +246,7 @@ openclaw doctor --non-interactive
|
||||
journalctl -u openclaw --no-pager -n 50
|
||||
```
|
||||
|
||||
### 端口已被使用
|
||||
### 端口已被占用
|
||||
|
||||
```bash
|
||||
lsof -i :18789
|
||||
@ -252,18 +256,18 @@ kill <PID>
|
||||
### 内存不足
|
||||
|
||||
```bash
|
||||
# Check memory
|
||||
# 检查内存
|
||||
free -h
|
||||
|
||||
# Add more swap
|
||||
# Or upgrade to $12/mo droplet (2GB RAM)
|
||||
# 添加更多 swap
|
||||
# 或升级到每月 12 美元的 droplet（2 GB RAM）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 另请参阅
|
||||
|
||||
- [Hetzner 指南](/install/hetzner) — 更便宜、更强大
|
||||
- [Docker 安装](/install/docker) — 容器化设置
|
||||
- [Tailscale](/gateway/tailscale) — 安全远程访问
|
||||
- [配置](/gateway/configuration) — 完整配置参考
|
||||
- [Hetzner guide](/install/hetzner) — 更便宜、性能更强
|
||||
- [Docker install](/install/docker) — 容器化设置
|
||||
- [Tailscale](/gateway/tailscale) — 安全的远程访问
|
||||
- [Configuration](/gateway/configuration) — 完整配置参考
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 查找操作系统支持或安装路径时
|
||||
- 决定在哪里运行 Gateway 网关时
|
||||
summary: 平台支持概述（Gateway 网关 + 配套应用）
|
||||
- 查找操作系统支持或安装路径
|
||||
- 决定在哪里运行 Gateway 网关
|
||||
summary: 平台支持概览（Gateway 网关 + 配套应用）
|
||||
title: 平台
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:52:07Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 254852a5ed1996982a52eed4a72659477609e08d340c625d24ef6d99c21eece6
|
||||
generated_at: "2026-03-16T06:24:20Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 653f395598b9558cb15b58ab42ed931dba47c70780be1c803d33dd795bad6503
|
||||
source_path: platforms/index.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -16,11 +16,11 @@ x-i18n:
|
||||
# 平台
|
||||
|
||||
OpenClaw 核心使用 TypeScript 编写。**Node 是推荐的运行时**。
|
||||
不推荐 Bun 用于 Gateway 网关（WhatsApp/Telegram 存在 bug）。
|
||||
不建议将 Bun 用于 Gateway 网关（存在 WhatsApp/Telegram bug）。
|
||||
|
||||
配套应用适用于 macOS（菜单栏应用）和移动节点（iOS/Android）。Windows 和
|
||||
Linux 配套应用已在计划中，但 Gateway 网关目前已完全支持。
|
||||
Windows 原生配套应用也在计划中；推荐通过 WSL2 使用 Gateway 网关。
|
||||
已提供适用于 macOS（菜单栏应用）和移动节点（iOS/Android）的配套应用。Windows 和
|
||||
Linux 配套应用已在规划中，但 Gateway 网关目前已得到完全支持。
|
||||
适用于 Windows 的原生配套应用也在规划中；推荐通过 WSL2 运行 Gateway 网关。
|
||||
|
||||
## 选择你的操作系统
|
||||
|
||||
@ -30,7 +30,7 @@ Windows 原生配套应用也在计划中；推荐通过 WSL2 使用 Gateway 网
|
||||
- Windows：[Windows](/platforms/windows)
|
||||
- Linux：[Linux](/platforms/linux)
|
||||
|
||||
## VPS 和托管
|
||||
## VPS 与托管
|
||||
|
||||
- VPS 中心：[VPS 托管](/vps)
|
||||
- Fly.io：[Fly.io](/install/fly)
|
||||
@ -47,14 +47,14 @@ Windows 原生配套应用也在计划中；推荐通过 WSL2 使用 Gateway 网
|
||||
|
||||
## Gateway 网关服务安装（CLI）
|
||||
|
||||
使用以下任一方式（均支持）：
|
||||
使用以下任一方式（均受支持）：
|
||||
|
||||
- 向导（推荐）：`openclaw onboard --install-daemon`
|
||||
- 直接安装：`openclaw gateway install`
|
||||
- 配置流程：`openclaw configure` → 选择 **Gateway service**
|
||||
- 修复/迁移：`openclaw doctor`（提供安装或修复服务）
|
||||
- 配置流程：`openclaw configure` → 选择 **Gateway 服务**
|
||||
- 修复/迁移：`openclaw doctor`（会提供安装或修复服务的选项）
|
||||
|
||||
服务目标取决于操作系统：
|
||||
|
||||
- macOS：LaunchAgent（`bot.molt.gateway` 或 `bot.molt.<profile>`；旧版 `com.openclaw.*`）
|
||||
- macOS：LaunchAgent（`ai.openclaw.gateway` 或 `ai.openclaw.<profile>`；旧版为 `com.openclaw.*`）
|
||||
- Linux/WSL2：systemd 用户服务（`openclaw-gateway[-<profile>].service`）
|
||||
|
||||
@ -1,31 +1,31 @@
|
||||
---
|
||||
read_when:
|
||||
- 查找 Linux 配套应用状态时
|
||||
- 规划平台覆盖或贡献时
|
||||
- 查找 Linux 配套应用状态
|
||||
- 规划平台覆盖范围或贡献
|
||||
summary: Linux 支持 + 配套应用状态
|
||||
title: Linux 应用
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:52:18Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a9bbbcecf2fd522a2f5ac8f3b9068febbc43658465bfb9276bff6c3e946789d2
|
||||
generated_at: "2026-03-16T06:24:30Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 12f2a28ec8fc17769210bda97af11fda332355956d41bba69ac51cc523be6178
|
||||
source_path: platforms/linux.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Linux 应用
|
||||
|
||||
Gateway 网关在 Linux 上完全支持。**Node 是推荐的运行时**。
|
||||
不推荐 Bun 用于 Gateway 网关（WhatsApp/Telegram 存在 bug）。
|
||||
Gateway 网关在 Linux 上得到完全支持。**Node 是推荐的运行时**。
|
||||
不建议将 Bun 用于 Gateway 网关（存在 WhatsApp/Telegram bug）。
|
||||
|
||||
原生 Linux 配套应用已在计划中。如果你想帮助构建，欢迎贡献。
|
||||
原生 Linux 配套应用已在规划中。如果你想帮助构建一个，欢迎贡献。
|
||||
|
||||
## 新手快速路径（VPS）
|
||||
## 面向初学者的快速路径（VPS）
|
||||
|
||||
1. 安装 Node 22+
|
||||
1. 安装 Node 24（推荐；Node 22 LTS，目前 `22.16+`，为了兼容性仍然可用）
|
||||
2. `npm i -g openclaw@latest`
|
||||
3. `openclaw onboard --install-daemon`
|
||||
4. 从你的笔记本电脑：`ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
|
||||
4. 在你的笔记本电脑上运行：`ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
|
||||
5. 打开 `http://127.0.0.1:18789/` 并粘贴你的令牌
|
||||
|
||||
分步 VPS 指南：[exe.dev](/install/exe-dev)
|
||||
@ -49,19 +49,19 @@ Gateway 网关在 Linux 上完全支持。**Node 是推荐的运行时**。
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
或：
|
||||
或者：
|
||||
|
||||
```
|
||||
openclaw gateway install
|
||||
```
|
||||
|
||||
或：
|
||||
或者：
|
||||
|
||||
```
|
||||
openclaw configure
|
||||
```
|
||||
|
||||
出现提示时选择 **Gateway service**。
|
||||
出现提示时，选择 **Gateway 服务**。
|
||||
|
||||
修复/迁移：
|
||||
|
||||
@ -71,9 +71,8 @@ openclaw doctor
|
||||
|
||||
## 系统控制（systemd 用户单元）
|
||||
|
||||
OpenClaw 默认安装 systemd **用户**服务。对于共享或常驻服务器使用**系统**
|
||||
服务。完整的单元示例和指南
|
||||
在 [Gateway 网关运行手册](/gateway) 中。
|
||||
OpenClaw 默认安装 systemd **用户**服务。对于共享或始终在线的服务器，请使用 **系统** 服务。完整的单元示例和指导
|
||||
请参见 [Gateway 网关运行手册](/gateway)。
|
||||
|
||||
最小设置：
|
||||
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- 在 Raspberry Pi 上设置 OpenClaw 时
|
||||
- 在 ARM 设备上运行 OpenClaw 时
|
||||
- 构建低成本常驻个人 AI 时
|
||||
summary: 在 Raspberry Pi 上运行 OpenClaw（低成本自托管设置）
|
||||
- 在 Raspberry Pi 上设置 OpenClaw
|
||||
- 在 ARM 设备上运行 OpenClaw
|
||||
- 构建一个低成本、始终在线的个人 AI
|
||||
summary: 在 Raspberry Pi 上运行 OpenClaw（低预算自托管方案）
|
||||
title: Raspberry Pi
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:53:30Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 6741eaf0115a4fa0efd6599a99e0526a20ceb30eda1d9b04cba9dd5dec84bee2
|
||||
generated_at: "2026-03-16T06:24:58Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3106dea63b5a548622b82e3090e7fdb7f748b96bf0e23893496f1b60c095334a
|
||||
source_path: platforms/raspberry-pi.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,51 +18,51 @@ x-i18n:
|
||||
|
||||
## 目标
|
||||
|
||||
在 Raspberry Pi 上运行持久、常驻的 OpenClaw Gateway 网关，**一次性成本约 $35-80**（无月费）。
|
||||
在 Raspberry Pi 上以 **约 35–80 美元**的一次性成本（无月费）运行一个持久化、始终在线的 OpenClaw Gateway 网关。
|
||||
|
||||
适用于：
|
||||
非常适合：
|
||||
|
||||
- 24/7 个人 AI 助手
|
||||
- 家庭自动化中心
|
||||
- 低功耗、随时可用的 Telegram/WhatsApp 机器人
|
||||
- 7×24 个人 AI 助手
|
||||
- 家庭自动化中枢
|
||||
- 低功耗、始终可用的 Telegram/WhatsApp bot
|
||||
|
||||
## 硬件要求
|
||||
|
||||
| Pi 型号 | 内存 | 是否可用？ | 说明 |
|
||||
| --------------- | ------- | ---------- | -------------------------- |
|
||||
| **Pi 5** | 4GB/8GB | ✅ 最佳 | 最快，推荐 |
|
||||
| **Pi 4** | 4GB | ✅ 良好 | 大多数用户的最佳选择 |
|
||||
| **Pi 4** | 2GB | ✅ 可以 | 可用，添加交换空间 |
|
||||
| **Pi 4** | 1GB | ⚠️ 紧张 | 使用交换空间可行，最小配置 |
|
||||
| **Pi 3B+** | 1GB | ⚠️ 慢 | 可用但较慢 |
|
||||
| **Pi Zero 2 W** | 512MB | ❌ | 不推荐 |
|
||||
| Pi 型号 | RAM | 可用？ | 说明 |
|
||||
| --------------- | ------- | ------- | -------------------------- |
|
||||
| **Pi 5** | 4GB/8GB | ✅ 最佳 | 最快，推荐 |
|
||||
| **Pi 4** | 4GB | ✅ 良好 | 适合大多数用户的最佳平衡点 |
|
||||
| **Pi 4** | 2GB | ✅ 可以 | 可用，建议加 swap |
|
||||
| **Pi 4** | 1GB | ⚠️ 紧张 | 配合 swap 和最小化配置可行 |
|
||||
| **Pi 3B+** | 1GB | ⚠️ 较慢 | 可用，但反应迟缓 |
|
||||
| **Pi Zero 2 W** | 512MB | ❌ | 不推荐 |
|
||||
|
||||
**最低配置：** 1GB 内存，1 核，500MB 磁盘
|
||||
**推荐：** 2GB+ 内存，64 位系统，16GB+ SD 卡（或 USB SSD）
|
||||
**最低规格：** 1 GB RAM、1 核、500 MB 磁盘
|
||||
**推荐规格：** 2 GB 以上 RAM、64 位 OS、16 GB 以上 SD 卡（或 USB SSD）
|
||||
|
||||
## 你需要准备
|
||||
## 你需要准备的内容
|
||||
|
||||
- Raspberry Pi 4 或 5（推荐 2GB+）
|
||||
- MicroSD 卡（16GB+）或 USB SSD（性能更好）
|
||||
- 电源（推荐官方 Pi 电源）
|
||||
- 网络连接（以太网或 WiFi）
|
||||
- Raspberry Pi 4 或 5（推荐 2 GB 以上）
|
||||
- MicroSD 卡（16 GB 以上）或 USB SSD（性能更好）
|
||||
- 电源（推荐使用官方 Pi 电源）
|
||||
- 网络连接（以太网或 Wi‑Fi）
|
||||
- 约 30 分钟
|
||||
|
||||
## 1) 刷写系统
|
||||
## 1）刷写 OS
|
||||
|
||||
使用 **Raspberry Pi OS Lite (64-bit)** — 无头服务器不需要桌面。
|
||||
使用 **Raspberry Pi OS Lite（64 位）** —— 对于无头服务器，不需要桌面环境。
|
||||
|
||||
1. 下载 [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
|
||||
2. 选择系统：**Raspberry Pi OS Lite (64-bit)**
|
||||
3. 点击齿轮图标（⚙️）预配置：
|
||||
2. 选择 OS：**Raspberry Pi OS Lite（64 位）**
|
||||
3. 点击齿轮图标（⚙️）进行预配置：
|
||||
- 设置主机名：`gateway-host`
|
||||
- 启用 SSH
|
||||
- 设置用户名/密码
|
||||
- 配置 WiFi（如果不使用以太网）
|
||||
4. 刷写到你的 SD 卡 / USB 驱动器
|
||||
- 配置 Wi‑Fi（如果不使用以太网）
|
||||
4. 将系统写入你的 SD 卡 / USB 驱动器
|
||||
5. 插入并启动 Pi
|
||||
|
||||
## 2) 通过 SSH 连接
|
||||
## 2）通过 SSH 连接
|
||||
|
||||
```bash
|
||||
ssh user@gateway-host
|
||||
@ -70,37 +70,37 @@ ssh user@gateway-host
|
||||
ssh user@192.168.x.x
|
||||
```
|
||||
|
||||
## 3) 系统设置
|
||||
## 3）系统设置
|
||||
|
||||
```bash
|
||||
# 更新系统
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
|
||||
# 安装必要软件包
|
||||
# 安装基础软件包
|
||||
sudo apt install -y git curl build-essential
|
||||
|
||||
# 设置时区（对 cron/提醒很重要）
|
||||
sudo timedatectl set-timezone America/Chicago # 改成你的时区
|
||||
```
|
||||
|
||||
## 4) 安装 Node.js 22（ARM64）
|
||||
## 4）安装 Node.js 24（ARM64）
|
||||
|
||||
```bash
|
||||
# 通过 NodeSource 安装 Node.js
|
||||
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
|
||||
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
|
||||
sudo apt install -y nodejs
|
||||
|
||||
# 验证
|
||||
node --version # 应显示 v22.x.x
|
||||
node --version # 应显示 v24.x.x
|
||||
npm --version
|
||||
```
|
||||
|
||||
## 5) 添加交换空间（2GB 或更少内存时很重要）
|
||||
## 5）添加 swap（对于 2 GB 或更低内存很重要）
|
||||
|
||||
交换空间可防止内存不足崩溃：
|
||||
swap 可以防止内存不足崩溃：
|
||||
|
||||
```bash
|
||||
# 创建 2GB 交换文件
|
||||
# 创建 2 GB swap 文件
|
||||
sudo fallocate -l 2G /swapfile
|
||||
sudo chmod 600 /swapfile
|
||||
sudo mkswap /swapfile
|
||||
@ -109,12 +109,12 @@ sudo swapon /swapfile
|
||||
# 永久生效
|
||||
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
|
||||
|
||||
# 优化低内存（降低 swappiness）
|
||||
# 针对低内存优化（降低 swappiness）
|
||||
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
|
||||
sudo sysctl -p
|
||||
```
|
||||
|
||||
## 6) 安装 OpenClaw
|
||||
## 6）安装 OpenClaw
|
||||
|
||||
### 选项 A：标准安装（推荐）
|
||||
|
||||
@ -122,7 +122,7 @@ sudo sysctl -p
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
### 选项 B：可修改安装（用于调试）
|
||||
### 选项 B：可修改安装（适合折腾）
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
@ -132,22 +132,22 @@ npm run build
|
||||
npm link
|
||||
```
|
||||
|
||||
可修改安装让你可以直接访问日志和代码 — 对调试 ARM 特定问题很有用。
|
||||
可修改安装会让你直接访问日志和代码 —— 这对于调试 ARM 特定问题很有帮助。
|
||||
|
||||
## 7) 运行新手引导
|
||||
## 7）运行新手引导
|
||||
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
按照向导操作：
|
||||
按向导完成设置：
|
||||
|
||||
1. **Gateway 网关模式：** Local
|
||||
2. **认证：** 推荐 API 密钥（OAuth 在无头 Pi 上可能不稳定）
|
||||
3. **渠道：** Telegram 最容易上手
|
||||
2. **认证：** 推荐 API key（在无头 Pi 上 OAuth 可能比较挑环境）
|
||||
3. **渠道：** 最容易上手的是 Telegram
|
||||
4. **守护进程：** 是（systemd）
|
||||
|
||||
## 8) 验证安装
|
||||
## 8）验证安装
|
||||
|
||||
```bash
|
||||
# 检查状态
|
||||
@ -160,52 +160,103 @@ sudo systemctl status openclaw
|
||||
journalctl -u openclaw -f
|
||||
```
|
||||
|
||||
## 9) 访问仪表板
|
||||
## 9）访问 OpenClaw Dashboard
|
||||
|
||||
由于 Pi 是无头的，使用 SSH 隧道：
|
||||
将 `user@gateway-host` 替换为你的 Pi 用户名，以及主机名或 IP 地址。
|
||||
|
||||
在你的电脑上，让 Pi 打印一个新的 Dashboard URL：
|
||||
|
||||
```bash
|
||||
# 从你的笔记本电脑/台式机
|
||||
ssh -L 18789:localhost:18789 user@gateway-host
|
||||
|
||||
# 然后在浏览器中打开
|
||||
open http://localhost:18789
|
||||
ssh user@gateway-host 'openclaw dashboard --no-open'
|
||||
```
|
||||
|
||||
或使用 Tailscale 实现常驻访问：
|
||||
该命令会打印 `Dashboard URL:`。根据 `gateway.auth.token`
|
||||
的配置方式，URL 可能是普通的 `http://127.0.0.1:18789/` 链接，也可能是包含 `#token=...` 的链接。
|
||||
|
||||
在你电脑上的另一个终端中，创建 SSH 隧道：
|
||||
|
||||
```bash
|
||||
# 在 Pi 上
|
||||
curl -fsSL https://tailscale.com/install.sh | sh
|
||||
sudo tailscale up
|
||||
|
||||
# 更新配置
|
||||
openclaw config set gateway.bind tailnet
|
||||
sudo systemctl restart openclaw
|
||||
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
|
||||
```
|
||||
|
||||
然后在本地浏览器中打开打印出的 Dashboard URL。
|
||||
|
||||
如果 UI 要求认证，请将 `gateway.auth.token`
|
||||
（或 `OPENCLAW_GATEWAY_TOKEN`）中的 token 粘贴到 Control UI 设置中。
|
||||
|
||||
如需始终在线的远程访问，请参阅 [Tailscale](/gateway/tailscale)。
|
||||
|
||||
---
|
||||
|
||||
## 性能优化
|
||||
|
||||
### 使用 USB SSD（巨大改进）
|
||||
### 使用 USB SSD（显著提升）
|
||||
|
||||
SD 卡速度慢且会磨损。USB SSD 可大幅提升性能：
|
||||
SD 卡速度慢且易磨损。USB SSD 会显著提升性能：
|
||||
|
||||
```bash
|
||||
# 检查是否从 USB 启动
|
||||
lsblk
|
||||
```
|
||||
|
||||
设置请参见 [Pi USB 启动指南](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot)。
|
||||
设置方法请参阅 [Pi USB boot guide](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot)。
|
||||
|
||||
### 减少内存使用
|
||||
### 加快 CLI 启动速度（模块编译缓存）
|
||||
|
||||
在性能较弱的 Pi 主机上，启用 Node 的模块编译缓存可以加快重复 CLI 运行速度：
|
||||
|
||||
```bash
|
||||
# 禁用 GPU 内存分配（无头模式）
|
||||
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
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `NODE_COMPILE_CACHE` 会加快后续运行（`status`、`health`、`--help`）。
|
||||
- `/var/tmp` 比 `/tmp` 更能在重启后保留内容。
|
||||
- `OPENCLAW_NO_RESPAWN=1` 可避免 CLI 自重启带来的额外启动开销。
|
||||
- 第一次运行会预热缓存；之后的运行收益最大。
|
||||
|
||||
### systemd 启动调优（可选）
|
||||
|
||||
如果这台 Pi 主要运行 OpenClaw，可以添加一个服务 drop-in，以减少重启抖动并保持稳定的启动环境：
|
||||
|
||||
```bash
|
||||
sudo systemctl edit openclaw
|
||||
```
|
||||
|
||||
```ini
|
||||
[Service]
|
||||
Environment=OPENCLAW_NO_RESPAWN=1
|
||||
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
|
||||
Restart=always
|
||||
RestartSec=2
|
||||
TimeoutStartSec=90
|
||||
```
|
||||
|
||||
然后应用：
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart openclaw
|
||||
```
|
||||
|
||||
如果可能，请将 OpenClaw 状态/缓存放在 SSD 支持的存储上，以避免冷启动期间 SD 卡随机 I/O 成为瓶颈。
|
||||
|
||||
关于 `Restart=` 策略如何帮助自动恢复：
|
||||
[systemd can automate service recovery](https://www.redhat.com/en/blog/systemd-automate-recovery)。
|
||||
|
||||
### 减少内存占用
|
||||
|
||||
```bash
|
||||
# 禁用 GPU 内存分配（无头）
|
||||
echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
|
||||
|
||||
# 如不需要则禁用蓝牙
|
||||
# 如果不需要，禁用蓝牙
|
||||
sudo systemctl disable bluetooth
|
||||
```
|
||||
|
||||
@ -228,32 +279,32 @@ htop
|
||||
|
||||
### 二进制兼容性
|
||||
|
||||
大多数 OpenClaw 功能在 ARM64 上可用，但某些外部二进制文件可能需要 ARM 构建：
|
||||
OpenClaw 的大多数功能都可在 ARM64 上运行，但某些外部二进制文件可能需要 ARM 构建版本：
|
||||
|
||||
| 工具 | ARM64 状态 | 说明 |
|
||||
| ------------------ | ---------- | ----------------------------------- |
|
||||
| Node.js | ✅ | 运行良好 |
|
||||
| WhatsApp (Baileys) | ✅ | 纯 JS，无问题 |
|
||||
| Telegram | ✅ | 纯 JS，无问题 |
|
||||
| gog (Gmail CLI) | ⚠️ | 检查是否有 ARM 版本 |
|
||||
| gog (Gmail CLI) | ⚠️ | 请检查是否有 ARM 发布版本 |
|
||||
| Chromium (browser) | ✅ | `sudo apt install chromium-browser` |
|
||||
|
||||
如果某个 skill 失败，检查其二进制文件是否有 ARM 构建。许多 Go/Rust 工具有；有些没有。
|
||||
如果某个 skill 失败，请检查其二进制文件是否有 ARM 构建版本。许多 Go/Rust 工具都有；有些则没有。
|
||||
|
||||
### 32 位 vs 64 位
|
||||
### 32 位与 64 位
|
||||
|
||||
**始终使用 64 位系统。** Node.js 和许多现代工具需要它。使用以下命令检查：
|
||||
**务必使用 64 位 OS。** Node.js 和许多现代工具都要求如此。使用以下命令检查：
|
||||
|
||||
```bash
|
||||
uname -m
|
||||
# 应显示：aarch64（64 位）而不是 armv7l（32 位）
|
||||
# 应显示：aarch64（64 位），而不是 armv7l（32 位）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 推荐的模型设置
|
||||
|
||||
由于 Pi 只是 Gateway 网关（模型在云端运行），使用基于 API 的模型：
|
||||
由于 Pi 只是 Gateway 网关（模型在云中运行），请使用基于 API 的模型：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -268,19 +319,19 @@ uname -m
|
||||
}
|
||||
```
|
||||
|
||||
**不要尝试在 Pi 上运行本地 LLM** — 即使是小模型也太慢了。让 Claude/GPT 来做繁重的工作。
|
||||
**不要尝试在 Pi 上运行本地 LLM** —— 即使是小模型也太慢了。让 Claude/GPT 负责主要计算工作。
|
||||
|
||||
---
|
||||
|
||||
## 开机自启
|
||||
## 开机自动启动
|
||||
|
||||
新手引导向导会设置这个，但要验证：
|
||||
设置向导会帮你配置这个，但你也可以这样验证：
|
||||
|
||||
```bash
|
||||
# 检查服务是否已启用
|
||||
sudo systemctl is-enabled openclaw
|
||||
|
||||
# 如果没有则启用
|
||||
# 如果没有，则启用
|
||||
sudo systemctl enable openclaw
|
||||
|
||||
# 开机启动
|
||||
@ -297,15 +348,15 @@ sudo systemctl start openclaw
|
||||
# 检查内存
|
||||
free -h
|
||||
|
||||
# 添加更多交换空间（见步骤 5）
|
||||
# 添加更多 swap（见第 5 步）
|
||||
# 或减少 Pi 上运行的服务
|
||||
```
|
||||
|
||||
### 性能慢
|
||||
### 性能缓慢
|
||||
|
||||
- 使用 USB SSD 代替 SD 卡
|
||||
- 使用 USB SSD 替代 SD 卡
|
||||
- 禁用未使用的服务：`sudo systemctl disable cups bluetooth avahi-daemon`
|
||||
- 检查 CPU 降频：`vcgencmd get_throttled`（应返回 `0x0`）
|
||||
- 检查 CPU 限频：`vcgencmd get_throttled`（应返回 `0x0`）
|
||||
|
||||
### 服务无法启动
|
||||
|
||||
@ -314,25 +365,25 @@ free -h
|
||||
journalctl -u openclaw --no-pager -n 100
|
||||
|
||||
# 常见修复：重新构建
|
||||
cd ~/openclaw # 如果使用可修改安装
|
||||
cd ~/openclaw # 如果使用的是可修改安装
|
||||
npm run build
|
||||
sudo systemctl restart openclaw
|
||||
```
|
||||
|
||||
### ARM 二进制问题
|
||||
|
||||
如果某个 skill 失败并显示"exec format error"：
|
||||
如果某个 skill 因 “exec format error” 失败：
|
||||
|
||||
1. 检查该二进制文件是否有 ARM64 构建
|
||||
2. 尝试从源代码构建
|
||||
1. 检查该二进制文件是否有 ARM64 构建版本
|
||||
2. 尝试从源码构建
|
||||
3. 或使用支持 ARM 的 Docker 容器
|
||||
|
||||
### WiFi 断开
|
||||
### Wi‑Fi 掉线
|
||||
|
||||
对于使用 WiFi 的无头 Pi：
|
||||
对于通过 Wi‑Fi 运行的无头 Pi：
|
||||
|
||||
```bash
|
||||
# 禁用 WiFi 电源管理
|
||||
# 禁用 Wi‑Fi 省电
|
||||
sudo iwconfig wlan0 power off
|
||||
|
||||
# 永久生效
|
||||
@ -343,23 +394,23 @@ echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
|
||||
|
||||
## 成本对比
|
||||
|
||||
| 设置 | 一次性成本 | 月费 | 说明 |
|
||||
| -------------- | ---------- | -------- | ------------------ |
|
||||
| **Pi 4 (2GB)** | ~$45 | $0 | + 电费（约 $5/年） |
|
||||
| **Pi 4 (4GB)** | ~$55 | $0 | 推荐 |
|
||||
| **Pi 5 (4GB)** | ~$60 | $0 | 最佳性能 |
|
||||
| **Pi 5 (8GB)** | ~$80 | $0 | 过剩但面向未来 |
|
||||
| DigitalOcean | $0 | $6/月 | $72/年 |
|
||||
| Hetzner | $0 | €3.79/月 | 约 $50/年 |
|
||||
| 方案 | 一次性成本 | 月成本 | 说明 |
|
||||
| --------------- | ---------- | -------- | ------------------------ |
|
||||
| **Pi 4（2GB）** | ~$45 | $0 | + 电费（约 $5/年） |
|
||||
| **Pi 4（4GB）** | ~$55 | $0 | 推荐 |
|
||||
| **Pi 5（4GB）** | ~$60 | $0 | 最佳性能 |
|
||||
| **Pi 5（8GB）** | ~$80 | $0 | 有些超配，但更有未来余量 |
|
||||
| DigitalOcean | $0 | $6/月 | $72/年 |
|
||||
| Hetzner | $0 | €3.79/月 | 约 $50/年 |
|
||||
|
||||
**回本期：** 与云 VPS 相比，Pi 约 6-12 个月内回本。
|
||||
**回本周期：** 与云 VPS 相比，一台 Pi 大约 6–12 个月即可回本。
|
||||
|
||||
---
|
||||
|
||||
## 另请参阅
|
||||
|
||||
- [Linux 指南](/platforms/linux) — 通用 Linux 设置
|
||||
- [DigitalOcean 指南](/platforms/digitalocean) — 云替代方案
|
||||
- [Hetzner 指南](/install/hetzner) — Docker 设置
|
||||
- [Linux guide](/platforms/linux) — 通用 Linux 设置
|
||||
- [DigitalOcean guide](/platforms/digitalocean) — 云端替代方案
|
||||
- [Hetzner guide](/install/hetzner) — Docker 设置
|
||||
- [Tailscale](/gateway/tailscale) — 远程访问
|
||||
- [节点](/nodes) — 将你的笔记本电脑/手机与 Pi Gateway 网关配对
|
||||
- [Nodes](/nodes) — 将你的笔记本电脑/手机与 Pi Gateway 网关配对
|
||||
|
||||
@ -3,31 +3,72 @@ read_when:
|
||||
- 在 Windows 上安装 OpenClaw
|
||||
- 查找 Windows 配套应用状态
|
||||
summary: Windows（WSL2）支持 + 配套应用状态
|
||||
title: Windows (WSL2)
|
||||
title: Windows（WSL2）
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:53:19Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: c93d2263b4e5b60cb6fbe9adcb1a0ca95b70cd6feb6e63cfc4459cb18b229da0
|
||||
generated_at: "2026-03-16T06:24:52Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2e905b129f34ac31e30d5767504233411b306b5985252f1a285e09f1ece19962
|
||||
source_path: platforms/windows.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Windows (WSL2)
|
||||
# Windows（WSL2）
|
||||
|
||||
Windows 上的 OpenClaw 推荐**通过 WSL2**（推荐 Ubuntu）。CLI + Gateway 网关在 Linux 内运行，这保持了运行时的一致性并使工具兼容性大大提高（Node/Bun/pnpm、Linux 二进制文件、Skills）。原生 Windows 可能更棘手。WSL2 给你完整的 Linux 体验——一条命令安装：`wsl --install`。
|
||||
推荐在 Windows 上**通过 WSL2** 运行 OpenClaw（推荐 Ubuntu）。CLI + Gateway 网关在 Linux 内运行，这能保持运行时一致，并使
|
||||
工具链兼容性高得多（Node/Bun/pnpm、Linux 二进制文件、Skills）。原生
|
||||
Windows 可能会更棘手。WSL2 可提供完整的 Linux 体验 —— 只需一条命令
|
||||
即可安装：`wsl --install`。
|
||||
|
||||
原生 Windows 配套应用已在计划中。
|
||||
原生 Windows 配套应用已在规划中。
|
||||
|
||||
## 安装（WSL2）
|
||||
|
||||
- [入门指南](/start/getting-started)（在 WSL 内使用）
|
||||
- [安装和更新](/install/updating)
|
||||
- 官方 WSL2 指南（Microsoft）：https://learn.microsoft.com/windows/wsl/install
|
||||
- [入门指南](/start/getting-started)（请在 WSL 内使用）
|
||||
- [安装与更新](/install/updating)
|
||||
- 官方 WSL2 指南（Microsoft）：[https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
|
||||
|
||||
## 原生 Windows 状态
|
||||
|
||||
原生 Windows CLI 流程正在改进，但 WSL2 仍然是推荐路径。
|
||||
|
||||
当前在原生 Windows 上运行良好的内容：
|
||||
|
||||
- 通过 `install.ps1` 使用网站安装器
|
||||
- 本地 CLI 用法，例如 `openclaw --version`、`openclaw doctor` 和 `openclaw plugins list --json`
|
||||
- 嵌入式 local-agent/provider 冒烟测试，例如：
|
||||
|
||||
```powershell
|
||||
openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."
|
||||
```
|
||||
|
||||
当前注意事项：
|
||||
|
||||
- 除非你传递 `--skip-health`，否则 `openclaw onboard --non-interactive` 仍然要求本地 Gateway 网关可访问
|
||||
- `openclaw onboard --non-interactive --install-daemon` 和 `openclaw gateway install` 会优先尝试 Windows Scheduled Tasks
|
||||
- 如果拒绝创建 Scheduled Task，OpenClaw 会回退到每用户 Startup 文件夹登录项，并立即启动 Gateway 网关
|
||||
- 如果 `schtasks` 本身卡住或停止响应，OpenClaw 现在会快速中止该路径并回退，而不是无限挂起
|
||||
- 在可用时仍优先使用 Scheduled Tasks，因为它们能提供更好的 supervisor 状态
|
||||
|
||||
如果你只想使用原生 CLI，而不安装 Gateway 网关服务，可使用以下任一方式：
|
||||
|
||||
```powershell
|
||||
openclaw onboard --non-interactive --skip-health
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
如果你确实想在原生 Windows 上使用受管启动：
|
||||
|
||||
```powershell
|
||||
openclaw gateway install
|
||||
openclaw gateway status --json
|
||||
```
|
||||
|
||||
如果无法创建 Scheduled Task，回退服务模式仍会通过当前用户的 Startup 文件夹在登录后自动启动。
|
||||
|
||||
## Gateway 网关
|
||||
|
||||
- [Gateway 网关操作手册](/gateway)
|
||||
- [Gateway 网关运行手册](/gateway)
|
||||
- [配置](/gateway/configuration)
|
||||
|
||||
## Gateway 网关服务安装（CLI）
|
||||
@ -38,19 +79,19 @@ Windows 上的 OpenClaw 推荐**通过 WSL2**（推荐 Ubuntu）。CLI + Gateway
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
或：
|
||||
或者：
|
||||
|
||||
```
|
||||
openclaw gateway install
|
||||
```
|
||||
|
||||
或：
|
||||
或者：
|
||||
|
||||
```
|
||||
openclaw configure
|
||||
```
|
||||
|
||||
出现提示时选择 **Gateway service**。
|
||||
出现提示时，选择 **Gateway 服务**。
|
||||
|
||||
修复/迁移：
|
||||
|
||||
@ -58,11 +99,58 @@ openclaw configure
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
## 高级：通过 LAN 暴露 WSL 服务（portproxy）
|
||||
## 在 Windows 登录前自动启动 Gateway 网关
|
||||
|
||||
WSL 有自己的虚拟网络。如果另一台机器需要访问**在 WSL 内**运行的服务（SSH、本地 TTS 服务器或 Gateway 网关），你必须将 Windows 端口转发到当前的 WSL IP。WSL IP 在重启后会改变，因此你可能需要刷新转发规则。
|
||||
对于无头设置，请确保完整的启动链即使在无人登录
|
||||
Windows 时也能运行。
|
||||
|
||||
示例（以**管理员身份**运行 PowerShell）：
|
||||
### 1）在未登录时保持用户服务运行
|
||||
|
||||
在 WSL 内：
|
||||
|
||||
```bash
|
||||
sudo loginctl enable-linger "$(whoami)"
|
||||
```
|
||||
|
||||
### 2）安装 OpenClaw Gateway 网关用户服务
|
||||
|
||||
在 WSL 内：
|
||||
|
||||
```bash
|
||||
openclaw gateway install
|
||||
```
|
||||
|
||||
### 3）在 Windows 启动时自动启动 WSL
|
||||
|
||||
以管理员身份打开 PowerShell：
|
||||
|
||||
```powershell
|
||||
schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM
|
||||
```
|
||||
|
||||
将 `Ubuntu` 替换为以下命令输出中的发行版名称：
|
||||
|
||||
```powershell
|
||||
wsl --list --verbose
|
||||
```
|
||||
|
||||
### 验证启动链
|
||||
|
||||
重启后（在 Windows 登录前），在 WSL 中检查：
|
||||
|
||||
```bash
|
||||
systemctl --user is-enabled openclaw-gateway
|
||||
systemctl --user status openclaw-gateway --no-pager
|
||||
```
|
||||
|
||||
## 高级：通过局域网暴露 WSL 服务（portproxy）
|
||||
|
||||
WSL 有自己的虚拟网络。如果另一台机器需要访问
|
||||
**在 WSL 内运行**的服务（SSH、本地 TTS 服务器或 Gateway 网关），你必须
|
||||
将 Windows 端口转发到当前的 WSL IP。WSL IP 会在重启后变化，
|
||||
因此你可能需要刷新转发规则。
|
||||
|
||||
示例（**以管理员身份**打开 PowerShell）：
|
||||
|
||||
```powershell
|
||||
$Distro = "Ubuntu-24.04"
|
||||
@ -76,7 +164,7 @@ netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPor
|
||||
connectaddress=$WslIp connectport=$TargetPort
|
||||
```
|
||||
|
||||
允许端口通过 Windows 防火墙（一次性）：
|
||||
允许该端口通过 Windows 防火墙（一次性）：
|
||||
|
||||
```powershell
|
||||
New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
|
||||
@ -91,14 +179,16 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.
|
||||
connectaddress=$WslIp connectport=$TargetPort | Out-Null
|
||||
```
|
||||
|
||||
注意事项：
|
||||
说明：
|
||||
|
||||
- 从另一台机器 SSH 目标是 **Windows 主机 IP**（示例：`ssh user@windows-host -p 2222`）。
|
||||
- 远程节点必须指向**可访问的** Gateway 网关 URL（不是 `127.0.0.1`）；使用 `openclaw status --all` 确认。
|
||||
- 使用 `listenaddress=0.0.0.0` 进行 LAN 访问；`127.0.0.1` 仅保持本地访问。
|
||||
- 如果你想自动化，注册一个计划任务在登录时运行刷新步骤。
|
||||
- 来自另一台机器的 SSH 应指向**Windows 主机 IP**（例如：`ssh user@windows-host -p 2222`）。
|
||||
- 远程节点必须指向**可访问的** Gateway 网关 URL（而不是 `127.0.0.1`）；请使用
|
||||
`openclaw status --all` 进行确认。
|
||||
- 使用 `listenaddress=0.0.0.0` 可供局域网访问；`127.0.0.1` 则仅限本地。
|
||||
- 如果你希望自动执行此操作，请注册一个 Scheduled Task，在登录时运行刷新
|
||||
步骤。
|
||||
|
||||
## WSL2 分步安装
|
||||
## 分步 WSL2 安装
|
||||
|
||||
### 1）安装 WSL2 + Ubuntu
|
||||
|
||||
@ -106,14 +196,14 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.
|
||||
|
||||
```powershell
|
||||
wsl --install
|
||||
# Or pick a distro explicitly:
|
||||
# 或显式选择一个发行版：
|
||||
wsl --list --online
|
||||
wsl --install -d Ubuntu-24.04
|
||||
```
|
||||
|
||||
如果 Windows 要求则重启。
|
||||
如果 Windows 提示，请重启。
|
||||
|
||||
### 2）启用 systemd（Gateway 网关安装所需）
|
||||
### 2）启用 systemd（Gateway 网关安装所必需）
|
||||
|
||||
在你的 WSL 终端中：
|
||||
|
||||
@ -124,7 +214,7 @@ systemd=true
|
||||
EOF
|
||||
```
|
||||
|
||||
然后从 PowerShell：
|
||||
然后在 PowerShell 中运行：
|
||||
|
||||
```powershell
|
||||
wsl --shutdown
|
||||
@ -138,13 +228,13 @@ systemctl --user status
|
||||
|
||||
### 3）安装 OpenClaw（在 WSL 内）
|
||||
|
||||
在 WSL 内按照 Linux 入门指南流程：
|
||||
在 WSL 内按照 Linux 入门指南流程操作：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
cd openclaw
|
||||
pnpm install
|
||||
pnpm ui:build # auto-installs UI deps on first run
|
||||
pnpm ui:build # 首次运行时会自动安装 UI 依赖
|
||||
pnpm build
|
||||
openclaw onboard
|
||||
```
|
||||
@ -153,4 +243,5 @@ openclaw onboard
|
||||
|
||||
## Windows 配套应用
|
||||
|
||||
我们还没有 Windows 配套应用。如果你想让它实现，欢迎贡献。
|
||||
我们还没有 Windows 配套应用。如果你想推动这件事发生，欢迎
|
||||
贡献。
|
||||
|
||||
@ -5,31 +5,31 @@ read_when:
|
||||
summary: 在 OpenClaw 中通过 API 密钥或 setup-token 使用 Anthropic Claude
|
||||
title: Anthropic
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T10:08:33Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a78ccd855810a93e71d7138af4d3fc7d66e877349815c4a3207cf2214b0150b3
|
||||
generated_at: "2026-03-16T06:25:19Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b18eff35b652d8dc4b6d55e9051d35682511909b3168be868fa172038294d20b
|
||||
source_path: providers/anthropic.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Anthropic（Claude）
|
||||
|
||||
Anthropic 构建了 **Claude** 模型系列，并通过 API 提供访问。
|
||||
在 OpenClaw 中，你可以使用 API 密钥或 **setup-token** 进行认证。
|
||||
Anthropic 构建了 **Claude** 模型家族，并通过 API 提供访问。
|
||||
在 OpenClaw 中，你可以使用 API 密钥或 **setup-token** 进行身份验证。
|
||||
|
||||
## 选项 A：Anthropic API 密钥
|
||||
|
||||
**适用于：** 标准 API 访问和按用量计费。
|
||||
在 Anthropic Console 中创建你的 API 密钥。
|
||||
**最适合：** 标准 API 访问和按使用量计费。
|
||||
请在 Anthropic Console 中创建你的 API 密钥。
|
||||
|
||||
### CLI 设置
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
# 选择：Anthropic API key
|
||||
# choose: Anthropic API key
|
||||
|
||||
# 或非交互式
|
||||
# or non-interactive
|
||||
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
|
||||
```
|
||||
|
||||
@ -38,22 +38,59 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
|
||||
```json5
|
||||
{
|
||||
env: { ANTHROPIC_API_KEY: "sk-ant-..." },
|
||||
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
|
||||
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
|
||||
}
|
||||
```
|
||||
|
||||
## 提示缓存（Anthropic API）
|
||||
## Thinking 默认值（Claude 4.6）
|
||||
|
||||
OpenClaw 支持 Anthropic 的提示缓存功能。这是**仅限 API**；订阅认证不支持缓存设置。
|
||||
- 当未设置显式 thinking 级别时，Anthropic Claude 4.6 模型在 OpenClaw 中默认使用 `adaptive` thinking。
|
||||
- 你可以按消息覆盖（`/think:<level>`），或在模型参数中覆盖：
|
||||
`agents.defaults.models["anthropic/<model>"].params.thinking`。
|
||||
- 相关 Anthropic 文档：
|
||||
- [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking)
|
||||
- [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
|
||||
|
||||
## 快速模式（Anthropic API）
|
||||
|
||||
OpenClaw 的共享 `/fast` 开关也支持直接 Anthropic API 密钥流量。
|
||||
|
||||
- `/fast on` 映射到 `service_tier: "auto"`
|
||||
- `/fast off` 映射到 `service_tier: "standard_only"`
|
||||
- 配置默认值：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
models: {
|
||||
"anthropic/claude-sonnet-4-5": {
|
||||
params: { fastMode: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
重要限制：
|
||||
|
||||
- 这**仅适用于 API 密钥**。Anthropic setup-token / OAuth 身份验证不会遵循 OpenClaw 的快速模式层级注入。
|
||||
- OpenClaw 仅对直接发往 `api.anthropic.com` 的请求注入 Anthropic 服务层级。如果你通过代理或网关路由 `anthropic/*`，`/fast` 不会修改 `service_tier`。
|
||||
- Anthropic 会在响应中的 `usage.service_tier` 下报告实际生效的层级。对于没有 Priority Tier 容量的账户，`service_tier: "auto"` 仍可能解析为 `standard`。
|
||||
|
||||
## Prompt 缓存（Anthropic API）
|
||||
|
||||
OpenClaw 支持 Anthropic 的 prompt 缓存功能。这**仅适用于 API**；订阅身份验证不会遵循缓存设置。
|
||||
|
||||
### 配置
|
||||
|
||||
在模型配置中使用 `cacheRetention` 参数：
|
||||
在你的模型配置中使用 `cacheRetention` 参数：
|
||||
|
||||
| 值 | 缓存时长 | 描述 |
|
||||
| 值 | 缓存时长 | 说明 |
|
||||
| ------- | -------- | -------------------------- |
|
||||
| `none` | 无缓存 | 禁用提示缓存 |
|
||||
| `short` | 5 分钟 | API 密钥认证的默认值 |
|
||||
| `none` | 不缓存 | 禁用 prompt 缓存 |
|
||||
| `short` | 5 分钟 | API 密钥身份验证的默认值 |
|
||||
| `long` | 1 小时 | 扩展缓存（需要 beta 标志） |
|
||||
|
||||
```json5
|
||||
@ -61,7 +98,7 @@ OpenClaw 支持 Anthropic 的提示缓存功能。这是**仅限 API**；订阅
|
||||
agents: {
|
||||
defaults: {
|
||||
models: {
|
||||
"anthropic/claude-opus-4-5": {
|
||||
"anthropic/claude-opus-4-6": {
|
||||
params: { cacheRetention: "long" },
|
||||
},
|
||||
},
|
||||
@ -72,88 +109,157 @@ OpenClaw 支持 Anthropic 的提示缓存功能。这是**仅限 API**；订阅
|
||||
|
||||
### 默认值
|
||||
|
||||
使用 Anthropic API 密钥认证时，OpenClaw 会自动为所有 Anthropic 模型应用 `cacheRetention: "short"`（5 分钟缓存）。你可以通过在配置中显式设置 `cacheRetention` 来覆盖此设置。
|
||||
当使用 Anthropic API 密钥身份验证时，OpenClaw 会自动对所有 Anthropic 模型应用 `cacheRetention: "short"`（5 分钟缓存）。你可以通过在配置中显式设置 `cacheRetention` 来覆盖此行为。
|
||||
|
||||
### 每个智能体的 cacheRetention 覆盖
|
||||
|
||||
将模型级参数用作基线，然后通过 `agents.list[].params` 覆盖特定智能体。
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "anthropic/claude-opus-4-6" },
|
||||
models: {
|
||||
"anthropic/claude-opus-4-6": {
|
||||
params: { cacheRetention: "long" }, // 大多数智能体的基线
|
||||
},
|
||||
},
|
||||
},
|
||||
list: [
|
||||
{ id: "research", default: true },
|
||||
{ id: "alerts", params: { cacheRetention: "none" } }, // 仅对该智能体覆盖
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
与缓存相关参数的配置合并顺序：
|
||||
|
||||
1. `agents.defaults.models["provider/model"].params`
|
||||
2. `agents.list[].params`（匹配 `id`，按键覆盖）
|
||||
|
||||
这使得一个智能体可以保留长生命周期缓存，而同一模型上的另一个智能体可以禁用缓存，以避免在突发/低复用流量上产生写入成本。
|
||||
|
||||
### Bedrock Claude 说明
|
||||
|
||||
- 当已配置时，Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）接受透传的 `cacheRetention`。
|
||||
- 非 Anthropic 的 Bedrock 模型会在运行时被强制设置为 `cacheRetention: "none"`。
|
||||
- 当未设置显式值时，Anthropic API 密钥的智能默认值也会为 Bedrock 上的 Claude 模型引用填入 `cacheRetention: "short"`。
|
||||
|
||||
### 旧版参数
|
||||
|
||||
为了向后兼容，仍支持旧版 `cacheControlTtl` 参数：
|
||||
旧的 `cacheControlTtl` 参数仍受支持，以保持向后兼容：
|
||||
|
||||
- `"5m"` 映射到 `short`
|
||||
- `"1h"` 映射到 `long`
|
||||
- `"5m"` 映射为 `short`
|
||||
- `"1h"` 映射为 `long`
|
||||
|
||||
我们建议迁移到新的 `cacheRetention` 参数。
|
||||
|
||||
OpenClaw 在 Anthropic API 请求中包含 `extended-cache-ttl-2025-04-11` beta 标志；
|
||||
如果你覆盖提供商头信息，请保留它（参见 [/gateway/configuration](/gateway/configuration)）。
|
||||
OpenClaw 会在 Anthropic API 请求中包含 `extended-cache-ttl-2025-04-11` beta 标志；
|
||||
如果你覆盖了提供商请求头，请保留它（参见 [/gateway/configuration](/gateway/configuration)）。
|
||||
|
||||
## 1M 上下文窗口（Anthropic beta）
|
||||
|
||||
Anthropic 的 1M 上下文窗口受 beta 门控。在 OpenClaw 中，可通过为受支持的 Opus/Sonnet 模型
|
||||
设置 `params.context1m: true` 按模型启用。
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
models: {
|
||||
"anthropic/claude-opus-4-6": {
|
||||
params: { context1m: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw 会将其映射为 Anthropic 请求上的 `anthropic-beta: context-1m-2025-08-07`。
|
||||
|
||||
仅当该模型的 `params.context1m` 被显式设置为 `true` 时，
|
||||
此功能才会激活。
|
||||
|
||||
要求：Anthropic 必须允许该凭证使用长上下文
|
||||
（通常是 API 密钥计费，或启用了 Extra Usage 的订阅账户）。
|
||||
否则 Anthropic 会返回：
|
||||
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。
|
||||
|
||||
注意：Anthropic 当前在使用
|
||||
OAuth/订阅令牌（`sk-ant-oat-*`）时会拒绝 `context-1m-*` beta 请求。OpenClaw 会自动跳过
|
||||
OAuth 身份验证的 `context1m` beta 请求头，并保留所需的 OAuth beta 标志。
|
||||
|
||||
## 选项 B：Claude setup-token
|
||||
|
||||
**适用于：** 使用你的 Claude 订阅。
|
||||
**最适合：** 使用你的 Claude 订阅。
|
||||
|
||||
### 在哪里获取 setup-token
|
||||
### 如何获取 setup-token
|
||||
|
||||
setup-token 由 **Claude Code CLI** 创建，而不是 Anthropic Console。你可以在**任何机器**上运行：
|
||||
setup-token 由 **Claude Code CLI** 创建，而不是在 Anthropic Console 中创建。你可以在**任何机器**上运行：
|
||||
|
||||
```bash
|
||||
claude setup-token
|
||||
```
|
||||
|
||||
将令牌粘贴到 OpenClaw（向导：**Anthropic token (paste setup-token)**），或在 Gateway 网关主机上运行：
|
||||
将该令牌粘贴到 OpenClaw 中（向导：**Anthropic token（粘贴 setup-token）**），或在 Gateway 网关主机上运行：
|
||||
|
||||
```bash
|
||||
openclaw models auth setup-token --provider anthropic
|
||||
```
|
||||
|
||||
如果你在不同的机器上生成了令牌，请粘贴它：
|
||||
如果你是在另一台机器上生成该令牌，请粘贴它：
|
||||
|
||||
```bash
|
||||
openclaw models auth paste-token --provider anthropic
|
||||
```
|
||||
|
||||
### CLI 设置
|
||||
### CLI 设置（setup-token）
|
||||
|
||||
```bash
|
||||
# 在新手引导期间粘贴 setup-token
|
||||
# Paste a setup-token during setup
|
||||
openclaw onboard --auth-choice setup-token
|
||||
```
|
||||
|
||||
### 配置片段
|
||||
### 配置片段（setup-token）
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
|
||||
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
## 说明
|
||||
|
||||
- 使用 `claude setup-token` 生成 setup-token 并粘贴，或在 Gateway 网关主机上运行 `openclaw models auth setup-token`。
|
||||
- 如果你在 Claude 订阅上看到"OAuth token refresh failed …"，请使用 setup-token 重新认证。参见 [/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription](/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription)。
|
||||
- 认证详情 + 重用规则在 [/concepts/oauth](/concepts/oauth)。
|
||||
- 使用 `claude setup-token` 生成 setup-token 并粘贴它，或者在 Gateway 网关主机上运行 `openclaw models auth setup-token`。
|
||||
- 如果你在 Claude 订阅上看到 “OAuth token refresh failed …”，请使用 setup-token 重新进行身份验证。请参见 [/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription](/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription)。
|
||||
- 身份验证详情和复用规则见 [/concepts/oauth](/concepts/oauth)。
|
||||
|
||||
## 故障排除
|
||||
|
||||
**401 错误/令牌突然失效**
|
||||
**401 错误 / 令牌突然无效**
|
||||
|
||||
- Claude 订阅认证可能过期或被撤销。重新运行 `claude setup-token`
|
||||
并将其粘贴到 **Gateway 网关主机**。
|
||||
- 如果 Claude CLI 登录在不同的机器上，在 Gateway 网关主机上使用
|
||||
- Claude 订阅身份验证可能会过期或被撤销。请重新运行 `claude setup-token`，
|
||||
并将其粘贴到 **Gateway 网关主机** 上。
|
||||
- 如果 Claude CLI 登录位于另一台机器上，请在 Gateway 网关主机上使用
|
||||
`openclaw models auth paste-token --provider anthropic`。
|
||||
|
||||
**No API key found for provider "anthropic"**
|
||||
|
||||
- 认证是**按智能体**的。新智能体不会继承主智能体的密钥。
|
||||
- 为该智能体重新运行新手引导，或在 Gateway 网关主机上粘贴 setup-token / API 密钥，
|
||||
然后使用 `openclaw models status` 验证。
|
||||
- 身份验证是**按智能体**区分的。新智能体不会继承主智能体的密钥。
|
||||
- 请为该智能体重新运行新手引导，或在
|
||||
Gateway 网关主机上粘贴 setup-token / API 密钥，然后使用 `openclaw models status` 验证。
|
||||
|
||||
**No credentials found for profile `anthropic:default`**
|
||||
|
||||
- 运行 `openclaw models status` 查看哪个认证配置文件处于活动状态。
|
||||
- 重新运行新手引导，或为该配置文件粘贴 setup-token / API 密钥。
|
||||
- 运行 `openclaw models status` 查看当前活动的 auth profile。
|
||||
- 重新运行新手引导，或为该配置档案粘贴 setup-token / API 密钥。
|
||||
|
||||
**No available auth profile (all in cooldown/unavailable)**
|
||||
|
||||
- 检查 `openclaw models status --json` 中的 `auth.unusableProfiles`。
|
||||
- 添加另一个 Anthropic 配置文件或等待冷却期结束。
|
||||
- 添加另一个 Anthropic 配置档案，或等待冷却结束。
|
||||
|
||||
更多信息：[/gateway/troubleshooting](/gateway/troubleshooting) 和 [/help/faq](/help/faq)。
|
||||
|
||||
78
docs/zh-CN/providers/cloudflare-ai-gateway.md
Normal file
78
docs/zh-CN/providers/cloudflare-ai-gateway.md
Normal file
@ -0,0 +1,78 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想将 Cloudflare AI Gateway 与 OpenClaw 一起使用
|
||||
- 你需要 account ID、gateway ID 或 API key 环境变量
|
||||
summary: Cloudflare AI Gateway 设置（认证 + 模型选择）
|
||||
title: Cloudflare AI Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-03-16T06:25:05Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: db77652c37652ca20f7c50f32382dbaeaeb50ea5bdeaf1d4fd17dc394e58950c
|
||||
source_path: providers/cloudflare-ai-gateway.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Cloudflare AI Gateway
|
||||
|
||||
Cloudflare AI Gateway 位于提供商 API 前方，让你能够添加分析、缓存和控制功能。对于 Anthropic，OpenClaw 会通过你的 Gateway 端点使用 Anthropic Messages API。
|
||||
|
||||
- 提供商：`cloudflare-ai-gateway`
|
||||
- Base URL：`https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic`
|
||||
- 默认模型：`cloudflare-ai-gateway/claude-sonnet-4-5`
|
||||
- API key：`CLOUDFLARE_AI_GATEWAY_API_KEY`（你用于通过 Gateway 发起请求的提供商 API key）
|
||||
|
||||
对于 Anthropic 模型，请使用你的 Anthropic API key。
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. 设置提供商 API key 和 Gateway 详细信息：
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice cloudflare-ai-gateway-api-key
|
||||
```
|
||||
|
||||
2. 设置默认模型：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "cloudflare-ai-gateway/claude-sonnet-4-5" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 非交互式示例
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice cloudflare-ai-gateway-api-key \
|
||||
--cloudflare-ai-gateway-account-id "your-account-id" \
|
||||
--cloudflare-ai-gateway-gateway-id "your-gateway-id" \
|
||||
--cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY"
|
||||
```
|
||||
|
||||
## 已认证的 Gateway
|
||||
|
||||
如果你在 Cloudflare 中启用了 Gateway 认证，请添加 `cf-aig-authorization` header（这是在你的提供商 API key 之外额外添加的）。
|
||||
|
||||
```json5
|
||||
{
|
||||
models: {
|
||||
providers: {
|
||||
"cloudflare-ai-gateway": {
|
||||
headers: {
|
||||
"cf-aig-authorization": "Bearer <cloudflare-ai-gateway-token>",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 环境说明
|
||||
|
||||
如果 Gateway 作为守护进程运行（launchd/systemd），请确保 `CLOUDFLARE_AI_GATEWAY_API_KEY` 对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。
|
||||
@ -1,26 +1,37 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在 OpenClaw 中使用 GLM 模型
|
||||
- 你需要了解模型命名规范和设置方法
|
||||
summary: GLM 模型系列概述 + 如何在 OpenClaw 中使用
|
||||
title: GLM 模型
|
||||
- 你需要了解模型命名约定和设置方法
|
||||
summary: GLM 模型家族概览 + 如何在 OpenClaw 中使用
|
||||
title: GLM Models
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:34:53Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 2d7b457f033f26f28c230a9cd2310151f825fc52c3ee4fb814d08fd2d022d041
|
||||
generated_at: "2026-03-16T06:25:10Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 061254ebeedec7285d9c0c6e88145f89184ad4ab8d8d6132f1d692c7d3ca03a2
|
||||
source_path: providers/glm.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# GLM 模型
|
||||
|
||||
GLM 是一个**模型系列**（而非公司），通过 Z.AI 平台提供。在 OpenClaw 中，GLM 模型通过 `zai` 提供商访问，模型 ID 格式如 `zai/glm-4.7`。
|
||||
GLM 是一个**模型家族**（不是公司），可通过 Z.AI 平台使用。在 OpenClaw 中，GLM
|
||||
模型通过 `zai` 提供商访问，模型 ID 形式如 `zai/glm-5`。
|
||||
|
||||
## CLI 设置
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice zai-api-key
|
||||
# Coding Plan Global，推荐给 Coding Plan 用户
|
||||
openclaw onboard --auth-choice zai-coding-global
|
||||
|
||||
# Coding Plan CN（中国区域），推荐给 Coding Plan 用户
|
||||
openclaw onboard --auth-choice zai-coding-cn
|
||||
|
||||
# 通用 API
|
||||
openclaw onboard --auth-choice zai-global
|
||||
|
||||
# 通用 API CN（中国区域）
|
||||
openclaw onboard --auth-choice zai-cn
|
||||
```
|
||||
|
||||
## 配置片段
|
||||
@ -28,12 +39,12 @@ openclaw onboard --auth-choice zai-api-key
|
||||
```json5
|
||||
{
|
||||
env: { ZAI_API_KEY: "sk-..." },
|
||||
agents: { defaults: { model: { primary: "zai/glm-4.7" } } },
|
||||
agents: { defaults: { model: { primary: "zai/glm-5" } } },
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
## 说明
|
||||
|
||||
- GLM 版本和可用性可能会变化；请查阅 Z.AI 的文档获取最新信息。
|
||||
- 示例模型 ID 包括 `glm-4.7` 和 `glm-4.6`。
|
||||
- 有关提供商的详细信息，请参阅 [/providers/zai](/providers/zai)。
|
||||
- GLM 版本和可用性可能会变化；请查看 Z.AI 的文档以获取最新信息。
|
||||
- 示例模型 ID 包括 `glm-5`、`glm-4.7` 和 `glm-4.6`。
|
||||
- 关于提供商详情，请参阅 [/providers/zai](/providers/zai)。
|
||||
|
||||
216
docs/zh-CN/providers/huggingface.md
Normal file
216
docs/zh-CN/providers/huggingface.md
Normal file
@ -0,0 +1,216 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想将 Hugging Face Inference 与 OpenClaw 一起使用
|
||||
- 你需要 HF token 环境变量或 CLI 认证选项
|
||||
summary: Hugging Face Inference 设置（认证 + 模型选择）
|
||||
title: Hugging Face（Inference）
|
||||
x-i18n:
|
||||
generated_at: "2026-03-16T06:25:40Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e62b74915c9a26ab21954abcd9c03442cdd2133fba3371ddb9bcfc3a3458a002
|
||||
source_path: providers/huggingface.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Hugging Face（Inference）
|
||||
|
||||
[Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers) 通过单一路由器 API 提供与 OpenAI 兼容的 chat completions。你只需一个 token，即可访问许多模型（DeepSeek、Llama 等）。OpenClaw 使用 **OpenAI 兼容端点**（仅 chat completions）；如果要使用 text-to-image、embeddings 或 speech，请直接使用 [HF inference clients](https://huggingface.co/docs/api-inference/quicktour)。
|
||||
|
||||
- 提供商：`huggingface`
|
||||
- 认证：`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`（带有 **Make calls to Inference Providers** 权限的细粒度 token）
|
||||
- API：OpenAI 兼容（`https://router.huggingface.co/v1`）
|
||||
- 计费：单个 HF token；[定价](https://huggingface.co/docs/inference-providers/pricing) 按提供商费率执行，并带有免费层。
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. 在 [Hugging Face → Settings → Tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained) 创建一个细粒度 token，并授予 **Make calls to Inference Providers** 权限。
|
||||
2. 运行新手引导，并在提供商下拉菜单中选择 **Hugging Face**，然后在提示时输入你的 API key：
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice huggingface-api-key
|
||||
```
|
||||
|
||||
3. 在 **Default Hugging Face model** 下拉菜单中，选择你想使用的模型（当你有有效 token 时，列表会从 Inference API 加载；否则会显示内置列表）。你的选择会保存为默认模型。
|
||||
4. 你也可以稍后在配置中设置或更改默认模型：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 非交互式示例
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice huggingface-api-key \
|
||||
--huggingface-api-key "$HF_TOKEN"
|
||||
```
|
||||
|
||||
这会将 `huggingface/deepseek-ai/DeepSeek-R1` 设置为默认模型。
|
||||
|
||||
## 环境说明
|
||||
|
||||
如果 Gateway 网关作为守护进程运行（launchd/systemd），请确保 `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`
|
||||
对此进程可用（例如放在 `~/.openclaw/.env` 中，或通过
|
||||
`env.shellEnv` 提供）。
|
||||
|
||||
## 模型发现和新手引导下拉菜单
|
||||
|
||||
OpenClaw 通过直接调用 **Inference 端点** 来发现模型：
|
||||
|
||||
```bash
|
||||
GET https://router.huggingface.co/v1/models
|
||||
```
|
||||
|
||||
（可选：发送 `Authorization: Bearer $HUGGINGFACE_HUB_TOKEN` 或 `$HF_TOKEN` 以获取完整列表；某些端点在未认证时只返回子集。）响应采用 OpenAI 风格：`{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }`。
|
||||
|
||||
当你配置 Hugging Face API key 时（通过新手引导、`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`），OpenClaw 会使用这个 GET 请求来发现可用的 chat-completion 模型。在**交互式设置**期间，你输入 token 后会看到一个 **Default Hugging Face model** 下拉菜单，其内容来自该列表（如果请求失败，则使用内置目录）。在运行时（例如 Gateway 网关启动时），只要存在 key，OpenClaw 就会再次调用 **GET** `https://router.huggingface.co/v1/models` 来刷新目录。该列表会与内置目录合并（以补充上下文窗口和成本等元数据）。如果请求失败或未设置 key，则只使用内置目录。
|
||||
|
||||
## 模型名称和可编辑选项
|
||||
|
||||
- **来自 API 的名称：** 当 API 返回 `name`、`title` 或 `display_name` 时，模型显示名称会从 **GET /v1/models** 中补全；否则会从模型 id 推导（例如 `deepseek-ai/DeepSeek-R1` → “DeepSeek R1”）。
|
||||
- **覆盖显示名称：** 你可以在配置中为每个模型设置自定义标签，使其在 CLI 和 UI 中按你希望的方式显示：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
models: {
|
||||
"huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
|
||||
"huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- **提供商 / 策略选择：** 在**模型 id** 后附加后缀，以选择路由器如何挑选后端：
|
||||
- **`:fastest`** — 最高吞吐量（由路由器选择；提供商选择会被**锁定** —— 不会显示交互式后端选择器）。
|
||||
- **`:cheapest`** — 每输出 token 成本最低（由路由器选择；提供商选择会被**锁定**）。
|
||||
- **`:provider`** — 强制使用特定后端（例如 `:sambanova`、`:together`）。
|
||||
|
||||
当你选择 **:cheapest** 或 **:fastest** 时（例如在新手引导的模型下拉菜单中），提供商会被锁定：路由器会按成本或速度决定，不会显示可选的“偏好特定后端”步骤。你可以将这些作为单独条目添加到 `models.providers.huggingface.models` 中，或为 `model.primary` 设置带后缀的值。你也可以在 [Inference Provider settings](https://hf.co/settings/inference-providers) 中设置默认顺序（无后缀 = 使用该顺序）。
|
||||
|
||||
- **配置合并：** 当配置被合并时，`models.providers.huggingface.models` 中已有的条目（例如在 `models.json` 中）会被保留。因此，你在其中设置的任何自定义 `name`、`alias` 或模型选项都会保留。
|
||||
|
||||
## 模型 ID 和配置示例
|
||||
|
||||
模型引用使用 `huggingface/<org>/<model>` 形式（Hub 风格 ID）。下面的列表来自 **GET** `https://router.huggingface.co/v1/models`；你的目录中可能包含更多内容。
|
||||
|
||||
**示例 ID（来自 inference 端点）：**
|
||||
|
||||
| 模型 | 引用（加上 `huggingface/` 前缀） |
|
||||
| ---------------------- | ----------------------------------- |
|
||||
| DeepSeek R1 | `deepseek-ai/DeepSeek-R1` |
|
||||
| DeepSeek V3.2 | `deepseek-ai/DeepSeek-V3.2` |
|
||||
| Qwen3 8B | `Qwen/Qwen3-8B` |
|
||||
| Qwen2.5 7B Instruct | `Qwen/Qwen2.5-7B-Instruct` |
|
||||
| Qwen3 32B | `Qwen/Qwen3-32B` |
|
||||
| Llama 3.3 70B Instruct | `meta-llama/Llama-3.3-70B-Instruct` |
|
||||
| Llama 3.1 8B Instruct | `meta-llama/Llama-3.1-8B-Instruct` |
|
||||
| GPT-OSS 120B | `openai/gpt-oss-120b` |
|
||||
| GLM 4.7 | `zai-org/GLM-4.7` |
|
||||
| Kimi K2.5 | `moonshotai/Kimi-K2.5` |
|
||||
|
||||
你可以在模型 id 后附加 `:fastest`、`:cheapest` 或 `:provider`（例如 `:together`、`:sambanova`）。请在 [Inference Provider settings](https://hf.co/settings/inference-providers) 中设置默认顺序；完整列表请参阅 [Inference Providers](https://huggingface.co/docs/inference-providers) 和 **GET** `https://router.huggingface.co/v1/models`。
|
||||
|
||||
### 完整配置示例
|
||||
|
||||
**以 DeepSeek R1 为主模型，Qwen 作为回退：**
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "huggingface/deepseek-ai/DeepSeek-R1",
|
||||
fallbacks: ["huggingface/Qwen/Qwen3-8B"],
|
||||
},
|
||||
models: {
|
||||
"huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
|
||||
"huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**以 Qwen 为默认模型，并包含 `:cheapest` 和 `:fastest` 变体：**
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "huggingface/Qwen/Qwen3-8B" },
|
||||
models: {
|
||||
"huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
|
||||
"huggingface/Qwen/Qwen3-8B:cheapest": { alias: "Qwen3 8B（最便宜）" },
|
||||
"huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B（最快）" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**带有别名的 DeepSeek + Llama + GPT-OSS：**
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "huggingface/deepseek-ai/DeepSeek-V3.2",
|
||||
fallbacks: [
|
||||
"huggingface/meta-llama/Llama-3.3-70B-Instruct",
|
||||
"huggingface/openai/gpt-oss-120b",
|
||||
],
|
||||
},
|
||||
models: {
|
||||
"huggingface/deepseek-ai/DeepSeek-V3.2": { alias: "DeepSeek V3.2" },
|
||||
"huggingface/meta-llama/Llama-3.3-70B-Instruct": { alias: "Llama 3.3 70B" },
|
||||
"huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**使用 `:provider` 强制指定特定后端：**
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "huggingface/deepseek-ai/DeepSeek-R1:together" },
|
||||
models: {
|
||||
"huggingface/deepseek-ai/DeepSeek-R1:together": { alias: "DeepSeek R1 (Together)" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**多个 Qwen 和 DeepSeek 模型，带策略后缀：**
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest" },
|
||||
models: {
|
||||
"huggingface/Qwen/Qwen2.5-7B-Instruct": { alias: "Qwen2.5 7B" },
|
||||
"huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest": { alias: "Qwen2.5 7B（便宜）" },
|
||||
"huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1（快速）" },
|
||||
"huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
@ -1,41 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想选择一个模型提供商
|
||||
- 你需要快速了解支持的 LLM 后端
|
||||
- 你需要支持的 LLM 后端的快速概览
|
||||
summary: OpenClaw 支持的模型提供商（LLM）
|
||||
title: 模型提供商
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:53:32Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: eb4a97438adcf610499253afcf8b2af6624f4be098df389a6c3746f14c4a901b
|
||||
generated_at: "2026-03-16T06:25:28Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 1d7ba79fd152a978e6eb3b8f8d5dfc44cebba77d2c74dc3892aae917d32ad2ee
|
||||
source_path: providers/index.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 模型提供商
|
||||
|
||||
OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，进行认证，然后将默认模型设置为 `provider/model`。
|
||||
OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份验证，然后将
|
||||
默认模型设置为 `provider/model`。
|
||||
|
||||
正在寻找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）等）？参见[渠道](/channels)。
|
||||
|
||||
## 亮点：Venice（Venice AI）
|
||||
|
||||
Venice 是我们推荐的 Venice AI 设置，用于隐私优先的推理，并可选择使用 Opus 处理困难任务。
|
||||
|
||||
- 默认：`venice/llama-3.3-70b`
|
||||
- 最佳综合：`venice/claude-opus-45`（Opus 仍然是最强的）
|
||||
|
||||
参见 [Venice AI](/providers/venice)。
|
||||
在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/等）？请参见 [Channels](/channels)。
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. 与提供商进行认证（通常通过 `openclaw onboard`）。
|
||||
1. 使用该提供商进行身份验证（通常通过 `openclaw onboard`）。
|
||||
2. 设置默认模型：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
|
||||
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
|
||||
}
|
||||
```
|
||||
|
||||
@ -43,15 +35,25 @@ Venice 是我们推荐的 Venice AI 设置，用于隐私优先的推理，并
|
||||
|
||||
- [Amazon Bedrock](/providers/bedrock)
|
||||
- [Anthropic（API + Claude Code CLI）](/providers/anthropic)
|
||||
- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
|
||||
- [GLM 模型](/providers/glm)
|
||||
- [Hugging Face（Inference）](/providers/huggingface)
|
||||
- [Kilocode](/providers/kilocode)
|
||||
- [LiteLLM（统一网关）](/providers/litellm)
|
||||
- [MiniMax](/providers/minimax)
|
||||
- [Mistral](/providers/mistral)
|
||||
- [Moonshot AI（Kimi + Kimi Coding）](/providers/moonshot)
|
||||
- [Ollama（本地模型）](/providers/ollama)
|
||||
- [NVIDIA](/providers/nvidia)
|
||||
- [Ollama（云端 + 本地模型）](/providers/ollama)
|
||||
- [OpenAI（API + Codex）](/providers/openai)
|
||||
- [OpenCode Zen](/providers/opencode)
|
||||
- [OpenCode（Zen + Go）](/providers/opencode)
|
||||
- [OpenRouter](/providers/openrouter)
|
||||
- [Qianfan](/providers/qianfan)
|
||||
- [Qwen（OAuth）](/providers/qwen)
|
||||
- [Together AI](/providers/together)
|
||||
- [Vercel AI Gateway](/providers/vercel-ai-gateway)
|
||||
- [Venice（Venice AI，注重隐私）](/providers/venice)
|
||||
- [vLLM（本地模型）](/providers/vllm)
|
||||
- [Xiaomi](/providers/xiaomi)
|
||||
- [Z.AI](/providers/zai)
|
||||
|
||||
@ -61,7 +63,7 @@ Venice 是我们推荐的 Venice AI 设置，用于隐私优先的推理，并
|
||||
|
||||
## 社区工具
|
||||
|
||||
- [Claude Max API Proxy](/providers/claude-max-api-proxy) - 将 Claude Max/Pro 订阅作为 OpenAI 兼容的 API 端点使用
|
||||
- [Claude Max API Proxy](/providers/claude-max-api-proxy) - 面向 Claude 订阅凭证的社区代理（使用前请核实 Anthropic 政策/条款）
|
||||
|
||||
有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，
|
||||
参见[模型提供商](/concepts/model-providers)。
|
||||
请参见 [模型提供商](/concepts/model-providers)。
|
||||
|
||||
80
docs/zh-CN/providers/kilocode.md
Normal file
80
docs/zh-CN/providers/kilocode.md
Normal file
@ -0,0 +1,80 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想用一个 API 密钥访问多种 LLM
|
||||
- 你想在 OpenClaw 中通过 Kilo Gateway 运行模型
|
||||
summary: 使用 Kilo Gateway 的统一 API 在 OpenClaw 中访问多种模型
|
||||
x-i18n:
|
||||
generated_at: "2026-03-16T06:25:35Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: acd4c29496abc1ef8d4da6c48575763dfe3b4c1319874f900532223ac3775257
|
||||
source_path: providers/kilocode.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Kilo Gateway
|
||||
|
||||
Kilo Gateway 提供一个**统一 API**，可通过单一
|
||||
端点和 API 密钥将请求路由到多种模型。它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换基础 URL 即可使用。
|
||||
|
||||
## 获取 API 密钥
|
||||
|
||||
1. 前往 [app.kilo.ai](https://app.kilo.ai)
|
||||
2. 登录或创建账户
|
||||
3. 进入 API Keys 并生成一个新密钥
|
||||
|
||||
## CLI 设置
|
||||
|
||||
```bash
|
||||
openclaw onboard --kilocode-api-key <key>
|
||||
```
|
||||
|
||||
或者设置环境变量：
|
||||
|
||||
```bash
|
||||
export KILOCODE_API_KEY="<your-kilocode-api-key>" # pragma: allowlist secret
|
||||
```
|
||||
|
||||
## 配置片段
|
||||
|
||||
```json5
|
||||
{
|
||||
env: { KILOCODE_API_KEY: "<your-kilocode-api-key>" }, // pragma: allowlist secret
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "kilocode/kilo/auto" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 默认模型
|
||||
|
||||
默认模型是 `kilocode/kilo/auto`，这是一个智能路由模型，会根据任务自动选择
|
||||
最佳的底层模型：
|
||||
|
||||
- 规划、调试和编排任务会路由到 Claude Opus
|
||||
- 代码编写和探索任务会路由到 Claude Sonnet
|
||||
|
||||
## 可用模型
|
||||
|
||||
OpenClaw 会在启动时从 Kilo Gateway 动态发现可用模型。使用
|
||||
`/models kilocode` 查看你的账户可用的完整模型列表。
|
||||
|
||||
Gateway 网关上任何可用的模型都可以使用 `kilocode/` 前缀：
|
||||
|
||||
```
|
||||
kilocode/kilo/auto (default - smart routing)
|
||||
kilocode/anthropic/claude-sonnet-4
|
||||
kilocode/openai/gpt-5.2
|
||||
kilocode/google/gemini-3-pro-preview
|
||||
...and many more
|
||||
```
|
||||
|
||||
## 说明
|
||||
|
||||
- 模型引用格式为 `kilocode/<model-id>`（例如 `kilocode/anthropic/claude-sonnet-4`）。
|
||||
- 默认模型：`kilocode/kilo/auto`
|
||||
- 基础 URL：`https://api.kilo.ai/api/gateway/`
|
||||
- 更多模型/提供商选项，请参见 [/concepts/model-providers](/concepts/model-providers)。
|
||||
- Kilo Gateway 在底层使用带有你的 API 密钥的 Bearer token。
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
x
Reference in New Issue
Block a user