Advanced OpenClaw Configuration and Automation Ops Guide

Chapter 1: Production Configuration Principles

OpenClaw’s configuration system consists of three layers that override each other from top to bottom: the user configuration file ~/.openclaw/openclaw.json (JSON5 format), workspace configuration files ( SOUL.md, USER.md, AGENTS.md, IDENTITY.md) and runtime overrides via the /config command. The CLI flag --config, the OPENCLAW_CONFIG environment variable, and the default file path are consulted in that order.

To verify the loading order, run:

openclaw gateway --verbose 2>&1 | grep -i "config\|workspace\|load"

The command prints each configuration source as it is applied.

Chapter 2: Gateway Operations

The Gateway is the core process that maintains long‑lived connections to all message channels. It listens on port 18789 by default and supports a priority order for port selection: CLI --port, OPENCLAW_GATEWAY_PORT environment variable, gateway.port in the config file, and finally the default 18789.

Authentication is mandatory; the default mode is token with a secret token defined in gateway.auth.token. For secure deployments, bind the Gateway to loopback and enable token authentication.

Hot‑reload modes: hybrid: Agent configuration reloads automatically, but a port change requires a manual restart. hot: All configuration reloads without any restart. restart: The Gateway restarts automatically after a config change. off: All changes require a manual restart.

Safe restart procedure (to avoid message loss):

# 1. Check current status
openclaw gateway status
# 2. Ensure no running cron jobs
openclaw cron list
# 3. Optionally wait for in‑flight tasks
sleep 30
# 4. Restart the Gateway
openclaw gateway restart
# 5. Verify health and status
openclaw gateway health
openclaw gateway status

Systemd service example (ensures automatic restart, minimal privileges, and directory isolation):

[Unit]
Description=OpenClaw Gateway Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=openclaw
Group=openclaw
ExecStart=/usr/local/bin/openclaw gateway start --verbose
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
Environment=OPENCLAW_GATEWAY_PORT=18789

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/openclaw /var/log/openclaw
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Chapter 3: Cron Scheduling and Automation

OpenClaw’s built‑in cron system supports three schedule types: at: One‑time execution at a specific ISO‑8601 timestamp (e.g., 2026-03-20T16:00:00+08:00). every: Fixed‑interval looping tasks defined by everyMs (e.g., 3600000 for hourly). cron: Full cron expression (five‑field syntax) with optional tz for time‑zone.

Example of a daily news summary using the cron type:

{
  "name": "Daily Briefing",
  "schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "Asia/Shanghai" },
  "payload": { "kind": "agentTurn", "message": "Generate a 5‑item tech news summary using model haiku." },
  "sessionTarget": "isolated",
  "delivery": { "mode": "announce", "channel": "telegram", "to": "user:123456789" }
}

Execution modes for payloads: systemEvent (main session injection, suitable for notifications). agentTurn (isolated session, suitable for tasks that need a fresh agent context).

Valid sessionTarget / payload.kind combinations are enforced; invalid combos cause a runtime error.

Chapter 4: Memory Management and Compaction

OpenClaw mitigates the “forgetting” problem of large language models with a Compaction mechanism. When the total token count approaches the model’s context window, the system automatically compresses older dialogue into a summary while preserving the most recent reserveTokensFloor tokens (default 20 000).

Compaction configuration example:

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "strategy": "default"
      }
    }
  }
}

Memory‑flush (pre‑compaction persistence) can be enabled to write important information to files before compression. Recommended settings:

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000
        }
      }
    }
  }
}

Manual compaction can be triggered with the slash command:

/compact Keep key technical decisions and architecture discussions

The memory hierarchy includes:

Index layer : MEMORY.md – core capabilities and quick links.

Project layer : memory/projects.md – status and TODOs per project.

Infrastructure layer : memory/infra.md – server and API details.

Lesson layer : memory/lessons.md – documented pitfalls.

Log layer : daily files memory/YYYY-MM-DD.md – structured logs with fields Conclusion , File Changes , Lesson , and tags.

Chapter 5: Multi‑Channel Integration

Discord Bot Setup – steps: create an application, enable “MESSAGE CONTENT INTENT”, generate a token, set permissions (Send Messages, Read History, Add Reactions, Use Slash Commands), invite the bot, and add the token to channels.discord.token. Example config snippet:

{
  "channels": {
    "discord": {
      "token": "your-bot-token",
      "allowFrom": ["server:123456789"],
      "ackReaction": "👀",
      "guilds": {
        "123456789": { "historyLimit": 20, "textChunkLimit": 2000 }
      }
    }
  }
}

Common Discord issues (Bot online but silent) are usually caused by a missing MESSAGE CONTENT INTENT.

Telegram Bot Setup – create a bot via @BotFather, obtain the token, retrieve your user ID (e.g., via @userinfobot), and configure:

{
  "channels": {
    "telegram": {
      "botToken": "123456:ABCdef...",
      "allowFrom": ["123456789"],
      "dm": { "enabled": true, "policy": "pairing" },
      "historyLimit": 50,
      "replyToMode": "first",
      "linkPreview": true,
      "streamMode": "partial"
    }
  }
}

DM policies: pairing (requires explicit pairing), allowlist, open, disabled.

When both Discord and Telegram are configured, OpenClaw automatically routes replies back to the originating channel.

Message Routing Rules – each incoming message carries a channel identifier; the routing engine matches it against bindings to select the appropriate Agent. Multi‑Agent bindings can be defined per channel or per account ID.

Chapter 6: Configuration Quick‑Reference and Troubleshooting

Key Gateway Settings gateway.port: 18789 (default) gateway.bind: loopback (recommended for production) gateway.auth.mode:

token

gateway.auth.token

: must be set in production gateway.reload.mode: hybrid Agent Defaults agents.defaults.workspace:

~/.openclaw/workspace

agents.defaults.model.primary

: e.g.,

provider/claude-sonnet-4

agents.defaults.compaction.reserveTokensFloor

: 20000 agents.defaults.compaction.memoryFlush.enabled: true agents.defaults.heartbeat.every:

30m

agents.defaults.heartbeat.activeHours

: {"start":"08:00","end":"23:00"} Common Failure Scenarios

Gateway fails to start : check JSON5 syntax with openclaw doctor, verify the port is free ( ss -tlnp | grep 18789), ensure the auth token is present, and examine journalctl -u openclaw-gateway for errors.

Channel bot does not respond : confirm the required intents (Discord) or token validity (Telegram), verify allowFrom includes the sender, and check channel permissions.

Cron job not firing : ensure the tz field is set, the job is enabled, and delivery.mode is not none. Use openclaw cron list and openclaw cron runs --id <ID> to inspect history.

AI loses context : verify memoryFlush.enabled and softThresholdTokens, confirm that MEMORY.md and daily logs exist, and look for “Auto‑compaction complete” in verbose logs.

Verification Checklist

Run openclaw gateway restart after any config change and confirm no errors in the journal.

Execute openclaw gateway status --deep to see channel health, CPU, memory, and disk usage.

Test a cron task manually with openclaw cron run --id <ID> --force.

Collect logs for evidence:

openclaw logs --since "2026-03-20 10:00:00" --until "2026-03-20 12:00:00" > /tmp/gateway-logs.txt

.

Backup & Rollback

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup-$(date +%Y%m%d-%H%M%S)

To restore, copy the backup file back and restart the Gateway.

Appendix: Vector Search Configuration

OpenClaw’s memorySearch uses semantic vectors. For Chinese‑centric workloads, the free SiliconFlow BAAI/bge-m3 model is recommended:

{
  "memorySearch": {
    "enabled": true,
    "provider": "openai",
    "remote": {
      "baseUrl": "https://api.siliconflow.cn/v1",
      "apiKey": "your-siliconflow-api-key"
    },
    "model": "BAAI/bge-m3"
  }
}

The model is 1024‑dimensional, free, and performs well on both English and Chinese semantic queries.

Best practices for high recall:

Use a consistent tag system (e.g., #deploy, #config, #bug) in log entries.

Place core keywords at the beginning of titles.

Keep conclusions self‑contained so they can be retrieved without reading the full log.

Run periodic maintenance cron (weekly) to prune old logs and synthesize summaries.

Example maintenance task:

{
  "name": "Memory Maintenance",
  "schedule": { "kind": "every", "everyMs": 604800000 },
  "payload": { "kind": "agentTurn", "message": "Read the last 7 days of logs, extract valuable info into projects.md and lessons.md, compress completed one‑off logs, delete stale entries, and update heartbeat-state.json." },
  "sessionTarget": "isolated",
  "delivery": { "mode": "none" }
}

The state file memory/heartbeat-state.json tracks the last maintenance date.

By following the configurations, command examples, and troubleshooting steps above, engineers can reliably deploy OpenClaw in production, maintain high‑availability services, and keep AI agents contextually aware over long periods.