openclaw.json Configuration Validation
Validate openclaw.json against the official OpenClaw documentation and check for latest features, deprecated settings, and optimal configurations.
Official Documentation Sources
When validating configuration, fetch the latest information using the docs-research skill — it holds the tool-priority ladder (Firecrawl → Exa → Perplexity → Jina → context7 → WebFetch) and the canonical OpenClaw documentation URL map (docs site, source/changelog, skills examples).
Always verify against official docs before recommending changes. OpenClaw evolves — features may be added or deprecated.
Validation Checklist
1. Structure Validation
Verify top-level sections exist and are well-formed:
{
"agents": { ... }, // Required
"channels": { ... }, // At least one channel needed
"tools": { ... }, // Recommended
"plugins": { ... }, // Optional
"session": { ... } // Optional
}
2. agents.defaults
| Field |
Check |
Severity |
model |
Is it set? Is the model name valid and current? |
HIGH |
workspace |
Defaults to ./workspace — verify path exists |
MEDIUM |
bootstrapMaxChars |
Default 20000. Warn if > 50000 (token cost) |
LOW |
bootstrapTotalMaxChars |
Default 150000. Warn if > 300000 |
LOW |
userTimezone |
Is it set? Valid IANA timezone? |
MEDIUM |
timeoutSeconds |
Default 600. Warn if > 1800 |
LOW |
maxConcurrent |
Default 3. Check based on usage |
LOW |
contextTokens |
Should match model's context window |
MEDIUM |
thinkingDefault |
Valid values: off/minimal/low/medium/high/adaptive |
LOW |
3. agents.defaults.heartbeat
| Field |
Check |
Severity |
every |
Is interval reasonable? (5m-1h typical) |
MEDIUM |
model |
Using a cheap model? (gpt-4o-mini, haiku recommended) |
MEDIUM |
lightContext |
Should be true for token efficiency |
LOW |
isolatedSession |
Recommended true to avoid session pollution |
LOW |
4. agents.defaults.compaction
| Field |
Check |
Severity |
memoryFlush |
Should be true for agents with memory |
MEDIUM |
reserveTokensFloor |
8000 is recommended minimum |
LOW |
5. agents.list[]
| Field |
Check |
Severity |
id |
Each agent has a unique ID? |
HIGH |
default |
Exactly one agent is default? |
HIGH |
identity |
Name, emoji set? |
LOW |
sandbox.mode |
Set for untrusted environments? |
MEDIUM |
6. channels.*
For each configured channel (telegram, discord, whatsapp):
| Field |
Check |
Severity |
enabled |
Is it intentionally enabled/disabled? |
MEDIUM |
botToken / token |
Uses SecretRef pattern? (see security-audit skill) |
CRITICAL |
dmPolicy |
Not "open" in production? Prefer "allowlist" |
HIGH |
allowFrom |
Matches USER.md profiles? |
MEDIUM |
groups / guilds |
Per-group config set for each group? |
LOW |
historyLimit |
Reasonable value? (20-100) |
LOW |
7. tools
| Field |
Check |
Severity |
profile |
Appropriate for use case? full needs justification |
MEDIUM |
deny |
Dangerous tools blocked? |
MEDIUM |
exec.timeoutSec |
Not too high (< 3600 recommended) |
LOW |
loopDetection.enabled |
true for production |
HIGH |
8. plugins
| Field |
Check |
Severity |
enabled |
Plugin system active? |
LOW |
entries |
Each plugin has valid config? |
MEDIUM |
entries.*.env |
Uses env vars for secrets? |
HIGH |
9. session
| Field |
Check |
Severity |
dmScope |
Appropriate? Options: main/per-peer/per-channel-peer/per-account-channel-peer |
LOW |
reset.mode |
Set to "daily"? (only valid value) |
LOW |
reset.atHour |
Reasonable reset hour? (default 4) |
LOW |
reset.idleMinutes |
Reasonable idle timeout? |
LOW |
resetTriggers |
Includes /new or /reset? |
LOW |
maintenance.mode |
"warn" or "enforce"? |
LOW |
Cross-Validation with Workspace Files
| openclaw.json |
Workspace File |
Check |
channels.*.allowFrom IDs |
USER.md |
Every ID in allowFrom has a profile in USER.md |
agents.defaults.model |
TOOLS.md |
Model-specific tool notes exist |
channels.telegram.groups |
AGENTS.md |
Group chat rules exist for each group |
agents.defaults.heartbeat |
HEARTBEAT.md |
Heartbeat config aligns with HEARTBEAT.md tasks |
agents.defaults.userTimezone |
USER.md |
Timezone matches user profile |
plugins.entries |
AGENTS.md |
Plugin-specific behavior rules exist |
Feature Freshness Check
After fetching latest docs, check for:
- New config fields not present in current config
- Deprecated fields that should be migrated
- New channel types available but not configured
- New tool profiles or options
- New compaction strategies or memory features
- Model updates — newer models available
Validation Report Template
# openclaw.json Validation Report
## Config Summary
- Model: [primary model]
- Channels: [list of enabled channels]
- Tools profile: [profile]
- Heartbeat: [interval] with [model]
## Validation Results
### CRITICAL
- [ ] [Issue + recommendation]
### HIGH
- [ ] [Issue + recommendation]
### MEDIUM
- [ ] [Issue + recommendation]
### LOW / Suggestions
- [ ] [Optional improvement]
## Cross-Validation
- [ ] USER.md ↔ allowFrom: [match/mismatch]
- [ ] HEARTBEAT.md ↔ heartbeat config: [aligned/misaligned]
- [ ] AGENTS.md ↔ group configs: [covered/missing]
## Feature Freshness
- [ ] Current version features: [all used / N missing]
- [ ] Deprecated settings: [none / list]
- [ ] Recommended additions: [list]
Best Practices
- Always validate after editing openclaw.json
- Run
openclaw doctor --fix after changes (Docker multi-instance: openclaw-{name} doctor --fix)
- Check official docs for latest features quarterly
- Keep model names current — use
provider/model format (e.g. anthropic/claude-sonnet-4-20250514)
- Use
allowlist dmPolicy in production
- Enable loopDetection for stability
- Set heartbeat to a cheap model, configure
heartbeat.target
- Match userTimezone to primary user's location
- Verify
agent.skipBootstrap path (singular agent, NOT agents.defaults.skipBootstrap)
- Cron jobs are managed via CLI, config only has
cron.enabled
agents-store