Gateway
Configuration — agents
Agent-scoped configuration keys under agents.*, multiAgent.*, session.*,
messages.*, and talk.*. For channels, tools, gateway runtime, and other
top-level keys, see Configuration reference.
OpenClaw stamps agents.ownership: "explicit" when creating a multi-agent fleet. Such fleets have no default: channels and ambient services need bindings or surface-specific agentId targets. Doctor materializes legacy owners during upgrade; sole-agent configs need no marker.
On a fresh install, interactive onboarding asks for the first agent's name and
uses main as the suggested value. Automated onboarding keeps the historical
main default unless you pass openclaw onboard --non-interactive --agent-name <name> .... A sole named agent uses the same default workspace and shared auth
store as main; onboarding also migrates legacy agent:main:* session history
to that sole owner before it finishes.
main is an ordinary agent id. Reusing it after a named agent owns the install
is guarded so old data is never silently adopted: legacy-session-migration-required
means openclaw doctor --fix must finish or quarantine legacy agent:main:*
claims, while shared-auth-store-owned-by-main means Doctor must first relocate
the shared auth store into state/openclaw.sqlite. After both repairs, the new
main gets fresh agent-scoped session and auth storage like any other agent.
What each page covers
- Configuration — agent workspace and bootstrap — workspace, cwd, repo root, skills, bootstrap injection, context budgets, images, and timezone.
- Configuration — agent models —
agents.defaults.model, fallback chains, per-purpose model slots, and model selection scope. - Configuration — agent runtime and CLI backends — runtime policy on providers and models, CLI backend selection, and GPT-5 personality.
- Configuration — agent heartbeat, compaction, and streaming — heartbeat runs, the system agent, compaction, context pruning, block streaming, and typing indicators.
- Configuration — agent sandboxing — the
agents.defaults.sandboxblock: image, workspace mode, mounts, and network policy. - Configuration — per-agent entries and multi-agent routing —
agents.entriesoverrides,multiAgentbindings, binding match fields, and access profiles. - Configuration — agent sessions —
session.*scope, identity links, reset policy, sharing, and retention. - Configuration — messages and talk —
messages.*delivery, prefixes, ack reactions, queueing, TTS, andtalk.*defaults.
Where each section moved
Every heading this page used to publish keeps its anchor here, so an existing
link such as /gateway/config-agents#agents.defaults.model still resolves. Each
entry points at the page that now holds the content.
- Agent defaults
agents.defaults.workspaceagents.defaults.cwdagents.defaults.repoRootagents.defaults.skillsagents.defaults.skipBootstrapagents.defaults.skipOptionalBootstrapFilesagents.defaults.contextInjectionagents.defaults.bootstrapMaxCharsagents.defaults.bootstrapTotalMaxChars- Per-agent bootstrap profile overrides
- Bootstrap truncation notice
- Context budget ownership map
agents.defaults.startupContextagents.defaults.contextLimitsagents.entries.*.contextLimitsskills.limits.maxSkillsPromptCharsagents.entries.*.skillsLimits.maxSkillsPromptCharsagents.defaults.imageMaxDimensionPxagents.defaults.imageQualityagents.defaults.userTimezoneagents.defaults.modelagents.defaults.modelSelectionScopeagents.defaults.modelSelectionScope- Runtime policy
- CLI backend selection
- OpenAI GPT-5 personality
agents.defaults.heartbeatagents.defaults.systemAgentagents.defaults.compactionagents.defaults.contextPruning- cache-ttl mode behavior
- Block streaming
- Typing indicators
agents.defaults.sandboxagents.defaults.sandbox- Sandbox details
agents.entries(per-agent overrides)agents.entries(per-agent overrides)- Multi-agent routing
- Binding match fields
- Per-agent access profiles
- Full access (no sandbox)
- Read-only tools + workspace
- No filesystem access (messaging only)
- Session
- Session field details
- Messages
- Response prefix
- Ack reaction
- Queue
- Inbound debounce
- Other message keys
- TTS (text-to-speech)
- Talk
Related
- Configuration reference — all other config keys
- Configuration — common tasks and quick setup
- Configuration examples
- Model providers — provider setup and model catalogs
- Agent bindings — how channel accounts and users select an agent
- Configuration — channels — the matching
channels.*reference
