Skill: phenixstar/openclaw-doctor-pro (version 1.1.0)

--- name: openclaw-doctor-pro description: Comprehensive diagnostic, error-fixing, and skill recommendation tool for OpenClaw license: MIT version: 1.0.0 homepage: https://github.com/PhenixStar/openclaw-doctor-pro user-invocable: true disable-model-invocation: false metadata: { "openclaw": { "emoji": "🏥", "requires": { "bins": ["python3"], "env": [] }, "install": [ { "id": "pip-deps", "kind": "shell", "command": "pip install click rich requests beautifulsoup4", "label": "Install Python dependencies" } ] } } --- # OpenClaw Doctor Pro Ultimate diagnostic, error-fixing, and skill recommendation tool for OpenClaw. ## When to Use Activate when user wants to: - Diagnose OpenClaw errors or issues - Auto-fix common problems - Find and recommend ClawHub skills - Run extended health checks - Setup OpenClaw for first time - Update documentation and caches ## Available Tools ### Error Fixer Diagnose and auto-fix OpenClaw errors. ```bash # Diagnose by error code python3 {baseDir}/scripts/error-fixer.py --error 401 # Analyze log file python3 {baseDir}/scripts/error-fixer.py --input /path/to/log # Auto-fix safe issues python3 {baseDir}/scripts/error-fixer.py --error EADDRINUSE --auto-fix # List errors by category python3 {baseDir}/scripts/error-fixer.py --category authentication ``` ### Skill Recommender Smart ClawHub skill recommendations. ```bash # Recommend for channel python3 {baseDir}/scripts/skill-recommender.py --channel whatsapp --top 5 # Recommend by use case python3 {baseDir}/scripts/skill-recommender.py --use-case "image generation" # Auto-detect from config python3 {baseDir}/scripts/skill-recommender.py --auto-detect # Check for updates python3 {baseDir}/scripts/skill-recommender.py --check-updates ``` ### Enhanced Doctor Extended diagnostic checks. ```bash # Full diagnostics python3 {baseDir}/scripts/enhanced-doctor.py # Deep scan with log analysis python3 {baseDir}/scripts/enhanced-doctor.py --deep # JSON output python3 {baseDir}/scripts/enhanced-doctor.py --json ``` ### Self-Updater Keep references and caches current. ```bash # Check what's outdated python3 {baseDir}/scripts/self-updater.py --check # Update everything python3 {baseDir}/scripts/self-updater.py --update # Update only skill cache python3 {baseDir}/scripts/self-updater.py --update --skills-only ``` ### Setup Wizard Interactive first-time setup. ```bash # Interactive setup python3 {baseDir}/scripts/setup-wizard.py # Check prerequisites only python3 {baseDir}/scripts/setup-wizard.py --check-only ``` ## Reference Files - [Error Catalog](references/error-catalog.md) - Master error index - [Auto-Fix Capabilities](references/auto-fix-capabilities.md) - Safe vs manual fixes - [Diagnostic Commands](references/diagnostic-commands.md) - CLI quick reference - [Troubleshooting Workflow](references/troubleshooting-workflow.md) - Decision tree - [Authentication Errors](references/authentication-errors.md) - Auth issues - [Rate Limiting Errors](references/rate-limiting-errors.md) - Quota management - [Gateway Errors](references/gateway-errors.md) - Network issues - [Channel Errors](references/channel-errors.md) - Channel-specific - [Sandbox Errors](references/sandbox-errors.md) - Docker issues - [Configuration Errors](references/configuration-errors.md) - Config problems - [Installation Errors](references/installation-errors.md) - Setup issues - [ClawHub Integration](references/clawhub-integration.md) - Skill management ## Templates - [Error Report](templates/error-report.md) - Diagnostic output format - [Recommendation Report](templates/recommendation-report.md) - Skill suggestions format

path: README.md
content: # OpenClaw Doctor Pro

Comprehensive diagnostic, error-fixing, and skill recommendation tool for OpenClaw.

## What is OpenClaw Doctor Pro?

OpenClaw Doctor Pro is an advanced troubleshooting suite for [OpenClaw](https://github.com/openclaw/openclaw) - a self-hosted AI gateway that connects messaging apps (WhatsApp, Telegram, Discord, Slack, Signal) to AI agents.

**Key Features:**
- 🔍 Automated error diagnosis across 10 error categories
- 🔧 Auto-fix capabilities for 40+ common issues
- 💡 Smart skill recommendations from ClawHub (5,700+ skills)
- 📊 Deep health checks and performance monitoring
- 📚 Comprehensive reference documentation
- 🎯 Interactive setup wizard for first-time users

## Quick Start

### Installation

```bash
# Install dependencies
pip install click rich requests beautifulsoup4

# Run diagnostic
python3 scripts/enhanced-doctor.py

# Fix errors automatically
python3 scripts/error-fixer.py --fix-all-safe

# Get skill recommendations
python3 scripts/skill-recommender.py --auto-detect
```

### First-Time Setup

```bash
# Interactive setup wizard
python3 scripts/setup-wizard.py

# Or check prerequisites only
python3 scripts/setup-wizard.py --check-only
```

## Tools Overview

### 1. Enhanced Doctor
Extended diagnostic checks beyond built-in `openclaw doctor`.

```bash
# Full diagnostics
python3 scripts/enhanced-doctor.py

# Deep scan with log analysis
python3 scripts/enhanced-doctor.py --deep

# JSON output
python3 scripts/enhanced-doctor.py --json
```

### 2. Error Fixer
Diagnose and auto-fix OpenClaw errors.

```bash
# Diagnose by error code
python3 scripts/error-fixer.py --error 401

# Analyze log file
python3 scripts/error-fixer.py --input /path/to/log

# Auto-fix safe issues
python3 scripts/error-fixer.py --error EADDRINUSE --auto-fix

# List errors by category
python3 scripts/error-fixer.py --category authentication
```

### 3. Skill Recommender
Smart ClawHub skill recommendations.

```bash
# Recommend for channel
python3 scripts/skill-recommender.py --channel whatsapp --top 5

# Recommend by use case
python3 scripts/skill-recommender.py --use-case "image generation"

# Auto-detect from config
python3 scripts/skill-recommender.py --auto-detect

# Check for updates
python3 scripts/skill-recommender.py --check-updates
```

### 4. Self-Updater
Keep references and caches current.

```bash
# Check what's outdated
python3 scripts/self-updater.py --check

# Update everything
python3 scripts/self-updater.py --update

# Update only skill cache
python3 scripts/self-updater.py --update --skills-only
```

### 5. Setup Wizard
Interactive first-time setup.

```bash
# Interactive setup
python3 scripts/setup-wizard.py

# Check prerequisites only
python3 scripts/setup-wizard.py --check-only
```

## Documentation Structure

### Reference Documentation (`references/`)

Comprehensive guides covering all aspects of OpenClaw troubleshooting:

| File | Description |
|------|-------------|
| [error-catalog.md](references/error-catalog.md) | Master index of all error types (10 categories, 50+ errors) |
| [authentication-errors.md](references/authentication-errors.md) | 401, API keys, tokens, env vars |
| [rate-limiting-errors.md](references/rate-limiting-errors.md) | 429, quotas, throttling, retry strategies |
| [gateway-errors.md](references/gateway-errors.md) | 502, port conflicts, network issues |
| [channel-errors.md](references/channel-errors.md) | WhatsApp, Telegram, Discord, Slack, Signal |
| [sandbox-errors.md](references/sandbox-errors.md) | Docker, containers, OOM, timeouts |
| [configuration-errors.md](references/configuration-errors.md) | Config validation, schema, types |
| [installation-errors.md](references/installation-errors.md) | Node.js, pnpm, PATH, dependencies |
| [diagnostic-commands.md](references/diagnostic-commands.md) | CLI command reference |
| [clawhub-integration.md](references/clawhub-integration.md) | Skill management, publishing |
| [auto-fix-capabilities.md](references/auto-fix-capabilities.md) | What can be auto-fixed |
| [troubleshooting-workflow.md](references/troubleshooting-workflow.md) | Decision trees and flows |

### Templates (`templates/`)

Report templates for consistent output:

| File | Purpose |
|------|---------|
| [error-report.md](templates/error-report.md) | Error diagnostic report format |
| [recommendation-report.md](templates/recommendation-report.md) | Skill recommendation report format |

## Error Categories

OpenClaw Doctor Pro handles 10 error categories:

1. **Authentication** - API keys, tokens, credentials
2. **Rate Limiting** - Quotas, throttling, burst limits
3. **Gateway** - Network, ports, connectivity
4. **Channels** - WhatsApp, Telegram, Discord, Slack, Signal
5. **Sandbox** - Docker, containers, execution
6. **Configuration** - Schema, validation, types
7. **Installation** - Dependencies, versions, PATH
8. **Plugins** - Loading, initialization, versions
9. **Skills** - ClawHub, execution, manifests
10. **System** - Disk, memory, permissions

## Auto-Fix Capabilities

### Safety Levels

- ✅ **Safe** - Fully automated, no user confirmation needed
- ⚠️ **Moderate** - Automated with optional confirmation
- 🔴 **Risky** - Requires explicit user confirmation
- ❌ **Manual** - Cannot auto-fix, guidance provided

### Examples

**Safe Auto-Fixes:**
- Increase sandbox timeout
- Enable retry strategy
- Convert config value types
- Migrate deprecated keys
- Refresh auth tokens

**Moderate Auto-Fixes:**
- Kill process on port (EADDRINUSE)
- Fix workspace permissions
- Install missing packages
- Re-set webhooks

**Risky Auto-Fixes:**
- Regenerate gateway token
- Start Docker daemon
- Install Signal CLI
- Modify firewall rules

See [auto-fix-capabilities.md](references/auto-fix-capabilities.md) for complete list.

## Common Workflows

### Gateway Won't Start
```bash
# 1. Run diagnostics
python3 scripts/enhanced-doctor.py

# 2. Fix common issues
python3 scripts/error-fixer.py --fix-all-safe

# 3. Check port
lsof -i :18789

# 4. Fix port conflict if needed
python3 scripts/error-fixer.py --error EADDRINUSE --auto-fix
```

### Channel Not Working
```bash
# 1. Check channel status
openclaw channels status whatsapp

# 2. View channel-specific errors
python3 scripts/error-fixer.py --category channel

# 3. Test channel
openclaw channels test whatsapp

# 4. Follow channel-specific guide
# See references/channel-errors.md
```

### API Rate Limits
```bash
# 1. Check quota
openclaw quota show

# 2. Enable retry strategy
python3 scripts/error-fixer.py --error 429 --auto-fix

# 3. Enable fallback provider
openclaw config set ai.fallback.enabled true
```

### Find Relevant Skills
```bash
# 1. Auto-detect needs
python3 scripts/skill-recommender.py --auto-detect

# 2. Install recommended
openclaw skills install skill-name

# 3. Check updates
python3 scripts/skill-recommender.py --check-updates
```

## ClawHub Integration

Access to 5,700+ skills across categories:

**Categories:**
- AI & Machine Learning (image gen, embeddings, sentiment)
- Automation (workflows, schedulers, triggers)
- Utilities (PDF, image tools, converters)
- Integrations (Google, GitHub, Zapier)
- Communication (email, SMS, notifications)
- Data (databases, analytics, visualization)

**Popular Skills:**
- `image-generator-pro` - Multi-provider image generation
- `pdf-toolkit` - Complete PDF manipulation
- `workflow-builder` - Visual automation
- `google-workspace` - Google integration
- `auto-responder` - Smart responses

See [clawhub-integration.md](references/clawhub-integration.md) for details.

## Project Structure

```
openclaw-doctor-pro/
├── SKILL.md                          # ClawHub manifest
├── README.md                         # This file
├── scripts/
│   ├── enhanced-doctor.py           # Extended diagnostics
│   ├── error-fixer.py               # Auto-fix errors
│   ├── skill-recommender.py         # Skill recommendations
│   ├── self-updater.py              # Update tool
│   └── setup-wizard.py              # First-time setup
├── references/
│   ├── error-catalog.md             # Error index
│   ├── authentication-errors.md     # Auth issues
│   ├── rate-limiting-errors.md      # Rate limits
│   ├── gateway-errors.md            # Gateway issues
│   ├── channel-errors.md            # Channel issues
│   ├── sandbox-errors.md            # Sandbox issues
│   ├── configuration-errors.md      # Config issues
│   ├── installation-errors.md       # Install issues
│   ├── diagnostic-commands.md       # CLI reference
│   ├── clawhub-integration.md       # Skill management
│   ├── auto-fix-capabilities.md     # Fix reference
│   └── troubleshooting-workflow.md  # Decision trees
├── templates/
│   ├── error-report.md              # Error report template
│   └── recommendation-report.md     # Recommendation template
├── data/
│   ├── error-patterns.json          # Error definitions
│   └── skills-cache.json            # ClawHub cache
└── cache/
    └── skill-recommendations.json   # Cached recommendations
```

## Requirements

- Python 3.8+
- OpenClaw installed
- Dependencies: `click`, `rich`, `requests`, `beautifulsoup4`

## Installation

```bash
# Clone or download
git clone https://github.com/username/openclaw-doctor-pro.git
cd openclaw-doctor-pro

# Install dependencies
pip install click rich requests beautifulsoup4

# Run setup wizard
python3 scripts/setup-wizard.py
```

## Contributing

Contributions welcome! Areas to improve:

- Add more error patterns
- Enhance auto-fix recipes
- Improve skill recommendations
- Add more platform support
- Update documentation

## License

MIT License - See LICENSE file for details.

## Support

- GitHub Issues: https://github.com/openclaw/openclaw/issues
- OpenClaw Docs: https://docs.openclaw.io
- Community Discord: https://discord.gg/openclaw

## Acknowledgments

Built for the OpenClaw community. Special thanks to:
- OpenClaw core team
- ClawHub contributors
- Community testers and feedback providers

---

**OpenClaw Doctor Pro** - Because every gateway needs a doctor 🏥


path: data/complementary-skills.json
content: {
  "version": "1.0.0",
  "updated": "2026-02-08",
  "relationships": [
    {
      "skill_slug": "openclaw-doctor-pro",
      "complements": [
        {
          "skill_slug": "debug-pro",
          "category": "diagnostics",
          "priority": "HIGH",
          "integration_type": "error_diagnosis",
          "reason": "Interactive debugging for complex errors",
          "benefit": "Step through code execution interactively",
          "trigger_conditions": ["auto_fix_failed", "complex_error"]
        },
        {
          "skill_slug": "docker-essentials",
          "category": "diagnostics",
          "priority": "HIGH",
          "integration_type": "container_diagnostics",
          "reason": "Container diagnostics for sandbox errors",
          "benefit": "Deep container inspection and troubleshooting",
          "trigger_conditions": ["sandbox_error", "container_timeout"]
        },
        {
          "skill_slug": "cognitive-memory",
          "category": "diagnostics",
          "priority": "HIGH",
          "integration_type": "pattern_tracking",
          "reason": "Track historical error patterns",
          "benefit": "Remember past fixes and solutions",
          "trigger_conditions": ["repeated_error", "learning_opportunity"]
        },
        {
          "skill_slug": "evolver",
          "category": "recovery",
          "priority": "HIGH",
          "integration_type": "fix_evolution",
          "reason": "Auto-evolve fix recipes based on success rates",
          "benefit": "Auto-refine recipes based on outcomes",
          "trigger_conditions": ["fix_applied", "success_rate_tracking"]
        },
        {
          "skill_slug": "workflow-builder",
          "category": "recovery",
          "priority": "HIGH",
          "integration_type": "recovery_workflows",
          "reason": "Build complex multi-step recovery workflows",
          "benefit": "Create reusable automated workflows",
          "trigger_conditions": ["multi_step_fix_needed", "conditional_logic"]
        },
        {
          "skill_slug": "multi-agent",
          "category": "recovery",
          "priority": "HIGH",
          "integration_type": "parallel_recovery",
          "reason": "Coordinate parallel recovery tasks",
          "benefit": "Run multiple diagnostics simultaneously",
          "trigger_conditions": ["multi_channel_error", "parallel_diagnostics"]
        },
        {
          "skill_slug": "registry-broker-skills",
          "category": "recommendations",
          "priority": "HIGH",
          "integration_type": "registry_integration",
          "reason": "Enhanced skill registry integration",
          "benefit": "Better skill discovery and management",
          "trigger_conditions": ["skill_search", "dependency_check"]
        },
        {
          "skill_slug": "github",
          "category": "integrations",
          "priority": "HIGH",
          "integration_type": "issue_tracking",
          "reason": "Auto-create GitHub issues for unresolved errors",
          "benefit": "Track unresolved errors as issues",
          "trigger_conditions": ["unresolved_error", "new_error_pattern"]
        },
        {
          "skill_slug": "slack-integration",
          "category": "integrations",
          "priority": "HIGH",
          "integration_type": "team_notifications",
          "reason": "Alert teams about critical errors",
          "benefit": "Alert team immediately on critical errors",
          "trigger_conditions": ["critical_error", "team_notification"]
        },
        {
          "skill_slug": "discord-bot",
          "category": "integrations",
          "priority": "HIGH",
          "integration_type": "community_support",
          "reason": "Community support channel notifications",
          "benefit": "Get help from OpenClaw community",
          "trigger_conditions": ["community_help_needed", "share_fix"]
        }
      ]
    }
  ],
  "categories": {
    "diagnostics": [
      "debug-pro",
      "docker-essentials",
      "cognitive-memory",
      "git-workflows",
      "cli-utilities",
      "data-analytics"
    ],
    "recovery": [
      "evolver",
      "workflow-builder",
      "multi-agent",
      "auto-responder",
      "backup-restore",
      "state-management",
      "resilience-patterns",
      "health-fitness"
    ],
    "recommendations": [
      "registry-broker-skills",
      "cognitive-memory",
      "data-analytics",
      "ab-testing",
      "benchmark-suite",
      "skill-testing"
    ],
    "integrations": [
      "github",
      "slack-integration",
      "discord-bot",
      "email-smtp",
      "webhook-relay",
      "ci-cd-pipeline",
      "gitlab"
    ]
  }
}


path: data/error-patterns.json
content: {
  "version": "1.0.0",
  "patterns": [
    {
      "id": "auth-001",
      "category": "authentication",
      "code": "401",
      "pattern": "(?i)(unauthorized|invalid.*api.*key|authentication.*failed|401)",
      "severity": "critical",
      "title": "Authentication Failed",
      "description": "API key is missing, invalid, or expired",
      "causes": ["Invalid API key", "Expired token", "Wrong provider configured"],
      "fix_steps": ["Verify API key in openclaw.json", "Check environment variables", "Run: openclaw models auth setup-token"],
      "fix_recipe_id": "fix-auth-key",
      "related_codes": ["INVALID_REQUEST"],
      "doc_url": "https://docs.openclaw.ai/configuration/auth"
    },
    {
      "id": "auth-002",
      "category": "authentication",
      "code": "401",
      "pattern": "(?i)(missing.*anthropic.*api.*key|ANTHROPIC_API_KEY.*not.*set|anthropic.*authentication)",
      "severity": "critical",
      "title": "Missing Anthropic API Key",
      "description": "ANTHROPIC_API_KEY environment variable is not set",
      "causes": ["Environment variable not set", "API key not configured in openclaw.json", "Wrong environment file loaded"],
      "fix_steps": ["Set ANTHROPIC_API_KEY environment variable", "Add key to .env file", "Run: openclaw models auth setup-token --provider anthropic"],
      "fix_recipe_id": "fix-auth-env",
      "related_codes": ["INVALID_REQUEST"],
      "doc_url": "https://docs.openclaw.ai/providers/anthropic"
    },
    {
      "id": "auth-003",
      "category": "authentication",
      "code": "401",
      "pattern": "(?i)(missing.*openai.*api.*key|OPENAI_API_KEY.*not.*set|openai.*authentication)",
      "severity": "critical",
      "title": "Missing OpenAI API Key",
      "description": "OPENAI_API_KEY environment variable is not set",
      "causes": ["Environment variable not set", "API key not configured in openclaw.json", "Wrong environment file loaded"],
      "fix_steps": ["Set OPENAI_API_KEY environment variable", "Add key to .env file", "Run: openclaw models auth setup-token --provider openai"],
      "fix_recipe_id": "fix-auth-env",
      "related_codes": ["INVALID_REQUEST"],
      "doc_url": "https://docs.openclaw.ai/providers/openai"
    },
    {
      "id": "auth-004",
      "category": "authentication",
      "code": "401",
      "pattern": "(?i)(token.*expired|jwt.*expired|session.*expired|expired.*credentials)",
      "severity": "high",
      "title": "Token Expired",
      "description": "Authentication token has expired and needs renewal",
      "causes": ["Token TTL exceeded", "Long-running session", "Clock skew"],
      "fix_steps": ["Refresh authentication token", "Re-authenticate with provider", "Run: openclaw models auth setup-token"],
      "fix_recipe_id": "fix-auth-key",
      "related_codes": ["TOKEN_EXPIRED"],
      "doc_url": "https://docs.openclaw.ai/configuration/auth"
    },
    {
      "id": "auth-005",
      "category": "authentication",
      "code": "401",
      "pattern": "(?i)(provider.*auth.*fail|api.*provider.*unauthorized|provider.*credentials.*invalid)",
      "severity": "critical",
      "title": "Provider Authentication Failure",
      "description": "AI provider rejected authentication credentials",
      "causes": ["Invalid provider API key", "Provider account suspended", "IP restriction on API key", "Wrong API endpoint"],
      "fix_steps": ["Verify provider API key is valid", "Check provider account status", "Review IP whitelist settings", "Test API key directly with provider"],
      "fix_recipe_id": "fix-auth-key",
      "related_codes": ["PROVIDER_AUTH_FAILED"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/providers"
    },
    {
      "id": "auth-006",
      "category": "authentication",
      "code": "403",
      "pattern": "(?i)(gateway.*token.*mismatch|invalid.*gateway.*token|gateway.*unauthorized)",
      "severity": "high",
      "title": "Gateway Token Mismatch",
      "description": "Gateway authentication token does not match configured value",
      "causes": ["Token mismatch between client and gateway", "Gateway token changed but not updated in channels", "Multiple gateway instances with different tokens"],
      "fix_steps": ["Verify GATEWAY_TOKEN in openclaw.json", "Update channel configurations with correct token", "Restart gateway after token change"],
      "fix_recipe_id": "fix-gateway-restart",
      "related_codes": ["FORBIDDEN"],
      "doc_url": "https://docs.openclaw.ai/gateway/security"
    },
    {
      "id": "auth-007",
      "category": "authentication",
      "code": "401",
      "pattern": "(?i)(api.*key.*revoked|credentials.*revoked|access.*revoked)",
      "severity": "critical",
      "title": "API Key Revoked",
      "description": "API key has been revoked by the provider",
      "causes": ["Manual key revocation", "Security incident", "Policy violation", "Billing issue"],
      "fix_steps": ["Generate new API key from provider dashboard", "Update openclaw.json with new key", "Run: openclaw models auth setup-token"],
      "fix_recipe_id": "fix-auth-key",
      "related_codes": ["INVALID_REQUEST"],
      "doc_url": "https://docs.openclaw.ai/configuration/auth"
    },
    {
      "id": "rate-001",
      "category": "rate-limiting",
      "code": "429",
      "pattern": "(?i)(rate.*limit.*exceed|too.*many.*requests|429|quota.*exceed)",
      "severity": "high",
      "title": "Rate Limit Exceeded",
      "description": "API request rate limit has been exceeded",
      "causes": ["Too many requests in short time", "Insufficient quota", "Shared rate limit across multiple instances"],
      "fix_steps": ["Wait before retrying", "Implement request throttling", "Increase rate limit with provider", "Distribute load across multiple API keys"],
      "fix_recipe_id": "fix-rate-wait",
      "related_codes": ["RATE_LIMITED"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/rate-limits"
    },
    {
      "id": "rate-002",
      "category": "rate-limiting",
      "code": "429",
      "pattern": "(?i)(daily.*limit.*reach|quota.*exhausted|usage.*limit)",
      "severity": "critical",
      "title": "Daily Quota Exhausted",
      "description": "Daily API usage quota has been exhausted",
      "causes": ["High usage volume", "Quota tier too low", "Unexpected usage spike"],
      "fix_steps": ["Wait for quota reset (usually midnight UTC)", "Upgrade provider plan", "Monitor usage with openclaw stats", "Implement usage alerts"],
      "fix_recipe_id": "fix-rate-wait",
      "related_codes": ["QUOTA_EXCEEDED"],
      "doc_url": "https://docs.openclaw.ai/monitoring/usage"
    },
    {
      "id": "rate-003",
      "category": "rate-limiting",
      "code": "429",
      "pattern": "(?i)(concurrent.*request.*limit|max.*concurrent|parallel.*limit)",
      "severity": "medium",
      "title": "Concurrent Request Limit",
      "description": "Maximum concurrent requests limit exceeded",
      "causes": ["Too many parallel requests", "Agent spawning too many concurrent tasks", "Channel flooding"],
      "fix_steps": ["Reduce concurrent request limit in openclaw.json", "Implement request queuing", "Add rate limiting per channel"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["CONCURRENT_LIMIT"],
      "doc_url": "https://docs.openclaw.ai/configuration/performance"
    },
    {
      "id": "rate-004",
      "category": "rate-limiting",
      "code": "429",
      "pattern": "(?i)(provider.*throttling|provider.*rate.*limit|api.*throttled)",
      "severity": "high",
      "title": "Provider Throttling",
      "description": "AI provider is actively throttling requests",
      "causes": ["Provider-side rate limiting", "Account tier limitations", "Unusual traffic pattern detected"],
      "fix_steps": ["Implement exponential backoff", "Reduce request frequency", "Contact provider support", "Upgrade account tier"],
      "fix_recipe_id": "fix-rate-wait",
      "related_codes": ["PROVIDER_THROTTLED"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/providers"
    },
    {
      "id": "rate-005",
      "category": "rate-limiting",
      "code": "429",
      "pattern": "(?i)(retry.*after|backoff|cooldown.*period)",
      "severity": "medium",
      "title": "Retry After Period",
      "description": "Request must wait for specified retry period",
      "causes": ["Recent rate limit violation", "Provider cooldown period", "Temporary throttling"],
      "fix_steps": ["Wait for Retry-After header duration", "Implement exponential backoff strategy", "Check openclaw logs for retry timing"],
      "fix_recipe_id": "fix-rate-wait",
      "related_codes": ["RETRY_AFTER"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/rate-limits"
    },
    {
      "id": "net-001",
      "category": "network",
      "code": "502",
      "pattern": "(?i)(502.*bad.*gateway|bad.*gateway|upstream.*error)",
      "severity": "high",
      "title": "Bad Gateway Error",
      "description": "Gateway received invalid response from upstream server",
      "causes": ["Provider API down", "Network routing issue", "Timeout from provider", "Proxy misconfiguration"],
      "fix_steps": ["Check provider status page", "Verify network connectivity", "Check openclaw gateway logs", "Test direct API access"],
      "fix_recipe_id": "fix-gateway-restart",
      "related_codes": ["BAD_GATEWAY"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/network"
    },
    {
      "id": "net-002",
      "category": "network",
      "code": "ETIMEDOUT",
      "pattern": "(?i)(connection.*timeout|ETIMEDOUT|request.*timeout|timed.*out)",
      "severity": "high",
      "title": "Connection Timeout",
      "description": "Network connection timed out before completing",
      "causes": ["Slow network connection", "Provider API latency", "Firewall blocking", "DNS resolution slow"],
      "fix_steps": ["Check internet connectivity", "Increase timeout in openclaw.json", "Verify firewall settings", "Test DNS resolution"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["TIMEOUT"],
      "doc_url": "https://docs.openclaw.ai/configuration/network"
    },
    {
      "id": "net-003",
      "category": "network",
      "code": "ENOTFOUND",
      "pattern": "(?i)(ENOTFOUND|dns.*resolution.*fail|host.*not.*found|name.*resolution)",
      "severity": "high",
      "title": "DNS Resolution Failed",
      "description": "Unable to resolve hostname to IP address",
      "causes": ["DNS server unreachable", "Invalid hostname", "Network configuration issue", "DNS cache poisoning"],
      "fix_steps": ["Check DNS server configuration", "Try alternative DNS (8.8.8.8)", "Flush DNS cache", "Verify hostname spelling"],
      "fix_recipe_id": "fix-network-dns",
      "related_codes": ["DNS_ERROR"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/network"
    },
    {
      "id": "net-004",
      "category": "network",
      "code": "ECONNREFUSED",
      "pattern": "(?i)(ECONNREFUSED|connection.*refused|refused.*to.*connect)",
      "severity": "critical",
      "title": "Connection Refused",
      "description": "Target server actively refused the connection",
      "causes": ["Service not running", "Wrong port number", "Firewall blocking", "Service crashed"],
      "fix_steps": ["Verify service is running", "Check port number in configuration", "Review firewall rules", "Check service logs"],
      "fix_recipe_id": "fix-gateway-restart",
      "related_codes": ["CONNECTION_REFUSED"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/network"
    },
    {
      "id": "net-005",
      "category": "network",
      "code": "SSL_ERROR",
      "pattern": "(?i)(ssl.*error|tls.*handshake.*fail|certificate.*invalid|CERT_.*ERROR)",
      "severity": "high",
      "title": "SSL/TLS Error",
      "description": "SSL/TLS connection failed due to certificate or handshake issue",
      "causes": ["Invalid SSL certificate", "Expired certificate", "Certificate chain broken", "TLS version mismatch"],
      "fix_steps": ["Update system CA certificates", "Check certificate validity", "Verify TLS version support", "Disable SSL verification temporarily for testing (not production)"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["SSL_ERROR"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/ssl"
    },
    {
      "id": "net-006",
      "category": "network",
      "code": "PROXY_ERROR",
      "pattern": "(?i)(proxy.*error|proxy.*connect.*fail|proxy.*timeout|proxy.*auth)",
      "severity": "medium",
      "title": "Proxy Connection Issue",
      "description": "Failed to connect through configured proxy",
      "causes": ["Proxy server down", "Proxy authentication failed", "Proxy misconfiguration", "Proxy timeout"],
      "fix_steps": ["Verify proxy server is running", "Check proxy credentials", "Test direct connection (disable proxy)", "Review proxy configuration"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["PROXY_ERROR"],
      "doc_url": "https://docs.openclaw.ai/configuration/proxy"
    },
    {
      "id": "net-007",
      "category": "network",
      "code": "503",
      "pattern": "(?i)(503.*service.*unavailable|api.*endpoint.*unreachable|provider.*unavailable)",
      "severity": "critical",
      "title": "API Endpoint Unreachable",
      "description": "API endpoint is unavailable or unreachable",
      "causes": ["Provider maintenance", "Provider outage", "Network path blocked", "Load balancer issue"],
      "fix_steps": ["Check provider status page", "Wait and retry", "Verify network path to endpoint", "Switch to backup provider if configured"],
      "fix_recipe_id": "fix-gateway-restart",
      "related_codes": ["SERVICE_UNAVAILABLE"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/providers"
    },
    {
      "id": "cfg-001",
      "category": "configuration",
      "code": "CONFIG_ERROR",
      "pattern": "(?i)(invalid.*json|json.*parse.*error|malformed.*json|unexpected.*token)",
      "severity": "critical",
      "title": "Invalid JSON Configuration",
      "description": "Configuration file contains invalid JSON syntax",
      "causes": ["Missing comma", "Trailing comma", "Unclosed bracket", "Invalid escape sequence"],
      "fix_steps": ["Validate JSON with jsonlint", "Check for syntax errors in openclaw.json", "Run: openclaw doctor --fix", "Restore from backup if available"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["PARSE_ERROR"],
      "doc_url": "https://docs.openclaw.ai/configuration/format"
    },
    {
      "id": "cfg-002",
      "category": "configuration",
      "code": "CONFIG_ERROR",
      "pattern": "(?i)(missing.*required.*field|required.*property|field.*is.*required)",
      "severity": "high",
      "title": "Missing Required Configuration Field",
      "description": "Required configuration field is missing from openclaw.json",
      "causes": ["Incomplete configuration", "Corrupted config file", "Migration from old version"],
      "fix_steps": ["Review required fields in documentation", "Run: openclaw doctor", "Regenerate config with: openclaw init", "Check config schema"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["VALIDATION_ERROR"],
      "doc_url": "https://docs.openclaw.ai/configuration/schema"
    },
    {
      "id": "cfg-003",
      "category": "configuration",
      "code": "CONFIG_ERROR",
      "pattern": "(?i)(unknown.*channel|channel.*not.*found|invalid.*channel.*type)",
      "severity": "high",
      "title": "Unknown Channel Type",
      "description": "Configured channel type is not recognized",
      "causes": ["Typo in channel type", "Unsupported channel", "Missing channel plugin", "Wrong channel name"],
      "fix_steps": ["Check channel type spelling", "Verify supported channels: whatsapp, telegram, discord, slack", "Install required channel plugin", "Review channel configuration"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["UNKNOWN_CHANNEL"],
      "doc_url": "https://docs.openclaw.ai/channels/overview"
    },
    {
      "id": "cfg-004",
      "category": "configuration",
      "code": "CONFIG_ERROR",
      "pattern": "(?i)(invalid.*port|port.*out.*of.*range|port.*must.*be.*number)",
      "severity": "medium",
      "title": "Invalid Port Configuration",
      "description": "Configured port number is invalid",
      "causes": ["Port number not an integer", "Port out of range (1-65535)", "Reserved port number"],
      "fix_steps": ["Set port to valid range 1-65535", "Use port > 1024 for non-root", "Change to available port", "Update GATEWAY_PORT in openclaw.json"],
      "fix_recipe_id": "fix-port-change",
      "related_codes": ["INVALID_PORT"],
      "doc_url": "https://docs.openclaw.ai/configuration/gateway"
    },
    {
      "id": "cfg-005",
      "category": "configuration",
      "code": "SCHEMA_ERROR",
      "pattern": "(?i)(schema.*validation.*fail|validation.*error|does.*not.*match.*schema)",
      "severity": "high",
      "title": "Schema Validation Failed",
      "description": "Configuration does not match expected schema",
      "causes": ["Wrong data type", "Invalid value", "Missing nested property", "Extra unknown fields"],
      "fix_steps": ["Run: openclaw doctor --fix", "Compare with schema documentation", "Validate against JSON schema", "Check for deprecated fields"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["VALIDATION_ERROR"],
      "doc_url": "https://docs.openclaw.ai/configuration/schema"
    },
    {
      "id": "cfg-006",
      "category": "configuration",
      "code": "CONFIG_ERROR",
      "pattern": "(?i)(deprecated.*config|config.*key.*deprecated|obsolete.*setting)",
      "severity": "low",
      "title": "Deprecated Configuration Key",
      "description": "Configuration uses deprecated or obsolete keys",
      "causes": ["Old configuration format", "Migrated from previous version", "Outdated documentation"],
      "fix_steps": ["Review deprecation warnings", "Update to new configuration keys", "Run: openclaw doctor --fix", "Check migration guide"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["DEPRECATED"],
      "doc_url": "https://docs.openclaw.ai/migration"
    },
    {
      "id": "chan-001",
      "category": "channel",
      "code": "CHANNEL_ERROR",
      "pattern": "(?i)(whatsapp.*not.*link|whatsapp.*qr.*code|NOT_LINKED|scan.*qr.*code)",
      "severity": "high",
      "title": "WhatsApp Not Linked - QR Scan Required",
      "description": "WhatsApp channel requires QR code scanning to link device",
      "causes": ["New WhatsApp channel setup", "Session expired", "Device unlinked", "Credentials cleared"],
      "fix_steps": ["Run: openclaw channels whatsapp scan", "Scan QR code with WhatsApp mobile app", "Wait for connection confirmation", "Restart gateway after linking"],
      "fix_recipe_id": "fix-channel-whatsapp-relink",
      "related_codes": ["NOT_LINKED"],
      "doc_url": "https://docs.openclaw.ai/channels/whatsapp"
    },
    {
      "id": "chan-002",
      "category": "channel",
      "code": "CHANNEL_ERROR",
      "pattern": "(?i)(telegram.*invalid.*token|telegram.*bot.*token|telegram.*auth.*fail)",
      "severity": "critical",
      "title": "Telegram Invalid Bot Token",
      "description": "Telegram bot token is invalid or missing",
      "causes": ["Wrong bot token", "Token not set in configuration", "Bot deleted by BotFather", "Token revoked"],
      "fix_steps": ["Get valid token from @BotFather on Telegram", "Update TELEGRAM_BOT_TOKEN in openclaw.json", "Run: openclaw channels telegram setup", "Verify token format"],
      "fix_recipe_id": "fix-channel-telegram-token",
      "related_codes": ["INVALID_TOKEN"],
      "doc_url": "https://docs.openclaw.ai/channels/telegram"
    },
    {
      "id": "chan-003",
      "category": "channel",
      "code": "CHANNEL_ERROR",
      "pattern": "(?i)(discord.*bot.*permission|discord.*missing.*intent|discord.*unauthorized)",
      "severity": "high",
      "title": "Discord Bot Missing Permissions",
      "description": "Discord bot lacks required permissions or intents",
      "causes": ["Missing MESSAGE_CONTENT intent", "Insufficient bot permissions", "Bot not invited to server", "Role hierarchy issue"],
      "fix_steps": ["Enable MESSAGE_CONTENT intent in Discord Developer Portal", "Re-invite bot with correct permissions", "Check bot role permissions in server", "Verify bot token"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["PERMISSION_DENIED"],
      "doc_url": "https://docs.openclaw.ai/channels/discord"
    },
    {
      "id": "chan-004",
      "category": "channel",
      "code": "CHANNEL_ERROR",
      "pattern": "(?i)(slack.*bolt.*connection|slack.*socket.*mode|slack.*app.*token)",
      "severity": "high",
      "title": "Slack Bolt Connection Failed",
      "description": "Slack Bolt app failed to establish socket mode connection",
      "causes": ["Invalid app token", "Socket mode not enabled", "Missing bot token", "Network issue"],
      "fix_steps": ["Enable Socket Mode in Slack app settings", "Verify SLACK_APP_TOKEN and SLACK_BOT_TOKEN", "Check app installation in workspace", "Review app manifest scopes"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["CONNECTION_ERROR"],
      "doc_url": "https://docs.openclaw.ai/channels/slack"
    },
    {
      "id": "chan-005",
      "category": "channel",
      "code": "CHANNEL_ERROR",
      "pattern": "(?i)(signal.*cli.*missing|signal.*not.*install|signal.*daemon)",
      "severity": "critical",
      "title": "Signal CLI Not Installed",
      "description": "Signal channel requires signal-cli to be installed",
      "causes": ["signal-cli not installed", "signal-cli not in PATH", "signal-cli daemon not running"],
      "fix_steps": ["Install signal-cli: brew install signal-cli (macOS) or apt install signal-cli (Linux)", "Start signal-cli daemon", "Register phone number", "Link device"],
      "fix_recipe_id": "fix-openclaw-install",
      "related_codes": ["DEPENDENCY_MISSING"],
      "doc_url": "https://docs.openclaw.ai/channels/signal"
    },
    {
      "id": "chan-006",
      "category": "channel",
      "code": "CHANNEL_ERROR",
      "pattern": "(?i)(imessage.*macos.*only|imessage.*not.*supported|imessage.*platform)",
      "severity": "high",
      "title": "iMessage Channel macOS Only",
      "description": "iMessage channel is only supported on macOS",
      "causes": ["Running on non-macOS platform", "Messages app not available", "Not logged into iCloud"],
      "fix_steps": ["Use macOS device for iMessage channel", "Ensure Messages app is installed and configured", "Sign in to iCloud", "Enable iMessage in Settings"],
      "fix_recipe_id": null,
      "related_codes": ["PLATFORM_UNSUPPORTED"],
      "doc_url": "https://docs.openclaw.ai/channels/imessage"
    },
    {
      "id": "chan-007",
      "category": "channel",
      "code": "CHANNEL_ERROR",
      "pattern": "(?i)(teams.*plugin.*required|teams.*not.*install|teams.*missing)",
      "severity": "medium",
      "title": "Microsoft Teams Plugin Required",
      "description": "Teams channel requires additional plugin installation",
      "causes": ["Teams plugin not installed", "Plugin version incompatible", "Plugin not activated"],
      "fix_steps": ["Install Teams plugin: pnpm add @openclaw/channel-teams", "Enable plugin in openclaw.json", "Configure Teams app credentials", "Restart gateway"],
      "fix_recipe_id": "fix-openclaw-install",
      "related_codes": ["PLUGIN_MISSING"],
      "doc_url": "https://docs.openclaw.ai/channels/teams"
    },
    {
      "id": "chan-008",
      "category": "channel",
      "code": "CHANNEL_ERROR",
      "pattern": "(?i)(pairing.*code.*expired|pairing.*timeout|link.*code.*invalid)",
      "severity": "medium",
      "title": "Pairing Code Expired",
      "description": "Channel pairing code has expired or is invalid",
      "causes": ["Timeout waiting for pairing", "Code already used", "Code manually entered incorrectly"],
      "fix_steps": ["Generate new pairing code", "Complete pairing within time limit", "Verify code entry is correct", "Check for typos"],
      "fix_recipe_id": "fix-channel-whatsapp-relink",
      "related_codes": ["PAIRING_FAILED"],
      "doc_url": "https://docs.openclaw.ai/channels/pairing"
    },
    {
      "id": "box-001",
      "category": "sandbox",
      "code": "SANDBOX_ERROR",
      "pattern": "(?i)(docker.*not.*running|docker.*daemon.*not.*start|cannot.*connect.*docker)",
      "severity": "critical",
      "title": "Docker Not Running",
      "description": "Docker daemon is not running or accessible",
      "causes": ["Docker daemon stopped", "Docker not installed", "Permission denied to Docker socket", "Docker Desktop not started"],
      "fix_steps": ["Start Docker daemon: systemctl start docker (Linux) or Docker Desktop (macOS/Windows)", "Verify Docker installation: docker --version", "Check Docker socket permissions", "Add user to docker group"],
      "fix_recipe_id": "fix-docker-start",
      "related_codes": ["DOCKER_NOT_RUNNING"],
      "doc_url": "https://docs.openclaw.ai/sandbox/docker"
    },
    {
      "id": "box-002",
      "category": "sandbox",
      "code": "SANDBOX_ERROR",
      "pattern": "(?i)(container.*oom|out.*of.*memory|memory.*limit.*exceed|killed.*oom)",
      "severity": "high",
      "title": "Container Out of Memory",
      "description": "Sandbox container exceeded memory limit and was killed",
      "causes": ["Memory-intensive operation", "Memory limit too low", "Memory leak in agent code", "Large file processing"],
      "fix_steps": ["Increase container memory limit in openclaw.json", "Optimize agent code for memory usage", "Monitor memory with: docker stats", "Reset sandbox container"],
      "fix_recipe_id": "fix-sandbox-reset",
      "related_codes": ["OOM_KILLED"],
      "doc_url": "https://docs.openclaw.ai/sandbox/limits"
    },
    {
      "id": "box-003",
      "category": "sandbox",
      "code": "SANDBOX_ERROR",
      "pattern": "(?i)(sandbox.*timeout|execution.*timeout|container.*timeout)",
      "severity": "medium",
      "title": "Sandbox Execution Timeout",
      "description": "Sandbox operation exceeded time limit",
      "causes": ["Long-running operation", "Infinite loop in code", "Timeout value too low", "Network delay"],
      "fix_steps": ["Increase sandbox timeout in openclaw.json", "Optimize agent code execution", "Check for infinite loops", "Review operation complexity"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["TIMEOUT"],
      "doc_url": "https://docs.openclaw.ai/sandbox/timeouts"
    },
    {
      "id": "box-004",
      "category": "sandbox",
      "code": "SANDBOX_ERROR",
      "pattern": "(?i)(permission.*denied.*sandbox|sandbox.*access.*denied|container.*permission)",
      "severity": "high",
      "title": "Sandbox Permission Denied",
      "description": "Permission denied when accessing sandbox resources",
      "causes": ["File permission issue", "SELinux blocking", "Volume mount permission", "User namespace mapping"],
      "fix_steps": ["Check volume mount permissions", "Review SELinux policies", "Verify Docker user mapping", "Run: ls -la on workspace directory"],
      "fix_recipe_id": "fix-permissions-fix",
      "related_codes": ["PERMISSION_DENIED"],
      "doc_url": "https://docs.openclaw.ai/sandbox/permissions"
    },
    {
      "id": "box-005",
      "category": "sandbox",
      "code": "SANDBOX_ERROR",
      "pattern": "(?i)(workspace.*mount.*fail|volume.*mount.*error|bind.*mount.*fail)",
      "severity": "high",
      "title": "Workspace Mount Failed",
      "description": "Failed to mount workspace directory into sandbox",
      "causes": ["Directory doesn't exist", "Permission denied", "Path too long", "Special characters in path"],
      "fix_steps": ["Verify workspace directory exists", "Check directory permissions", "Avoid special characters in path", "Use absolute path"],
      "fix_recipe_id": "fix-permissions-fix",
      "related_codes": ["MOUNT_ERROR"],
      "doc_url": "https://docs.openclaw.ai/sandbox/workspace"
    },
    {
      "id": "inst-001",
      "category": "installation",
      "code": "INSTALL_ERROR",
      "pattern": "(?i)(node.*version.*too.*old|node.*version.*require|node.*22.*require)",
      "severity": "critical",
      "title": "Node.js Version Too Old",
      "description": "Node.js version is below required minimum (v22)",
      "causes": ["Old Node.js installation", "Using system Node.js", "Wrong Node.js version active"],
      "fix_steps": ["Install Node.js v22+: Use fnm or nvm", "Switch to correct version: fnm use 22", "Verify: node --version", "Update PATH if needed"],
      "fix_recipe_id": "fix-node-install",
      "related_codes": ["VERSION_MISMATCH"],
      "doc_url": "https://docs.openclaw.ai/installation/requirements"
    },
    {
      "id": "inst-002",
      "category": "installation",
      "code": "INSTALL_ERROR",
      "pattern": "(?i)(pnpm.*not.*found|pnpm.*command.*not.*found|pnpm.*missing)",
      "severity": "high",
      "title": "pnpm Not Installed",
      "description": "pnpm package manager is not installed",
      "causes": ["pnpm not installed globally", "pnpm not in PATH", "Using npm instead of pnpm"],
      "fix_steps": ["Install pnpm: npm install -g pnpm", "Or use: corepack enable pnpm", "Verify: pnpm --version", "Restart terminal"],
      "fix_recipe_id": "fix-pnpm-install",
      "related_codes": ["DEPENDENCY_MISSING"],
      "doc_url": "https://docs.openclaw.ai/installation/setup"
    },
    {
      "id": "inst-003",
      "category": "installation",
      "code": "INSTALL_ERROR",
      "pattern": "(?i)(openclaw.*not.*found|openclaw.*command.*not.*found|openclaw.*not.*install)",
      "severity": "critical",
      "title": "OpenClaw Not in PATH",
      "description": "openclaw command is not found in system PATH",
      "causes": ["openclaw not installed globally", "npm global bin not in PATH", "Installation failed", "Using wrong package manager"],
      "fix_steps": ["Install: npm install -g openclaw", "Add npm bin to PATH: export PATH=$PATH:$(npm bin -g)", "Verify: openclaw --version", "Restart terminal"],
      "fix_recipe_id": "fix-openclaw-install",
      "related_codes": ["COMMAND_NOT_FOUND"],
      "doc_url": "https://docs.openclaw.ai/installation"
    },
    {
      "id": "inst-004",
      "category": "installation",
      "code": "INSTALL_ERROR",
      "pattern": "(?i)(npm.*install.*fail|pnpm.*install.*error|dependency.*install.*fail)",
      "severity": "high",
      "title": "Dependency Installation Failed",
      "description": "Failed to install package dependencies",
      "causes": ["Network error", "Registry unreachable", "Dependency conflict", "Insufficient disk space"],
      "fix_steps": ["Clear cache: pnpm store prune", "Retry installation", "Check network connectivity", "Verify disk space", "Try: pnpm install --force"],
      "fix_recipe_id": "fix-openclaw-install",
      "related_codes": ["INSTALL_FAILED"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/installation"
    },
    {
      "id": "inst-005",
      "category": "installation",
      "code": "INSTALL_ERROR",
      "pattern": "(?i)(git.*not.*found|git.*command.*not.*found|git.*missing)",
      "severity": "medium",
      "title": "Git Not Installed",
      "description": "Git version control system is not installed",
      "causes": ["Git not installed", "Git not in PATH", "Minimal system installation"],
      "fix_steps": ["Install Git: apt install git (Linux) or brew install git (macOS)", "Verify: git --version", "Add to PATH if needed"],
      "fix_recipe_id": null,
      "related_codes": ["DEPENDENCY_MISSING"],
      "doc_url": "https://docs.openclaw.ai/installation/requirements"
    },
    {
      "id": "port-001",
      "category": "port",
      "code": "EADDRINUSE",
      "pattern": "(?i)(EADDRINUSE|address.*already.*in.*use|port.*already.*bound)",
      "severity": "high",
      "title": "Port Already in Use",
      "description": "Configured port is already bound by another process",
      "causes": ["Another OpenClaw instance running", "Different service using port", "Previous process not terminated"],
      "fix_steps": ["Find process: lsof -i :PORT or netstat -ano | findstr :PORT", "Kill process or change port", "Update GATEWAY_PORT in openclaw.json", "Restart gateway"],
      "fix_recipe_id": "fix-port-kill",
      "related_codes": ["PORT_IN_USE"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/ports"
    },
    {
      "id": "port-002",
      "category": "port",
      "code": "PORT_ERROR",
      "pattern": "(?i)(port.*bind.*error|failed.*to.*bind|bind.*EADDRINUSE)",
      "severity": "high",
      "title": "Failed to Bind Port",
      "description": "Unable to bind to specified port",
      "causes": ["Port already in use", "Permission denied", "Invalid port number", "Network interface issue"],
      "fix_steps": ["Check port availability", "Use port > 1024 for non-root", "Verify port in range 1-65535", "Change to different port"],
      "fix_recipe_id": "fix-port-change",
      "related_codes": ["BIND_ERROR"],
      "doc_url": "https://docs.openclaw.ai/configuration/gateway"
    },
    {
      "id": "port-003",
      "category": "port",
      "code": "EACCES",
      "pattern": "(?i)(EACCES.*port|permission.*denied.*port|port.*1024.*root)",
      "severity": "medium",
      "title": "Permission Denied on Port",
      "description": "Insufficient permissions to bind to port (ports < 1024 require root)",
      "causes": ["Using privileged port without root", "Port < 1024", "SELinux policy blocking"],
      "fix_steps": ["Use port > 1024", "Run as root (not recommended)", "Use port forwarding: iptables", "Change GATEWAY_PORT in openclaw.json"],
      "fix_recipe_id": "fix-port-change",
      "related_codes": ["PERMISSION_DENIED"],
      "doc_url": "https://docs.openclaw.ai/configuration/gateway"
    },
    {
      "id": "perm-001",
      "category": "permission",
      "code": "EACCES",
      "pattern": "(?i)(EACCES|permission.*denied|access.*denied|operation.*not.*permitted)",
      "severity": "high",
      "title": "File Permission Denied",
      "description": "Insufficient permissions to access file or directory",
      "causes": ["Wrong file ownership", "Incorrect permissions", "SELinux blocking", "Read-only filesystem"],
      "fix_steps": ["Check file permissions: ls -la", "Fix ownership: chown user:group file", "Fix permissions: chmod 644 file", "Check SELinux status"],
      "fix_recipe_id": "fix-permissions-fix",
      "related_codes": ["PERMISSION_DENIED"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/permissions"
    },
    {
      "id": "perm-002",
      "category": "permission",
      "code": "EACCES",
      "pattern": "(?i)(credentials.*dir.*not.*writable|cannot.*write.*credentials|credentials.*permission)",
      "severity": "critical",
      "title": "Credentials Directory Not Writable",
      "description": "Unable to write to credentials directory",
      "causes": ["Directory doesn't exist", "Permission denied", "Read-only mount", "Disk full"],
      "fix_steps": ["Create directory: mkdir -p ~/.openclaw/credentials", "Fix permissions: chmod 700 ~/.openclaw/credentials", "Verify disk space: df -h", "Check directory ownership"],
      "fix_recipe_id": "fix-permissions-fix",
      "related_codes": ["WRITE_ERROR"],
      "doc_url": "https://docs.openclaw.ai/configuration/credentials"
    },
    {
      "id": "perm-003",
      "category": "permission",
      "code": "PERMISSION_ERROR",
      "pattern": "(?i)(SYSTEM_RUN_DENIED|exec.*not.*allowed|command.*execution.*denied)",
      "severity": "high",
      "title": "System Command Execution Denied",
      "description": "Agent attempted to run system command without approval",
      "causes": ["Auto-approval disabled", "Command not whitelisted", "Security policy blocking", "Sandbox restriction"],
      "fix_steps": ["Enable auto-approval for trusted commands in openclaw.json", "Approve command manually when prompted", "Review security policy", "Check sandbox permissions"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["EXEC_DENIED"],
      "doc_url": "https://docs.openclaw.ai/security/approvals"
    },
    {
      "id": "perm-004",
      "category": "permission",
      "code": "APPROVAL_ERROR",
      "pattern": "(?i)(approval.*required|exec.*approval.*need|user.*approval.*pending)",
      "severity": "medium",
      "title": "User Approval Required",
      "description": "Operation requires explicit user approval before proceeding",
      "causes": ["Sensitive operation", "Auto-approval not configured", "Security policy", "First-time command"],
      "fix_steps": ["Approve the operation when prompted", "Enable auto-approval for trusted operations", "Review approval settings in openclaw.json", "Whitelist command if appropriate"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["APPROVAL_REQUIRED"],
      "doc_url": "https://docs.openclaw.ai/security/approvals"
    },
    {
      "id": "api-001",
      "category": "api",
      "code": "AGENT_TIMEOUT",
      "pattern": "(?i)(AGENT_TIMEOUT|agent.*timeout|agent.*unresponsive|agent.*hang)",
      "severity": "high",
      "title": "Agent Execution Timeout",
      "description": "Agent failed to respond within timeout period",
      "causes": ["Long-running operation", "Agent stuck", "Provider API slow", "Infinite loop"],
      "fix_steps": ["Increase agent timeout in openclaw.json", "Check agent logs for errors", "Optimize agent code", "Review provider latency"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["TIMEOUT"],
      "doc_url": "https://docs.openclaw.ai/agents/timeouts"
    },
    {
      "id": "api-002",
      "category": "api",
      "code": "503",
      "pattern": "(?i)(UNAVAILABLE|service.*unavailable|temporarily.*unavailable|503)",
      "severity": "high",
      "title": "Service Temporarily Unavailable",
      "description": "API service is temporarily unavailable",
      "causes": ["Provider maintenance", "Server overload", "Temporary outage", "Rate limiting"],
      "fix_steps": ["Wait and retry", "Check provider status page", "Implement exponential backoff", "Use fallback provider if configured"],
      "fix_recipe_id": "fix-gateway-restart",
      "related_codes": ["SERVICE_UNAVAILABLE"],
      "doc_url": "https://docs.openclaw.ai/troubleshooting/availability"
    },
    {
      "id": "api-003",
      "category": "api",
      "code": "400",
      "pattern": "(?i)(INVALID_REQUEST|invalid.*request|bad.*request|400)",
      "severity": "medium",
      "title": "Invalid API Request",
      "description": "API request is malformed or invalid",
      "causes": ["Invalid parameters", "Wrong request format", "Missing required fields", "Invalid JSON"],
      "fix_steps": ["Review request parameters", "Check API documentation", "Validate request format", "Review agent code"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["BAD_REQUEST"],
      "doc_url": "https://docs.openclaw.ai/api/requests"
    },
    {
      "id": "api-004",
      "category": "api",
      "code": "404",
      "pattern": "(?i)(model.*not.*found|unknown.*model|invalid.*model|404.*model)",
      "severity": "high",
      "title": "Model Not Found",
      "description": "Requested AI model is not available or doesn't exist",
      "causes": ["Model name typo", "Model deprecated", "Wrong provider", "Model not in account tier"],
      "fix_steps": ["Verify model name", "Check available models: openclaw models list", "Update model in openclaw.json", "Verify provider access"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["NOT_FOUND"],
      "doc_url": "https://docs.openclaw.ai/models/overview"
    },
    {
      "id": "api-005",
      "category": "api",
      "code": "413",
      "pattern": "(?i)(context.*window.*exceed|token.*limit.*exceed|payload.*too.*large|413)",
      "severity": "medium",
      "title": "Context Window Exceeded",
      "description": "Request exceeds model's context window limit",
      "causes": ["Too many tokens in prompt", "Large conversation history", "Big file attachment", "Context accumulation"],
      "fix_steps": ["Reduce prompt length", "Clear conversation history", "Use model with larger context window", "Implement context pruning"],
      "fix_recipe_id": "fix-config-validate",
      "related_codes": ["PAYLOAD_TOO_LARGE"],
      "doc_url": "https://docs.openclaw.ai/models/context-limits"
    }
  ]
}


path: data/fix-execution-history.json
content: {
  "executions": [],
  "success_rates": {}
}


path: data/fix-recipes.json
content: {
  "version": "1.0.0",
  "recipes": [
    {
      "id": "fix-auth-key",
      "title": "Reset API Authentication",
      "safe_auto": false,
      "description": "Reconfigure API key for the provider",
      "steps": [
        {
          "type": "command",
          "command": "openclaw models auth setup-token --provider {provider}",
          "description": "Interactive API key setup"
        }
      ],
      "rollback": null,
      "requires_restart": true
    },
    {
      "id": "fix-auth-env",
      "title": "Configure Environment Variable",
      "safe_auto": true,
      "description": "Guide to set missing API key environment variable",
      "steps": [
        {
          "type": "info",
          "message": "Set the {env_var} environment variable with your API key",
          "description": "Environment variable configuration needed"
        },
        {
          "type": "info",
          "message": "Add to .env file: {env_var}=your-api-key-here",
          "description": "Add to .env file for persistence"
        },
        {
          "type": "info",
          "message": "Or export temporarily: export {env_var}=your-api-key-here",
          "description": "Temporary shell export"
        }
      ],
      "rollback": null,
      "requires_restart": true
    },
    {
      "id": "fix-rate-wait",
      "title": "Rate Limit Wait Strategy",
      "safe_auto": true,
      "description": "Wait and retry with exponential backoff",
      "steps": [
        {
          "type": "info",
          "message": "Rate limit exceeded. Implementing backoff strategy",
          "description": "Rate limiting detected"
        },
        {
          "type": "info",
          "message": "Wait for Retry-After header duration or implement exponential backoff",
          "description": "Backoff recommendation"
        },
        {
          "type": "info",
          "message": "Consider upgrading provider tier or distributing load",
          "description": "Long-term solution"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-port-change",
      "title": "Change Gateway Port",
      "safe_auto": true,
      "description": "Update gateway port to an available port",
      "steps": [
        {
          "type": "config",
          "file": "openclaw.json",
          "path": "gateway.port",
          "value": 3001,
          "description": "Change port to 3001 (or next available)"
        },
        {
          "type": "info",
          "message": "Port updated. Use ports > 1024 to avoid permission issues",
          "description": "Port change guidance"
        }
      ],
      "rollback": {
        "type": "config",
        "file": "openclaw.json",
        "path": "gateway.port",
        "value": "{original_port}"
      },
      "requires_restart": true
    },
    {
      "id": "fix-port-kill",
      "title": "Kill Process on Port",
      "safe_auto": false,
      "description": "Terminate process using the required port",
      "steps": [
        {
          "type": "command",
          "command": "lsof -ti :{port} | xargs kill -9",
          "description": "Kill process on port (Unix/Linux/macOS)",
          "platforms": ["linux", "darwin"]
        },
        {
          "type": "command",
          "command": "netstat -ano | findstr :{port} && taskkill /PID <PID> /F",
          "description": "Kill process on port (Windows)",
          "platforms": ["win32"]
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-config-validate",
      "title": "Validate and Fix Configuration",
      "safe_auto": true,
      "description": "Run configuration validation and auto-fix",
      "steps": [
        {
          "type": "command",
          "command": "openclaw doctor --fix",
          "description": "Validate and auto-fix configuration issues"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-config-reset",
      "title": "Reset Configuration",
      "safe_auto": false,
      "description": "Backup current config and reset to defaults",
      "steps": [
        {
          "type": "command",
          "command": "cp openclaw.json openclaw.json.backup",
          "description": "Backup current configuration"
        },
        {
          "type": "command",
          "command": "openclaw init --force",
          "description": "Regenerate default configuration"
        },
        {
          "type": "info",
          "message": "Configuration reset. Previous config saved as openclaw.json.backup",
          "description": "Reset confirmation"
        }
      ],
      "rollback": {
        "type": "command",
        "command": "mv openclaw.json.backup openclaw.json"
      },
      "requires_restart": true
    },
    {
      "id": "fix-channel-whatsapp-relink",
      "title": "Re-link WhatsApp Channel",
      "safe_auto": false,
      "description": "Scan QR code to re-link WhatsApp device",
      "steps": [
        {
          "type": "command",
          "command": "openclaw channels whatsapp scan",
          "description": "Display QR code for WhatsApp linking"
        },
        {
          "type": "info",
          "message": "Scan QR code with WhatsApp mobile app (Settings > Linked Devices)",
          "description": "User action required"
        }
      ],
      "rollback": null,
      "requires_restart": true
    },
    {
      "id": "fix-channel-telegram-token",
      "title": "Update Telegram Bot Token",
      "safe_auto": false,
      "description": "Configure new Telegram bot token",
      "steps": [
        {
          "type": "info",
          "message": "Get bot token from @BotFather on Telegram",
          "description": "Obtain token from BotFather"
        },
        {
          "type": "command",
          "command": "openclaw channels telegram setup",
          "description": "Interactive Telegram bot setup"
        }
      ],
      "rollback": null,
      "requires_restart": true
    },
    {
      "id": "fix-docker-start",
      "title": "Start Docker Daemon",
      "safe_auto": false,
      "description": "Start Docker daemon for sandbox functionality",
      "steps": [
        {
          "type": "command",
          "command": "systemctl start docker",
          "description": "Start Docker daemon (Linux systemd)",
          "platforms": ["linux"]
        },
        {
          "type": "command",
          "command": "open -a Docker",
          "description": "Start Docker Desktop (macOS)",
          "platforms": ["darwin"]
        },
        {
          "type": "info",
          "message": "Start Docker Desktop from Start Menu (Windows)",
          "description": "Manual start required (Windows)",
          "platforms": ["win32"]
        },
        {
          "type": "command",
          "command": "docker ps",
          "description": "Verify Docker is running"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-docker-pull",
      "title": "Pull OpenClaw Sandbox Image",
      "safe_auto": true,
      "description": "Download latest OpenClaw sandbox Docker image",
      "steps": [
        {
          "type": "command",
          "command": "docker pull openclaw/sandbox:latest",
          "description": "Pull sandbox image from registry"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-node-install",
      "title": "Install Node.js v22+",
      "safe_auto": false,
      "description": "Install compatible Node.js version using fnm",
      "steps": [
        {
          "type": "command",
          "command": "fnm install 22",
          "description": "Install Node.js v22 via fnm"
        },
        {
          "type": "command",
          "command": "fnm use 22",
          "description": "Switch to Node.js v22"
        },
        {
          "type": "command",
          "command": "node --version",
          "description": "Verify Node.js version"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-pnpm-install",
      "title": "Install pnpm Package Manager",
      "safe_auto": true,
      "description": "Install pnpm globally",
      "steps": [
        {
          "type": "command",
          "command": "npm install -g pnpm",
          "description": "Install pnpm via npm"
        },
        {
          "type": "command",
          "command": "pnpm --version",
          "description": "Verify pnpm installation"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-openclaw-install",
      "title": "Install OpenClaw CLI",
      "safe_auto": true,
      "description": "Install openclaw command globally",
      "steps": [
        {
          "type": "command",
          "command": "npm install -g openclaw",
          "description": "Install openclaw globally via npm"
        },
        {
          "type": "command",
          "command": "openclaw --version",
          "description": "Verify openclaw installation"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-openclaw-update",
      "title": "Update OpenClaw CLI",
      "safe_auto": true,
      "description": "Update openclaw to latest version",
      "steps": [
        {
          "type": "command",
          "command": "npm update -g openclaw",
          "description": "Update openclaw to latest version"
        },
        {
          "type": "command",
          "command": "openclaw --version",
          "description": "Verify updated version"
        }
      ],
      "rollback": null,
      "requires_restart": true
    },
    {
      "id": "fix-permissions-fix",
      "title": "Fix File Permissions",
      "safe_auto": true,
      "description": "Correct file and directory permissions",
      "steps": [
        {
          "type": "command",
          "command": "mkdir -p ~/.openclaw/credentials",
          "description": "Ensure credentials directory exists"
        },
        {
          "type": "command",
          "command": "chmod 700 ~/.openclaw/credentials",
          "description": "Set secure permissions on credentials directory"
        },
        {
          "type": "command",
          "command": "chmod 600 ~/.openclaw/credentials/*",
          "description": "Set secure permissions on credential files"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-gateway-restart",
      "title": "Restart Gateway",
      "safe_auto": false,
      "description": "Stop and restart OpenClaw gateway",
      "steps": [
        {
          "type": "command",
          "command": "openclaw gateway stop",
          "description": "Stop gateway gracefully"
        },
        {
          "type": "command",
          "command": "openclaw gateway start",
          "description": "Start gateway with current configuration"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-gateway-force",
      "title": "Force Gateway Restart",
      "safe_auto": false,
      "description": "Force kill and restart gateway",
      "steps": [
        {
          "type": "command",
          "command": "pkill -9 -f 'openclaw gateway'",
          "description": "Force kill gateway process",
          "platforms": ["linux", "darwin"]
        },
        {
          "type": "command",
          "command": "taskkill /F /IM openclaw.exe",
          "description": "Force kill gateway process (Windows)",
          "platforms": ["win32"]
        },
        {
          "type": "command",
          "command": "openclaw gateway start --force",
          "description": "Force start gateway"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-sandbox-reset",
      "title": "Reset Sandbox Container",
      "safe_auto": false,
      "description": "Remove and recreate sandbox container",
      "steps": [
        {
          "type": "command",
          "command": "docker stop openclaw-sandbox",
          "description": "Stop sandbox container"
        },
        {
          "type": "command",
          "command": "docker rm openclaw-sandbox",
          "description": "Remove sandbox container"
        },
        {
          "type": "command",
          "command": "openclaw sandbox init",
          "description": "Reinitialize sandbox"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-network-dns",
      "title": "DNS Configuration Guidance",
      "safe_auto": true,
      "description": "Suggest DNS troubleshooting steps",
      "steps": [
        {
          "type": "info",
          "message": "Try using Google DNS (8.8.8.8) or Cloudflare DNS (1.1.1.1)",
          "description": "Alternative DNS servers"
        },
        {
          "type": "command",
          "command": "ping -c 3 8.8.8.8",
          "description": "Test basic network connectivity",
          "platforms": ["linux", "darwin"]
        },
        {
          "type": "command",
          "command": "ping -n 3 8.8.8.8",
          "description": "Test basic network connectivity (Windows)",
          "platforms": ["win32"]
        },
        {
          "type": "info",
          "message": "Update /etc/resolv.conf or network settings to use alternative DNS",
          "description": "DNS configuration location"
        }
      ],
      "rollback": null,
      "requires_restart": false
    },
    {
      "id": "fix-disk-cleanup",
      "title": "Cleanup Old Logs",
      "safe_auto": false,
      "description": "Remove old log files to free disk space",
      "steps": [
        {
          "type": "command",
          "command": "find ~/.openclaw/logs -name '*.log' -mtime +30 -delete",
          "description": "Delete logs older than 30 days",
          "platforms": ["linux", "darwin"]
        },
        {
          "type": "command",
          "command": "docker system prune -f",
          "description": "Clean up Docker resources"
        },
        {
          "type": "command",
          "command": "du -sh ~/.openclaw",
          "description": "Check OpenClaw directory size",
          "platforms": ["linux", "darwin"]
        }
      ],
      "rollback": null,
      "requires_restart": false
    }
  ]
}


path: data/integration-hooks.json
content: {
  "version": "1.0.0",
  "hooks": {
    "diagnostic_enhancement": {
      "debug-pro": {
        "enabled": false,
        "trigger_on": ["auto_fix_failed", "complex_stack_trace"],
        "action": "suggest_interactive_debugging",
        "priority": "HIGH",
        "install_command": "openclaw skills install debug-pro"
      },
      "docker-essentials": {
        "enabled": false,
        "trigger_on": ["sandbox_error", "container_timeout"],
        "action": "run_container_diagnostics",
        "priority": "HIGH",
        "install_command": "openclaw skills install docker-essentials"
      },
      "cognitive-memory": {
        "enabled": false,
        "trigger_on": ["recurring_error"],
        "action": "search_error_history",
        "priority": "HIGH",
        "install_command": "openclaw skills install cognitive-memory"
      }
    },
    "recovery_automation": {
      "evolver": {
        "enabled": false,
        "trigger_on": ["fix_applied", "low_success_rate"],
        "action": "track_fix_success_rate",
        "priority": "HIGH",
        "install_command": "openclaw skills install evolver"
      },
      "workflow-builder": {
        "enabled": false,
        "trigger_on": ["multi_step_fix_needed"],
        "action": "suggest_workflow_creation",
        "priority": "HIGH",
        "install_command": "openclaw skills install workflow-builder"
      },
      "multi-agent": {
        "enabled": false,
        "trigger_on": ["multi_channel_error"],
        "action": "coordinate_parallel_diagnostics",
        "priority": "HIGH",
        "install_command": "openclaw skills install multi-agent"
      }
    },
    "notifications": {
      "github": {
        "enabled": false,
        "trigger_on": ["unresolved_error", "new_error_pattern"],
        "action": "create_github_issue",
        "priority": "HIGH",
        "install_command": "openclaw skills install github"
      },
      "slack-integration": {
        "enabled": false,
        "trigger_on": ["critical_error", "team_environment"],
        "action": "send_slack_alert",
        "priority": "HIGH",
        "install_command": "openclaw skills install slack-integration"
      },
      "discord-bot": {
        "enabled": false,
        "trigger_on": ["community_help_needed"],
        "action": "post_to_discord",
        "priority": "MEDIUM",
        "install_command": "openclaw skills install discord-bot"
      }
    }
  }
}


path: references/authentication-errors.md
content: # Authentication Errors

Complete guide to diagnosing and fixing OpenClaw authentication issues.

## Error Types

### 401 Unauthorized

**Symptoms:**
- API requests return 401 status
- "Unauthorized" or "Invalid credentials" messages
- Gateway rejects AI provider requests

**Common Causes:**
- Missing API key in .env file
- Incorrect API key value
- API key not activated with provider
- Typo in environment variable name

**Diagnostic Commands:**
```bash
# Check if API keys are set
openclaw config get ai.provider.apiKey

# Verify environment variables
env | grep -i api_key

# Test provider connection
openclaw doctor --check-auth
```

**Fix:**
```bash
# Set API key via CLI
openclaw config set ai.openai.apiKey "sk-..."

# Or edit .env file
echo "OPENAI_API_KEY=sk-..." >> .env

# Restart gateway
openclaw restart
```

**Auto-Fix Available:** Yes
```bash
python3 scripts/error-fixer.py --error 401 --auto-fix
```

---

### INVALID_API_KEY

**Symptoms:**
- Error message: "API key format invalid"
- Provider returns authentication error
- Key validation fails

**Common Causes:**
- API key missing prefix (e.g., `sk-` for OpenAI)
- Extra whitespace or newlines in key
- Copy-paste truncation
- Wrong provider key used

**Diagnostic Commands:**
```bash
# Validate key format
python3 scripts/error-fixer.py --error INVALID_API_KEY --validate

# Check key length and prefix
openclaw config get ai.provider.apiKey | wc -c
```

**Fix:**
```bash
# Get new key from provider dashboard
# OpenAI: https://platform.openai.com/api-keys
# Anthropic: https://console.anthropic.com/settings/keys
# Google: https://makersuite.google.com/app/apikey

# Set correct key
openclaw config set ai.openai.apiKey "sk-proj-..."

# Clear any cached credentials
openclaw cache clear --auth
```

**Auto-Fix Available:** Yes (detects format issues)

---

### TOKEN_EXPIRED

**Symptoms:**
- "Token expired" error messages
- Authentication works initially then fails
- Intermittent 401 errors

**Common Causes:**
- Session token TTL exceeded
- Gateway token not refreshed
- Clock skew between client/server

**Diagnostic Commands:**
```bash
# Check token expiry
openclaw status --show-tokens

# Verify system time
date && curl -I https://www.google.com | grep Date
```

**Fix:**
```bash
# Refresh gateway token
openclaw auth refresh

# Or restart to get new token
openclaw restart

# Sync system time (if clock skew)
sudo ntpdate -s time.nist.gov  # Linux
```

**Auto-Fix Available:** Yes

---

### MISSING_ENV_VAR

**Symptoms:**
- Error: "Required environment variable not set"
- Config validation fails
- Provider initialization errors

**Common Causes:**
- .env file not loaded
- Variable name typo
- .env.example not copied to .env
- Running from wrong directory

**Required Variables:**
```
OPENAI_API_KEY          # For OpenAI
ANTHROPIC_API_KEY       # For Claude
GOOGLE_API_KEY          # For Gemini
GATEWAY_TOKEN           # For gateway auth
WHATSAPP_TOKEN          # For WhatsApp channel
TELEGRAM_BOT_TOKEN      # For Telegram
DISCORD_BOT_TOKEN       # For Discord
SLACK_BOT_TOKEN         # For Slack
```

**Diagnostic Commands:**
```bash
# Check which vars are missing
openclaw doctor --check-env

# List all expected vars
cat .env.example
```

**Fix:**
```bash
# Copy example and edit
cp .env.example .env
nano .env

# Or set individually
openclaw config set env.OPENAI_API_KEY "sk-..."

# Verify all required vars set
openclaw config validate
```

**Auto-Fix Available:** Partial (can template .env, user must add keys)

---

### GATEWAY_TOKEN_MISMATCH

**Symptoms:**
- Channel connections fail authentication
- Gateway rejects client requests
- "Token mismatch" error in logs

**Common Causes:**
- Different GATEWAY_TOKEN in .env vs running instance
- Gateway restarted with new token
- Multiple OpenClaw instances running
- Client using cached old token

**Diagnostic Commands:**
```bash
# Check running gateway token
openclaw status --show-gateway-token

# Compare with config
openclaw config get gateway.token

# Check for multiple instances
ps aux | grep openclaw
```

**Fix:**
```bash
# Stop all instances
killall openclaw

# Generate new token
openclaw auth generate-token

# Update all clients with new token
openclaw channels update-token

# Restart gateway
openclaw start
```

**Auto-Fix Available:** No (requires manual coordination)

---

## Prevention Best Practices

1. **Use .env file:** Don't hardcode keys in config
2. **Validate on start:** Enable `validateAuth: true` in config
3. **Rotate regularly:** Set up key rotation schedule
4. **Monitor expiry:** Use `openclaw status --watch` to track token TTL
5. **Secure storage:** Use secrets manager for production

## Quick Diagnostic Ladder

1. Run `openclaw doctor --check-auth`
2. Verify .env file exists and is loaded
3. Check API key format and prefix
4. Test provider connection directly
5. Review gateway logs: `openclaw logs --auth-only`
6. Validate system time sync
7. Clear auth cache and restart

## Related Files

- [Error Catalog](error-catalog.md) - All error types
- [Configuration Errors](configuration-errors.md) - Config issues
- [Diagnostic Commands](diagnostic-commands.md) - CLI reference


path: references/auto-fix-capabilities.md
content: # Auto-Fix Capabilities

Complete reference for automated error fixes in OpenClaw Doctor Pro.

## Fix Safety Levels

| Safety Level | Description | User Confirmation | Rollback Available |
|--------------|-------------|-------------------|-------------------|
| **Safe** | No risk, fully reversible | No | Yes |
| **Moderate** | Low risk, config changes only | Optional | Yes |
| **Risky** | Potential data impact | Required | Partial |
| **Manual** | Cannot auto-fix, guidance provided | N/A | N/A |

## Auto-Fix Recipes

### Authentication Errors

| Error | Fix Recipe | Safety | What It Does |
|-------|-----------|--------|--------------|
| 401 | Set API key from env | Safe | Reads API key from .env and sets in config |
| INVALID_API_KEY | Validate and prompt | Moderate | Validates format, prompts for new key if invalid |
| TOKEN_EXPIRED | Refresh token | Safe | Calls auth refresh endpoint |
| MISSING_ENV_VAR | Template .env file | Moderate | Creates .env from .env.example |
| GATEWAY_TOKEN_MISMATCH | Regenerate token | Risky | Generates new token, updates all channels |

**Commands:**
```bash
# Auto-fix auth errors
python3 scripts/error-fixer.py --error 401 --auto-fix
python3 scripts/error-fixer.py --category authentication --auto-fix

# With confirmation
python3 scripts/error-fixer.py --error GATEWAY_TOKEN_MISMATCH --auto-fix --confirm
```

---

### Rate Limiting Errors

| Error | Fix Recipe | Safety | What It Does |
|-------|-----------|--------|--------------|
| 429 | Enable retry strategy | Safe | Adds exponential backoff config |
| QUOTA_EXCEEDED | Enable fallback provider | Moderate | Switches to alternate provider |
| PROVIDER_THROTTLE | Reduce request rate | Safe | Lowers RPM in config |
| CONCURRENT_LIMIT | Reduce concurrency | Safe | Lowers max concurrent requests |
| BURST_LIMIT | Add burst protection | Safe | Enables rate limiting per second |

**Commands:**
```bash
# Auto-fix rate limits
python3 scripts/error-fixer.py --error 429 --auto-fix

# Apply recommended config
python3 scripts/error-fixer.py --error QUOTA_EXCEEDED --apply-recommended
```

**What Gets Changed:**
```yaml
# Before
ai:
  retryStrategy:
    enabled: false

# After (429 fix)
ai:
  retryStrategy:
    enabled: true
    maxRetries: 3
    backoffMs: 1000
    backoffMultiplier: 2
    jitter: true
```

---

### Gateway Errors

| Error | Fix Recipe | Safety | What It Does |
|-------|-----------|--------|--------------|
| 502 | Restart gateway | Safe | Executes `openclaw restart` |
| EADDRINUSE | Kill process on port | Moderate | Finds and kills process using port 18789 |
| ECONNREFUSED | Fix binding + restart | Moderate | Sets host to 0.0.0.0, restarts gateway |
| NETWORK_TIMEOUT | Increase timeouts | Safe | Raises timeout values in config |
| DNS_RESOLUTION | Set public DNS | Moderate | Configures 8.8.8.8 and 1.1.1.1 |

**Commands:**
```bash
# Auto-fix port conflict
python3 scripts/error-fixer.py --error EADDRINUSE --auto-fix

# Dry-run (show what would change)
python3 scripts/error-fixer.py --error ECONNREFUSED --auto-fix --dry-run
```

**EADDRINUSE Fix Process:**
```bash
# Step 1: Detect process
lsof -t -i:18789

# Step 2: Attempt graceful shutdown
kill -15 <PID>
sleep 2

# Step 3: Force kill if needed
kill -9 <PID>

# Step 4: Verify port free
lsof -i:18789 || echo "Port available"

# Step 5: Start gateway
openclaw start
```

---

### Channel Errors

| Error | Fix Recipe | Safety | What It Does |
|-------|-----------|--------|--------------|
| WHATSAPP_NOT_LINKED | Initiate linking | Manual | Guides through QR code linking |
| TELEGRAM_WEBHOOK_FAIL | Re-set webhook | Moderate | Calls Telegram API to set webhook |
| DISCORD_INVALID_PERMS | Generate invite URL | Safe | Creates invite with correct permissions |
| SLACK_BOLT_ERROR | Refresh tokens | Moderate | Regenerates OAuth tokens |
| SIGNAL_CLI_MISSING | Install Signal CLI | Risky | Downloads and installs Signal CLI binary |

**Commands:**
```bash
# Auto-fix Telegram webhook
python3 scripts/error-fixer.py --error TELEGRAM_WEBHOOK_FAIL --auto-fix

# Install Signal CLI
python3 scripts/error-fixer.py --error SIGNAL_CLI_MISSING --auto-fix --confirm
```

**SIGNAL_CLI_MISSING Fix Process:**
```bash
# Step 1: Detect OS
OS=$(uname -s)

# Step 2: Download binary
wget https://github.com/AsamK/signal-cli/releases/download/v0.11.11/signal-cli-0.11.11-Linux.tar.gz

# Step 3: Extract
tar xf signal-cli-*.tar.gz -C /opt

# Step 4: Symlink
sudo ln -sf /opt/signal-cli-*/bin/signal-cli /usr/local/bin/

# Step 5: Verify
signal-cli --version

# Step 6: Update config
openclaw config set channels.signal.cliPath "/usr/local/bin/signal-cli"
```

---

### Sandbox Errors

| Error | Fix Recipe | Safety | What It Does |
|-------|-----------|--------|--------------|
| DOCKER_NOT_RUNNING | Start Docker daemon | Risky | Executes `systemctl start docker` |
| CONTAINER_OOM | Increase memory limit | Safe | Raises memory limit to 2GB |
| SANDBOX_TIMEOUT | Increase timeout | Safe | Raises execution timeout to 5 minutes |
| WORKSPACE_MOUNT_FAIL | Create workspace dir | Moderate | Creates and sets permissions on workspace |
| PERMISSION_DENIED | Fix ownership | Moderate | Chowns workspace to UID 1000 |

**Commands:**
```bash
# Auto-fix memory issues
python3 scripts/error-fixer.py --error CONTAINER_OOM --auto-fix

# Fix workspace permissions
python3 scripts/error-fixer.py --error WORKSPACE_MOUNT_FAIL --auto-fix
```

**CONTAINER_OOM Fix Changes:**
```yaml
# Before
sandbox:
  memory:
    limit: "512MB"

# After
sandbox:
  memory:
    limit: "2GB"
    swap: "4GB"
  monitoring:
    memory:
      enabled: true
      alertThreshold: 85
```

---

### Configuration Errors

| Error | Fix Recipe | Safety | What It Does |
|-------|-----------|--------|--------------|
| CONFIG_SCHEMA_INVALID | Auto-correct schema | Safe | Fixes common YAML/JSON syntax errors |
| MISSING_REQUIRED_FIELD | Add with defaults | Safe | Adds missing fields with default values |
| INVALID_VALUE_TYPE | Convert types | Safe | Converts strings to numbers, booleans, etc. |
| DEPRECATED_KEY | Migrate config | Safe | Renames deprecated keys to new format |
| CONFIG_PARSE_ERROR | Restore backup | Moderate | Restores last known good config |

**Commands:**
```bash
# Auto-fix config issues
python3 scripts/error-fixer.py --error CONFIG_SCHEMA_INVALID --auto-fix

# Migrate deprecated keys
python3 scripts/error-fixer.py --error DEPRECATED_KEY --auto-fix
```

**Type Conversion Examples:**
```yaml
# Before (INVALID_VALUE_TYPE)
gateway:
  port: "18789"           # String
  cors:
    enabled: "true"       # String

# After (auto-fixed)
gateway:
  port: 18789             # Number
  cors:
    enabled: true         # Boolean
```

---

### Installation Errors

| Error | Fix Recipe | Safety | What It Does |
|-------|-----------|--------|--------------|
| NODE_VERSION_OLD | Guide NVM install | Manual | Provides installation commands |
| PNPM_NOT_FOUND | Install pnpm | Moderate | Runs `npm install -g pnpm` |
| NPM_INSTALL_FAILED | Clear cache + retry | Moderate | Clears npm cache, retries install |
| PATH_NOT_SET | Add to PATH | Moderate | Adds npm bin to shell profile |
| DEPENDENCY_CONFLICT | Use legacy peer deps | Safe | Retries with `--legacy-peer-deps` |

**Commands:**
```bash
# Auto-fix pnpm missing
python3 scripts/error-fixer.py --error PNPM_NOT_FOUND --auto-fix

# Fix PATH
python3 scripts/error-fixer.py --error PATH_NOT_SET --auto-fix
```

**PATH_NOT_SET Fix Process:**
```bash
# Step 1: Detect shell
SHELL_NAME=$(basename "$SHELL")

# Step 2: Get npm bin path
NPM_BIN=$(npm bin -g)

# Step 3: Add to profile
if [ "$SHELL_NAME" = "bash" ]; then
  echo 'export PATH="'$NPM_BIN':$PATH"' >> ~/.bashrc
  source ~/.bashrc
elif [ "$SHELL_NAME" = "zsh" ]; then
  echo 'export PATH="'$NPM_BIN':$PATH"' >> ~/.zshrc
  source ~/.zshrc
fi

# Step 4: Verify
which openclaw
```

---

## Batch Auto-Fix

### Fix All Safe Issues
```bash
# Auto-fix everything marked as "Safe"
python3 scripts/error-fixer.py --fix-all-safe

# Expected output:
# ✓ Fixed: SANDBOX_TIMEOUT (increased to 300s)
# ✓ Fixed: INVALID_VALUE_TYPE (converted 3 fields)
# ✓ Fixed: DEPRECATED_KEY (migrated 5 keys)
# ⚠ Skipped: GATEWAY_TOKEN_MISMATCH (requires confirmation)
# ⚠ Skipped: DOCKER_NOT_RUNNING (risky operation)
```

### Fix by Category
```bash
# Fix all authentication issues
python3 scripts/error-fixer.py --category authentication --auto-fix-safe

# Fix all configuration issues
python3 scripts/error-fixer.py --category configuration --auto-fix-safe

# Fix all sandbox issues
python3 scripts/error-fixer.py --category sandbox --auto-fix-safe
```

### Fix with Confirmation
```bash
# Fix moderate-risk items with prompts
python3 scripts/error-fixer.py --auto-fix-moderate --interactive

# Example interaction:
# ? Fix EADDRINUSE by killing process 12345? (y/N): y
# ✓ Killed process 12345
# ✓ Port 18789 now available
# ? Fix WORKSPACE_MOUNT_FAIL by creating directory? (y/N): y
# ✓ Created /home/user/.openclaw/workspace
# ✓ Set permissions to 755
```

## Rollback Support

### Automatic Backups
```bash
# All fixes create backups
python3 scripts/error-fixer.py --error CONFIG_SCHEMA_INVALID --auto-fix

# Backup created at:
# ~/.openclaw/backups/config-20260208-075230.yaml
```

### Manual Rollback
```bash
# List backups
python3 scripts/error-fixer.py --list-backups

# Rollback to specific backup
python3 scripts/error-fixer.py --rollback config-20260208-075230

# Rollback last fix
python3 scripts/error-fixer.py --undo-last
```

## Fix Logging

### View Fix History
```bash
# Show all fixes applied
python3 scripts/error-fixer.py --history

# Example output:
# 2026-02-08 07:52:30 - Fixed: CONTAINER_OOM
#   Changed: sandbox.memory.limit "512MB" → "2GB"
#   Backup: backups/config-20260208-075230.yaml
#
# 2026-02-08 07:45:15 - Fixed: DEPRECATED_KEY
#   Migrated: ai.openai.key → ai.providers.openai.apiKey
#   Backup: backups/config-20260208-074515.yaml
```

## Custom Fix Recipes

### Create Custom Fix
```yaml
# custom-fixes.yaml
fixes:
  - error: CUSTOM_ERROR
    safety: moderate
    description: "Fix my custom error"
    steps:
      - action: config_set
        key: my.custom.setting
        value: "fixed"
      - action: restart
        service: gateway
```

### Load Custom Fixes
```bash
python3 scripts/error-fixer.py --load-recipes custom-fixes.yaml
```

## Safety Guardrails

### What Can Be Auto-Fixed
- ✓ Configuration changes
- ✓ Restarting services
- ✓ Installing packages (with confirmation)
- ✓ Fixing file permissions (with confirmation)
- ✓ Clearing caches

### What Cannot Be Auto-Fixed
- ✗ Modifying .env secrets
- ✗ Changing firewall rules
- ✗ Editing system files
- ✗ Account-level changes (billing, quotas)
- ✗ Data deletion

### Confirmation Required For
- ⚠ Killing processes
- ⚠ Installing system packages
- ⚠ Modifying file permissions
- ⚠ Regenerating tokens
- ⚠ Starting/stopping Docker

## Best Practices

1. **Always dry-run first**: Use `--dry-run` to preview changes
2. **Review backups**: Check backup before rollback
3. **Fix incrementally**: Don't batch-fix everything at once
4. **Test after fixing**: Run `openclaw doctor` after fixes
5. **Keep history**: Don't clear fix history logs
6. **Use safe fixes**: Only use `--auto-fix-safe` in automation
7. **Confirm risky**: Always review risky operations manually

## Related Files

- [Error Catalog](error-catalog.md) - All errors and fix availability
- [Diagnostic Commands](diagnostic-commands.md) - Manual fix commands
- [Troubleshooting Workflow](troubleshooting-workflow.md) - When to auto-fix vs manual


path: references/channel-errors.md
content: # Channel Errors

Channel-specific troubleshooting for WhatsApp, Telegram, Discord, Slack, and Signal.

## WhatsApp Errors

### WHATSAPP_NOT_LINKED

**Symptoms:**
- "WhatsApp not linked" error
- QR code doesn't appear
- Phone scan succeeds but connection fails
- "Session invalid" messages

**Common Causes:**
- WhatsApp session expired
- Phone not connected to internet
- Multi-device limit reached (4 devices)
- Account banned/restricted

**Diagnostic Commands:**
```bash
# Check WhatsApp status
openclaw channels status whatsapp

# View session info
openclaw whatsapp session-info

# Test connection
openclaw whatsapp test-connection

# Generate new QR code
openclaw whatsapp qr-code
```

**Fix:**
```bash
# Re-link WhatsApp
openclaw whatsapp link

# Clear old session
openclaw whatsapp logout
rm -rf .openclaw/whatsapp-session
openclaw whatsapp link

# Check multi-device slots
# Open WhatsApp on phone → Linked Devices → Remove old devices

# If banned, contact WhatsApp support or use different number
```

**Auto-Fix Available:** No (requires phone interaction)

**Prevention:**
- Keep phone connected to internet
- Don't logout from gateway frequently
- Monitor session health: `openclaw whatsapp session-health`

---

### WHATSAPP_RATE_LIMIT

**Symptoms:**
- Messages delayed or not sent
- "Rate limit exceeded" warning
- WhatsApp API throttling

**Fix:**
```bash
# Reduce message rate
openclaw config set channels.whatsapp.rateLimit.messagesPerMinute 20

# Enable message queuing
openclaw config set channels.whatsapp.queueing.enabled true
```

---

## Telegram Errors

### TELEGRAM_WEBHOOK_FAIL

**Symptoms:**
- Webhook setup fails
- "Invalid webhook URL" error
- Messages not received
- Telegram API returns 400/401

**Common Causes:**
- Invalid bot token
- Webhook URL not HTTPS (if remote)
- Port not accessible from internet
- Bot token revoked

**Diagnostic Commands:**
```bash
# Check bot status
openclaw channels status telegram

# Test bot token
curl "https://api.telegram.org/bot<TOKEN>/getMe"

# View webhook info
openclaw telegram webhook-info

# Check current webhook
curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"
```

**Fix:**
```bash
# Re-set webhook (local mode)
openclaw telegram set-webhook --mode local

# For remote setup (needs HTTPS)
openclaw telegram set-webhook --url https://yourdomain.com/webhook/telegram

# Delete and recreate webhook
openclaw telegram delete-webhook
openclaw telegram set-webhook

# Use polling instead (fallback)
openclaw config set channels.telegram.mode polling
openclaw restart
```

**Auto-Fix Available:** Partial

---

### TELEGRAM_BOT_BLOCKED

**Symptoms:**
- "Bot was blocked by user" errors
- Cannot send messages to specific users

**Fix:**
- Users must /start the bot again
- Cannot be fixed from gateway side

---

## Discord Errors

### DISCORD_INVALID_PERMS

**Symptoms:**
- "Missing permissions" errors
- Cannot send messages in channels
- Cannot read message history
- Slash commands not working

**Required Permissions:**
- Read Messages/View Channels
- Send Messages
- Embed Links
- Attach Files
- Read Message History
- Use Slash Commands
- Add Reactions

**Diagnostic Commands:**
```bash
# Check bot permissions
openclaw channels status discord

# List missing permissions
openclaw discord check-permissions

# View bot role
openclaw discord bot-info
```

**Fix:**
```bash
# Generate invite with correct permissions
openclaw discord generate-invite

# Or manually in Discord:
# 1. Server Settings → Roles → Bot Role
# 2. Enable required permissions
# 3. Ensure role is above other roles

# Re-invite bot with correct scopes
# https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=515396&scope=bot%20applications.commands
```

**Auto-Fix Available:** No (requires Discord admin)

---

### DISCORD_GATEWAY_ERROR

**Symptoms:**
- "Discord gateway connection failed"
- Bot appears offline
- Events not received

**Fix:**
```bash
# Check intents enabled in Discord Developer Portal
# Required: GUILD_MESSAGES, DIRECT_MESSAGES, MESSAGE_CONTENT

# Update config
openclaw config set channels.discord.intents '["GUILDS", "GUILD_MESSAGES", "DIRECT_MESSAGES", "MESSAGE_CONTENT"]'

# Restart connection
openclaw channels restart discord
```

---

## Slack Errors

### SLACK_BOLT_ERROR

**Symptoms:**
- Slack Bolt framework errors
- Events not received
- "Failed to verify request" errors

**Common Causes:**
- Incorrect signing secret
- Request timestamp too old
- Bolt app not initialized
- OAuth token expired

**Diagnostic Commands:**
```bash
# Check Slack connection
openclaw channels status slack

# Test signing secret
openclaw slack verify-signing-secret

# View app manifest
openclaw slack app-info
```

**Fix:**
```bash
# Update signing secret
openclaw config set channels.slack.signingSecret "your-secret"

# Refresh OAuth token
openclaw slack refresh-token

# Reinstall app
openclaw slack reinstall

# Check event subscriptions in Slack App dashboard
# Events API → Request URL should be: https://yourdomain.com/webhook/slack
```

**Auto-Fix Available:** Partial

---

### SLACK_SCOPE_MISSING

**Symptoms:**
- "Missing OAuth scope" errors
- Cannot call certain API methods

**Required Scopes:**
- chat:write
- channels:history
- groups:history
- im:history
- mpim:history
- users:read
- files:write

**Fix:**
```bash
# Regenerate OAuth token with correct scopes
# 1. Go to Slack App dashboard
# 2. OAuth & Permissions → Add scopes
# 3. Reinstall app to workspace
# 4. Update token in OpenClaw

openclaw config set channels.slack.botToken "xoxb-new-token"
openclaw channels restart slack
```

---

## Signal Errors

### SIGNAL_CLI_MISSING

**Symptoms:**
- "Signal CLI not found" error
- Command not in PATH
- Signal channel won't start

**Diagnostic Commands:**
```bash
# Check if signal-cli installed
which signal-cli
signal-cli --version

# Check PATH
echo $PATH
```

**Fix:**
```bash
# Install signal-cli (Linux)
wget https://github.com/AsamK/signal-cli/releases/download/v0.11.11/signal-cli-0.11.11-Linux.tar.gz
tar xf signal-cli-0.11.11-Linux.tar.gz -C /opt
sudo ln -sf /opt/signal-cli-0.11.11/bin/signal-cli /usr/local/bin/

# Install via package manager
# Debian/Ubuntu
sudo apt install signal-cli

# macOS
brew install signal-cli

# Verify installation
signal-cli --version

# Register with Signal
signal-cli -u +1234567890 register
signal-cli -u +1234567890 verify CODE

# Configure OpenClaw
openclaw config set channels.signal.phone "+1234567890"
openclaw channels start signal
```

**Auto-Fix Available:** Yes (can guide installation)

---

### SIGNAL_REGISTRATION_FAILED

**Symptoms:**
- Cannot register phone number
- "Rate limit exceeded" during registration
- Verification code not received

**Fix:**
```bash
# Wait 24h if rate limited

# Use voice verification
signal-cli -u +1234567890 register --voice

# Try different number

# Check phone number format (+country code)
```

---

## General Channel Debugging

### Channel Status Overview
```bash
# List all channels
openclaw channels list

# Check status
openclaw channels status --all

# Restart specific channel
openclaw channels restart whatsapp

# View channel logs
openclaw logs --channel telegram --last 30m
```

### Common Issues All Channels

**Channel Not Starting:**
```bash
# Check config
openclaw config validate

# Check token/credentials
openclaw config get channels.CHANNEL.token

# Review logs
openclaw logs --channel CHANNEL --level error

# Restart channel
openclaw channels restart CHANNEL
```

**Messages Not Received:**
```bash
# Check webhook/polling status
openclaw channels webhook-status CHANNEL

# Test connection
openclaw channels test CHANNEL

# Enable verbose logging
openclaw config set channels.CHANNEL.logging.level debug
openclaw channels restart CHANNEL
```

**Messages Not Sent:**
```bash
# Check rate limits
openclaw status --rate-limits

# Check message queue
openclaw queue status --channel CHANNEL

# Verify permissions
openclaw channels check-permissions CHANNEL
```

## Channel Configuration Template

```yaml
channels:
  whatsapp:
    enabled: true
    sessionPath: ".openclaw/whatsapp-session"
    rateLimit:
      messagesPerMinute: 20

  telegram:
    enabled: true
    botToken: "${TELEGRAM_BOT_TOKEN}"
    mode: "webhook"  # or "polling"
    webhookUrl: "https://yourdomain.com/webhook/telegram"

  discord:
    enabled: true
    botToken: "${DISCORD_BOT_TOKEN}"
    intents: ["GUILDS", "GUILD_MESSAGES", "MESSAGE_CONTENT"]

  slack:
    enabled: true
    botToken: "${SLACK_BOT_TOKEN}"
    signingSecret: "${SLACK_SIGNING_SECRET}"
    appToken: "${SLACK_APP_TOKEN}"

  signal:
    enabled: true
    phone: "${SIGNAL_PHONE}"
    cliPath: "/usr/local/bin/signal-cli"
```

## Related Files

- [Error Catalog](error-catalog.md) - All error types
- [Configuration Errors](configuration-errors.md) - Config issues
- [Gateway Errors](gateway-errors.md) - Network issues


path: references/clawhub-integration.md
content: # ClawHub Integration

Complete guide to using ClawHub - the OpenClaw skill registry with 5,700+ skills.

## Overview

ClawHub is the central registry for OpenClaw skills. It provides:
- **5,700+ skills** across categories (AI, automation, utilities, integrations)
- **Skill discovery** via search and recommendations
- **Version management** and automatic updates
- **Publishing platform** for custom skills
- **Quality ratings** and community reviews

## Basic Commands

### Search Skills

```bash
# Search by keyword
openclaw skills search "image generation"
openclaw skills search "pdf"
openclaw skills search "automation"

# Search by category
openclaw skills search --category ai
openclaw skills search --category utilities

# Filter by rating
openclaw skills search "image" --min-rating 4.0

# Show details
openclaw skills search "image" --detailed
```

**Example Output:**
```
Found 15 skills matching "image":

1. image-generator-pro (⭐ 4.8, 2.3K installs)
   Generate images with DALL-E, Stable Diffusion, Midjourney
   openclaw skills install image-generator-pro

2. image-optimizer (⭐ 4.5, 1.5K installs)
   Compress and optimize images (PNG, JPG, WebP)
   openclaw skills install image-optimizer

3. image-to-text (⭐ 4.3, 890 installs)
   OCR and text extraction from images
   openclaw skills install image-to-text
```

### Install Skills

```bash
# Install by name
openclaw skills install image-generator-pro

# Install specific version
openclaw skills install image-generator-pro@2.1.0

# Install multiple skills
openclaw skills install image-gen pdf-tools automation-helper

# Install from URL (private/custom)
openclaw skills install https://github.com/user/custom-skill.git

# Install with dependencies
openclaw skills install skill-name --with-deps
```

### List Installed Skills

```bash
# List all installed
openclaw skills list

# Show details
openclaw skills list --detailed

# Filter by category
openclaw skills list --category ai

# Show outdated skills
openclaw skills list --outdated
```

**Example Output:**
```
Installed Skills (12):

✓ image-generator-pro (v2.1.0)  - AI
✓ pdf-tools (v1.5.2)            - Utilities
✓ automation-helper (v3.0.1)    - Automation
⚠ web-scraper (v1.2.0 → v1.3.0) - Utilities [UPDATE AVAILABLE]
✗ broken-skill (v0.5.0)         - Error: missing dependency
```

### Update Skills

```bash
# Update all skills
openclaw skills update

# Update specific skill
openclaw skills update image-generator-pro

# Check for updates only
openclaw skills check-updates

# Update with changelog
openclaw skills update --show-changelog
```

### Uninstall Skills

```bash
# Uninstall skill
openclaw skills uninstall image-generator-pro

# Uninstall with cleanup
openclaw skills uninstall skill-name --clean

# Uninstall multiple
openclaw skills uninstall skill1 skill2 skill3
```

## Skill Information

### View Skill Details

```bash
# Show full details
openclaw skills info image-generator-pro

# Show README
openclaw skills readme image-generator-pro

# Show changelog
openclaw skills changelog image-generator-pro

# Show dependencies
openclaw skills deps image-generator-pro
```

**Example Output:**
```
Skill: image-generator-pro
Version: 2.1.0
Author: ClawHub Community
Rating: ⭐⭐⭐⭐⭐ (4.8/5.0, 2,340 installs)
Category: AI
License: MIT

Description:
Generate images using DALL-E 3, Stable Diffusion XL, or Midjourney.
Supports batch generation, style presets, and custom parameters.

Features:
- Multiple AI providers (DALL-E, SD, Midjourney)
- Style presets (realistic, anime, sketch, etc.)
- Batch generation
- Image editing and variations
- Custom resolution up to 4K

Requirements:
- OpenAI API key (for DALL-E)
- Stability API key (for SD)
- Midjourney API key (for MJ)

Installation:
openclaw skills install image-generator-pro
```

### Check Skill Health

```bash
# Validate installed skills
openclaw skills check

# Validate specific skill
openclaw skills check image-generator-pro

# Fix broken skills
openclaw skills doctor --fix
```

## Skill Discovery

### Browse by Category

```bash
# List categories
openclaw skills categories

# Browse category
openclaw skills browse --category ai
openclaw skills browse --category automation
openclaw skills browse --category utilities
openclaw skills browse --category integrations
```

**Categories:**
- **AI**: Language models, image generation, embeddings
- **Automation**: Workflows, schedulers, triggers
- **Utilities**: File tools, converters, formatters
- **Integrations**: Third-party APIs, webhooks
- **Communication**: Email, SMS, notifications
- **Data**: Databases, analytics, visualization
- **Security**: Encryption, auth, scanning
- **Developer**: Code tools, testing, deployment

### Popular Skills

```bash
# Most popular
openclaw skills popular --top 20

# Trending this week
openclaw skills trending

# Recently updated
openclaw skills recent
```

### Recommended Skills

```bash
# Auto-detect and recommend
openclaw skills recommend

# Recommend for specific channel
openclaw skills recommend --channel whatsapp

# Recommend for use case
openclaw skills recommend --use-case "customer support"
```

**Example Recommendations:**
```
Recommended Skills for WhatsApp:

Essential:
- whatsapp-media-handler - Handle images, videos, docs
- message-formatter - Rich formatting for messages
- qr-code-generator - Generate QR codes

Suggested:
- auto-responder - Automated responses
- translation-tool - Multi-language support
- analytics-tracker - Message analytics

Install all: openclaw skills install whatsapp-media-handler message-formatter qr-code-generator
```

## Publishing Skills

### Create Skill

```bash
# Generate skill template
openclaw skills create my-awesome-skill

# Interactive wizard
openclaw skills create --interactive
```

**Template Structure:**
```
my-awesome-skill/
├── SKILL.md           # Manifest
├── README.md          # Documentation
├── script.py          # Main script
├── config.yaml        # Configuration
├── requirements.txt   # Dependencies
└── tests/            # Tests
```

### Validate Skill

```bash
# Validate before publishing
openclaw skills validate my-awesome-skill/

# Test locally
openclaw skills test-local my-awesome-skill/
```

### Publish to ClawHub

```bash
# Login to ClawHub
openclaw skills login

# Publish skill
openclaw skills publish my-awesome-skill/

# Publish with version
openclaw skills publish my-awesome-skill/ --version 1.0.0

# Publish with changelog
openclaw skills publish my-awesome-skill/ --changelog "Initial release"
```

### Update Published Skill

```bash
# Publish update
openclaw skills publish my-awesome-skill/ --version 1.1.0

# Deprecate old version
openclaw skills deprecate my-awesome-skill@1.0.0

# Unpublish (use with caution)
openclaw skills unpublish my-awesome-skill
```

## Skill Management

### Sync with ClawHub

```bash
# Sync skill catalog
openclaw skills sync

# Force refresh cache
openclaw skills sync --force

# Sync specific category
openclaw skills sync --category ai
```

### Skill Configuration

```bash
# Configure skill
openclaw skills config image-gen set provider "dall-e"

# View skill config
openclaw skills config image-gen show

# Reset skill config
openclaw skills config image-gen reset
```

### Skill Execution

```bash
# Run skill manually
openclaw skills run image-gen --prompt "a cat"

# Run with parameters
openclaw skills run pdf-tools --input doc.pdf --output out.pdf

# Run in background
openclaw skills run long-task --async
```

## Advanced Usage

### Private Skill Registry

```bash
# Add private registry
openclaw skills registry add my-company https://skills.company.com

# Set default registry
openclaw skills registry use my-company

# Install from specific registry
openclaw skills install skill-name --registry my-company

# List registries
openclaw skills registry list
```

### Skill Dependencies

```bash
# Show dependency tree
openclaw skills deps image-gen --tree

# Install missing dependencies
openclaw skills install-deps image-gen

# Check for conflicts
openclaw skills check-conflicts
```

### Skill Versioning

```bash
# List versions
openclaw skills versions image-gen

# Install specific version
openclaw skills install image-gen@2.0.0

# Rollback to previous
openclaw skills rollback image-gen

# Pin version (prevent updates)
openclaw skills pin image-gen@2.0.0
```

## ClawHub API Integration

### Search API

```bash
# Search with filters
openclaw skills search "image" \
  --category ai \
  --min-rating 4.0 \
  --min-installs 100 \
  --sort-by popularity
```

### Automation

```bash
# Auto-install recommended skills
openclaw skills recommend --auto-install

# Schedule updates
openclaw skills update --schedule "0 2 * * *"  # 2 AM daily

# Backup skill list
openclaw skills list --json > skills-backup.json

# Restore from backup
openclaw skills install-from-list skills-backup.json
```

## Skill Quality Guidelines

### Rating System
- ⭐⭐⭐⭐⭐ (5.0) - Exceptional quality, well-maintained
- ⭐⭐⭐⭐ (4.0) - Good quality, recommended
- ⭐⭐⭐ (3.0) - Average, usable with minor issues
- ⭐⭐ (2.0) - Below average, use with caution
- ⭐ (1.0) - Poor quality, not recommended

### Quality Indicators
```bash
# Check skill quality
openclaw skills quality-check image-gen

Quality Report:
✓ Active maintenance (updated 2 weeks ago)
✓ High rating (4.8/5.0)
✓ Well documented
✓ Has tests
✓ Good community support (50+ reviews)
⚠ Large dependency tree (15 deps)
✗ No CI/CD configured
```

## Troubleshooting

### Installation Issues

```bash
# Clear cache
openclaw skills cache clear

# Reinstall skill
openclaw skills uninstall skill-name
openclaw skills install skill-name

# Install with verbose output
openclaw skills install skill-name --verbose
```

### Broken Skills

```bash
# Diagnose issues
openclaw skills doctor

# Fix broken dependencies
openclaw skills doctor --fix-deps

# Rebuild skill
openclaw skills rebuild skill-name
```

### Network Issues

```bash
# Use mirror registry
openclaw skills registry use mirror

# Offline mode (use cache)
openclaw skills list --offline

# Export/import for airgapped systems
openclaw skills export skill-name > skill.tar.gz
openclaw skills import skill.tar.gz
```

## Best Practices

1. **Regular Updates**: Run `openclaw skills update` weekly
2. **Pin Critical Skills**: Use `openclaw skills pin` for production
3. **Review Ratings**: Check ratings before installing
4. **Read Documentation**: Use `openclaw skills readme` before use
5. **Test Before Production**: Use `openclaw skills test-local`
6. **Monitor Dependencies**: Run `openclaw skills check-conflicts` regularly
7. **Backup Skill List**: Export installed skills periodically
8. **Use Recommendations**: Let system recommend relevant skills

## Popular Skills by Category

### AI & Machine Learning
- `image-generator-pro` - Multi-provider image generation
- `text-embeddings` - Generate text embeddings
- `sentiment-analyzer` - Sentiment analysis
- `translation-ai` - Neural machine translation

### Automation
- `workflow-builder` - Visual workflow automation
- `scheduler-pro` - Advanced task scheduling
- `auto-responder` - Smart auto-responses
- `batch-processor` - Batch operations

### Utilities
- `pdf-toolkit` - PDF manipulation
- `image-optimizer` - Image compression
- `file-converter` - Format conversion
- `qr-code-tools` - QR code generation/scanning

### Integrations
- `google-workspace` - Google Workspace integration
- `slack-connector` - Slack integration
- `github-integration` - GitHub automation
- `zapier-bridge` - Zapier compatibility

## Related Files

- [Error Catalog](error-catalog.md) - Skill-related errors
- [Diagnostic Commands](diagnostic-commands.md) - Skill commands
- [Auto-Fix Capabilities](auto-fix-capabilities.md) - Skill auto-fixes


path: references/configuration-errors.md
content: # Configuration Errors

Complete guide to OpenClaw configuration validation and common config issues.

## Error Types

### CONFIG_SCHEMA_INVALID

**Symptoms:**
- "Configuration schema validation failed" error
- Gateway won't start
- Config file rejected
- Schema mismatch messages

**Common Causes:**
- Invalid YAML/JSON syntax
- Wrong data types
- Missing required fields
- Unknown configuration keys

**Diagnostic Commands:**
```bash
# Validate config
openclaw config validate

# Show schema
openclaw config schema

# Check syntax
yamllint ~/.openclaw/config.yaml
jsonlint ~/.openclaw/config.json

# View config with validation
openclaw config show --validate
```

**Fix:**
```bash
# Auto-fix common issues
openclaw config fix --auto

# Reset to defaults
openclaw config reset

# Merge with defaults (keeps your values)
openclaw config merge --with-defaults

# Validate specific section
openclaw config validate --section gateway
```

**Common Syntax Errors:**
```yaml
# Wrong: mixing tabs and spaces
gateway:
	port: 18789  # tab used
  host: "0.0.0.0"  # spaces used

# Correct: consistent indentation
gateway:
  port: 18789
  host: "0.0.0.0"

# Wrong: unquoted special characters
description: Hello: World

# Correct: quoted strings
description: "Hello: World"

# Wrong: invalid boolean
enabled: yes  # use true/false

# Correct: proper boolean
enabled: true
```

**Auto-Fix Available:** Yes

---

### MISSING_REQUIRED_FIELD

**Symptoms:**
- "Required field missing" error
- Config validation fails
- Gateway fails to start
- Feature doesn't work

**Required Fields:**
```yaml
# Minimum required config
gateway:
  port: 18789          # Required
  host: "0.0.0.0"      # Required

ai:
  defaultProvider: "openai"  # Required
  providers:
    openai:
      [REDACTED_SECRET]"       # Required if provider enabled

channels: {}  # Can be empty but must exist
```

**Diagnostic Commands:**
```bash
# List missing fields
openclaw config validate --show-missing

# Check specific section
openclaw config validate --section ai.providers.openai

# Show required fields
openclaw config schema --required-only
```

**Fix:**
```bash
# Add missing field
openclaw config set gateway.port 18789

# Set from environment variable
openclaw config set ai.openai.apiKey "${OPENAI_API_KEY}"

# Use interactive wizard
openclaw config wizard --missing-only

# Generate complete config from template
openclaw config init --template full
```

**Auto-Fix Available:** Partial (can add with default values)

---

### INVALID_VALUE_TYPE

**Symptoms:**
- "Invalid value type" error
- Type mismatch in config
- Number passed as string or vice versa
- Array expected but object provided

**Common Type Errors:**
```yaml
# Wrong: port as string
gateway:
  port: "18789"

# Correct: port as number
gateway:
  port: 18789

# Wrong: boolean as string
channels:
  whatsapp:
    enabled: "true"

# Correct: boolean as boolean
channels:
  whatsapp:
    enabled: true

# Wrong: array as single value
ai:
  providers: "openai"

# Correct: array of values
ai:
  providers: ["openai", "anthropic"]

# Wrong: object as string
sandbox:
  memory: "2GB"

# Correct: object with proper structure
sandbox:
  memory:
    limit: "2GB"
```

**Diagnostic Commands:**
```bash
# Show type errors
openclaw config validate --show-types

# Get expected type
openclaw config schema --field gateway.port

# Show example values
openclaw config examples --field ai.timeout
```

**Fix:**
```bash
# Auto-convert types
openclaw config fix --convert-types

# Set with correct type
openclaw config set gateway.port 18789 --type number
openclaw config set channels.whatsapp.enabled true --type boolean

# View and fix interactively
openclaw config edit --validate-on-save
```

**Auto-Fix Available:** Yes

---

### DEPRECATED_KEY

**Symptoms:**
- "Deprecated configuration key" warning
- Feature still works but warns
- Migration needed message

**Common Deprecated Keys:**
```yaml
# Deprecated (old v1.x format)
ai:
  openai:
    key: "sk-..."

# New (v2.x format)
ai:
  providers:
    openai:
      [REDACTED_SECRET]"

# Deprecated
gateway:
  apiPort: 18789

# New
gateway:
  port: 18789

# Deprecated
channels:
  telegram:
    polling: true

# New
channels:
  telegram:
    mode: "polling"
```

**Diagnostic Commands:**
```bash
# List deprecated keys
openclaw config validate --show-deprecated

# Show migration path
openclaw config migrate --dry-run

# View changelog
openclaw changelog --config-changes
```

**Fix:**
```bash
# Auto-migrate to new format
openclaw config migrate --backup

# Manually remove deprecated keys
openclaw config unset ai.openai.key
openclaw config set ai.providers.openai.apiKey "sk-..."

# Use migration wizard
openclaw config migrate --interactive
```

**Auto-Fix Available:** Yes

---

### CONFIG_PARSE_ERROR

**Symptoms:**
- "Cannot parse configuration file" error
- YAML/JSON syntax error
- Gateway won't start
- Config file corrupted

**Common Parse Errors:**
```yaml
# Missing closing quote
description: "Hello World

# Extra comma (JSON)
{"port": 18789,}

# Tab instead of spaces in YAML
gateway:
→port: 18789

# Duplicate keys
gateway:
  port: 18789
gateway:
  host: "0.0.0.0"

# Invalid character
gateway:
  port: 18789@
```

**Diagnostic Commands:**
```bash
# Parse and show errors
openclaw config parse ~/.openclaw/config.yaml

# Validate syntax only
yamllint ~/.openclaw/config.yaml

# Pretty-print to find issues
openclaw config show --format json | jq .
```

**Fix:**
```bash
# Restore from backup
openclaw config restore --from-backup

# Reset to last known good
openclaw config reset --keep-backup

# Fix syntax errors
openclaw config fix --syntax

# Edit with validation
openclaw config edit --validate-on-save

# If all else fails, start fresh
mv ~/.openclaw/config.yaml ~/.openclaw/config.yaml.broken
openclaw config init
```

**Auto-Fix Available:** No (manual syntax fixing needed)

---

### ENV_VAR_NOT_FOUND

**Symptoms:**
- "Environment variable not found" error
- Config references ${VAR} but VAR not set
- Substitution fails

**Example:**
```yaml
# Config references env var
ai:
  providers:
    openai:
      [REDACTED_SECRET]"  # Error if not set
```

**Diagnostic Commands:**
```bash
# Check which env vars are referenced
openclaw config show --show-env-refs

# Validate env vars
openclaw config validate --check-env

# List missing vars
openclaw doctor --check-env
```

**Fix:**
```bash
# Set environment variable
export OPENAI_API_KEY="sk-..."

# Or add to .env file
echo "OPENAI_API_KEY=sk-..." >> .env

# Use direct value instead
openclaw config set ai.providers.openai.apiKey "sk-..." --no-env

# Set default for missing var
openclaw config set-default OPENAI_API_KEY "default-value"
```

**Auto-Fix Available:** Partial

---

## Configuration Best Practices

### File Structure
```yaml
# ~/.openclaw/config.yaml
gateway:
  port: 18789
  host: "0.0.0.0"
  cors:
    enabled: true
    origins: ["*"]

ai:
  defaultProvider: "openai"
  providers:
    openai:
      [REDACTED_SECRET]"
      model: "gpt-4"
      timeout: 60000

    anthropic:
      [REDACTED_SECRET]"
      model: "claude-3-sonnet-20240229"

  retryStrategy:
    enabled: true
    maxRetries: 3

channels:
  whatsapp:
    enabled: true
    sessionPath: ".openclaw/whatsapp-session"

  telegram:
    enabled: true
    botToken: "${TELEGRAM_BOT_TOKEN}"
    mode: "webhook"

sandbox:
  enabled: true
  image: "python:3.11-slim"
  memory:
    limit: "2GB"
  timeout:
    execution: 300000
```

### Environment Variables (.env)
```bash
# .env file
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
TELEGRAM_BOT_TOKEN=...
DISCORD_BOT_TOKEN=...
SLACK_BOT_TOKEN=...
GATEWAY_TOKEN=...
```

### Configuration Management

```bash
# View current config
openclaw config show

# Edit config
openclaw config edit

# Set single value
openclaw config set gateway.port 18790

# Get single value
openclaw config get gateway.port

# Unset value (use default)
openclaw config unset gateway.cors.enabled

# Validate before applying
openclaw config validate

# Backup config
openclaw config backup

# Restore from backup
openclaw config restore

# Export config
openclaw config export --output config-backup.yaml

# Import config
openclaw config import --input config-backup.yaml
```

### Config Validation Workflow

```
1. Edit config file
   ↓
2. Validate syntax: openclaw config validate
   ↓
3. Check required fields: openclaw config validate --show-missing
   ↓
4. Fix type errors: openclaw config fix --convert-types
   ↓
5. Migrate deprecated: openclaw config migrate
   ↓
6. Test config: openclaw config test
   ↓
7. Apply: openclaw restart
```

### Schema Documentation

```bash
# View full schema
openclaw config schema

# Get field description
openclaw config schema --field gateway.port

# Show examples
openclaw config examples

# Export schema
openclaw config schema --format json > schema.json
```

## Common Configuration Patterns

### Multi-Provider Setup
```yaml
ai:
  defaultProvider: "openai"
  fallback:
    enabled: true
    providers: ["anthropic", "google"]

  providers:
    openai:
      [REDACTED_SECRET]"
      priority: 1

    anthropic:
      [REDACTED_SECRET]"
      priority: 2

    google:
      [REDACTED_SECRET]"
      priority: 3
```

### High Availability Setup
```yaml
gateway:
  cluster:
    enabled: true
    instances: 3
    loadBalancing: "round-robin"

  healthCheck:
    enabled: true
    interval: 10000
    timeout: 5000
```

### Development vs Production
```yaml
# config.dev.yaml
sandbox:
  enabled: true
  network:
    enabled: true  # Allow network in dev

# config.prod.yaml
sandbox:
  enabled: true
  network:
    enabled: false  # Isolate in prod
  memory:
    limit: "4GB"    # More resources
```

```bash
# Use specific config
openclaw start --config config.prod.yaml
```

## Related Files

- [Error Catalog](error-catalog.md) - All error types
- [Authentication Errors](authentication-errors.md) - Auth config
- [Channel Errors](channel-errors.md) - Channel config
- [Sandbox Errors](sandbox-errors.md) - Sandbox config


path: references/diagnostic-commands.md
content: # Diagnostic Commands

Quick reference for all OpenClaw CLI diagnostic and troubleshooting commands.

## System Health

| Command | Description | Example Output |
|---------|-------------|----------------|
| `openclaw doctor` | Run comprehensive health check | Overall status + issues found |
| `openclaw doctor --full` | Extended diagnostics with all checks | Detailed component status |
| `openclaw doctor --check-auth` | Verify API authentication | Auth status per provider |
| `openclaw doctor --check-env` | Check environment variables | Missing/invalid env vars |
| `openclaw status` | Show gateway and service status | Running/stopped + uptime |
| `openclaw status --watch` | Monitor status continuously | Real-time status updates |
| `openclaw status --detailed` | Detailed status with metrics | CPU/memory/connections |

## Configuration

| Command | Description | Example |
|---------|-------------|---------|
| `openclaw config show` | Display current configuration | Full config YAML |
| `openclaw config get <key>` | Get specific config value | `openclaw config get gateway.port` |
| `openclaw config set <key> <value>` | Set config value | `openclaw config set gateway.port 18790` |
| `openclaw config validate` | Validate configuration | Schema validation result |
| `openclaw config validate --show-missing` | List missing required fields | Required fields not set |
| `openclaw config schema` | Show config schema | Full schema with types |
| `openclaw config edit` | Open config in editor | Opens $EDITOR |
| `openclaw config reset` | Reset to defaults | Backup + restore defaults |
| `openclaw config migrate` | Migrate deprecated keys | Update to new format |

## Gateway Management

| Command | Description | Example |
|---------|-------------|---------|
| `openclaw start` | Start gateway | Daemon mode |
| `openclaw start --foreground` | Start in foreground | Verbose output |
| `openclaw stop` | Stop gateway | Graceful shutdown |
| `openclaw restart` | Restart gateway | Stop + start |
| `openclaw status` | Check if running | PID + port + uptime |
| `openclaw logs` | View gateway logs | Recent log entries |
| `openclaw logs --follow` | Stream logs live | Continuous output |
| `openclaw logs --level error` | Filter by log level | Errors only |
| `openclaw logs --last 30m` | Logs from time period | Last 30 minutes |

## Channel Management

| Command | Description | Example |
|---------|-------------|---------|
| `openclaw channels list` | List all channels | Status + config |
| `openclaw channels status` | Show channel status | Connected/disconnected |
| `openclaw channels status --all` | Status of all channels | All channels overview |
| `openclaw channels enable <name>` | Enable channel | `openclaw channels enable whatsapp` |
| `openclaw channels disable <name>` | Disable channel | `openclaw channels disable telegram` |
| `openclaw channels restart <name>` | Restart channel | Reconnect channel |
| `openclaw channels test <name>` | Test channel connection | Connection test result |

### WhatsApp Commands

| Command | Description |
|---------|-------------|
| `openclaw whatsapp link` | Link WhatsApp account |
| `openclaw whatsapp qr-code` | Show QR code for linking |
| `openclaw whatsapp logout` | Unlink WhatsApp |
| `openclaw whatsapp session-info` | Show session details |
| `openclaw whatsapp test-connection` | Test WhatsApp connection |

### Telegram Commands

| Command | Description |
|---------|-------------|
| `openclaw telegram set-webhook` | Configure webhook |
| `openclaw telegram delete-webhook` | Remove webhook |
| `openclaw telegram webhook-info` | Show webhook status |

### Discord Commands

| Command | Description |
|---------|-------------|
| `openclaw discord generate-invite` | Generate bot invite URL |
| `openclaw discord check-permissions` | Verify bot permissions |
| `openclaw discord bot-info` | Show bot details |

### Slack Commands

| Command | Description |
|---------|-------------|
| `openclaw slack verify-signing-secret` | Test signing secret |
| `openclaw slack refresh-token` | Refresh OAuth token |
| `openclaw slack reinstall` | Reinstall app |

## AI Provider Management

| Command | Description | Example |
|---------|-------------|---------|
| `openclaw providers list` | List configured providers | All providers + status |
| `openclaw providers test <name>` | Test provider connection | `openclaw providers test openai` |
| `openclaw providers status` | Show provider health | Connected/rate limits |
| `openclaw quota show` | Display API quota usage | Usage per provider |
| `openclaw quota status` | Check quota limits | Remaining quota |

## Sandbox Management

| Command | Description | Example |
|---------|-------------|---------|
| `openclaw sandbox stats` | Show sandbox metrics | CPU/memory/disk usage |
| `openclaw sandbox exec <cmd>` | Execute in sandbox | `openclaw sandbox exec -- python script.py` |
| `openclaw sandbox history` | Show execution history | Recent executions |
| `openclaw sandbox restart` | Restart sandbox container | Stop + start |

## Skill Management (ClawHub)

| Command | Description | Example |
|---------|-------------|---------|
| `openclaw skills list` | List installed skills | Installed skills |
| `openclaw skills search <query>` | Search ClawHub | `openclaw skills search "image"` |
| `openclaw skills install <name>` | Install skill | `openclaw skills install image-gen` |
| `openclaw skills uninstall <name>` | Remove skill | `openclaw skills uninstall skill-name` |
| `openclaw skills update` | Update all skills | Check + update |
| `openclaw skills sync` | Sync with ClawHub | Refresh catalog |
| `openclaw skills check` | Verify skills | Validation status |

## Plugin Management

| Command | Description | Example |
|---------|-------------|---------|
| `openclaw plugins list` | List installed plugins | All plugins |
| `openclaw plugins doctor` | Check plugin health | Validation + errors |
| `openclaw plugins reload <name>` | Reload plugin | Hot reload |

## Logging and Debugging

| Command | Description | Filters |
|---------|-------------|---------|
| `openclaw logs` | View all logs | Default: last 100 lines |
| `openclaw logs --follow` | Stream logs | Live updates |
| `openclaw logs --level <level>` | Filter by level | debug/info/warn/error |
| `openclaw logs --channel <name>` | Channel-specific logs | `--channel whatsapp` |
| `openclaw logs --filter <text>` | Text search | `--filter "401"` |
| `openclaw logs --last <time>` | Time period | `--last 1h`, `--last 30m` |
| `openclaw logs --json` | JSON output | Machine-readable |
| `openclaw logs --auth-only` | Auth logs only | Authentication events |
| `openclaw logs --sandbox-only` | Sandbox logs only | Execution logs |

## Performance Monitoring

| Command | Description | Output |
|---------|-------------|--------|
| `openclaw status --metrics` | Show performance metrics | CPU/mem/requests |
| `openclaw benchmark --provider <name>` | Test provider latency | Response times |
| `openclaw analytics --metric <name>` | View analytics | Usage statistics |
| `openclaw requests --status <status>` | List active requests | Pending/running/failed |

## Network Diagnostics

| Command | Description | Use Case |
|---------|-------------|----------|
| `openclaw status --provider-health` | Check provider connectivity | Network issues |
| `openclaw connections --active` | Show active connections | Connection debugging |
| `openclaw connections reset` | Reset all connections | Fix stuck connections |

## Cache Management

| Command | Description | Use Case |
|---------|-------------|----------|
| `openclaw cache clear` | Clear all caches | Fix stale data |
| `openclaw cache clear --auth` | Clear auth cache | Auth issues |
| `openclaw cache status` | Show cache stats | Cache size/hits |

## Backup and Restore

| Command | Description | Example |
|---------|-------------|---------|
| `openclaw config backup` | Backup configuration | Creates timestamped backup |
| `openclaw config restore` | Restore from backup | Latest backup |
| `openclaw config export --output <file>` | Export config | `--output backup.yaml` |
| `openclaw config import --input <file>` | Import config | `--input backup.yaml` |

## Alerts and Notifications

| Command | Description | Example |
|---------|-------------|---------|
| `openclaw alerts list` | List configured alerts | All alerts |
| `openclaw alerts add --metric <metric>` | Create alert | `--metric quota --threshold 80` |
| `openclaw alerts remove <id>` | Delete alert | Alert ID |

## Version and Updates

| Command | Description | Output |
|---------|-------------|--------|
| `openclaw --version` | Show version | Current version |
| `openclaw version --check-updates` | Check for updates | Latest version available |
| `openclaw changelog` | View changelog | Recent changes |

## Diagnostic Workflow Examples

### Gateway Won't Start
```bash
# 1. Check what's running
openclaw status

# 2. Check port availability
lsof -i :18789

# 3. Review logs for errors
openclaw logs --level error --last 5m

# 4. Validate configuration
openclaw config validate

# 5. Run health check
openclaw doctor --full
```

### Authentication Issues
```bash
# 1. Check auth configuration
openclaw doctor --check-auth

# 2. Verify environment variables
openclaw doctor --check-env

# 3. Test provider connection
openclaw providers test openai

# 4. View auth-related logs
openclaw logs --auth-only --last 1h
```

### Channel Not Working
```bash
# 1. Check channel status
openclaw channels status whatsapp

# 2. Test channel connection
openclaw channels test whatsapp

# 3. View channel logs
openclaw logs --channel whatsapp --last 30m

# 4. Check permissions (Discord)
openclaw discord check-permissions

# 5. Restart channel
openclaw channels restart whatsapp
```

### Performance Issues
```bash
# 1. Check metrics
openclaw status --metrics

# 2. View active requests
openclaw requests --status pending

# 3. Check sandbox stats
openclaw sandbox stats

# 4. Benchmark providers
openclaw benchmark --provider openai --samples 10

# 5. Review rate limits
openclaw status --rate-limits
```

### Quota/Rate Limit Issues
```bash
# 1. Check quota status
openclaw quota show

# 2. View rate limit events
openclaw logs --filter "429" --last 24h

# 3. Check provider status
openclaw providers status

# 4. View usage analytics
openclaw analytics --metric quota --last 7d
```

## Quick Troubleshooting Commands

```bash
# All-in-one health check
openclaw doctor --full

# System overview
openclaw status --detailed

# Recent errors
openclaw logs --level error --last 1h

# Validate everything
openclaw config validate && \
openclaw channels status --all && \
openclaw providers status

# Full diagnostic report
openclaw doctor --full > diagnostic-report.txt
openclaw status --detailed >> diagnostic-report.txt
openclaw logs --last 1h >> diagnostic-report.txt
```

## Output Formats

Most commands support output formatting:

```bash
# JSON output
openclaw status --json

# YAML output
openclaw config show --format yaml

# Table output
openclaw channels list --format table

# Minimal output
openclaw status --quiet
```

## Related Files

- [Error Catalog](error-catalog.md) - All error types
- [Troubleshooting Workflow](troubleshooting-workflow.md) - Decision trees
- [Auto-Fix Capabilities](auto-fix-capabilities.md) - Automated fixes


path: references/error-catalog.md
content: # Error Catalog

Master index of all OpenClaw error types with diagnostic and fix information.

## Error Categories

| Code | Severity | Description | Auto-Fix |
|------|----------|-------------|----------|
| **Authentication Errors** |
| 401 | High | Unauthorized - Invalid or missing API key | Yes |
| INVALID_API_KEY | High | API key format invalid or not recognized | Yes |
| TOKEN_EXPIRED | Medium | Authentication token has expired | Yes |
| MISSING_ENV_VAR | High | Required environment variable not set | Partial |
| GATEWAY_TOKEN_MISMATCH | High | Gateway token doesn't match config | No |
| **Rate Limiting Errors** |
| 429 | Medium | Too many requests - rate limit exceeded | No |
| QUOTA_EXCEEDED | High | API quota limit reached | No |
| PROVIDER_THROTTLE | Medium | Provider-side throttling active | No |
| CONCURRENT_LIMIT | Medium | Too many concurrent requests | Yes |
| BURST_LIMIT | Low | Short-term burst limit exceeded | No |
| **Gateway Errors** |
| 502 | High | Bad gateway - upstream connection failed | Partial |
| EADDRINUSE | High | Port 18789 already in use | Yes |
| ECONNREFUSED | High | Connection refused by gateway | Partial |
| NETWORK_TIMEOUT | Medium | Network request timeout | No |
| DNS_RESOLUTION | Medium | Cannot resolve hostname | No |
| **Channel Errors** |
| WHATSAPP_NOT_LINKED | High | WhatsApp not linked to gateway | No |
| TELEGRAM_WEBHOOK_FAIL | High | Telegram webhook setup failed | Partial |
| DISCORD_INVALID_PERMS | Medium | Discord bot missing permissions | No |
| SLACK_BOLT_ERROR | Medium | Slack Bolt framework error | Partial |
| SIGNAL_CLI_MISSING | High | Signal CLI not installed | Yes |
| **Sandbox Errors** |
| DOCKER_NOT_RUNNING | High | Docker daemon not running | No |
| CONTAINER_OOM | High | Container out of memory | Partial |
| SANDBOX_TIMEOUT | Medium | Sandbox execution timeout | Yes |
| WORKSPACE_MOUNT_FAIL | High | Cannot mount workspace volume | No |
| PERMISSION_DENIED | High | Sandbox permission denied | Partial |
| **Configuration Errors** |
| CONFIG_SCHEMA_INVALID | High | Config doesn't match schema | Yes |
| MISSING_REQUIRED_FIELD | High | Required config field missing | Partial |
| INVALID_VALUE_TYPE | Medium | Config value has wrong type | Yes |
| DEPRECATED_KEY | Low | Using deprecated config key | Yes |
| CONFIG_PARSE_ERROR | High | Cannot parse config file | No |
| **Installation Errors** |
| NODE_VERSION_OLD | High | Node.js version < 22 required | No |
| PNPM_NOT_FOUND | High | pnpm not installed or not in PATH | No |
| NPM_INSTALL_FAILED | High | npm/pnpm install failed | Partial |
| PATH_NOT_SET | Medium | OpenClaw not in system PATH | Yes |
| DEPENDENCY_CONFLICT | Medium | Package dependency conflict | No |
| **Plugin Errors** |
| PLUGIN_LOAD_FAILED | High | Plugin failed to load | Partial |
| PLUGIN_INIT_ERROR | High | Plugin initialization error | No |
| PLUGIN_VERSION_MISMATCH | Medium | Plugin incompatible with OpenClaw version | No |
| PLUGIN_MISSING_DEPS | High | Plugin dependencies not installed | Yes |
| PLUGIN_CONFIG_INVALID | Medium | Plugin config invalid | Partial |
| **Skill Errors** |
| SKILL_NOT_FOUND | Medium | Requested skill not installed | Yes |
| SKILL_EXEC_TIMEOUT | Medium | Skill execution timeout | Yes |
| SKILL_MANIFEST_INVALID | High | Skill manifest parse error | No |
| CLAWHUB_UNREACHABLE | Medium | Cannot connect to ClawHub | No |
| SKILL_INSTALL_FAILED | High | Skill installation failed | Partial |
| **System Errors** |
| DISK_FULL | Critical | Disk space exhausted | No |
| MEMORY_EXHAUSTED | Critical | System out of memory | No |
| FILE_NOT_FOUND | Medium | Required file missing | Partial |
| PERMISSION_ERROR | High | File system permission denied | No |
| PROCESS_CRASH | Critical | OpenClaw process crashed | No |

## Severity Levels

- **Critical**: System cannot function, immediate action required
- **High**: Major functionality broken, needs urgent fix
- **Medium**: Partial functionality impaired, fix recommended
- **Low**: Minor issue, cosmetic or deprecated feature

## Auto-Fix Capabilities

- **Yes**: Fully automated fix available
- **Partial**: Some aspects can be auto-fixed, manual steps may be needed
- **No**: Requires manual intervention

## Usage

Use error-fixer.py to diagnose and fix:

```bash
# By error code
python3 scripts/error-fixer.py --error 401

# By category
python3 scripts/error-fixer.py --category authentication

# Auto-fix when available
python3 scripts/error-fixer.py --error EADDRINUSE --auto-fix
```

See individual error category files for detailed diagnostics and fixes.


path: references/gateway-errors.md
content: # Gateway Errors

Complete guide to diagnosing and fixing OpenClaw gateway networking issues.

## Error Types

### 502 Bad Gateway

**Symptoms:**
- HTTP 502 status from gateway
- "Bad gateway" or "upstream error" messages
- Channels cannot connect to gateway
- Intermittent connection failures

**Common Causes:**
- Gateway service crashed or not running
- Upstream AI provider unreachable
- Network connectivity issues
- Reverse proxy misconfiguration

**Diagnostic Ladder:**
```bash
# Step 1: Check if gateway is running
openclaw status

# Step 2: Test gateway port
curl http://localhost:18789/health

# Step 3: Check upstream connectivity
curl -I https://api.openai.com/v1/models

# Step 4: Review gateway logs
openclaw logs --level error --last 10m

# Step 5: Test with verbose output
openclaw start --verbose --foreground
```

**Fix:**
```bash
# If gateway not running
openclaw start

# If gateway crashed, restart
openclaw restart

# If upstream unreachable, check network
ping api.openai.com
traceroute api.openai.com

# If reverse proxy issue, check config
nginx -t  # For nginx
apache2ctl configtest  # For Apache

# If persistent, rebuild
openclaw rebuild
```

**Auto-Fix Available:** Partial (can restart gateway)

---

### EADDRINUSE

**Symptoms:**
- Error: "Address already in use"
- "Port 18789 is already in use"
- Gateway fails to start
- Cannot bind to port

**Common Causes:**
- Previous OpenClaw instance still running
- Another service using port 18789
- Zombie process holding port
- Docker container port conflict

**Diagnostic Commands:**
```bash
# Find what's using port 18789
lsof -i :18789              # Linux/macOS
netstat -ano | findstr 18789  # Windows

# Check for openclaw processes
ps aux | grep openclaw

# Check Docker containers
docker ps | grep 18789
```

**Fix:**
```bash
# Option 1: Kill process using port
kill $(lsof -t -i:18789)

# Option 2: Use different port
openclaw config set gateway.port 18790
openclaw restart

# Option 3: Stop all OpenClaw instances
openclaw stop --all
killall openclaw
openclaw start

# Option 4: Stop Docker containers
docker stop $(docker ps -q --filter "expose=18789")
```

**Auto-Fix Available:** Yes
```bash
python3 scripts/error-fixer.py --error EADDRINUSE --auto-fix
```

---

### ECONNREFUSED

**Symptoms:**
- "Connection refused" error
- Cannot connect to localhost:18789
- Gateway appears running but unreachable
- Channel connections fail

**Common Causes:**
- Gateway bound to wrong interface (127.0.0.1 vs 0.0.0.0)
- Firewall blocking port 18789
- Gateway listening but not accepting connections
- SELinux/AppArmor blocking connections

**Diagnostic Commands:**
```bash
# Check gateway binding
netstat -tulpn | grep 18789
ss -tulpn | grep 18789

# Test local connection
curl http://127.0.0.1:18789/health
curl http://localhost:18789/health
curl http://0.0.0.0:18789/health

# Check firewall
sudo ufw status          # Linux
sudo firewall-cmd --list-all  # RHEL/CentOS

# Check if process listening
openclaw status --detailed
```

**Fix:**
```bash
# Bind to all interfaces
openclaw config set gateway.host "0.0.0.0"
openclaw restart

# Allow firewall
sudo ufw allow 18789/tcp          # Linux
sudo firewall-cmd --add-port=18789/tcp --permanent  # RHEL

# Disable SELinux temporarily (testing only)
sudo setenforce 0

# Check logs for binding errors
openclaw logs --filter="bind" --last 5m
```

**Auto-Fix Available:** Partial

---

### NETWORK_TIMEOUT

**Symptoms:**
- Requests time out waiting for response
- "Request timeout" errors
- Gateway slow to respond
- Channels report timeout

**Common Causes:**
- Slow AI provider response
- Network congestion
- Timeout setting too low
- Gateway under heavy load

**Diagnostic Commands:**
```bash
# Measure response times
time curl http://localhost:18789/health

# Check gateway load
openclaw status --metrics

# Test provider latency
openclaw benchmark --provider openai

# Monitor active requests
openclaw requests --status pending
```

**Fix:**
```bash
# Increase timeout
openclaw config set gateway.timeout.requestMs 60000
openclaw config set gateway.timeout.responseMs 120000

# Increase AI provider timeout
openclaw config set ai.timeout.requestMs 90000

# Enable request queuing
openclaw config set gateway.queueing.enabled true

# Reduce concurrent load
openclaw config set gateway.concurrency.max 50

# Scale gateway (if using cluster)
openclaw scale --instances 3
```

**Auto-Fix Available:** No (requires tuning)

---

### DNS_RESOLUTION

**Symptoms:**
- "Cannot resolve hostname" errors
- "getaddrinfo ENOTFOUND" messages
- Gateway cannot reach AI providers
- Network requests fail with DNS errors

**Common Causes:**
- DNS server unreachable
- /etc/resolv.conf misconfigured
- Corporate firewall blocking DNS
- VPN interfering with DNS

**Diagnostic Commands:**
```bash
# Test DNS resolution
nslookup api.openai.com
dig api.openai.com
host api.anthropic.com

# Check DNS config
cat /etc/resolv.conf

# Test with different DNS
nslookup api.openai.com 8.8.8.8
```

**Fix:**
```bash
# Use public DNS temporarily
openclaw config set gateway.dns.servers '["8.8.8.8", "1.1.1.1"]'

# Fix system DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

# Use IP addresses (emergency only)
openclaw config set ai.openai.endpoint "https://13.107.21.200/v1"

# Check VPN/proxy
openclaw config set gateway.proxy.enabled false

# Flush DNS cache
sudo systemd-resolve --flush-caches  # Linux
sudo dscacheutil -flushcache         # macOS
ipconfig /flushdns                   # Windows
```

**Auto-Fix Available:** No (system-level issue)

---

## Gateway Health Monitoring

### Health Check Endpoint
```bash
# Basic health
curl http://localhost:18789/health

# Detailed status
curl http://localhost:18789/health/detailed

# Provider connectivity
curl http://localhost:18789/health/providers

# Expected response
{
  "status": "healthy",
  "uptime": 3600,
  "providers": {
    "openai": "connected",
    "anthropic": "connected"
  },
  "channels": {
    "whatsapp": "active",
    "telegram": "active"
  }
}
```

### Continuous Monitoring
```bash
# Watch health status
watch -n 5 'curl -s http://localhost:18789/health | jq'

# Monitor logs
openclaw logs --follow --level warn

# Set up alerts
openclaw alerts add --metric gateway_health --action restart
```

## Network Diagnostic Workflow

```
Gateway won't start?
├─ Check port 18789 in use? → Kill process or change port
├─ Check gateway process running? → Start gateway
└─ Check logs for errors → Review and fix

Gateway unreachable?
├─ Test localhost:18789/health → Fix binding/firewall
├─ Check if listening on 0.0.0.0 → Update config
└─ Check firewall/SELinux → Allow port

Requests timing out?
├─ Check gateway load → Scale or reduce concurrency
├─ Test provider latency → Increase timeout
└─ Monitor active requests → Enable queuing

Cannot reach providers?
├─ Test DNS resolution → Fix DNS config
├─ Check network connectivity → Fix routing/proxy
└─ Verify API endpoints → Update endpoints
```

## Performance Tuning

```yaml
gateway:
  port: 18789
  host: "0.0.0.0"

  timeout:
    requestMs: 60000
    responseMs: 120000
    keepAliveMs: 5000

  concurrency:
    max: 100
    perChannel: 20

  queueing:
    enabled: true
    maxSize: 1000

  monitoring:
    healthCheck: true
    metricsInterval: 10000
```

## Related Files

- [Error Catalog](error-catalog.md) - All error types
- [Channel Errors](channel-errors.md) - Channel-specific issues
- [Diagnostic Commands](diagnostic-commands.md) - CLI reference
- [Installation Errors](installation-errors.md) - Setup issues


path: references/installation-errors.md
content: # Installation Errors

Complete guide to OpenClaw installation and setup issues across all platforms.

## Error Types

### NODE_VERSION_OLD

**Symptoms:**
- "Node.js version 22 or higher required" error
- Installation fails with version check
- Features not working (using old syntax)
- npm/pnpm errors about unsupported version

**Diagnostic Commands:**
```bash
# Check Node.js version
node --version

# Check npm version
npm --version

# Check if nvm installed
nvm --version
```

**Fix:**

**Linux:**
```bash
# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22

# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version  # Should show v22.x.x
```

**macOS:**
```bash
# Using nvm
brew install nvm
nvm install 22
nvm use 22

# Or using Homebrew directly
brew install node@22
brew link --overwrite node@22

# Verify
node --version
```

**Windows:**
```powershell
# Download from nodejs.org
# Or use nvm-windows
choco install nvm
nvm install 22
nvm use 22

# Or use official installer
# https://nodejs.org/dist/v22.0.0/node-v22.0.0-x64.msi

# Verify
node --version
```

**Auto-Fix Available:** No (requires system-level install)

---

### PNPM_NOT_FOUND

**Symptoms:**
- "pnpm: command not found" error
- Installation script fails
- Cannot run OpenClaw commands

**Diagnostic Commands:**
```bash
# Check if pnpm installed
which pnpm
pnpm --version

# Check PATH
echo $PATH | tr ':' '\n' | grep pnpm
```

**Fix:**

**All Platforms:**
```bash
# Install pnpm via npm (recommended)
npm install -g pnpm

# Or via standalone script
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Or via Homebrew (macOS)
brew install pnpm

# Or via Chocolatey (Windows)
choco install pnpm

# Verify
pnpm --version
```

**Fix PATH if needed:**
```bash
# Linux/macOS
echo 'export PATH="$HOME/.local/share/pnpm:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Windows (PowerShell as Admin)
$env:Path += ";$env:LOCALAPPDATA\pnpm"
[Environment]::SetEnvironmentVariable("Path", $env:Path, "User")
```

**Auto-Fix Available:** No (requires package manager)

---

### NPM_INSTALL_FAILED

**Symptoms:**
- "npm install failed" or "pnpm install failed"
- Dependency resolution errors
- Network timeout during install
- Permission errors during install

**Common Causes:**
- Network connectivity issues
- Registry timeout
- Permission denied (installing globally without sudo)
- Disk space full
- Corrupted package cache

**Diagnostic Commands:**
```bash
# Check disk space
df -h

# Check npm registry
npm config get registry
ping registry.npmjs.org

# Check cache
npm cache verify
pnpm store status

# Test network
curl -I https://registry.npmjs.org
```

**Fix:**

**Network Issues:**
```bash
# Use different registry
npm config set registry https://registry.npmmirror.com  # China mirror
pnpm config set registry https://registry.npmmirror.com

# Increase timeout
npm config set timeout 60000
pnpm config set network-timeout 60000

# Use corporate proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
```

**Permission Issues:**
```bash
# Fix npm permissions (Linux/macOS)
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

# Or use sudo (not recommended)
sudo npm install -g openclaw

# Fix ownership
sudo chown -R $USER:$USER ~/.npm
sudo chown -R $USER:$USER ~/.pnpm-store
```

**Cache Issues:**
```bash
# Clear npm cache
npm cache clean --force

# Clear pnpm cache
pnpm store prune

# Remove node_modules and retry
rm -rf node_modules package-lock.json
npm install
```

**Dependency Conflicts:**
```bash
# Use legacy peer deps
npm install --legacy-peer-deps

# Or force install
npm install --force

# For pnpm
pnpm install --no-strict-peer-dependencies
```

**Auto-Fix Available:** Partial

---

### PATH_NOT_SET

**Symptoms:**
- "openclaw: command not found" error
- Binary installed but not accessible
- Works in install directory but not globally

**Diagnostic Commands:**
```bash
# Check if openclaw exists
which openclaw
find / -name openclaw 2>/dev/null

# Check PATH
echo $PATH

# Check npm global bin path
npm bin -g
pnpm bin -g
```

**Fix:**

**Linux/macOS:**
```bash
# Add npm global bin to PATH
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or for pnpm
echo 'export PATH="$(pnpm bin -g):$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or add specific path
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh users
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**Windows:**
```powershell
# Add to PATH (PowerShell as Admin)
$npmPath = npm bin -g
$env:Path += ";$npmPath"
[Environment]::SetEnvironmentVariable("Path", $env:Path, "User")

# Restart terminal
```

**Verify:**
```bash
# Should show path to openclaw
which openclaw

# Should work from any directory
cd ~
openclaw --version
```

**Auto-Fix Available:** Yes

---

### DEPENDENCY_CONFLICT

**Symptoms:**
- "Peer dependency conflict" errors
- "Could not resolve dependency" errors
- Version mismatch warnings
- Installation completes but features broken

**Diagnostic Commands:**
```bash
# Check for conflicts
npm ls
pnpm why <package-name>

# View dependency tree
npm list --depth=1
```

**Fix:**
```bash
# Update to compatible versions
pnpm update --latest

# Resolve conflicts
pnpm install --fix-lockfile

# Use overrides (package.json)
{
  "pnpm": {
    "overrides": {
      "problematic-package": "^2.0.0"
    }
  }
}

# Or dedupe
npm dedupe

# Clean install
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

**Auto-Fix Available:** No (requires manual resolution)

---

## Platform-Specific Installation

### Linux (Ubuntu/Debian)

```bash
# Install prerequisites
sudo apt update
sudo apt install -y curl git build-essential

# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Install pnpm
npm install -g pnpm

# Install OpenClaw
pnpm install -g openclaw

# Verify
openclaw --version
openclaw doctor
```

### macOS

```bash
# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node@22
brew link --overwrite node@22

# Install pnpm
brew install pnpm

# Install OpenClaw
pnpm install -g openclaw

# Verify
openclaw --version
openclaw doctor
```

### Windows

```powershell
# Install via Chocolatey (run as Administrator)
# Install Chocolatey first: https://chocolatey.org/install

# Install Node.js
choco install nodejs-lts --version=22.0.0

# Install pnpm
choco install pnpm

# Install OpenClaw
pnpm install -g openclaw

# Verify
openclaw --version
openclaw doctor
```

### Docker Installation

```bash
# Pull official image
docker pull openclaw/openclaw:latest

# Or build from source
git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker build -t openclaw:local .

# Run container
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e OPENAI_API_KEY=sk-... \
  openclaw/openclaw:latest

# Check status
docker logs openclaw
docker exec openclaw openclaw status
```

## Post-Installation Setup

### First-Time Configuration

```bash
# Run setup wizard
openclaw init

# Or manual setup
openclaw config init

# Set API keys
openclaw config set ai.providers.openai.apiKey "sk-..."
openclaw config set ai.providers.anthropic.apiKey "sk-ant-..."

# Enable channels
openclaw channels enable whatsapp
openclaw channels enable telegram

# Start gateway
openclaw start

# Verify installation
openclaw doctor
openclaw status
```

### Verify Installation

```bash
# Check all components
openclaw doctor --full

# Expected output:
# ✓ Node.js version (22.x.x)
# ✓ pnpm installed
# ✓ OpenClaw installed
# ✓ Configuration valid
# ✓ Gateway running (port 18789)
# ✓ AI providers configured
# ✓ Channels configured
```

## Common Installation Workflows

### Fresh Install
```bash
# 1. Install Node.js 22+
nvm install 22

# 2. Install pnpm
npm install -g pnpm

# 3. Install OpenClaw
pnpm install -g openclaw

# 4. Initialize
openclaw init

# 5. Configure
openclaw config wizard

# 6. Start
openclaw start
```

### Update/Upgrade
```bash
# Check current version
openclaw --version

# Update to latest
pnpm update -g openclaw

# Or reinstall
pnpm remove -g openclaw
pnpm install -g openclaw

# Migrate config if needed
openclaw config migrate

# Restart
openclaw restart
```

### Troubleshooting Failed Install
```bash
# 1. Clean everything
pnpm remove -g openclaw
rm -rf ~/.openclaw/cache
pnpm cache clean --force

# 2. Check prerequisites
node --version  # Must be 22+
pnpm --version

# 3. Fix permissions
sudo chown -R $USER:$USER ~/.npm
sudo chown -R $USER:$USER ~/.pnpm-store

# 4. Reinstall
pnpm install -g openclaw --force

# 5. Verify
openclaw doctor --verbose
```

## Development Installation

```bash
# Clone repository
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install dependencies
pnpm install

# Build
pnpm build

# Link for local development
pnpm link --global

# Run in dev mode
pnpm dev

# Run tests
pnpm test
```

## Uninstallation

```bash
# Stop gateway
openclaw stop

# Uninstall package
pnpm remove -g openclaw

# Remove config (optional)
rm -rf ~/.openclaw

# Remove from PATH (if manually added)
# Edit ~/.bashrc and remove openclaw PATH entries
```

## Related Files

- [Error Catalog](error-catalog.md) - All error types
- [Configuration Errors](configuration-errors.md) - Config setup
- [Gateway Errors](gateway-errors.md) - Post-install issues
- [Diagnostic Commands](diagnostic-commands.md) - Verification commands


path: references/rate-limiting-errors.md
content: # Rate Limiting Errors

Guide to managing API rate limits, quotas, and throttling in OpenClaw.

## Error Types

### 429 Too Many Requests

**Symptoms:**
- HTTP 429 status code from AI provider
- "Rate limit exceeded" error messages
- Requests temporarily rejected
- Slow or failed responses

**Common Causes:**
- Exceeding provider's requests-per-minute (RPM) limit
- Exceeding tokens-per-minute (TPM) limit
- Too many concurrent requests
- Shared API key hitting aggregate limits

**Provider Limits:**
```
OpenAI (Free Tier):
- 3 RPM, 40,000 TPM (GPT-3.5)
- 3 RPM, 150,000 TPM (GPT-4)

OpenAI (Pay-as-you-go):
- 3,500 RPM, 90,000 TPM (GPT-3.5)
- 500 RPM, 30,000 TPM (GPT-4)

Anthropic (Free Tier):
- 5 RPM, 25,000 TPM

Anthropic (Pro):
- 1,000 RPM, 100,000 TPM

Google Gemini (Free):
- 15 RPM, 1M TPM

Google Gemini (Pro):
- 360 RPM, 4M TPM
```

**Diagnostic Commands:**
```bash
# Check current rate limit status
openclaw status --rate-limits

# View request history
openclaw logs --filter="429" --last=1h

# Show quota usage
openclaw quota show
```

**Fix with Retry Strategy:**
```bash
# Enable exponential backoff in config
openclaw config set ai.retryStrategy.enabled true
openclaw config set ai.retryStrategy.maxRetries 3
openclaw config set ai.retryStrategy.backoffMs 1000

# Set rate limit buffer
openclaw config set ai.rateLimiting.bufferPercent 20
```

**Manual Fix:**
```bash
# Wait for rate limit window to reset (usually 1 minute)
sleep 60

# Reduce concurrent requests
openclaw config set ai.concurrency.max 2

# Enable request queuing
openclaw config set ai.queueing.enabled true
```

**Auto-Fix Available:** No (requires waiting or config adjustment)

---

### QUOTA_EXCEEDED

**Symptoms:**
- "Quota exceeded" error
- All requests fail even after waiting
- Provider dashboard shows 100% usage
- Billing alerts received

**Common Causes:**
- Monthly quota exhausted
- Free tier limit reached
- Billing issue (payment failed)
- Trial period expired

**Diagnostic Commands:**
```bash
# Check quota status
openclaw quota status --provider openai

# View usage breakdown
openclaw quota breakdown --last-30-days

# Estimate remaining capacity
openclaw quota estimate
```

**Fix:**
```bash
# Option 1: Upgrade tier
# Visit provider dashboard and upgrade plan

# Option 2: Switch to fallback provider
openclaw config set ai.fallback.enabled true
openclaw config set ai.fallback.provider anthropic

# Option 3: Wait for quota reset
# Monthly quotas reset on billing cycle date

# Option 4: Add additional API key
openclaw config set ai.openai.apiKeys '["sk-key1", "sk-key2"]'
openclaw config set ai.keyRotation.enabled true
```

**Prevention:**
```bash
# Set quota alerts
openclaw config set ai.quotaAlerts.enabled true
openclaw config set ai.quotaAlerts.thresholds '[80, 90, 95]'

# Enable cost tracking
openclaw config set ai.costTracking.enabled true
openclaw config set ai.costTracking.maxDailyCost 10.00
```

**Auto-Fix Available:** No (requires billing action)

---

### PROVIDER_THROTTLE

**Symptoms:**
- Intermittent slowdowns
- Requests succeed but take longer
- Provider returns "throttling" messages
- Degraded service notices

**Common Causes:**
- Provider-side load balancing
- Regional capacity limits
- Account-level throttling
- Abuse detection false positive

**Diagnostic Commands:**
```bash
# Check provider status
openclaw status --provider-health

# Measure response times
openclaw benchmark --provider openai --samples 10

# View throttling events
openclaw logs --filter="throttle" --last=24h
```

**Fix:**
```bash
# Reduce request frequency
openclaw config set ai.rateLimiting.requestsPerMinute 30

# Add request delays
openclaw config set ai.rateLimiting.minDelayMs 100

# Use different region endpoint
openclaw config set ai.openai.endpoint "https://api.openai.com/v1"  # Try different region

# Spread load across time
openclaw config set ai.scheduling.spreadLoad true
```

**Auto-Fix Available:** No (provider-side issue)

---

### CONCURRENT_LIMIT

**Symptoms:**
- "Too many concurrent requests" error
- Some requests queued indefinitely
- Gateway connection pool exhausted

**Common Causes:**
- Exceeding max concurrent connections (usually 100)
- Long-running requests blocking pool
- No connection timeout set
- WebSocket connections not closing

**Diagnostic Commands:**
```bash
# Check active connections
openclaw status --connections

# View connection pool stats
openclaw debug --connection-pool

# List long-running requests
openclaw requests --status running --min-duration 30s
```

**Fix:**
```bash
# Reduce max concurrent
openclaw config set ai.concurrency.max 50

# Set request timeout
openclaw config set ai.timeout.requestMs 30000

# Enable connection reuse
openclaw config set ai.http.keepAlive true
openclaw config set ai.http.maxSockets 100

# Clear stuck connections
openclaw connections reset
```

**Auto-Fix Available:** Yes

---

### BURST_LIMIT

**Symptoms:**
- Rapid succession of requests fails
- First few requests succeed, rest fail
- "Burst limit exceeded" message
- Short-term rate limit hit

**Common Causes:**
- Too many requests in short window (e.g., 10 requests in 1 second)
- Webhook spam
- Batch processing without delays
- Message flood from channel

**Diagnostic Commands:**
```bash
# View request burst patterns
openclaw analytics --metric burst --window 1s

# Check webhook activity
openclaw webhooks stats --last 5m
```

**Fix:**
```bash
# Enable burst protection
openclaw config set ai.burstProtection.enabled true
openclaw config set ai.burstProtection.maxPerSecond 5

# Add inter-request delays
openclaw config set ai.rateLimiting.burstDelayMs 200

# Implement message queuing
openclaw config set channels.queueing.enabled true
openclaw config set channels.queueing.maxPerSecond 3
```

**Auto-Fix Available:** No (requires config tuning)

---

## Rate Limiting Best Practices

### Configuration Template
```yaml
ai:
  rateLimiting:
    enabled: true
    requestsPerMinute: 50
    tokensPerMinute: 80000
    bufferPercent: 20
    minDelayMs: 100

  retryStrategy:
    enabled: true
    maxRetries: 3
    backoffMs: 1000
    backoffMultiplier: 2
    jitter: true

  concurrency:
    max: 10
    perProvider: 5

  queueing:
    enabled: true
    maxQueueSize: 100
    priorityMode: "fifo"

  fallback:
    enabled: true
    providers: ["anthropic", "google"]
    switchOnQuota: true
```

### Monitoring Strategy
```bash
# Real-time monitoring
openclaw status --watch --interval 5

# Daily quota summary
openclaw quota summary --email daily

# Alert on threshold
openclaw alerts add --metric quota --threshold 80 --action notify
```

### Cost Management
```bash
# Set daily budget
openclaw config set ai.budget.daily 20.00

# Enable cost alerts
openclaw config set ai.costAlerts.enabled true

# Track per-channel costs
openclaw analytics --metric cost --group-by channel
```

## Retry Strategies

**Exponential Backoff:**
- Retry after 1s, 2s, 4s, 8s...
- Prevents thundering herd
- Recommended for 429 errors

**Jittered Backoff:**
- Add random delay (±25%)
- Spreads load
- Best for multiple clients

**Fixed Delay:**
- Constant delay between retries
- Simple, predictable
- Use for non-critical requests

## Related Files

- [Error Catalog](error-catalog.md) - All error types
- [Diagnostic Commands](diagnostic-commands.md) - CLI reference
- [Configuration Errors](configuration-errors.md) - Config issues


path: references/sandbox-errors.md
content: # Sandbox Errors

Guide to diagnosing and fixing Docker sandbox and code execution issues.

## Error Types

### DOCKER_NOT_RUNNING

**Symptoms:**
- "Cannot connect to Docker daemon" error
- "Is Docker running?" messages
- Sandbox initialization fails
- Code execution requests fail

**Common Causes:**
- Docker daemon not started
- User not in docker group
- Docker socket permission denied
- Docker Desktop not running (macOS/Windows)

**Diagnostic Commands:**
```bash
# Check Docker status
docker info
systemctl status docker  # Linux
docker version

# Check Docker socket
ls -la /var/run/docker.sock

# Test Docker access
docker ps
```

**Fix:**
```bash
# Start Docker daemon (Linux)
sudo systemctl start docker
sudo systemctl enable docker

# Start Docker Desktop (macOS/Windows)
# Launch Docker Desktop application

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

# Fix socket permissions
sudo chmod 666 /var/run/docker.sock

# Verify
docker run hello-world
```

**Auto-Fix Available:** No (requires system-level action)

---

### CONTAINER_OOM

**Symptoms:**
- "Container killed - out of memory" error
- Sandbox container exits with code 137
- Memory limit exceeded messages
- Code execution fails on large datasets

**Common Causes:**
- Memory limit too low (default: 512MB)
- Memory leak in user code
- Large file processing
- Inefficient algorithms

**Diagnostic Commands:**
```bash
# Check container memory usage
openclaw sandbox stats

# View killed containers
docker ps -a --filter "exited=137"

# Monitor memory usage
docker stats --no-stream

# Check logs
openclaw logs --sandbox --filter="OOM"
```

**Fix:**
```bash
# Increase memory limit
openclaw config set sandbox.memory.limit "2GB"

# Set swap limit
openclaw config set sandbox.memory.swap "4GB"

# Enable memory monitoring
openclaw config set sandbox.monitoring.memory.enabled true
openclaw config set sandbox.monitoring.memory.alertThreshold 80

# Restart with new limits
openclaw sandbox restart

# For specific execution
openclaw sandbox exec --memory 4GB -- python script.py
```

**Prevention:**
```yaml
sandbox:
  memory:
    limit: "2GB"
    swap: "4GB"
    reservation: "512MB"
  monitoring:
    enabled: true
    alertThreshold: 85
```

**Auto-Fix Available:** Partial (can increase limits)

---

### SANDBOX_TIMEOUT

**Symptoms:**
- "Execution timeout" error
- Code execution killed after time limit
- Long-running scripts terminated
- Timeout after 30s (default)

**Common Causes:**
- Timeout setting too low
- Infinite loops in code
- Slow external API calls
- Large data processing

**Diagnostic Commands:**
```bash
# Check current timeout
openclaw config get sandbox.timeout.execution

# View timed-out executions
openclaw sandbox history --filter timeout

# Monitor execution time
openclaw sandbox exec --verbose -- python script.py
```

**Fix:**
```bash
# Increase timeout
openclaw config set sandbox.timeout.execution 300000  # 5 minutes in ms

# Set per-execution timeout
openclaw sandbox exec --timeout 600 -- python long_script.py

# Disable timeout (dangerous, use with care)
openclaw config set sandbox.timeout.execution 0

# Enable execution streaming
openclaw config set sandbox.streaming.enabled true
```

**Configuration:**
```yaml
sandbox:
  timeout:
    execution: 300000    # 5 minutes
    startup: 30000       # 30 seconds
    shutdown: 10000      # 10 seconds
```

**Auto-Fix Available:** Yes (increases timeout)

---

### WORKSPACE_MOUNT_FAIL

**Symptoms:**
- "Failed to mount workspace" error
- Files not accessible in sandbox
- Volume mount permission denied
- Bind mount failed

**Common Causes:**
- Workspace directory doesn't exist
- Permission denied on workspace path
- SELinux blocking volume mounts
- Docker volume driver issue

**Diagnostic Commands:**
```bash
# Check workspace path
openclaw config get sandbox.workspace.path
ls -la $(openclaw config get sandbox.workspace.path)

# Test volume mount
docker run -v /path/to/workspace:/workspace alpine ls /workspace

# Check SELinux status
getenforce
```

**Fix:**
```bash
# Create workspace directory
mkdir -p ~/.openclaw/workspace
chmod 755 ~/.openclaw/workspace

# Set correct ownership
sudo chown -R $USER:$USER ~/.openclaw/workspace

# Update workspace path
openclaw config set sandbox.workspace.path "$HOME/.openclaw/workspace"

# SELinux: add context (Linux)
chcon -Rt svirt_sandbox_file_t ~/.openclaw/workspace

# Or disable SELinux temporarily (testing only)
sudo setenforce 0

# Use named volume instead
openclaw config set sandbox.workspace.type "volume"
openclaw config set sandbox.workspace.name "openclaw-workspace"
```

**Auto-Fix Available:** No (requires file system access)

---

### PERMISSION_DENIED

**Symptoms:**
- "Permission denied" in sandbox
- Cannot execute files
- Cannot write to workspace
- File operation fails

**Common Causes:**
- File ownership mismatch (host vs container user)
- Files not executable
- Read-only volume mount
- AppArmor/SELinux restrictions

**Diagnostic Commands:**
```bash
# Check file permissions
ls -la ~/.openclaw/workspace/

# Check container user
docker exec sandbox-container whoami
docker exec sandbox-container id

# Test permissions in container
openclaw sandbox exec -- ls -la /workspace
```

**Fix:**
```bash
# Match container UID (usually 1000)
openclaw config set sandbox.user.uid 1000
openclaw config set sandbox.user.gid 1000

# Make files executable
chmod +x ~/.openclaw/workspace/script.sh

# Fix ownership
sudo chown -R 1000:1000 ~/.openclaw/workspace/

# Use read-write mount
openclaw config set sandbox.workspace.readOnly false

# Run as root (not recommended, use with care)
openclaw config set sandbox.user.runAsRoot true
```

**Auto-Fix Available:** Partial

---

### IMAGE_PULL_FAILED

**Symptoms:**
- "Failed to pull Docker image" error
- Sandbox container won't start
- Network timeout during pull
- Authentication required for image

**Common Causes:**
- No internet connection
- Docker Hub rate limit
- Private image requires auth
- Image doesn't exist

**Diagnostic Commands:**
```bash
# Check current image
openclaw config get sandbox.image

# Try pulling manually
docker pull $(openclaw config get sandbox.image)

# Check Docker Hub rate limit
docker pull ratelimitpreview/test

# List available images
docker images
```

**Fix:**
```bash
# Use pre-pulled image
docker pull python:3.11-slim
openclaw config set sandbox.image "python:3.11-slim"

# Login to Docker Hub (for private images)
docker login

# Use local image
openclaw config set sandbox.image.pullPolicy "IfNotPresent"

# Set registry mirror (China/restricted networks)
openclaw config set sandbox.image.registry "mirror.gcr.io"

# Build custom image
cd ~/.openclaw/sandbox/
docker build -t openclaw-sandbox:latest .
openclaw config set sandbox.image "openclaw-sandbox:latest"
```

**Auto-Fix Available:** No (requires network/auth)

---

### CONTAINER_NETWORK_ERROR

**Symptoms:**
- Sandbox cannot access network
- DNS resolution fails in container
- Cannot download packages
- API calls timeout

**Fix:**
```bash
# Enable network access
openclaw config set sandbox.network.enabled true

# Set DNS servers
openclaw config set sandbox.network.dns '["8.8.8.8", "1.1.1.1"]'

# Use host network (bypass isolation)
openclaw config set sandbox.network.mode "host"

# Or bridge with custom network
docker network create openclaw-net
openclaw config set sandbox.network.name "openclaw-net"
```

---

## Sandbox Configuration

### Recommended Settings
```yaml
sandbox:
  enabled: true
  image: "python:3.11-slim"

  memory:
    limit: "2GB"
    swap: "4GB"

  cpu:
    limit: 2.0
    shares: 1024

  timeout:
    execution: 300000
    startup: 30000

  workspace:
    path: "$HOME/.openclaw/workspace"
    readOnly: false

  user:
    uid: 1000
    gid: 1000
    runAsRoot: false

  network:
    enabled: true
    mode: "bridge"
    dns: ["8.8.8.8", "1.1.1.1"]

  security:
    privileged: false
    capAdd: []
    capDrop: ["ALL"]
```

### Security Best Practices

1. **Never run as root** unless absolutely necessary
2. **Limit memory/CPU** to prevent resource exhaustion
3. **Drop capabilities** - remove unnecessary Linux capabilities
4. **Use read-only mounts** when possible
5. **Enable timeout** to prevent runaway processes
6. **Disable network** for untrusted code
7. **Use specific image tags** instead of :latest

### Resource Limits

```bash
# Set CPU limit (1.5 cores)
openclaw config set sandbox.cpu.limit 1.5

# Set memory limit
openclaw config set sandbox.memory.limit "1GB"

# Set disk I/O limit
openclaw config set sandbox.disk.readBps "100MB"
openclaw config set sandbox.disk.writeBps "50MB"

# Set max processes
openclaw config set sandbox.pids.limit 100
```

### Monitoring

```bash
# Real-time stats
openclaw sandbox stats --watch

# Resource usage history
openclaw sandbox metrics --last 1h

# Alert on high usage
openclaw alerts add --metric sandbox_memory --threshold 90 --action notify
```

## Docker Troubleshooting

### Docker Won't Start
```bash
# Check systemd service
sudo systemctl status docker
sudo journalctl -u docker -n 50

# Check disk space
df -h

# Check Docker root
docker info | grep "Docker Root Dir"

# Clean up space
docker system prune -a
```

### Container Keeps Crashing
```bash
# View container logs
docker logs <container_id>

# Inspect container
docker inspect <container_id>

# Check exit code
docker ps -a --filter "exited=1"

# Run interactively for debugging
docker run -it --rm python:3.11-slim /bin/bash
```

## Related Files

- [Error Catalog](error-catalog.md) - All error types
- [Installation Errors](installation-errors.md) - Docker setup
- [Configuration Errors](configuration-errors.md) - Config issues
- [Diagnostic Commands](diagnostic-commands.md) - CLI reference


path: requirements.txt
content: click>=8.1.0
rich>=13.0.0
requests>=2.31.0
beautifulsoup4>=4.12.0


path: scripts/lib/__init__.py
content: """OpenClaw Doctor Pro - Library modules."""

# Note: File names use kebab-case but Python requires underscores for imports
# These files will be imported directly using importlib in the main scripts


path: scripts/lib/error_extraction_helpers.py
content: """Helper functions for extracting error metadata from text."""
from __future__ import annotations

import re

TIMESTAMP_PATTERNS = [
    r'\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}',
    r'\[\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\]',
]


def extract_timestamp(line: str) -> str | None:
    """Extract timestamp from line.

    Args:
        line: Line text

    Returns:
        Timestamp string or None
    """
    for pattern in TIMESTAMP_PATTERNS:
        match = re.search(pattern, line)
        if match:
            return match.group(0)
    return None


def extract_error_code(text: str) -> str | None:
    """Extract error code from text.

    Common patterns:
    - NOT_LINKED, AGENT_TIMEOUT, CONFIG_INVALID
    - HTTP 404, HTTP 500

    Args:
        text: Text to search

    Returns:
        Error code or None
    """
    # OpenClaw style codes (CAPS_WITH_UNDERSCORES)
    code_match = re.search(r'\b([A-Z][A-Z_]{3,})\b', text)
    if code_match:
        return code_match.group(1)

    # HTTP status codes
    http_match = re.search(r'HTTP\s+([4-5]\d{2})', text, re.IGNORECASE)
    if http_match:
        return f"HTTP_{http_match.group(1)}"

    return None


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)