From 1bf9f237f719385517ba5f6c709875a18c1a53b6 Mon Sep 17 00:00:00 2001 From: Sebastian <19554889+sebslight@users.noreply.github.com> Date: Fri, 6 Feb 2026 09:35:57 -0500 Subject: [PATCH] docs: linting --- docs/channels/slack.md | 4 ++-- docs/channels/telegram.md | 2 +- docs/concepts/groups.md | 13 +++++++------ docs/concepts/session.md | 2 +- docs/gateway/configuration.md | 17 +++++++++-------- docs/help/faq.md | 22 +++++++++++----------- docs/hooks.md | 2 +- docs/nodes/camera.md | 4 ++-- docs/platforms/mac/voice-overlay.md | 10 +++++----- docs/providers/anthropic.md | 4 ++-- docs/providers/openai.md | 4 ++-- docs/reference/templates/USER.md | 15 ++++++++------- docs/start/pairing.md | 2 +- docs/tools/web.md | 6 +++--- docs/tui.md | 2 +- 15 files changed, 56 insertions(+), 53 deletions(-) diff --git a/docs/channels/slack.md b/docs/channels/slack.md index a9dbc24667..c8329439f7 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -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**. diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index 655749d876..c7fb4fe57c 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. diff --git a/docs/concepts/groups.md b/docs/concepts/groups.md index 04e90106de..635211d336 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/session.md b/docs/concepts/session.md index 922bb960fa..503dcf37f4 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/gateway/configuration.md b/docs/gateway/configuration.md index 0a5a85f1d7..545a937dfb 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) @@ -3366,7 +3367,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/help/faq.md b/docs/help/faq.md index 2c9e9f1be7..191d2be1e5 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) @@ -685,7 +685,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). @@ -1069,7 +1069,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. @@ -1449,7 +1449,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 @@ -1717,7 +1717,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 @@ -2624,7 +2624,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/hooks.md b/docs/hooks.md index 4aa6e6e3a8..a4a3a95df1 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 diff --git a/docs/nodes/camera.md b/docs/nodes/camera.md index 8ee0dd99a8..3d5416a544 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/platforms/mac/voice-overlay.md b/docs/platforms/mac/voice-overlay.md index 10df85007a..9c42601b18 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/providers/anthropic.md b/docs/providers/anthropic.md index 5f2374fe14..ff82280bef 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/openai.md b/docs/providers/openai.md index 509fb56405..54e3d29e45 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/templates/USER.md b/docs/reference/templates/USER.md index 6dc5512389..682e99ae6c 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 b11373c933..19813155f5 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/tools/web.md b/docs/tools/web.md index 4c1ff47b61..4a3c23841c 100644 --- a/docs/tools/web.md +++ b/docs/tools/web.md @@ -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 2be342092e..8398cedfe1 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.