Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
105 lines
4.6 KiB
Markdown
105 lines
4.6 KiB
Markdown
# Configuration
|
|
|
|
## Overview
|
|
|
|
OpenClaw reads an optional JSON5 config from `~/.openclaw/openclaw.json` with support for comments and trailing commas. The system uses sensible defaults when the file is absent, though configuration becomes necessary for:
|
|
|
|
- Restricting bot access by channel and sender
|
|
- Managing group allowlists and mention behaviors
|
|
- Customizing message prefixes
|
|
- Setting agent workspaces
|
|
- Tuning embedded agent defaults and session behavior
|
|
- Defining per-agent identity settings
|
|
|
|
## Validation & Error Handling
|
|
|
|
OpenClaw only accepts configurations that fully match the schema. Unknown keys, malformed types, or invalid values cause the Gateway to refuse to start for safety.
|
|
|
|
When validation fails, diagnostic commands remain available. Running `openclaw doctor` reveals specific issues, while `openclaw doctor --fix` applies migrations without requiring explicit confirmation.
|
|
|
|
## Configuration Management
|
|
|
|
### Apply & Restart
|
|
|
|
The `config.apply` RPC validates and writes the complete configuration in one operation, replacing the entire config file. Users should maintain backups before updates.
|
|
|
|
### Partial Updates
|
|
|
|
The `config.patch` method merges changes without affecting unrelated keys, using JSON merge patch semantics where objects combine recursively and `null` deletes entries.
|
|
|
|
## Environment Variables
|
|
|
|
OpenClaw loads environment variables from:
|
|
|
|
- Parent process (shell, launchd/systemd, CI)
|
|
- `.env` in the current working directory
|
|
- Global `.env` from `~/.openclaw/.env`
|
|
|
|
Variables can be referenced in config strings using `${VAR_NAME}` syntax, with substitution occurring at load time before validation.
|
|
|
|
## Multi-Agent Routing
|
|
|
|
Multiple isolated agents can run within a single Gateway instance, each with separate workspaces and sessions. Inbound messages route to agents via bindings based on channel, account, and peer matching with deterministic precedence rules.
|
|
|
|
Per-agent configuration allows mixed access levels - from full access (personal agents) to restricted tools and read-only workspaces (family/public agents).
|
|
|
|
## Channel Configuration
|
|
|
|
### WhatsApp
|
|
|
|
Supports DM policies (pairing, allowlist, open, disabled), multi-account setup, read receipt control, and group allowlists with mention gating.
|
|
|
|
### Telegram
|
|
|
|
Includes custom commands, draft streaming, reaction notifications, and per-topic configuration for groups.
|
|
|
|
### Discord
|
|
|
|
Offers guild/channel-specific settings, reaction modes, thread isolation, and action gating with media size limits.
|
|
|
|
### Additional Channels
|
|
|
|
Google Chat, Slack, Mattermost, Signal, iMessage, and Microsoft Teams each support webhooks, tokens, or native integrations with channel-specific mention and reaction handling.
|
|
|
|
## Agent Defaults
|
|
|
|
### Models
|
|
|
|
The embedded agent runtime is controlled via `agents.defaults`, which manages model selection, thinking modes, verbose output, and timeouts.
|
|
|
|
Primary and fallback models support provider/model format (e.g., `anthropic/claude-opus-4-6`). Model catalogs include built-in aliases and custom provider definitions.
|
|
|
|
### Sandbox Configuration
|
|
|
|
Optional Docker sandboxing isolates non-main sessions from the host system, with configurable scopes (session, agent, shared), workspace access levels, and optional browser support via Chromium and CDP.
|
|
|
|
### Thinking & Reasoning
|
|
|
|
`thinkingDefault` and `verboseDefault` control extended reasoning behavior, while `contextPruning` manages token usage by pruning old tool results before LLM requests.
|
|
|
|
## Session Management
|
|
|
|
Sessions can scope to per-sender, per-channel-peer, or per-account-channel-peer models. Reset policies support daily schedules and idle thresholds, with per-session-type overrides. Identity links map canonical IDs across channels for unified conversations.
|
|
|
|
## Tools & Access Control
|
|
|
|
Tool policies use allow/deny lists with group shorthands (`group:fs`, `group:runtime`, `group:sessions`). Elevated access requires explicit allowlisting by channel and sender. Per-agent tool restrictions further limit capabilities in multi-agent setups.
|
|
|
|
## Advanced Features
|
|
|
|
- **TTS**: Auto text-to-speech for outbound replies via ElevenLabs or OpenAI
|
|
- **Block Streaming**: Chunked message delivery for long responses
|
|
- **Typing Indicators**: Configurable modes (never, instant, thinking, message)
|
|
- **Heartbeats**: Periodic agent runs with optional memory flush before compaction
|
|
- **Skills**: Bundled and workspace skill management with per-skill configuration
|
|
- **Plugins**: Extension loading with allow/deny lists and per-plugin config
|
|
|
|
## Recommended Starting Configuration
|
|
|
|
```json5
|
|
{
|
|
agents: { defaults: { workspace: "~/.openclaw/workspace" } },
|
|
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
|
|
}
|
|
```
|