openclaw-optimizer

name

openclaw-optimizer

description

Optimize OpenClaw agent workspaces for security, performance, and usefulness. Use when (1) Setting up a new OpenClaw agent, (2) Improving an existing agent's behavior or performance, (3) Hardening security configuration, (4) Troubleshooting agent issues, (5) Choosing the right model for cost/performance, (6) Optimizing memory management, or (7) Creating workspace files (SOUL.md, AGENTS.md, USER.md, IDENTITY.md, HEARTBEAT.md).

OpenClaw Agent Optimizer

Optimize OpenClaw agents for security, performance, and usefulness based on canonical OpenClaw workspace architecture.

Quick Start

Optimizing an OpenClaw agent involves these sequential steps:

1. Run Security Audit — Validate security configuration with scripts/security_audit.py
2. Optimize Workspace Files — Configure SOUL.md, AGENTS.md, USER.md, IDENTITY.md
3. Set Up Memory System — Configure long-term memory and daily logging
4. Choose Model — Select appropriate model for use case and budget
5. Set Up Monitoring — Deploy health check and watchdog scripts

For detailed guidance on each step, read the corresponding reference file.

Workspace Structure (Canonical)

OpenClaw workspace = agent's "home" directory. Common files at workspace root:

• AGENTS.md — Operating instructions (how to behave, safety rules, memory workflow)
• SOUL.md — Persona, tone, boundaries
• IDENTITY.md — Name/vibe/emoji (short)
• USER.md — Who the user is + how to address them
• TOOLS.md — Local notes + conventions (NOT tool availability)
• HEARTBEAT.md — Optional heartbeat checklist (keep tiny)
• BOOTSTRAP.md — One-time first-run ritual; delete after completed
• MEMORY.md — Optional curated long-term memory (private sessions only)
• memory/YYYY-MM-DD.md — Daily logs
• skills/ — Optional workspace-specific skills

Important: Sub-agents do NOT receive full bootstrap files. Sub-agents only get AGENTS.md + TOOLS.md by default (not SOUL.md, USER.md, etc.).

Implication: If you delegate, ensure AGENTS.md contains cross-cutting safety and operating rules you need sub-agents to follow.

For complete workspace layout and best practices, read references/workspace-structure.md.

Optimization Workflows

New Agent Setup

For fresh OpenClaw installations:

1. Security First — Read references/security-hardening.md and apply all measures:

   • Gateway binding (loopback only)
   • Authentication tokens
   • File permissions (chmod 700)
   • Group chat settings (requireMention)

2. Run Security Audit — Execute the audit script:

   python3 scripts/security_audit.py
   

   Fix any issues before proceeding.

3. Create Workspace Files — Read references/workspace-templates.md and generate:

   • IDENTITY.md — Name, creature, vibe, emoji
   • SOUL.md — Persona, boundaries, vibe, operating stance
   • AGENTS.md — Session start, safety, memory workflow, group chats, delegation
   • USER.md — Name, preferred address, timezone, notes
   • HEARTBEAT.md — Keep empty or 1-5 checklist items only

4. Set Up Memory — Create MEMORY.md structure and configure daily logging

5. Choose Model — Read references/model-selection.md to select appropriate model:

   • Start with Sonnet (cost-effective)
   • Switch to Opus for complex tasks

6. Deploy Monitoring — Set up health check watchdog:

   # Test health check script
   python3 scripts/health_check.py
   
   # Set up LaunchAgent for continuous monitoring
   

Existing Agent Optimization

For agents that need improvement:

1. Identify Issues — Ask user about failure modes:

   • Verbosity problems?
   • Security concerns?
   • Performance issues?
   • Memory not working?
   • Group chat behavior?

2. Run Diagnostics:

   # Security check
   python3 scripts/security_audit.py
   
   # Health check
   python3 scripts/health_check.py
   

3. Apply Targeted Fixes — Based on issues identified:

   • Verbosity → Update SOUL.md with concise communication rules (see references/workspace-templates.md)
   • Security → Follow hardening guide in references/security-hardening.md
   • Performance → Check model selection in references/model-selection.md
   • Memory → Review memory management in references/workspace-templates.md
   • Group chats → Update AGENTS.md with group chat rules

4. Verify Fixes — Test agent behavior and re-run diagnostics

Troubleshooting Issues

When agent is not working properly:

1. Identify Symptoms — Read references/troubleshooting.md section matching the issue:

   • Agent silent (WhatsApp disconnects, gateway crashes)
   • Errors (API key, model overloaded)
   • Performance problems (slow responses, high costs)
   • Memory issues (agent forgets context)
   • Group chat problems (spamming, not responding)

2. Run Diagnostics:

   python3 scripts/health_check.py
   

3. Apply Solution — Follow specific fix from references/troubleshooting.md

4. Verify Recovery — Test agent and check logs

Reference Files

references/workspace-structure.md

Canonical OpenClaw workspace layout:

• Complete file structure with descriptions
• What NOT to store in workspace (secrets, credentials)
• Heartbeat rules and best practices
• Safety defaults (recommended)
• Sub-agent behavior and implications

Read when: Understanding OpenClaw workspace architecture, setting up new agent, or troubleshooting workspace issues.

references/workspace-templates.md

File templates and best practices:

• IDENTITY.md template (short)
• SOUL.md template (persona + boundaries)
• AGENTS.md template (operating instructions)
• USER.md template (user profile)
• HEARTBEAT.md template (keep tiny)
• Optimization patterns for common issues

Read when: Creating or updating workspace files, configuring agent personality, or improving behavior.

references/security-hardening.md

Comprehensive security guide covering:

• Gateway security (binding, authentication)
• Network security (Tailscale, shared networks)
• Group chat security
• Prompt injection defense
• Crash recovery setup
• Security audit checklist

Read when: Setting up new agent, experiencing security concerns, or during periodic security reviews.

references/troubleshooting.md

Solutions for common issues:

• WhatsApp disconnects
• Gateway crashes
• API key problems
• Model errors
• Memory issues
• Group chat problems
• Performance issues
• Security concerns
• Debugging tools and commands

Read when: Agent is not working, experiencing errors, or debugging issues.

references/model-selection.md

Guidance on choosing models:

• Claude Opus vs Sonnet comparison
• Cost optimization strategies
• Performance considerations
• Model switching procedures
• API key options
• Usage patterns and recommendations

Read when: Setting up new agent, experiencing high costs, or optimizing performance.

Scripts

scripts/security_audit.py

Validates OpenClaw configuration for security best practices:

• Gateway binding check
• Authentication verification
• File permissions audit
• Group chat settings check
• Memory security scan
• API key storage validation

Usage:

python3 scripts/security_audit.py

Run when: After initial setup, periodically for security maintenance, or when making config changes.

scripts/health_check.py

Monitors gateway health and auto-restarts if needed:

• Health endpoint checking
• Process verification
• Automatic restart on failure
• Notification support
• Health logging

Usage:

# One-time check
python3 scripts/health_check.py

# Continuous monitoring (via LaunchAgent)
# See references/troubleshooting.md for setup instructions

Run when: Gateway issues suspected, or set up for continuous monitoring via LaunchAgent.

Safety Defaults (Recommended)

Apply these rules by default:

• Never run destructive/state-changing actions without explicit permission
• Never send outbound messages/emails/posts unless explicitly asked
• Prefer trash over rm
• Stop on CLI usage errors; run --help and correct
• In group chats: don't be the user's voice; respond only when mentioned or clearly useful

Ensure these are documented in AGENTS.md since sub-agents only receive that file by default.

Optimization Patterns

Reducing Verbosity

Add to SOUL.md:

**Be genuinely helpful, not performatively helpful.**
Skip the "Great question!" and "I'd be happy to help!"
Just help. Actions speak louder than filler words.

**Be concise.** Default to the shortest response that's complete.
If I need more detail, I'll ask.

Improving Decision Making

Add to AGENTS.md:

**When uncertain:**
1. List 2-3 options with tradeoffs
2. Make a recommendation
3. Ask if I want to proceed or choose differently

Better Context Use

Add to AGENTS.md:

**Before asking questions:**
1. Check MEMORY.md for relevant history
2. Search existing files and docs
3. Review recent conversation history
4. Then ask if still uncertain

Group Chat Behavior

Add to AGENTS.md:

## Group chats

- You are a participant, not the user's voice
- Reply only when mentioned or when value is high
- Don't reveal private workspace contents in shared/group chats

Memory Hygiene

Add to AGENTS.md:

## Memory workflow

- Daily log: `memory/YYYY-MM-DD.md` (raw session notes)
- Long-term: `MEMORY.md` (decisions, preferences, durable facts)
- In private main sessions only: read `MEMORY.md` if present