openclaw-config

Files (53)

• SKILL.md
• auth-credential-semantics.md · references/
• authentication.md · references/
• background-process.md · references/
• bonjour.md · references/
• bridge-protocol.md · references/
• cli-backends.md · references/
• config-agents.md · references/
• config-channels.md · references/
• config-tools.md · references/
• configuration-reference.md · references/
• configuration.md · references/
• diagnostics.md · references/
• discovery.md · references/
• doctor.md · references/
• environment.md · references/
• external-apps.md · references/
• gateway-config.md · references/
• gateway-index.md · references/
• gateway-lock.md · references/
• gateway-troubleshooting.md · references/
• health.md · references/
• heartbeat.md · references/
• index.md · references/
• local-model-services.md · references/
• local-models.md · references/
• logging.md · references/
• model-failover.md · references/
• multiple-gateways.md · references/
• network-model.md · references/
• network-proxy.md · references/
• oauth.md · references/
• openshell.md · references/
• operator-scopes.md · references/
• pairing.md · references/
• prompt-caching.md · references/
• protocol.md · references/
• remote-gateway-readme.md · references/
• remote-gateway.md · references/
• remote.md · references/
• retry.md · references/
• sandboxing.md · references/
• secretref-credential-surface.md · references/
• secrets-plan-contract.md · references/
• secrets.md · references/
• security.md · references/
• audit-checks.md · references/security/
• index.md · references/security/
• tailscale.md · references/
• timezone.md · references/
• tools-invoke-http-api.md · references/
• trusted-proxy-auth.md · references/
• usage-tracking.md · references/

SKILL.md (first lines)

## Routing hints

You should route to this skill when the user asks about any OpenClaw config key, the `openclaw.json` schema, `~/.openclaw/openclaw.json` location, secrets management, `SecretRef` references, authentication, auth profiles, model failover, retry policy, gateway config, or any field-by-field configuration question. References: `configuration-reference.md`, `gateway-config.md`, `secrets.md`, `authentication.md`, `config-agents.md`, `config-channels.md`, `config-tools.md`, `retry.md`, `model-failover.md`, `protocol.md`, `cli-backends.md`, `doctor.md`, `operator-scopes.md`, `secretref-credential-surface.md`, `prompt-caching.md`, `timezone.md`.


# OpenClaw Config Reference

Complete reference for `~/.openclaw/openclaw.json`.

## Quick cheatsheet

```json5
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "provider/model", fallbacks: [] },
      memorySearch: { provider: "openai" },
      subagents: { maxConcurrent: 3, runTimeoutSeconds: 300 },
      contextPruning: { mode: "cache-ttl" },
    },
    list: [{ id, model, bindings, skills, runtime: { type: "acp" } }]
  },
  memory: { backend: "builtin", citations: "auto" },
  plugins: { slots: { memory: "openclaw-honcho" }, entries: {} },
  channels: { discord: { token: "BOT", dmPolicy: "pairing" } },
  tools: { profile: "coding", elevated: { enabled: false } },
  session: { scope: "per-sender", dmScope: "main" },
  env: { vars: {} }
}
```

## Critical defaults (safety)

| Feature | Default | Risk if enabled accidentally |
|---------|---------|----------------------------|
| `tools.loopDetection` | `false` | Infinite loops run forever |
| `execApprovals` | not set | Any user can trigger exec |
| `session.maintenance.enforce` | not set | Sessions grow unbounded |

## Common fixes

**Honcho as memory (most common misconfig):**
```json5
plugins: {
  slots: { memory: "openclaw-honcho" },
  entries: { "openclaw-honcho": { enabled: true, config: { baseUrl: "http://127.0.0.1:8000" } } }
}
```
Restart required. Do NOT set `memory.backend` — the slot override handles it.

**Discord bot silent:**
- `dmPolicy: "pairing"` — approve via `openclaw pairing approve discord <CODE>`
- `allowFrom` must include your Discord user ID
- Enable Message Content Intent in Discord Developer Portal

## Config editing

**`config.patch`** (preferred — partial merge):
```javascript
gateway(action: "config.patch", raw: "{ channels: { telegram: { enabled: true } } }", baseHash: "<hash>")
```
- Objects merge recursively
- `null` deletes a key
- Arrays replace entirely

**`config.apply`** (full replacement — use sparingly)

**Hot reload:** Gateway watches `~/.openclaw/openclaw.json` and auto-reloads. Restart required for: `memory.backend`, `plugins.slots`, `agents.defaults.*`.

**Rate limit:** 3 config writes per 60 seconds per device.

## Secrets

Use SecretRefs instead of plaintext:
```json5
{ apiKeyRef: "secret:my-key" }
```
Stored under `~/.openclaw/credentials/`. Startup fails fast on unresolved refs.

## Restart triggers

| Require restart | Hot-reload only |
|----------------|-----------------|
| `memory.backend` | `tools.web.search.apiKey` |
| `plugins.slots` | `agents.defaults.memorySearch.remote` |
| `agents.defaults.*` | Channel `enabled` |
| `session.identityLinks` | Most other changes |

## References

- `references/gateway-config.md` — full config reference (all keys)
- `references/secrets.md` — SecretRef details
- `references/config-channels.md` — channel config
- `openclaw-memory/references/memory-config.md` — memory knobs
- `openclaw-concepts/references/session.md` — session system
- `openclaw-troubleshooting/references/diagnostic-flowchart.md` — triage

From Hashi-Ai-Dev/openclaw-clawdoc, MIT.

More from Hashi-Ai-Dev/openclaw-clawdoc