🦞 OpenClaw 服务部署
与 API 访问权限配置指南

企业级 AI Agent 网关完整部署方案 —— 从环境准备、Docker 容器化部署到 API 认证配置、安全加固的全流程实操手册

📅 更新日期：2026 年 3 月 12 日 📦 OpenClaw 版本：v2026.3.8 🔐 安全级别：企业生产环境 ⏱️ 预计耗时：60-90 分钟

1. 部署前准备与安全警告

⚠️ 重要安全警告（2026 年 3 月工信部预警）

截至 2026 年 3 月，全球超过 12 万 OpenClaw 实例因配置不当暴露于公网，导致大规模 API 密钥窃取和恶意软件传播事件。请务必遵循以下安全准则：

  • 禁止公网裸奔：不要将 OpenClaw Web UI（默认端口 3000）直接暴露于公网
  • 强制认证：必须配置强密码和 API Token 认证
  • 网络隔离：使用防火墙限制访问来源 IP，仅允许可信网络
  • 定期更新：保持 OpenClaw 为最新版本（当前 v2026.3.8），及时修复 CVE 漏洞
  • 密钥管理：API Key 存储在 ~/.openclaw/.env 文件，设置 600 权限（仅所有者可读写）
  • 技能包审查：仅安装官方或可信来源的技能包，避免供应链攻击

1.1 刑事风险警示

风险场景 可能罪名 后果
配置裸奔 非法获取计算机信息系统数据罪 API 密钥、Cookie、SSH 密钥被盗
权限失控 非法控制计算机信息系统罪 设备被接管用于挖矿、DDoS 攻击
恶意技能包 提供侵入、非法控制计算机信息系统程序、工具罪 unknowingly 传播后门程序
数据泄露 侵犯公民个人信息罪 用户隐私数据超范围收集/泄露
✅ 本指南安全承诺：

本部署指南严格遵循 2026 年最新安全标准，包含完整的认证配置、网络隔离、密钥管理和审计日志功能。按照本指南部署的 OpenClaw 实例可达到企业生产环境安全级别。

2. 系统要求与环境诊断

2.1 硬件与软件要求

💻 操作系统

  • Windows 10+ (1903 或更高)
  • macOS 12+ (Monterey 或更高)
  • Linux: Ubuntu 20.04+, Debian 11+, CentOS 8+
  • WSL2 (Windows Subsystem for Linux) 推荐

🧠 硬件配置

  • CPU: 双核 2.0GHz+ (推荐 4 核+)
  • 内存：最低 2GB，推荐 4GB+
  • 磁盘：500MB 可用空间（不含模型缓存）
  • 网络：稳定互联网连接（调用 AI API）

🛠️ 必需软件

  • Node.js 22+ LTS (必须，18/20 不兼容)
  • npm 10+ 或 pnpm 9+
  • Git 2.30+ (源码安装需要)
  • Docker 20+ (容器化部署需要)

🔧 可选依赖

  • Python 3.10+ (部分技能需要)
  • Ollama (本地模型推理)
  • nvm (Node 版本管理，推荐)
  • 1Panel (面板管理，可选)

2.2 环境诊断命令

# 1. 检查 Node.js 版本（必须 22+） node --version # 期望输出：v22.x.x 或 v23.x.x # 2. 检查 npm/pnpm 版本 npm --version pnpm --version # 3. 检查 Git 安装 git --version # 4. 检查 Docker（如使用容器化部署） docker --version docker-compose --version # 5. 检查端口占用情况（3000 端口） # Linux/macOS: lsof -i :3000 netstat -tlnp | grep 3000 # Windows: netstat -ano | findstr :3000 # 6. 检查网络连接（访问 AI API） curl -I https://api.anthropic.com curl -I https://api.openai.com # 7. 检查磁盘空间 df -h ~ # Windows: wmic logicaldisk get size,freespace,caption

2.3 自动诊断工具

# OpenClaw 内置诊断命令（安装后使用） openclaw doctor # 输出示例： ✓ Node.js v22.14.0 (required: >=22.0.0) ✓ npm 10.8.0 ✓ Configuration file exists: ~/.openclaw/.env ✓ Network connectivity: OK ✓ Port 3000 is available ⚠ Warning: Python 3.9 detected (some skills require 3.10+)

3. 安装方式选择与对比

3.1 四种安装方式对比

安装方式 适用场景 优点 缺点 推荐度
Docker 容器化 生产环境、服务器部署 环境隔离、一键部署、易维护 需要 Docker 基础 ⭐⭐⭐⭐⭐
npm/pnpm 全局安装 开发环境、个人使用 简单快速、版本管理方便 污染全局环境 ⭐⭐⭐⭐
源码编译 定制开发、贡献代码 完全掌控、可修改源码 复杂、需要构建工具链 ⭐⭐⭐
一键安装脚本 快速体验、新手入门 最简单、自动化程度高 自定义能力弱 ⭐⭐⭐⭐
💡 推荐方案：
  • 生产环境：Docker Compose 部署（本指南重点讲解）
  • 开发环境：pnpm 全局安装（速度快、节省空间）
  • Windows 用户：WSL2 + Docker（避免原生 Windows 环境坑）

4. Docker 容器化部署（推荐）

步骤 1：安装 Docker 环境

# ===== Linux (Ubuntu/Debian) ===== # 卸载旧版本（如有） sudo apt-get remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg lsb-release # 添加 Docker GPG 密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 设置稳定版仓库 echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 Docker Engine sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 验证安装 docker --version docker compose version # 将当前用户加入 docker 组（免 sudo） sudo usermod -aG docker $USER newgrp docker # ===== macOS ===== # 使用 Homebrew 安装 Docker Desktop brew install --cask docker # 然后打开 Applications/Docker.app 完成安装 # ===== Windows ===== # 下载 Docker Desktop: https://www.docker.com/products/docker-desktop/ # 运行安装程序，按向导完成安装 # 启用 WSL2 后端（设置 → General → Use WSL 2 based engine）

步骤 2：创建配置文件与目录结构

# 创建 OpenClaw 工作目录 mkdir -p ~/openclaw/{data,config,logs} cd ~/openclaw # 创建 .env 配置文件 cat > .env << 'EOF' # ========== AI 模型配置 ========== # 选择并配置一个主要模型提供商（必填） ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx # OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx # GOOGLE_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx # OLLAMA_HOST=http://host.docker.internal:11434 # ========== 网络配置 ========== PORT=3000 HOST=0.0.0.0 # ========== 安全配置 ========== # 生成强密码作为 Dashboard 访问令牌 OPENCLAW_TOKEN=your_secure_random_token_here # 启用 HTTPS（生产环境强烈建议） HTTPS_ENABLED=false # HTTPS_CERT_PATH=/path/to/cert.pem # HTTPS_KEY_PATH=/path/to/key.pem # ========== 存储配置 ========== DATA_DIR=/app/data CONFIG_DIR=/app/config LOG_LEVEL=info # ========== 代理配置（国内用户可选）========== # HTTP_PROXY=http://proxy-server:port # HTTPS_PROXY=http://proxy-server:port # NO_PROXY=localhost,127.0.0.1 # ========== 高级配置 ========== # MAX_CONTEXT_LENGTH=100000 # DEFAULT_MODEL=claude-sonnet-4-20250514 # FALLBACK_MODELS=claude-3-5-sonnet-20241022,gpt-4o EOF # 设置 .env 文件权限（仅所有者可读写） chmod 600 .env # 创建数据目录 mkdir -p data config logs chmod 700 data config logs

步骤 3：编写 Docker Compose 配置文件

# docker-compose.yml version: '3.8' services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - "${PORT:-3000}:3000" volumes: - ./data:/app/data - ./config:/app/config - ./logs:/app/logs - ~/.openclaw:/root/.openclaw env_file: - .env environment: - NODE_ENV=production - TZ=Asia/Shanghai networks: - openclaw-network healthcheck: test: ["CMD", "curl", "-f", "http://localhost:3000/health"] interval: 30s timeout: 10s retries: 3 start_period: 40s deploy: resources: limits: cpus: '2.0' memory: 2G reservations: cpus: '0.5' memory: 512M # 可选：Nginx 反向代理（生产环境推荐） nginx: image: nginx:alpine container_name: openclaw-nginx restart: unless-stopped ports: - "80:80" - "443:443" volumes: - ./nginx.conf:/etc/nginx/nginx.conf:ro - ./ssl:/etc/nginx/ssl:ro depends_on: - openclaw networks: - openclaw-network networks: openclaw-network: driver: bridge

步骤 4：配置 Nginx 反向代理（可选但推荐）

# nginx.conf - 生产环境配置 events { worker_connections 1024; } http { # 安全头 add_header X-Frame-Options "SAMEORIGIN" always; add_header X-Content-Type-Options "nosniff" always; add_header X-XSS-Protection "1; mode=block" always; add_header Referrer-Policy "strict-origin-when-cross-origin" always; # 限流配置 limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s; server { listen 80; server_name your-domain.com; # 强制跳转到 HTTPS return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; # SSL 证书配置 ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; ssl_prefer_server_ciphers on; location / { proxy_pass http://openclaw:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket 支持 proxy_read_timeout 86400s; proxy_send_timeout 86400s; # 限流 limit_req zone=api_limit burst=20 nodelay; } # 健康检查端点 location /health { proxy_pass http://openclaw:3000/health; access_log off; } } }

步骤 5：启动 OpenClaw 服务

# 拉取最新镜像 docker compose pull # 后台启动服务 docker compose up -d # 查看启动日志 docker compose logs -f openclaw # 检查服务状态 docker compose ps docker inspect openclaw --format='{{.State.Health.Status}}' # 期望输出：healthy # 测试服务是否正常运行 curl http://localhost:3000/health # 期望输出：{"status":"ok","version":"2026.3.8"}

步骤 6：初始化配置向导

# 进入容器执行初始化 docker exec -it openclaw openclaw onboard # 交互式配置向导将引导你完成： 1. 选择 AI 供应商（Anthropic/OpenAI/Google/Ollama） 2. 输入 API Key（如未在 .env 中配置） 3. 连接聊天平台（Telegram/WhatsApp/Discord 等） 4. 发送测试消息验证配置 # 配置完成后，访问 Web Dashboard 浏览器打开：http://localhost:3000/?token=YOUR_TOKEN

5. Linux/macOS 原生部署

5.1 一键安装脚本（推荐）

# ===== Linux/macOS 一键安装 ===== curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git # 或使用 npm 安装 npm i -g openclaw@beta # 或使用 pnpm（更快更省空间） pnpm add -g openclaw@beta # 验证安装 openclaw --version openclaw doctor # 运行初始化向导 openclaw onboard

5.2 配置 Daemon 服务（开机自启）

# 创建 systemd 服务文件（Linux） sudo tee /etc/systemd/system/openclaw.service > /dev/null << 'EOF' [Unit] Description=OpenClaw AI Agent Gateway After=network.target [Service] Type=simple User=your-username WorkingDirectory=/home/your-username ExecStart=/usr/bin/openclaw start Restart=on-failure RestartSec=10 Environment=NODE_ENV=production LimitNOFILE=65536 [Install] WantedBy=multi-user.target EOF # 重新加载 systemd 并启动服务 sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw sudo systemctl status openclaw # macOS 使用 launchd openclaw onboard --install-daemon

6. Windows 部署方案

⚠️ Windows 部署注意事项：

强烈建议使用 WSL2 部署 OpenClaw，避免原生 Windows 环境的 Node.js 版本、PowerShell 权限、C++ 编译工具等问题。

6.1 WSL2 部署（推荐）

# PowerShell（管理员权限）安装 WSL2 wsl --install -d Ubuntu-22.04 # 重启电脑后，在 WSL 终端中执行 curl -fsSL https://openclaw.ai/install.sh | bash # 后续步骤与 Linux 相同

6.2 原生 Windows 部署

# PowerShell（管理员权限）一键安装 curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd --tag beta && del install.cmd # 验证安装 openclaw --version openclaw doctor openclaw onboard

7. API Key 配置与模型接入

7.1 主流 AI 平台 API Key 获取

平台 获取地址 推荐模型 价格参考
Anthropic console.anthropic.com Claude Sonnet 4 $3-15 / 1M tokens
OpenAI platform.openai.com GPT-4o $5-30 / 1M tokens
Google aistudio.google.com Gemini 2.0 Pro $1-7 / 1M tokens
智谱 AI open.bigmodel.cn GLM-4 ¥0.005-0.1 / K tokens
DeepSeek platform.deepseek.com DeepSeek-V3 ¥0.3-1 / 1M tokens

7.2 多模型 fallback 配置

# ~/.openclaw/.env 多模型配置示例 # 主模型（Anthropic Claude） ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx DEFAULT_MODEL=claude-sonnet-4-20250514 # Fallback 模型（当主模型限流或不可用时自动切换） FALLBACK_MODELS=claude-3-5-sonnet-20241022,gpt-4o,deepseek-chat # OpenAI 备用 OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx # DeepSeek 备用（成本低） DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 模型路由策略 MODEL_ROUTING_STRATEGY=priority COOLDOWN_PERIOD=60s MAX_RETRIES=3

7.3 本地模型部署（Ollama）

# 安装 Ollama curl -fsSL https://ollama.ai/install.sh | sh # 拉取开源模型 ollama pull qwen2.5-coder:32b ollama pull llama-3.1-70b ollama pull deepseek-coder:33b # 配置 OpenClaw 使用本地模型 echo "OLLAMA_HOST=http://host.docker.internal:11434" >> ~/.openclaw/.env echo "DEFAULT_MODEL=qwen2.5-coder:32b" >> ~/.openclaw/.env # 重启 OpenClaw docker compose restart openclaw

8. 聊天平台集成配置

8.1 支持的聊天平台

💬 Telegram

  • 通过 @BotFather 创建 Bot
  • 获取 Bot Token
  • 支持群聊/私聊
  • 完全免费

📱 WhatsApp

  • 扫描二维码连接
  • 支持个人号/商务号
  • 需保持在线状态
  • 注意封号风险

🎮 Discord

  • 开发者门户创建应用
  • 配置 Bot 权限
  • 支持服务器/频道
  • 适合社区运营

📧 Email

  • IMAP/SMTP 协议
  • 自动回复邮件
  • 支持附件处理
  • 适合工单系统

8.2 Telegram Bot 配置示例

# 1. 在 Telegram 搜索 @BotFather # 2. 发送 /newbot 创建新 Bot # 3. 按提示设置 Bot 名称和用户名 # 4. 获取 Bot Token（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz） # 5. 在 OpenClaw 中配置 openclaw configure channels.telegram.enabled true openclaw configure channels.telegram.token 123456789:ABCdefGHIjklMNOpqrsTUVwxyz # 6. 重启 OpenClaw docker compose restart openclaw # 7. 向 Bot 发送 /start 测试

9. API 访问权限与认证配置

9.1 API 认证方式

认证方式 安全性 适用场景 配置方法
Token 认证 ⭐⭐⭐⭐ Web Dashboard 访问 URL 参数 ?token=xxx
API Key 认证 ⭐⭐⭐⭐⭐ REST API 调用 Header: X-API-Key
JWT 认证 ⭐⭐⭐⭐⭐ 企业 SSO 集成 Bearer Token
Basic Auth ⭐⭐⭐ 内部测试环境 username:password

9.2 生成 API Key

# 方法 1：通过 OpenClaw CLI 生成 openclaw api-keys create --name "Production API Key" --permissions read,write,execute # 输出： ✓ API Key created: ocak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ⚠️ Save this key securely. It won't be shown again. # 方法 2：手动生成强随机 Token openssl rand -hex 32 # 输出：a1b2c3d4e5f6... # 方法 3：使用 Python 生成 python3 -c "import secrets; print(secrets.token_urlsafe(32))"

9.3 配置 API 访问控制

# ~/.openclaw/.env API 安全配置 # 启用 API 认证 API_AUTH_ENABLED=true # API Key 列表（逗号分隔） API_KEYS=ocak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx,ocak_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy # 权限配置 API_PERMISSIONS=read,write,execute,admin # IP 白名单（可选，逗号分隔） API_IP_WHITELIST=192.168.1.0/24,10.0.0.0/8 # 速率限制（请求数/分钟） API_RATE_LIMIT=100 # CORS 配置 CORS_ORIGINS=https://your-domain.com,https://admin.your-domain.com CORS_METHODS=GET,POST,PUT,DELETE CORS_ALLOWED_HEADERS=Content-Type,Authorization,X-API-Key # JWT 配置（如使用 JWT 认证） JWT_SECRET=your_jwt_secret_key_here_minimum_32_chars JWT_EXPIRY=24h JWT_ISSUER=openclaw.your-company.com

9.4 REST API 调用示例

# ===== cURL 示例 ===== # 1. 发送消息到 OpenClaw curl -X POST https://your-domain.com/api/v1/messages \ -H "Content-Type: application/json" \ -H "X-API-Key: ocak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -d '{ "channel": "telegram", "recipient": "@username", "content": "你好，请帮我分析这个需求文档...", "priority": "normal" }' # 2. 查询任务状态 curl -X GET https://your-domain.com/api/v1/tasks/task-123 \ -H "X-API-Key: ocak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # 3. 执行系统命令（需要 execute 权限） curl -X POST https://your-domain.com/api/v1/execute \ -H "Content-Type: application/json" \ -H "X-API-Key: ocak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -d '{ "command": "ls -la /app/data", "timeout": 30 }' # 4. 上传文件 curl -X POST https://your-domain.com/api/v1/files \ -H "X-API-Key: ocak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -F "file=@/path/to/document.pdf" \ -F "description=需求文档" # ===== Python 示例 ===== import requests API_BASE = "https://your-domain.com/api/v1" API_KEY = "ocak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" headers = {"X-API-Key": API_KEY} # 发送消息 response = requests.post( f"{API_BASE}/messages", headers=headers, json={ "channel": "telegram", "recipient": "@username", "content": "Hello from Python!" } ) print(response.json())

10. 安全加固与最佳实践

10.1 安全配置清单

🔐 OpenClaw 安全加固检查清单

10.2 防火墙配置（UFW）

# Linux UFW 防火墙配置 # 启用防火墙 sudo ufw enable # 默认拒绝所有入站 sudo ufw default deny incoming sudo ufw default allow outgoing # 允许 SSH（防止把自己锁在外面） sudo ufw allow 22/tcp # 允许 HTTP/HTTPS（通过 Nginx） sudo ufw allow 80/tcp sudo ufw allow 443/tcp # 如需直接访问 OpenClaw（不推荐） # sudo ufw allow from 192.168.1.0/24 to any port 3000 proto tcp # 查看状态 sudo ufw status verbose # 重置规则（如需） sudo ufw reset

10.3 Fail2Ban 防暴力破解

# 安装 Fail2Ban sudo apt-get install fail2ban -y # 创建 OpenClaw 防护规则 sudo tee /etc/fail2ban/jail.d/openclaw.local > /dev/null << 'EOF' [openclaw] enabled = true port = 3000,80,443 filter = openclaw logpath = /var/log/openclaw/*.log maxretry = 5 bantime = 3600 findtime = 600 EOF sudo systemctl restart fail2ban sudo fail2ban-client status openclaw

10.4 自动备份脚本

#!/bin/bash # backup-openclaw.sh - OpenClaw 自动备份脚本 BACKUP_DIR="/backup/openclaw" DATE=$(date +%Y%m%d_%H%M%S) RETENTION_DAYS=30 # 创建备份目录 mkdir -p ${BACKUP_DIR} # 备份配置文件 tar -czf ${BACKUP_DIR}/config_${DATE}.tar.gz \ ~/.openclaw/.env \ ~/openclaw/config/ \ ~/openclaw/docker-compose.yml # 备份数据目录 tar -czf ${BACKUP_DIR}/data_${DATE}.tar.gz \ ~/openclaw/data/ # 备份日志（最近 7 天） find ~/openclaw/logs -mtime -7 -type f | \ tar -czf ${BACKUP_DIR}/logs_${DATE}.tar.gz -T - # 加密备份（可选） # openssl enc -aes-256-cbc -salt -in ${BACKUP_DIR}/data_${DATE}.tar.gz \ # -out ${BACKUP_DIR}/data_${DATE}.tar.gz.enc -pass pass:${ENCRYPTION_PASSWORD} # 删除旧备份 find ${BACKUP_DIR} -name "*.tar.gz" -mtime +${RETENTION_DAYS} -delete # 上传到云存储（可选） # aws s3 cp ${BACKUP_DIR} s3://your-bucket/openclaw-backups/ --recursive echo "Backup completed: ${DATE}"
# 添加到 crontab（每天凌晨 2 点备份） crontab -e # 添加以下行 0 2 * * * /usr/local/bin/backup-openclaw.sh >> /var/log/openclaw-backup.log 2>&1

11. 验证测试与故障排查

11.1 健康检查

# 1. 检查容器状态 docker compose ps # 期望输出：openclaw - Running (healthy) # 2. 检查服务日志 docker compose logs openclaw | tail -50 # 3. 测试健康端点 curl http://localhost:3000/health # 期望输出：{"status":"ok","version":"2026.3.8","uptime":"2h30m"} # 4. 测试 API 端点 curl -H "X-API-Key: ocak_xxx" http://localhost:3000/api/v1/status # 5. 发送测试消息 curl -X POST http://localhost:3000/api/v1/messages \ -H "Content-Type: application/json" \ -H "X-API-Key: ocak_xxx" \ -d '{"channel":"test","content":"Hello OpenClaw!"}'

11.2 常见问题排查

问题现象 可能原因 解决方案
容器启动失败 端口冲突、内存不足、缺少环境变量 检查端口占用、增加内存、确认.env 配置
API Key 认证失败 Key 错误、权限不足、IP 不在白名单 验证 Key 格式、检查权限配置、确认 IP 白名单
无法连接 AI API 网络问题、Key 无效、速率限制 检查网络连接、验证 API Key、查看配额
WebSocket 断开 Nginx 配置不当、超时设置过短 配置 proxy_read_timeout、启用 WebSocket 支持
二维码不显示 终端不支持、无头服务器 更换终端、使用 WebChat 界面扫码
技能加载失败 依赖缺失、权限问题、版本不兼容 安装 Python 依赖、检查文件权限、升级 OpenClaw

11.3 调试模式

# 启用调试日志 openclaw configure log_level debug docker compose restart openclaw # 实时查看日志 docker compose logs -f openclaw # 进入容器调试 docker exec -it openclaw bash # 在容器内测试 openclaw doctor openclaw test-connection

12. K8S 集群部署方案

12.1 Helm Chart 部署

# 添加 OpenClaw Helm Repository helm repo add openclaw https://feiskyer.github.io/openclaw-kubernetes helm repo update # 创建命名空间 kubectl create namespace openclaw # 创建 values.yaml 配置文件 cat > values.yaml << 'EOF' replicaCount: 2 image: repository: openclaw/openclaw tag: latest pullPolicy: IfNotPresent service: type: ClusterIP port: 3000 ingress: enabled: true className: nginx hosts: - host: openclaw.your-domain.com paths: - path: / pathType: Prefix tls: - secretName: openclaw-tls hosts: - openclaw.your-domain.com env: - name: ANTHROPIC_API_KEY valueFrom: secretKeyRef: name: openclaw-secrets key: anthropic-api-key - name: API_KEYS valueFrom: secretKeyRef: name: openclaw-secrets key: api-keys persistence: enabled: true storageClass: nfs-client size: 10Gi accessModes: - ReadWriteMany resources: limits: cpu: 2000m memory: 2Gi requests: cpu: 500m memory: 512Mi autoscaling: enabled: true minReplicas: 2 maxReplicas: 10 targetCPUUtilizationPercentage: 80 EOF # 部署 OpenClaw helm install openclaw openclaw/openclaw \ --namespace openclaw \ -f values.yaml # 查看部署状态 kubectl get pods -n openclaw kubectl get svc -n openclaw kubectl get ingress -n openclaw

12.2 创建 Kubernetes Secrets

# 创建 Secret 存储敏感信息 kubectl create secret generic openclaw-secrets \ --from-literal=anthropic-api-key='sk-ant-api03-xxx' \ --from-literal=api-keys='ocak_xxx,ocak_yyy' \ --from-literal=jwt-secret='your_jwt_secret_here' \ -n openclaw # 查看 Secret（base64 编码） kubectl get secret openclaw-secrets -n openclaw -o yaml