Troubleshooting and Performance

As you build more complex OpenClaw setups with multiple agents, custom skills, and connected channels, you will inevitably encounter issues. This lesson equips you with the diagnostic tools, optimization techniques, and troubleshooting knowledge to keep your agent running smoothly.

What You'll Learn

By the end of this lesson, you will know how to use OpenClaw's diagnostic tools, optimize context window usage, tune compaction settings, resolve common issues, and monitor your agent's performance.

Diagnostic Tools

Reading Logs

The first stop for any issue is the logs:

# View the last 50 log entries
openclaw logs --tail 50

# Follow logs in real time (useful during testing)
openclaw logs --follow

# Filter logs by severity
openclaw logs --level error
openclaw logs --level warn

# Filter logs by component
openclaw logs --filter gateway
openclaw logs --filter agent
openclaw logs --filter channel

Understanding Log Entries

Each log entry contains:

• Timestamp — When the event occurred
• Level — debug, info, warn, error
• Component — Which part of the system generated the log (gateway, agent, channel, skill)
• Message — What happened
• Context — Additional data like message IDs, channel names, or error stack traces

Key Log Patterns to Watch For

[ERROR] [channel:whatsapp] Connection lost, reconnecting...

Network issue — usually resolves automatically. If it persists, check your internet connection and run openclaw channels reconnect.

[WARN] [agent] Context window 92% full, triggering compaction

The conversation is getting long. Compaction will summarize older messages. See the optimization section below.

[ERROR] [skill:my-skill] Tool execution failed: API rate limit exceeded

An external API your skill uses hit its rate limit. Add retry logic or rate limiting to your skill.

[WARN] [gateway] Heartbeat task skipped: agent busy

The heartbeat tried to run a scheduled task but the agent was already processing a request. The task will retry on the next heartbeat cycle.

Context Window Optimization

The context window is your agent's working memory for a single conversation. When it fills up, older messages are compacted (summarized), which can lose nuance. Managing context efficiently keeps your agent sharp.

How Context Gets Used

Each turn, OpenClaw assembles context from multiple sources:

Source	Typical Size	Description
SOUL.md	500-2000 tokens	Agent personality and rules
USER.md	200-500 tokens	User preferences
Injected skills	500-3000 tokens	Only relevant skills per turn
Memory	200-1000 tokens	Relevant long-term memory
Conversation history	Variable	Recent messages
Current message	Variable	The user's latest input

Reducing Context Usage

Keep SOUL.md concise. Every token in SOUL.md is included in every turn. Remove verbose explanations and keep only essential behavioral rules.

Trim USER.md. Only include preferences that affect daily interactions. Move rarely-needed information to memory files instead.

Review skill sizes. Large SKILL.md files consume context when injected. Keep instructions focused. If a skill's instructions exceed 500 tokens, consider splitting it.

Use specific skill names. When you name an agent or skill in your message, OpenClaw can inject only that skill instead of searching all skills for relevance.

Compaction Tuning

Compaction summarizes older conversation messages to free up context space. You can tune its behavior in config.json:

{
  "compaction": {
    "threshold": 0.85,
    "strategy": "smart",
    "preserve_recent": 10,
    "preserve_tool_results": true
  }
}

• threshold — Trigger compaction when context is this percentage full (default: 0.85 = 85%)
• strategy — "smart" (AI-powered summarization), "truncate" (remove oldest messages), or "sliding" (keep a fixed window)
• preserve_recent — Always keep the N most recent messages uncompacted
• preserve_tool_results — Keep tool outputs intact (they often contain important data)

When to adjust:

• Lower the threshold (e.g., 0.75) if you notice the agent forgetting important context
• Increase preserve_recent if multi-step conversations lose track of earlier steps
• Set preserve_tool_results to true if you use data-heavy tools like web search or database queries

Common Issues and Solutions

Channel Connection Issues

Problem	Solution
WhatsApp disconnects frequently	Check that your phone has a stable internet connection. Run openclaw channels reconnect whatsapp
Telegram bot not responding	Verify the bot token is correct. Check if the bot was revoked in @BotFather
Discord messages not arriving	Ensure the bot has the correct permissions (Send Messages, Read Message History) in the server settings
Slack integration broken	Regenerate the Slack app token and update config.json

Agent Behavior Issues

Problem	Solution
Agent ignores instructions	Check SOUL.md for contradictory rules. Simplify and prioritize instructions
Agent uses wrong skill	Make skill descriptions more specific. Add negative examples ("Do NOT use this for...")
Agent hallucinates tool results	Enable preserve_tool_results in compaction settings. Ensure the agent's model supports tool use well
Agent responds too slowly	Switch to a faster model for non-critical tasks. Reduce the number of injected skills
Agent stuck in a loop	Set a max iterations limit in config.json. Check if tool outputs are triggering re-evaluation

Skill Issues

Problem	Solution
Skill not loading	Check SKILL.md frontmatter for YAML syntax errors. Run openclaw skills list to verify
Custom tool failing	Check the tool's JavaScript for errors. Verify API keys are set in the environment
Skill conflicts	Two skills with overlapping descriptions confuse the injection system. Make descriptions distinct
Skill causing high latency	Profile the tool execution. Add timeouts to external API calls

Memory Issues

Problem	Solution
Agent forgets past conversations	Check that MEMORY.md is being written to. Verify compaction is not too aggressive
Memory file growing too large	Archive old daily logs. Keep MEMORY.md focused on active, relevant information
Duplicate memory entries	Add deduplication instructions to SOUL.md: "Before saving to memory, check if similar information already exists"

Performance Monitoring

Key Metrics to Track

Response latency — How long the agent takes to respond. Track this over time to spot degradation.

# View average response times
openclaw stats --period 7d

Token usage — How many tokens each conversation uses. High usage means higher costs and more frequent compaction.

Tool execution time — How long individual tools take. Slow tools are the most common cause of slow agent responses.

Error rate — What percentage of requests result in errors. A sudden spike usually indicates an external service issue.

Setting Up Alerts

You can configure alerts in config.json:

{
  "alerts": {
    "error_rate_threshold": 0.1,
    "latency_threshold_ms": 30000,
    "notify_channel": "telegram"
  }
}

This sends you a notification on Telegram if the error rate exceeds 10% or response time exceeds 30 seconds.

Maintenance Routine

Daily

• Check openclaw status for any disconnected channels
• Review error logs: openclaw logs --level error --since 24h

Weekly

• Review token usage and costs: openclaw stats --period 7d
• Check for skill updates: openclaw skills update --check
• Review and clean up MEMORY.md if it is growing large

Monthly

• Run a security audit: openclaw security audit --deep
• Update OpenClaw: npm update -g @openclaw/cli
• Review and optimize SOUL.md and AGENTS.md based on usage patterns
• Archive old transcript and memory files

Key Takeaways

• Use openclaw logs with filters for level, component, and time range as your first diagnostic tool.
• Context window management is critical — keep SOUL.md concise, trim skills, and tune compaction settings.
• Set compaction threshold to 0.75-0.85 and always preserve recent messages and tool results.
• Most common issues stem from channel connections, skill conflicts, or overly aggressive compaction — check these first.
• Establish a daily/weekly/monthly maintenance routine to keep your agent running smoothly.