Battle-tested optimizations for OpenClaw instances. Reduce token costs, fix capability gaps, tune performance, harden security.

The Token Cost Formula

Every workspace file loaded at session start multiplies across every call. Keep them lean.

Step 1 — Audit Current State

# Check workspace file token usage (macOS/Linux)
for f in AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md MEMORY.md; do
  p="$HOME/.openclaw/workspace/$f"
  [ -f "$p" ] && echo "$f : ~$(($(wc -c < "$p") / 4)) tokens"
done
cat ~/.openclaw/openclaw.json

Step 2 — SOUL.md Core Constraints

Ensure these principles are present in SOUL.md. They are system-level behavioral guarantees, not style preferences:

🔒 安全与渠道原则（必须加入 SOUL.md）

📝 Markdown 规范（必须加入 SOUL.md）

禁用 ASCII 图 · 流程图用 Mermaid · 对比用表格 · 标题加 emoji · Mermaid 换行用


Step 3 — Slim Down Workspace Files

Target: AGENTS.md ≤ 300 tokens · SOUL.md ≤ 600 tokens · MEMORY.md ≤ 2000 tokens

内容完整比 token 少更重要。安全原则、行为约束等实质性规则不应为省 token 而删减。

• AGENTS.md — keep only: session startup flow, memory structure, WAL protocol, safety rules. Remove duplicates already covered by system prompt (group chat, proactive work, etc.)
• SOUL.md — compress to concise bullet points
• MEMORY.md — remove outdated entries
• Periodically clean memory/YYYY-MM-DD.md logs older than 30 days

Saving 1000 tokens = ~$45/month at Sonnet × 100 calls/day.

Step 3 — Key openclaw.json Settings

⚠️ heartbeat.quiet is not supported — throws Unrecognized key error. Do not add it.
⚠️ tools.profile must be "full". Defaults (coding / messaging) silently disable most tools.
⚠️ Set contextPruning.ttl to match heartbeat.every (both "55m") to keep cache warm.

Step 4 — Security Hardening

Checklist

Enable macOS Application Firewall

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate on
# Verify:
/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

Trade-off: First run of any new app that listens on a port will trigger a system dialog. Allow or deny as needed. Can be disabled anytime:

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off

Fix config file permissions if needed

chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/credentials

Step 5 — Essential Skills

# Proactive behavior + self-improvement
npx skills add halthelobster/proactive-agent@proactive-agent -g -y

Avoid:

• bdi-mental-states — academic only, not useful for personal assistants
• autonomous-agents — reference manual, limited practical value

Optional (after memory files exceed 5000+ tokens):

npm install -g https://github.com/tobi/qmd

Step 6 — Model Switching

/model opus    # Switch to Opus (complex / reasoning tasks)
/model sonnet  # Switch back to Sonnet (daily use)

Set model aliases in openclaw.json:

"agents": {
  "defaults": {
    "models": {
      "amazon-bedrock/global.anthropic.claude-opus-4-6-v1": { "alias": "opus", "params": { "cacheRetention": "long" } },
      "amazon-bedrock/global.anthropic.claude-sonnet-4-6": { "alias": "sonnet", "params": { "cacheRetention": "long" } }
    }
  }
}

Step 7 — Verify

# macOS/Linux
node -e "const fs=require('fs'); eval('('+fs.readFileSync(process.env.HOME+'/.openclaw/openclaw.json','utf8')+')'); console.log('Config valid ✅')"

Check Prompt Cache hit rate after a few conversations with /status.

Priority Order (highest impact first)

• tools.profile → full (broken without this)
• SOUL.md core constraints (读懂阶段再动手 / 脚本优先 / API 优先 / 做完才说完)
• SOUL.md 安全与渠道原则 (渠道可信度 / 注入防御 / 安全红线)
• Slim workspace files
• Prompt Caching (cacheRetention: long)
• Gemini web search (fixes search)
• Gemini embeddings (fixes non-English memory recall)
• Security hardening (firewall + permissions audit)
• Context Pruning + Compaction (ttl aligned to heartbeat)
• Install proactive-agent
• qmd (after files accumulate)