LeoYeAI/agent-master-skills / skills/bengii-gemini-fix
openclaw
FlaggedComprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.
references/config_reference.md
View on GitHub# OpenClaw Configuration Reference
Complete field-by-field reference for `~/.openclaw/openclaw.json`. This covers the most important configuration sections.
## Table of Contents
- [Config File](#config-file)
- [Gateway Section](#gateway-section)
- [Channels Section](#channels-section)
- [Agent Defaults](#agent-defaults)
- [Tools Section](#tools-section)
- [Session Section](#session-section)
- [Multi-Agent Routing](#multi-agent-routing)
- [Secrets Section](#secrets-section)
- [Environment Section](#environment-section)
- [Browser Section](#browser-section)
- [Plugins Section](#plugins-section)
- [Hooks Section](#hooks-section)
- [Cron Section](#cron-section)
- [Config Includes](#config-includes)
## Config File
Path: `~/.openclaw/openclaw.json` (JSON5 format)
Override via `OPENCLAW_CONFIG_PATH` env var.
### Config Validation
```bash
openclaw config validate # Validate config before gateway startup
openclaw config validate --json # Machine-readable output
openclaw config file # Print active config file path
```
If config is invalid:
- Gateway does not boot
- Only diagnostic commands work (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`)
- Run `openclaw doctor --fix` to apply repairs
## Gateway Section
```json5
{
gateway: {
mode: "local", // "local" (run gateway) | "remote" (connect to remote)
port: 18789, // Single multiplexed port for WS + HTTP
bind: "loopback", // "auto" | "loopback" (default) | "lan" | "tailnet" | "custom"
auth: {
mode: "token", // "none" | "token" | "password" | "trusted-proxy"
token: "your-token",
// password: "your-password",
allowTailscale: true, // Allow Tailscale Serve identity headers
rateLimit: {
maxAttempts: 10,
windowMs: 60000,
lockoutMs: 300000,
exemptLoopback: true, // Default true
},
},
tailscale: {
mode: "off", // "off" | "serve" | "funnel"
resetOnExit: false,
},
controlUi: {
enabled: true,
basePath: "/openclaw",
},
remote: { // For mode: "remote"
url: "ws://gateway.tailnet:18789",
transport: "ssh", // "ssh" | "direct"
token: "your-token",
},
trustedProxies: [], // IP addresses of trusted reverse proxies
reload: {
mode: "hybrid", // "off" | "hot" | "restart" | "hybrid"
debounceMs: 300,
},
http: {
securityHeaders: {
strictTransportSecurity: "max-age=63072000", // Optional HSTS for direct HTTPS
},
},
webhooks: { enabled: false }, // Enable inbound HTTP webhook endpoints
},
}
```
**Port precedence** (highest to lowest):
1. `--port` CLI flag
2. `OPENCLAW_GATEWAY_PORT` env var
3. `gateway.port` in config
4. Default: `18789`
**Auth notes:**
- Non-loopback binds REQUIRE auth
- `"trusted-proxy"`: delegate to identity-aware reverse proxy
- Rate limiter blocks per client IP, returns `429 + Retry-After`
**Config hot reload** (mode: `hybrid`):
- Hot-applies: `agents`, `models`, `routing`, `hooks`, `cron`, `session`, `messages`, `tools`, `browser`, `skills`, `audio`, `talk`, `ui`, `logging`, `identity`, `bindings`
- Requires restart: `gateway.*`, `discovery`, `canvasHost`, `plugins`, `gateway.reload`, `gateway.remote`, `channels.*`
**Container health probes** (built-in, always available):
- `GET /health`, `GET /healthz` — liveness check
- `GET /ready`, `GET /readyz` — readiness check
## Channels Section
### Per-Channel Config
```json5
{
channels: {
whatsapp: {
enabled: true,
dmPolicy: "pairing", // "pairing" | "allowlist" | "open" | "disabled"
allowFrom: ["+15551234567"],
groupPolicy: "allowlist", // "open" | "allowlist" | "disabled"
groupAllowFrom: ["+15551234567"],
groups: {
"*": { requireMention: true },
"123@g.us": { requireMention: false },
},
selfChatMode: true, // For personal number use
textChunkLimit: 4096,
sendReadReceipts: true,
},
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing",
allowFrom: ["tg:123"],
streaming: "partial", // Default changed to "partial" in v2026.3.2
// "off" | "partial" | "block" | "progress"
proxy: "socks5://user:pass@host:1080",
// Per-DM topic config (v2026.3.1+):
// direct: { allowlists, dmPolicy, skills, systemPrompt, requireTopic }
},
discord: {
enabled: true,
token: "bot-token",
dmPolicy: "pairing",
guilds: {
SERVER_ID: {
requireMention: true,
users: ["USER_ID"],
},
},
},
slack: {
enabled: true,
mode: "socket", // "socket" | "http"
appToken: "xapp-...",
botToken: "xoxb-...",
signingSecret: "...", // For HTTP mode
},
},
}
```
### Multi-Account (All Channels)
```json5
{
channels: {
telegram: {
accounts: {
personal: { botToken: "...", dmPolicy: "pairing" },
work: { botToken: "...", dmPolicy: "allowlist", allowFrom: ["tg:456"] },
},
},
},
}
```
## Agent Defaults
```json5
{
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: ["openai/gpt-5.2"],
},
imageModel: {
primary: "openai/dall-e-3",
},
pdfModel: { // v2026.3.2+: dedicated PDF model
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5-mini"],
},
pdfMaxBytesMb: 10, // Per-PDF size cap
pdfMaxPages: 20, // Max pages for extraction fallback
models: { // Model catalog + allowlist for /model
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
"openai/gpt-5.2": { alias: "GPT" },
},
imageMaxDimensionPx: 1200, // Image downscaling (reduces vision-token usage)
elevatedDefault: "off", // Default elevated mode: "off" | "on" | "ask" | "full"
heartbeat: {
every: "30m",
directPolicy: "allow", // "allow" | "block" — DM delivery for heartbeat
lightContext: false, // Lightweight bootstrap (only HEARTBEAT.md) for heartbeat runs
},
params: { // Per-agent params merged on top of model defaults
cacheRetention: 300, // Prompt cache TTL in seconds
},
compaction: { ... },
contextPruning: { ... },
sandbox: {
mode: "off", // "off" | "non-main" | "all"
scope: "session", // "session" | "agent" | "shared"
workspaceAccess: "none", // "none" | "ro" | "rw"
},
},
},
}
```
## Tools Section
```json5
{
tools: {
profile: "full", // "minimal" | "coding" | "messaging" | "full"
allow: [], // Explicit tool allow (if non-empty, everything else blocked)
deny: ["browser", "canvas"], // Block specific tools
byProvider: { // Per-model tool restrictions
"google-antigravity": { profile: "minimal" },
},
elevated: {
enabled: true,
allowFrom: {
whatsapp: ["+15555550123"],
},
},
exec: {
security: "allow", // "allow" | "ask" | "deny"
ask: "risky", // "always" | "risky" | "never"
backgroundMs: 10000,
timeoutSec: 1800,
},
fs: {
workspaceOnly: false, // Restrict to workspace directory
},
web: {
search: {
apiKey: "${BRAVE_API_KEY}",
},
},
},
}
```
### Tool Groups
| Group | Tools Included |
|---|---|
| `group:runtime` | exec, process, bash |
| `group:fs` | read, write, edit, apply_patch |
| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, session_status |
| `group:memory` | memory_search, memory_get |
| `group:web` | web_search, web_fetch |
| `group:ui` | browser, canvas |
| `group:automation` | cron, gateway |
| `group:messaging` | message |
| `group:nodes` | nodes |
## Session Section
```json5
{
session: {
dmScope: "main", // "main" | "per-channel-peer" | "per-account-channel-peer"
mainKey: "main", // Key for the main session
historyLimit: 100,
maintenance: {
maxDiskBytes: 500000000, // Session disk budget (500MB)
highWaterBytes: 400000000, // Trigger cleanup above this
},
},
}
```
## Multi-Agent Routing
```json5
{
agents: {
list: [
{ id: "main", workspace: "~/.openclaw/workspace" },
{ id: "work", workspace: "~/.openclaw/workspace-work",
model: { primary: "anthropic/claude-opus-4-6" },
tools: { profile: "coding" },
},
],
},
bindings: [
{ agentId: "work", match: { channel: "telegram", accountId: "work" } },
{ agentId: "main", match: { channel: "whatsapp" } },
],
}
```
### Binding Match Fields
- `channel` — channel name
- `accountId` — channel account ID
- `peer.kind` — `"direct"` or `"group"`
- `peer.id` — specific sender/group ID
## Secrets Section
See [references/secrets.md](secrets.md) for full details.
## Environment Section
```json5
{
env: {
OPENROUTER_API_KEY: "sk-or-...",
vars: { GROQ_API_KEY: "gsk-..." },
shellEnv: {
enabled: true, // Import shell env
timeoutMs: 15000,
},
},
}
```
## Browser Section
```json5
{
browser: {
executablePath: "/usr/bin/google-chrome",
// ... CDP config
},
}
```
## Plugins Section
```json5
{
plugins: {
allow: ["backups", "memory-lancedb-pro"], // Explicit allowlist
},
}
```
## Hooks Section
See [references/hooks.md](hooks.md) for full details.
```json5
{
hooks: {
enabled: true, // Enable HTTP webhook endpoints
token: "your-webhook-token",// Auth for webhooks
path: "/hooks", // Custom path prefix
dirs: ["/extra/hooks"], // Additional hook discovery dirs
},
}
```
## Cron Section
```json5
{
cron: {
jobs: [
{ schedule: "0 9 * * *", message: "Good morning!", channel: "whatsapp" },
],
webhookToken: "your-token", // Auth for webhook delivery mode
},
}
```
## Security Section
```json5
{
security: {
trust_model: {
multi_user_heuristic: true, // Flag likely shared-user ingress
},
},
}
```
## Update Section
```json5
{
update: {
auto: {
enabled: false, // Default off
// Stable: rollout delay+jitter; Beta: hourly cadence
},
},
}
```
```bash
openclaw update # Manual update
openclaw update --dry-run # Preview without mutating
```
## Config Includes
Split config across files using `$include`:
```json5
{
$include: ["./channels.json", "./agents.json"],
gateway: { ... },
}
```
### Env Var Substitution
- Syntax: `${VAR_NAME}` in config values
- Only uppercase names matched: `[A-Z_][A-Z0-9_]*`
- Missing/empty vars throw error at load time
- Escape with `$${VAR}` for literal output
- Works inside `$include` files
- Inline: `"${BASE}/v1"` → `"https://api.example.com/v1"`
### Secret Refs (env, file, exec)
```json5
{
models: {
providers: {
openai: {
apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
},
},
},
}
```
Sources: `env`, `file`, `exec`. See [secrets.md](secrets.md) for full details.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |