05 - 实施与部署指南

部署模式选择

OpenClaw 支持多种部署模式，根据使用场景选择合适的方式：

模式一：本地部署 (推荐个人使用)

适用场景:

• 个人助手，数据完全本地
• 开发和测试环境
• 对隐私和安全要求极高

优势:

• 数据不离开本地机器
• 零网络延迟
• 完全控制配置

劣势:

• 需要保持设备在线
• 无法共享给其他用户

部署步骤:

# 1. 安装 Node.js >=22
nvm install 22
nvm use 22

# 2. 全局安装 OpenClaw
npm install -g openclaw@latest

# 3. 运行初始化向导
openclaw onboard --install-daemon

# 4. 启动 Gateway
openclaw gateway --port 18789 --verbose

# 5. 连接 Telegram Bot
openclaw channels login telegram

模式二：远程服务器部署 (推荐团队使用)

适用场景:

• 团队共享 AI 助手
• 需要 24/7 可用性
• 多设备访问

优势:

• 持续运行，不依赖个人设备
• 可被多个客户端访问
• 便于集中管理和监控

劣势:

• 需要服务器资源
• 需要配置安全访问

部署平台选项:

Railway 部署示例:

# 1. Fork OpenClaw 仓库
# 2. 在 Railway 导入项目
# 3. 配置环境变量:
TELEGRAM_BOT_TOKEN=your_token_here
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here

# 4. Railway 自动构建和部署
# 5. 获取 Railway 提供的公共 URL
# 6. 配置 Telegram Bot Webhook 指向该 URL

模式三：混合部署 (本地 Gateway + 远程 Nodes)

适用场景:

• 保持 Gateway 控制核心功能
• 设备特定功能在本地执行
• 需要跨设备协作

架构:

Remote Gateway (Linux Server)
    ├── AI Agent Runtime
    ├── Tool Registry
    └── Channel Connections
            │
            │ Tailscale / SSH Tunnel
            ▼
Local macOS/iOS/Android Nodes
    ├── Camera, Screen Recording
    ├── System Run (host commands)
    └── Canvas Rendering

优势:

• 核心功能持续可用
• 设备敏感操作在本地执行
• 平衡性能和隐私

配置示例:

{
  "gateway": {
    "bind": "127.0.0.1",
    "tailscale": {
      "mode": "serve"
    }
  },
  "nodes": {
    "autoConnect": ["macbook-local", "iphone-local"]
  }
}

配置文件详解

最小配置 (~/.openclaw/openclaw.json)

{
  "agent": {
    "model": "anthropic/claude-opus-4-5"
  },
  "channels": {
    "telegram": {
      "botToken": "123456:ABCDEF"
    }
  }
}

完整配置示例

{
  "gateway": {
    "bind": "127.0.0.1",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "gateway-secret-here"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  },
  "agent": {
    "model": "anthropic/claude-opus-4-5",
    "defaults": {
      "workspace": "/Users/username/.openclaw/workspace",
      "thinking": "medium",
      "verbose": false,
      "sandbox": {
        "mode": "non-main",
        "allowlist": ["bash", "read", "write"],
        "denylist": ["browser", "canvas"]
      }
    },
    "models": [
      {
        "id": "anthropic/claude-opus-4-5",
        "provider": "anthropic",
        "authProfile": "claude-pro"
      },
      {
        "id": "openai/gpt-4-turbo",
        "provider": "openai",
        "authProfile": "openai-key"
      }
    ]
  },
  "channels": {
    "telegram": {
      "botToken": "123456:ABCDEF",
      "dmPolicy": "pairing",
      "allowFrom": ["trusted-user"],
      "groups": {
        "group-123": {
          "requireMention": true,
          "activation": "mention"
        }
      },
      "webhookUrl": "https://mydomain.com/webhook/telegram",
      "webhookSecret": "webhook-secret"
    },
    "whatsapp": {
      "allowFrom": ["+1234567890", "+9876543210"],
      "groups": ["*"]
    }
  },
  "tools": {
    "browser": {
      "enabled": true,
      "color": "#FF4500"
    },
    "canvas": {
      "enabled": true,
      "port": 18793
    },
    "cron": {
      "enabled": true,
      "timezone": "Asia/Shanghai"
    }
  },
  "logging": {
    "level": "info",
    "files": {
      "gateway": "/var/log/openclaw/gateway.log",
      "agent": "/var/log/openclaw/agent.log"
    }
  }
}

环境变量配置

必需变量

可选变量

Docker 环境变量

# docker-compose.yml
version: '3.8'
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:2026.1.29
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENCLAW_GATEWAY_TOKEN=${GATEWAY_TOKEN}
    volumes:
      - ~/.openclaw:/app/.openclaw
      - ~/.openclaw/workspace:/app/.openclaw/workspace
    ports:
      - "18789:18789"
      - "18793:18793"
    restart: unless-stopped

安全最佳实践

1. 访问控制

本地 Gateway:

{
  "gateway": {
    "bind": "127.0.0.1",  // 仅监听本地
    "auth": {
      "mode": "token"      // 启用令牌认证
    }
  }
}

远程访问 (Tailscale):

{
  "gateway": {
    "tailscale": {
      "mode": "serve",      // 仅 tailnet 内可访问
      "allowPublic": false
    }
  }
}

公网访问 (谨慎使用):

{
  "gateway": {
    "auth": {
      "mode": "password",   // 启用密码认证
      "password": "strong-password-here"
    },
    "tailscale": {
      "mode": "funnel"     // 公网 HTTPS (需密码)
    }
  }
}

2. Telegram 安全

配置 DM 配对策略:

{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing",  // 默认配对模式
      "allowFrom": ["trusted-user"]  // 预批准用户
    }
  }
}

群组保护:

{
  "channels": {
    "telegram": {
      "groups": {
        "group-123": {
          "requireMention": true,  // 仅响应 @bot
          "activation": "mention",
          "allowedCommands": ["/status", "/new"]  // 限制命令
        }
      }
    }
  }
}

3. 沙盒隔离

启用 Docker 沙盒:

{
  "agent": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "image": "openclaw/sandbox:latest",
        "allowlist": ["bash", "read", "write"],
        "denylist": ["browser", "canvas", "nodes"]
      }
    }
  }
}

4. 敏感信息保护

使用环境变量:

# .env 文件 (不提交到 Git)
TELEGRAM_BOT_TOKEN=123456:ABCDEF
ANTHROPIC_API_KEY=sk-ant-...

启用 secret 检测:

{
  "security": {
    "detectSecrets": true,
    "secretPatterns": [
      "sk-.*",  // API keys
      "\\+\\d{10,15}",  // Phone numbers
      "password.*=.*"  // Passwords
    ]
  }
}

监控与运维

健康检查

Gateway 健康端点:

# 通过 WebSocket
ws://localhost:18789/health

# CLI 命令
openclaw health

# 预期响应
{
  "status": "healthy",
  "gateway": "running",
  "channels": {
    "telegram": "connected",
    "whatsapp": "connected"
  },
  "uptime": 86400
}

日志管理

配置日志轮转:

{
  "logging": {
    "level": "info",
    "files": {
      "gateway": {
        "path": "/var/log/openclaw/gateway.log",
        "maxSize": "100MB",
        "maxFiles": 5
      }
    }
  }
}

日志聚合 (可选):

• Loki + Grafana
• ELK Stack (Elasticsearch, Logstash, Kibana)
• Datadog Logs

性能监控

启用指标收集:

{
  "metrics": {
    "enabled": true,
    "export": "prometheus",
    "port": 9090
  }
}

关键指标:

• gateway_connections: 活跃 WebSocket 连接数
• agent_requests_total: Agent 请求数
• agent_duration_seconds: 请求处理时长
• channel_messages_total: 消息吞吐量
• tool_errors_total: 工具执行错误数

故障恢复

自动重启 (systemd):

# /etc/systemd/user/openclaw.service
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

启动服务:

systemctl --user daemon-reload
systemctl --user enable openclaw
systemctl --user start openclaw
systemctl --user status openclaw

故障排查指南

常见问题诊断

1. Gateway 无法启动

# 检查端口占用
lsof -i :18789

# 检查配置语法
openclaw doctor

# 查看详细日志
openclaw gateway --verbose --debug

2. Telegram Bot 无响应

# 验证 Bot Token
curl https://api.telegram.org/bot<TOKEN>/getMe

# 删除现有 Webhook
curl -X POST https://api.telegram.org/bot<TOKEN>/deleteWebhook

# 手动发送测试消息
curl -X POST https://api.telegram.org/bot<TOKEN>/sendMessage \
  -d "chat_id=<CHAT_ID>&text=Test"

3. Agent 拒绝执行工具

# 检查权限配置
cat ~/.openclaw/openclaw.json | grep sandbox

# 运行诊断
openclaw doctor --verbose

# 临时禁用沙盒 (仅测试)
openclaw agent --no-sandbox "test command"

4. 性能问题

# 检查资源使用
htop

# 查看当前会话数
openclaw sessions list

# 压缩会话减少 token 使用
openclaw sessions compact <session-id>

紧急恢复

重置 Gateway:

# 停止服务
systemctl --user stop openclaw

# 备份配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 重置状态 (保留配置)
rm -rf ~/.openclaw/state

# 重启服务
systemctl --user start openclaw

恢复出厂设置:

# 完全重置 (警告：删除所有数据)
openclaw reset --hard

# 重新初始化
openclaw onboard --install-daemon

结论

OpenClaw 的部署支持从个人本地使用到团队远程服务的多种场景。核心配置原则包括：

1. 安全优先: 启用认证、配置白名单、启用沙盒隔离
2. 可观测性: 配置日志、监控和健康检查
3. 高可用: 使用 systemd 自动重启、Docker 容器化部署
4. 灵活扩展: 通过 Tailscale、SSH 隧道实现安全的远程访问

生产环境部署建议遵循最小权限原则，逐步开放必要功能，定期运行 openclaw doctor 检查配置风险。