mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-23 02:45:38 -06:00
docs: absorb documentation PR sweep
This commit is contained in:
Peter Steinberger
@@ -45,12 +45,13 @@ Minimal config:
|
||||
|
||||
Field reference:
|
||||
|
||||
| Field | Description |
|
||||
| ----------- | ------------------------------------------------- |
|
||||
| `account` | Bot phone number in E.164 format (`+15551234567`) |
|
||||
| `cliPath` | Path to `signal-cli` (`signal-cli` if on `PATH`) |
|
||||
| `dmPolicy` | DM access policy (`pairing` recommended) |
|
||||
| `allowFrom` | Phone numbers or `uuid:<id>` values allowed to DM |
|
||||
| Field | Description |
|
||||
| ------------ | ------------------------------------------------- |
|
||||
| `account` | Bot phone number in E.164 format (`+15551234567`) |
|
||||
| `cliPath` | Path to `signal-cli` (`signal-cli` if on `PATH`) |
|
||||
| `configPath` | signal-cli config dir passed as `--config` |
|
||||
| `dmPolicy` | DM access policy (`pairing` recommended) |
|
||||
| `allowFrom` | Phone numbers or `uuid:<id>` values allowed to DM |
|
||||
|
||||
## What it is
|
||||
|
||||
@@ -365,6 +366,7 @@ Provider options:
|
||||
- `channels.signal.apiMode`: `auto | native | container` (default: auto). See [Container mode](#container-mode-bbernhardsignal-cli-rest-api).
|
||||
- `channels.signal.account`: E.164 for the bot account.
|
||||
- `channels.signal.cliPath`: path to `signal-cli`.
|
||||
- `channels.signal.configPath`: optional `signal-cli --config` directory.
|
||||
- `channels.signal.httpUrl`: full daemon URL (overrides host/port).
|
||||
- `channels.signal.httpHost`, `channels.signal.httpPort`: daemon bind (default 127.0.0.1:8080).
|
||||
- `channels.signal.autoStart`: auto-spawn daemon (default true if `httpUrl` unset).
|
||||
|
||||
+12
-12
@@ -27,7 +27,7 @@ Both transports are production-ready and reach feature parity for messaging, sla
|
||||
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
||||
| Public Gateway URL | Not required | Required (DNS, TLS, reverse proxy or tunnel) |
|
||||
| Outbound network | Outbound WSS to `wss-primary.slack.com` must be reachable | No outbound WS; inbound HTTPS only |
|
||||
| Tokens needed | Bot token (`xoxb-...`) + App-Level Token (`xapp-...`) with `connections:write` | Bot token (`xoxb-...`) + Signing Secret |
|
||||
| Tokens needed | Bot token + App-Level Token with `connections:write` | Bot token + Signing Secret |
|
||||
| Dev laptop / behind firewall | Works as-is | Needs a public tunnel (ngrok, Cloudflare Tunnel, Tailscale Funnel) or staging Gateway |
|
||||
| Horizontal scaling | One Socket Mode session per app per host; multiple Gateways need separate Slack apps | Stateless POST handler; multiple Gateway replicas can share one app behind a load balancer |
|
||||
| Multi-account on one Gateway | Supported; each account opens its own WS | Supported; each account needs a unique `webhookPath` (default `/slack/events`) so registrations do not collide |
|
||||
@@ -222,8 +222,8 @@ openclaw plugins install @openclaw/slack
|
||||
|
||||
After Slack creates the app:
|
||||
|
||||
- **Basic Information → App-Level Tokens → Generate Token and Scopes**: add `connections:write`, save, copy the `xapp-...` value.
|
||||
- **Install App → Install to Workspace**: copy the `xoxb-...` Bot User OAuth Token.
|
||||
- **Basic Information -> App-Level Tokens -> Generate Token and Scopes**: add `connections:write`, save, copy the App-Level Token.
|
||||
- **Install App -> Install to Workspace**: copy the Bot User OAuth Token.
|
||||
|
||||
</Step>
|
||||
|
||||
@@ -232,8 +232,8 @@ openclaw plugins install @openclaw/slack
|
||||
Recommended SecretRef setup:
|
||||
|
||||
```bash
|
||||
export SLACK_APP_TOKEN=xapp-...
|
||||
export SLACK_BOT_TOKEN=xoxb-...
|
||||
export SLACK_APP_TOKEN=slack-app-token-example
|
||||
export SLACK_BOT_TOKEN=slack-bot-token-example
|
||||
cat > slack.socket.patch.json5 <<'JSON5'
|
||||
{
|
||||
channels: {
|
||||
@@ -253,8 +253,8 @@ openclaw config patch --file ./slack.socket.patch.json5
|
||||
Env fallback (default account only):
|
||||
|
||||
```bash
|
||||
SLACK_APP_TOKEN=xapp-...
|
||||
SLACK_BOT_TOKEN=xoxb-...
|
||||
SLACK_APP_TOKEN=slack-app-token-example
|
||||
SLACK_BOT_TOKEN=slack-bot-token-example
|
||||
```
|
||||
|
||||
</Step>
|
||||
@@ -455,7 +455,7 @@ openclaw gateway
|
||||
After Slack creates the app:
|
||||
|
||||
- **Basic Information → App Credentials**: copy the **Signing Secret** for request verification.
|
||||
- **Install App → Install to Workspace**: copy the `xoxb-...` Bot User OAuth Token.
|
||||
- **Install App -> Install to Workspace**: copy the Bot User OAuth Token.
|
||||
|
||||
</Step>
|
||||
|
||||
@@ -464,7 +464,7 @@ openclaw gateway
|
||||
Recommended SecretRef setup:
|
||||
|
||||
```bash
|
||||
export SLACK_BOT_TOKEN=xoxb-...
|
||||
export SLACK_BOT_TOKEN=slack-bot-token-example
|
||||
export SLACK_SIGNING_SECRET=...
|
||||
cat > slack.http.patch.json5 <<'JSON5'
|
||||
{
|
||||
@@ -867,7 +867,7 @@ The default manifest enables the Slack App Home **Home** tab and subscribes to `
|
||||
strings or SecretRef objects.
|
||||
- Config tokens override env fallback.
|
||||
- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env fallback applies only to the default account.
|
||||
- `userToken` (`xoxp-...`) is config-only (no env fallback) and defaults to read-only behavior (`userTokenReadOnly: true`).
|
||||
- `userToken` is config-only (no env fallback) and defaults to read-only behavior (`userTokenReadOnly: true`).
|
||||
|
||||
Status snapshot behavior:
|
||||
|
||||
@@ -1462,7 +1462,7 @@ openclaw pairing list slack
|
||||
|
||||
<Accordion title="Socket mode not connecting">
|
||||
Validate bot + app tokens and Socket Mode enablement in Slack app settings.
|
||||
The `xapp-...` App-Level Token needs `connections:write`, and the `xoxb-...`
|
||||
The App-Level Token needs `connections:write`, and the Bot User OAuth Token
|
||||
bot token must belong to the same Slack app/workspace as the app token.
|
||||
|
||||
If `openclaw channels status --probe --json` shows `botTokenStatus` or
|
||||
@@ -1532,7 +1532,7 @@ Slack can attach downloaded media to the agent turn when Slack file downloads su
|
||||
|
||||
When a Slack message with file attachments arrives:
|
||||
|
||||
1. OpenClaw downloads the file from Slack's private URL using the bot token (`xoxb-...`).
|
||||
1. OpenClaw downloads the file from Slack's private URL using the bot token.
|
||||
2. The file is written to the media store on success.
|
||||
3. Downloaded media paths and content types are added to the inbound context.
|
||||
4. Image-capable model/tool paths can use image attachments from that context.
|
||||
|
||||
@@ -635,6 +635,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Topic inheritance: topic entries inherit group settings unless overridden (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` is topic-only and does not inherit from group defaults.
|
||||
`topics."*"` sets defaults for every topic in that group; exact topic IDs still win over `"*"`.
|
||||
|
||||
**Per-topic agent routing**: Each topic can route to a different agent by setting `agentId` in the topic config. This gives each topic its own isolated workspace, memory, and session. Example:
|
||||
|
||||
@@ -1074,6 +1075,7 @@ Primary reference: [Configuration reference - Telegram](/gateway/config-channels
|
||||
|
||||
- startup/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` must point to a regular file; symlinks are rejected)
|
||||
- access control: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, top-level `bindings[]` (`type: "acp"`)
|
||||
- topic defaults: `groups.<chatId>.topics."*"` applies to unmatched forum topics; exact topic IDs override it
|
||||
- exec approvals: `execApprovals`, `accounts.*.execApprovals`
|
||||
- command/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- threading/replies: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
|
||||
|
||||
+2
-1
@@ -17,13 +17,14 @@ openclaw backup create --dry-run --json
|
||||
openclaw backup create --verify
|
||||
openclaw backup create --no-include-workspace
|
||||
openclaw backup create --only-config
|
||||
openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz
|
||||
openclaw backup verify ./2026-03-09T08-00-00.000+08-00-openclaw-backup.tar.gz
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- The archive includes a `manifest.json` file with the resolved source paths and archive layout.
|
||||
- Default output is a timestamped `.tar.gz` archive in the current working directory.
|
||||
- Timestamped backup filenames use your machine's local timezone and include the UTC offset.
|
||||
- If the current working directory is inside a backed-up source tree, OpenClaw falls back to your home directory for the default archive location.
|
||||
- Existing archive files are never overwritten.
|
||||
- Output paths inside the source state/workspace trees are rejected to avoid self-inclusion.
|
||||
|
||||
@@ -1379,10 +1379,10 @@ Split config into multiple files:
|
||||
- Array of files: deep-merged in order (later overrides earlier).
|
||||
- Sibling keys: merged after includes (override included values).
|
||||
- Nested includes: up to 10 levels deep.
|
||||
- Paths: resolved relative to the including file, but must stay inside the top-level config directory (`dirname` of `openclaw.json`). Absolute/`../` forms are allowed only when they still resolve inside that boundary.
|
||||
- Paths: resolved relative to the including file, but must stay inside the top-level config directory (`dirname` of `openclaw.json`). Absolute/`../` forms are allowed only when they still resolve inside that boundary. Paths must not contain null bytes and must be strictly shorter than 4096 characters before and after resolution.
|
||||
- OpenClaw-owned writes that change only one top-level section backed by a single-file include write through to that included file. For example, `plugins install` updates `plugins: { $include: "./plugins.json5" }` in `plugins.json5` and leaves `openclaw.json` intact.
|
||||
- Root includes, include arrays, and includes with sibling overrides are read-only for OpenClaw-owned writes; those writes fail closed instead of flattening the config.
|
||||
- Errors: clear messages for missing files, parse errors, and circular includes.
|
||||
- Errors: clear messages for missing files, parse errors, circular includes, invalid path format, and excessive length.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -513,6 +513,7 @@ candidate contains redacted secret placeholders such as `***`.
|
||||
- **Sibling keys**: merged after includes (override included values)
|
||||
- **Nested includes**: supported up to 10 levels deep
|
||||
- **Relative paths**: resolved relative to the including file
|
||||
- **Path format**: include paths must not contain null bytes and must be strictly shorter than 4096 characters before and after resolution
|
||||
- **OpenClaw-owned writes**: when a write changes only one top-level section
|
||||
backed by a single-file include such as `plugins: { $include: "./plugins.json5" }`,
|
||||
OpenClaw updates that included file and leaves `openclaw.json` intact
|
||||
@@ -525,7 +526,7 @@ candidate contains redacted secret placeholders such as `***`.
|
||||
additional directories that includes may reference. Symlinks are resolved
|
||||
and re-checked, so a path that lexically lives in a config dir but whose
|
||||
real target escapes every allowed root is still rejected.
|
||||
- **Error handling**: clear errors for missing files, parse errors, and circular includes
|
||||
- **Error handling**: clear errors for missing files, parse errors, circular includes, invalid path format, and excessive length
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -159,7 +159,7 @@ shorthand values.
|
||||
|
||||
When set, `OPENCLAW_HOME` replaces the system home directory (`$HOME` / `os.homedir()`) for all internal path resolution. This enables full filesystem isolation for headless service accounts.
|
||||
|
||||
**Precedence:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > `os.homedir()`
|
||||
**Precedence:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > Termux `PREFIX` home fallback on Android > `os.homedir()`
|
||||
|
||||
**Example** (macOS LaunchDaemon):
|
||||
|
||||
@@ -171,7 +171,7 @@ When set, `OPENCLAW_HOME` replaces the system home directory (`$HOME` / `os.home
|
||||
</dict>
|
||||
```
|
||||
|
||||
`OPENCLAW_HOME` can also be set to a tilde path (e.g. `~/svc`), which gets expanded using `$HOME` before use.
|
||||
`OPENCLAW_HOME` can also be set to a tilde path (e.g. `~/svc`), which gets expanded using the same OS home fallback chain before use.
|
||||
|
||||
## nvm users: web_fetch TLS failures
|
||||
|
||||
|
||||
+3
-3
@@ -98,14 +98,14 @@ read_when:
|
||||
fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
|
||||
|
||||
# Model provider API keys
|
||||
fly secrets set ANTHROPIC_API_KEY=sk-ant-...
|
||||
fly secrets set ANTHROPIC_API_KEY=example-anthropic-key-not-real
|
||||
|
||||
# Optional: Other providers
|
||||
fly secrets set OPENAI_API_KEY=sk-...
|
||||
fly secrets set OPENAI_API_KEY=example-openai-key-not-real
|
||||
fly secrets set GOOGLE_API_KEY=...
|
||||
|
||||
# Channel tokens
|
||||
fly secrets set DISCORD_BOT_TOKEN=MTQ...
|
||||
fly secrets set DISCORD_BOT_TOKEN=example-discord-bot-token
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
@@ -105,10 +105,10 @@ In the VNC window:
|
||||
3. Create a user account (remember the username and password)
|
||||
4. Skip all optional features
|
||||
|
||||
After setup completes, enable SSH:
|
||||
After setup completes:
|
||||
|
||||
1. Open System Settings → General → Sharing
|
||||
2. Enable "Remote Login"
|
||||
1. Enable SSH: Open System Settings -> General -> Sharing and enable "Remote Login".
|
||||
2. For headless VM use, enable auto-login: Open System Settings -> Users & Groups, select "Automatically log in as:", and choose the VM user.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+3
-2
@@ -26,11 +26,12 @@ OpenClaw auto-detects in this order and stops at the first working option:
|
||||
- `sherpa-onnx-offline` (requires `SHERPA_ONNX_MODEL_DIR` with encoder/decoder/joiner/tokens)
|
||||
- `whisper-cli` (from `whisper-cpp`; uses `WHISPER_CPP_MODEL` or the bundled tiny model)
|
||||
- `whisper` (Python CLI; downloads models automatically)
|
||||
3. **Gemini CLI** (`gemini`) using `read_many_files`
|
||||
4. **Provider auth**
|
||||
3. **Provider auth**
|
||||
- Configured `models.providers.*` entries that support audio are tried first
|
||||
- Bundled fallback order: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral
|
||||
|
||||
As of 2026-05-22, Gemini CLI auto-detect is no longer supported for media understanding. Google is transitioning Gemini CLI users to Antigravity CLI; audio should use local or provider transcription, while image/video CLI fallback should move to Antigravity CLI (`agy`).
|
||||
|
||||
To disable auto-detection, set `tools.media.audio.enabled: false`.
|
||||
To customize, set `tools.media.audio.models`.
|
||||
Note: Binary detection is best-effort across macOS/Linux/Windows; ensure the CLI is on `PATH` (we expand `~`), or set an explicit CLI model with a full command path.
|
||||
|
||||
@@ -60,7 +60,7 @@ Anthropic's current public docs:
|
||||
|
||||
```json5
|
||||
{
|
||||
env: { ANTHROPIC_API_KEY: "sk-ant-..." },
|
||||
env: { ANTHROPIC_API_KEY: "example-anthropic-key-not-real" },
|
||||
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
|
||||
}
|
||||
```
|
||||
|
||||
@@ -28,7 +28,7 @@ Choose your preferred auth method and follow the setup steps.
|
||||
<Steps>
|
||||
<Step title="Set AWS credentials on the gateway host">
|
||||
```bash
|
||||
export AWS_ACCESS_KEY_ID="AKIA..."
|
||||
export AWS_ACCESS_KEY_ID="EXAMPLE_AWS_ACCESS_KEY_ID"
|
||||
export AWS_SECRET_ACCESS_KEY="..."
|
||||
export AWS_REGION="us-east-1"
|
||||
# Optional:
|
||||
|
||||
@@ -170,7 +170,7 @@ Choose your preferred auth method and follow the setup steps.
|
||||
|
||||
```json5
|
||||
{
|
||||
env: { OPENAI_API_KEY: "sk-..." },
|
||||
env: { OPENAI_API_KEY: "example-openai-key-not-real" },
|
||||
agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
|
||||
}
|
||||
```
|
||||
@@ -180,7 +180,7 @@ Choose your preferred auth method and follow the setup steps.
|
||||
|
||||
```json5
|
||||
{
|
||||
env: { OPENAI_API_KEY: "sk-..." },
|
||||
env: { OPENAI_API_KEY: "example-openai-key-not-real" },
|
||||
agents: { defaults: { model: { primary: "openai/chat-latest" } } },
|
||||
}
|
||||
```
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
summary: "Secret-scanner-safe placeholder conventions for docs and examples"
|
||||
read_when:
|
||||
- Writing docs that include tokens, API keys, or credential snippets
|
||||
- Updating examples that may be scanned by secret-detection tooling
|
||||
title: "Secret Placeholder Conventions"
|
||||
---
|
||||
|
||||
# Secret placeholder conventions
|
||||
|
||||
Use placeholders that are human-readable but do not resemble real secrets.
|
||||
|
||||
## Recommended style
|
||||
|
||||
- Prefer descriptive values like `example-openai-key-not-real` or `example-discord-bot-token`.
|
||||
- For shell snippets, prefer `${OPENAI_API_KEY}` over inline token-like strings.
|
||||
- Keep examples obviously fake and scoped to purpose (provider, channel, auth type).
|
||||
|
||||
## Avoid these patterns in docs
|
||||
|
||||
- Private key sentinels such as `-----BEGIN PRIVATE KEY-----`.
|
||||
- Prefixes that resemble live credentials, for example `sk-...`, `xoxb-...`, `AKIA...`.
|
||||
- Realistic-looking bearer tokens copied from runtime logs.
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
# Good
|
||||
export OPENAI_API_KEY="example-openai-key-not-real"
|
||||
|
||||
# Better (when the doc is about env wiring)
|
||||
export OPENAI_API_KEY="${OPENAI_API_KEY}"
|
||||
```
|
||||
@@ -26,6 +26,10 @@ OpenClaw assembles its own system prompt on every run. It includes:
|
||||
|
||||
See the full breakdown in [System Prompt](/concepts/system-prompt).
|
||||
|
||||
When documenting credentials or auth snippets, use the
|
||||
[Secret Placeholder Conventions](/reference/secret-placeholder-conventions) to
|
||||
avoid secret-scanner false positives in docs-only changes.
|
||||
|
||||
## What counts in the context window
|
||||
|
||||
Everything the model receives counts toward the context limit:
|
||||
|
||||
Reference in New Issue
Block a user