OpenClaw Deep Dive: Configuration, Proxy & Troubleshooting

This article is for users who already have basic OpenClaw knowledge, focusing on advanced configuration and troubleshooting.

Introduction

OpenClaw has maintained extreme popularity for over a month and continues to grow. I've been helping clients with deployment, channel integration, and troubleshooting various complex issues. This article summarizes the problems I've encountered and their solutions.

Note: This is not a beginner's tutorial. For basics, installation, and configuration, please search for other resources.

Quick Installation Guide

Universal Steps (Windows/Linux/macOS)

Install Node.js: Recommended 22 LTS version
Install Git: Mac users run xcode-select --install

Install OpenClaw globally:

npm install openclaw@latest -g
openclaw onboard

Non-global Installation

npm install openclaw@latest
npx openclaw gateway  # Add npx prefix

Configuration Directories

macOS/Linux: ~/.openclaw/
Windows: %USERPROFILE%\.openclaw\

Basic Commands

openclaw gateway              # Start in foreground
openclaw gateway install      # Start as service
openclaw gateway restart      # Restart
openclaw gateway stop         # Stop
openclaw gateway uninstall    # Uninstall service

Common Issues & Solutions

1. Configuration Not Taking Effect

Symptom: Errors like Unrecognized key, Invalid input.

Solution:

Use VS Code or professional editors
Check key names, nesting, JSON format
Verify syntax with latest documentation

2. Error "duplicate plugin id detected"

Symptom: Common when integrating Feishu/Lark.

Solution: Don't install Feishu plugin separately! It's built-in. Just modify the config file.

3. Cannot Send Local Images/Documents

Symptom: Returns only file path text.

Solution:

Check logs for LocalMediaAccessError
Create files directory in workspace
Instruct agent to save files there first

4. Model Config Not Taking Effect

Symptom: Config correct but not working.

Solution:

Agent config at ~/.openclaw/agents/<agent>/agent/models.json has higher priority
Delete this file to resolve 99.9% of cases

5. Error "connection error"

Symptom: Cannot connect to model API.

Solutions:

a) Check Proxy

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

b) Certificate Issues (Mac)

export NODE_EXTRA_CA_CERTS=your_cert_path
# Or (dangerous, last resort)
export NODE_TLS_REJECT_UNAUTHORIZED=0

c) Daemon Config (Mac launchd)

launchctl setenv HTTP_PROXY http://127.0.0.1:7890
launchctl setenv HTTPS_PROXY http://127.0.0.1:7890

6. Token Mismatch (Mac)

Solution:

# Add to ~/.zshrc
export OPENCLAW_GATEWAY_TOKEN='your_token'

7. Bot Replies with Pairing Command

Symptom: Text ending with openclaw pairing approve XXXXXXX.

Solution: Execute that command in terminal.

8. Error "spawn git ENOENT"

Solution: Install Git or check PATH.

9. npm git pull failed: code 128

Solution:

Option A: Configure GitHub SSH (recommended)

Option B: Force HTTPS

git config --global url."https://github.com/".insteadOf ssh://[email protected]/

10. Permission Issues (EACCES, EPERM)

Solution:

Windows: Run as administrator
Mac/Linux: Use sudo

11. WhatsApp Issues

"Unsupported channel" error:

"channels": {
    "whatsapp": {
        "enabled": true
    }
}

Error 408: Enable TUN mode in proxy software.

💡 Tip: Avoid WhatsApp if possible. Telegram works best.

12. Memory System Issues

OpenClaw's memory has three layers:

Layer	Description	Persistent
Session	Current chat history	❌ Short-term
Workspace Files	`~/.openclaw/workspace/`	✅ Long-term
Semantic Retrieval	`memory_search` + `memory_get`	✅ On-demand

Default Files:

memory/YYYY-MM-DD.md - Daily logs
MEMORY.md - Long-term compressed memory
USER.md, AGENTS.md, TOOLS.md

Optimization Tips:

Use qmd as memory retrieval engine
Configure Cron jobs for memory sync

Conclusion

Most issues in this article come from Mac environment troubleshooting, but the logic applies cross-platform. Feedback and corrections are welcome!

References: