docs: typography hygiene across 6 pages

Replaced 74 typography characters (curly quotes, apostrophes, em/en
dashes, non-breaking hyphens) with ASCII equivalents per
docs/CLAUDE.md heading and content hygiene rules.

- docs/gateway/opentelemetry.md: 13 chars
- docs/channels/msteams.md: 13 chars
- docs/tools/skills.md: 12 chars
- docs/start/setup.md: 12 chars
- docs/nodes/location-command.md: 12 chars
- docs/concepts/context-engine.md: 12 chars
This commit is contained in:
Vincent Koc
2026-05-05 20:34:37 -07:00
parent ae9f779e5f
commit f4a63940cc
6 changed files with 61 additions and 61 deletions

View File

@@ -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 <teamsAppId> --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 mentiongated 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 (mentiongated).
- 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

View File

@@ -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
</Step>
<Step title="Switch back to legacy (optional)">
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).
</Step>
</Steps>
@@ -200,13 +200,13 @@ Required members:
<ParamField path="promptAuthority" type='"assembled" | "preassembly_may_overflow"'>
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.
</ParamField>
`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
```
<Note>
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.
</Note>
<Note>
@@ -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.).
</Accordion>
<Accordion title="Memory plugins">
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(...)`.
</Accordion>
<Accordion title="Session pruning">
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

View File

@@ -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

View File

@@ -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

View File

@@ -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 dont 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; dont 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 its still off, run:
lingering for you (may prompt for sudo). If it's still off, run:
```bash
sudo loginctl enable-linger $USER

View File

@@ -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.
</Accordion>
@@ -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 <slug>` is different it downloads a ClawHub skill folder into the workspace and does not use the installer-metadata path above.
- `openclaw skills install <slug>` 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`:
</ParamField>
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`.
<Note>
@@ -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