From 834fdc4832f632d834941399603f5062e5512e66 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 23 Apr 2026 07:21:39 +0100 Subject: [PATCH] docs: align documentation with current surfaces --- .markdownlint-cli2.jsonc | 5 +++ docs/.i18n/glossary.zh-CN.json | 16 +++++++ docs/AGENTS.md | 4 +- docs/automation/poll.md | 2 +- docs/channels/bluebubbles.md | 2 + docs/channels/feishu.md | 2 + docs/channels/irc.md | 2 +- docs/channels/msteams.md | 2 + docs/cli/plugins.md | 2 +- docs/cli/security.md | 2 +- docs/concepts/dreaming.md | 2 +- docs/gateway/configuration-reference.md | 4 +- docs/install/docker.md | 18 ++++---- docs/install/hostinger.md | 2 +- docs/install/podman.md | 2 +- docs/providers/anthropic.md | 3 +- docs/providers/deepgram.md | 4 +- docs/providers/index.md | 1 + docs/providers/litellm.md | 3 +- docs/providers/mistral.md | 2 +- docs/providers/moonshot.md | 2 +- docs/providers/openai.md | 2 + docs/providers/tencent.md | 2 +- docs/providers/volcengine.md | 2 +- ...exec-duplicate-completion-investigation.md | 8 ++++ docs/refactor/qa.md | 8 ++++ docs/reference/rich-output-protocol.md | 8 ++++ docs/start/showcase.md | 30 ++++++++----- docs/tools/index.md | 36 ++++++++-------- docs/tools/plugin.md | 2 +- docs/tts.md | 1 + extensions/openai/index.test.ts | 42 ++++++++++++------- scripts/codespell-ignore.txt | 4 ++ test/setup.shared.ts | 8 ++++ 34 files changed, 162 insertions(+), 73 deletions(-) diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index 3cb1d071ea3..9cf34019a60 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -39,7 +39,12 @@ "details", "summary", "p", + "div", "strong", + "span", + "iframe", + "h2", + "h3", "picture", "source", "Tooltip", diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index 3dff4abfa9a..f2b04362f7f 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -383,6 +383,22 @@ "source": "Testing", "target": "测试" }, + { + "source": "Async Exec Duplicate Completion Investigation", + "target": "Async Exec Duplicate Completion Investigation" + }, + { + "source": "QA Refactor", + "target": "QA 重构" + }, + { + "source": "Rich Output Protocol", + "target": "富输出协议" + }, + { + "source": "Tencent Cloud (TokenHub)", + "target": "腾讯云（TokenHub）" + }, { "source": "/gateway/configuration#strict-validation", "target": "/gateway/configuration#strict-validation" diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 751f993a18c..43027196714 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -5,8 +5,8 @@ This directory owns docs authoring, Mintlify link rules, and docs i18n policy. ## Mintlify Rules - Docs are hosted on Mintlify (`https://docs.openclaw.ai`). -- Internal doc links in `docs/**/*.md` must stay root-relative with no `.md` or `.mdx` suffix (example: `[Config](/configuration)`). -- Section cross-references should use anchors on root-relative paths (example: `[Hooks](/configuration#hooks)`). +- Internal doc links in `docs/**/*.md` must stay root-relative with no `.md` or `.mdx` suffix (example: `[Config](/gateway/configuration)`). +- Section cross-references should use anchors on root-relative paths (example: `[Hooks](/gateway/configuration-reference#hooks)`). - Doc headings should avoid em dashes and apostrophes because Mintlify anchor generation is brittle there. - README and other GitHub-rendered docs should keep absolute docs URLs so links work outside Mintlify. - Docs content must stay generic: no personal device names, hostnames, or local paths; use placeholders like `user@gateway-host`. diff --git a/docs/automation/poll.md b/docs/automation/poll.md index d990cffbf4e..df6a1084de8 100644 --- a/docs/automation/poll.md +++ b/docs/automation/poll.md @@ -1,5 +1,5 @@ --- -summary: "Redirect to /tools/message" +summary: "Redirect to /cli/message" title: "Polls" --- diff --git a/docs/channels/bluebubbles.md b/docs/channels/bluebubbles.md index cbad7bbb251..e404b116913 100644 --- a/docs/channels/bluebubbles.md +++ b/docs/channels/bluebubbles.md @@ -393,6 +393,8 @@ Use full IDs for durable automations and storage: See [Configuration](/gateway/configuration) for template variables. + + ## Coalescing split-send DMs (command + URL in one composition) When a user types a command and a URL together in iMessage — e.g. `Dump https://example.com/article` — Apple splits the send into **two separate webhook deliveries**: diff --git a/docs/channels/feishu.md b/docs/channels/feishu.md index 5f4b9ed56f5..8e9cabfcb4b 100644 --- a/docs/channels/feishu.md +++ b/docs/channels/feishu.md @@ -135,6 +135,8 @@ Default: `allowlist` --- + + ## Get group/user IDs ### Group IDs (`chat_id`, format: `oc_xxx`) diff --git a/docs/channels/irc.md b/docs/channels/irc.md index 6dd181bf1e4..1eb04cd46a4 100644 --- a/docs/channels/irc.md +++ b/docs/channels/irc.md @@ -9,7 +9,7 @@ read_when: # IRC Use IRC when you want OpenClaw in classic channels (`#room`) and direct messages. -IRC ships as an extension plugin, but it is configured in the main config under `channels.irc`. +IRC ships as a bundled plugin, but it is configured in the main config under `channels.irc`. ## Quick start diff --git a/docs/channels/msteams.md b/docs/channels/msteams.md index 43b2efc72a2..1efbafbd5e4 100644 --- a/docs/channels/msteams.md +++ b/docs/channels/msteams.md @@ -190,6 +190,8 @@ Before configuring OpenClaw, you need to create an Azure Bot resource. 2. Click **Microsoft Teams** → Configure → Save 3. Accept the Terms of Service + + ## Federated Authentication (Certificate + Managed Identity) > Added in 2026.3.24 diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index 9a3d0fd7741..4bd876a8814 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -172,7 +172,7 @@ For local paths and archives, OpenClaw auto-detects: component layout) - Cursor-compatible bundles (`.cursor-plugin/plugin.json`) -Compatible bundles install into the normal extensions root and participate in +Compatible bundles install into the normal plugin root and participate in the same list/info/enable/disable flow. Today, bundle skills, Claude command-skills, Claude `settings.json` defaults, Claude `.lsp.json` / manifest-declared `lspServers` defaults, Cursor command-skills, and compatible diff --git a/docs/cli/security.md b/docs/cli/security.md index 0cf5423a391..af1bfea86b5 100644 --- a/docs/cli/security.md +++ b/docs/cli/security.md @@ -31,7 +31,7 @@ It also emits `security.trust_model.multi_user_heuristic` when config suggests l For intentional shared-user setups, the audit guidance is to sandbox all sessions, keep filesystem access workspace-scoped, and keep personal/private identities or credentials off that runtime. It also warns when small models (`<=300B`) are used without sandboxing and with web/browser tools enabled. For webhook ingress, it warns when `hooks.token` reuses the Gateway token, when `hooks.token` is short, when `hooks.path="/"`, when `hooks.defaultSessionKey` is unset, when `hooks.allowedAgentIds` is unrestricted, when request `sessionKey` overrides are enabled, and when overrides are enabled without `hooks.allowedSessionKeyPrefixes`. -It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries (exact node command-name matching only, not shell-text filtering), when `gateway.nodes.allowCommands` explicitly enables dangerous node commands, when global `tools.profile="minimal"` is overridden by agent tool profiles, when open groups expose runtime/filesystem tools without sandbox/workspace guards, and when installed extension plugin tools may be reachable under permissive tool policy. +It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries (exact node command-name matching only, not shell-text filtering), when `gateway.nodes.allowCommands` explicitly enables dangerous node commands, when global `tools.profile="minimal"` is overridden by agent tool profiles, when open groups expose runtime/filesystem tools without sandbox/workspace guards, and when installed plugin tools may be reachable under permissive tool policy. It also flags `gateway.allowRealIpFallback=true` (header-spoofing risk if proxies are misconfigured) and `discovery.mdns.mode="full"` (metadata leakage via mDNS TXT records). It also warns when sandbox browser uses Docker `bridge` network without `sandbox.browser.cdpSourceRange`. It also flags dangerous sandbox Docker network modes (including `host` and `container:*` namespace joins). diff --git a/docs/concepts/dreaming.md b/docs/concepts/dreaming.md index e844af242ae..d16c966dad7 100644 --- a/docs/concepts/dreaming.md +++ b/docs/concepts/dreaming.md @@ -238,7 +238,7 @@ The managed dreaming cron rides the default agent's heartbeat. If heartbeat is n Two common causes: - Another agent declares an explicit `heartbeat:` block. When any entry in `agents.list` has its own `heartbeat` block, only those agents heartbeat — the defaults stop applying to everyone else, so the default agent can go silent. Move the heartbeat settings to `agents.defaults.heartbeat`, or add an explicit `heartbeat` block on the default agent. See [Scope and precedence](/gateway/heartbeat#scope-and-precedence). -- `heartbeat.every` is `0`, empty, or unparseable. The cron has no interval to schedule against, so the heartbeat is effectively disabled. Set `every` to a positive duration such as `30m`. See [Defaults](/gateway/heartbeat#defaults). +- `heartbeat.every` is `0`, empty, or unparsable. The cron has no interval to schedule against, so the heartbeat is effectively disabled. Set `every` to a positive duration such as `30m`. See [Defaults](/gateway/heartbeat#defaults). ## Related diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index eb55aded951..a05e3871342 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -2493,6 +2493,8 @@ Notes: - File permissions are `0700` for directories and `0600` for files. - Cleanup follows the `cleanup` policy: `delete` always removes attachments; `keep` retains them only when `retainOnSessionKeep: true`. + + ### `tools.experimental` Experimental built-in tool flags. Default off unless a strict-agentic GPT-5 auto-enable rule applies. @@ -2891,7 +2893,7 @@ See [Local Models](/gateway/local-models). TL;DR: run a large local model via LM allow: ["voice-call"], deny: [], load: { - paths: ["~/Projects/oss/voice-call-extension"], + paths: ["~/Projects/oss/voice-call-plugin"], }, entries: { "voice-call": { diff --git a/docs/install/docker.md b/docs/install/docker.md index 07a4369cbde..2a162955b75 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -124,15 +124,15 @@ and setup-time config writes through `openclaw-gateway` with The setup script accepts these optional environment variables: -| Variable | Purpose | -| ------------------------------ | ---------------------------------------------------------------- | -| `OPENCLAW_IMAGE` | Use a remote image instead of building locally | -| `OPENCLAW_DOCKER_APT_PACKAGES` | Install extra apt packages during build (space-separated) | -| `OPENCLAW_EXTENSIONS` | Pre-install extension deps at build time (space-separated names) | -| `OPENCLAW_EXTRA_MOUNTS` | Extra host bind mounts (comma-separated `source:target[:opts]`) | -| `OPENCLAW_HOME_VOLUME` | Persist `/home/node` in a named Docker volume | -| `OPENCLAW_SANDBOX` | Opt in to sandbox bootstrap (`1`, `true`, `yes`, `on`) | -| `OPENCLAW_DOCKER_SOCKET` | Override Docker socket path | +| Variable | Purpose | +| ------------------------------ | --------------------------------------------------------------- | +| `OPENCLAW_IMAGE` | Use a remote image instead of building locally | +| `OPENCLAW_DOCKER_APT_PACKAGES` | Install extra apt packages during build (space-separated) | +| `OPENCLAW_EXTENSIONS` | Pre-install plugin deps at build time (space-separated names) | +| `OPENCLAW_EXTRA_MOUNTS` | Extra host bind mounts (comma-separated `source:target[:opts]`) | +| `OPENCLAW_HOME_VOLUME` | Persist `/home/node` in a named Docker volume | +| `OPENCLAW_SANDBOX` | Opt in to sandbox bootstrap (`1`, `true`, `yes`, `on`) | +| `OPENCLAW_DOCKER_SOCKET` | Override Docker socket path | ### Health checks diff --git a/docs/install/hostinger.md b/docs/install/hostinger.md index 0d196275209..7beff21c9e6 100644 --- a/docs/install/hostinger.md +++ b/docs/install/hostinger.md @@ -91,4 +91,4 @@ Send "Hi" to your assistant on the channel you connected. OpenClaw will reply an ## Next steps - [Channels](/channels) -- connect Telegram, WhatsApp, Discord, and more -- [Gateway configuration](/gateway/configuration) -- all config optionss +- [Gateway configuration](/gateway/configuration) -- all config options diff --git a/docs/install/podman.md b/docs/install/podman.md index 46da51c4734..f2ee029a782 100644 --- a/docs/install/podman.md +++ b/docs/install/podman.md @@ -64,7 +64,7 @@ Optional build/setup env vars: - `OPENCLAW_IMAGE` or `OPENCLAW_PODMAN_IMAGE` -- use an existing/pulled image instead of building `openclaw:local` - `OPENCLAW_DOCKER_APT_PACKAGES` -- install extra apt packages during image build -- `OPENCLAW_EXTENSIONS` -- pre-install extension dependencies at build time +- `OPENCLAW_EXTENSIONS` -- pre-install plugin dependencies at build time Container start: diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md index 0650204c8d8..2e958f29757 100644 --- a/docs/providers/anthropic.md +++ b/docs/providers/anthropic.md @@ -26,7 +26,8 @@ Anthropic's current public docs: - [Claude Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview) - [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) - [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/) - + + ## Getting started diff --git a/docs/providers/deepgram.md b/docs/providers/deepgram.md index ec2db0fcd1f..cc834f1c620 100644 --- a/docs/providers/deepgram.md +++ b/docs/providers/deepgram.md @@ -171,10 +171,10 @@ Twilio media frames can be forwarded directly. ## Related - + Audio, image, and video processing pipeline overview. - + Full config reference including media tool settings. diff --git a/docs/providers/index.md b/docs/providers/index.md index 18a09e36410..9bd1d86065b 100644 --- a/docs/providers/index.md +++ b/docs/providers/index.md @@ -64,6 +64,7 @@ Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugi - [SGLang (local models)](/providers/sglang) - [StepFun](/providers/stepfun) - [Synthetic](/providers/synthetic) +- [Tencent Cloud (TokenHub)](/providers/tencent) - [Together AI](/providers/together) - [Venice (Venice AI, privacy-focused)](/providers/venice) - [Vercel AI Gateway](/providers/vercel-ai-gateway) diff --git a/docs/providers/litellm.md b/docs/providers/litellm.md index 6e43118f40f..f6bb9087860 100644 --- a/docs/providers/litellm.md +++ b/docs/providers/litellm.md @@ -18,7 +18,8 @@ read_when: - **Virtual keys** — Create keys with spend limits for OpenClaw - **Logging** — Full request/response logs for debugging - **Fallbacks** — Automatic failover if your primary provider is down - + + ## Quick start diff --git a/docs/providers/mistral.md b/docs/providers/mistral.md index ec48d1ee0e2..7eb537be1ca 100644 --- a/docs/providers/mistral.md +++ b/docs/providers/mistral.md @@ -172,7 +172,7 @@ matching `sampleRate` only if your upstream stream is already raw PCM. Choosing providers, model refs, and failover behavior. - + Audio transcription setup and provider selection. diff --git a/docs/providers/moonshot.md b/docs/providers/moonshot.md index 7b1871f8045..f4de2040915 100644 --- a/docs/providers/moonshot.md +++ b/docs/providers/moonshot.md @@ -383,7 +383,7 @@ Config lives under `plugins.entries.moonshot.config.webSearch`: Choosing providers, model refs, and failover behavior. - + Configuring web search providers including Kimi. diff --git a/docs/providers/openai.md b/docs/providers/openai.md index 94cf7eef23c..96e36d887ed 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -445,6 +445,8 @@ Legacy `plugins.entries.openai.config.personality` is still read as a compatibil + + OpenClaw exposes a shared fast-mode toggle for both `openai/*` and `openai-codex/*`: diff --git a/docs/providers/tencent.md b/docs/providers/tencent.md index 5c65f93af40..6685ee51517 100644 --- a/docs/providers/tencent.md +++ b/docs/providers/tencent.md @@ -55,6 +55,6 @@ is available to that process (for example, in `~/.openclaw/.env` or via ## Related documentation -- [OpenClaw Configuration](/configuration) +- [OpenClaw Configuration](/gateway/configuration) - [Model Providers](/concepts/model-providers) - [Tencent TokenHub](https://cloud.tencent.com/document/product/1823/130050) diff --git a/docs/providers/volcengine.md b/docs/providers/volcengine.md index e0afa94628a..16d8782de63 100644 --- a/docs/providers/volcengine.md +++ b/docs/providers/volcengine.md @@ -131,7 +131,7 @@ interactive shell are not automatically inherited. See the daemon note above. Choosing providers, model refs, and failover behavior. - + Full config reference for agents, models, and providers. diff --git a/docs/refactor/async-exec-duplicate-completion-investigation.md b/docs/refactor/async-exec-duplicate-completion-investigation.md index 622b34cb297..2c108cf1a05 100644 --- a/docs/refactor/async-exec-duplicate-completion-investigation.md +++ b/docs/refactor/async-exec-duplicate-completion-investigation.md @@ -1,3 +1,11 @@ +--- +summary: "Investigation notes for duplicate async exec completion injection" +read_when: + - Debugging repeated node exec completion events + - Working on heartbeat/system-event dedupe +title: "Async Exec Duplicate Completion Investigation" +--- + # Async Exec Duplicate Completion Investigation ## Scope diff --git a/docs/refactor/qa.md b/docs/refactor/qa.md index e22a6d52fba..5d9b4b7e651 100644 --- a/docs/refactor/qa.md +++ b/docs/refactor/qa.md @@ -1,3 +1,11 @@ +--- +summary: "QA refactor plan for scenario catalog and harness consolidation" +read_when: + - Refactoring QA scenario definitions or qa-lab harness code + - Moving QA behavior between markdown scenarios and TypeScript harness logic +title: "QA Refactor" +--- + # QA Refactor Status: foundational migration landed. diff --git a/docs/reference/rich-output-protocol.md b/docs/reference/rich-output-protocol.md index c1547d586aa..665f5b9a9d6 100644 --- a/docs/reference/rich-output-protocol.md +++ b/docs/reference/rich-output-protocol.md @@ -1,3 +1,11 @@ +--- +summary: "Rich output shortcode protocol for embeds, media, audio hints, and replies" +read_when: + - Changing assistant output rendering in the Control UI + - Debugging `[embed ...]`, `MEDIA:`, reply, or audio presentation directives +title: "Rich Output Protocol" +--- + # Rich Output Protocol Assistant output can carry a small set of delivery/render directives: diff --git a/docs/start/showcase.md b/docs/start/showcase.md index 83dc6f4395d..bd9b4d858ee 100644 --- a/docs/start/showcase.md +++ b/docs/start/showcase.md @@ -7,8 +7,6 @@ read_when: - Updating community project highlights --- - - # Showcase
@@ -54,7 +52,7 @@ read_when: Submit a project
-

Videos

+## Videos

Start here if you want the shortest path from “what is this?” to “okay, I get it.” @@ -107,7 +105,7 @@ read_when: -

Fresh from Discord

+## Fresh from Discord

Recent standouts across coding, devtools, mobile, and chat-native product building. @@ -234,7 +232,9 @@ Read, send, and archive messages via Beeper Desktop. Uses Beeper local MCP API s -

Automation & Workflows

+ + +## Automation & Workflows

Scheduling, browser control, support loops, and the “just do the task for me” side of the product. @@ -316,7 +316,9 @@ Watches company Slack channel, responds helpfully, and forwards notifications to -

Knowledge & Memory

+ + +## Knowledge & Memory

Systems that index, search, remember, and reason over personal or team knowledge. @@ -352,7 +354,9 @@ Watches company Slack channel, responds helpfully, and forwards notifications to -

Voice & Phone

+ + +## Voice & Phone

Speech-first entry points, phone bridges, and transcription-heavy workflows. @@ -374,7 +378,9 @@ Multi-lingual audio transcription via OpenRouter (Gemini, etc). Available on Cla -

Infrastructure & Deployment

+ + +## Infrastructure & Deployment

Packaging, deployment, and integrations that make OpenClaw easier to run and extend. @@ -408,7 +414,9 @@ Multi-lingual audio transcription via OpenRouter (Gemini, etc). Available on Cla -

Home & Hardware

+ + +## Home & Hardware

The physical-world side of OpenClaw: homes, sensors, cameras, vacuums, and other devices. @@ -434,7 +442,7 @@ Multi-lingual audio transcription via OpenRouter (Gemini, etc). Available on Cla -

Community Projects

+## Community Projects

Things that grew beyond a single workflow into broader products or ecosystems. @@ -452,7 +460,7 @@ Multi-lingual audio transcription via OpenRouter (Gemini, etc). Available on Cla --- -

Submit Your Project

+## Submit Your Project

If you are building something interesting with OpenClaw, send it over. Strong screenshots and concrete outcomes help. diff --git a/docs/tools/index.md b/docs/tools/index.md index d43f005ef46..efa37d285d0 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -53,24 +53,24 @@ OpenClaw has three layers that work together: These tools ship with OpenClaw and are available without installing any plugins: -| Tool | What it does | Page | -| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------- | -| `exec` / `process` | Run shell commands, manage background processes | [Exec](/tools/exec) | -| `code_execution` | Run sandboxed remote Python analysis | [Code Execution](/tools/code-execution) | -| `browser` | Control a Chromium browser (navigate, click, screenshot) | [Browser](/tools/browser) | -| `web_search` / `x_search` / `web_fetch` | Search the web, search X posts, fetch page content | [Web](/tools/web) | -| `read` / `write` / `edit` | File I/O in the workspace | | -| `apply_patch` | Multi-hunk file patches | [Apply Patch](/tools/apply-patch) | -| `message` | Send messages across all channels | [Agent Send](/tools/agent-send) | -| `canvas` | Drive node Canvas (present, eval, snapshot) | | -| `nodes` | Discover and target paired devices | | -| `cron` / `gateway` | Manage scheduled jobs; inspect, patch, restart, or update the gateway | | -| `image` / `image_generate` | Analyze or generate images | [Image Generation](/tools/image-generation) | -| `music_generate` | Generate music tracks | [Music Generation](/tools/music-generation) | -| `video_generate` | Generate videos | [Video Generation](/tools/video-generation) | -| `tts` | One-shot text-to-speech conversion | [TTS](/tools/tts) | -| `sessions_*` / `subagents` / `agents_list` | Session management, status, and sub-agent orchestration | [Sub-agents](/tools/subagents) | -| `session_status` | Lightweight `/status`-style readback and session model override | [Session Tools](/concepts/session-tool) | +| Tool | What it does | Page | +| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ | +| `exec` / `process` | Run shell commands, manage background processes | [Exec](/tools/exec), [Exec Approvals](/tools/exec-approvals) | +| `code_execution` | Run sandboxed remote Python analysis | [Code Execution](/tools/code-execution) | +| `browser` | Control a Chromium browser (navigate, click, screenshot) | [Browser](/tools/browser) | +| `web_search` / `x_search` / `web_fetch` | Search the web, search X posts, fetch page content | [Web](/tools/web), [Web Fetch](/tools/web-fetch) | +| `read` / `write` / `edit` | File I/O in the workspace | | +| `apply_patch` | Multi-hunk file patches | [Apply Patch](/tools/apply-patch) | +| `message` | Send messages across all channels | [Agent Send](/tools/agent-send) | +| `canvas` | Drive node Canvas (present, eval, snapshot) | | +| `nodes` | Discover and target paired devices | | +| `cron` / `gateway` | Manage scheduled jobs; inspect, patch, restart, or update the gateway | | +| `image` / `image_generate` | Analyze or generate images | [Image Generation](/tools/image-generation) | +| `music_generate` | Generate music tracks | [Music Generation](/tools/music-generation) | +| `video_generate` | Generate videos | [Video Generation](/tools/video-generation) | +| `tts` | One-shot text-to-speech conversion | [TTS](/tools/tts) | +| `sessions_*` / `subagents` / `agents_list` | Session management, status, and sub-agent orchestration | [Sub-agents](/tools/subagents) | +| `session_status` | Lightweight `/status`-style readback and session model override | [Session Tools](/concepts/session-tool) | For image work, use `image` for analysis and `image_generate` for generation or editing. If you target `openai/*`, `google/*`, `fal/*`, or another non-default image provider, configure that provider's auth/API key first. diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index e29883c2047..99bf8d899f0 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -133,7 +133,7 @@ Looking for third-party plugins? See [Community Plugins](/plugins/community). enabled: true, allow: ["voice-call"], deny: ["untrusted-plugin"], - load: { paths: ["~/Projects/oss/voice-call-extension"] }, + load: { paths: ["~/Projects/oss/voice-call-plugin"] }, entries: { "voice-call": { enabled: true, config: { provider: "twilio" } }, }, diff --git a/docs/tts.md b/docs/tts.md index e212b3cb32a..9fecbeac043 100644 --- a/docs/tts.md +++ b/docs/tts.md @@ -1,5 +1,6 @@ --- title: "Text-to-Speech" +summary: "Redirect to /tools/tts" redirect: /tools/tts --- diff --git a/extensions/openai/index.test.ts b/extensions/openai/index.test.ts index a42d1f9dd55..b7e60cd5a83 100644 --- a/extensions/openai/index.test.ts +++ b/extensions/openai/index.test.ts @@ -21,6 +21,12 @@ const runtimeMocks = vi.hoisted(() => ({ refreshOpenAICodexToken: vi.fn(), })); +type OpenAIRefreshDelegateGlobal = typeof globalThis & { + __OPENCLAW_TEST_REFRESH_OPENAI_CODEX_TOKEN__?: (...args: unknown[]) => unknown; +}; + +const openAIRefreshDelegateGlobal = () => globalThis as OpenAIRefreshDelegateGlobal; + vi.mock("openclaw/plugin-sdk/runtime-env", async () => { const actual = await vi.importActual( "openclaw/plugin-sdk/runtime-env", @@ -31,15 +37,14 @@ vi.mock("openclaw/plugin-sdk/runtime-env", async () => { }; }); -vi.mock("@mariozechner/pi-ai/oauth", async () => { - const actual = await vi.importActual( - "@mariozechner/pi-ai/oauth", - ); - return { - ...actual, - refreshOpenAICodexToken: runtimeMocks.refreshOpenAICodexToken, - }; -}); +vi.mock("@mariozechner/pi-ai/oauth", () => ({ + getOAuthApiKey: vi.fn(), + getOAuthProviders: () => [], + loginOpenAICodex: vi.fn(), + refreshOpenAICodexToken: vi.fn((...args: unknown[]) => + openAIRefreshDelegateGlobal().__OPENCLAW_TEST_REFRESH_OPENAI_CODEX_TOKEN__?.(...args), + ), +})); import { refreshOpenAICodexToken } from "./openai-codex-provider.runtime.js"; @@ -282,14 +287,19 @@ describe("openai plugin", () => { expires: Date.now() + 60_000, }; runtimeMocks.refreshOpenAICodexToken.mockResolvedValue(refreshed); + openAIRefreshDelegateGlobal().__OPENCLAW_TEST_REFRESH_OPENAI_CODEX_TOKEN__ = + runtimeMocks.refreshOpenAICodexToken; + try { + await expect(refreshOpenAICodexToken("refresh-token")).resolves.toBe(refreshed); - await expect(refreshOpenAICodexToken("refresh-token")).resolves.toBe(refreshed); - - expect(runtimeMocks.ensureGlobalUndiciEnvProxyDispatcher).toHaveBeenCalledOnce(); - expect(runtimeMocks.refreshOpenAICodexToken).toHaveBeenCalledOnce(); - expect( - runtimeMocks.ensureGlobalUndiciEnvProxyDispatcher.mock.invocationCallOrder[0], - ).toBeLessThan(runtimeMocks.refreshOpenAICodexToken.mock.invocationCallOrder[0]); + expect(runtimeMocks.ensureGlobalUndiciEnvProxyDispatcher).toHaveBeenCalledOnce(); + expect(runtimeMocks.refreshOpenAICodexToken).toHaveBeenCalledOnce(); + expect( + runtimeMocks.ensureGlobalUndiciEnvProxyDispatcher.mock.invocationCallOrder[0], + ).toBeLessThan(runtimeMocks.refreshOpenAICodexToken.mock.invocationCallOrder[0]); + } finally { + delete openAIRefreshDelegateGlobal().__OPENCLAW_TEST_REFRESH_OPENAI_CODEX_TOKEN__; + } }); it("registers provider-owned OpenAI tool compat hooks for openai and codex", async () => { diff --git a/scripts/codespell-ignore.txt b/scripts/codespell-ignore.txt index 3c242f6a2e2..22fb46a9d3e 100644 --- a/scripts/codespell-ignore.txt +++ b/scripts/codespell-ignore.txt @@ -7,3 +7,7 @@ OptionA CAF overlayed re-use +AKS +Ballance +optIn +wit diff --git a/test/setup.shared.ts b/test/setup.shared.ts index cdd96346a20..3ad9f77286e 100644 --- a/test/setup.shared.ts +++ b/test/setup.shared.ts @@ -1,9 +1,17 @@ import { vi } from "vitest"; +declare global { + // Optional per-test delegate for the shared OAuth mock. + var __OPENCLAW_TEST_REFRESH_OPENAI_CODEX_TOKEN__: ((...args: unknown[]) => unknown) | undefined; +} + vi.mock("@mariozechner/pi-ai/oauth", () => ({ getOAuthApiKey: () => undefined, getOAuthProviders: () => [], loginOpenAICodex: vi.fn(), + refreshOpenAICodexToken: vi.fn((...args: unknown[]) => + globalThis.__OPENCLAW_TEST_REFRESH_OPENAI_CODEX_TOKEN__?.(...args), + ), })); vi.mock("@mariozechner/clipboard", () => ({