OpenClaw Deployment Guide
Deploy a multi-agent collaboration system in 3 minutes, 50+ built-in tools, fully self-hosted
OpenClaw Agent Deployment Guide
Self-hosted multi-Agent system with GPU acceleration, Skill extensions, and Feishu / Telegram / Discord platform integration
🚀 Quick Install
One command to launch OpenClaw, supporting Docker or native Python
5 min to get started🔧 Full Configuration
Detailed explanation of every config.yaml field, helping you understand each option
Config Reference❌ FAQ
GPU not recognized, API Key errors, port conflicts... Problems and solutions
Troubleshooting💡 Usage Tips
Multi-model switching, Memory management, Skill authoring, and performance tuning to make your Agent stronger
Advanced TipsI. Installation
Recommended: Ubuntu 20.04+ / macOS 12+, Python 3.10+, NVIDIA GPU recommended for best performance. CPU-only inference also works without GPU.
Method A: Docker Install (Recommended)
Make sure docker and nvidia-docker are installed (for machines with GPU). One command spins up all services.
docker pull openclaw/openclaw:latest docker run -d \ --gpus all \ -p 8080:8080 \ -v ~/openclaw/config.yaml:/app/config.yaml \ -v ~/openclaw/data:/app/data \ --name openclaw \ openclaw/openclaw:latest
Tip: First startup automatically downloads the model, which takes a few minutes. Subsequent startups take only 10–15 seconds. Use docker logs -f openclaw to view startup logs.
Method B: Native Python Install
Requires Python 3.10+, virtual environment recommended.
pip install openclaw-agent openclaw init ~/openclaw cd ~/openclaw openclaw start
Note: Native install requires manual model download and dependency handling. Try Docker first; check logs if issues arise.
Verify Installation
After starting, access http://<your-server-IP>:8080. If you see the Web UI, installation succeeded.
# Check running status openclaw status # View real-time logs openclaw logs -f # Test if API is working curl http://localhost:8080/health
II. config.yaml Reference
config.yaml is the core OpenClaw config file, defining Agent behavior, model sources, and platform access. Below is a detailed explanation of each field.
| Field | Type | Description |
|---|---|---|
| agent.name | string | Agent name, used as identifier in multi-Agent collaboration |
| agent.model | string | Default model, e.g. gpt-4o, claude-4-sonnet, deepseek-v3 |
| agent.model_map | object | Model alias mapping, for assigning different models to different tasks |
| agent.max_tokens | int | Max tokens per response, default 4096 |
| agent.temperature | float | Sampling temperature, 0.0–2.0, default 0.7. Higher = more creative, lower = more deterministic |
| agent.proxy_url | string | Proxy address (e.g. FlowerWolf compute node URL), leave empty for direct connection |
| agent.api_key | string | API Key, required. Get from FlowerWolf Token Market |
| gpu.enabled | bool | Whether to enable GPU acceleration, requires NVIDIA GPU + CUDA |
| gpu.device | string | GPU device number, 0 is the first GPU, can also use cuda:0 |
| memory.type | string | Memory storage type: sqlite, postgres, memory |
| memory.session_limit | int | Max messages per session; oldest messages are auto-summarized when limit is exceeded |
| skills.dir | string | Skill file directory path, default ./skills |
| skills.autoload | bool | Whether to auto-load all Skills on startup |
| platforms.feishu.enabled | bool | Whether to enable Feishu platform integration |
| platforms.telegram.enabled | bool | Whether to enable Telegram platform integration |
| platforms.discord.enabled | bool | Whether to enable Discord platform integration |
| log.level | string | Log level: debug / info / warn / error |
| log.file | string | Log file path, leave empty to output to stdout only |
Minimal Working Config
agent: name: my-agent model: gpt-4o api_key: your-flowerwolf-token-here proxy_url: https://api.flowerwolf.net/v1 gpu: enabled: true device: "0" memory: type: sqlite session_limit: 50 log: level: info
Tip — Multi-model config: Use model_map to assign different models for different tasks, saving cost:
agent.model_map: { coding: "deepseek-v3", analysis: "claude-4-sonnet", quick: "gpt-4o-mini" }
III. Troubleshooting
When encountering issues, check the logs first: openclaw logs. Most problems can be identified there.
GPU Not Recognized / CUDA Error
Symptoms: CUDA error: no CUDA-capable device found on startup, or model loads extremely slowly (CPU-only speed).
Steps:
1. Verify NVIDIA GPU is installed: nvidia-smi, if it outputs, GPU is fine.
2. Check CUDA driver version: nvidia-smi | head -4, top-left shows driver version, needs >= 450.
3. Verify PyTorch CUDA compatibility: run python -c "import torch; print(torch.cuda.is_available())", must return True.
4. Docker startup requires --gpus all flag: docker run --gpus all ...
Common cause: Docker daemon doesn't have NVIDIA runtime enabled. Edit /etc/docker/daemon.json to add "default-runtime": "nvidia", then sudo systemctl restart docker.
API Key Error / 401 Unauthorized
Symptoms: Logs show 401 or Authentication failed, Agent cannot make requests.
Steps:
1. Verify Key spelling is correct, no extra spaces or line breaks. Key format is like sk-flo...xxxx.
2. Verify Key has balance: log in at flowerwolf.net/token.html to check balance.
3. Verify proxy_url is correct: must include full path like https://api.flowerwolf.net/v1, no trailing slash.
4. Check whether proxy_url in config.yaml has a wrong address.
Port Already in Use
Symptoms: port 8080 is already in use on startup.
First find the occupying process with ss -tlnp | grep 8080 (or netstat -tlnp | grep 8080), then kill it with kill <PID>. If it's another OpenClaw instance. If it's another OpenClaw instance, run openclaw stop to stop the old process.
Prevention: Before each restart, run openclaw stop then openclaw start.
Agent Doesn't Reply / No Response to Messages
Steps:
1. Verify the corresponding platform's (Feishu/Telegram/Discord) Webhook is correctly configured and publicly reachable.
2. Feishu: verify "Use long-polling for events" is enabled in event subscription, and the bot is added to app permissions.
3. Telegram: verify Bot Token is correct, webhook URL format is https://your-domain/telegram/webhook.
4. Check logs for received message records: openclaw logs | grep "received".
5. Verify Agent isn't processing other requests (single-threaded queue), use openclaw status to check queue status.
Model Response Very Slow / Timeout
Possible causes:
1. GPU memory insufficient: model too large, forced to use CPU. Try a smaller model (e.g. gpt-4o-mini) or reduce max_tokens.
2. Network issue: high latency to the node pointed to by proxy_url. Test with: ping api.flowerwolf.net.
3. Request queuing: when Token balance is low, API queues requests. Check balance or wait for queue to clear.
4. Slow model loading: first request loads the model into GPU memory, 10–30 seconds; subsequent requests are much faster.
Skill Loading Failed / Skill Not Found
Verify Skill file is in the skills.dir directory specified in config.yaml, file format is .yaml or .py. Filenames must not contain Chinese characters or spaces.
Check Skill YAML syntax is correct. Required fields: name, description, action (or script). See Skill authoring tutorial.
Docker Exits Immediately After Start / Container Exited
Run docker logs openclaw to check the exit reason. Common causes: config.yaml format errors (YAML is indentation-sensitive), missing API Key, incorrect port mapping (-p 8080:8080 format: host-port:container-port).
IV. Usage Tips
Multi-Model Smart Routing
Don't use the same model for all tasks. Use model_map to assign the most suitable model for different tasks: deepseek-v3 for coding (best cost-performance), gpt-4o for creative writing, claude-4-sonnet.
Example: specifying model: deepseek-v3 in a Skill makes that Skill always use that specific model, unaffected by the global model setting.
Memory Management: Periodic Session History Cleanup
OpenClaw session history is stored in SQLite (default) or PostgreSQL. As conversations grow, use session_limit to control max messages per session. Exceeding the limit auto-summarizes and compresses the oldest messages, preventing infinite growth.
For manual cleanup: openclaw memory purge --session <session-id>. View current session count: openclaw memory stats.
Skill Authoring: Letting Agent Call External Tools
Skill is OpenClaw's most powerful extension mechanism. You can write a Python function and let the Agent call it during conversation.
Skill files go in the skills/ directory. Each Skill has a description (for the Agent to decide when to call it) and implementation logic.
# skills/weather.yaml
name: get_weather
description: Query weather for a specified city, e.g. "What's the weather in Beijing today?"
action: python
script: |
def get_weather(city):
# Call weather API
return f"{city} is sunny today, 25-30C, great for going out"
get_weather("{{city}}")The Agent automatically recognizes when to call a Skill — no manual triggering needed.
GPU Memory Insufficient? Use Quantized Models
If GPU memory is limited (e.g. 8GB), enable model quantization. Quantized models are 50–75% smaller with typically < 3% accuracy loss.
Set gpu.quantization: "int8" in config.yaml to enable INT8 quantization. Note: quantization is completed during first model load and takes effect after restart.
Automation with Cron Jobs
OpenClaw supports Cron Jobs for periodic tasks. Examples: "Summarize yesterday's sales data every day at 9am", "Check server status every hour and alert on anomalies".
Configure in config.yaml: cron: { "0 9 * * *": "summarize_sales" }. Task names correspond to a Skill.
Multi-Agent Collaboration: Assign Different Roles
OpenClaw supports multi-Agent collaboration. You can have one Agent for code review, another for customer replies, and a third for data monitoring. They communicate via shared Memory, each with its own role.
Configure multiple agents[] in config.yaml, each with independent name, model, role.
Log Debugging: Enable Debug Mode
When troubleshooting, change log.level to debug and restart. Logs will output the full context of each request and the Agent's reasoning process — very verbose, great for diagnosing difficult issues.
Switch back to info during normal operation to avoid log bloat.
Hidden Web UI Features
OpenClaw's Web UI (port 8080) is not just for chat. Click the settings icon (top-right) to: view current Token balance (FlowerWolf API real-time query), switch the current Agent model, clear session history, export conversation records as JSON.
V. Multi-Platform Integration
OpenClaw supports simultaneous integration with multiple platforms such as Feishu, Telegram, and Discord. Messages from all platforms are unified and routed to the same Agent for processing.
| Platform | Config Field Prefix | Key Config Items |
|---|---|---|
| Feishu | platforms.feishu | app_id, app_secret, bot_name, enable_dm, enable_group |
| Telegram | platforms.telegram | bot_token, admin_ids (list of admin Telegram IDs) |
| Discord | platforms.discord | bot_token, guild_id, channel_ids |
| WeChat (Enterprise) | platforms.wechat | corp_id, corp_secret, agent_id |
Feishu Integration Notes:
1. Create an app at open.feishu.cn and enable the "Bot" capability.
2. When configuring event subscriptions, select "Use long-polling to receive events" (no public Webhook URL required).
3. Required permissions: im:message (read messages), im:message:send_as_bot (send messages).
4. For group messages, enable "Allow bot to receive group messages" in app settings and configure the FEISHU_GROUP_POLICY=open environment variable.
VI. FAQ
Q: What's the difference between OpenClaw and directly calling the API?
Direct API calls only support single-turn Q&A. OpenClaw adds an Agent framework on top of the API: multi-turn conversation memory management, Skill invocation mechanism, platform integration (Feishu/Telegram), Cron automation, debugging tools, etc. Think of it as an "operating system" for the API.
Q: How many OpenClaw instances can run on one machine?
It depends on your GPU memory. Each instance loads one model (3-10GB VRAM). A 4090 with 24GB VRAM can run 2 instances (one primary + one standby); the same applies to a 3090 24GB. CPU mode is only limited by RAM -- 16GB can run 3-5 instances.
Q: What models does OpenClaw support?
Theoretically supports all OpenAI API-compatible models. Verified working: GPT-4o, GPT-4o mini, Claude 4 Sonnet, Claude 3.5 Sonnet, Gemini 2.0 Flash, DeepSeek V3, Qwen Turbo, Doubao, etc. Accessed through the FlowerWolf Token Market -- no per-model integration needed.
Q: How to back up OpenClaw data?
Regularly back up the data/ directory (contains SQLite database and model cache). If using PostgreSQL, back up the database. It's also recommended to regularly back up config.yaml. For Docker, use docker cp openclaw:/app/data ./openclaw-data-backup.