OpenClaw 常见问题解答：部署和运行中的 20 个高频问题

OpenClaw 常见问题解答

本文收录了社区中出现频率最高的 20 个问题，按类别整理，遇到问题可直接跳转对应章节。

---

安装与启动问题

Q1：执行 docker compose up 后 API 容器反复重启，日志显示 Connection refused

原因：API 服务在 PostgreSQL 完全就绪前就尝试连接。

解决方案：在 docker-compose.yml 的 api 服务中添加健康检查等待：

depends_on:
  postgres:
    condition: service_healthy

# postgres 服务增加 healthcheck
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
  interval: 5s
  timeout: 5s
  retries: 10

Q2：启动时报 SECRET_KEY not set

原因：.env 文件未正确加载，或 SECRET_KEY 变量为空。

# 检查 .env 是否存在且非空
cat .env | grep SECRET_KEY

# 手动生成并设置
echo "SECRET_KEY=$(openssl rand -hex 32)" >> .env

Q3：镜像拉取失败，提示 timeout

国内服务器直接拉取 Docker Hub 镜像可能超时。

# 配置镜像加速
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://registry.cn-hangzhou.aliyuncs.com"
  ]
}
EOF
sudo systemctl daemon-reload && sudo systemctl restart docker

---

Agent 运行问题

Q4：Agent 收到消息后无响应，Worker 日志显示 Task pending 一直不处理

原因：Worker 进程未启动，或 Redis 队列连接失败。

# 检查 worker 容器状态
docker compose ps worker

# 查看 worker 日志
docker compose logs worker --tail=50

# 测试 Redis 连通性
docker compose exec worker redis-cli -h redis -a ${REDIS_PASSWORD} ping
# 预期返回：PONG

Q5：Agent 调用工具时报 ToolExecutionError: timeout

原因：工具执行超时，默认超时为 30 秒。

在 Agent 配置中调整：

{
  "tool_timeout": 120,
  "max_retries": 3
}

Q6：多轮对话后 Agent 「失忆」，不记得之前说过的内容

原因：会话上下文未持久化，或 session_id 在前端请求时未正确传递。

# 正确：每次请求携带相同 session_id
response = client.chat(
    session_id="user_123_session_456",  # 必须固定
    message="继续上面的话题"
)

Q7：Agent 返回内容被截断，明显没说完

原因：max_tokens 设置过低，或 LLM 提供商的 token 限制。

# 在 Agent 配置中增加
llm:
  max_tokens: 4096  # 根据模型上限调整
  stream: true       # 开启流式输出避免超时

---

性能与稳定性问题

Q8：并发请求多时响应变慢，CPU 飙升

原因：Worker 进程数不足。

# 扩展 Worker 实例数
docker compose up -d --scale worker=4

同时检查 LLM 提供商的 RPM（每分钟请求数）限制。

Q9：PostgreSQL 连接数报警 too many connections

原因：每个 API 实例默认开启较多连接池。

# .env 中降低每实例连接数
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10

或者在 PostgreSQL 前加 PgBouncer 连接池。

Q10：磁盘使用率增长很快

OpenClaw 默认保留所有对话日志。清理策略：

-- 清理 30 天前的对话记录
DELETE FROM conversation_logs
WHERE created_at < NOW() - INTERVAL '30 days';

建议定期执行或设置定时任务。

---

集成与 API 问题

Q11：调用 OpenClaw API 返回 401

# 检查 Authorization header 格式
curl -H "Authorization: Bearer YOUR_TOKEN" https://your-domain.com/api/v1/agents
# 注意：Bearer 后面有一个空格

Q12：Webhook 收不到回调

原因：服务器防火墙拦截了出站请求，或 Webhook URL 不可达。

# 在服务器上测试出站连通性
curl -X POST YOUR_WEBHOOK_URL -d '{"test": true}'

# 检查防火墙规则
sudo ufw status

Q13：如何接入企业微信 / 钉钉

OpenClaw 官方提供了 Channel 适配器，在管理后台 设置 → 渠道 中配置对应平台的 AppID 和 Token 即可，无需修改代码。

---

升级与维护问题

Q14：升级后出现 Migration failed 错误

# 升级前务必备份数据库
docker compose exec postgres pg_dump -U ${POSTGRES_USER} ${POSTGRES_DB} > backup_$(date +%Y%m%d).sql

# 手动执行迁移
docker compose exec api python manage.py migrate --plan  # 先预览
docker compose exec api python manage.py migrate

Q15：如何回滚到上一个版本

# 修改 docker-compose.yml 中的镜像 tag
image: openclaw/api:1.2.3  # 改为上一个稳定版本号

# 重新部署
docker compose up -d

# 数据库可能需要回滚迁移
docker compose exec api python manage.py migrate myapp 0012  # 指定迁移编号

---

其余高频问题

Q16 - Q20 快速解答

问题	答案
如何修改 Agent 的系统提示词？	管理后台 → Agent → 编辑 → System Prompt
支持哪些 LLM？	OpenAI、DeepSeek、Qwen、本地 Ollama 均支持
数据存在哪里？	PostgreSQL（结构化数据）+ 本地磁盘（文件附件）
有没有 Python SDK？	有，pip install openclaw-sdk
免费版和付费版区别？	免费版无用量限制，付费版有优先技术支持

---

问题没有解决？

如果上述方案都无法解决你的问题，可以在 LocalClaw（insman.cn） 上找到专业的 OpenClaw 服务商，提供有偿的技术排查服务，通常 1 个工作日内响应。