diff --git a/docs/hooks.md b/docs/automation/hooks.md similarity index 99% rename from docs/hooks.md rename to docs/automation/hooks.md index dfcd61ca10..e842b8c58e 100644 --- a/docs/hooks.md +++ b/docs/automation/hooks.md @@ -17,7 +17,7 @@ Hooks are small scripts that run when something happens. There are two kinds: - **Hooks** (this page): run inside the Gateway when agent events fire, like `/new`, `/reset`, `/stop`, or lifecycle events. - **Webhooks**: external HTTP webhooks that let other systems trigger work in OpenClaw. See [Webhook Hooks](/automation/webhook) or use `openclaw webhooks` for Gmail helper commands. -Hooks can also be bundled inside plugins; see [Plugins](/plugin#plugin-hooks). +Hooks can also be bundled inside plugins; see [Plugins](/tools/plugin#plugin-hooks). Common uses: diff --git a/docs/channels/bluebubbles.md b/docs/channels/bluebubbles.md index 1b43240875..ab852e9821 100644 --- a/docs/channels/bluebubbles.md +++ b/docs/channels/bluebubbles.md @@ -18,7 +18,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R - OpenClaw talks to it through its REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`). - Incoming messages arrive via webhooks; outgoing replies, typing indicators, read receipts, and tapbacks are REST calls. - Attachments and stickers are ingested as inbound media (and surfaced to the agent when possible). -- Pairing/allowlist works the same way as other channels (`/start/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes. +- Pairing/allowlist works the same way as other channels (`/channels/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes. - Reactions are surfaced as system events just like Slack/Telegram so agents can "mention" them before replying. - Advanced features: edit, unsend, reply threading, message effects, group management. @@ -149,7 +149,7 @@ DMs: - Approve via: - `openclaw pairing list bluebubbles` - `openclaw pairing approve bluebubbles ` -- Pairing is the default token exchange. Details: [Pairing](/start/pairing) +- Pairing is the default token exchange. Details: [Pairing](/channels/pairing) Groups: @@ -337,4 +337,4 @@ Prefer `chat_guid` for stable routing: - OpenClaw auto-hides known-broken actions based on the BlueBubbles server's macOS version. If edit still appears on macOS 26 (Tahoe), disable it manually with `channels.bluebubbles.actions.edit=false`. - For status/health info: `openclaw status --all` or `openclaw status --deep`. -For general channel workflow reference, see [Channels](/channels) and the [Plugins](/plugin) guide. +For general channel workflow reference, see [Channels](/channels) and the [Plugins](/tools/plugin) guide. diff --git a/docs/broadcast-groups.md b/docs/channels/broadcast-groups.md similarity index 98% rename from docs/broadcast-groups.md rename to docs/channels/broadcast-groups.md index eb1b10ce7e..2d47d7c594 100644 --- a/docs/broadcast-groups.md +++ b/docs/channels/broadcast-groups.md @@ -437,6 +437,6 @@ Planned features: ## See Also -- [Multi-Agent Configuration](/multi-agent-sandbox-tools) -- [Routing Configuration](/concepts/channel-routing) +- [Multi-Agent Configuration](/tools/multi-agent-sandbox-tools) +- [Routing Configuration](/channels/channel-routing) - [Session Management](/concepts/sessions) diff --git a/docs/concepts/channel-routing.md b/docs/channels/channel-routing.md similarity index 98% rename from docs/concepts/channel-routing.md rename to docs/channels/channel-routing.md index 9ecdb8f741..6ee1945391 100644 --- a/docs/concepts/channel-routing.md +++ b/docs/channels/channel-routing.md @@ -68,7 +68,7 @@ Config: } ``` -See: [Broadcast Groups](/broadcast-groups). +See: [Broadcast Groups](/channels/broadcast-groups). ## Config overview diff --git a/docs/concepts/group-messages.md b/docs/channels/group-messages.md similarity index 100% rename from docs/concepts/group-messages.md rename to docs/channels/group-messages.md diff --git a/docs/concepts/groups.md b/docs/channels/groups.md similarity index 99% rename from docs/concepts/groups.md rename to docs/channels/groups.md index 635211d336..d2497148b2 100644 --- a/docs/concepts/groups.md +++ b/docs/channels/groups.md @@ -371,4 +371,4 @@ The agent system prompt includes a group intro on the first turn of a new group ## WhatsApp specifics -See [Group messages](/concepts/group-messages) for WhatsApp-only behavior (history injection, mention handling details). +See [Group messages](/channels/group-messages) for WhatsApp-only behavior (history injection, mention handling details). diff --git a/docs/channels/imessage.md b/docs/channels/imessage.md index 080d3cb87a..c4fa867f1b 100644 --- a/docs/channels/imessage.md +++ b/docs/channels/imessage.md @@ -224,7 +224,7 @@ DMs: - Approve via: - `openclaw pairing list imessage` - `openclaw pairing approve imessage ` -- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/start/pairing) +- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/channels/pairing) Groups: diff --git a/docs/channels/index.md b/docs/channels/index.md index 844af27505..23bf98915f 100644 --- a/docs/channels/index.md +++ b/docs/channels/index.md @@ -39,7 +39,7 @@ Text is supported everywhere; media and reactions vary by channel. - Channels can run simultaneously; configure multiple and OpenClaw will route per chat. - Fastest setup is usually **Telegram** (simple bot token). WhatsApp requires QR pairing and stores more state on disk. -- Group behavior varies by channel; see [Groups](/concepts/groups). +- Group behavior varies by channel; see [Groups](/channels/groups). - DM pairing and allowlists are enforced for safety; see [Security](/gateway/security). - Telegram internals: [grammY notes](/channels/grammy). - Troubleshooting: [Channel troubleshooting](/channels/troubleshooting). diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md index 86e25ee9bc..68a5ac5050 100644 --- a/docs/channels/matrix.md +++ b/docs/channels/matrix.md @@ -34,7 +34,7 @@ openclaw plugins install ./extensions/matrix If you choose Matrix during configure/onboarding and a git checkout is detected, OpenClaw will offer the local install path automatically. -Details: [Plugins](/plugin) +Details: [Plugins](/tools/plugin) ## Setup diff --git a/docs/channels/mattermost.md b/docs/channels/mattermost.md index 8958f5b5b7..f4353180e2 100644 --- a/docs/channels/mattermost.md +++ b/docs/channels/mattermost.md @@ -31,7 +31,7 @@ openclaw plugins install ./extensions/mattermost If you choose Mattermost during configure/onboarding and a git checkout is detected, OpenClaw will offer the local install path automatically. -Details: [Plugins](/plugin) +Details: [Plugins](/tools/plugin) ## Quick setup diff --git a/docs/channels/msteams.md b/docs/channels/msteams.md index 572ff1284a..7729ca62a5 100644 --- a/docs/channels/msteams.md +++ b/docs/channels/msteams.md @@ -36,7 +36,7 @@ openclaw plugins install ./extensions/msteams If you choose Teams during configure/onboarding and a git checkout is detected, OpenClaw will offer the local install path automatically. -Details: [Plugins](/plugin) +Details: [Plugins](/tools/plugin) ## Quick setup (beginner) diff --git a/docs/channels/nextcloud-talk.md b/docs/channels/nextcloud-talk.md index efecfd9900..d4ab9e2c39 100644 --- a/docs/channels/nextcloud-talk.md +++ b/docs/channels/nextcloud-talk.md @@ -28,7 +28,7 @@ openclaw plugins install ./extensions/nextcloud-talk If you choose Nextcloud Talk during configure/onboarding and a git checkout is detected, OpenClaw will offer the local install path automatically. -Details: [Plugins](/plugin) +Details: [Plugins](/tools/plugin) ## Quick setup (beginner) diff --git a/docs/start/pairing.md b/docs/channels/pairing.md similarity index 100% rename from docs/start/pairing.md rename to docs/channels/pairing.md diff --git a/docs/channels/signal.md b/docs/channels/signal.md index 72abe2f28d..df4d630cc5 100644 --- a/docs/channels/signal.md +++ b/docs/channels/signal.md @@ -109,7 +109,7 @@ DMs: - Approve via: - `openclaw pairing list signal` - `openclaw pairing approve signal ` -- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/start/pairing) +- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/channels/pairing) - UUID-only senders (from `sourceUuid`) are stored as `uuid:` in `channels.signal.allowFrom`. Groups: diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index 609daf9a6c..f4d7971c60 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -351,7 +351,7 @@ Use the global setting when all Telegram bots/accounts should behave the same. U - Approve via: - `openclaw pairing list telegram` - `openclaw pairing approve telegram ` -- Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/start/pairing) +- Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/channels/pairing) - `channels.telegram.allowFrom` accepts numeric user IDs (recommended) or `@username` entries. It is **not** the bot username; use the human sender’s ID. The wizard accepts `@username` and resolves it to the numeric ID when possible. #### Finding your Telegram user ID diff --git a/docs/channels/tlon.md b/docs/channels/tlon.md index 3b632a9274..b55d996da4 100644 --- a/docs/channels/tlon.md +++ b/docs/channels/tlon.md @@ -30,7 +30,7 @@ Local checkout (when running from a git repo): openclaw plugins install ./extensions/tlon ``` -Details: [Plugins](/plugin) +Details: [Plugins](/tools/plugin) ## Setup diff --git a/docs/channels/twitch.md b/docs/channels/twitch.md index ac46e35d6e..32670f3154 100644 --- a/docs/channels/twitch.md +++ b/docs/channels/twitch.md @@ -25,7 +25,7 @@ Local checkout (when running from a git repo): openclaw plugins install ./extensions/twitch ``` -Details: [Plugins](/plugin) +Details: [Plugins](/tools/plugin) ## Quick setup (beginner) diff --git a/docs/channels/zalo.md b/docs/channels/zalo.md index 88143dd58e..c595c5e6dd 100644 --- a/docs/channels/zalo.md +++ b/docs/channels/zalo.md @@ -15,7 +15,7 @@ Zalo ships as a plugin and is not bundled with the core install. - Install via CLI: `openclaw plugins install @openclaw/zalo` - Or select **Zalo** during onboarding and confirm the install prompt -- Details: [Plugins](/plugin) +- Details: [Plugins](/tools/plugin) ## Quick setup (beginner) @@ -104,7 +104,7 @@ Multi-account support: use `channels.zalo.accounts` with per-account tokens and - Approve via: - `openclaw pairing list zalo` - `openclaw pairing approve zalo ` -- Pairing is the default token exchange. Details: [Pairing](/start/pairing) +- Pairing is the default token exchange. Details: [Pairing](/channels/pairing) - `channels.zalo.allowFrom` accepts numeric user IDs (no username lookup available). ## Long-polling vs webhook diff --git a/docs/channels/zalouser.md b/docs/channels/zalouser.md index 5a1b555b82..e93e71a6f7 100644 --- a/docs/channels/zalouser.md +++ b/docs/channels/zalouser.md @@ -18,7 +18,7 @@ Zalo Personal ships as a plugin and is not bundled with the core install. - Install via CLI: `openclaw plugins install @openclaw/zalouser` - Or from a source checkout: `openclaw plugins install ./extensions/zalouser` -- Details: [Plugins](/plugin) +- Details: [Plugins](/tools/plugin) ## Prerequisite: zca-cli diff --git a/docs/cli/hooks.md b/docs/cli/hooks.md index 311df38488..d7531a02d9 100644 --- a/docs/cli/hooks.md +++ b/docs/cli/hooks.md @@ -12,8 +12,8 @@ Manage agent hooks (event-driven automations for commands like `/new`, `/reset`, Related: -- Hooks: [Hooks](/hooks) -- Plugin hooks: [Plugins](/plugin#plugin-hooks) +- Hooks: [Hooks](/automation/hooks) +- Plugin hooks: [Plugins](/tools/plugin#plugin-hooks) ## List All Hooks @@ -248,7 +248,7 @@ openclaw hooks enable session-memory **Output:** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md` -**See:** [session-memory documentation](/hooks#session-memory) +**See:** [session-memory documentation](/automation/hooks#session-memory) ### command-logger @@ -275,7 +275,7 @@ cat ~/.openclaw/logs/commands.log | jq . grep '"action":"new"' ~/.openclaw/logs/commands.log | jq . ``` -**See:** [command-logger documentation](/hooks#command-logger) +**See:** [command-logger documentation](/automation/hooks#command-logger) ### soul-evil @@ -301,4 +301,4 @@ Runs `BOOT.md` when the gateway starts (after channels start). openclaw hooks enable boot-md ``` -**See:** [boot-md documentation](/hooks#boot-md) +**See:** [boot-md documentation](/automation/hooks#boot-md) diff --git a/docs/cli/index.md b/docs/cli/index.md index ad0034f85d..918d92ad34 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -255,7 +255,7 @@ Manage extensions and their config: - `openclaw plugins enable ` / `disable ` — toggle `plugins.entries..enabled`. - `openclaw plugins doctor` — report plugin load errors. -Most plugin changes require a gateway restart. See [/plugin](/plugin). +Most plugin changes require a gateway restart. See [/plugin](/tools/plugin). ## Memory diff --git a/docs/cli/memory.md b/docs/cli/memory.md index db56e773f1..bc6d05c12e 100644 --- a/docs/cli/memory.md +++ b/docs/cli/memory.md @@ -14,7 +14,7 @@ Provided by the active memory plugin (default: `memory-core`; set `plugins.slots Related: - Memory concept: [Memory](/concepts/memory) -- Plugins: [Plugins](/plugin) +- Plugins: [Plugins](/tools/plugin) ## Examples diff --git a/docs/cli/pairing.md b/docs/cli/pairing.md index fadec9fb4c..319ddc29a0 100644 --- a/docs/cli/pairing.md +++ b/docs/cli/pairing.md @@ -11,7 +11,7 @@ Approve or inspect DM pairing requests (for channels that support pairing). Related: -- Pairing flow: [Pairing](/start/pairing) +- Pairing flow: [Pairing](/channels/pairing) ## Commands diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index a15dd6cd51..19e56ab1c1 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -12,7 +12,7 @@ Manage Gateway plugins/extensions (loaded in-process). Related: -- Plugin system: [Plugins](/plugin) +- Plugin system: [Plugins](/tools/plugin) - Plugin manifest + schema: [Plugin manifest](/plugins/manifest) - Security hardening: [Security](/gateway/security) diff --git a/docs/cli/tui.md b/docs/cli/tui.md index 19440421a2..2b6d9f45ed 100644 --- a/docs/cli/tui.md +++ b/docs/cli/tui.md @@ -12,7 +12,7 @@ Open the terminal UI connected to the Gateway. Related: -- TUI guide: [TUI](/tui) +- TUI guide: [TUI](/web/tui) ## Examples diff --git a/docs/concepts/agent-loop.md b/docs/concepts/agent-loop.md index 8e45682173..b0d99ca907 100644 --- a/docs/concepts/agent-loop.md +++ b/docs/concepts/agent-loop.md @@ -75,7 +75,7 @@ OpenClaw has two hook systems: Use this to add/remove bootstrap context files. - **Command hooks**: `/new`, `/reset`, `/stop`, and other command events (see Hooks doc). -See [Hooks](/hooks) for setup and examples. +See [Hooks](/automation/hooks) for setup and examples. ### Plugin hooks (agent + gateway lifecycle) @@ -90,7 +90,7 @@ These run inside the agent loop or gateway pipeline: - **`session_start` / `session_end`**: session lifecycle boundaries. - **`gateway_start` / `gateway_stop`**: gateway lifecycle events. -See [Plugins](/plugin#plugin-hooks) for the hook API and registration details. +See [Plugins](/tools/plugin#plugin-hooks) for the hook API and registration details. ## Streaming + partial replies diff --git a/docs/concepts/agent-workspace.md b/docs/concepts/agent-workspace.md index fe3a69fbae..79e1647e8f 100644 --- a/docs/concepts/agent-workspace.md +++ b/docs/concepts/agent-workspace.md @@ -228,6 +228,6 @@ Suggested `.gitignore` starter: ## Advanced notes - Multi-agent routing can use different workspaces per agent. See - [Channel routing](/concepts/channel-routing) for routing configuration. + [Channel routing](/channels/channel-routing) for routing configuration. - If `agents.defaults.sandbox` is enabled, non-main sessions can use per-session sandbox workspaces under `agents.defaults.sandbox.workspaceRoot`. diff --git a/docs/concepts/agent.md b/docs/concepts/agent.md index 9cc2611332..26d677745e 100644 --- a/docs/concepts/agent.md +++ b/docs/concepts/agent.md @@ -120,4 +120,4 @@ At minimum, set: --- -_Next: [Group Chats](/concepts/group-messages)_ 🦞 +_Next: [Group Chats](/channels/group-messages)_ 🦞 diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md index a9676b171c..d8c7404b89 100644 --- a/docs/concepts/architecture.md +++ b/docs/concepts/architecture.md @@ -97,7 +97,7 @@ Client Gateway - Gateway auth (`gateway.auth.*`) still applies to **all** connections, local or remote. -Details: [Gateway protocol](/gateway/protocol), [Pairing](/start/pairing), +Details: [Gateway protocol](/gateway/protocol), [Pairing](/channels/pairing), [Security](/gateway/security). ## Protocol typing and codegen diff --git a/docs/concepts/context.md b/docs/concepts/context.md index 550767efb8..834cc96524 100644 --- a/docs/concepts/context.md +++ b/docs/concepts/context.md @@ -27,7 +27,7 @@ Context is _not the same thing_ as “memory”: memory can be stored on disk an - `/usage tokens` → append per-reply usage footer to normal replies. - `/compact` → summarize older history into a compact entry to free window space. -See also: [Slash commands](/tools/slash-commands), [Token use & costs](/token-use), [Compaction](/concepts/compaction). +See also: [Slash commands](/tools/slash-commands), [Token use & costs](/reference/token-use), [Compaction](/concepts/compaction). ## Example output diff --git a/docs/concepts/messages.md b/docs/concepts/messages.md index 6ebb0be813..4930002187 100644 --- a/docs/concepts/messages.md +++ b/docs/concepts/messages.md @@ -142,7 +142,7 @@ OpenClaw can expose or hide model reasoning: - Reasoning content still counts toward token usage when produced by the model. - Telegram supports reasoning stream into the draft bubble. -Details: [Thinking + reasoning directives](/tools/thinking) and [Token use](/token-use). +Details: [Thinking + reasoning directives](/tools/thinking) and [Token use](/reference/token-use). ## Prefixes, threading, and replies diff --git a/docs/concepts/models.md b/docs/concepts/models.md index 1f602bac75..3af853f5b4 100644 --- a/docs/concepts/models.md +++ b/docs/concepts/models.md @@ -194,7 +194,7 @@ Scan results are ranked by: Input - OpenRouter `/models` list (filter `:free`) -- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` (see [/environment](/environment)) +- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` (see [/environment](/help/environment)) - Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates` - Probe controls: `--timeout`, `--concurrency` diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md index 9952319731..6f8bad589d 100644 --- a/docs/concepts/multi-agent.md +++ b/docs/concepts/multi-agent.md @@ -112,7 +112,7 @@ Example: Notes: - DM access control is **global per WhatsApp account** (pairing/allowlist), not per agent. -- For shared groups, bind the group to one agent or use [Broadcast groups](/broadcast-groups). +- For shared groups, bind the group to one agent or use [Broadcast groups](/channels/broadcast-groups). ## Routing rules (how messages pick an agent) @@ -373,4 +373,4 @@ Note: `tools.elevated` is **global** and sender-based; it is not configurable pe If you need per-agent boundaries, use `agents.list[].tools` to deny `exec`. For group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent. -See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for detailed examples. +See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for detailed examples. diff --git a/docs/docs.json b/docs/docs.json index 3a47206bec..b32ed2800a 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -38,18 +38,6 @@ ] }, "redirects": [ - { - "source": "/cron", - "destination": "/cron-jobs" - }, - { - "source": "/model", - "destination": "/models" - }, - { - "source": "/model/", - "destination": "/models" - }, { "source": "/messages", "destination": "/concepts/messages" @@ -62,6 +50,10 @@ "source": "/compaction", "destination": "/concepts/compaction" }, + { + "source": "/cron", + "destination": "/cron-jobs" + }, { "source": "/minimax", "destination": "/providers/minimax" @@ -356,11 +348,11 @@ }, { "source": "/group-messages", - "destination": "/concepts/group-messages" + "destination": "/channels/group-messages" }, { "source": "/groups", - "destination": "/concepts/groups" + "destination": "/channels/groups" }, { "source": "/health", @@ -486,6 +478,14 @@ "source": "/model-failover", "destination": "/concepts/model-failover" }, + { + "source": "/model", + "destination": "/models" + }, + { + "source": "/model/", + "destination": "/models" + }, { "source": "/models", "destination": "/concepts/models" @@ -508,7 +508,7 @@ }, { "source": "/pairing", - "destination": "/start/pairing" + "destination": "/channels/pairing" }, { "source": "/plans/cron-add-hardening", @@ -532,11 +532,11 @@ }, { "source": "/provider-routing", - "destination": "/concepts/channel-routing" + "destination": "/channels/channel-routing" }, { "source": "/concepts/provider-routing", - "destination": "/concepts/channel-routing" + "destination": "/channels/channel-routing" }, { "source": "/queue", @@ -667,8 +667,8 @@ "destination": "/help/troubleshooting" }, { - "source": "/web/tui", - "destination": "/tui" + "source": "/tui", + "destination": "/web/tui" }, { "source": "/typebox", @@ -722,9 +722,13 @@ "source": "/oauth", "destination": "/concepts/oauth" }, + { + "source": "/plugin", + "destination": "/tools/plugin" + }, { "source": "/plugins", - "destination": "/plugin" + "destination": "/tools/plugin" }, { "source": "/railway", @@ -783,9 +787,17 @@ { "tab": "Get started", "groups": [ + { + "group": "Home", + "pages": ["index"] + }, { "group": "Overview", - "pages": ["index", "concepts/features", "start/showcase"] + "pages": ["start/showcase"] + }, + { + "group": "Core concepts", + "pages": ["concepts/features"] }, { "group": "First steps", @@ -861,11 +873,11 @@ { "group": "Configuration", "pages": [ - "start/pairing", - "concepts/group-messages", - "concepts/groups", - "broadcast-groups", - "concepts/channel-routing", + "channels/pairing", + "channels/group-messages", + "channels/groups", + "channels/broadcast-groups", + "channels/channel-routing", "channels/location", "channels/troubleshooting" ] @@ -884,10 +896,13 @@ "concepts/system-prompt", "concepts/context", "concepts/agent-workspace", - "start/bootstrapping", "concepts/oauth" ] }, + { + "group": "Bootstrapping", + "pages": ["start/bootstrapping"] + }, { "group": "Sessions and memory", "pages": [ @@ -945,25 +960,26 @@ }, { "group": "Agent coordination", - "pages": ["tools/agent-send", "tools/subagents", "multi-agent-sandbox-tools"] + "pages": ["tools/agent-send", "tools/subagents", "tools/multi-agent-sandbox-tools"] }, { - "group": "Skills and extensions", + "group": "Skills", "pages": [ "tools/slash-commands", "tools/skills", "tools/skills-config", "tools/clawhub", - "plugin", - "plugins/voice-call", - "plugins/zalouser" + "tools/plugin" ] }, + { + "group": "Extensions", + "pages": ["plugins/voice-call", "plugins/zalouser"] + }, { "group": "Automation", "pages": [ - "hooks", - "hooks/soul-evil", + "automation/hooks", "automation/cron-jobs", "automation/cron-vs-heartbeat", "automation/troubleshooting", @@ -973,6 +989,10 @@ "automation/auth-monitoring" ] }, + { + "group": "Hooks", + "pages": ["hooks/soul-evil"] + }, { "group": "Media and devices", "pages": [ @@ -993,7 +1013,11 @@ "groups": [ { "group": "Overview", - "pages": ["providers/index", "providers/models", "concepts/models"] + "pages": ["providers/index", "providers/models"] + }, + { + "group": "Model concepts", + "pages": ["concepts/models"] }, { "group": "Configuration", @@ -1005,7 +1029,7 @@ "providers/anthropic", "providers/openai", "providers/openrouter", - "bedrock", + "providers/bedrock", "providers/vercel-ai-gateway", "providers/moonshot", "providers/minimax", @@ -1120,7 +1144,7 @@ }, { "group": "Web interfaces", - "pages": ["web/index", "web/control-ui", "web/dashboard", "web/webchat", "tui"] + "pages": ["web/index", "web/control-ui", "web/dashboard", "web/webchat", "web/tui"] } ] }, @@ -1188,14 +1212,16 @@ }, { "group": "Technical reference", + "pages": ["reference/wizard", "reference/token-use"] + }, + { + "group": "Concept internals", "pages": [ - "reference/wizard", "concepts/typebox", "concepts/markdown-formatting", "concepts/typing-indicators", "concepts/usage-tracking", - "concepts/timezone", - "token-use" + "concepts/timezone" ] }, { @@ -1221,18 +1247,23 @@ }, { "group": "Environment and debugging", - "pages": [ - "install/node", - "environment", - "debugging", - "testing", - "scripts", - "reference/session-management-compaction" - ] + "pages": ["help/environment", "help/debugging", "help/testing", "help/scripts"] }, { - "group": "Developer workflows", - "pages": ["start/setup", "help/submitting-a-pr", "help/submitting-an-issue"] + "group": "Node runtime", + "pages": ["install/node"] + }, + { + "group": "Compaction internals", + "pages": ["reference/session-management-compaction"] + }, + { + "group": "Developer setup", + "pages": ["start/setup"] + }, + { + "group": "Contributing", + "pages": ["help/submitting-a-pr", "help/submitting-an-issue"] }, { "group": "Docs meta", @@ -1248,9 +1279,17 @@ { "tab": "快速开始", "groups": [ + { + "group": "首页", + "pages": ["zh-CN/index"] + }, { "group": "概览", - "pages": ["zh-CN/index", "zh-CN/concepts/features", "zh-CN/start/showcase"] + "pages": ["zh-CN/start/showcase"] + }, + { + "group": "核心概念", + "pages": ["zh-CN/concepts/features"] }, { "group": "第一步", @@ -1276,7 +1315,6 @@ { "group": "安装方式", "pages": [ - "zh-CN/install/node", "zh-CN/install/docker", "zh-CN/install/nix", "zh-CN/install/ansible", @@ -1340,11 +1378,11 @@ { "group": "配置", "pages": [ - "zh-CN/start/pairing", - "zh-CN/concepts/group-messages", - "zh-CN/concepts/groups", - "zh-CN/broadcast-groups", - "zh-CN/concepts/channel-routing", + "zh-CN/channels/pairing", + "zh-CN/channels/group-messages", + "zh-CN/channels/groups", + "zh-CN/channels/broadcast-groups", + "zh-CN/channels/channel-routing", "zh-CN/channels/location", "zh-CN/channels/troubleshooting" ] @@ -1366,6 +1404,10 @@ "zh-CN/concepts/oauth" ] }, + { + "group": "引导", + "pages": ["zh-CN/start/bootstrapping"] + }, { "group": "会话与记忆", "pages": [ @@ -1426,38 +1468,45 @@ "pages": [ "zh-CN/tools/agent-send", "zh-CN/tools/subagents", - "zh-CN/multi-agent-sandbox-tools" + "zh-CN/tools/multi-agent-sandbox-tools" ] }, { - "group": "技能与扩展", + "group": "技能", "pages": [ "zh-CN/tools/slash-commands", "zh-CN/tools/skills", "zh-CN/tools/skills-config", "zh-CN/tools/clawhub", - "zh-CN/plugin", - "zh-CN/plugins/voice-call", - "zh-CN/plugins/zalouser" + "zh-CN/tools/plugin" ] }, + { + "group": "扩展", + "pages": ["zh-CN/plugins/voice-call", "zh-CN/plugins/zalouser"] + }, { "group": "自动化", "pages": [ - "zh-CN/hooks", - "zh-CN/hooks/soul-evil", + "zh-CN/automation/hooks", "zh-CN/automation/cron-jobs", "zh-CN/automation/cron-vs-heartbeat", + "zh-CN/automation/troubleshooting", "zh-CN/automation/webhook", "zh-CN/automation/gmail-pubsub", "zh-CN/automation/poll", "zh-CN/automation/auth-monitoring" ] }, + { + "group": "Hooks", + "pages": ["zh-CN/hooks/soul-evil"] + }, { "group": "媒体与设备", "pages": [ "zh-CN/nodes/index", + "zh-CN/nodes/troubleshooting", "zh-CN/nodes/images", "zh-CN/nodes/audio", "zh-CN/nodes/camera", @@ -1473,11 +1522,11 @@ "groups": [ { "group": "概览", - "pages": [ - "zh-CN/providers/index", - "zh-CN/providers/models", - "zh-CN/concepts/models" - ] + "pages": ["zh-CN/providers/index", "zh-CN/providers/models"] + }, + { + "group": "模型概念", + "pages": ["zh-CN/concepts/models"] }, { "group": "配置", @@ -1489,14 +1538,15 @@ "zh-CN/providers/anthropic", "zh-CN/providers/openai", "zh-CN/providers/openrouter", - "zh-CN/bedrock", + "zh-CN/providers/bedrock", "zh-CN/providers/vercel-ai-gateway", "zh-CN/providers/moonshot", "zh-CN/providers/minimax", "zh-CN/providers/opencode", "zh-CN/providers/glm", "zh-CN/providers/zai", - "zh-CN/providers/synthetic" + "zh-CN/providers/synthetic", + "zh-CN/providers/qianfan" ] } ] @@ -1612,7 +1662,7 @@ "zh-CN/web/control-ui", "zh-CN/web/dashboard", "zh-CN/web/webchat", - "zh-CN/tui" + "zh-CN/web/tui" ] } ] @@ -1681,13 +1731,16 @@ }, { "group": "技术参考", + "pages": ["zh-CN/reference/wizard", "zh-CN/reference/token-use"] + }, + { + "group": "概念内部机制", "pages": [ "zh-CN/concepts/typebox", "zh-CN/concepts/markdown-formatting", "zh-CN/concepts/typing-indicators", "zh-CN/concepts/usage-tracking", - "zh-CN/concepts/timezone", - "zh-CN/token-use" + "zh-CN/concepts/timezone" ] }, { @@ -1714,17 +1767,28 @@ { "group": "环境与调试", "pages": [ - "zh-CN/environment", - "zh-CN/debugging", - "zh-CN/testing", - "zh-CN/scripts", - "zh-CN/reference/session-management-compaction" + "zh-CN/help/environment", + "zh-CN/help/debugging", + "zh-CN/help/testing", + "zh-CN/help/scripts" ] }, { - "group": "开发者工作流", + "group": "Node 运行时", + "pages": ["zh-CN/install/node"] + }, + { + "group": "压缩机制内部参考", + "pages": ["zh-CN/reference/session-management-compaction"] + }, + { + "group": "开发者设置", "pages": ["zh-CN/start/setup"] }, + { + "group": "贡献", + "pages": ["zh-CN/help/submitting-a-pr", "zh-CN/help/submitting-an-issue"] + }, { "group": "文档元信息", "pages": ["zh-CN/start/hubs", "zh-CN/start/docs-directory"] diff --git a/docs/experiments/plans/group-policy-hardening.md b/docs/experiments/plans/group-policy-hardening.md index a684e1f876..2a51b7c130 100644 --- a/docs/experiments/plans/group-policy-hardening.md +++ b/docs/experiments/plans/group-policy-hardening.md @@ -36,5 +36,5 @@ false negatives when deciding whether to respond in DMs or groups. ## Related docs -- [Group Chats](/concepts/groups) +- [Group Chats](/channels/groups) - [Telegram Provider](/channels/telegram) diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index a22afea199..35302f9bc3 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -289,7 +289,7 @@ process env is missing the key (same non-overriding rule): } ``` -See [/environment](/environment) for full precedence and sources. +See [/environment](/help/environment) for full precedence and sources. ### `env.shellEnv` (optional) @@ -788,7 +788,7 @@ levels in one gateway: - **Read-only** tools + workspace - **No filesystem access** (messaging/session tools only) -See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence and +See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for precedence and additional examples. Full access (no sandbox): @@ -2857,7 +2857,7 @@ Example: Controls plugin discovery, allow/deny, and per-plugin config. Plugins are loaded from `~/.openclaw/extensions`, `/.openclaw/extensions`, plus any `plugins.load.paths` entries. **Config changes require a gateway restart.** -See [/plugin](/plugin) for full usage. +See [/plugin](/tools/plugin) for full usage. Fields: diff --git a/docs/gateway/heartbeat.md b/docs/gateway/heartbeat.md index fa13040916..6c467d2ae1 100644 --- a/docs/gateway/heartbeat.md +++ b/docs/gateway/heartbeat.md @@ -200,7 +200,7 @@ Use `accountId` to target a specific account on multi-account channels like Tele - `session`: optional session key for heartbeat runs. - `main` (default): agent main session. - Explicit session key (copy from `openclaw sessions --json` or the [sessions CLI](/cli/sessions)). - - Session key formats: see [Sessions](/concepts/session) and [Groups](/concepts/groups). + - Session key formats: see [Sessions](/concepts/session) and [Groups](/channels/groups). - `target`: - `last` (default): deliver to the last used external channel. - explicit channel: `whatsapp` / `telegram` / `discord` / `googlechat` / `slack` / `msteams` / `signal` / `imessage`. diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md index f31aeea8ba..45062ea9df 100644 --- a/docs/gateway/sandboxing.md +++ b/docs/gateway/sandboxing.md @@ -168,7 +168,7 @@ Debugging: Each agent can override sandbox + tools: `agents.list[].sandbox` and `agents.list[].tools` (plus `agents.list[].tools.sandbox.tools` for sandbox tool policy). -See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence. +See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for precedence. ## Minimal enable example @@ -189,5 +189,5 @@ See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence. ## Related docs - [Sandbox Configuration](/gateway/configuration#agentsdefaults-sandbox) -- [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) +- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) - [Security](/gateway/security) diff --git a/docs/gateway/security/formal-verification.md b/docs/gateway/security/formal-verification.md deleted file mode 100644 index 3ed2b42c1d..0000000000 --- a/docs/gateway/security/formal-verification.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: Formal Verification (Security Models) -summary: Machine-checked security models for OpenClaw’s highest-risk paths. -permalink: /security/formal-verification/ ---- - -# Formal Verification (Security Models) - -This page tracks OpenClaw’s **formal security models** (TLA+/TLC today; more as needed). - -> Note: some older links may refer to the previous project name. - -**Goal (north star):** provide a machine-checked argument that OpenClaw enforces its -intended security policy (authorization, session isolation, tool gating, and -misconfiguration safety), under explicit assumptions. - -**What this is (today):** an executable, attacker-driven **security regression suite**: - -- Each claim has a runnable model-check over a finite state space. -- Many claims have a paired **negative model** that produces a counterexample trace for a realistic bug class. - -**What this is not (yet):** a proof that “OpenClaw is secure in all respects” or that the full TypeScript implementation is correct. - -## Where the models live - -Models are maintained in a separate repo: [vignesh07/clawdbot-formal-models](https://github.com/vignesh07/clawdbot-formal-models). - -## Important caveats - -- These are **models**, not the full TypeScript implementation. Drift between model and code is possible. -- Results are bounded by the state space explored by TLC; “green” does not imply security beyond the modeled assumptions and bounds. -- Some claims rely on explicit environmental assumptions (e.g., correct deployment, correct configuration inputs). - -## Reproducing results - -Today, results are reproduced by cloning the models repo locally and running TLC (see below). A future iteration could offer: - -- CI-run models with public artifacts (counterexample traces, run logs) -- a hosted “run this model” workflow for small, bounded checks - -Getting started: - -```bash -git clone https://github.com/vignesh07/clawdbot-formal-models -cd clawdbot-formal-models - -# Java 11+ required (TLC runs on the JVM). -# The repo vendors a pinned `tla2tools.jar` (TLA+ tools) and provides `bin/tlc` + Make targets. - -make -``` - -### Gateway exposure and open gateway misconfiguration - -**Claim:** binding beyond loopback without auth can make remote compromise possible / increases exposure; token/password blocks unauth attackers (per the model assumptions). - -- Green runs: - - `make gateway-exposure-v2` - - `make gateway-exposure-v2-protected` -- Red (expected): - - `make gateway-exposure-v2-negative` - -See also: `docs/gateway-exposure-matrix.md` in the models repo. - -### Nodes.run pipeline (highest-risk capability) - -**Claim:** `nodes.run` requires (a) node command allowlist plus declared commands and (b) live approval when configured; approvals are tokenized to prevent replay (in the model). - -- Green runs: - - `make nodes-pipeline` - - `make approvals-token` -- Red (expected): - - `make nodes-pipeline-negative` - - `make approvals-token-negative` - -### Pairing store (DM gating) - -**Claim:** pairing requests respect TTL and pending-request caps. - -- Green runs: - - `make pairing` - - `make pairing-cap` -- Red (expected): - - `make pairing-negative` - - `make pairing-cap-negative` - -### Ingress gating (mentions + control-command bypass) - -**Claim:** in group contexts requiring mention, an unauthorized “control command” cannot bypass mention gating. - -- Green: - - `make ingress-gating` -- Red (expected): - - `make ingress-gating-negative` - -### Routing/session-key isolation - -**Claim:** DMs from distinct peers do not collapse into the same session unless explicitly linked/configured. - -- Green: - - `make routing-isolation` -- Red (expected): - - `make routing-isolation-negative` - -## v1++: additional bounded models (concurrency, retries, trace correctness) - -These are follow-on models that tighten fidelity around real-world failure modes (non-atomic updates, retries, and message fan-out). - -### Pairing store concurrency / idempotency - -**Claim:** a pairing store should enforce `MaxPending` and idempotency even under interleavings (i.e., “check-then-write” must be atomic / locked; refresh shouldn’t create duplicates). - -What it means: - -- Under concurrent requests, you can’t exceed `MaxPending` for a channel. -- Repeated requests/refreshes for the same `(channel, sender)` should not create duplicate live pending rows. - -- Green runs: - - `make pairing-race` (atomic/locked cap check) - - `make pairing-idempotency` - - `make pairing-refresh` - - `make pairing-refresh-race` -- Red (expected): - - `make pairing-race-negative` (non-atomic begin/commit cap race) - - `make pairing-idempotency-negative` - - `make pairing-refresh-negative` - - `make pairing-refresh-race-negative` - -### Ingress trace correlation / idempotency - -**Claim:** ingestion should preserve trace correlation across fan-out and be idempotent under provider retries. - -What it means: - -- When one external event becomes multiple internal messages, every part keeps the same trace/event identity. -- Retries do not result in double-processing. -- If provider event IDs are missing, dedupe falls back to a safe key (e.g., trace ID) to avoid dropping distinct events. - -- Green: - - `make ingress-trace` - - `make ingress-trace2` - - `make ingress-idempotency` - - `make ingress-dedupe-fallback` -- Red (expected): - - `make ingress-trace-negative` - - `make ingress-trace2-negative` - - `make ingress-idempotency-negative` - - `make ingress-dedupe-fallback-negative` - -### Routing dmScope precedence + identityLinks - -**Claim:** routing must keep DM sessions isolated by default, and only collapse sessions when explicitly configured (channel precedence + identity links). - -What it means: - -- Channel-specific dmScope overrides must win over global defaults. -- identityLinks should collapse only within explicit linked groups, not across unrelated peers. - -- Green: - - `make routing-precedence` - - `make routing-identitylinks` -- Red (expected): - - `make routing-precedence-negative` - - `make routing-identitylinks-negative` diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index f6bd917346..d8df55b0a9 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -175,7 +175,7 @@ Plugins run **in-process** with the Gateway. Treat them as trusted code: - OpenClaw uses `npm pack` and then runs `npm install --omit=dev` in that directory (npm lifecycle scripts can execute code during install). - Prefer pinned, exact versions (`@scope/pkg@1.2.3`), and inspect the unpacked code on disk before enabling. -Details: [Plugins](/plugin) +Details: [Plugins](/tools/plugin) ## DM access model (pairing / allowlist / open / disabled) @@ -193,7 +193,7 @@ openclaw pairing list openclaw pairing approve ``` -Details + files on disk: [Pairing](/start/pairing) +Details + files on disk: [Pairing](/channels/pairing) ## DM session isolation (multi-user mode) @@ -229,7 +229,7 @@ OpenClaw has two separate “who can trigger me?” layers: - `channels.discord.guilds` / `channels.slack.channels`: per-surface allowlists + mention defaults. - **Security note:** treat `dmPolicy="open"` and `groupPolicy="open"` as last-resort settings. They should be barely used; prefer pairing + allowlists unless you fully trust every member of the room. -Details: [Configuration](/gateway/configuration) and [Groups](/concepts/groups) +Details: [Configuration](/gateway/configuration) and [Groups](/channels/groups) ## Prompt injection (what it is, why it matters) @@ -627,7 +627,7 @@ access those accounts and data. Treat browser profiles as **sensitive state**: With multi-agent routing, each agent can have its own sandbox + tool policy: use this to give **full access**, **read-only**, or **no access** per agent. -See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for full details +See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for full details and precedence rules. Common use cases: diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index 32091dc547..9d6ba53d7e 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -56,8 +56,8 @@ Common signatures: Related: - [/channels/troubleshooting](/channels/troubleshooting) -- [/start/pairing](/start/pairing) -- [/concepts/groups](/concepts/groups) +- [/channels/pairing](/channels/pairing) +- [/channels/groups](/channels/groups) ## Dashboard control ui connectivity diff --git a/docs/debugging.md b/docs/help/debugging.md similarity index 100% rename from docs/debugging.md rename to docs/help/debugging.md diff --git a/docs/environment.md b/docs/help/environment.md similarity index 100% rename from docs/environment.md rename to docs/help/environment.md diff --git a/docs/help/faq.md b/docs/help/faq.md index fda1acddb4..dc5ef64122 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -707,7 +707,7 @@ See [Models](/cli/models) and [OAuth](/concepts/oauth). ### Is AWS Bedrock supported -Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI-compatible proxy in front of Bedrock is still a valid option. +Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/providers/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI-compatible proxy in front of Bedrock is still a valid option. ### How does Codex auth work @@ -1177,7 +1177,7 @@ Yes - if your private traffic is **DMs** and your public traffic is **groups**. Use `agents.defaults.sandbox.mode: "non-main"` so group/channel sessions (non-main keys) run in Docker, while the main DM session stays on-host. Then restrict what tools are available in sandboxed sessions via `tools.sandbox.tools`. -Setup walkthrough + example config: [Groups: personal DMs + public groups](/concepts/groups#pattern-personal-dms-public-groups-single-agent) +Setup walkthrough + example config: [Groups: personal DMs + public groups](/channels/groups#pattern-personal-dms-public-groups-single-agent) Key config reference: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox) @@ -1427,7 +1427,7 @@ The common pattern is **one Gateway** (e.g. Raspberry Pi) plus **nodes** and **a - **Sub-agents:** spawn background work from a main agent when you want parallelism. - **TUI:** connect to the Gateway and switch agents/sessions. -Docs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/tui). +Docs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/web/tui). ### Can the OpenClaw browser run headless @@ -1681,7 +1681,7 @@ You can also define inline env vars in config (applied only if missing from the } ``` -See [/environment](/environment) for full precedence and sources. +See [/environment](/help/environment) for full precedence and sources. ### I started the Gateway via the service and my env vars disappeared What now @@ -1729,7 +1729,7 @@ openclaw models status ``` Copilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`). -See [/concepts/model-providers](/concepts/model-providers) and [/environment](/environment). +See [/concepts/model-providers](/concepts/model-providers) and [/environment](/help/environment). ## Sessions and multiple chats @@ -1902,11 +1902,11 @@ Two common causes: - Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`). - You configured `channels.whatsapp.groups` without `"*"` and the group isn't allowlisted. -See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages). +See [Groups](/channels/groups) and [Group messages](/channels/group-messages). ### Do groupsthreads share context with DMs -Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages). +Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/channels/groups) and [Group messages](/channels/group-messages). ### How many workspaces and agents can I create @@ -2609,7 +2609,7 @@ openclaw logs --follow In the TUI, use `/status` to see the current state. If you expect replies in a chat channel, make sure delivery is enabled (`/deliver on`). -Docs: [TUI](/tui), [Slash commands](/tools/slash-commands). +Docs: [TUI](/web/tui), [Slash commands](/tools/slash-commands). ### How do I completely stop then start the Gateway @@ -2701,7 +2701,7 @@ credentials or revoke access without impacting your personal accounts. Start small. Give access only to the tools and accounts you actually need, and expand later if required. -Docs: [Security](/gateway/security), [Pairing](/start/pairing). +Docs: [Security](/gateway/security), [Pairing](/channels/pairing). ### Can I give it autonomy over my text messages and is that safe diff --git a/docs/scripts.md b/docs/help/scripts.md similarity index 100% rename from docs/scripts.md rename to docs/help/scripts.md diff --git a/docs/testing.md b/docs/help/testing.md similarity index 100% rename from docs/testing.md rename to docs/help/testing.md diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md index c050d1b0d6..83cad80ba3 100644 --- a/docs/help/troubleshooting.md +++ b/docs/help/troubleshooting.md @@ -83,7 +83,7 @@ flowchart TD - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies) - [/channels/troubleshooting](/channels/troubleshooting) - - [/start/pairing](/start/pairing) + - [/channels/pairing](/channels/pairing) diff --git a/docs/hooks/soul-evil.md b/docs/hooks/soul-evil.md index 98a1bbca09..0b08d54a1c 100644 --- a/docs/hooks/soul-evil.md +++ b/docs/hooks/soul-evil.md @@ -66,4 +66,4 @@ Create `SOUL_EVIL.md` in the agent workspace root (next to `SOUL.md`). ## See Also -- [Hooks](/hooks) +- [Hooks](/automation/hooks) diff --git a/docs/install/ansible.md b/docs/install/ansible.md index 32bda68a47..be91aedaad 100644 --- a/docs/install/ansible.md +++ b/docs/install/ansible.md @@ -107,7 +107,7 @@ Should show **only port 22** (SSH) open. All other services (gateway, Docker) ar Docker is installed for **agent sandboxes** (isolated tool execution), not for running the gateway itself. The gateway binds to localhost only and is accessible via Tailscale VPN. -See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for sandbox configuration. +See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for sandbox configuration. ## Manual Installation @@ -205,4 +205,4 @@ For detailed security architecture and troubleshooting: - [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — full deployment guide - [Docker](/install/docker) — containerized gateway setup - [Sandboxing](/gateway/sandboxing) — agent sandbox configuration -- [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) — per-agent isolation +- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) — per-agent isolation diff --git a/docs/install/docker.md b/docs/install/docker.md index 252bdb1ac2..5529e28ea6 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -336,7 +336,7 @@ mixed access levels in one gateway: - Read-only tools + read-only workspace (family/work agent) - No filesystem/shell tools (public agent) -See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for examples, +See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for examples, precedence, and troubleshooting. ### Default behavior diff --git a/docs/network.md b/docs/network.md index 4298a7019e..f9bacafc94 100644 --- a/docs/network.md +++ b/docs/network.md @@ -21,7 +21,7 @@ devices across localhost, LAN, and tailnet. ## Pairing + identity -- [Pairing overview (DM + nodes)](/start/pairing) +- [Pairing overview (DM + nodes)](/channels/pairing) - [Gateway-owned node pairing](/gateway/pairing) - [Devices CLI (pairing + token rotation)](/cli/devices) - [Pairing CLI (DM approvals)](/cli/pairing) diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md index 152a71170c..77fc543a64 100644 --- a/docs/plugins/manifest.md +++ b/docs/plugins/manifest.md @@ -13,7 +13,7 @@ OpenClaw uses this manifest to validate configuration **without executing plugin code**. Missing or invalid manifests are treated as plugin errors and block config validation. -See the full plugin system guide: [Plugins](/plugin). +See the full plugin system guide: [Plugins](/tools/plugin). ## Required fields diff --git a/docs/prose.md b/docs/prose.md index 7b4b8c002b..a3d22f14c4 100644 --- a/docs/prose.md +++ b/docs/prose.md @@ -31,7 +31,7 @@ Restart the Gateway after enabling the plugin. Dev/local checkout: `openclaw plugins install ./extensions/open-prose` -Related docs: [Plugins](/plugin), [Plugin manifest](/plugins/manifest), [Skills](/tools/skills). +Related docs: [Plugins](/tools/plugin), [Plugin manifest](/plugins/manifest), [Skills](/tools/skills). ## Slash command diff --git a/docs/bedrock.md b/docs/providers/bedrock.md similarity index 100% rename from docs/bedrock.md rename to docs/providers/bedrock.md diff --git a/docs/providers/index.md b/docs/providers/index.md index 4c60fea4c7..21aaff7ed3 100644 --- a/docs/providers/index.md +++ b/docs/providers/index.md @@ -43,7 +43,7 @@ See [Venice AI](/providers/venice). - [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway) - [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot) - [OpenCode Zen](/providers/opencode) -- [Amazon Bedrock](/bedrock) +- [Amazon Bedrock](/providers/bedrock) - [Z.AI](/providers/zai) - [Xiaomi](/providers/xiaomi) - [GLM models](/providers/glm) diff --git a/docs/providers/models.md b/docs/providers/models.md index 1a9d28cf8a..aff92bd074 100644 --- a/docs/providers/models.md +++ b/docs/providers/models.md @@ -45,7 +45,7 @@ See [Venice AI](/providers/venice). - [GLM models](/providers/glm) - [MiniMax](/providers/minimax) - [Venice (Venice AI)](/providers/venice) -- [Amazon Bedrock](/bedrock) +- [Amazon Bedrock](/providers/bedrock) - [Qianfan](/providers/qianfan) For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration, diff --git a/docs/providers/qianfan.md b/docs/providers/qianfan.md index 9991fec8de..1e80dafb26 100644 --- a/docs/providers/qianfan.md +++ b/docs/providers/qianfan.md @@ -32,7 +32,7 @@ openclaw onboard --auth-choice qianfan-api-key ## Related Documentation -- [OpenClaw Configuration](/configuration) +- [OpenClaw Configuration](/gateway/configuration) - [Model Providers](/concepts/model-providers) -- [Agent Setup](/agents) +- [Agent Setup](/concepts/agent) - [Qianfan API Documentation](https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb) diff --git a/docs/refactor/plugin-sdk.md b/docs/refactor/plugin-sdk.md index 44c23542f2..4c9d5910ce 100644 --- a/docs/refactor/plugin-sdk.md +++ b/docs/refactor/plugin-sdk.md @@ -211,4 +211,4 @@ Notes: - New connector templates depend only on SDK + runtime. - External plugins can be developed and updated without core source access. -Related docs: [Plugins](/plugin), [Channels](/channels/index), [Configuration](/gateway/configuration). +Related docs: [Plugins](/tools/plugin), [Channels](/channels/index), [Configuration](/gateway/configuration). diff --git a/docs/reference/api-usage-costs.md b/docs/reference/api-usage-costs.md index 5450b63a42..0eb9517141 100644 --- a/docs/reference/api-usage-costs.md +++ b/docs/reference/api-usage-costs.md @@ -29,7 +29,7 @@ OpenClaw features that can generate provider usage or paid API calls. - `openclaw status --usage` and `openclaw channels list` show provider **usage windows** (quota snapshots, not per-message costs). -See [Token use & costs](/token-use) for details and examples. +See [Token use & costs](/reference/token-use) for details and examples. ## How keys are discovered @@ -48,7 +48,7 @@ OpenClaw can pick up credentials from: Every reply or tool call uses the **current model provider** (OpenAI, Anthropic, etc). This is the primary source of usage and cost. -See [Models](/providers/models) for pricing config and [Token use & costs](/token-use) for display. +See [Models](/providers/models) for pricing config and [Token use & costs](/reference/token-use) for display. ### 2) Media understanding (audio/image/video) diff --git a/docs/reference/session-management-compaction.md b/docs/reference/session-management-compaction.md index 8f45f61090..3a08575454 100644 --- a/docs/reference/session-management-compaction.md +++ b/docs/reference/session-management-compaction.md @@ -154,7 +154,7 @@ If you’re tuning limits: - The context window comes from the model catalog (and can be overridden via config). - `contextTokens` in the store is a runtime estimate/reporting value; don’t treat it as a strict guarantee. -For more, see [/token-use](/token-use). +For more, see [/token-use](/reference/token-use). --- diff --git a/docs/reference/test.md b/docs/reference/test.md index 1a06991bf9..ca9f906d3e 100644 --- a/docs/reference/test.md +++ b/docs/reference/test.md @@ -7,7 +7,7 @@ title: "Tests" # Tests -- Full testing kit (suites, live, Docker): [Testing](/testing) +- Full testing kit (suites, live, Docker): [Testing](/help/testing) - `pnpm test:force`: Kills any lingering gateway process holding the default control port, then runs the full Vitest suite with an isolated gateway port so server tests don’t collide with a running instance. Use this when a prior gateway run left port 18789 occupied. - `pnpm test:coverage`: Runs Vitest with V8 coverage. Global thresholds are 70% lines/branches/functions/statements. Coverage excludes integration-heavy entrypoints (CLI wiring, gateway/telegram bridges, webchat static server) to keep the target focused on unit-testable logic. diff --git a/docs/token-use.md b/docs/reference/token-use.md similarity index 100% rename from docs/token-use.md rename to docs/reference/token-use.md diff --git a/docs/start/docs-directory.md b/docs/start/docs-directory.md index 683b5c7dd8..b7c283e1aa 100644 --- a/docs/start/docs-directory.md +++ b/docs/start/docs-directory.md @@ -19,7 +19,7 @@ For a complete map of the docs, see [Docs hubs](/start/hubs). - [Slash commands](/tools/slash-commands) - [Multi-agent routing](/concepts/multi-agent) - [Updating and rollback](/install/updating) -- [Pairing (DM and nodes)](/start/pairing) +- [Pairing (DM and nodes)](/channels/pairing) - [Nix mode](/install/nix) - [OpenClaw assistant setup](/start/openclaw) - [Skills](/tools/skills) @@ -41,8 +41,8 @@ For a complete map of the docs, see [Docs hubs](/start/hubs). - [Mattermost (plugin)](/channels/mattermost) - [BlueBubbles (iMessage)](/channels/bluebubbles) - [iMessage (legacy)](/channels/imessage) -- [Groups](/concepts/groups) -- [WhatsApp group messages](/concepts/group-messages) +- [Groups](/channels/groups) +- [WhatsApp group messages](/channels/group-messages) - [Media images](/nodes/images) - [Media audio](/nodes/audio) diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md index 6c38b6e280..928c05c4ac 100644 --- a/docs/start/getting-started.md +++ b/docs/start/getting-started.md @@ -115,6 +115,6 @@ If the Control UI loads, your Gateway is ready for use. ## Next steps -- DM safety and approvals: [Pairing](/start/pairing) +- DM safety and approvals: [Pairing](/channels/pairing) - Connect more channels: [Channels](/channels) - Advanced workflows and from source: [Setup](/start/setup) diff --git a/docs/start/hubs.md b/docs/start/hubs.md index 67467d4568..b573b6009a 100644 --- a/docs/start/hubs.md +++ b/docs/start/hubs.md @@ -61,9 +61,9 @@ Use these hubs to discover every page, including deep dives and reference docs t - [Presence](/concepts/presence) - [Discovery + transports](/gateway/discovery) - [Bonjour](/gateway/bonjour) -- [Channel routing](/concepts/channel-routing) -- [Groups](/concepts/groups) -- [Group messages](/concepts/group-messages) +- [Channel routing](/channels/channel-routing) +- [Groups](/channels/groups) +- [Group messages](/channels/group-messages) - [Model failover](/concepts/model-failover) - [OAuth](/concepts/oauth) @@ -118,7 +118,7 @@ Use these hubs to discover every page, including deep dives and reference docs t - [Models](/concepts/models) - [Sub-agents](/tools/subagents) - [Agent send CLI](/tools/agent-send) -- [Terminal UI](/tui) +- [Terminal UI](/web/tui) - [Browser control](/tools/browser) - [Browser (Linux troubleshooting)](/tools/browser-linux-troubleshooting) - [Polls](/automation/poll) diff --git a/docs/tools/index.md b/docs/tools/index.md index 5ecb51b424..07815dba7e 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -166,7 +166,7 @@ Example (allow only file tools + browser): ## Plugins + tools Plugins can register **additional tools** (and CLI commands) beyond the core set. -See [Plugins](/plugin) for install + config, and [Skills](/tools/skills) for how +See [Plugins](/tools/plugin) for install + config, and [Skills](/tools/skills) for how tool usage guidance is injected into prompts. Some plugins ship their own skills alongside tools (for example, the voice-call plugin). diff --git a/docs/tools/lobster.md b/docs/tools/lobster.md index ed9ed1fb27..31e4e17d52 100644 --- a/docs/tools/lobster.md +++ b/docs/tools/lobster.md @@ -331,7 +331,7 @@ OpenProse pairs well with Lobster: use `/prose` to orchestrate multi-agent prep, ## Learn more -- [Plugins](/plugin) +- [Plugins](/tools/plugin) - [Plugin tool authoring](/plugins/agent-tools) ## Case study: community workflows diff --git a/docs/multi-agent-sandbox-tools.md b/docs/tools/multi-agent-sandbox-tools.md similarity index 100% rename from docs/multi-agent-sandbox-tools.md rename to docs/tools/multi-agent-sandbox-tools.md diff --git a/docs/plugin.md b/docs/tools/plugin.md similarity index 100% rename from docs/plugin.md rename to docs/tools/plugin.md diff --git a/docs/tools/skills.md b/docs/tools/skills.md index b8038ee0fa..1e5fa2c504 100644 --- a/docs/tools/skills.md +++ b/docs/tools/skills.md @@ -44,7 +44,7 @@ Plugins can ship their own skills by listing `skills` directories in `openclaw.plugin.json` (paths relative to the plugin root). Plugin skills load when the plugin is enabled and participate in the normal skill precedence rules. You can gate them via `metadata.openclaw.requires.config` on the plugin’s config -entry. See [Plugins](/plugin) for discovery/config and [Tools](/tools) for the +entry. See [Plugins](/tools/plugin) for discovery/config and [Tools](/tools) for the tool surface those skills teach. ## ClawHub (install + sync) diff --git a/docs/tui.md b/docs/web/tui.md similarity index 100% rename from docs/tui.md rename to docs/web/tui.md diff --git a/docs/zh-CN/hooks.md b/docs/zh-CN/automation/hooks.md similarity index 99% rename from docs/zh-CN/hooks.md rename to docs/zh-CN/automation/hooks.md index b9cea27926..d0a2c890c6 100644 --- a/docs/zh-CN/hooks.md +++ b/docs/zh-CN/automation/hooks.md @@ -9,7 +9,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: 853227a0f1abd20790b425fa64dda60efc6b5f93c1b13ecd2dcb788268f71d79 - source_path: hooks.md + source_path: automation/hooks.md workflow: 15 --- @@ -24,7 +24,7 @@ Hooks 是在事件发生时运行的小脚本。有两种类型： - **Hooks**（本页）：当智能体事件触发时在 Gateway 网关内运行，如 `/new`、`/reset`、`/stop` 或生命周期事件。 - **Webhooks**：外部 HTTP webhooks，让其他系统触发 OpenClaw 中的工作。参见 [Webhook Hooks](/automation/webhook) 或使用 `openclaw webhooks` 获取 Gmail 助手命令。 -Hooks 也可以捆绑在插件中；参见 [插件](/plugin#plugin-hooks)。 +Hooks 也可以捆绑在插件中；参见 [插件](/tools/plugin#plugin-hooks)。 常见用途： diff --git a/docs/zh-CN/automation/troubleshooting.md b/docs/zh-CN/automation/troubleshooting.md new file mode 100644 index 0000000000..3da90add21 --- /dev/null +++ b/docs/zh-CN/automation/troubleshooting.md @@ -0,0 +1,8 @@ +--- +summary: 自动化故障排查：排查 cron 和 heartbeat 调度与投递问题 +title: 自动化故障排查 +--- + +# 自动化故障排查 + +该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Automation Troubleshooting](/automation/troubleshooting)。 diff --git a/docs/zh-CN/channels/bluebubbles.md b/docs/zh-CN/channels/bluebubbles.md index 15e85d0c1d..4ee4cb71e3 100644 --- a/docs/zh-CN/channels/bluebubbles.md +++ b/docs/zh-CN/channels/bluebubbles.md @@ -25,7 +25,7 @@ x-i18n: - OpenClaw 通过其 REST API 与之通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。 - 传入消息通过 webhook 到达；发出的回复、输入指示器、已读回执和 tapback 均为 REST 调用。 - 附件和贴纸作为入站媒体被接收（并在可能时呈现给智能体）。 -- 配对/白名单的工作方式与其他渠道相同（`/start/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。 +- 配对/白名单的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。 - 回应作为系统事件呈现，与 Slack/Telegram 类似，智能体可以在回复前"提及"它们。 - 高级功能：编辑、撤回、回复线程、消息效果、群组管理。 @@ -80,7 +80,7 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor - 批准方式： - `openclaw pairing list bluebubbles` - `openclaw pairing approve bluebubbles ` -- 配对是默认的令牌交换方式。详情：[配对](/start/pairing) +- 配对是默认的令牌交换方式。详情：[配对](/channels/pairing) 群组： @@ -268,4 +268,4 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。 - OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果在 macOS 26（Tahoe）上编辑仍然显示，请使用 `channels.bluebubbles.actions.edit=false` 手动禁用。 - 查看状态/健康信息：`openclaw status --all` 或 `openclaw status --deep`。 -有关通用渠道工作流参考，请参阅[渠道](/channels)和[插件](/plugins)指南。 +有关通用渠道工作流参考，请参阅[渠道](/channels)和[插件](/tools/plugin)指南。 diff --git a/docs/zh-CN/broadcast-groups.md b/docs/zh-CN/channels/broadcast-groups.md similarity index 98% rename from docs/zh-CN/broadcast-groups.md rename to docs/zh-CN/channels/broadcast-groups.md index dff1e9c814..fc76f38a0c 100644 --- a/docs/zh-CN/broadcast-groups.md +++ b/docs/zh-CN/channels/broadcast-groups.md @@ -10,7 +10,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: eaeb4035912c49413e012177cf0bd28b348130d30d3317674418dca728229b70 - source_path: broadcast-groups.md + source_path: channels/broadcast-groups.md workflow: 15 --- @@ -444,6 +444,6 @@ interface OpenClawConfig { ## 另请参阅 -- [多智能体配置](/multi-agent-sandbox-tools) -- [路由配置](/concepts/channel-routing) +- [多智能体配置](/tools/multi-agent-sandbox-tools) +- [路由配置](/channels/channel-routing) - [会话管理](/concepts/sessions) diff --git a/docs/zh-CN/concepts/channel-routing.md b/docs/zh-CN/channels/channel-routing.md similarity index 97% rename from docs/zh-CN/concepts/channel-routing.md rename to docs/zh-CN/channels/channel-routing.md index 57fc2aba5a..d307d41e4f 100644 --- a/docs/zh-CN/concepts/channel-routing.md +++ b/docs/zh-CN/channels/channel-routing.md @@ -8,7 +8,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: 1a322b5187e32c82fc1e8aac02437e2eeb7ba84e7b3a1db89feeab1dcf7dbbab - source_path: concepts/channel-routing.md + source_path: channels/channel-routing.md workflow: 14 --- @@ -73,7 +73,7 @@ OpenClaw 将回复**路由回消息来源的渠道**。模型不会选择渠道 } ``` -参见：[广播组](/broadcast-groups)。 +参见：[广播组](/channels/broadcast-groups)。 ## 配置概览 diff --git a/docs/zh-CN/concepts/group-messages.md b/docs/zh-CN/channels/group-messages.md similarity index 99% rename from docs/zh-CN/concepts/group-messages.md rename to docs/zh-CN/channels/group-messages.md index 292c9bdbb5..ca9762f209 100644 --- a/docs/zh-CN/concepts/group-messages.md +++ b/docs/zh-CN/channels/group-messages.md @@ -8,7 +8,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: 181a72f12f5021af77c2e4c913120f711e0c0bc271d218d75cb6fe80dab675bb - source_path: concepts/group-messages.md + source_path: channels/group-messages.md workflow: 15 --- diff --git a/docs/zh-CN/concepts/groups.md b/docs/zh-CN/channels/groups.md similarity index 99% rename from docs/zh-CN/concepts/groups.md rename to docs/zh-CN/channels/groups.md index 05fc637fe7..54d103f204 100644 --- a/docs/zh-CN/concepts/groups.md +++ b/docs/zh-CN/channels/groups.md @@ -8,7 +8,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: b727a053edf51f6e7b5c0c324c2fc9c9789a9796c37f622418bd555e8b5a0ec4 - source_path: concepts/groups.md + source_path: channels/groups.md workflow: 15 --- @@ -376,4 +376,4 @@ requireMention? 是 -> 被提及? 否 -> 仅存储为上下文 ## WhatsApp 特定内容 -参见[群消息](/concepts/group-messages)了解 WhatsApp 专有行为（历史注入、提及处理详情）。 +参见[群消息](/channels/group-messages)了解 WhatsApp 专有行为（历史注入、提及处理详情）。 diff --git a/docs/zh-CN/channels/imessage.md b/docs/zh-CN/channels/imessage.md index 84ab14103b..4f02e2fe0d 100644 --- a/docs/zh-CN/channels/imessage.md +++ b/docs/zh-CN/channels/imessage.md @@ -205,7 +205,7 @@ exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@" - 批准方式： - `openclaw pairing list imessage` - `openclaw pairing approve imessage ` -- 配对是 iMessage 私信的默认令牌交换方式。详情：[配对](/start/pairing) +- 配对是 iMessage 私信的默认令牌交换方式。详情：[配对](/channels/pairing) 群组： diff --git a/docs/zh-CN/channels/index.md b/docs/zh-CN/channels/index.md index c48670711f..a41f0a28c5 100644 --- a/docs/zh-CN/channels/index.md +++ b/docs/zh-CN/channels/index.md @@ -46,7 +46,7 @@ OpenClaw 可以在你已经使用的任何聊天应用上与你交流。每个 - 渠道可以同时运行；配置多个渠道后，OpenClaw 会按聊天进行路由。 - 最快的设置方式通常是 **Telegram**（简单的机器人令牌）。WhatsApp 需要二维码配对， 并在磁盘上存储更多状态。 -- 群组行为因渠道而异；参见[群组](/concepts/groups)。 +- 群组行为因渠道而异；参见[群组](/channels/groups)。 - 为安全起见，私信配对和允许列表会被强制执行；参见[安全](/gateway/security)。 - Telegram 内部机制：[grammY 说明](/channels/grammy)。 - 故障排除：[渠道故障排除](/channels/troubleshooting)。 diff --git a/docs/zh-CN/channels/matrix.md b/docs/zh-CN/channels/matrix.md index d793560125..4bfe4ed263 100644 --- a/docs/zh-CN/channels/matrix.md +++ b/docs/zh-CN/channels/matrix.md @@ -36,7 +36,7 @@ openclaw plugins install ./extensions/matrix 如果你在配置/新手引导期间选择 Matrix 并检测到 git 检出，OpenClaw 将自动提供本地安装路径。 -详情：[插件](/plugin) +详情：[插件](/tools/plugin) ## 设置 diff --git a/docs/zh-CN/channels/mattermost.md b/docs/zh-CN/channels/mattermost.md index 67cb5897dc..c4cb938b2f 100644 --- a/docs/zh-CN/channels/mattermost.md +++ b/docs/zh-CN/channels/mattermost.md @@ -37,7 +37,7 @@ openclaw plugins install ./extensions/mattermost 如果你在配置/新手引导期间选择 Mattermost 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。 -详情：[插件](/plugin) +详情：[插件](/tools/plugin) ## 快速设置 diff --git a/docs/zh-CN/channels/msteams.md b/docs/zh-CN/channels/msteams.md index e957ee0e56..78ba28f373 100644 --- a/docs/zh-CN/channels/msteams.md +++ b/docs/zh-CN/channels/msteams.md @@ -43,7 +43,7 @@ openclaw plugins install ./extensions/msteams 如果你在配置/新手引导过程中选择 Teams 并检测到 git 检出， OpenClaw 将自动提供本地安装路径。 -详情：[插件](/plugin) +详情：[插件](/tools/plugin) ## 快速设置（初学者） diff --git a/docs/zh-CN/channels/nextcloud-talk.md b/docs/zh-CN/channels/nextcloud-talk.md index e3cad25edf..0b07b94126 100644 --- a/docs/zh-CN/channels/nextcloud-talk.md +++ b/docs/zh-CN/channels/nextcloud-talk.md @@ -35,7 +35,7 @@ openclaw plugins install ./extensions/nextcloud-talk 如果你在配置/新手引导过程中选择了 Nextcloud Talk，并且检测到 git 检出， OpenClaw 将自动提供本地安装路径。 -详情：[插件](/plugin) +详情：[插件](/tools/plugin) ## 快速设置（新手） diff --git a/docs/zh-CN/start/pairing.md b/docs/zh-CN/channels/pairing.md similarity index 98% rename from docs/zh-CN/start/pairing.md rename to docs/zh-CN/channels/pairing.md index d0eb7058b0..03c04baacb 100644 --- a/docs/zh-CN/start/pairing.md +++ b/docs/zh-CN/channels/pairing.md @@ -10,7 +10,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: c46a5c39f289c8fd0783baacd927f550c3d3ae8889a7bc7de133b795f16fa08a - source_path: start/pairing.md + source_path: channels/pairing.md workflow: 15 --- diff --git a/docs/zh-CN/channels/signal.md b/docs/zh-CN/channels/signal.md index ec3c0ff13c..c6410cddcf 100644 --- a/docs/zh-CN/channels/signal.md +++ b/docs/zh-CN/channels/signal.md @@ -116,7 +116,7 @@ x-i18n: - 通过以下方式批准： - `openclaw pairing list signal` - `openclaw pairing approve signal ` -- 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/start/pairing) +- 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/channels/pairing) - 仅有 UUID 的发送者（来自 `sourceUuid`）在 `channels.signal.allowFrom` 中存储为 `uuid:`。 群组： diff --git a/docs/zh-CN/channels/telegram.md b/docs/zh-CN/channels/telegram.md index e51418ba58..90a21149e3 100644 --- a/docs/zh-CN/channels/telegram.md +++ b/docs/zh-CN/channels/telegram.md @@ -356,7 +356,7 @@ Telegram 功能可以在两个级别配置（上面显示的对象形式；旧 - 批准方式： - `openclaw pairing list telegram` - `openclaw pairing approve telegram ` -- 配对是 Telegram 私信使用的默认 token 交换。详情：[配对](/start/pairing) +- 配对是 Telegram 私信使用的默认 token 交换。详情：[配对](/channels/pairing) - `channels.telegram.allowFrom` 接受数字用户 ID（推荐）或 `@username` 条目。这**不是**机器人用户名；使用人类发送者的 ID。向导接受 `@username` 并在可能时将其解析为数字 ID。 #### 查找你的 Telegram 用户 ID diff --git a/docs/zh-CN/channels/tlon.md b/docs/zh-CN/channels/tlon.md index e71bcd3fee..2e13d1ed86 100644 --- a/docs/zh-CN/channels/tlon.md +++ b/docs/zh-CN/channels/tlon.md @@ -34,7 +34,7 @@ openclaw plugins install @openclaw/tlon openclaw plugins install ./extensions/tlon ``` -详情：[插件](/plugin) +详情：[插件](/tools/plugin) ## 设置 diff --git a/docs/zh-CN/channels/twitch.md b/docs/zh-CN/channels/twitch.md index 05a0d352da..ea07603e64 100644 --- a/docs/zh-CN/channels/twitch.md +++ b/docs/zh-CN/channels/twitch.md @@ -32,7 +32,7 @@ openclaw plugins install @openclaw/twitch openclaw plugins install ./extensions/twitch ``` -详情：[插件](/plugin) +详情：[插件](/tools/plugin) ## 快速设置（新手） diff --git a/docs/zh-CN/channels/zalo.md b/docs/zh-CN/channels/zalo.md index b1378e0ab7..a8d83439d0 100644 --- a/docs/zh-CN/channels/zalo.md +++ b/docs/zh-CN/channels/zalo.md @@ -22,7 +22,7 @@ Zalo 以插件形式提供，不包含在核心安装中。 - 通过 CLI 安装：`openclaw plugins install @openclaw/zalo` - 或在新手引导期间选择 **Zalo** 并确认安装提示 -- 详情：[插件](/plugin) +- 详情：[插件](/tools/plugin) ## 快速设置（初学者） @@ -111,7 +111,7 @@ Zalo 是一款专注于越南市场的即时通讯应用；其 Bot API 让 Gatew - 通过以下方式批准： - `openclaw pairing list zalo` - `openclaw pairing approve zalo ` -- 配对是默认的令牌交换方式。详情：[配对](/start/pairing) +- 配对是默认的令牌交换方式。详情：[配对](/channels/pairing) - `channels.zalo.allowFrom` 接受数字用户 ID（无用户名查找功能）。 ## 长轮询与 webhook diff --git a/docs/zh-CN/channels/zalouser.md b/docs/zh-CN/channels/zalouser.md index 36630ddd78..8b6962fb3e 100644 --- a/docs/zh-CN/channels/zalouser.md +++ b/docs/zh-CN/channels/zalouser.md @@ -25,7 +25,7 @@ Zalo Personal 作为插件提供，不包含在核心安装中。 - 通过 CLI 安装：`openclaw plugins install @openclaw/zalouser` - 或从源码检出安装：`openclaw plugins install ./extensions/zalouser` -- 详情：[插件](/plugin) +- 详情：[插件](/tools/plugin) ## 前置条件：zca-cli diff --git a/docs/zh-CN/cli/hooks.md b/docs/zh-CN/cli/hooks.md index e06ed6ca24..02c2a62e8d 100644 --- a/docs/zh-CN/cli/hooks.md +++ b/docs/zh-CN/cli/hooks.md @@ -19,8 +19,8 @@ x-i18n: 相关内容： -- 钩子：[钩子](/hooks) -- 插件钩子：[插件](/plugin#plugin-hooks) +- 钩子：[钩子](/automation/hooks) +- 插件钩子：[插件](/tools/plugin#plugin-hooks) ## 列出所有钩子 @@ -255,7 +255,7 @@ openclaw hooks enable session-memory **输出：** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md` -**参见：** [session-memory 文档](/hooks#session-memory) +**参见：** [session-memory 文档](/automation/hooks#session-memory) ### command-logger @@ -282,7 +282,7 @@ cat ~/.openclaw/logs/commands.log | jq . grep '"action":"new"' ~/.openclaw/logs/commands.log | jq . ``` -**参见：** [command-logger 文档](/hooks#command-logger) +**参见：** [command-logger 文档](/automation/hooks#command-logger) ### soul-evil @@ -308,4 +308,4 @@ openclaw hooks enable soul-evil openclaw hooks enable boot-md ``` -**参见：** [boot-md 文档](/hooks#boot-md) +**参见：** [boot-md 文档](/automation/hooks#boot-md) diff --git a/docs/zh-CN/cli/index.md b/docs/zh-CN/cli/index.md index 41a9af26e8..c22fad5c4b 100644 --- a/docs/zh-CN/cli/index.md +++ b/docs/zh-CN/cli/index.md @@ -262,7 +262,7 @@ openclaw [--dev] [--profile ] - `openclaw plugins enable ` / `disable ` — 切换 `plugins.entries..enabled`。 - `openclaw plugins doctor` — 报告插件加载错误。 -大多数插件更改需要重启 Gateway 网关。参见 [/plugin](/plugin)。 +大多数插件更改需要重启 Gateway 网关。参见 [/plugin](/tools/plugin)。 ## 记忆 diff --git a/docs/zh-CN/cli/memory.md b/docs/zh-CN/cli/memory.md index 0e9f0b2a0f..514ca3b398 100644 --- a/docs/zh-CN/cli/memory.md +++ b/docs/zh-CN/cli/memory.md @@ -21,7 +21,7 @@ x-i18n: 相关内容： - 记忆概念：[记忆](/concepts/memory) -- 插件：[插件](/plugins) +- 插件：[插件](/tools/plugin) ## 示例 diff --git a/docs/zh-CN/cli/pairing.md b/docs/zh-CN/cli/pairing.md index f289bebfe1..491c45c696 100644 --- a/docs/zh-CN/cli/pairing.md +++ b/docs/zh-CN/cli/pairing.md @@ -18,7 +18,7 @@ x-i18n: 相关内容： -- 配对流程：[配对](/start/pairing) +- 配对流程：[配对](/channels/pairing) ## 命令 diff --git a/docs/zh-CN/cli/plugins.md b/docs/zh-CN/cli/plugins.md index 8cd278628a..465df8d233 100644 --- a/docs/zh-CN/cli/plugins.md +++ b/docs/zh-CN/cli/plugins.md @@ -19,7 +19,7 @@ x-i18n: 相关内容： -- 插件系统：[插件](/plugin) +- 插件系统：[插件](/tools/plugin) - 插件清单 + 模式：[插件清单](/plugins/manifest) - 安全加固：[安全](/gateway/security) diff --git a/docs/zh-CN/cli/tui.md b/docs/zh-CN/cli/tui.md index 8d0bc2e5b7..1c92603b9b 100644 --- a/docs/zh-CN/cli/tui.md +++ b/docs/zh-CN/cli/tui.md @@ -19,7 +19,7 @@ x-i18n: 相关： -- TUI 指南：[TUI](/tui) +- TUI 指南：[TUI](/web/tui) ## 示例 diff --git a/docs/zh-CN/concepts/agent-loop.md b/docs/zh-CN/concepts/agent-loop.md index f19f91e601..68e9c8ee36 100644 --- a/docs/zh-CN/concepts/agent-loop.md +++ b/docs/zh-CN/concepts/agent-loop.md @@ -76,7 +76,7 @@ OpenClaw 有两个钩子系统： - **`agent:bootstrap`**：在系统提示最终确定之前构建引导文件时运行。用于添加/删除引导上下文文件。 - **命令钩子**：`/new`、`/reset`、`/stop` 和其他命令事件（参见钩子文档）。 -参见[钩子](/hooks)了解设置和示例。 +参见[钩子](/automation/hooks)了解设置和示例。 ### 插件钩子（智能体 + Gateway 网关生命周期） @@ -91,7 +91,7 @@ OpenClaw 有两个钩子系统： - **`session_start` / `session_end`**：会话生命周期边界。 - **`gateway_start` / `gateway_stop`**：Gateway 网关生命周期事件。 -参见[插件](/plugin#plugin-hooks)了解钩子 API 和注册详情。 +参见[插件](/tools/plugin#plugin-hooks)了解钩子 API 和注册详情。 ## 流式传输 + 部分回复 diff --git a/docs/zh-CN/concepts/agent-workspace.md b/docs/zh-CN/concepts/agent-workspace.md index f2ccb9130f..7438a790d2 100644 --- a/docs/zh-CN/concepts/agent-workspace.md +++ b/docs/zh-CN/concepts/agent-workspace.md @@ -215,5 +215,5 @@ git push ## 高级注意事项 - 多智能体路由可以为每个智能体使用不同的工作区。参见 - [渠道路由](/concepts/channel-routing) 了解路由配置。 + [渠道路由](/channels/channel-routing) 了解路由配置。 - 如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用每会话沙箱工作区。 diff --git a/docs/zh-CN/concepts/agent.md b/docs/zh-CN/concepts/agent.md index 2656c0502e..dc8cb52327 100644 --- a/docs/zh-CN/concepts/agent.md +++ b/docs/zh-CN/concepts/agent.md @@ -112,4 +112,4 @@ OpenClaw 复用 pi-mono 代码库的部分内容（模型/工具），但**会 --- -_下一篇：[群聊](/concepts/group-messages)_ 🦞 +_下一篇：[群聊](/channels/group-messages)_ 🦞 diff --git a/docs/zh-CN/concepts/architecture.md b/docs/zh-CN/concepts/architecture.md index 9069f21785..abfaa064d6 100644 --- a/docs/zh-CN/concepts/architecture.md +++ b/docs/zh-CN/concepts/architecture.md @@ -92,7 +92,7 @@ Client Gateway - **非本地**连接必须签名 `connect.challenge` nonce 并需要明确批准。 - Gateway 网关认证（`gateway.auth.*`）仍适用于**所有**连接，无论本地还是远程。 -详情：[Gateway 网关协议](/gateway/protocol)、[配对](/start/pairing)、[安全](/gateway/security)。 +详情：[Gateway 网关协议](/gateway/protocol)、[配对](/channels/pairing)、[安全](/gateway/security)。 ## 协议类型和代码生成 diff --git a/docs/zh-CN/concepts/context.md b/docs/zh-CN/concepts/context.md index 6896c33dab..9950b9ccbe 100644 --- a/docs/zh-CN/concepts/context.md +++ b/docs/zh-CN/concepts/context.md @@ -34,7 +34,7 @@ x-i18n: - `/usage tokens` → 在正常回复后附加每次回复的使用量页脚。 - `/compact` → 将较旧的历史总结为紧凑条目以释放窗口空间。 -另请参阅：[斜杠命令](/tools/slash-commands)、[Token 使用与成本](/token-use)、[压缩](/concepts/compaction)。 +另请参阅：[斜杠命令](/tools/slash-commands)、[Token 使用与成本](/reference/token-use)、[压缩](/concepts/compaction)。 ## 示例输出 diff --git a/docs/zh-CN/concepts/messages.md b/docs/zh-CN/concepts/messages.md index d27e77f37e..1b1651b5ef 100644 --- a/docs/zh-CN/concepts/messages.md +++ b/docs/zh-CN/concepts/messages.md @@ -129,7 +129,7 @@ OpenClaw 可以显示或隐藏模型推理： - 当模型产生推理内容时，它仍计入 token 使用量。 - Telegram 支持将推理流式传输到草稿气泡中。 -详情：[思考 + 推理指令](/tools/thinking)和 [Token 使用](/token-use)。 +详情：[思考 + 推理指令](/tools/thinking)和 [Token 使用](/reference/token-use)。 ## 前缀、线程和回复 diff --git a/docs/zh-CN/concepts/models.md b/docs/zh-CN/concepts/models.md index 2ac312fc19..01bb8e1420 100644 --- a/docs/zh-CN/concepts/models.md +++ b/docs/zh-CN/concepts/models.md @@ -185,7 +185,7 @@ openclaw models status 输入 - OpenRouter `/models` 列表（筛选 `:free`） -- 需要来自认证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/environment)） +- 需要来自认证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/help/environment)） - 可选筛选器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` - 探测控制：`--timeout`、`--concurrency` diff --git a/docs/zh-CN/concepts/multi-agent.md b/docs/zh-CN/concepts/multi-agent.md index b911356255..047f2ce272 100644 --- a/docs/zh-CN/concepts/multi-agent.md +++ b/docs/zh-CN/concepts/multi-agent.md @@ -113,7 +113,7 @@ openclaw agents list --bindings 注意事项： - 私信访问控制是**每 WhatsApp 账户全局的**（配对/允许列表），而不是每智能体。 -- 对于共享群组，将群组绑定到一个智能体或使用 [广播群组](/broadcast-groups)。 +- 对于共享群组，将群组绑定到一个智能体或使用 [广播群组](/channels/broadcast-groups)。 ## 路由规则（消息如何选择智能体） @@ -369,4 +369,4 @@ openclaw agents list --bindings 如果你需要每智能体边界，使用 `agents.list[].tools` 拒绝 `exec`。 对于群组定向，使用 `agents.list[].groupChat.mentionPatterns` 使 @提及清晰地映射到目标智能体。 -参见 [多智能体沙箱和工具](/multi-agent-sandbox-tools) 了解详细示例。 +参见 [多智能体沙箱和工具](/tools/multi-agent-sandbox-tools) 了解详细示例。 diff --git a/docs/zh-CN/experiments/plans/group-policy-hardening.md b/docs/zh-CN/experiments/plans/group-policy-hardening.md index 8147bf1440..afbb8b39d6 100644 --- a/docs/zh-CN/experiments/plans/group-policy-hardening.md +++ b/docs/zh-CN/experiments/plans/group-policy-hardening.md @@ -41,5 +41,5 @@ Telegram 允许列表现在不区分大小写地接受 `telegram:` 和 `tg:` 前 ## 相关文档 -- [群聊](/concepts/groups) +- [群聊](/channels/groups) - [Telegram 提供商](/channels/telegram) diff --git a/docs/zh-CN/gateway/configuration.md b/docs/zh-CN/gateway/configuration.md index 67fda2f0c3..cd269cef3b 100644 --- a/docs/zh-CN/gateway/configuration.md +++ b/docs/zh-CN/gateway/configuration.md @@ -294,7 +294,7 @@ OpenClaw 从父进程（shell、launchd/systemd、CI 等）读取环境变量。 } ``` -参见 [/environment](/environment) 了解优先级和来源详情。 +参见 [/environment](/help/environment) 了解优先级和来源详情。 ### `env.shellEnv`（可选） @@ -789,7 +789,7 @@ OpenClaw 在以下位置存储**每个智能体的**认证配置文件（OAuth + - **只读**工具 + 工作区 - **无文件系统访问**（仅消息/会话工具） -参见[多智能体沙箱与工具](/multi-agent-sandbox-tools)了解优先级和更多示例。 +参见[多智能体沙箱与工具](/tools/multi-agent-sandbox-tools)了解优先级和更多示例。 完全访问（无沙箱）： @@ -2780,7 +2780,7 @@ Z.AI 模型通过内置的 `zai` 提供商提供。在环境中设置 `ZAI_API_K ### `plugins`（扩展） 控制插件发现、允许/拒绝和每插件配置。插件从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及任何 `plugins.load.paths` 条目加载。**配置更改需要重启 Gateway 网关。** -参见 [/plugin](/plugin) 了解详情。 +参见 [/plugin](/tools/plugin) 了解详情。 字段： diff --git a/docs/zh-CN/gateway/heartbeat.md b/docs/zh-CN/gateway/heartbeat.md index 761f3bf272..97e12182a9 100644 --- a/docs/zh-CN/gateway/heartbeat.md +++ b/docs/zh-CN/gateway/heartbeat.md @@ -137,7 +137,7 @@ x-i18n: - `session`：心跳运行的可选会话键。 - `main`（默认）：智能体主会话。 - 显式会话键（从 `openclaw sessions --json` 或 [sessions CLI](/cli/sessions) 复制）。 - - 会话键格式：参见[会话](/concepts/session)和[群组](/concepts/groups)。 + - 会话键格式：参见[会话](/concepts/session)和[群组](/channels/groups)。 - `target`： - `last`（默认）：发送到最后使用的外部渠道。 - 显式渠道：`whatsapp` / `telegram` / `discord` / `googlechat` / `slack` / `msteams` / `signal` / `imessage`。 diff --git a/docs/zh-CN/gateway/sandboxing.md b/docs/zh-CN/gateway/sandboxing.md index 8092a9a079..8db652bef9 100644 --- a/docs/zh-CN/gateway/sandboxing.md +++ b/docs/zh-CN/gateway/sandboxing.md @@ -163,7 +163,7 @@ Docker 安装和容器化 Gateway 网关在此： 每个智能体可以覆盖沙箱 + 工具： `agents.list[].sandbox` 和 `agents.list[].tools`（加上 `agents.list[].tools.sandbox.tools` 用于沙箱工具策略）。 -参见[多智能体沙箱与工具](/multi-agent-sandbox-tools)了解优先级。 +参见[多智能体沙箱与工具](/tools/multi-agent-sandbox-tools)了解优先级。 ## 最小启用示例 @@ -184,5 +184,5 @@ Docker 安装和容器化 Gateway 网关在此： ## 相关文档 - [沙箱配置](/gateway/configuration#agentsdefaults-sandbox) -- [多智能体沙箱与工具](/multi-agent-sandbox-tools) +- [多智能体沙箱与工具](/tools/multi-agent-sandbox-tools) - [安全](/gateway/security) diff --git a/docs/zh-CN/gateway/security/formal-verification.md b/docs/zh-CN/gateway/security/formal-verification.md deleted file mode 100644 index 532d99eaec..0000000000 --- a/docs/zh-CN/gateway/security/formal-verification.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -permalink: /security/formal-verification/ -summary: 针对 OpenClaw 最高风险路径的机器检查安全模型。 -title: 形式化验证（安全模型） -x-i18n: - generated_at: "2026-02-03T07:49:03Z" - model: claude-opus-4-5 - provider: pi - source_hash: 8dff6ea41a37fb6b870424e4e788015c3f8a6099075eece5dbf909883c045106 - source_path: gateway/security/formal-verification.md - workflow: 15 ---- - -# 形式化验证（安全模型） - -本页跟踪 OpenClaw 的**形式化安全模型**（目前是 TLA+/TLC；根据需要会增加更多）。 - -> 注意：一些较旧的链接可能引用以前的项目名称。 - -**目标（北极星）：** 在明确的假设下，提供机器检查的论证，证明 OpenClaw 执行其预期的安全策略（授权、会话隔离、工具限制和错误配置安全）。 - -**目前是什么：** 一个可执行的、攻击者驱动的**安全回归套件**： - -- 每个声明都有一个在有限状态空间上运行的模型检查。 -- 许多声明有一个配对的**负面模型**，为现实的错误类别生成反例轨迹。 - -**目前还不是什么：** 证明"OpenClaw 在所有方面都是安全的"或完整的 TypeScript 实现是正确的。 - -## 模型存放位置 - -模型维护在单独的仓库中：[vignesh07/openclaw-formal-models](https://github.com/vignesh07/openclaw-formal-models)。 - -## 重要注意事项 - -- 这些是**模型**，不是完整的 TypeScript 实现。模型和代码之间可能存在偏差。 -- 结果受 TLC 探索的状态空间限制；"绿色"并不意味着超出建模假设和边界的安全性。 -- 一些声明依赖于明确的环境假设（例如，正确的部署、正确的配置输入）。 - -## 重现结果 - -目前，通过在本地克隆模型仓库并运行 TLC 来重现结果（见下文）。未来的迭代可能提供： - -- 带有公开产物（反例轨迹、运行日志）的 CI 运行模型 -- 用于小型有界检查的托管"运行此模型"工作流 - -入门： - -```bash -git clone https://github.com/vignesh07/openclaw-formal-models -cd openclaw-formal-models - -# 需要 Java 11+（TLC 在 JVM 上运行）。 -# 仓库附带一个固定版本的 `tla2tools.jar`（TLA+ 工具）并提供 `bin/tlc` + Make 目标。 - -make -``` - -### Gateway 网关暴露和开放 Gateway 网关错误配置 - -**声明：** 在没有认证的情况下绑定到 loopback 之外可能导致远程攻击 / 增加暴露；令牌/密码阻止未授权攻击者（根据模型假设）。 - -- 绿色运行： - - `make gateway-exposure-v2` - - `make gateway-exposure-v2-protected` -- 红色（预期）： - - `make gateway-exposure-v2-negative` - -另请参阅：模型仓库中的 `docs/gateway-exposure-matrix.md`。 - -### Nodes.run 管道（最高风险能力） - -**声明：** `nodes.run` 需要 (a) 节点命令允许列表加上声明的命令，以及 (b) 配置时的实时批准；批准是令牌化的以防止重放（在模型中）。 - -- 绿色运行： - - `make nodes-pipeline` - - `make approvals-token` -- 红色（预期）： - - `make nodes-pipeline-negative` - - `make approvals-token-negative` - -### 配对存储（私信限制） - -**声明：** 配对请求遵守 TTL 和待处理请求上限。 - -- 绿色运行： - - `make pairing` - - `make pairing-cap` -- 红色（预期）： - - `make pairing-negative` - - `make pairing-cap-negative` - -### 入站限制（提及 + 控制命令绕过） - -**声明：** 在需要提及的群组上下文中，未授权的"控制命令"无法绕过提及限制。 - -- 绿色： - - `make ingress-gating` -- 红色（预期）： - - `make ingress-gating-negative` - -### 路由/会话键隔离 - -**声明：** 来自不同对等方的私信不会合并到同一会话中，除非明确链接/配置。 - -- 绿色： - - `make routing-isolation` -- 红色（预期）： - - `make routing-isolation-negative` - -## v1++：额外的有界模型（并发、重试、轨迹正确性） - -这些是后续模型，围绕真实世界的故障模式（非原子更新、重试和消息扇出）提高保真度。 - -### 配对存储并发/幂等性 - -**声明：** 即使在交错执行下，配对存储也应强制执行 `MaxPending` 和幂等性（即"检查后写入"必须是原子/锁定的；刷新不应创建重复项）。 - -这意味着： - -- 在并发请求下，你不能超过渠道的 `MaxPending`。 -- 对同一 `(channel, sender)` 的重复请求/刷新不应创建重复的活动待处理行。 - -- 绿色运行： - - `make pairing-race`（原子/锁定上限检查） - - `make pairing-idempotency` - - `make pairing-refresh` - - `make pairing-refresh-race` -- 红色（预期）： - - `make pairing-race-negative`（非原子 begin/commit 上限竞争） - - `make pairing-idempotency-negative` - - `make pairing-refresh-negative` - - `make pairing-refresh-race-negative` - -### 入站轨迹关联/幂等性 - -**声明：** 摄取应在扇出时保留轨迹关联，并在提供商重试下保持幂等。 - -这意味着： - -- 当一个外部事件变成多个内部消息时，每个部分保持相同的轨迹/事件标识。 -- 重试不会导致重复处理。 -- 如果缺少提供商事件 ID，去重会回退到安全键（例如轨迹 ID）以避免丢弃不同的事件。 - -- 绿色： - - `make ingress-trace` - - `make ingress-trace2` - - `make ingress-idempotency` - - `make ingress-dedupe-fallback` -- 红色（预期）： - - `make ingress-trace-negative` - - `make ingress-trace2-negative` - - `make ingress-idempotency-negative` - - `make ingress-dedupe-fallback-negative` - -### 路由 dmScope 优先级 + identityLinks - -**声明：** 路由必须默认保持私信会话隔离，仅在明确配置时合并会话（渠道优先级 + 身份链接）。 - -这意味着： - -- 渠道特定的 dmScope 覆盖必须优先于全局默认值。 -- identityLinks 应仅在明确链接的组内合并，而不是跨不相关的对等方。 - -- 绿色： - - `make routing-precedence` - - `make routing-identitylinks` -- 红色（预期）： - - `make routing-precedence-negative` - - `make routing-identitylinks-negative` diff --git a/docs/zh-CN/gateway/security/index.md b/docs/zh-CN/gateway/security/index.md index 63f3e2d998..02fc1b16e2 100644 --- a/docs/zh-CN/gateway/security/index.md +++ b/docs/zh-CN/gateway/security/index.md @@ -169,7 +169,7 @@ OpenClaw 的立场： - OpenClaw 使用 `npm pack` 然后在该目录中运行 `npm install --omit=dev`（npm 生命周期脚本可以在安装期间执行代码）。 - 优先使用固定的精确版本（`@scope/pkg@1.2.3`），并在启用之前检查磁盘上解压的代码。 -详情：[插件](/plugin) +详情：[插件](/tools/plugin) ## 私信访问模型（配对/白名单/开放/禁用） @@ -187,7 +187,7 @@ openclaw pairing list openclaw pairing approve ``` -详情 + 磁盘上的文件：[配对](/start/pairing) +详情 + 磁盘上的文件：[配对](/channels/pairing) ## 私信会话隔离（多用户模式） @@ -214,7 +214,7 @@ OpenClaw 有两个独立的"谁可以触发我？"层： - `channels.discord.guilds` / `channels.slack.channels`：单平台白名单 + 提及默认值。 - **安全说明：** 将 `dmPolicy="open"` 和 `groupPolicy="open"` 视为最后手段的设置。应该很少使用；除非你完全信任房间的每个成员，否则优先使用配对 + 白名单。 -详情：[配置](/gateway/configuration)和[群组](/concepts/groups) +详情：[配置](/gateway/configuration)和[群组](/channels/groups) ## 提示词注入（是什么，为什么重要） @@ -584,7 +584,7 @@ Doctor 可以为你生成一个：`openclaw doctor --generate-gateway-token`。 ## 单智能体访问配置（多智能体） -通过多智能体路由，每个智能体可以有自己的沙箱 + 工具策略：使用这个为每个智能体提供**完全访问**、**只读**或**无访问**权限。参见[多智能体沙箱和工具](/multi-agent-sandbox-tools)了解详情和优先级规则。 +通过多智能体路由，每个智能体可以有自己的沙箱 + 工具策略：使用这个为每个智能体提供**完全访问**、**只读**或**无访问**权限。参见[多智能体沙箱和工具](/tools/multi-agent-sandbox-tools)了解详情和优先级规则。 常见用例： diff --git a/docs/zh-CN/debugging.md b/docs/zh-CN/help/debugging.md similarity index 99% rename from docs/zh-CN/debugging.md rename to docs/zh-CN/help/debugging.md index 0c7fb6cbfa..19f6486390 100644 --- a/docs/zh-CN/debugging.md +++ b/docs/zh-CN/help/debugging.md @@ -10,7 +10,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: 504c824bff4790006c8b73600daca66b919e049178e9711e6e65b6254731911a - source_path: debugging.md + source_path: help/debugging.md workflow: 15 --- diff --git a/docs/zh-CN/environment.md b/docs/zh-CN/help/environment.md similarity index 98% rename from docs/zh-CN/environment.md rename to docs/zh-CN/help/environment.md index 2e83d2e05b..e91b00c744 100644 --- a/docs/zh-CN/environment.md +++ b/docs/zh-CN/help/environment.md @@ -10,7 +10,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: b49ae50e5d306612f89f93a86236188a4f2ec23f667e2388b043832be3ac1546 - source_path: environment.md + source_path: help/environment.md workflow: 15 --- diff --git a/docs/zh-CN/help/faq.md b/docs/zh-CN/help/faq.md index f155112379..3d9742c2b2 100644 --- a/docs/zh-CN/help/faq.md +++ b/docs/zh-CN/help/faq.md @@ -669,7 +669,7 @@ claude setup-token ### 支持 AWS Bedrock 吗 -是的——通过 pi-ai 的 **Amazon Bedrock (Converse)** 提供商进行**手动配置**。你必须在 Gateway 网关主机上提供 AWS 凭据/区域，并在模型配置中添加 Bedrock 提供商条目。参阅 [Amazon Bedrock](/bedrock) 和[模型提供商](/providers/models)。如果你更喜欢托管密钥流程，在 Bedrock 前面使用兼容 OpenAI 的代理仍然是有效选项。 +是的——通过 pi-ai 的 **Amazon Bedrock (Converse)** 提供商进行**手动配置**。你必须在 Gateway 网关主机上提供 AWS 凭据/区域，并在模型配置中添加 Bedrock 提供商条目。参阅 [Amazon Bedrock](/providers/bedrock) 和[模型提供商](/providers/models)。如果你更喜欢托管密钥流程，在 Bedrock 前面使用兼容 OpenAI 的代理仍然是有效选项。 ### Codex 认证如何工作 @@ -1094,7 +1094,7 @@ openclaw browser extension path 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/频道会话（非主键）在 Docker 中运行，而主私信会话保持在主机上。然后通过 `tools.sandbox.tools` 限制沙箱会话中可用的工具。 -设置指南 + 示例配置：[群组：个人私信 + 公开群组](/concepts/groups#pattern-personal-dms-public-groups-single-agent) +设置指南 + 示例配置：[群组：个人私信 + 公开群组](/channels/groups#pattern-personal-dms-public-groups-single-agent) 关键配置参考：[Gateway 网关配置](/gateway/configuration#agentsdefaultssandbox) @@ -1321,7 +1321,7 @@ Gateway 网关监视配置文件并支持热重载： - **子智能体：** 需要并行处理时从主智能体生成后台工作。 - **TUI：** 连接到 Gateway 网关并切换智能体/会话。 -文档：[节点](/nodes)、[远程访问](/gateway/remote)、[多智能体路由](/concepts/multi-agent)、[子智能体](/tools/subagents)、[TUI](/tui)。 +文档：[节点](/nodes)、[远程访问](/gateway/remote)、[多智能体路由](/concepts/multi-agent)、[子智能体](/tools/subagents)、[TUI](/web/tui)。 ### OpenClaw 浏览器可以无头运行吗 @@ -1527,7 +1527,7 @@ OpenClaw 从父进程（shell、launchd/systemd、CI 等）读取环境变量， } ``` -参阅 [/environment](/environment) 了解优先级和来源详情。 +参阅 [/environment](/help/environment) 了解优先级和来源详情。 ### 我通过服务启动了 Gateway 网关，但环境变量消失了，怎么办 @@ -1570,7 +1570,7 @@ openclaw models status ``` Copilot 令牌从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 -参阅 [/concepts/model-providers](/concepts/model-providers) 和 [/environment](/environment)。 +参阅 [/concepts/model-providers](/concepts/model-providers) 和 [/environment](/help/environment)。 ## 会话与多聊天 @@ -1731,11 +1731,11 @@ openclaw directory groups list --channel whatsapp - 提及限制已开启（默认）。你必须 @提及机器人（或匹配 `mentionPatterns`）。 - 你配置了 `channels.whatsapp.groups` 但没有 `"*"` 且该群组未加入允许列表。 -参阅[群组](/concepts/groups)和[群组消息](/concepts/group-messages)。 +参阅[群组](/channels/groups)和[群组消息](/channels/group-messages)。 ### 群组/线程与私聊共享上下文吗 -直接聊天默认折叠到主会话。群组/频道有自己的会话键，Telegram 话题 / Discord 线程是独立的会话。参阅[群组](/concepts/groups)和[群组消息](/concepts/group-messages)。 +直接聊天默认折叠到主会话。群组/频道有自己的会话键，Telegram 话题 / Discord 线程是独立的会话。参阅[群组](/channels/groups)和[群组消息](/channels/group-messages)。 ### 可以创建多少个工作区和智能体 @@ -2410,7 +2410,7 @@ openclaw logs --follow 在 TUI 中，使用 `/status` 查看当前状态。如果你期望在聊天渠道中收到回复，确保投递已启用（`/deliver on`）。 -文档：[TUI](/tui)、[斜杠命令](/tools/slash-commands)。 +文档：[TUI](/web/tui)、[斜杠命令](/tools/slash-commands)。 ### 如何完全停止然后启动 Gateway 网关如果你安装了服务： @@ -2492,7 +2492,7 @@ openclaw message send --target +15555550123 --message "Here you go" --media /pat 从小处开始。只授予你实际需要的工具和账户的访问权限，以后需要时再扩展。 -文档：[安全](/gateway/security)、[配对](/start/pairing)。 +文档：[安全](/gateway/security)、[配对](/channels/pairing)。 ### 我能让它自主管理我的短信吗？这安全吗 diff --git a/docs/zh-CN/scripts.md b/docs/zh-CN/help/scripts.md similarity index 97% rename from docs/zh-CN/scripts.md rename to docs/zh-CN/help/scripts.md index 09ee5ce27b..9711f2801f 100644 --- a/docs/zh-CN/scripts.md +++ b/docs/zh-CN/help/scripts.md @@ -9,7 +9,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: bfedc3c123c4a43b351f793e2137568786f90732723da5fd223c2a088bc59e43 - source_path: scripts.md + source_path: help/scripts.md workflow: 15 --- diff --git a/docs/zh-CN/help/submitting-a-pr.md b/docs/zh-CN/help/submitting-a-pr.md new file mode 100644 index 0000000000..b2feee4dc0 --- /dev/null +++ b/docs/zh-CN/help/submitting-a-pr.md @@ -0,0 +1,8 @@ +--- +summary: 如何提交高信号 PR +title: 提交 PR +--- + +# 提交 PR + +该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Submitting a PR](/help/submitting-a-pr)。 diff --git a/docs/zh-CN/help/submitting-an-issue.md b/docs/zh-CN/help/submitting-an-issue.md new file mode 100644 index 0000000000..c328002a71 --- /dev/null +++ b/docs/zh-CN/help/submitting-an-issue.md @@ -0,0 +1,8 @@ +--- +summary: 如何提交高信号 Issue +title: 提交 Issue +--- + +# 提交 Issue + +该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Submitting an Issue](/help/submitting-an-issue)。 diff --git a/docs/zh-CN/testing.md b/docs/zh-CN/help/testing.md similarity index 99% rename from docs/zh-CN/testing.md rename to docs/zh-CN/help/testing.md index 4856ece03c..780f289df8 100644 --- a/docs/zh-CN/testing.md +++ b/docs/zh-CN/help/testing.md @@ -10,7 +10,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: 8c236673838731c49464622ac54bf0336acf787b857677c8c2d2aa52949c8ad5 - source_path: testing.md + source_path: help/testing.md workflow: 15 --- diff --git a/docs/zh-CN/hooks/soul-evil.md b/docs/zh-CN/hooks/soul-evil.md index e775ee0213..c9401a8454 100644 --- a/docs/zh-CN/hooks/soul-evil.md +++ b/docs/zh-CN/hooks/soul-evil.md @@ -69,4 +69,4 @@ openclaw hooks enable soul-evil ## 另请参阅 -- [钩子](/hooks) +- [钩子](/automation/hooks) diff --git a/docs/zh-CN/install/ansible.md b/docs/zh-CN/install/ansible.md index e81a6b4ebd..04425887d2 100644 --- a/docs/zh-CN/install/ansible.md +++ b/docs/zh-CN/install/ansible.md @@ -114,7 +114,7 @@ nmap -p- YOUR_SERVER_IP Docker 用于**智能体沙箱**（隔离的工具执行），而不是用于运行 Gateway 网关本身。Gateway 网关仅绑定到 localhost，通过 Tailscale VPN 访问。 -沙箱配置参见[多智能体沙箱与工具](/multi-agent-sandbox-tools)。 +沙箱配置参见[多智能体沙箱与工具](/tools/multi-agent-sandbox-tools)。 ## 手动安装 @@ -212,4 +212,4 @@ openclaw channels login - [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — 完整部署指南 - [Docker](/install/docker) — 容器化 Gateway 网关设置 - [沙箱隔离](/gateway/sandboxing) — 智能体沙箱配置 -- [多智能体沙箱与工具](/multi-agent-sandbox-tools) — 每个智能体的隔离 +- [多智能体沙箱与工具](/tools/multi-agent-sandbox-tools) — 每个智能体的隔离 diff --git a/docs/zh-CN/install/docker.md b/docs/zh-CN/install/docker.md index 0b0577738b..08a84d2d6e 100644 --- a/docs/zh-CN/install/docker.md +++ b/docs/zh-CN/install/docker.md @@ -314,7 +314,7 @@ pnpm test:docker:qr - 只读工具 + 只读工作区（家庭/工作智能体） - 无文件系统/shell 工具（公共智能体） -参阅[多智能体沙箱与工具](/multi-agent-sandbox-tools)了解示例、优先级和故障排除。 +参阅[多智能体沙箱与工具](/tools/multi-agent-sandbox-tools)了解示例、优先级和故障排除。 ### 默认行为 diff --git a/docs/zh-CN/install/node.md b/docs/zh-CN/install/node.md index 86ffb2bd1c..c8059d85af 100644 --- a/docs/zh-CN/install/node.md +++ b/docs/zh-CN/install/node.md @@ -1,85 +1,8 @@ --- -read_when: - - 你已安装 OpenClaw 但 `openclaw` 提示"command not found" - - 你正在新机器上配置 Node.js/npm - - npm install -g ... 因权限或 PATH 问题失败 -summary: Node.js + npm 安装完整性检查：版本、PATH 及全局安装 -title: Node.js + npm（PATH 安装完整性检查） -x-i18n: - generated_at: "2026-02-01T21:16:20Z" - model: claude-opus-4-5 - provider: pi - source_hash: 9f6d83be362e3e148ddf07d47e57c51679c22687263d3b5131cccbef2e37c598 - source_path: install/node.md - workflow: 15 +summary: Node.js 安装与配置（OpenClaw 版本要求、安装方式与 PATH 排错） +title: Node.js --- -# Node.js + npm（PATH 安装完整性检查） +# Node.js -OpenClaw 的运行时基线要求为 **Node 22+**。 - -如果你能运行 `npm install -g openclaw@latest`，但之后看到 `openclaw: command not found`，这几乎总是 **PATH** 问题：npm 存放全局二进制文件的目录不在你 shell 的 PATH 中。 - -## 快速诊断 - -运行： - -```bash -node -v -npm -v -npm prefix -g -echo "$PATH" -``` - -如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**未出现**在 `echo "$PATH"` 的输出中，你的 shell 就无法找到全局 npm 二进制文件（包括 `openclaw`）。 - -## 修复：将 npm 的全局 bin 目录添加到 PATH - -1. 查找你的全局 npm 前缀： - -```bash -npm prefix -g -``` - -2. 将全局 npm bin 目录添加到你的 shell 启动文件中： - -- zsh：`~/.zshrc` -- bash：`~/.bashrc` - -示例（将路径替换为你的 `npm prefix -g` 输出）： - -```bash -# macOS / Linux -export PATH="/path/from/npm/prefix/bin:$PATH" -``` - -然后打开一个**新终端**（或在 zsh 中运行 `rehash` / 在 bash 中运行 `hash -r`）。 - -在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH 中。 - -## 修复：避免 `sudo npm install -g` / 权限错误（Linux） - -如果 `npm install -g ...` 因 `EACCES` 失败，请将 npm 的全局前缀切换到用户可写的目录： - -```bash -mkdir -p "$HOME/.npm-global" -npm config set prefix "$HOME/.npm-global" -export PATH="$HOME/.npm-global/bin:$PATH" -``` - -将 `export PATH=...` 这一行持久化到你的 shell 启动文件中。 - -## 推荐的 Node 安装方式 - -如果 Node/npm 的安装方式满足以下条件，你将遇到最少的问题： - -- 保持 Node 更新（22+） -- 使全局 npm bin 目录稳定且在新 shell 中位于 PATH 中 - -常见选择： - -- macOS：Homebrew（`brew install node`）或版本管理器 -- Linux：你偏好的版本管理器，或提供 Node 22+ 的发行版支持的安装方式 -- Windows：官方 Node 安装程序、`winget` 或 Windows Node 版本管理器 - -如果你使用版本管理器（nvm/fnm/asdf 等），请确保它在你日常使用的 shell（zsh 或 bash）中已初始化，这样它设置的 PATH 在你运行安装程序时才会生效。 +该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Node.js](/install/node)。 diff --git a/docs/zh-CN/network.md b/docs/zh-CN/network.md index 7c45edc73d..d702d6be94 100644 --- a/docs/zh-CN/network.md +++ b/docs/zh-CN/network.md @@ -27,7 +27,7 @@ x-i18n: ## 配对 + 身份 -- [配对概述（私信 + 节点）](/start/pairing) +- [配对概述（私信 + 节点）](/channels/pairing) - [Gateway 网关拥有的节点配对](/gateway/pairing) - [Devices CLI（配对 + token 轮换）](/cli/devices) - [Pairing CLI（私信审批）](/cli/pairing) diff --git a/docs/zh-CN/nodes/troubleshooting.md b/docs/zh-CN/nodes/troubleshooting.md new file mode 100644 index 0000000000..d65074d087 --- /dev/null +++ b/docs/zh-CN/nodes/troubleshooting.md @@ -0,0 +1,8 @@ +--- +summary: 节点故障排查：排查配对、前台限制、权限与工具调用失败 +title: 节点故障排查 +--- + +# 节点故障排查 + +该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Node Troubleshooting](/nodes/troubleshooting)。 diff --git a/docs/zh-CN/plugins/manifest.md b/docs/zh-CN/plugins/manifest.md index fa9e5f9a5e..1d193594ea 100644 --- a/docs/zh-CN/plugins/manifest.md +++ b/docs/zh-CN/plugins/manifest.md @@ -17,7 +17,7 @@ x-i18n: 每个插件都**必须**在**插件根目录**下提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单来**在不执行插件代码的情况下**验证配置。缺失或无效的清单将被视为插件错误，并阻止配置验证。 -参阅完整的插件系统指南：[插件](/plugin)。 +参阅完整的插件系统指南：[插件](/tools/plugin)。 ## 必填字段 diff --git a/docs/zh-CN/prose.md b/docs/zh-CN/prose.md index 7ffd5d17c9..17b9571399 100644 --- a/docs/zh-CN/prose.md +++ b/docs/zh-CN/prose.md @@ -38,7 +38,7 @@ openclaw plugins enable open-prose 开发/本地检出：`openclaw plugins install ./extensions/open-prose` -相关文档：[插件](/plugin)、[插件清单](/plugins/manifest)、[Skills](/tools/skills)。 +相关文档：[插件](/tools/plugin)、[插件清单](/plugins/manifest)、[Skills](/tools/skills)。 ## 斜杠命令 diff --git a/docs/zh-CN/bedrock.md b/docs/zh-CN/providers/bedrock.md similarity index 99% rename from docs/zh-CN/bedrock.md rename to docs/zh-CN/providers/bedrock.md index bf88fe1418..3e661e7e0e 100644 --- a/docs/zh-CN/bedrock.md +++ b/docs/zh-CN/providers/bedrock.md @@ -9,7 +9,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: 318f1048451a1910b70522e2f7f9dfc87084de26d9e3938a29d372eed32244a8 - source_path: bedrock.md + source_path: providers/bedrock.md workflow: 15 --- diff --git a/docs/zh-CN/providers/index.md b/docs/zh-CN/providers/index.md index 81601bda38..d3752f97f1 100644 --- a/docs/zh-CN/providers/index.md +++ b/docs/zh-CN/providers/index.md @@ -48,7 +48,7 @@ Venice 是我们推荐的 Venice AI 设置，用于隐私优先的推理，并 - [Vercel AI Gateway](/providers/vercel-ai-gateway) - [Moonshot AI（Kimi + Kimi Coding）](/providers/moonshot) - [OpenCode Zen](/providers/opencode) -- [Amazon Bedrock](/bedrock) +- [Amazon Bedrock](/providers/bedrock) - [Z.AI](/providers/zai) - [Xiaomi](/providers/xiaomi) - [GLM 模型](/providers/glm) diff --git a/docs/zh-CN/providers/models.md b/docs/zh-CN/providers/models.md index ffeb613f54..dc5210b128 100644 --- a/docs/zh-CN/providers/models.md +++ b/docs/zh-CN/providers/models.md @@ -50,6 +50,6 @@ Venice 是我们推荐的 Venice AI 设置，用于隐私优先的推理，并 - [GLM 模型](/providers/glm) - [MiniMax](/providers/minimax) - [Venice（Venice AI）](/providers/venice) -- [Amazon Bedrock](/bedrock) +- [Amazon Bedrock](/providers/bedrock) 有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅[模型提供商](/concepts/model-providers)。 diff --git a/docs/zh-CN/providers/qianfan.md b/docs/zh-CN/providers/qianfan.md new file mode 100644 index 0000000000..4bb17cee5c --- /dev/null +++ b/docs/zh-CN/providers/qianfan.md @@ -0,0 +1,8 @@ +--- +summary: 使用千帆统一 API 在 OpenClaw 中接入多种模型 +title: 千帆（Qianfan） +--- + +# 千帆（Qianfan） + +该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Qianfan](/providers/qianfan)。 diff --git a/docs/zh-CN/refactor/plugin-sdk.md b/docs/zh-CN/refactor/plugin-sdk.md index a3fc05b47f..7142aa9f8b 100644 --- a/docs/zh-CN/refactor/plugin-sdk.md +++ b/docs/zh-CN/refactor/plugin-sdk.md @@ -218,4 +218,4 @@ export type PluginRuntime = { - 新连接器模板仅依赖 SDK + 运行时。 - 外部插件可以在无需访问核心源码的情况下进行开发和更新。 -相关文档：[插件](/plugin)、[渠道](/channels/index)、[配置](/gateway/configuration)。 +相关文档：[插件](/tools/plugin)、[渠道](/channels/index)、[配置](/gateway/configuration)。 diff --git a/docs/zh-CN/reference/api-usage-costs.md b/docs/zh-CN/reference/api-usage-costs.md index b6e0634663..feb62d60c6 100644 --- a/docs/zh-CN/reference/api-usage-costs.md +++ b/docs/zh-CN/reference/api-usage-costs.md @@ -34,7 +34,7 @@ x-i18n: - `openclaw status --usage` 和 `openclaw channels list` 显示提供商**用量窗口**（配额快照，非每条消息的费用）。 -详情和示例请参阅 [Token 用量与费用](/token-use)。 +详情和示例请参阅 [Token 用量与费用](/reference/token-use)。 ## 密钥的发现方式 @@ -51,7 +51,7 @@ OpenClaw 可以从以下来源获取凭据： 每次回复或工具调用都使用**当前模型提供商**（OpenAI、Anthropic 等）。这是用量和费用的主要来源。 -定价配置请参阅[模型](/providers/models)，显示方式请参阅 [Token 用量与费用](/token-use)。 +定价配置请参阅[模型](/providers/models)，显示方式请参阅 [Token 用量与费用](/reference/token-use)。 ### 2）媒体理解（音频/图像/视频） diff --git a/docs/zh-CN/reference/session-management-compaction.md b/docs/zh-CN/reference/session-management-compaction.md index 5fd95beb87..7c1db7560d 100644 --- a/docs/zh-CN/reference/session-management-compaction.md +++ b/docs/zh-CN/reference/session-management-compaction.md @@ -161,7 +161,7 @@ OpenClaw 有意**不**"修复"记录；Gateway 网关使用 `SessionManager` 来 - 上下文窗口来自模型目录（可以通过配置覆盖）。 - 存储中的 `contextTokens` 是运行时估计/报告值；不要将其视为严格保证。 -更多信息，参见 [/token-use](/token-use)。 +更多信息，参见 [/token-use](/reference/token-use)。 --- diff --git a/docs/zh-CN/reference/test.md b/docs/zh-CN/reference/test.md index b0c9bae798..95f55fb54f 100644 --- a/docs/zh-CN/reference/test.md +++ b/docs/zh-CN/reference/test.md @@ -14,7 +14,7 @@ x-i18n: # 测试 -- 完整测试套件（测试集、实时测试、Docker）：[测试](/testing) +- 完整测试套件（测试集、实时测试、Docker）：[测试](/help/testing) - `pnpm test:force`：终止任何占用默认控制端口的遗留 Gateway 网关进程，然后使用隔离的 Gateway 网关端口运行完整的 Vitest 套件，这样服务器测试不会与正在运行的实例冲突。当之前的 Gateway 网关运行占用了端口 18789 时使用此命令。 - `pnpm test:coverage`：使用 V8 覆盖率运行 Vitest。全局阈值为 70% 的行/分支/函数/语句覆盖率。覆盖率排除了集成密集型入口点（CLI 连接、gateway/telegram 桥接、webchat 静态服务器），以保持目标集中在可单元测试的逻辑上。 diff --git a/docs/zh-CN/token-use.md b/docs/zh-CN/reference/token-use.md similarity index 99% rename from docs/zh-CN/token-use.md rename to docs/zh-CN/reference/token-use.md index d7359d37e9..54f71149ac 100644 --- a/docs/zh-CN/token-use.md +++ b/docs/zh-CN/reference/token-use.md @@ -9,7 +9,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: aee417119851db9e36890487517ed9602d214849e412127e7f534ebec5c9e105 - source_path: token-use.md + source_path: reference/token-use.md workflow: 15 --- diff --git a/docs/zh-CN/reference/wizard.md b/docs/zh-CN/reference/wizard.md new file mode 100644 index 0000000000..766c689994 --- /dev/null +++ b/docs/zh-CN/reference/wizard.md @@ -0,0 +1,9 @@ +--- +summary: Onboarding 向导参考：完整步骤、参数与配置字段 +title: 向导参考 +sidebarTitle: 向导参考 +--- + +# 向导参考 + +该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Onboarding Wizard Reference](/reference/wizard)。 diff --git a/docs/zh-CN/start/bootstrapping.md b/docs/zh-CN/start/bootstrapping.md new file mode 100644 index 0000000000..508081b893 --- /dev/null +++ b/docs/zh-CN/start/bootstrapping.md @@ -0,0 +1,9 @@ +--- +summary: 智能体引导流程：首次运行时如何初始化工作区与身份文件 +title: 智能体引导 +sidebarTitle: 引导 +--- + +# 智能体引导 + +该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Agent Bootstrapping](/start/bootstrapping)。 diff --git a/docs/zh-CN/start/docs-directory.md b/docs/zh-CN/start/docs-directory.md index 6e5dbaee82..6933d35c0a 100644 --- a/docs/zh-CN/start/docs-directory.md +++ b/docs/zh-CN/start/docs-directory.md @@ -25,7 +25,7 @@ x-i18n: - [斜杠命令](/tools/slash-commands) - [多智能体路由](/concepts/multi-agent) - [更新与回滚](/install/updating) -- [配对（私信和节点）](/start/pairing) +- [配对（私信和节点）](/channels/pairing) - [Nix 模式](/install/nix) - [OpenClaw 助手设置](/start/openclaw) - [Skills](/tools/skills) @@ -47,8 +47,8 @@ x-i18n: - [Mattermost（插件）](/channels/mattermost) - [BlueBubbles (iMessage)](/channels/bluebubbles) - [iMessage（旧版）](/channels/imessage) -- [群组](/concepts/groups) -- [WhatsApp 群消息](/concepts/group-messages) +- [群组](/channels/groups) +- [WhatsApp 群消息](/channels/group-messages) - [媒体图片](/nodes/images) - [媒体音频](/nodes/audio) diff --git a/docs/zh-CN/start/getting-started.md b/docs/zh-CN/start/getting-started.md index 985122ea02..c144bd053b 100644 --- a/docs/zh-CN/start/getting-started.md +++ b/docs/zh-CN/start/getting-started.md @@ -28,7 +28,7 @@ x-i18n: - 工作区引导 + Skills - 可选的后台服务 -如果你想要更深入的参考页面，跳转到：[向导](/start/wizard)、[设置](/start/setup)、[配对](/start/pairing)、[安全](/gateway/security)。 +如果你想要更深入的参考页面，跳转到：[向导](/start/wizard)、[设置](/start/setup)、[配对](/channels/pairing)、[安全](/gateway/security)。 沙箱注意事项：`agents.defaults.sandbox.mode: "non-main"` 使用 `session.mainKey`（默认 `"main"`），因此群组/渠道会话会被沙箱隔离。如果你想要主智能体始终在主机上运行，设置显式的每智能体覆盖： @@ -162,7 +162,7 @@ openclaw pairing list whatsapp openclaw pairing approve whatsapp ``` -配对文档：[配对](/start/pairing) +配对文档：[配对](/channels/pairing) ## 从源代码（开发） diff --git a/docs/zh-CN/start/hubs.md b/docs/zh-CN/start/hubs.md index 362d226684..d4392700e0 100644 --- a/docs/zh-CN/start/hubs.md +++ b/docs/zh-CN/start/hubs.md @@ -64,9 +64,9 @@ x-i18n: - [在线状态](/concepts/presence) - [设备发现 + 传输协议](/gateway/discovery) - [Bonjour](/gateway/bonjour) -- [渠道路由](/concepts/channel-routing) -- [群组](/concepts/groups) -- [群组消息](/concepts/group-messages) +- [渠道路由](/channels/channel-routing) +- [群组](/channels/groups) +- [群组消息](/channels/group-messages) - [模型故障转移](/concepts/model-failover) - [OAuth](/concepts/oauth) @@ -121,7 +121,7 @@ x-i18n: - [模型](/concepts/models) - [子智能体](/tools/subagents) - [Agent send CLI](/tools/agent-send) -- [终端界面](/tui) +- [终端界面](/web/tui) - [浏览器控制](/tools/browser) - [浏览器（Linux 故障排除）](/tools/browser-linux-troubleshooting) - [轮询](/automation/poll) diff --git a/docs/zh-CN/tools/index.md b/docs/zh-CN/tools/index.md index 13e496e767..bdbc0a02e5 100644 --- a/docs/zh-CN/tools/index.md +++ b/docs/zh-CN/tools/index.md @@ -173,7 +173,7 @@ OpenClaw 为 browser、canvas、nodes 和 cron 暴露**一流的智能体工具* ## 插件 + 工具 插件可以在核心集之外注册**额外的工具**（和 CLI 命令）。 -参见[插件](/plugin)了解安装 + 配置，以及 [Skills](/tools/skills) 了解 +参见[插件](/tools/plugin)了解安装 + 配置，以及 [Skills](/tools/skills) 了解 工具使用指导如何被注入到提示中。一些插件随工具一起提供自己的 Skills （例如，voice-call 插件）。 diff --git a/docs/zh-CN/tools/lobster.md b/docs/zh-CN/tools/lobster.md index d9e1ca5aaa..29f1c57754 100644 --- a/docs/zh-CN/tools/lobster.md +++ b/docs/zh-CN/tools/lobster.md @@ -338,7 +338,7 @@ OpenProse 与 Lobster 配合良好：使用 `/prose` 编排多智能体准备， ## 了解更多 -- [插件](/plugin) +- [插件](/tools/plugin) - [插件工具开发](/plugins/agent-tools) ## 案例研究：社区工作流 diff --git a/docs/zh-CN/multi-agent-sandbox-tools.md b/docs/zh-CN/tools/multi-agent-sandbox-tools.md similarity index 99% rename from docs/zh-CN/multi-agent-sandbox-tools.md rename to docs/zh-CN/tools/multi-agent-sandbox-tools.md index a438653764..fd34f5afa5 100644 --- a/docs/zh-CN/multi-agent-sandbox-tools.md +++ b/docs/zh-CN/tools/multi-agent-sandbox-tools.md @@ -8,7 +8,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: f602cb6192b84b404cd7b6336562888a239d0fe79514edd51bd73c5b090131ef - source_path: multi-agent-sandbox-tools.md + source_path: tools/multi-agent-sandbox-tools.md workflow: 15 --- diff --git a/docs/zh-CN/plugin.md b/docs/zh-CN/tools/plugin.md similarity index 99% rename from docs/zh-CN/plugin.md rename to docs/zh-CN/tools/plugin.md index b47a20becc..fde337fc3a 100644 --- a/docs/zh-CN/plugin.md +++ b/docs/zh-CN/tools/plugin.md @@ -9,7 +9,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: b36ca6b90ca03eaae25c00f9b12f2717fcd17ac540ba616ee03b398b234c2308 - source_path: plugin.md + source_path: tools/plugin.md workflow: 15 --- diff --git a/docs/zh-CN/tools/skills.md b/docs/zh-CN/tools/skills.md index c81c9d623e..711fc3790c 100644 --- a/docs/zh-CN/tools/skills.md +++ b/docs/zh-CN/tools/skills.md @@ -43,7 +43,7 @@ Skills 从**三个**位置加载： ## 插件 + Skills -插件可以通过在 `openclaw.plugin.json` 中列出 `skills` 目录（相对于插件根目录的路径）来发布自己的 Skills。插件 Skills 在插件启用时加载，并参与正常的 Skills 优先级规则。你可以通过插件配置条目上的 `metadata.openclaw.requires.config` 对它们进行门控。参见[插件](/plugin)了解发现/配置，以及[工具](/tools)了解这些 Skills 所教授的工具接口。 +插件可以通过在 `openclaw.plugin.json` 中列出 `skills` 目录（相对于插件根目录的路径）来发布自己的 Skills。插件 Skills 在插件启用时加载，并参与正常的 Skills 优先级规则。你可以通过插件配置条目上的 `metadata.openclaw.requires.config` 对它们进行门控。参见[插件](/tools/plugin)了解发现/配置，以及[工具](/tools)了解这些 Skills 所教授的工具接口。 ## ClawHub（安装 + 同步） diff --git a/docs/zh-CN/tui.md b/docs/zh-CN/web/tui.md similarity index 99% rename from docs/zh-CN/tui.md rename to docs/zh-CN/web/tui.md index 9f54f08234..db10b848e4 100644 --- a/docs/zh-CN/tui.md +++ b/docs/zh-CN/web/tui.md @@ -9,7 +9,7 @@ x-i18n: model: claude-opus-4-5 provider: pi source_hash: 4bf5b0037bbb3a166289f2f0a9399489637d4cf26335ae3577af9ea83eee747e - source_path: tui.md + source_path: web/tui.md workflow: 15 --- diff --git a/package.json b/package.json index a5fd1978fc..3ce20f8037 100644 --- a/package.json +++ b/package.json @@ -41,6 +41,7 @@ "dev": "node scripts/run-node.mjs", "docs:bin": "node scripts/build-docs-list.mjs", "docs:build": "cd docs && pnpm dlx --reporter append-only mint broken-links", + "docs:check-links": "node scripts/docs-link-audit.mjs", "docs:dev": "cd docs && mint dev", "docs:list": "node scripts/docs-list.js", "format": "oxfmt --check", diff --git a/scripts/docs-link-audit.mjs b/scripts/docs-link-audit.mjs new file mode 100644 index 0000000000..2a9abdc69e --- /dev/null +++ b/scripts/docs-link-audit.mjs @@ -0,0 +1,207 @@ +#!/usr/bin/env node + +import fs from "node:fs"; +import path from "node:path"; + +const ROOT = process.cwd(); +const DOCS_DIR = path.join(ROOT, "docs"); +const DOCS_JSON_PATH = path.join(DOCS_DIR, "docs.json"); + +if (!fs.existsSync(DOCS_DIR) || !fs.statSync(DOCS_DIR).isDirectory()) { + console.error("docs:check-links: missing docs directory; run from repo root."); + process.exit(1); +} + +if (!fs.existsSync(DOCS_JSON_PATH)) { + console.error("docs:check-links: missing docs/docs.json."); + process.exit(1); +} + +/** @param {string} dir */ +function walk(dir) { + /** @type {string[]} */ + const out = []; + const entries = fs.readdirSync(dir, { withFileTypes: true }); + for (const entry of entries) { + if (entry.name.startsWith(".")) { + continue; + } + const full = path.join(dir, entry.name); + if (entry.isDirectory()) { + out.push(...walk(full)); + } else if (entry.isFile()) { + out.push(full); + } + } + return out; +} + +/** @param {string} p */ +function normalizeSlashes(p) { + return p.replace(/\\/g, "/"); +} + +/** @param {string} p */ +function normalizeRoute(p) { + const stripped = p.replace(/^\/+|\/+$/g, ""); + return stripped ? `/${stripped}` : "/"; +} + +/** @param {string} text */ +function stripCodeFences(text) { + return text.replace(/```[\s\S]*?```/g, ""); +} + +const docsConfig = JSON.parse(fs.readFileSync(DOCS_JSON_PATH, "utf8")); +const redirects = new Map(); +for (const item of docsConfig.redirects || []) { + const source = normalizeRoute(String(item.source || "")); + const destination = normalizeRoute(String(item.destination || "")); + redirects.set(source, destination); +} + +const allFiles = walk(DOCS_DIR); +const relAllFiles = new Set(allFiles.map((abs) => normalizeSlashes(path.relative(DOCS_DIR, abs)))); + +const markdownFiles = allFiles.filter((abs) => /\.(md|mdx)$/i.test(abs)); +const routes = new Set(); + +for (const abs of markdownFiles) { + const rel = normalizeSlashes(path.relative(DOCS_DIR, abs)); + const slug = rel.replace(/\.(md|mdx)$/i, ""); + routes.add(normalizeRoute(slug)); + if (slug.endsWith("/index")) { + routes.add(normalizeRoute(slug.slice(0, -"/index".length))); + } + + const text = fs.readFileSync(abs, "utf8"); + if (!text.startsWith("---")) { + continue; + } + + const end = text.indexOf("\n---", 3); + if (end === -1) { + continue; + } + const frontMatter = text.slice(3, end); + const match = frontMatter.match(/^permalink:\s*(.+)\s*$/m); + if (!match) { + continue; + } + const permalink = String(match[1]) + .trim() + .replace(/^['"]|['"]$/g, ""); + routes.add(normalizeRoute(permalink)); +} + +/** @param {string} route */ +function resolveRoute(route) { + let current = normalizeRoute(route); + if (current === "/") { + return { ok: true, terminal: "/" }; + } + + const seen = new Set([current]); + while (redirects.has(current)) { + current = redirects.get(current); + if (seen.has(current)) { + return { ok: false, terminal: current, loop: true }; + } + seen.add(current); + } + return { ok: routes.has(current), terminal: current }; +} + +const markdownLinkRegex = /!?\[[^\]]*\]\(([^)]+)\)/g; + +/** @type {{file: string; link: string; reason: string}[]} */ +const broken = []; +let checked = 0; + +for (const abs of markdownFiles) { + const rel = normalizeSlashes(path.relative(DOCS_DIR, abs)); + const baseDir = normalizeSlashes(path.dirname(rel)); + const text = stripCodeFences(fs.readFileSync(abs, "utf8")); + + for (const match of text.matchAll(markdownLinkRegex)) { + const raw = match[1]?.trim(); + if (!raw) { + continue; + } + if (/^(https?:|mailto:|tel:|data:|#)/i.test(raw)) { + continue; + } + + const clean = raw.split("#")[0].split("?")[0]; + if (!clean) { + continue; + } + checked++; + + if (clean.startsWith("/")) { + const route = normalizeRoute(clean); + const resolvedRoute = resolveRoute(route); + if (resolvedRoute.ok) { + continue; + } + + const staticRel = route.replace(/^\//, ""); + if (relAllFiles.has(staticRel)) { + continue; + } + + broken.push({ + file: rel, + link: raw, + reason: `route/file not found (terminal: ${resolvedRoute.terminal})`, + }); + continue; + } + + // Relative placeholder strings used in code examples (for example "url") + // are intentionally skipped. + if (!clean.startsWith(".") && !clean.includes("/")) { + continue; + } + + const normalizedRel = normalizeSlashes(path.normalize(path.join(baseDir, clean))); + + if (/\.[a-zA-Z0-9]+$/.test(normalizedRel)) { + if (!relAllFiles.has(normalizedRel)) { + broken.push({ + file: rel, + link: raw, + reason: "relative file not found", + }); + } + continue; + } + + const candidates = [ + normalizedRel, + `${normalizedRel}.md`, + `${normalizedRel}.mdx`, + `${normalizedRel}/index.md`, + `${normalizedRel}/index.mdx`, + ]; + + if (!candidates.some((candidate) => relAllFiles.has(candidate))) { + broken.push({ + file: rel, + link: raw, + reason: "relative doc target not found", + }); + } + } +} + +console.log(`checked_internal_links=${checked}`); +console.log(`broken_links=${broken.length}`); + +for (const item of broken) { + console.log(`${item.file} :: ${item.link} :: ${item.reason}`); +} + +if (broken.length > 0) { + process.exit(1); +}