diff --git a/docs/channels/msteams.md b/docs/channels/msteams.md index 184eab43c4b..e8fc0eb3e48 100644 --- a/docs/channels/msteams.md +++ b/docs/channels/msteams.md @@ -79,9 +79,9 @@ This single command: - Creates an Entra ID (Azure AD) application - Generates a client secret - Builds and uploads a Teams app manifest (with icons) -- Registers the bot (Teams-managed by default — no Azure subscription needed) +- Registers the bot (Teams-managed by default - no Azure subscription needed) -The output will show `CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID`, and a **Teams App ID** — note these for the next steps. It also offers to install the app in Teams directly. +The output will show `CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID`, and a **Teams App ID** - note these for the next steps. It also offers to install the app in Teams directly. **4. Configure OpenClaw** using the credentials from the output: @@ -103,7 +103,7 @@ Or use environment variables directly: `MSTEAMS_APP_ID`, `MSTEAMS_APP_PASSWORD`, **5. Install the app in Teams** -`teams app create` will prompt you to install the app — select "Install in Teams". If you skipped it, you can get the link later: +`teams app create` will prompt you to install the app - select "Install in Teams". If you skipped it, you can get the link later: ```bash teams app get --install-link @@ -147,14 +147,14 @@ Disable with: - Default: `channels.msteams.dmPolicy = "pairing"`. Unknown senders are ignored until approved. - `channels.msteams.allowFrom` should use stable AAD object IDs. -- Do not rely on UPN/display-name matching for allowlists — they can change. OpenClaw disables direct name matching by default; opt in explicitly with `channels.msteams.dangerouslyAllowNameMatching: true`. +- Do not rely on UPN/display-name matching for allowlists - they can change. OpenClaw disables direct name matching by default; opt in explicitly with `channels.msteams.dangerouslyAllowNameMatching: true`. - The wizard can resolve names to IDs via Microsoft Graph when credentials allow. **Group access** - Default: `channels.msteams.groupPolicy = "allowlist"` (blocked unless you add `groupAllowFrom`). Use `channels.defaults.groupPolicy` to override the default when unset. - `channels.msteams.groupAllowFrom` controls which senders can trigger in group chats/channels (falls back to `channels.msteams.allowFrom`). -- Set `groupPolicy: "open"` to allow any member (still mention‑gated by default). +- Set `groupPolicy: "open"` to allow any member (still mention-gated by default). - To allow **no channels**, set `channels.msteams.groupPolicy: "disabled"`. Example: @@ -174,7 +174,7 @@ Example: - Scope group/channel replies by listing teams and channels under `channels.msteams.teams`. - Keys should use stable Teams conversation IDs from Teams links, not mutable display names. -- When `groupPolicy="allowlist"` and a teams allowlist is present, only listed teams/channels are accepted (mention‑gated). +- When `groupPolicy="allowlist"` and a teams allowlist is present, only listed teams/channels are accepted (mention-gated). - The configure wizard accepts `Team/Channel` entries and stores them for you. - On startup, OpenClaw resolves team/channel and user allowlist names to IDs (when Graph permissions allow) and logs the mapping; unresolved team/channel names are kept as typed but ignored for routing by default unless `channels.msteams.dangerouslyAllowNameMatching: true` is enabled. @@ -416,7 +416,7 @@ For AKS deployments using workload identity: azure.workload.identity/use: "true" ``` -5. **Ensure network access** to IMDS (`169.254.169.254`) — if using NetworkPolicy, add an egress rule allowing traffic to `169.254.169.254/32` on port 80. +5. **Ensure network access** to IMDS (`169.254.169.254`) - if using NetworkPolicy, add an egress rule allowing traffic to `169.254.169.254/32` on port 80. ### Auth type comparison @@ -702,7 +702,7 @@ Key settings (see `/gateway/configuration` for shared channel patterns): - `toolsBySender` keys should use explicit prefixes: `id:`, `e164:`, `username:`, `name:` (legacy unprefixed keys still map to `id:` only). - `channels.msteams.actions.memberInfo`: enable or disable the Graph-backed member info action (default: enabled when Graph credentials are available). -- `channels.msteams.authType`: authentication type — `"secret"` (default) or `"federated"`. +- `channels.msteams.authType`: authentication type - `"secret"` (default) or `"federated"`. - `channels.msteams.certificatePath`: path to PEM certificate file (federated + certificate auth). - `channels.msteams.certificateThumbprint`: certificate thumbprint (optional, not required for auth). - `channels.msteams.useManagedIdentity`: enable managed identity auth (federated mode). @@ -1014,8 +1014,8 @@ Bots have limited support in private channels: ## Related -- [Channels Overview](/channels) — all supported channels -- [Pairing](/channels/pairing) — DM authentication and pairing flow -- [Groups](/channels/groups) — group chat behavior and mention gating -- [Channel Routing](/channels/channel-routing) — session routing for messages -- [Security](/gateway/security) — access model and hardening +- [Channels Overview](/channels) - all supported channels +- [Pairing](/channels/pairing) - DM authentication and pairing flow +- [Groups](/channels/groups) - group chat behavior and mention gating +- [Channel Routing](/channels/channel-routing) - session routing for messages +- [Security](/gateway/security) - access model and hardening diff --git a/docs/concepts/context-engine.md b/docs/concepts/context-engine.md index fdd14f6434f..ef6ed7e7577 100644 --- a/docs/concepts/context-engine.md +++ b/docs/concepts/context-engine.md @@ -10,7 +10,7 @@ sidebarTitle: "Context engine" A **context engine** controls how OpenClaw builds model context for each run: which messages to include, how to summarize older history, and how to manage context across subagent boundaries. -OpenClaw ships with a built-in `legacy` engine and uses it by default — most users never need to change this. Install and select a plugin engine only when you want different assembly, compaction, or cross-session recall behavior. +OpenClaw ships with a built-in `legacy` engine and uses it by default - most users never need to change this. Install and select a plugin engine only when you want different assembly, compaction, or cross-session recall behavior. ## Quick start @@ -61,7 +61,7 @@ OpenClaw ships with a built-in `legacy` engine and uses it by default — most u - Set `contextEngine` to `"legacy"` (or remove the key entirely — `"legacy"` is the default). + Set `contextEngine` to `"legacy"` (or remove the key entirely - `"legacy"` is the default). @@ -200,13 +200,13 @@ Required members: Controls which token estimate the runner uses for preemptive overflow prechecks. Defaults to `"assembled"`, which means only the assembled - prompt's estimate is checked — appropriate for engines that return a + prompt's estimate is checked - appropriate for engines that return a windowed, self-contained context. Set to `"preassembly_may_overflow"` only when your assembled view can hide overflow risk in the underlying transcript; the runner then takes the maximum of the assembled estimate and the pre-assembly (unwindowed) session-history estimate when deciding whether to preemptively compact. Either way, the messages you return are - still what the model sees — `promptAuthority` only affects the precheck. + still what the model sees - `promptAuthority` only affects the precheck. `compact` returns a `CompactResult`. When compaction rotates the active @@ -222,7 +222,7 @@ Optional members: | `afterTurn(params)` | Method | Post-run lifecycle work (persist state, trigger background compaction). | | `prepareSubagentSpawn(params)` | Method | Set up shared state for a child session before it starts. | | `onSubagentEnded(params)` | Method | Clean up after a subagent ends. | -| `dispose()` | Method | Release resources. Called during gateway shutdown or plugin reload — not per-session. | +| `dispose()` | Method | Release resources. Called during gateway shutdown or plugin reload - not per-session. | ### ownsCompaction @@ -269,7 +269,7 @@ A no-op `compact()` is unsafe for an active non-owning engine because it disable ``` -The slot is exclusive at run time — only one registered context engine is resolved for a given run or compaction operation. Other enabled `kind: "context-engine"` plugins can still load and run their registration code; `plugins.slots.contextEngine` only selects which registered engine id OpenClaw resolves when it needs a context engine. +The slot is exclusive at run time - only one registered context engine is resolved for a given run or compaction operation. Other enabled `kind: "context-engine"` plugins can still load and run their registration code; `plugins.slots.contextEngine` only selects which registered engine id OpenClaw resolves when it needs a context engine. @@ -283,7 +283,7 @@ The slot is exclusive at run time — only one registered context engine is reso Compaction is one responsibility of the context engine. The legacy engine delegates to OpenClaw's built-in summarization. Plugin engines can implement any compaction strategy (DAG summaries, vector retrieval, etc.). - Memory plugins (`plugins.slots.memory`) are separate from context engines. Memory plugins provide search/retrieval; context engines control what the model sees. They can work together — a context engine might use memory plugin data during assembly. Plugin engines that want the active memory prompt path should prefer `buildMemorySystemPromptAddition(...)` from `openclaw/plugin-sdk/core`, which converts the active memory prompt sections into a ready-to-prepend `systemPromptAddition`. If an engine needs lower-level control, it can still pull raw lines from `openclaw/plugin-sdk/memory-host-core` via `buildActiveMemoryPromptSection(...)`. + Memory plugins (`plugins.slots.memory`) are separate from context engines. Memory plugins provide search/retrieval; context engines control what the model sees. They can work together - a context engine might use memory plugin data during assembly. Plugin engines that want the active memory prompt path should prefer `buildMemorySystemPromptAddition(...)` from `openclaw/plugin-sdk/core`, which converts the active memory prompt sections into a ready-to-prepend `systemPromptAddition`. If an engine needs lower-level control, it can still pull raw lines from `openclaw/plugin-sdk/memory-host-core` via `buildActiveMemoryPromptSection(...)`. Trimming old tool results in-memory still runs regardless of which context engine is active. @@ -299,8 +299,8 @@ The slot is exclusive at run time — only one registered context engine is reso ## Related -- [Compaction](/concepts/compaction) — summarizing long conversations -- [Context](/concepts/context) — how context is built for agent turns -- [Plugin Architecture](/plugins/architecture) — registering context engine plugins -- [Plugin manifest](/plugins/manifest) — plugin manifest fields -- [Plugins](/tools/plugin) — plugin overview +- [Compaction](/concepts/compaction) - summarizing long conversations +- [Context](/concepts/context) - how context is built for agent turns +- [Plugin Architecture](/plugins/architecture) - registering context engine plugins +- [Plugin manifest](/plugins/manifest) - plugin manifest fields +- [Plugins](/tools/plugin) - plugin overview diff --git a/docs/gateway/opentelemetry.md b/docs/gateway/opentelemetry.md index 3f9883afe0a..13731697ee6 100644 --- a/docs/gateway/opentelemetry.md +++ b/docs/gateway/opentelemetry.md @@ -139,11 +139,11 @@ Set `diagnostics.otel.captureContent.*` to `true` only when your collector and retention policy are approved for prompt, response, tool, or system-prompt text. Each subkey is opt-in independently: -- `inputMessages` — user prompt content. -- `outputMessages` — model response content. -- `toolInputs` — tool argument payloads. -- `toolOutputs` — tool result payloads. -- `systemPrompt` — assembled system/developer prompt. +- `inputMessages` - user prompt content. +- `outputMessages` - model response content. +- `toolInputs` - tool argument payloads. +- `toolOutputs` - tool result payloads. +- `systemPrompt` - assembled system/developer prompt. When any subkey is enabled, model and tool spans get bounded, redacted `openclaw.content.*` attributes for that class only. @@ -302,7 +302,7 @@ to them directly without OTLP export. **Model usage** -- `model.usage` — tokens, cost, duration, context, provider/model/channel, +- `model.usage` - tokens, cost, duration, context, provider/model/channel, session ids. `usage` is provider/turn accounting for cost and telemetry; `context.used` is the current prompt/context snapshot and can be lower than provider `usage.total` when cached input or tool-loop calls are involved. @@ -322,7 +322,7 @@ to them directly without OTLP export. **Harness lifecycle** -- `harness.run.started` / `harness.run.completed` / `harness.run.error` — +- `harness.run.started` / `harness.run.completed` / `harness.run.error` - per-run lifecycle for the agent harness. Includes `harnessId`, optional `pluginId`, provider/model/channel, and run id. Completion adds `durationMs`, `outcome`, optional `resultClassification`, `yieldDetected`, @@ -332,7 +332,7 @@ to them directly without OTLP export. **Exec** -- `exec.process.completed` — terminal outcome, duration, target, mode, exit +- `exec.process.completed` - terminal outcome, duration, target, mode, exit code, and failure kind. Command text and working directories are not included. @@ -380,8 +380,8 @@ You can also leave `diagnostics-otel` out of `plugins.allow`, or run ## Related -- [Logging](/logging) — file logs, console output, CLI tailing, and the Control UI Logs tab -- [Gateway logging internals](/gateway/logging) — WS log styles, subsystem prefixes, and console capture -- [Diagnostics flags](/diagnostics/flags) — targeted debug-log flags -- [Diagnostics export](/gateway/diagnostics) — operator support-bundle tool (separate from OTEL export) -- [Configuration reference](/gateway/configuration-reference#diagnostics) — full `diagnostics.*` field reference +- [Logging](/logging) - file logs, console output, CLI tailing, and the Control UI Logs tab +- [Gateway logging internals](/gateway/logging) - WS log styles, subsystem prefixes, and console capture +- [Diagnostics flags](/diagnostics/flags) - targeted debug-log flags +- [Diagnostics export](/gateway/diagnostics) - operator support-bundle tool (separate from OTEL export) +- [Configuration reference](/gateway/configuration-reference#diagnostics) - full `diagnostics.*` field reference diff --git a/docs/nodes/location-command.md b/docs/nodes/location-command.md index 3eb5bc99d31..1393b7c6db5 100644 --- a/docs/nodes/location-command.md +++ b/docs/nodes/location-command.md @@ -19,7 +19,7 @@ OS permissions are multi-level. We can expose a selector in-app, but the OS stil - iOS/macOS may expose **While Using** or **Always** in system prompts/Settings. - Android app currently supports foreground location only. -- Precise location is a separate grant (iOS 14+ “Precise”, Android “fine” vs “coarse”). +- Precise location is a separate grant (iOS 14+ "Precise", Android "fine" vs "coarse"). Selector in UI drives our requested mode; actual grant lives in OS settings. @@ -91,9 +91,9 @@ Errors (stable codes): ## UX copy (suggested) -- Off: “Location sharing is disabled.” -- While Using: “Only when OpenClaw is open.” -- Precise: “Use precise GPS location. Toggle off to share approximate location.” +- Off: "Location sharing is disabled." +- While Using: "Only when OpenClaw is open." +- Precise: "Use precise GPS location. Toggle off to share approximate location." ## Related diff --git a/docs/start/setup.md b/docs/start/setup.md index 82e6a2f2cda..1f66ca4c688 100644 --- a/docs/start/setup.md +++ b/docs/start/setup.md @@ -2,7 +2,7 @@ summary: "Advanced setup and development workflows for OpenClaw" read_when: - Setting up a new machine - - You want “latest + greatest” without breaking your personal setup + - You want "latest + greatest" without breaking your personal setup title: "Setup" --- @@ -25,11 +25,11 @@ Pick a setup workflow based on how often you want updates and whether you want t - `pnpm` required for source checkouts. OpenClaw loads bundled plugins from the `extensions/*` pnpm workspace packages in dev mode, so root `npm install` does not prepare the full source tree. -- Docker (optional; only for containerized setup/e2e — see [Docker](/install/docker)) +- Docker (optional; only for containerized setup/e2e - see [Docker](/install/docker)) ## Tailoring strategy (so updates do not hurt) -If you want “100% tailored to me” _and_ easy updates, keep your customization in: +If you want "100% tailored to me" _and_ easy updates, keep your customization in: - **Config:** `~/.openclaw/openclaw.json` (JSON/JSON5-ish) - **Workspace:** `~/.openclaw/workspace` (skills, prompts, memories; make it a private git repo) @@ -46,7 +46,7 @@ From inside this repo, use the local CLI entry: openclaw setup ``` -If you don’t have a global install yet, run it via `pnpm openclaw setup`. +If you don't have a global install yet, run it via `pnpm openclaw setup`. ## Run the Gateway from this repo @@ -119,7 +119,7 @@ In **OpenClaw.app**: ### 3) Verify -- In-app Gateway status should read **“Using existing gateway …”** +- In-app Gateway status should read **"Using existing gateway …"** - Or via CLI: ```bash @@ -153,14 +153,14 @@ Use this when debugging auth or deciding what to back up: ## Updating (without wrecking your setup) -- Keep `~/.openclaw/workspace` and `~/.openclaw/` as “your stuff”; don’t put personal prompts/config into the `openclaw` repo. +- Keep `~/.openclaw/workspace` and `~/.openclaw/` as "your stuff"; don't put personal prompts/config into the `openclaw` repo. - Updating source: `git pull` + `pnpm install` + keep using `pnpm gateway:watch`. ## Linux (systemd user service) Linux installs use a systemd **user** service. By default, systemd stops user services on logout/idle, which kills the Gateway. Onboarding attempts to enable -lingering for you (may prompt for sudo). If it’s still off, run: +lingering for you (may prompt for sudo). If it's still off, run: ```bash sudo loginctl enable-linger $USER diff --git a/docs/tools/skills.md b/docs/tools/skills.md index b9320c6b029..626cde60df0 100644 --- a/docs/tools/skills.md +++ b/docs/tools/skills.md @@ -80,7 +80,7 @@ allowlists decide which skills an agent can actually use. - Omit `agents.list[].skills` to inherit `agents.defaults.skills`. - Set `agents.list[].skills: []` for no skills. - A non-empty `agents.list[].skills` list is the **final** set for that - agent — it does not merge with defaults. + agent - it does not merge with defaults. - The effective allowlist applies across prompt building, skill slash-command discovery, sandbox sync, and skill snapshots. @@ -92,7 +92,7 @@ Plugins can ship their own skills by listing `skills` directories in `openclaw.plugin.json` (paths relative to the plugin root). Plugin skills load when the plugin is enabled. This is the right place for tool-specific operating guides that are too long for the tool description but should be -available whenever the plugin is installed — for example, the browser +available whenever the plugin is installed - for example, the browser plugin ships a `browser-automation` skill for multi-step browser control. Plugin skill directories are merged into the same low-precedence path as @@ -158,7 +158,7 @@ Prefer sandboxed runs for untrusted inputs and risky tools. See - Workspace and extra-dir skill discovery only accepts skill roots and `SKILL.md` files whose resolved realpath stays inside the configured root. - Gateway-backed skill dependency installs (`skills.install`, onboarding, and the Skills settings UI) run the built-in dangerous-code scanner before executing installer metadata. `critical` findings block by default unless the caller explicitly sets the dangerous override; suspicious findings still warn only. -- `openclaw skills install ` is different — it downloads a ClawHub skill folder into the workspace and does not use the installer-metadata path above. +- `openclaw skills install ` is different - it downloads a ClawHub skill folder into the workspace and does not use the installer-metadata path above. - `skills.entries.*.env` and `skills.entries.*.apiKey` inject secrets into the **host** process for that agent turn (not the sandbox). Keep secrets out of prompts and logs. For a broader threat model and checklists, see [Security](/gateway/security). @@ -302,7 +302,7 @@ metadata: - If multiple installers are listed, the gateway picks a single preferred option (brew when available, otherwise node). - If all installers are `download`, OpenClaw lists each entry so you can see the available artifacts. - Installer specs can include `os: ["darwin"|"linux"|"win32"]` to filter options by platform. - - Node installs honor `skills.install.nodeManager` in `openclaw.json` (default: npm; options: npm/pnpm/yarn/bun). This only affects skill installs; the Gateway runtime should still be Node — Bun is not recommended for WhatsApp/Telegram. + - Node installs honor `skills.install.nodeManager` in `openclaw.json` (default: npm; options: npm/pnpm/yarn/bun). This only affects skill installs; the Gateway runtime should still be Node - Bun is not recommended for WhatsApp/Telegram. - Gateway-backed installer selection is preference-driven: when install specs mix kinds, OpenClaw prefers Homebrew when `skills.install.preferBrew` is enabled and `brew` exists, then `uv`, then the configured node manager, then other fallbacks like `go` or `download`. - If every install spec is `download`, OpenClaw surfaces all download options instead of collapsing to one preferred installer. @@ -362,7 +362,7 @@ under `skills.entries` in `~/.openclaw/openclaw.json`: If the skill name contains hyphens, quote the key (JSON5 allows quoted -keys). Config keys match the **skill name** by default — if a skill +keys). Config keys match the **skill name** by default - if a skill defines `metadata.openclaw.skillKey`, use that key under `skills.entries`. @@ -464,7 +464,7 @@ skill plus your actual field lengths. OpenClaw ships a baseline set of skills as **bundled skills** with the install (npm package or OpenClaw.app). `~/.openclaw/skills` exists for -local overrides — for example, pinning or patching a skill without +local overrides - for example, pinning or patching a skill without changing the bundled copy. Workspace skills are user-owned and override both on name conflicts. @@ -475,9 +475,9 @@ schema: [Skills config](/tools/skills-config). ## Related -- [ClawHub](/tools/clawhub) — public skills registry -- [Creating skills](/tools/creating-skills) — building custom skills -- [Plugins](/tools/plugin) — plugin system overview -- [Skill Workshop plugin](/plugins/skill-workshop) — generate skills from agent work -- [Skills config](/tools/skills-config) — skill configuration reference -- [Slash commands](/tools/slash-commands) — all available slash commands +- [ClawHub](/tools/clawhub) - public skills registry +- [Creating skills](/tools/creating-skills) - building custom skills +- [Plugins](/tools/plugin) - plugin system overview +- [Skill Workshop plugin](/plugins/skill-workshop) - generate skills from agent work +- [Skills config](/tools/skills-config) - skill configuration reference +- [Slash commands](/tools/slash-commands) - all available slash commands