🔧 Troubleshooting Guide

Solutions:

1. Check the logs:

   openclaw logs --tail 50

   Look for error messages indicating the cause.
2. Validate your config:

   openclaw config validate

   This checks config syntax and missing required fields.
3. Check port conflicts:

   lsof -i :18789

   If another process is using the gateway port, either stop it or change the port in your config.
4. Verify API keys: Ensure your ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable is set correctly.

Solutions:

1. Don't run as root: OpenClaw should run as a regular user, not root.
2. Use a port above 1024: Ports below 1024 require root privileges. Use 3000, 8080, etc.
3. Check workspace permissions:

   ls -la ~/.openclaw/
   chmod -R u+rw ~/.openclaw/

Solutions:

1. Reinstall dependencies:

   npm install -g openclaw@latest

2. Clear npm cache:

   openclaw update status
   openclaw update

3. Check Node.js version:

   node --version

   OpenClaw recommends Node 24 and requires Node 22.19+ if you manage Node yourself.

Solutions:

1. Verify the bot token:

   curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

   You should see your bot's info. If not, the token is invalid.
2. Check webhook vs polling: If using webhooks, ensure your server is accessible from the internet on the configured port.
3. Look for duplicate bots: If you have multiple OpenClaw instances using the same bot token, only one will receive messages.
4. Check chat ID allowlist: If configured, ensure your Telegram user ID is in the allowedChats list.

Solutions:

1. Check bot token: Regenerate the token in Discord Developer Portal if needed.
2. Verify intents: In the Developer Portal, ensure "Message Content Intent" is enabled under Bot settings.
3. Check bot permissions: The bot needs "Read Messages" and "Send Messages" permissions in the channel.
4. Review logs:

   openclaw logs | grep -i discord

Solutions:

1. Check signal-cli: Signal requires signal-cli to be installed and linked to a phone number.

   signal-cli -a +1234567890 receive

2. Verify registration: You need to register the phone number with Signal first.
3. Check JSON-RPC mode: OpenClaw connects via JSON-RPC. Ensure signal-cli is running in daemon mode:

   signal-cli -a +1234567890 daemon --socket /tmp/signal.sock

Solutions:

1. Check skill installation:

   ls ~/.openclaw/skills/

   Each skill should have a SKILL.md file.
2. Verify skill format: The SKILL.md must follow the correct structure with description, commands, etc.
3. Restart gateway: Skills are loaded at startup. Restart after adding new skills:

   openclaw gateway restart

4. Check skill allowlist: If your config has a skills allowlist, ensure the skill is included.

Solutions:

1. Check PATH: The CLI tool must be in the system PATH. Check:

   which <tool-name>

2. Install missing tools: Many skills require external CLIs. Check the skill's SKILL.md for requirements.
3. Use absolute paths: In skill scripts, use absolute paths instead of relying on PATH.

Solutions:

These skills use macOS-specific APIs and apps. They only work on macOS.

If you have a Mac Mini or MacBook available, you can:

1. Run those skills via a Node connection to your Mac
2. Use platform-agnostic alternatives (e.g., Notion instead of Apple Notes)

Solutions:

1. Check memory files exist:

   ls ~/.openclaw/workspace/MEMORY.md
   ls ~/.openclaw/workspace/memory/

2. Verify AGENTS.md includes memory instructions: Your AGENTS.md should tell the agent to read memory files on startup.
3. Ensure agent is writing to memory: The agent should update memory/YYYY-MM-DD.md files. Check if they're being created.
4. Check file permissions: The agent needs write access to the memory directory.

Solutions:

1. Check embedding model: Memory search uses embeddings. Ensure the embedding service is configured.
2. Verify file content: Empty or very short files may not produce useful embeddings.
3. Lower the minScore: Try searching with a lower minimum score threshold:

   memory_search({ query: "...", minScore: 0.3 })

Solutions:

1. Check tool allowlist: If your config has a tools.allowlist, ensure the tool is included.
2. Verify tool name: Tool names are case-sensitive. Check the exact name in the documentation.
3. Check policy settings: Some tools may be disabled by security policy.

Solutions:

1. Check path restrictions: By default, file operations may be restricted to the workspace. Check your config.
2. Use absolute paths: Always use absolute paths, not relative ones.
3. Verify file exists: For read and edit, ensure the file exists first.

Solutions:

1. Avoid interactive commands: Commands that wait for input will hang. Use -y or --yes flags when available.
2. Check for prompts: Some commands prompt for confirmation. Pass appropriate flags to skip.
3. Use PTY for interactive: If the command requires a terminal, use pty: true in the exec call.
4. Set a timeout: Add a timeout parameter to prevent indefinite hanging.

Solutions:

1. Check job status:

   cron({ action: "list" })

   Verify the job is enabled and the schedule is correct.
2. Verify timezone: Jobs use the configured timezone. Ensure it matches your expected timezone.
3. Check cron expression: Common mistake: */5 * * * * runs every 5 minutes, not at :05.
4. Gateway must be running: Cron jobs only fire when the gateway daemon is running.

Solutions:

1. Check run history:

   cron({ action: "runs", jobId: "your-job-id" })

2. Use delivery for output: For agentTurn jobs, set deliver: true to send results to a channel.
3. Write to files: Have the job write results to a file you can check later.

Solutions:

1. Check network connectivity: The node must be able to reach your gateway's URL.
2. Verify gateway URL: On the node, ensure it's configured with the correct gateway URL and token.
3. Check firewall: Ensure the gateway port is accessible from the node's network.
4. Look at node logs: Check the mobile app or CLI node for error messages.

Solutions:

1. Check node is online:

   nodes({ action: "status" })

2. Verify the command: Some commands require specific setup on the node (e.g., camera permissions).
3. Increase timeout: Long-running commands may need a higher timeout value.

Solutions:

1. Check model: Larger/high-thinking models are slower. Use faster models or lower thinking for simple tasks.
2. Reduce context: Very long system prompts or memory files increase latency. Keep context focused.
3. Check API status: Provider outages can cause slowdowns. Check Anthropic/OpenAI status pages.
4. Disable thinking for simple tasks: Thinking/reasoning modes add latency. Disable for quick tasks.

Solutions:

1. Restart periodically: Long-running processes may accumulate memory. Restart the gateway weekly.
2. Check for runaway sessions: Background sessions that never complete can accumulate.
3. Update to latest version: Memory leaks are fixed in updates.

   openclaw update

Solutions:

1. Start the browser profile:

   browser({ action: "start", profile: "openclaw" })

2. For Chrome extension: Install the OpenClaw Browser Relay extension and click "Attach Tab" on the toolbar.
3. Check browser is installed: The openclaw profile needs Chromium or Chrome installed.

Solutions:

1. Navigate first: Ensure a page is loaded:

   browser({ action: "navigate", targetUrl: "https://example.com" })

2. Wait for content: Some pages load dynamically. Try again after a short delay.
3. Check targetId: If you have multiple tabs, ensure you're targeting the right one.

Solutions:

1. Clear npm cache:

   npm cache clean --force

2. Uninstall and reinstall:

   openclaw update --dry-run
   openclaw update

3. Check Node version: Use Node 24 recommended, or Node 22.19+ minimum.

Solutions:

1. Check release notes: Major updates may require config changes. Check the changelog.
2. Validate config:

   openclaw config validate

3. Use config migration: Some updates include automatic config migration. Check the docs.