OpenClaw Agent 部署指南

🚀 快速安装

一条命令启动 OpenClaw，支持 Docker 或原生 Python

5 分钟上手

🔧 完整配置

config.yaml 每个字段的详细说明，帮你理解每个选项的含义

配置详解

❌ 常见问题

GPU 不识别、API Key 报错、端口冲突… 问题网罗与解决方案

排错指南

💡 使用技巧

多模型切换、Memory 管理、Skill 编写、性能调优，让你的 Agent 更强

进阶技巧

一、安装

推荐环境：Ubuntu 20.04+ / macOS 12+，Python 3.10+，推荐有 NVIDIA GPU 的机器以获得最佳性能。无 GPU 也可运行纯 CPU 推理。

方式 A：Docker 安装（推荐）

确保机器已安装 docker 和 nvidia-docker（有 GPU 的机器）。一条命令拉起全部服务。

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：首次启动会自动下载模型，需要几分钟。之后启动只需 10–15 秒。使用 docker logs -f openclaw 查看启动日志。

方式 B：原生 Python 安装

需要 Python 3.10+，推荐使用虚拟环境。

pip install openclaw-agent
openclaw init ~/openclaw
cd ~/openclaw
openclaw start

注意：原生安装需要手动处理模型下载和依赖。推荐先试 Docker 方式，遇到问题再看日志。

验证安装

启动后访问 http://<你的服务器IP>:8080，看到 Web UI 即表示安装成功。

# 查看运行状态
openclaw status

# 查看实时日志
openclaw logs -f

# 测试 API 是否正常
curl http://localhost:8080/health

二、config.yaml 配置详解

config.yaml 是 OpenClaw 的核心配置文件，决定了 Agent 的行为、模型来源和平台接入方式。以下是每个字段的详细说明。

字段	类型	说明
agent.name	string	Agent 名称，用于多 Agent 协作时的标识
agent.model	string	默认模型，如 `gpt-4o`、`claude-4-sonnet`、`deepseek-v3`
agent.model_map	object	模型别名映射，可为不同任务指定不同模型
agent.max_tokens	int	单次回复最大 token 数，默认 4096
agent.temperature	float	采样温度，0.0–2.0，默认 0.7。越高越有创造性，越低越确定
agent.proxy_url	string	代理地址（如 FlowerWolf 算力节点 URL），留空则直连
agent.api_key	string	API Key，必填。从 FlowerWolf Token 超市获取
gpu.enabled	bool	是否启用 GPU 加速，需 NVIDIA GPU + CUDA
gpu.device	string	GPU 设备号，`0` 为第一块显卡，可填 `cuda:0`
memory.type	string	记忆存储方式：`sqlite`、`postgres`、`memory`
memory.session_limit	int	每个会话保留的最大消息数，超出后自动摘要压缩
skills.dir	string	Skill 文件目录路径，默认 `./skills`
skills.autoload	bool	启动时是否自动加载所有 Skill
platforms.feishu.enabled	bool	是否启用飞书平台接入
platforms.telegram.enabled	bool	是否启用 Telegram 平台接入
platforms.discord.enabled	bool	是否启用 Discord 平台接入
log.level	string	日志级别：`debug` / `info` / `warn` / `error`
log.file	string	日志文件路径，留空则只输出到 stdout

最小可用配置

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 — 多模型配置：用 model_map 为不同任务指定不同模型，节省成本：

agent.model_map: { coding: "deepseek-v3", analysis: "claude-4-sonnet", quick: "gpt-4o-mini" }

三、常见问题排查

遇到问题时，先看日志：openclaw logs。大多数问题从这里能找到原因。

GPU 不被识别 / CUDA error

错误表现：启动时报 CUDA error: no CUDA-capable device found，或模型加载极慢（纯 CPU 速度）。

排查步骤：

1. 确认 NVIDIA GPU 已安装：nvidia-smi，有输出则 GPU 正常。

2. 确认 CUDA 驱动版本：nvidia-smi | head -4，左上角显示驱动版本，需 >= 450。

3. 确认 PyTorch CUDA 版本匹配：运行 python -c "import torch; print(torch.cuda.is_available())"，返回 True 才正常。

4. Docker 方式启动需加 --gpus all 参数：docker run --gpus all ...

常见原因：Docker daemon 没有启用 NVIDIA runtime。编辑 /etc/docker/daemon.json 加入 "default-runtime": "nvidia"，然后 sudo systemctl restart docker。

API Key 报错 / 401 Unauthorized

错误表现：日志出现 401 或 Authentication failed，Agent 无法发出请求。

排查步骤：

1. 确认 Key 拼写正确，没有多余空格或换行。Key 格式类似 sk-flowerwolf-xxxxx。

2. 确认 Key 有余额：登录 flowerwolf.net/token.html 查看余额。

3. 确认 proxy_url 正确：需包含完整路径如 https://api.flowerwolf.net/v1，末尾不带斜杠。

4. 检查 config.yaml 里的 proxy_url 是否填写了错误地址。

端口被占用 / Address already in use

错误表现：启动时报 port 8080 is already in use。

先用 ss -tlnp | grep 8080（或 netstat -tlnp | grep 8080）找到占用进程，然后用 kill <PID> 结束它。如果是被另一个 OpenClaw 实例占用，先用 openclaw stop 停止旧进程。

预防：每次重启前先 openclaw stop 再 openclaw start。

Agent 不回复消息 / 消息发出去没反应

排查步骤：

1. 确认对应平台（飞书/Telegram/Discord）的 Webhook 已正确配置并公网可达。

2. 飞书：确认事件订阅的「使用长连接接收事件」已开启，且机器人已添加到应用权限。

3. Telegram：确认 Bot Token 正确，webhook URL 格式为 https://your-domain/telegram/webhook。

4. 看日志里有没有收到消息的记录：openclaw logs | grep "received"。

5. 确认 Agent 没有在处理其他请求（单线程排队中），可用 openclaw status 查看队列状态。

模型响应极慢 / 超时

可能原因：

1. GPU 显存不足：模型太大，显存不够被迫用 CPU。尝试换更小的模型（如 gpt-4o-mini）或减小 max_tokens。

2. 网络问题：proxy_url 指向的节点网络延迟高。可 ping 一下测试：ping api.flowerwolf.net。

3. 请求排队：Token 余额不足时，API 会排队等待。检查余额或等待队列消化。

4. 模型加载慢：首次请求模型需要加载到显存，10–30秒，后续请求会快很多。

Skill 加载失败 / Skill not found

确认 Skill 文件在 config.yaml 指定的 skills.dir 目录下，文件格式为 .yaml 或 .py。文件名不能有中文和空格。

检查 Skill YAML 语法是否正确，必要字段：name、description、action（或 script）。参考 Skill 编写教程。

Docker 启动后立即退出 / container exited

运行 docker logs openclaw 查看退出原因。常见：config.yaml 格式错误（YAML 缩进敏感）、API Key 缺失、端口映射错误（-p 8080:8080 格式：主机端口:容器端口）。

四、使用技巧

多模型智能路由

不用同一个模型处理所有任务。通过 model_map 为不同任务指定最合适的模型：代码任务用 deepseek-v3（性价比最高），创意写作用 gpt-4o，长文分析用 claude-4-sonnet。

示例：在 Skill 里指定 model: deepseek-v3 可以让这个 Skill 始终使用特定模型，不受全局 model 设置影响。

Memory 管理：定期清理会话历史

OpenClaw 会话历史存储在 SQLite（默认）或 PostgreSQL。当对话变长时，用 session_limit 控制单会话最大消息数。超出后最早的消息会被自动摘要并压缩，不会无限增长。

如果想手动清理：openclaw memory purge --session <session-id>。查看当前会话数：openclaw memory stats。

Skill 编写：让 Agent 调用外部工具

Skill 是 OpenClaw 最强大的扩展机制。你可以写一个 Python 函数，让 Agent 在对话中调用它。

Skill 文件放在 skills/ 目录，每个 Skill 有描述（供 Agent 判断何时调用）和实现逻辑。

# skills/weather.yaml
name: get_weather
description: 查询指定城市的天气情况，例如"北京今天天气怎么样"
action: python
script: |
  def get_weather(city):
      # 调用天气API
      return f"{city}今天晴，温度25-30度，适宜出行"
  get_weather("{{city}}")

Agent 会自动识别何时需要调用 Skill，完全不需要手工触发。

GPU 显存不够？用量化模型

如果 GPU 显存有限（如 8GB），可以启用模型量化。量化后的模型体积缩小 50–75%，精度损失通常 < 3%。

在 config.yaml 里设置 gpu.quantization: "int8" 即可启用 INT8 量化。注意：量化需要在模型首次加载时完成，重启后生效。

用 Cron Job 实现自动化

OpenClaw 支持 Cron Job，可以定期执行任务。比如：「每天早上 9 点汇总昨天的销售数据」、「每小时检查一次服务器状态，有异常就报警」。

在 config.yaml 里配置：cron: { "0 9 * * *": "summarize_sales" }。任务名称对应一个 Skill。

多 Agent 协作：分配不同角色

OpenClaw 支持多 Agent 协作。你可以让一个 Agent 负责代码审查，另一个负责回复客户，第三个负责数据监控。它们通过共享 Memory 通信，各司其职。

在 config.yaml 里配置多个 agents[]，每个有独立的 name、model、role。

日志调试：打开 debug 模式

遇到问题时，把 log.level 改为 debug 重启，日志会输出每个请求的完整上下文和 Agent 的推理过程，信息量很大，适合定位疑难杂症。

正常运行时改回 info，避免日志膨胀。

Web UI 的隐藏功能

OpenClaw 的 Web UI（端口 8080）不只用于聊天。点右上角设置图标可以：查看当前 Token 余额（调用 FlowerWolf API 实时查询）、切换当前 Agent 模型、清空会话历史、导出对话记录为 JSON。

五、多平台接入

OpenClaw 支持同时接入飞书、Telegram、Discord 等多个平台，不同平台的消息统一汇聚到同一个 Agent 处理。

平台	配置字段前缀	关键配置项
飞书	platforms.feishu	app_id, app_secret, bot_name, enable_dm, enable_group
Telegram	platforms.telegram	bot_token, admin_ids（管理员 Telegram ID 列表）
Discord	platforms.discord	bot_token, guild_id, channel_ids
微信（企业）	platforms.wechat	corp_id, corp_secret, agent_id

飞书接入注意事项：

1. 在 open.feishu.cn 创建应用，开通「机器人」能力。

2. 配置事件订阅时选择「使用长连接接收事件」（不需要公网 Webhook URL）。

3. 需要开通权限：im:message（读取消息）、im:message:send_as_bot（发送消息）。

4. 群组消息需要在应用配置里开启「允许机器人接收群消息」并配置 FEISHU_GROUP_POLICY=open 环境变量。

六、常见问答

问：OpenClaw 和直接调用 API 有什么区别？

直接调用 API 只能做单轮问答。OpenClaw 在 API 之上加了一层 Agent 框架：多轮对话记忆管理、Skill 调用机制、平台接入（飞书/Telegram）、Cron 自动化、调试工具等。相当于给 API 加了「操作系统」。

问：一台机器能跑几个 OpenClaw 实例？

取决于你的 GPU 显存。每个实例加载一个模型（3–10GB 显存）。4090 24GB 显存可以跑 2 个实例（一个主力模型 + 一个备用），3090 24GB 同理。CPU 模式则只受内存限制，16GB RAM 可跑 3–5 个实例。

问：OpenClaw 支持哪些模型？

理论上支持所有 OpenAI API 兼容格式的模型。实测可用：GPT-4o、GPT-4o mini、Claude 4 Sonnet、Claude 3.5 Sonnet、Gemini 2.0 Flash、DeepSeek V3、Qwen Turbo、豆包等。通过 FlowerWolf Token 超市统一接入，无需逐一对接。

问：如何备份 OpenClaw 数据？

定期备份 data/ 目录（包含 SQLite 数据库和模型缓存）。如果使用 PostgreSQL，备份数据库即可。配置文件 config.yaml 也建议定期备份。Docker 方式可用 docker cp openclaw:/app/data ./openclaw-data-backup。