diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 00000000000..0b6b8f0fb71 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,52 @@ +{ + "globs": ["docs/**/*.md", "docs/**/*.mdx", "README.md"], + "ignores": ["docs/zh-CN/**", "docs/.i18n/**", "docs/reference/templates/**"], + "config": { + "default": true, + + "MD013": false, + "MD025": false, + "MD029": false, + + "MD033": { + "allowed_elements": [ + "Note", + "Info", + "Tip", + "Warning", + "Card", + "CardGroup", + "Columns", + "Steps", + "Step", + "Tabs", + "Tab", + "Accordion", + "AccordionGroup", + "CodeGroup", + "Frame", + "Callout", + "ParamField", + "ResponseField", + "RequestExample", + "ResponseExample", + "img", + "a", + "br", + "details", + "summary", + "p", + "strong", + "picture", + "source", + "Tooltip", + "Check", + ], + }, + + "MD036": false, + "MD040": false, + "MD041": false, + "MD046": false, + }, +} diff --git a/docs/brave-search.md b/docs/brave-search.md index 2606479422b..ba18a6c552d 100644 --- a/docs/brave-search.md +++ b/docs/brave-search.md @@ -12,7 +12,7 @@ OpenClaw uses Brave Search as the default provider for `web_search`. ## Get an API key -1. Create a Brave Search API account at https://brave.com/search/api/ +1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/) 2. In the dashboard, choose the **Data for Search** plan and generate an API key. 3. Store the key in config (recommended) or set `BRAVE_API_KEY` in the Gateway environment. diff --git a/docs/channels/bluebubbles.md b/docs/channels/bluebubbles.md index b40fc375da2..1f1ee40ea3e 100644 --- a/docs/channels/bluebubbles.md +++ b/docs/channels/bluebubbles.md @@ -27,6 +27,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R 1. Install the BlueBubbles server on your Mac (follow the instructions at [bluebubbles.app/install](https://bluebubbles.app/install)). 2. In the BlueBubbles config, enable the web API and set a password. 3. Run `openclaw onboard` and select BlueBubbles, or configure manually: + ```json5 { channels: { @@ -39,6 +40,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R }, } ``` + 4. Point BlueBubbles webhooks to your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=`). 5. Start the gateway; it will register the webhook handler and start pairing. diff --git a/docs/channels/feishu.md b/docs/channels/feishu.md index 2c6ba1e7f42..e15feafe345 100644 --- a/docs/channels/feishu.md +++ b/docs/channels/feishu.md @@ -75,7 +75,7 @@ Choose **Feishu**, then enter the App ID and App Secret. Visit [Feishu Open Platform](https://open.feishu.cn/app) and sign in. -Lark (global) tenants should use https://open.larksuite.com/app and set `domain: "lark"` in the Feishu config. +Lark (global) tenants should use [https://open.larksuite.com/app](https://open.larksuite.com/app) and set `domain: "lark"` in the Feishu config. ### 2. Create an app @@ -261,10 +261,12 @@ After approval, you can chat normally. - **Default**: `dmPolicy: "pairing"` (unknown users get a pairing code) - **Approve pairing**: + ```bash openclaw pairing list feishu openclaw pairing approve feishu ``` + - **Allowlist mode**: set `channels.feishu.allowFrom` with allowed Open IDs ### Group chats diff --git a/docs/channels/googlechat.md b/docs/channels/googlechat.md index 07c7dd7dc69..39192ecae2f 100644 --- a/docs/channels/googlechat.md +++ b/docs/channels/googlechat.md @@ -101,6 +101,7 @@ Use Tailscale Serve for the private dashboard and Funnel for the public webhook If prompted, visit the authorization URL shown in the output to enable Funnel for this node in your tailnet policy. 5. **Verify the configuration:** + ```bash tailscale serve status tailscale funnel status @@ -225,6 +226,7 @@ This means the webhook handler isn't registered. Common causes: If it shows "disabled", add `plugins.entries.googlechat.enabled: true` to your config. 3. **Gateway not restarted**: After adding config, restart the gateway: + ```bash openclaw gateway restart ``` diff --git a/docs/channels/line.md b/docs/channels/line.md index f68ae5aa1e8..d32e683fbeb 100644 --- a/docs/channels/line.md +++ b/docs/channels/line.md @@ -34,7 +34,7 @@ openclaw plugins install ./extensions/line ## Setup 1. Create a LINE Developers account and open the Console: - https://developers.line.biz/console/ + [https://developers.line.biz/console/](https://developers.line.biz/console/) 2. Create (or pick) a Provider and add a **Messaging API** channel. 3. Copy the **Channel access token** and **Channel secret** from the channel settings. 4. Enable **Use webhook** in the Messaging API settings. diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md index a196a68b674..56b363fdd9a 100644 --- a/docs/channels/matrix.md +++ b/docs/channels/matrix.md @@ -74,7 +74,7 @@ Details: [Plugins](/plugin) - When set, `channels.matrix.userId` should be the full Matrix ID (example: `@bot:example.org`). 5. Restart the gateway (or finish onboarding). 6. Start a DM with the bot or invite it to a room from any Matrix client - (Element, Beeper, etc.; see https://matrix.org/ecosystem/clients/). Beeper requires E2EE, + (Element, Beeper, etc.; see [https://matrix.org/ecosystem/clients/](https://matrix.org/ecosystem/clients/)). Beeper requires E2EE, so set `channels.matrix.encryption: true` and verify the device. Minimal config (access token, user ID auto-fetched): diff --git a/docs/channels/msteams.md b/docs/channels/msteams.md index a18e8063d04..572ff1284ab 100644 --- a/docs/channels/msteams.md +++ b/docs/channels/msteams.md @@ -558,6 +558,7 @@ Bots don't have a personal OneDrive drive (the `/me/drive` Graph API endpoint do ``` 4. **Configure OpenClaw:** + ```json5 { channels: { @@ -747,7 +748,7 @@ Bots have limited support in private channels: - **"Icon file cannot be empty":** The manifest references icon files that are 0 bytes. Create valid PNG icons (32x32 for `outline.png`, 192x192 for `color.png`). - **"webApplicationInfo.Id already in use":** The app is still installed in another team/chat. Find and uninstall it first, or wait 5-10 minutes for propagation. -- **"Something went wrong" on upload:** Upload via https://admin.teams.microsoft.com instead, open browser DevTools (F12) → Network tab, and check the response body for the actual error. +- **"Something went wrong" on upload:** Upload via [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) instead, open browser DevTools (F12) → Network tab, and check the response body for the actual error. - **Sideload failing:** Try "Upload an app to your org's app catalog" instead of "Upload a custom app" - this often bypasses sideload restrictions. ### RSC permissions not working diff --git a/docs/channels/nextcloud-talk.md b/docs/channels/nextcloud-talk.md index edca54bc44c..efecfd99001 100644 --- a/docs/channels/nextcloud-talk.md +++ b/docs/channels/nextcloud-talk.md @@ -34,9 +34,11 @@ Details: [Plugins](/plugin) 1. Install the Nextcloud Talk plugin. 2. On your Nextcloud server, create a bot: + ```bash ./occ talk:bot:install "OpenClaw" "" "" --feature reaction ``` + 3. Enable the bot in the target room settings. 4. Configure OpenClaw: - Config: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret` diff --git a/docs/channels/slack.md b/docs/channels/slack.md index a9dbc246672..1343ebf77d6 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -30,7 +30,7 @@ Minimal config: ### Setup -1. Create a Slack app (From scratch) in https://api.slack.com/apps. +1. Create a Slack app (From scratch) in [https://api.slack.com/apps](https://api.slack.com/apps). 2. **Socket Mode** → toggle on. Then go to **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes** with scope `connections:write`. Copy the **App Token** (`xapp-...`). 3. **OAuth & Permissions** → add bot token scopes (use the manifest below). Click **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`). 4. Optional: **OAuth & Permissions** → add **User Token Scopes** (see the read-only list below). Reinstall the app and copy the **User OAuth Token** (`xoxp-...`). @@ -49,7 +49,7 @@ Use the manifest below so scopes and events stay in sync. Multi-account support: use `channels.slack.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern. -### OpenClaw config (minimal) +### OpenClaw config (Socket mode) Set tokens via env vars (recommended): @@ -130,7 +130,7 @@ Example with userTokenReadOnly explicitly set (allow user token writes): Use HTTP webhook mode when your Gateway is reachable by Slack over HTTPS (typical for server deployments). HTTP mode uses the Events API + Interactivity + Slash Commands with a shared request URL. -### Setup +### Setup (HTTP mode) 1. Create a Slack app and **disable Socket Mode** (optional if you only use HTTP). 2. **Basic Information** → copy the **Signing Secret**. @@ -260,30 +260,30 @@ If you enable native commands, add one `slash_commands` entry per command you wa Slack's Conversations API is type-scoped: you only need the scopes for the conversation types you actually touch (channels, groups, im, mpim). See -https://docs.slack.dev/apis/web-api/using-the-conversations-api/ for the overview. +[https://docs.slack.dev/apis/web-api/using-the-conversations-api/](https://docs.slack.dev/apis/web-api/using-the-conversations-api/) for the overview. ### Bot token scopes (required) - `chat:write` (send/update/delete messages via `chat.postMessage`) - https://docs.slack.dev/reference/methods/chat.postMessage + [https://docs.slack.dev/reference/methods/chat.postMessage](https://docs.slack.dev/reference/methods/chat.postMessage) - `im:write` (open DMs via `conversations.open` for user DMs) - https://docs.slack.dev/reference/methods/conversations.open + [https://docs.slack.dev/reference/methods/conversations.open](https://docs.slack.dev/reference/methods/conversations.open) - `channels:history`, `groups:history`, `im:history`, `mpim:history` - https://docs.slack.dev/reference/methods/conversations.history + [https://docs.slack.dev/reference/methods/conversations.history](https://docs.slack.dev/reference/methods/conversations.history) - `channels:read`, `groups:read`, `im:read`, `mpim:read` - https://docs.slack.dev/reference/methods/conversations.info + [https://docs.slack.dev/reference/methods/conversations.info](https://docs.slack.dev/reference/methods/conversations.info) - `users:read` (user lookup) - https://docs.slack.dev/reference/methods/users.info + [https://docs.slack.dev/reference/methods/users.info](https://docs.slack.dev/reference/methods/users.info) - `reactions:read`, `reactions:write` (`reactions.get` / `reactions.add`) - https://docs.slack.dev/reference/methods/reactions.get - https://docs.slack.dev/reference/methods/reactions.add + [https://docs.slack.dev/reference/methods/reactions.get](https://docs.slack.dev/reference/methods/reactions.get) + [https://docs.slack.dev/reference/methods/reactions.add](https://docs.slack.dev/reference/methods/reactions.add) - `pins:read`, `pins:write` (`pins.list` / `pins.add` / `pins.remove`) - https://docs.slack.dev/reference/scopes/pins.read - https://docs.slack.dev/reference/scopes/pins.write + [https://docs.slack.dev/reference/scopes/pins.read](https://docs.slack.dev/reference/scopes/pins.read) + [https://docs.slack.dev/reference/scopes/pins.write](https://docs.slack.dev/reference/scopes/pins.write) - `emoji:read` (`emoji.list`) - https://docs.slack.dev/reference/scopes/emoji.read + [https://docs.slack.dev/reference/scopes/emoji.read](https://docs.slack.dev/reference/scopes/emoji.read) - `files:write` (uploads via `files.uploadV2`) - https://docs.slack.dev/messaging/working-with-files/#upload + [https://docs.slack.dev/messaging/working-with-files/#upload](https://docs.slack.dev/messaging/working-with-files/#upload) ### User token scopes (optional, read-only by default) @@ -302,9 +302,9 @@ Add these under **User Token Scopes** if you configure `channels.slack.userToken - `mpim:write` (only if we add group-DM open/DM start via `conversations.open`) - `groups:write` (only if we add private-channel management: create/rename/invite/archive) - `chat:write.public` (only if we want to post to channels the bot isn't in) - https://docs.slack.dev/reference/scopes/chat.write.public + [https://docs.slack.dev/reference/scopes/chat.write.public](https://docs.slack.dev/reference/scopes/chat.write.public) - `users:read.email` (only if we need email fields from `users.info`) - https://docs.slack.dev/changelog/2017-04-narrowing-email-access + [https://docs.slack.dev/changelog/2017-04-narrowing-email-access](https://docs.slack.dev/changelog/2017-04-narrowing-email-access) - `files:read` (only if we start listing/reading file metadata) ## Config diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index 655749d8763..609daf9a6ca 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -147,7 +147,7 @@ You can add custom commands to the menu via config: } ``` -## Troubleshooting +## Setup troubleshooting (commands) - `setMyCommands failed` in logs usually means outbound HTTPS/DNS is blocked to `api.telegram.org`. - If you see `sendMessage` or `sendChatAction` failures, check IPv6 routing and DNS. @@ -365,6 +365,7 @@ Alternate (official Bot API): 1. DM your bot. 2. Fetch updates with your bot token and read `message.from.id`: + ```bash curl "https://api.telegram.org/bot/getUpdates" ``` diff --git a/docs/channels/twitch.md b/docs/channels/twitch.md index 7901c042781..ac46e35d6ee 100644 --- a/docs/channels/twitch.md +++ b/docs/channels/twitch.md @@ -34,7 +34,7 @@ Details: [Plugins](/plugin) - Select **Bot Token** - Verify scopes `chat:read` and `chat:write` are selected - Copy the **Client ID** and **Access Token** -3. Find your Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ +3. Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) 4. Configure the token: - Env: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (default account only) - Or config: `channels.twitch.accessToken` @@ -123,7 +123,7 @@ Prefer `allowFrom` for a hard allowlist. Use `allowedRoles` instead if you want **Why user IDs?** Usernames can change, allowing impersonation. User IDs are permanent. -Find your Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/ (Convert your Twitch username to ID) +Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/) (Convert your Twitch username to ID) ## Token refresh (optional) diff --git a/docs/channels/whatsapp.md b/docs/channels/whatsapp.md index 1741ee1b7e0..966c0902aa3 100644 --- a/docs/channels/whatsapp.md +++ b/docs/channels/whatsapp.md @@ -205,11 +205,13 @@ The wizard uses it to set your **allowlist/owner** so your own DMs are permitted - `Body` is the current message body with envelope. - Quoted reply context is **always appended**: + ``` [Replying to +1555 id:ABC123] > [/Replying] ``` + - Reply metadata also set: - `ReplyToId` = stanzaId - `ReplyToBody` = quoted body or media placeholder diff --git a/docs/channels/zalo.md b/docs/channels/zalo.md index 0f247190c36..88143dd58e7 100644 --- a/docs/channels/zalo.md +++ b/docs/channels/zalo.md @@ -57,7 +57,7 @@ It is a good fit for support or notifications where you want deterministic routi ### 1) Create a bot token (Zalo Bot Platform) -1. Go to **https://bot.zaloplatforms.com** and sign in. +1. Go to [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) and sign in. 2. Create a new bot and configure its settings. 3. Copy the bot token (format: `12345689:abc-xyz`). diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md index a1c7f3383cc..a9676b171ce 100644 --- a/docs/concepts/architecture.md +++ b/docs/concepts/architecture.md @@ -110,9 +110,11 @@ Details: [Gateway protocol](/gateway/protocol), [Pairing](/start/pairing), - Preferred: Tailscale or VPN. - Alternative: SSH tunnel + ```bash ssh -N -L 18789:127.0.0.1:18789 user@host ``` + - The same handshake + auth token apply over the tunnel. - TLS + optional pinning can be enabled for WS in remote setups. diff --git a/docs/concepts/groups.md b/docs/concepts/groups.md index 04e90106ded..635211d3363 100644 --- a/docs/concepts/groups.md +++ b/docs/concepts/groups.md @@ -39,12 +39,13 @@ otherwise -> reply ![Group message flow](/images/groups-flow.svg) If you want... -| Goal | What to set | -|------|-------------| -| Allow all groups but only reply on @mentions | `groups: { "*": { requireMention: true } }` | -| Disable all group replies | `groupPolicy: "disabled"` | -| Only specific groups | `groups: { "": { ... } }` (no `"*"` key) | -| Only you can trigger in groups | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | + +| Goal | What to set | +| -------------------------------------------- | ---------------------------------------------------------- | +| Allow all groups but only reply on @mentions | `groups: { "*": { requireMention: true } }` | +| Disable all group replies | `groupPolicy: "disabled"` | +| Only specific groups | `groups: { "": { ... } }` (no `"*"` key) | +| Only you can trigger in groups | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | ## Session keys diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md index 4b499860b5b..ea5c08002ee 100644 --- a/docs/concepts/memory.md +++ b/docs/concepts/memory.md @@ -302,8 +302,8 @@ Why OpenAI batch is fast + cheap: - For large backfills, OpenAI is typically the fastest option we support because we can submit many embedding requests in a single batch job and let OpenAI process them asynchronously. - OpenAI offers discounted pricing for Batch API workloads, so large indexing runs are usually cheaper than sending the same requests synchronously. - See the OpenAI Batch API docs and pricing for details: - - https://platform.openai.com/docs/api-reference/batch - - https://platform.openai.com/pricing + - [https://platform.openai.com/docs/api-reference/batch](https://platform.openai.com/docs/api-reference/batch) + - [https://platform.openai.com/pricing](https://platform.openai.com/pricing) Config example: diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md index 4d313cf0f22..fba56a34a1d 100644 --- a/docs/concepts/model-providers.md +++ b/docs/concepts/model-providers.md @@ -136,14 +136,14 @@ Moonshot uses OpenAI-compatible endpoints, so configure it as a custom provider: Kimi K2 model IDs: -{/_ moonshot-kimi-k2-model-refs:start _/ && null} +{/_moonshot-kimi-k2-model-refs:start_/ && null} - `moonshot/kimi-k2.5` - `moonshot/kimi-k2-0905-preview` - `moonshot/kimi-k2-turbo-preview` - `moonshot/kimi-k2-thinking` - `moonshot/kimi-k2-thinking-turbo` - {/_ moonshot-kimi-k2-model-refs:end _/ && null} + {/_moonshot-kimi-k2-model-refs:end_/ && null} ```json5 { @@ -242,7 +242,7 @@ Ollama is a local LLM runtime that provides an OpenAI-compatible API: - Provider: `ollama` - Auth: None required (local server) - Example model: `ollama/llama3.3` -- Installation: https://ollama.ai +- Installation: [https://ollama.ai](https://ollama.ai) ```bash # Install Ollama, then pull a model: diff --git a/docs/concepts/session.md b/docs/concepts/session.md index 922bb960fa8..503dcf37f48 100644 --- a/docs/concepts/session.md +++ b/docs/concepts/session.md @@ -17,7 +17,7 @@ Use `session.dmScope` to control how **direct messages** are grouped: - `per-account-channel-peer`: isolate by account + channel + sender (recommended for multi-account inboxes). Use `session.identityLinks` to map provider-prefixed peer ids to a canonical identity so the same person shares a DM session across channels when using `per-peer`, `per-channel-peer`, or `per-account-channel-peer`. -### Secure DM mode (recommended for multi-user setups) +## Secure DM mode (recommended for multi-user setups) > **Security Warning:** If your agent can receive DMs from **multiple people**, you should strongly consider enabling secure DM mode. Without it, all users share the same conversation context, which can leak private information between users. diff --git a/docs/concepts/system-prompt.md b/docs/concepts/system-prompt.md index aafa80473dd..acb2bf8b5f9 100644 --- a/docs/concepts/system-prompt.md +++ b/docs/concepts/system-prompt.md @@ -110,6 +110,6 @@ This keeps the base prompt small while still enabling targeted skill usage. When available, the system prompt includes a **Documentation** section that points to the local OpenClaw docs directory (either `docs/` in the repo workspace or the bundled npm package docs) and also notes the public mirror, source repo, community Discord, and -ClawHub (https://clawhub.com) for skills discovery. The prompt instructs the model to consult local docs first +ClawHub ([https://clawhub.com](https://clawhub.com)) for skills discovery. The prompt instructs the model to consult local docs first for OpenClaw behavior, commands, configuration, or architecture, and to run `openclaw status` itself when possible (asking the user only when it lacks access). diff --git a/docs/concepts/typebox.md b/docs/concepts/typebox.md index 38ee7d8cac9..f60c5b8ef46 100644 --- a/docs/concepts/typebox.md +++ b/docs/concepts/typebox.md @@ -280,7 +280,7 @@ Unknown frame types are preserved as raw payloads for forward compatibility. Generated JSON Schema is in the repo at `dist/protocol.schema.json`. The published raw file is typically available at: -- https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json +- [https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json](https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json) ## When you change schemas diff --git a/docs/debug/node-issue.md b/docs/debug/node-issue.md index ce46b1a05e7..8355d2abc38 100644 --- a/docs/debug/node-issue.md +++ b/docs/debug/node-issue.md @@ -62,19 +62,21 @@ node --import tsx scripts/repro/tsx-name-repro.ts - Use Bun for dev scripts (current temporary revert). - Use Node + tsc watch, then run compiled output: + ```bash pnpm exec tsc --watch --preserveWatchOutput node --watch openclaw.mjs status ``` + - Confirmed locally: `pnpm exec tsc -p tsconfig.json` + `node openclaw.mjs status` works on Node 25. - Disable esbuild keepNames in the TS loader if possible (prevents `__name` helper insertion); tsx does not currently expose this. - Test Node LTS (22/24) with `tsx` to see if the issue is Node 25–specific. ## References -- https://opennext.js.org/cloudflare/howtos/keep_names -- https://esbuild.github.io/api/#keep-names -- https://github.com/evanw/esbuild/issues/1031 +- [https://opennext.js.org/cloudflare/howtos/keep_names](https://opennext.js.org/cloudflare/howtos/keep_names) +- [https://esbuild.github.io/api/#keep-names](https://esbuild.github.io/api/#keep-names) +- [https://github.com/evanw/esbuild/issues/1031](https://github.com/evanw/esbuild/issues/1031) ## Next steps diff --git a/docs/gateway/bonjour.md b/docs/gateway/bonjour.md index b8f08741e70..9e2ad8753ae 100644 --- a/docs/gateway/bonjour.md +++ b/docs/gateway/bonjour.md @@ -105,10 +105,13 @@ The Gateway advertises small non‑secret hints to make UI flows convenient: Useful built‑in tools: - Browse instances: + ```bash dns-sd -B _openclaw-gw._tcp local. ``` + - Resolve one instance (replace ``): + ```bash dns-sd -L "" _openclaw-gw._tcp local. ``` diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 0a5a85f1d77..639f84bd6e7 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -1310,13 +1310,14 @@ Thread session isolation: - `channels.slack.thread.inheritParent` controls whether new thread sessions inherit the parent channel transcript (default: false). Slack action groups (gate `slack` tool actions): -| Action group | Default | Notes | -| --- | --- | --- | -| reactions | enabled | React + list reactions | -| messages | enabled | Read/send/edit/delete | -| pins | enabled | Pin/unpin/list | -| memberInfo | enabled | Member info | -| emojiList | enabled | Custom emoji list | + +| Action group | Default | Notes | +| ------------ | ------- | ---------------------- | +| reactions | enabled | React + list reactions | +| messages | enabled | Read/send/edit/delete | +| pins | enabled | Pin/unpin/list | +| memberInfo | enabled | Member info | +| emojiList | enabled | Custom emoji list | ### `channels.mattermost` (bot token) @@ -1977,11 +1978,13 @@ Block streaming: - `agents.defaults.blockStreamingChunk`: soft chunking for streamed blocks. Defaults to 800–1200 chars, prefers paragraph breaks (`\n\n`), then newlines, then sentences. Example: + ```json5 { agents: { defaults: { blockStreamingChunk: { minChars: 800, maxChars: 1200 } } }, } ``` + - `agents.defaults.blockStreamingCoalesce`: merge streamed blocks before sending. Defaults to `{ idleMs: 1000 }` and inherits `minChars` from `blockStreamingChunk` with `maxChars` capped to the channel text limit. Signal/Slack/Discord/Google Chat default @@ -1995,11 +1998,13 @@ Block streaming: Modes: `off` (default), `natural` (800–2500ms), `custom` (use `minMs`/`maxMs`). Per-agent override: `agents.list[].humanDelay`. Example: + ```json5 { agents: { defaults: { humanDelay: { mode: "natural" } } }, } ``` + See [/concepts/streaming](/concepts/streaming) for behavior + chunking details. Typing indicators: @@ -2065,7 +2070,7 @@ of `every`, keep `HEARTBEAT.md` tiny, and/or choose a cheaper `model`. - `tools.web.fetch.readability` (default true; disable to use basic HTML cleanup only) - `tools.web.fetch.firecrawl.enabled` (default true when an API key is set) - `tools.web.fetch.firecrawl.apiKey` (optional; defaults to `FIRECRAWL_API_KEY`) -- `tools.web.fetch.firecrawl.baseUrl` (default https://api.firecrawl.dev) +- `tools.web.fetch.firecrawl.baseUrl` (default [https://api.firecrawl.dev](https://api.firecrawl.dev)) - `tools.web.fetch.firecrawl.onlyMainContent` (default true) - `tools.web.fetch.firecrawl.maxAgeMs` (optional) - `tools.web.fetch.firecrawl.timeoutSeconds` (optional) @@ -2481,7 +2486,7 @@ Select the model via `agents.defaults.model.primary` (provider/model). OpenCode Zen is a multi-model gateway with per-model endpoints. OpenClaw uses the built-in `opencode` provider from pi-ai; set `OPENCODE_API_KEY` (or -`OPENCODE_ZEN_API_KEY`) from https://opencode.ai/auth. +`OPENCODE_ZEN_API_KEY`) from [https://opencode.ai/auth](https://opencode.ai/auth). Notes: @@ -3366,7 +3371,7 @@ openclaw dns setup --apply } ``` -## Template variables +## Media model template variables Template placeholders are expanded in `tools.media.*.models[].args` and `tools.media.models[].args` (and any future templated argument fields). diff --git a/docs/gateway/index.md b/docs/gateway/index.md index 06dd72c13d0..64697f1f461 100644 --- a/docs/gateway/index.md +++ b/docs/gateway/index.md @@ -49,9 +49,11 @@ pnpm gateway:watch ## Remote access - Tailscale/VPN preferred; otherwise SSH tunnel: + ```bash ssh -N -L 18789:127.0.0.1:18789 user@host ``` + - Clients then connect to `ws://127.0.0.1:18789` through the tunnel. - If a token is configured, clients must include it in `connect.params.auth.token` even over the tunnel. diff --git a/docs/gateway/local-models.md b/docs/gateway/local-models.md index fe715ab0550..3f7e13d41e6 100644 --- a/docs/gateway/local-models.md +++ b/docs/gateway/local-models.md @@ -52,7 +52,7 @@ Best current local stack. Load MiniMax M2.1 in LM Studio, enable the local serve **Setup checklist** -- Install LM Studio: https://lmstudio.ai +- Install LM Studio: [https://lmstudio.ai](https://lmstudio.ai) - In LM Studio, download the **largest MiniMax M2.1 build available** (avoid “small”/heavily quantized variants), start the server, confirm `http://127.0.0.1:1234/v1/models` lists it. - Keep the model loaded; cold-load adds startup latency. - Adjust `contextWindow`/`maxTokens` if your LM Studio build differs. diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index c6b521048e2..f6bd9173462 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -773,18 +773,22 @@ If it fails, there are new candidates not yet in the baseline. ### If CI fails 1. Reproduce locally: + ```bash detect-secrets scan --baseline .secrets.baseline ``` + 2. Understand the tools: - `detect-secrets scan` finds candidates and compares them to the baseline. - `detect-secrets audit` opens an interactive review to mark each baseline item as real or false positive. 3. For real secrets: rotate/remove them, then re-run the scan to update the baseline. 4. For false positives: run the interactive audit and mark them as false: + ```bash detect-secrets audit .secrets.baseline ``` + 5. If you need new excludes, add them to `.detect-secrets.cfg` and regenerate the baseline with matching `--exclude-files` / `--exclude-lines` flags (the config file is reference-only; detect-secrets doesn’t read it automatically). @@ -814,7 +818,7 @@ Mario asking for find ~ Found a vulnerability in OpenClaw? Please report responsibly: -1. Email: security@openclaw.ai +1. Email: [security@openclaw.ai](mailto:security@openclaw.ai) 2. Don't post publicly until fixed 3. We'll credit you (unless you prefer anonymity) diff --git a/docs/gateway/tailscale.md b/docs/gateway/tailscale.md index 3f4daa11108..3a12b7fe169 100644 --- a/docs/gateway/tailscale.md +++ b/docs/gateway/tailscale.md @@ -121,7 +121,7 @@ Avoid Funnel for browser control; treat node pairing like operator access. ## Learn more -- Tailscale Serve overview: https://tailscale.com/kb/1312/serve -- `tailscale serve` command: https://tailscale.com/kb/1242/tailscale-serve -- Tailscale Funnel overview: https://tailscale.com/kb/1223/tailscale-funnel -- `tailscale funnel` command: https://tailscale.com/kb/1311/tailscale-funnel +- Tailscale Serve overview: [https://tailscale.com/kb/1312/serve](https://tailscale.com/kb/1312/serve) +- `tailscale serve` command: [https://tailscale.com/kb/1242/tailscale-serve](https://tailscale.com/kb/1242/tailscale-serve) +- Tailscale Funnel overview: [https://tailscale.com/kb/1223/tailscale-funnel](https://tailscale.com/kb/1223/tailscale-funnel) +- `tailscale funnel` command: [https://tailscale.com/kb/1311/tailscale-funnel](https://tailscale.com/kb/1311/tailscale-funnel) diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index d9aa303cd88..5f9d51f1dde 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -42,9 +42,11 @@ Fix options: - Re-run onboarding and choose **Anthropic** for that agent. - Or paste a setup-token on the **gateway host**: + ```bash openclaw models auth setup-token --provider anthropic ``` + - Or copy `auth-profiles.json` from the main agent dir to the new agent dir. Verify: @@ -120,13 +122,17 @@ Doctor/service will show runtime state (PID/last exit) and log hints. **Enable more logging:** - Bump file log detail (persisted JSONL): + ```json { "logging": { "level": "debug" } } ``` + - Bump console verbosity (TTY output only): + ```json { "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } } ``` + - Quick tip: `--verbose` affects **console** output only. File logs remain controlled by `logging.level`. See [/logging](/logging) for a full overview of formats, config, and access. @@ -139,10 +145,13 @@ Gateway refuses to start. **Fix (recommended):** - Run the wizard and set the Gateway run mode to **Local**: + ```bash openclaw configure ``` + - Or set it directly: + ```bash openclaw config set gateway.mode local ``` @@ -150,6 +159,7 @@ Gateway refuses to start. **If you meant to run a remote Gateway instead:** - Set a remote URL and keep `gateway.mode=remote`: + ```bash openclaw config set gateway.mode remote openclaw config set gateway.remote.url "wss://gateway.example.com" @@ -554,6 +564,7 @@ Notes: - The git flow only rebases if the repo is clean. Commit or stash changes first. - After switching, run: + ```bash openclaw doctor openclaw gateway restart diff --git a/docs/help/faq.md b/docs/help/faq.md index 2c9e9f1be77..fda1acddb4f 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -9,7 +9,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ## Table of contents -- [Quick start and first-run setup](#quick-start-and-firstrun-setup) +- [Quick start and first-run setup] - [Im stuck whats the fastest way to get unstuck?](#im-stuck-whats-the-fastest-way-to-get-unstuck) - [What's the recommended way to install and set up OpenClaw?](#whats-the-recommended-way-to-install-and-set-up-openclaw) - [How do I open the dashboard after onboarding?](#how-do-i-open-the-dashboard-after-onboarding) @@ -37,7 +37,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [Can I use Claude Max subscription without an API key](#can-i-use-claude-max-subscription-without-an-api-key) - [How does Anthropic "setup-token" auth work?](#how-does-anthropic-setuptoken-auth-work) - [Where do I find an Anthropic setup-token?](#where-do-i-find-an-anthropic-setuptoken) - - [Do you support Claude subscription auth (Claude Code OAuth)?](#do-you-support-claude-subscription-auth-claude-code-oauth) + - [Do you support Claude subscription auth (Claude Pro or Max)?](#do-you-support-claude-subscription-auth-claude-pro-or-max) - [Why am I seeing `HTTP 429: rate_limit_error` from Anthropic?](#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) - [Is AWS Bedrock supported?](#is-aws-bedrock-supported) - [How does Codex auth work?](#how-does-codex-auth-work) @@ -74,7 +74,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [Cron or reminders do not fire. What should I check?](#cron-or-reminders-do-not-fire-what-should-i-check) - [How do I install skills on Linux?](#how-do-i-install-skills-on-linux) - [Can OpenClaw run tasks on a schedule or continuously in the background?](#can-openclaw-run-tasks-on-a-schedule-or-continuously-in-the-background) - - [Can I run Apple/macOS-only skills from Linux?](#can-i-run-applemacosonly-skills-from-linux) + - [Can I run Apple macOS-only skills from Linux?](#can-i-run-apple-macos-only-skills-from-linux) - [Do you have a Notion or HeyGen integration?](#do-you-have-a-notion-or-heygen-integration) - [How do I install the Chrome extension for browser takeover?](#how-do-i-install-the-chrome-extension-for-browser-takeover) - [Sandboxing and memory](#sandboxing-and-memory) @@ -102,7 +102,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [How do I run a central Gateway with specialized workers across devices?](#how-do-i-run-a-central-gateway-with-specialized-workers-across-devices) - [Can the OpenClaw browser run headless?](#can-the-openclaw-browser-run-headless) - [How do I use Brave for browser control?](#how-do-i-use-brave-for-browser-control) -- [Remote gateways + nodes](#remote-gateways-nodes) +- [Remote gateways and nodes](#remote-gateways-and-nodes) - [How do commands propagate between Telegram, the gateway, and nodes?](#how-do-commands-propagate-between-telegram-the-gateway-and-nodes) - [How can my agent access my computer if the Gateway is hosted remotely?](#how-can-my-agent-access-my-computer-if-the-gateway-is-hosted-remotely) - [Tailscale is connected but I get no replies. What now?](#tailscale-is-connected-but-i-get-no-replies-what-now) @@ -119,7 +119,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [How does OpenClaw load environment variables?](#how-does-openclaw-load-environment-variables) - ["I started the Gateway via the service and my env vars disappeared." What now?](#i-started-the-gateway-via-the-service-and-my-env-vars-disappeared-what-now) - [I set `COPILOT_GITHUB_TOKEN`, but models status shows "Shell env: off." Why?](#i-set-copilotgithubtoken-but-models-status-shows-shell-env-off-why) -- [Sessions & multiple chats](#sessions-multiple-chats) +- [Sessions and multiple chats](#sessions-and-multiple-chats) - [How do I start a fresh conversation?](#how-do-i-start-a-fresh-conversation) - [Do sessions reset automatically if I never send `/new`?](#do-sessions-reset-automatically-if-i-never-send-new) - [Is there a way to make a team of OpenClaw instances one CEO and many agents](#is-there-a-way-to-make-a-team-of-openclaw-instances-one-ceo-and-many-agents) @@ -179,7 +179,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [How do I completely stop then start the Gateway?](#how-do-i-completely-stop-then-start-the-gateway) - [ELI5: `openclaw gateway restart` vs `openclaw gateway`](#eli5-openclaw-gateway-restart-vs-openclaw-gateway) - [What's the fastest way to get more details when something fails?](#whats-the-fastest-way-to-get-more-details-when-something-fails) -- [Media & attachments](#media-attachments) +- [Media and attachments](#media-and-attachments) - [My skill generated an image/PDF, but nothing was sent](#my-skill-generated-an-imagepdf-but-nothing-was-sent) - [Security and access control](#security-and-access-control) - [Is it safe to expose OpenClaw to inbound DMs?](#is-it-safe-to-expose-openclaw-to-inbound-dms) @@ -252,10 +252,12 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, Repairs/migrates config/state + runs health checks. See [Doctor](/gateway/doctor). 7. **Gateway snapshot** + ```bash openclaw health --json openclaw health --verbose # shows the target URL + config path on errors ``` + Asks the running gateway for a full snapshot (WS-only). See [Health](/gateway/health). ## Quick start and first-run setup @@ -266,8 +268,8 @@ Use a local AI agent that can **see your machine**. That is far more effective t in Discord, because most "I'm stuck" cases are **local config or environment issues** that remote helpers cannot inspect. -- **Claude Code**: https://www.anthropic.com/claude-code/ -- **OpenAI Codex**: https://openai.com/codex/ +- **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) +- **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) These tools can read the repo, run commands, inspect logs, and help fix your machine-level setup (PATH, services, permissions, auth files). Give them the **full source checkout** via @@ -285,8 +287,8 @@ Tip: ask the agent to **plan and supervise** the fix (step-by-step), then execut necessary commands. That keeps changes small and easier to audit. If you discover a real bug or fix, please file a GitHub issue or send a PR: -https://github.com/openclaw/openclaw/issues -https://github.com/openclaw/openclaw/pulls +[https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) +[https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) Start with these commands (share outputs when asking for help): @@ -432,7 +434,7 @@ Related: [Migrating](/install/migrating), [Where things live on disk](/help/faq# ### Where do I see what is new in the latest version Check the GitHub changelog: -https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md +[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) Newest entries are at the top. If the top section is marked **Unreleased**, the next dated section is the latest shipped version. Entries are grouped by **Highlights**, **Changes**, and @@ -443,10 +445,10 @@ section is the latest shipped version. Entries are grouped by **Highlights**, ** Some Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity Advanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. More detail: [Troubleshooting](/help/troubleshooting#docsopenclawai-shows-an-ssl-error-comcastxfinity). -Please help us unblock it by reporting here: https://spa.xfinity.com/check_url_status. +Please help us unblock it by reporting here: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). If you still can't reach the site, the docs are mirrored on GitHub: -https://github.com/openclaw/openclaw/tree/main/docs +[https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) ### What's the difference between stable and beta @@ -460,7 +462,7 @@ that same version to `latest`**. That's why beta and stable can point at the **same version**. See what changed: -https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md +[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) ### How do I install the beta version and whats the difference between beta and dev @@ -478,7 +480,7 @@ curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s - ``` Windows installer (PowerShell): -https://openclaw.ai/install.ps1 +[https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer). @@ -559,9 +561,11 @@ Two common Windows issues: - Your npm global bin folder is not on PATH. - Check the path: + ```powershell npm config get prefix ``` + - Ensure `\\bin` is on PATH (on most systems it is `%AppData%\\npm`). - Close and reopen PowerShell after updating PATH. @@ -685,7 +689,7 @@ claude setup-token Copy the token it prints, then choose **Anthropic token (paste setup-token)** in the wizard. If you want to run it on the gateway host, use `openclaw models auth setup-token --provider anthropic`. If you ran `claude setup-token` elsewhere, paste it on the gateway host with `openclaw models auth paste-token --provider anthropic`. See [Anthropic](/providers/anthropic). -### Do you support Claude subscription auth (Claude Pro/Max) +### Do you support Claude subscription auth (Claude Pro or Max) Yes - via **setup-token**. OpenClaw no longer reuses Claude Code CLI OAuth tokens; use a setup-token or an Anthropic API key. Generate the token anywhere and paste it on the gateway host. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth). @@ -988,7 +992,7 @@ Advantages: - **Always-on Gateway** (run on a VPS, interact from anywhere) - **Nodes** for local browser/screen/camera/exec -Showcase: https://openclaw.ai/showcase +Showcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) ## Skills and automation @@ -1046,7 +1050,7 @@ Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-v ### How do I install skills on Linux Use **ClawHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn't available on Linux. -Browse skills at https://clawhub.com. +Browse skills at [https://clawhub.com](https://clawhub.com). Install the ClawHub CLI (pick one package manager): @@ -1069,7 +1073,7 @@ Yes. Use the Gateway scheduler: Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat), [Heartbeat](/gateway/heartbeat). -**Can I run Apple macOS only skills from Linux** +### Can I run Apple macOS-only skills from Linux? Not directly. macOS skills are gated by `metadata.openclaw.os` plus required binaries, and skills only appear in the system prompt when they are eligible on the **Gateway host**. On Linux, `darwin`-only skills (like `apple-notes`, `apple-reminders`, `things-mac`) will not load unless you override the gating. @@ -1085,13 +1089,16 @@ Run the Gateway on Linux, pair a macOS node (menubar app), and set **Node Run Co Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wrappers that run on a Mac. Then override the skill to allow Linux so it stays eligible. 1. Create an SSH wrapper for the binary (example: `memo` for Apple Notes): + ```bash #!/usr/bin/env bash set -euo pipefail exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` + 2. Put the wrapper on `PATH` on the Linux host (for example `~/bin/memo`). 3. Override the skill metadata (workspace or `~/.openclaw/skills`) to allow Linux: + ```markdown --- name: apple-notes @@ -1099,6 +1106,7 @@ Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wra metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` + 4. Start a new session so the skills snapshot refreshes. ### Do you have a Notion or HeyGen integration @@ -1449,7 +1457,7 @@ Headless uses the **same Chromium engine** and works for most automation (forms, Set `browser.executablePath` to your Brave binary (or any Chromium-based browser) and restart the Gateway. See the full config examples in [Browser](/tools/browser#use-brave-or-another-chromium-based-browser). -## Remote gateways + nodes +## Remote gateways and nodes ### How do commands propagate between Telegram the gateway and nodes @@ -1473,6 +1481,7 @@ Typical setup: 4. Open the macOS app locally and connect in **Remote over SSH** mode (or direct tailnet) so it can register as a node. 5. Approve the node on the Gateway: + ```bash openclaw nodes pending openclaw nodes approve @@ -1610,10 +1619,12 @@ This sets your workspace and restricts who can trigger the bot. Minimal steps: 1. **Install + login on the VPS** + ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` + 2. **Install + login on your Mac** - Use the Tailscale app and sign in to the same tailnet. 3. **Enable MagicDNS (recommended)** @@ -1640,6 +1651,7 @@ Recommended setup: 2. **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname). The app will tunnel the Gateway port and connect as a node. 3. **Approve the node** on the gateway: + ```bash openclaw nodes pending openclaw nodes approve @@ -1702,9 +1714,11 @@ If the Gateway runs as a service (launchd/systemd), it won't inherit your shell environment. Fix by doing one of these: 1. Put the token in `~/.openclaw/.env`: + ``` COPILOT_GITHUB_TOKEN=... ``` + 2. Or enable shell import (`env.shellEnv.enabled: true`). 3. Or add it to your config `env` block (applies only if missing). @@ -1717,7 +1731,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). -## Sessions & multiple chats +## Sessions and multiple chats ### How do I start a fresh conversation @@ -1801,6 +1815,7 @@ Use one of these: or `/compact ` to guide the summary. - **Reset** (fresh session ID for the same chat key): + ``` /new /reset @@ -2071,9 +2086,11 @@ Fix checklist: 3. Use the exact model id (case-sensitive): `minimax/MiniMax-M2.1` or `minimax/MiniMax-M2.1-lightning`. 4. Run: + ```bash openclaw models list ``` + and pick from the list (or `/model list` in chat). See [MiniMax](/providers/minimax) and [Models](/concepts/models). @@ -2238,9 +2255,11 @@ can't find it in its auth store. - **If you want to use an API key instead** - Put `ANTHROPIC_API_KEY` in `~/.openclaw/.env` on the **gateway host**. - Clear any pinned order that forces a missing profile: + ```bash openclaw models auth order clear --provider anthropic ``` + - **Confirm you're running commands on the gateway host** - In remote mode, auth profiles live on the gateway machine, not your laptop. @@ -2624,7 +2643,7 @@ you want a one-off, foreground run. Start the Gateway with `--verbose` to get more console detail. Then inspect the log file for channel auth, model routing, and RPC errors. -## Media & attachments +## Media and attachments ### My skill generated an imagePDF but nothing was sent diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md index 03896a91618..2b201c5e9ae 100644 --- a/docs/help/troubleshooting.md +++ b/docs/help/troubleshooting.md @@ -65,7 +65,7 @@ You can also set `OPENCLAW_VERBOSE=1` instead of the flag. Some Comcast/Xfinity connections block `docs.openclaw.ai` via Xfinity Advanced Security. Disable Advanced Security or add `docs.openclaw.ai` to the allowlist, then retry. -- Xfinity Advanced Security help: https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security +- Xfinity Advanced Security help: [https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security](https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security) - Quick sanity checks: try a mobile hotspot or VPN to confirm it’s ISP-level filtering ### Service says running, but RPC probe fails diff --git a/docs/hooks.md b/docs/hooks.md index 4aa6e6e3a8b..dfcd61ca10f 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -444,7 +444,7 @@ openclaw hooks enable session-memory openclaw hooks disable command-logger ``` -## Bundled Hooks +## Bundled hook reference ### session-memory @@ -787,6 +787,7 @@ Session reset ``` 3. List all discovered hooks: + ```bash openclaw hooks list ``` @@ -818,6 +819,7 @@ Look for missing: 2. Restart your gateway process so hooks reload. 3. Check gateway logs for errors: + ```bash ./scripts/clawlog.sh | grep hook ``` @@ -892,6 +894,7 @@ node -e "import('./path/to/handler.ts').then(console.log)" ``` 4. Verify and restart your gateway process: + ```bash openclaw hooks list # Should show: 🎯 my-hook ✓ diff --git a/docs/index.md b/docs/index.md index 651f98440ce..60c59bb7fa4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -120,7 +120,7 @@ Need the full install and dev setup? See [Quick start](/start/quickstart). Open the browser Control UI after the Gateway starts. -- Local default: http://127.0.0.1:18789/ +- Local default: [http://127.0.0.1:18789/](http://127.0.0.1:18789/) - Remote access: [Web surfaces](/web) and [Tailscale](/gateway/tailscale)

diff --git a/docs/install/gcp.md b/docs/install/gcp.md index 172a32ca8f6..6026fd87d55 100644 --- a/docs/install/gcp.md +++ b/docs/install/gcp.md @@ -69,7 +69,7 @@ For the generic Docker flow, see [Docker](/install/docker). **Option A: gcloud CLI** (recommended for automation) -Install from https://cloud.google.com/sdk/docs/install +Install from [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install) Initialize and authenticate: @@ -80,7 +80,7 @@ gcloud auth login **Option B: Cloud Console** -All steps can be done via the web UI at https://console.cloud.google.com +All steps can be done via the web UI at [https://console.cloud.google.com](https://console.cloud.google.com) --- @@ -93,7 +93,7 @@ gcloud projects create my-openclaw-project --name="OpenClaw Gateway" gcloud config set project my-openclaw-project ``` -Enable billing at https://console.cloud.google.com/billing (required for Compute Engine). +Enable billing at [https://console.cloud.google.com/billing](https://console.cloud.google.com/billing) (required for Compute Engine). Enable the Compute Engine API: @@ -484,6 +484,7 @@ For automation or CI/CD pipelines, create a dedicated service account with minim ``` 2. Grant Compute Instance Admin role (or narrower custom role): + ```bash gcloud projects add-iam-policy-binding my-openclaw-project \ --member="serviceAccount:openclaw-deploy@my-openclaw-project.iam.gserviceaccount.com" \ @@ -492,7 +493,7 @@ For automation or CI/CD pipelines, create a dedicated service account with minim Avoid using the Owner role for automation. Use the principle of least privilege. -See https://cloud.google.com/iam/docs/understanding-roles for IAM role details. +See [https://cloud.google.com/iam/docs/understanding-roles](https://cloud.google.com/iam/docs/understanding-roles) for IAM role details. --- diff --git a/docs/install/installer.md b/docs/install/installer.md index 1fb7061bdf0..92c24e6a46b 100644 --- a/docs/install/installer.md +++ b/docs/install/installer.md @@ -1,5 +1,5 @@ --- -summary: "How the installer scripts work (install.sh + install-cli.sh), flags, and automation" +summary: "How the installer scripts work (install.sh, install-cli.sh, install.ps1), flags, and automation" read_when: - You want to understand `openclaw.ai/install.sh` - You want to automate installs (CI / headless) @@ -9,153 +9,377 @@ title: "Installer Internals" # Installer internals -OpenClaw ships two installer scripts (served from `openclaw.ai`): +OpenClaw ships three installer scripts, served from `openclaw.ai`. -- `https://openclaw.ai/install.sh` - "recommended" installer (global npm install by default; can also install from a GitHub checkout) -- `https://openclaw.ai/install-cli.sh` - non-root-friendly CLI installer (installs into a prefix with its own Node) -- `https://openclaw.ai/install.ps1` - Windows PowerShell installer (npm by default; optional git install) +| Script | Platform | What it does | +| ----------------------------------- | -------------------- | -------------------------------------------------------------------------------------------- | +| [`install.sh`](#install-sh) | macOS / Linux / WSL | Installs Node if needed, installs OpenClaw via npm (default) or git, and can run onboarding. | +| [`install-cli.sh`](#install-cli-sh) | macOS / Linux / WSL | Installs Node + OpenClaw into a local prefix (`~/.openclaw`). No root required. | +| [`install.ps1`](#install-ps1) | Windows (PowerShell) | Installs Node if needed, installs OpenClaw via npm (default) or git, and can run onboarding. | -To see the current flags/behavior, run: +## Quick commands -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help -``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash + ``` -Windows (PowerShell) help: + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help + ``` -```powershell -& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -? -``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash + ``` -If the installer completes but `openclaw` is not found in a new terminal, it's usually a Node/npm PATH issue. See: [Node.js](/install/node#troubleshooting). + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help + ``` -## Flags and environment variables + + + ```powershell + iwr -useb https://openclaw.ai/install.ps1 | iex + ``` -### CLI flags (install.sh) + ```powershell + & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun + ``` -| Flag | Description | -| --------------------------- | ------------------------------------------------ | -| `--install-method npm\|git` | Choose install method (default: `npm`) | -| `--git-dir ` | Source checkout location (default: `~/openclaw`) | -| `--no-git-update` | Skip `git pull` when using an existing checkout | -| `--no-prompt` | Disable prompts (required in CI/automation) | -| `--dry-run` | Print what would happen; make no changes | -| `--no-onboard` | Skip onboarding after install | + + -### PowerShell flags (install.ps1) + +If install succeeds but `openclaw` is not found in a new terminal, see [Node.js troubleshooting](/install/node#troubleshooting). + -| Flag | Description | -| ------------------------- | ----------------------------------------------- | -| `-InstallMethod npm\|git` | Choose install method (default: `npm`) | -| `-GitDir ` | Source checkout location | -| `-NoOnboard` | Skip onboarding after install | -| `-NoGitUpdate` | Skip `git pull` when using an existing checkout | -| `-DryRun` | Print what would happen; make no changes | -| `-Tag ` | npm dist-tag to install (default: `latest`) | +--- -### Environment variables +## install.sh -Equivalent env vars (useful for CI/automation): + +Recommended for most interactive installs on macOS/Linux/WSL. + -| Variable | Description | -| ---------------------------------- | ------------------------------------------------------------ | -| `OPENCLAW_INSTALL_METHOD=git\|npm` | Install method | -| `OPENCLAW_GIT_DIR=` | Source checkout location | -| `OPENCLAW_GIT_UPDATE=0\|1` | Toggle git pull | -| `OPENCLAW_NO_PROMPT=1` | Disable prompts | -| `OPENCLAW_DRY_RUN=1` | Dry run mode | -| `OPENCLAW_NO_ONBOARD=1` | Skip onboarding | -| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | Avoid `sharp` building against system libvips (default: `1`) | +### Flow -## install.sh (recommended) + + + Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing. + + + Checks Node version and installs Node 22 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum). + + + Installs Git if missing. + + + - `npm` method (default): global npm install + - `git` method: clone/update repo, install deps with pnpm, build, then install wrapper at `~/.local/bin/openclaw` + + + - Runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort) + - Attempts onboarding when appropriate (TTY available, onboarding not disabled, and bootstrap/config checks pass) + - Defaults `SHARP_IGNORE_GLOBAL_LIBVIPS=1` + + -What it does (high level): +### Source checkout detection -- Detect OS (macOS / Linux / WSL). -- Ensure Node.js **22+** (macOS via Homebrew; Linux via NodeSource). -- Choose install method: - - `npm` (default): `npm install -g openclaw@latest` - - `git`: clone/build a source checkout and install a wrapper script -- On Linux: avoid global npm permission errors by switching npm's prefix to `~/.npm-global` when needed. -- If upgrading an existing install: runs `openclaw doctor --non-interactive` (best effort). -- For git installs: runs `openclaw doctor --non-interactive` after install/update (best effort). -- Mitigates `sharp` native install gotchas by defaulting `SHARP_IGNORE_GLOBAL_LIBVIPS=1` (avoids building against system libvips). +If run inside an OpenClaw checkout (`package.json` + `pnpm-workspace.yaml`), the script offers: -If you _want_ `sharp` to link against a globally-installed libvips (or you're debugging), set: +- use checkout (`git`), or +- use global install (`npm`) -```bash -SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash -``` +If no TTY is available and no install method is set, it defaults to `npm` and warns. -### Discoverability / "git install" prompt +The script exits with code `2` for invalid method selection or invalid `--install-method` values. -If you run the installer while **already inside a OpenClaw source checkout** (detected via `package.json` + `pnpm-workspace.yaml`), it prompts: +### Examples -- update and use this checkout (`git`) -- or migrate to the global npm install (`npm`) + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash + ``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard + ``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git + ``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run + ``` + + -In non-interactive contexts (no TTY / `--no-prompt`), you must pass `--install-method git|npm` (or set `OPENCLAW_INSTALL_METHOD`), otherwise the script exits with code `2`. + + -### Why Git is needed +| Flag | Description | +| ------------------------------- | ---------------------------------------------------------- | +| `--install-method npm\|git` | Choose install method (default: `npm`). Alias: `--method` | +| `--npm` | Shortcut for npm method | +| `--git` | Shortcut for git method. Alias: `--github` | +| `--version ` | npm version or dist-tag (default: `latest`) | +| `--beta` | Use beta dist-tag if available, else fallback to `latest` | +| `--git-dir ` | Checkout directory (default: `~/openclaw`). Alias: `--dir` | +| `--no-git-update` | Skip `git pull` for existing checkout | +| `--no-prompt` | Disable prompts | +| `--no-onboard` | Skip onboarding | +| `--onboard` | Enable onboarding | +| `--dry-run` | Print actions without applying changes | +| `--verbose` | Enable debug output (`set -x`, npm notice-level logs) | +| `--help` | Show usage (`-h`) | -Git is required for the `--install-method git` path (clone / pull). + -For `npm` installs, Git is _usually_ not required, but some environments still end up needing it (e.g. when a package or dependency is fetched via a git URL). The installer currently ensures Git is present to avoid `spawn git ENOENT` surprises on fresh distros. + -### Why npm hits `EACCES` on fresh Linux +| Variable | Description | +| ------------------------------------------- | --------------------------------------------- | +| `OPENCLAW_INSTALL_METHOD=git\|npm` | Install method | +| `OPENCLAW_VERSION=latest\|next\|` | npm version or dist-tag | +| `OPENCLAW_BETA=0\|1` | Use beta if available | +| `OPENCLAW_GIT_DIR=` | Checkout directory | +| `OPENCLAW_GIT_UPDATE=0\|1` | Toggle git updates | +| `OPENCLAW_NO_PROMPT=1` | Disable prompts | +| `OPENCLAW_NO_ONBOARD=1` | Skip onboarding | +| `OPENCLAW_DRY_RUN=1` | Dry run mode | +| `OPENCLAW_VERBOSE=1` | Debug mode | +| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level | +| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | Control sharp/libvips behavior (default: `1`) | -On some Linux setups (especially after installing Node via the system package manager or NodeSource), npm's global prefix points at a root-owned location. Then `npm install -g ...` fails with `EACCES` / `mkdir` permission errors. + + -`install.sh` mitigates this by switching the prefix to: +--- -- `~/.npm-global` (and adding it to `PATH` in `~/.bashrc` / `~/.zshrc` when present) +## install-cli.sh -## install-cli.sh (non-root CLI installer) + +Designed for environments where you want everything under a local prefix (default `~/.openclaw`) and no system Node dependency. + -This script installs `openclaw` into a prefix (default: `~/.openclaw`) and also installs a dedicated Node runtime under that prefix, so it can work on machines where you don't want to touch the system Node/npm. +### Flow -Help: + + + Downloads Node tarball (default `22.22.0`) to `/tools/node-v` and verifies SHA-256. + + + If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on macOS. + + + Installs with npm using `--prefix `, then writes wrapper to `/bin/openclaw`. + + -```bash -curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help -``` +### Examples -## install.ps1 (Windows PowerShell) + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash + ``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest + ``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw + ``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard + ``` + + -What it does (high level): + + -- Ensure Node.js **22+** (winget/Chocolatey/Scoop or manual). -- Choose install method: - - `npm` (default): `npm install -g openclaw@latest` - - `git`: clone/build a source checkout and install a wrapper script -- Runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort). +| Flag | Description | +| ---------------------- | ------------------------------------------------------------------------------- | +| `--prefix ` | Install prefix (default: `~/.openclaw`) | +| `--version ` | OpenClaw version or dist-tag (default: `latest`) | +| `--node-version ` | Node version (default: `22.22.0`) | +| `--json` | Emit NDJSON events | +| `--onboard` | Run `openclaw onboard` after install | +| `--no-onboard` | Skip onboarding (default) | +| `--set-npm-prefix` | On Linux, force npm prefix to `~/.npm-global` if current prefix is not writable | +| `--help` | Show usage (`-h`) | -Examples: + -```powershell -iwr -useb https://openclaw.ai/install.ps1 | iex -``` + -```powershell -iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -``` +| Variable | Description | +| ------------------------------------------- | --------------------------------------------------------------------------------- | +| `OPENCLAW_PREFIX=` | Install prefix | +| `OPENCLAW_VERSION=` | OpenClaw version or dist-tag | +| `OPENCLAW_NODE_VERSION=` | Node version | +| `OPENCLAW_NO_ONBOARD=1` | Skip onboarding | +| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level | +| `OPENCLAW_GIT_DIR=` | Legacy cleanup lookup path (used when removing old `Peekaboo` submodule checkout) | +| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | Control sharp/libvips behavior (default: `1`) | -```powershell -iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw" -``` + + -Environment variables: +--- -- `OPENCLAW_INSTALL_METHOD=git|npm` -- `OPENCLAW_GIT_DIR=...` +## install.ps1 -Git requirement: +### Flow -If you choose `-InstallMethod git` and Git is missing, the installer will print the -Git for Windows link (`https://git-scm.com/download/win`) and exit. + + + Requires PowerShell 5+. + + + If missing, attempts install via winget, then Chocolatey, then Scoop. + + + - `npm` method (default): global npm install using selected `-Tag` + - `git` method: clone/update repo, install/build with pnpm, and install wrapper at `%USERPROFILE%\.local\bin\openclaw.cmd` + + + Adds needed bin directory to user PATH when possible, then runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort). + + -Common Windows issues: +### Examples -- **npm error spawn git / ENOENT**: install Git for Windows and reopen PowerShell, then rerun the installer. -- **"openclaw" is not recognized**: your npm global bin folder is not on PATH. Most systems use - `%AppData%\\npm`. You can also run `npm config get prefix` and add `\\bin` to PATH, then reopen PowerShell. + + + ```powershell + iwr -useb https://openclaw.ai/install.ps1 | iex + ``` + + + ```powershell + & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git + ``` + + + ```powershell + & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw" + ``` + + + ```powershell + & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun + ``` + + + + + + +| Flag | Description | +| ------------------------- | ------------------------------------------------------ | +| `-InstallMethod npm\|git` | Install method (default: `npm`) | +| `-Tag ` | npm dist-tag (default: `latest`) | +| `-GitDir ` | Checkout directory (default: `%USERPROFILE%\openclaw`) | +| `-NoOnboard` | Skip onboarding | +| `-NoGitUpdate` | Skip `git pull` | +| `-DryRun` | Print actions only | + + + + + +| Variable | Description | +| ---------------------------------- | ------------------ | +| `OPENCLAW_INSTALL_METHOD=git\|npm` | Install method | +| `OPENCLAW_GIT_DIR=` | Checkout directory | +| `OPENCLAW_NO_ONBOARD=1` | Skip onboarding | +| `OPENCLAW_GIT_UPDATE=0` | Disable git pull | +| `OPENCLAW_DRY_RUN=1` | Dry run mode | + + + + + +If `-InstallMethod git` is used and Git is missing, the script exits and prints the Git for Windows link. + + +--- + +## CI and automation + +Use non-interactive flags/env vars for predictable runs. + + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard + ``` + + + ```bash + OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \ + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash + ``` + + + ```bash + curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw + ``` + + + ```powershell + & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard + ``` + + + +--- + +## Troubleshooting + + + + Git is required for `git` install method. For `npm` installs, Git is still checked/installed to avoid `spawn git ENOENT` failures when dependencies use git URLs. + + + + Some Linux setups point npm global prefix to root-owned paths. `install.sh` can switch prefix to `~/.npm-global` and append PATH exports to shell rc files (when those files exist). + + + + The scripts default `SHARP_IGNORE_GLOBAL_LIBVIPS=1` to avoid sharp building against system libvips. To override: + + ```bash + SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash + ``` + + + + + Install Git for Windows, reopen PowerShell, rerun installer. + + + + Run `npm config get prefix`, append `\bin`, add that directory to user PATH, then reopen PowerShell. + + + + Usually a PATH issue. See [Node.js troubleshooting](/install/node#troubleshooting). + + diff --git a/docs/install/northflank.mdx b/docs/install/northflank.mdx index 8c1ff33ec40..d3157d72e74 100644 --- a/docs/install/northflank.mdx +++ b/docs/install/northflank.mdx @@ -45,7 +45,7 @@ If Telegram DMs are set to pairing, the setup wizard can approve the pairing cod ### Discord bot token -1. Go to https://discord.com/developers/applications +1. Go to [https://discord.com/developers/applications](https://discord.com/developers/applications) 2. **New Application** → choose a name 3. **Bot** → **Add Bot** 4. **Enable MESSAGE CONTENT INTENT** under Bot → Privileged Gateway Intents (required or the bot will crash on startup) diff --git a/docs/install/railway.mdx b/docs/install/railway.mdx index b27d94203ad..73f23fbe48a 100644 --- a/docs/install/railway.mdx +++ b/docs/install/railway.mdx @@ -83,7 +83,7 @@ If Telegram DMs are set to pairing, the setup wizard can approve the pairing cod ### Discord bot token -1. Go to https://discord.com/developers/applications +1. Go to [https://discord.com/developers/applications](https://discord.com/developers/applications) 2. **New Application** → choose a name 3. **Bot** → **Add Bot** 4. **Enable MESSAGE CONTENT INTENT** under Bot → Privileged Gateway Intents (required or the bot will crash on startup) diff --git a/docs/install/render.mdx b/docs/install/render.mdx index a682d61c99e..ae945687025 100644 --- a/docs/install/render.mdx +++ b/docs/install/render.mdx @@ -11,13 +11,7 @@ Deploy OpenClaw on Render using Infrastructure as Code. The included `render.yam ## Deploy with a Render Blueprint - - Deploy to Render - +[Deploy to Render](https://render.com/deploy?repo=https://github.com/openclaw/openclaw) Clicking this link will: diff --git a/docs/install/updating.md b/docs/install/updating.md index ae4b3d1ebef..e463a5001fb 100644 --- a/docs/install/updating.md +++ b/docs/install/updating.md @@ -24,10 +24,13 @@ Notes: - Add `--no-onboard` if you don’t want the onboarding wizard to run again. - For **source installs**, use: + ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard ``` + The installer will `git pull --rebase` **only** if the repo is clean. + - For **global installs**, the script uses `npm install -g openclaw@latest` under the hood. - Legacy note: `clawdbot` remains available as a compatibility shim. @@ -225,4 +228,4 @@ git pull - Run `openclaw doctor` again and read the output carefully (it often tells you the fix). - Check: [Troubleshooting](/gateway/troubleshooting) -- Ask in Discord: https://discord.gg/clawd +- Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd) diff --git a/docs/multi-agent-sandbox-tools.md b/docs/multi-agent-sandbox-tools.md index a02af8d5383..e7de9caf8d3 100644 --- a/docs/multi-agent-sandbox-tools.md +++ b/docs/multi-agent-sandbox-tools.md @@ -362,6 +362,7 @@ After configuring multi-agent sandbox and tools: - Verify the agent cannot use denied tools 4. **Monitor logs:** + ```exec tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools" ``` diff --git a/docs/nodes/camera.md b/docs/nodes/camera.md index 8ee0dd99a88..3d5416a5448 100644 --- a/docs/nodes/camera.md +++ b/docs/nodes/camera.md @@ -81,7 +81,7 @@ Notes: ## Android node -### User setting (default on) +### Android user setting (default on) - Android Settings sheet → **Camera** → **Allow Camera** (`camera.enabled`) - Default: **on** (missing key is treated as enabled). @@ -96,7 +96,7 @@ Notes: If permissions are missing, the app will prompt when possible; if denied, `camera.*` requests fail with a `*_PERMISSION_REQUIRED` error. -### Foreground requirement +### Android foreground requirement Like `canvas.*`, the Android node only allows `camera.*` commands in the **foreground**. Background invocations return `NODE_BACKGROUND_UNAVAILABLE`. diff --git a/docs/perplexity.md b/docs/perplexity.md index 46c4f12b9aa..178a7c36015 100644 --- a/docs/perplexity.md +++ b/docs/perplexity.md @@ -15,12 +15,12 @@ through Perplexity’s direct API or via OpenRouter. ### Perplexity (direct) -- Base URL: https://api.perplexity.ai +- Base URL: [https://api.perplexity.ai](https://api.perplexity.ai) - Environment variable: `PERPLEXITY_API_KEY` ### OpenRouter (alternative) -- Base URL: https://openrouter.ai/api/v1 +- Base URL: [https://openrouter.ai/api/v1](https://openrouter.ai/api/v1) - Environment variable: `OPENROUTER_API_KEY` - Supports prepaid/crypto credits. diff --git a/docs/pi-dev.md b/docs/pi-dev.md index e850b8dc7af..2eeebdcc289 100644 --- a/docs/pi-dev.md +++ b/docs/pi-dev.md @@ -66,5 +66,5 @@ If you only want to reset sessions, delete `agents//sessions/` and `age ## References -- https://docs.openclaw.ai/testing -- https://docs.openclaw.ai/start/getting-started +- [https://docs.openclaw.ai/testing](https://docs.openclaw.ai/testing) +- [https://docs.openclaw.ai/start/getting-started](https://docs.openclaw.ai/start/getting-started) diff --git a/docs/platforms/android.md b/docs/platforms/android.md index 6e395994b90..b786e1782e0 100644 --- a/docs/platforms/android.md +++ b/docs/platforms/android.md @@ -98,10 +98,13 @@ Pairing details: [Gateway pairing](/gateway/pairing). ### 5) Verify the node is connected - Via nodes status: + ```bash openclaw nodes status ``` + - Via Gateway: + ```bash openclaw gateway call node.list --params "{}" ``` diff --git a/docs/platforms/mac/dev-setup.md b/docs/platforms/mac/dev-setup.md index 39d3125d81f..8aff5134886 100644 --- a/docs/platforms/mac/dev-setup.md +++ b/docs/platforms/mac/dev-setup.md @@ -13,8 +13,8 @@ This guide covers the necessary steps to build and run the OpenClaw macOS applic Before building the app, ensure you have the following installed: -1. **Xcode 26.2+**: Required for Swift development. -2. **Node.js 22+ & pnpm**: Required for the gateway, CLI, and packaging scripts. +1. **Xcode 26.2+**: Required for Swift development. +2. **Node.js 22+ & pnpm**: Required for the gateway, CLI, and packaging scripts. ## 1. Install Dependencies @@ -35,7 +35,7 @@ To build the macOS app and package it into `dist/OpenClaw.app`, run: If you don't have an Apple Developer ID certificate, the script will automatically use **ad-hoc signing** (`-`). For dev run modes, signing flags, and Team ID troubleshooting, see the macOS app README: -https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md +[https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md](https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md) > **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#troubleshooting) section. @@ -45,9 +45,9 @@ The macOS app expects a global `openclaw` CLI install to manage background tasks **To install it (recommended):** -1. Open the OpenClaw app. -2. Go to the **General** settings tab. -3. Click **"Install CLI"**. +1. Open the OpenClaw app. +2. Go to the **General** settings tab. +3. Click **"Install CLI"**. Alternatively, install it manually: @@ -82,9 +82,11 @@ If the app crashes when you try to allow **Speech Recognition** or **Microphone* **Fix:** 1. Reset the TCC permissions: + ```bash tccutil reset All bot.molt.mac.debug ``` + 2. If that fails, change the `BUNDLE_ID` temporarily in [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) to force a "clean slate" from macOS. ### Gateway "Starting..." indefinitely diff --git a/docs/platforms/mac/voice-overlay.md b/docs/platforms/mac/voice-overlay.md index 10df85007ab..9c42601b186 100644 --- a/docs/platforms/mac/voice-overlay.md +++ b/docs/platforms/mac/voice-overlay.md @@ -9,18 +9,18 @@ title: "Voice Overlay" Audience: macOS app contributors. Goal: keep the voice overlay predictable when wake-word and push-to-talk overlap. -### Current intent +## Current intent - If the overlay is already visible from wake-word and the user presses the hotkey, the hotkey session _adopts_ the existing text instead of resetting it. The overlay stays up while the hotkey is held. When the user releases: send if there is trimmed text, otherwise dismiss. - Wake-word alone still auto-sends on silence; push-to-talk sends immediately on release. -### Implemented (Dec 9, 2025) +## Implemented (Dec 9, 2025) - Overlay sessions now carry a token per capture (wake-word or push-to-talk). Partial/final/send/dismiss/level updates are dropped when the token doesn’t match, avoiding stale callbacks. - Push-to-talk adopts any visible overlay text as a prefix (so pressing the hotkey while the wake overlay is up keeps the text and appends new speech). It waits up to 1.5s for a final transcript before falling back to the current text. - Chime/overlay logging is emitted at `info` in categories `voicewake.overlay`, `voicewake.ptt`, and `voicewake.chime` (session start, partial, final, send, dismiss, chime reason). -### Next steps +## Next steps 1. **VoiceSessionCoordinator (actor)** - Owns exactly one `VoiceSession` at a time. @@ -40,7 +40,7 @@ Audience: macOS app contributors. Goal: keep the voice overlay predictable when - Coordinator emits `.info` logs in subsystem `bot.molt`, categories `voicewake.overlay` and `voicewake.chime`. - Key events: `session_started`, `adopted_by_push_to_talk`, `partial`, `finalized`, `send`, `dismiss`, `cancel`, `cooldown`. -### Debugging checklist +## Debugging checklist - Stream logs while reproducing a sticky overlay: @@ -51,7 +51,7 @@ Audience: macOS app contributors. Goal: keep the voice overlay predictable when - Verify only one active session token; stale callbacks should be dropped by the coordinator. - Ensure push-to-talk release always calls `endCapture` with the active token; if text is empty, expect `dismiss` without chime or send. -### Migration steps (suggested) +## Migration steps (suggested) 1. Add `VoiceSessionCoordinator`, `VoiceSession`, and `VoiceSessionPublisher`. 2. Refactor `VoiceWakeRuntime` to create/update/end sessions instead of touching `VoiceWakeOverlayController` directly. diff --git a/docs/platforms/mac/webchat.md b/docs/platforms/mac/webchat.md index 5f654e1744a..ea6791ff50e 100644 --- a/docs/platforms/mac/webchat.md +++ b/docs/platforms/mac/webchat.md @@ -19,9 +19,11 @@ agent (with a session switcher for other sessions). - Manual: Lobster menu → “Open Chat”. - Auto‑open for testing: + ```bash dist/OpenClaw.app/Contents/MacOS/OpenClaw --webchat ``` + - Logs: `./scripts/clawlog.sh` (subsystem `bot.molt`, category `WebChatSwiftUI`). ## How it’s wired diff --git a/docs/platforms/windows.md b/docs/platforms/windows.md index e89cae95ee5..d1513148689 100644 --- a/docs/platforms/windows.md +++ b/docs/platforms/windows.md @@ -20,7 +20,7 @@ Native Windows companion apps are planned. - [Getting Started](/start/getting-started) (use inside WSL) - [Install & updates](/install/updating) -- Official WSL2 guide (Microsoft): https://learn.microsoft.com/windows/wsl/install +- Official WSL2 guide (Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install) ## Gateway diff --git a/docs/prose.md b/docs/prose.md index 4b825c467c5..7b4b8c002be 100644 --- a/docs/prose.md +++ b/docs/prose.md @@ -11,7 +11,7 @@ title: "OpenProse" OpenProse is a portable, markdown-first workflow format for orchestrating AI sessions. In OpenClaw it ships as a plugin that installs an OpenProse skill pack plus a `/prose` slash command. Programs live in `.prose` files and can spawn multiple sub-agents with explicit control flow. -Official site: https://www.prose.md +Official site: [https://www.prose.md](https://www.prose.md) ## What it can do diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md index 5f2374fe143..ff82280bef6 100644 --- a/docs/providers/anthropic.md +++ b/docs/providers/anthropic.md @@ -103,14 +103,14 @@ If you generated the token on a different machine, paste it: openclaw models auth paste-token --provider anthropic ``` -### CLI setup +### CLI setup (setup-token) ```bash # Paste a setup-token during onboarding openclaw onboard --auth-choice setup-token ``` -### Config snippet +### Config snippet (setup-token) ```json5 { diff --git a/docs/providers/claude-max-api-proxy.md b/docs/providers/claude-max-api-proxy.md index 9970233121a..11b83071081 100644 --- a/docs/providers/claude-max-api-proxy.md +++ b/docs/providers/claude-max-api-proxy.md @@ -131,9 +131,9 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist ## Links -- **npm:** https://www.npmjs.com/package/claude-max-api-proxy -- **GitHub:** https://github.com/atalovesyou/claude-max-api-proxy -- **Issues:** https://github.com/atalovesyou/claude-max-api-proxy/issues +- **npm:** [https://www.npmjs.com/package/claude-max-api-proxy](https://www.npmjs.com/package/claude-max-api-proxy) +- **GitHub:** [https://github.com/atalovesyou/claude-max-api-proxy](https://github.com/atalovesyou/claude-max-api-proxy) +- **Issues:** [https://github.com/atalovesyou/claude-max-api-proxy/issues](https://github.com/atalovesyou/claude-max-api-proxy/issues) ## Notes diff --git a/docs/providers/deepgram.md b/docs/providers/deepgram.md index cf32467e50a..b7a21fa6f13 100644 --- a/docs/providers/deepgram.md +++ b/docs/providers/deepgram.md @@ -15,8 +15,8 @@ When enabled, OpenClaw uploads the audio file to Deepgram and injects the transc into the reply pipeline (`{{Transcript}}` + `[Audio]` block). This is **not streaming**; it uses the pre-recorded transcription endpoint. -Website: https://deepgram.com -Docs: https://developers.deepgram.com +Website: [https://deepgram.com](https://deepgram.com) +Docs: [https://developers.deepgram.com](https://developers.deepgram.com) ## Quick start diff --git a/docs/providers/minimax.md b/docs/providers/minimax.md index f19478a49f2..294388fbcc7 100644 --- a/docs/providers/minimax.md +++ b/docs/providers/minimax.md @@ -179,7 +179,7 @@ Use the interactive config wizard to set MiniMax without editing JSON: - Model refs are `minimax/`. - Coding Plan usage API: `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` (requires a coding plan key). - Update pricing values in `models.json` if you need exact cost tracking. -- Referral link for MiniMax Coding Plan (10% off): https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link +- Referral link for MiniMax Coding Plan (10% off): [https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link) - See [/concepts/model-providers](/concepts/model-providers) for provider rules. - Use `openclaw models list` and `openclaw models set minimax/MiniMax-M2.1` to switch. diff --git a/docs/providers/moonshot.md b/docs/providers/moonshot.md index 6e6ec52959b..0a46c906748 100644 --- a/docs/providers/moonshot.md +++ b/docs/providers/moonshot.md @@ -15,14 +15,14 @@ Kimi Coding with `kimi-coding/k2p5`. Current Kimi K2 model IDs: -{/_ moonshot-kimi-k2-ids:start _/ && null} +{/_moonshot-kimi-k2-ids:start_/ && null} - `kimi-k2.5` - `kimi-k2-0905-preview` - `kimi-k2-turbo-preview` - `kimi-k2-thinking` - `kimi-k2-thinking-turbo` - {/_ moonshot-kimi-k2-ids:end _/ && null} + {/_moonshot-kimi-k2-ids:end_/ && null} ```bash openclaw onboard --auth-choice moonshot-api-key diff --git a/docs/providers/ollama.md b/docs/providers/ollama.md index 9d2f177bf59..463923fb7c2 100644 --- a/docs/providers/ollama.md +++ b/docs/providers/ollama.md @@ -12,7 +12,7 @@ Ollama is a local LLM runtime that makes it easy to run open-source models on yo ## Quick start -1. Install Ollama: https://ollama.ai +1. Install Ollama: [https://ollama.ai](https://ollama.ai) 2. Pull a model: diff --git a/docs/providers/openai.md b/docs/providers/openai.md index 509fb56405d..54e3d29e454 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -38,7 +38,7 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY" **Best for:** using ChatGPT/Codex subscription access instead of an API key. Codex cloud requires ChatGPT sign-in, while the Codex CLI supports ChatGPT or API key sign-in. -### CLI setup +### CLI setup (Codex OAuth) ```bash # Run Codex OAuth in the wizard @@ -48,7 +48,7 @@ openclaw onboard --auth-choice openai-codex openclaw models auth login --provider openai-codex ``` -### Config snippet +### Config snippet (Codex subscription) ```json5 { diff --git a/docs/reference/credits.md b/docs/reference/credits.md index e9ba9bca398..67e85ca72e7 100644 --- a/docs/reference/credits.md +++ b/docs/reference/credits.md @@ -17,8 +17,8 @@ OpenClaw = CLAW + TARDIS, because every space lobster needs a time and space mac ## Core contributors -- **Maxim Vovshin** (@Hyaxia, 36747317+Hyaxia@users.noreply.github.com) - Blogwatcher skill -- **Nacho Iacovino** (@nachoiacovino, nacho.iacovino@gmail.com) - Location parsing (Telegram and WhatsApp) +- **Maxim Vovshin** (@Hyaxia, [36747317+Hyaxia@users.noreply.github.com](mailto:36747317+Hyaxia@users.noreply.github.com)) - Blogwatcher skill +- **Nacho Iacovino** (@nachoiacovino, [nacho.iacovino@gmail.com](mailto:nacho.iacovino@gmail.com)) - Location parsing (Telegram and WhatsApp) ## License diff --git a/docs/reference/templates/IDENTITY.md b/docs/reference/templates/IDENTITY.md index 9fa2fe5b079..9ec2dd62c7f 100644 --- a/docs/reference/templates/IDENTITY.md +++ b/docs/reference/templates/IDENTITY.md @@ -3,25 +3,27 @@ summary: "Agent identity record" read_when: - Bootstrapping a workspace manually --- + # IDENTITY.md - Who Am I? -*Fill this in during your first conversation. Make it yours.* +_Fill this in during your first conversation. Make it yours._ - **Name:** - *(pick something you like)* + _(pick something you like)_ - **Creature:** - *(AI? robot? familiar? ghost in the machine? something weirder?)* + _(AI? robot? familiar? ghost in the machine? something weirder?)_ - **Vibe:** - *(how do you come across? sharp? warm? chaotic? calm?)* + _(how do you come across? sharp? warm? chaotic? calm?)_ - **Emoji:** - *(your signature — pick one that feels right)* + _(your signature — pick one that feels right)_ - **Avatar:** - *(workspace-relative path, http(s) URL, or data URI)* + _(workspace-relative path, http(s) URL, or data URI)_ --- This isn't just metadata. It's the start of figuring out who you are. Notes: + - Save this file at the workspace root as `IDENTITY.md`. - For avatars, use a workspace-relative path like `avatars/openclaw.png`. diff --git a/docs/reference/templates/USER.md b/docs/reference/templates/USER.md index 6dc55123892..682e99ae6cc 100644 --- a/docs/reference/templates/USER.md +++ b/docs/reference/templates/USER.md @@ -3,19 +3,20 @@ summary: "User profile record" read_when: - Bootstrapping a workspace manually --- + # USER.md - About Your Human -*Learn about the person you're helping. Update this as you go.* +_Learn about the person you're helping. Update this as you go._ -- **Name:** -- **What to call them:** -- **Pronouns:** *(optional)* -- **Timezone:** -- **Notes:** +- **Name:** +- **What to call them:** +- **Pronouns:** _(optional)_ +- **Timezone:** +- **Notes:** ## Context -*(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)* +_(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)_ --- diff --git a/docs/start/pairing.md b/docs/start/pairing.md index b11373c933e..19813155f56 100644 --- a/docs/start/pairing.md +++ b/docs/start/pairing.md @@ -60,7 +60,7 @@ openclaw devices approve openclaw devices reject ``` -### Where the state lives +### Node pairing state storage Stored under `~/.openclaw/devices/`: diff --git a/docs/token-use.md b/docs/token-use.md index 7f8dcb7fbb9..16b0fe9618c 100644 --- a/docs/token-use.md +++ b/docs/token-use.md @@ -85,7 +85,7 @@ re-caching the full prompt, reducing cache write costs. For Anthropic API pricing, cache reads are significantly cheaper than input tokens, while cache writes are billed at a higher multiplier. See Anthropic’s prompt caching pricing for the latest rates and TTL multipliers: -https://docs.anthropic.com/docs/build-with-claude/prompt-caching +[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching) ### Example: keep 1h cache warm with heartbeat diff --git a/docs/tools/browser-login.md b/docs/tools/browser-login.md index dcfb5ceb48c..a3c7a4615f5 100644 --- a/docs/tools/browser-login.md +++ b/docs/tools/browser-login.md @@ -35,7 +35,7 @@ If you have multiple profiles, pass `--browser-profile ` (the default is ` ## X/Twitter: recommended flow - **Read/search/threads:** use the **bird** CLI skill (no browser, stable). - - Repo: https://github.com/steipete/bird + - Repo: [https://github.com/steipete/bird](https://github.com/steipete/bird) - **Post updates:** use the **host** browser (manual login). ## Sandboxing + host browser access diff --git a/docs/tools/lobster.md b/docs/tools/lobster.md index 62ef213575a..ed9ed1fb27e 100644 --- a/docs/tools/lobster.md +++ b/docs/tools/lobster.md @@ -338,5 +338,5 @@ OpenProse pairs well with Lobster: use `/prose` to orchestrate multi-agent prep, One public example: a “second brain” CLI + Lobster pipelines that manage three Markdown vaults (personal, partner, shared). The CLI emits JSON for stats, inbox listings, and stale scans; Lobster chains those commands into workflows like `weekly-review`, `inbox-triage`, `memory-consolidation`, and `shared-task-sync`, each with approval gates. AI handles judgment (categorization) when available and falls back to deterministic rules when not. -- Thread: https://x.com/plattenschieber/status/2014508656335770033 -- Repo: https://github.com/bloomedai/brain-cli +- Thread: [https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033) +- Repo: [https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli) diff --git a/docs/tools/skills.md b/docs/tools/skills.md index b4a142e3341..b8038ee0fa3 100644 --- a/docs/tools/skills.md +++ b/docs/tools/skills.md @@ -50,7 +50,7 @@ tool surface those skills teach. ## ClawHub (install + sync) ClawHub is the public skills registry for OpenClaw. Browse at -https://clawhub.com. Use it to discover, install, update, and back up skills. +[https://clawhub.com](https://clawhub.com). Use it to discover, install, update, and back up skills. Full guide: [ClawHub](/tools/clawhub). Common flows: @@ -295,6 +295,6 @@ See [Skills config](/tools/skills-config) for the full configuration schema. ## Looking for more skills? -Browse https://clawhub.com. +Browse [https://clawhub.com](https://clawhub.com). --- diff --git a/docs/tools/web.md b/docs/tools/web.md index 4c1ff47b616..c22bc1707eb 100644 --- a/docs/tools/web.md +++ b/docs/tools/web.md @@ -71,7 +71,7 @@ Example: switch to Perplexity Sonar (direct API): ## Getting a Brave API key -1. Create a Brave Search API account at https://brave.com/search/api/ +1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/) 2. In the dashboard, choose the **Data for Search** plan (not “Data for AI”) and generate an API key. 3. Run `openclaw configure --section web` to store the key in config (recommended), or set `BRAVE_API_KEY` in your environment. @@ -95,7 +95,7 @@ crypto/prepaid). ### Getting an OpenRouter API key -1. Create an account at https://openrouter.ai/ +1. Create an account at [https://openrouter.ai/](https://openrouter.ai/) 2. Add credits (supports crypto, prepaid, or credit card) 3. Generate an API key in your account settings @@ -207,12 +207,12 @@ await web_search({ Fetch a URL and extract readable content. -### Requirements +### web_fetch requirements - `tools.web.fetch.enabled` must not be `false` (default: enabled) - Optional Firecrawl fallback: set `tools.web.fetch.firecrawl.apiKey` or `FIRECRAWL_API_KEY`. -### Config +### web_fetch config ```json5 { @@ -241,7 +241,7 @@ Fetch a URL and extract readable content. } ``` -### Tool parameters +### web_fetch tool parameters - `url` (required, http/https only) - `extractMode` (`markdown` | `text`) diff --git a/docs/tui.md b/docs/tui.md index 2be342092ed..8398cedfe1e 100644 --- a/docs/tui.md +++ b/docs/tui.md @@ -155,7 +155,7 @@ No output after sending a message: - If you expect messages in a chat channel, enable delivery (`/deliver on` or `--deliver`). - `--history-limit `: History entries to load (default 200) -## Troubleshooting +## Connection troubleshooting - `disconnected`: ensure the Gateway is running and your `--url/--token/--password` are correct. - No agents in picker: check `openclaw agents list` and your routing config. diff --git a/docs/vps.md b/docs/vps.md index dedccee4b7e..f0b1f7d7777 100644 --- a/docs/vps.md +++ b/docs/vps.md @@ -21,7 +21,7 @@ deployments work at a high level. - **GCP (Compute Engine)**: [GCP](/install/gcp) - **exe.dev** (VM + HTTPS proxy): [exe.dev](/install/exe-dev) - **AWS (EC2/Lightsail/free tier)**: works well too. Video guide: - https://x.com/techfrenAJ/status/2014934471095812547 + [https://x.com/techfrenAJ/status/2014934471095812547](https://x.com/techfrenAJ/status/2014934471095812547) ## How cloud setups work diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md index 640340f17c9..233a67c48b0 100644 --- a/docs/web/control-ui.md +++ b/docs/web/control-ui.md @@ -19,7 +19,7 @@ It speaks **directly to the Gateway WebSocket** on the same port. If the Gateway is running on the same computer, open: -- http://127.0.0.1:18789/ (or http://localhost:18789/) +- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/)) If the page fails to load, start the Gateway first: `openclaw gateway`. diff --git a/docs/web/dashboard.md b/docs/web/dashboard.md index d68456821d6..5c33455f058 100644 --- a/docs/web/dashboard.md +++ b/docs/web/dashboard.md @@ -12,7 +12,7 @@ The Gateway dashboard is the browser Control UI served at `/` by default Quick open (local Gateway): -- http://127.0.0.1:18789/ (or http://localhost:18789/) +- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/)) Key references: diff --git a/package.json b/package.json index 50c97adfed8..8bf93835651 100644 --- a/package.json +++ b/package.json @@ -35,6 +35,7 @@ "build": "pnpm canvas:a2ui:bundle && tsdown && node --import tsx scripts/canvas-a2ui-copy.ts && node --import tsx scripts/copy-hook-metadata.ts && node --import tsx scripts/write-build-info.ts && node --import tsx scripts/write-cli-compat.ts", "canvas:a2ui:bundle": "bash scripts/bundle-a2ui.sh", "check": "pnpm tsgo && pnpm lint && pnpm format", + "check:docs": "pnpm format:docs && pnpm lint:docs && pnpm docs:build", "check:loc": "node --import tsx scripts/check-ts-max-loc.ts --max 500", "dev": "node scripts/run-node.mjs", "docs:bin": "node scripts/build-docs-list.mjs", @@ -43,6 +44,8 @@ "docs:list": "node scripts/docs-list.js", "format": "oxfmt --check", "format:all": "pnpm format && pnpm format:swift", + "format:docs": "git ls-files 'docs/**/*.md' 'docs/**/*.mdx' 'README.md' | xargs oxfmt --check", + "format:docs:fix": "git ls-files 'docs/**/*.md' 'docs/**/*.mdx' 'README.md' | xargs oxfmt --write", "format:fix": "oxfmt --write", "format:swift": "swiftformat --lint --config .swiftformat apps/macos/Sources apps/ios/Sources apps/shared/OpenClawKit/Sources", "gateway:dev": "OPENCLAW_SKIP_CHANNELS=1 CLAWDBOT_SKIP_CHANNELS=1 node scripts/run-node.mjs --dev gateway", @@ -54,6 +57,8 @@ "ios:run": "bash -lc 'cd apps/ios && xcodegen generate && xcodebuild -project OpenClaw.xcodeproj -scheme OpenClaw -destination \"${IOS_DEST:-platform=iOS Simulator,name=iPhone 17}\" -configuration Debug build && xcrun simctl boot \"${IOS_SIM:-iPhone 17}\" || true && xcrun simctl launch booted ai.openclaw.ios'", "lint": "oxlint --type-aware", "lint:all": "pnpm lint && pnpm lint:swift", + "lint:docs": "pnpm dlx markdownlint-cli2", + "lint:docs:fix": "pnpm dlx markdownlint-cli2 --fix", "lint:fix": "oxlint --type-aware --fix && pnpm format:fix", "lint:swift": "swiftlint lint --config .swiftlint.yml && (cd apps/ios && swiftlint lint --config .swiftlint.yml)", "mac:open": "open dist/OpenClaw.app",