第16章 Production Case Studies

"Theory is when you know everything but nothing works. Practice is when everything works but no one knows why. We've combined theory and practice: nothing works and no one knows why."

The OpenClaw project has been deployed in hundreds of production environments since its inception as a personal learning experiment. Each deployment reveals patterns—some successful, some painful—that inform how we think about running AI assistants at scale. This chapter presents real case studies from production deployments, extracts the lessons learned, and gives you the principles to apply to your own setup.

Case Study: Personal Assistant

The most common OpenClaw deployment is also the simplest: a single user running the assistant for personal productivity. But "simple" doesn't mean "without pitfalls."

The Setup

A software engineer we'll call Alex set up OpenClaw to manage her development workflow, personal notes, and home automation. Her deployment ran on a Mac mini that stayed on 24/7, serving channels across WhatsApp, Telegram, and Discord.

The configuration started minimal:

# ch-16-code1.yaml
identity:
  name: "Jarvis"
  theme: "helpful assistant"
  emoji: "🤖"

agent:
  workspace: "~/.openclaw/workspace"
  model:
    primary: "anthropic/claude-sonnet-4-6"
    fallbacks: ["openai/gpt-5.4"]

channels:
  telegram:
    enabled: true
    botToken: "${TELEGRAM_BOT_TOKEN}"
    allowFrom: ["123456789"]
    groups:
      "*":
        requireMention: true

  discord:
    enabled: true
    token: "${DISCORD_BOT_TOKEN}"
    dm:
      enabled: true
      allowFrom: ["123456789012345678"]
    guilds:
      "987654321098765432":
        slug: "personal-server"
        requireMention: false
        channels:
          general:
            allow: true
          ai-experiments:
            allow: true

tools:
  allow: ["exec", "read", "write", "edit"]
  elevated:
    enabled: true
    allowFrom:
      telegram: ["123456789"]
      discord: ["123456789012345678"]

What Went Wrong

Three months in, Alex noticed her sessions were becoming confused. Conversations from her coding Discord channel were bleeding context into home automation requests made via WhatsApp. The assistant would reference code variables when asked to turn off the lights.

The root cause was session scope configuration. By default, OpenClaw uses scope: "per-channel-peer", which creates separate sessions per channel. But Alex hadn't configured channel-specific session isolation, and her automated scripts were all hitting the same session.

The Fix

The solution involved explicit session scoping and channel-specific routing:

session:
  scope: "per-channel-peer"  # [1]
  dmScope: "per-channel-peer"  # [2]
  reset:
    mode: "daily"
    atHour: 4
    idleMinutes: 60

agents:
  defaults:
    skills: ["github", "obsidian", "weather"]
  list:
    - id: "main"
      default: true
      # Inherits default skills
    - id: "home"
      skills: ["homekit"]
      thinkingDefault: "low"  # [3]
    - id: "coding"
      skills: ["github", "coding-agent"]
      thinkingDefault: "high"  # [4]
      reasoningDefault: "on"

tools:
  allow: ["exec", "read", "write", "edit", "process"]
  exec:
    timeoutSec: 300
    backgroundMs: 10000

🤿 深入底层：The scope: "per-channel-peer" setting creates a separate session for each unique (channelId, peerId) tuple. This means DMs from WhatsApp, Telegram, and Discord all maintain separate context. The dmScope configuration specifically handles direct messages, while group chats follow their own isolation rules.

Patterns for Similar Deployments

Personal assistant deployments share several common patterns:

Pattern	Why It Matters	Configuration
Channel isolation	Prevents context bleeding between work and personal contexts	`session.scope: "per-channel-peer"`
Agent specialization	Different contexts need different capabilities	Multiple agents with `skills` and `thinkingDefault`
Tool permissioning	Security boundaries for automated access	`tools.elevated.allowFrom` per channel
Session pruning	Prevents memory bloat and context pollution	`session.reset.mode: "daily"`
Heartbeat monitoring	Alerts you if the gateway goes silent	`agents.defaults.heartbeat.every: "30m"`

Operational Practices

Alex developed operational habits that kept her deployment healthy:

Weekly session review: openclaw sessions list --all to identify stale sessions
Monthly config backup: cp ~/.openclaw/openclaw.json ~/backups/openclaw-$(date +%Y%m%d).json
Health monitoring: A cron job that pings the gateway health endpoint and alerts on failure
Log rotation: Configured logging.file with automatic rotation via session.maintenance.rotateBytes

⚠️ 避坑指南：Never store actual API keys in your main configuration file. Use environment variables (as shown with ${TELEGRAM_BOT_TOKEN}) or the auth profiles system. Alex initially committed her config to GitHub with real tokens—a mistake she caught only after seeing unexpected activity on her Telegram bot.

Case Study: Team Coordination

A different challenge emerges when OpenClaw serves multiple users: coordination, permissions, and expectations management.

The Scenario

A small startup deployed OpenClaw as a team assistant serving 12 engineers across Slack and Discord. The assistant handled code reviews, deployment coordination, and documentation queries. Unlike the personal deployment, this setup needed multi-user considerations from day one.

Initial Configuration

# ch-16-code2.yaml
identity:
  name: "TeamBot"
  theme: "engineering team assistant"
  emoji: "🤖"

channels:
  slack:
    enabled: true
    botToken: "${SLACK_BOT_TOKEN}"
    appToken: "${SLACK_APP_TOKEN}"
    slashCommand:
      enabled: true
      name: "claw"
      sessionPrefix: "slack:slash"  # [1]
      ephemeral: false  # [2] Show responses to channel
    channels:
      "#eng":
        allow: true
        requireMention: true
      "#deployments":
        allow: true
        requireMention: false  # Always active in deployment channel
      "#code-review":
        allow: true
        requireMention: true
    dm:
      enabled: true
      allowFrom: ["U_SITE_ADMIN"]  # [3]

  discord:
    enabled: true
    token: "${DISCORD_BOT_TOKEN}"
    guilds:
      "GUILD_ID":
        slug: "team-server"
        requireMention: false
        channels:
          general:
            allow: false  # [4] Explicit deny
          deployments:
            allow: true
          bot-playground:
            allow: true
            requireMention: false

session:
  scope: "per-channel"  # [5] Shared session per channel
  dmScope: "per-channel-peer"  # [6] Isolated DM sessions
  reset:
    mode: "idle"
    idleMinutes: 120

tools:
  allow: ["read", "canvas", "process"]
  deny: ["exec", "write"]  # [7] No filesystem writes
  elevated:
    enabled: false  # [8] No elevated tools for team deployment

Multi-User Considerations

Team deployments face unique challenges:

Challenge	Solution	Implementation
Permission sprawl	Explicit channel allowlists	`channels.slack.channels.*.allow: true`
Context pollution	Shorter session retention	`session.reset.idleMinutes: 120`
Tool safety	Deny dangerous tools	`tools.deny: ["exec", "write"]`
Visibility control	Per-channel mention requirements	`requireMention: true`
Admin isolation	Separate DM permissions	`dm.allowFrom: ["U_SITE_ADMIN"]`

Scaling Beyond Single-User

As the team grew from 3 to 12 users, they hit scaling issues:

Memory pressure: With 12 active users, the Gateway's memory usage grew to 2GB. Solution: Added agents.defaults.maxConcurrent: 2 to limit parallel agent execution.
Response latency: Users in the deployment channel experienced delays during code review spikes. Solution: Created a dedicated agent for deployment operations with fastModeDefault: true.
Session confusion: Multiple users in the same channel were overwriting each other's context. Solution: Changed from scope: "per-channel" to scope: "per-channel-peer" for better isolation.

The final configuration included agent specialization:

agents:
  defaults:
    maxConcurrent: 2  # Limit parallel execution
    skills: ["github"]
  list:
    - id: "main"
      default: true
      skills: ["github", "summarize"]
    - id: "deployer"
      fastModeDefault: true  # [9] Quick responses for ops
      skills: ["github"]
      reasoningDefault: "off"
    - id: "reviewer"
      thinkingDefault: "high"
      reasoningDefault: "on"
      skills: ["github", "coding-agent"]

☕ 茶水间时间：The team initially tried using OpenClaw for automatic code reviews, but found the AI's feedback too verbose for PR comments. They pivoted to using the assistant only for review summaries and style checking, letting humans handle substantive feedback. The lesson? Match the tool to the strength—AI excels at pattern matching and summarization, not nuanced judgment.

Operational Workflows

Team deployments benefit from established operational workflows:

Onboarding: New users get a pinned message in #bot-playground with available commands and expectations
Incident response: If the bot misbehaves, any user can DM the designated admin to reset the channel session
Feature requests: Tracked in a dedicated GitHub repo linked via a /feature slash command
Weekly retro: The team reviews bot interactions weekly to identify patterns and improve prompts

Case Study: Automation and Bots

The third pattern uses OpenClaw as an automation platform rather than a conversational assistant. These deployments emphasize tool access, scheduled tasks, and monitoring over chat interaction.

Tool-Heavy Configurations

A DevOps engineer deployed OpenClaw to manage infrastructure automation, monitoring alerts, and periodic maintenance tasks. This configuration maximizes tool access while minimizing conversational overhead:

# ch-16-code3.yaml
identity:
  name: "AutoBot"
  theme: "automation assistant"
  emoji: "⚙️"

channels:
  discord:
    enabled: true
    token: "${DISCORD_BOT_TOKEN}"
    guilds:
      "GUILD_ID":
        slug: "ops-center"
        requireMention: false
        channels:
          alerts:
            allow: true
          automation:
            allow: true

tools:
  allow:
    - "exec"
    - "process"
    - "read"
    - "write"
    - "edit"
    - "apply_patch"
    - "canvas"
  exec:
    timeoutSec: 3600  # [1] 1 hour for long-running tasks
    backgroundMs: 30000
    cleanupMs: 7200000  # [2] Clean up after 2 hours
  elevated:
    enabled: true
    allowFrom:
      discord: ["ADMIN_USER_ID"]

agents:
  defaults:
    workspace: "~/.openclaw/workspace"
    model:
      primary: "anthropic/claude-sonnet-4-6"
    skills: ["healthcheck", "github"]
    thinkingDefault: "low"
    reasoningDefault: "off"
    fastModeDefault: true  # [3] Minimize processing overhead
    timeoutSeconds: 3600  # [4] Match exec timeout
  list:
    - id: "main"
      default: true
    - id: "monitor"
      skills: ["healthcheck"]
      heartbeat:
        every: "15m"  # [5] Frequent health checks
        model: "anthropic/claude-haiku-4-5"  # [6] Cheaper model for monitoring
        target: "last"
        to: "DISCORD_CHANNEL_ID"
        prompt: |
          Check the health of the following services:
          - API endpoint: https://api.example.com/health
          - Database: postgres://prod-db.example.com
          - Redis: redis://prod-redis.example.com
          Report any issues found.
        directPolicy: "allow"
        ackMaxChars: 500

Integration Patterns

Automation deployments commonly integrate with external systems:

# Cron jobs for scheduled automation
cron:
  - id: "daily-maintenance"
    schedule: "0 2 * * *"  # [7] 2 AM daily
    prompt: |
      Run daily maintenance tasks:
      1. Clean up temporary files in /tmp
      2. Rotate logs older than 7 days
      3. Check disk usage and alert if > 80%
      4. Backup database to /backups
    agentId: "main"
    recurring: true
    durable: true  # [8] Persist across restarts

  - id: "weekly-report"
    schedule: "0 9 * * 1"  # [9] 9 AM every Monday
    prompt: |
      Generate a weekly operations report covering:
      - Incident count and severity
      - Deployment frequency
      - System uptime
      - Top performance issues
      Send the report to #ops-center
    agentId: "monitor"
    recurring: true
    durable: true

Monitoring

Automation platforms require observability. OpenClaw provides several monitoring mechanisms:

logging:
  level: "debug"  # [10] Detailed logging for automation
  file: "/var/log/openclaw/automation.log"
  consoleLevel: "warn"
  redactSensitive: "tools"  # [11] Redact sensitive data in tool calls

agents:
  defaults:
    heartbeat:
      every: "15m"
      model: "anthropic/claude-haiku-4-5"  # Cheaper for monitoring
      target: "last"
      to: "DISCORD_CHANNEL_ID"
      prompt: "HEARTBEAT: Report system status"
      directPolicy: "allow"
      ackMaxChars: 500

⚠️ 避坑指南：Automation deployments are prone to runaway costs. The engineer initially used claude-opus-4-6 for monitoring heartbeats, racking up unexpected API charges. Switching to claude-haiku-4-5 for automated checks reduced costs by 90% while maintaining adequate monitoring coverage.

Automation Platform Capabilities

When deployed as an automation platform, OpenClaw provides:

Capability	Use Case	Implementation
Scheduled tasks	Periodic maintenance, reports	`cron` jobs with recurring schedules
Event-driven responses	Alert handling, incident response	Gateway event subscriptions
Tool orchestration	Multi-step automation workflows	Agent tools with sequential execution
Monitoring	Health checks, uptime monitoring	`agents.defaults.heartbeat`
Logging and audit	Compliance, debugging	`logging.file` with redaction

Lessons Learned

Across dozens of production deployments, certain patterns emerge consistently. Understanding these patterns helps you avoid common pitfalls and adopt proven configurations.

Best Practices Synthesis

Rendering diagram...

Common Pitfalls

Pitfall	Impact	Prevention
Committed secrets	Security breach	Use environment variables or auth profiles
Unbounded session growth	Memory exhaustion, context pollution	Configure `session.reset` with idle/daily modes
Missing channel isolation	Context bleeding between conversations	Set `session.scope: "per-channel-peer"`
Over-permissive tools	Unauthorized system access	Start with `tools.deny: ["exec", "write"]`, add explicitly
No monitoring	Silent failures, undetected downtime	Configure `heartbeat` for automated health checks
Expensive monitoring models	Unexpected API costs	Use cheaper models (`haiku`) for automated tasks
Single point of failure	Service unavailability	Run Gateway with `restart: unless-stopped`, add healthcheck

Proven Configurations

Based on production deployments, here are battle-tested configuration patterns:

Minimal Personal Deployment:

identity:
  name: "Assistant"
agent:
  workspace: "~/.openclaw/workspace"
channels:
  telegram:
    allowFrom: ["USER_ID"]
session:
  scope: "per-channel-peer"
  reset:
    mode: "daily"

Team Deployment with Safety:

tools:
  allow: ["read", "canvas", "process"]
  deny: ["exec", "write"]
  elevated:
    enabled: false
session:
  scope: "per-channel-peer"
  reset:
    mode: "idle"
    idleMinutes: 120

Automation Platform:

agents:
  defaults:
    fastModeDefault: true
    thinkingDefault: "low"
    heartbeat:
      every: "15m"
      model: "anthropic/claude-haiku-4-5"
tools:
  allow: ["exec", "read", "write", "edit"]
logging:
  level: "info"
  redactSensitive: "tools"

Principles for Deployment

Across all deployment types, certain principles hold true:

Start restrictive, relax gradually: Begin with minimal permissions and tool access. Add capabilities only when needed.
Isolate by context: Different channels, purposes, or users deserve separate sessions. Configure scope accordingly.
Monitor before automating: Establish observability (heartbeat, logging) before enabling automated tasks or cron jobs.
Budget for failures: Set timeoutSeconds, idleMinutes, and resource limits to prevent runaway processes or infinite loops.
Document your deployment: Your future self (or your successor) will thank you. Document channels, agents, skills, and operational procedures.
Test in staging: Before deploying automation to production, test in a dedicated environment with similar tool access.
Plan for scaling: What works for one user may break at ten. Design configuration that scales—use allowlists, scoping, and resource limits from the start.

The deployments that succeed share a common trait: they respect OpenClaw's architecture rather than fighting it. They use the plugin system for extensibility, the agent system for specialization, and the Gateway protocol for reliable communication. They configure defensively, monitor proactively, and iterate based on real usage patterns.

Your deployment will be unique, but it doesn't have to be unique in its mistakes. Learn from these case studies, apply the patterns that match your use case, and build on proven configurations rather than starting from scratch.

Chapter Exercises

Design a deployment for your use case: Sketch the channels, agents, and tools you'd need. What session scope makes sense? What tools should be allowed or denied?
Identify potential issues: Review the configuration snippets in this chapter. What could go wrong with each? What safeguards would you add?
Document your patterns: If you already run OpenClaw, document your deployment patterns. What works? What would you change? What lessons have you learned?