部署指南¶

本指南介绍如何在生产环境部署 OpenClaw-Py。

1. 系统要求¶

项目	最低要求	推荐
Python	3.10+	3.12+
内存	512 MB	2 GB+
存储	100 MB	1 GB+
操作系统	Linux, macOS, Windows	Linux

2. 安装方式¶

PyPI（推荐）¶

pip install openclaw-py

从源码¶

git clone https://github.com/anthropics/openclaw-py.git
cd openclaw-py
pip install -e ".[dev]"

Docker¶

FROM python:3.12-slim

WORKDIR /app

# 安装依赖
RUN pip install --no-cache-dir openclaw-py

# 创建配置目录
RUN mkdir -p /root/.pyclaw/state

# 暴露端口
EXPOSE 18777

# 启动 Gateway
CMD ["pyclaw", "gateway", "--port", "18777", "--bind", "0.0.0.0"]

构建和运行：

docker build -t openclaw-py .
docker run -d -p 18777:18777 -v ~/.pyclaw:/root/.pyclaw openclaw-py

3. 配置¶

配置文件位置¶

~/.pyclaw/pyclaw.json          # 主配置
~/.pyclaw/secrets.json         # 密钥（API Keys）
~/.pyclaw/state/               # 运行时状态

基础配置示例¶

{
  "meta": {
    "version": "0.1.7"
  },
  "auth": {
    "token": "your-secure-token-here"
  },
  "gateway": {
    "port": 18777,
    "bind": "0.0.0.0",
    "channelHealthCheckMinutes": 15
  },
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}",
        "baseUrl": "https://api.anthropic.com"
      },
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      }
    }
  },
  "agents": {
    "defaults": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6"
    }
  }
}

环境变量¶

变量	用途
`ANTHROPIC_API_KEY`	Anthropic API Key
`OPENAI_API_KEY`	OpenAI API Key
`PYCLAW_LOG_LEVEL`	日志级别 (DEBUG, INFO, WARNING)
`PYCLAW_CONFIG_PATH`	自定义配置路径

4. Systemd 服务（Linux）¶

创建服务文件 /etc/systemd/system/pyclaw.service：

[Unit]
Description=OpenClaw-Py Gateway
After=network.target

[Service]
Type=simple
User=pyclaw
Group=pyclaw
WorkingDirectory=/home/pyclaw
Environment="PYCLAW_LOG_LEVEL=INFO"
ExecStart=/usr/local/bin/pyclaw gateway --port 18777 --bind 0.0.0.0
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启用和启动：

sudo systemctl daemon-reload
sudo systemctl enable pyclaw
sudo systemctl start pyclaw
sudo systemctl status pyclaw

5. 反向代理（Nginx）¶

upstream pyclaw {
    server 127.0.0.1:18777;
}

server {
    listen 80;
    server_name pyclaw.example.com;

    # 重定向到 HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name pyclaw.example.com;

    ssl_certificate /etc/letsencrypt/live/pyclaw.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pyclaw.example.com/privkey.pem;

    # WebSocket 支持
    location / {
        proxy_pass http://pyclaw;
        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_read_timeout 86400;
    }

    # HTTP API
    location /health {
        proxy_pass http://pyclaw/health;
    }
}

6. 高可用部署¶

Docker Compose¶

version: '3.8'

services:
  pyclaw:
    image: openclaw-py:latest
    ports:
      - "18777:18777"
    volumes:
      - pyclaw-data:/root/.pyclaw
    environment:
      - PYCLAW_LOG_LEVEL=INFO
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18777/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - pyclaw
    restart: unless-stopped

volumes:
  pyclaw-data:

Kubernetes¶

apiVersion: apps/v1
kind: Deployment
metadata:
  name: pyclaw
spec:
  replicas: 2
  selector:
    matchLabels:
      app: pyclaw
  template:
    metadata:
      labels:
        app: pyclaw
    spec:
      containers:
      - name: pyclaw
        image: openclaw-py:latest
        ports:
        - containerPort: 18777
        env:
        - name: ANTHROPIC_API_KEY
          valueFrom:
            secretKeyRef:
              name: pyclaw-secrets
              key: anthropic-api-key
        livenessProbe:
          httpGet:
            path: /health
            port: 18777
          initialDelaySeconds: 10
          periodSeconds: 30
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1Gi"
            cpu: "500m"
---
apiVersion: v1
kind: Service
metadata:
  name: pyclaw
spec:
  selector:
    app: pyclaw
  ports:
  - port: 18777
    targetPort: 18777

7. 安全配置¶

认证 Token¶

生成安全 Token：

python -c "import secrets; print(secrets.token_urlsafe(32))"

配置：

{
  "auth": {
    "token": "your-generated-token"
  }
}

密钥管理¶

使用 secrets.json 存储敏感信息：

{
  "apiKeys": {
    "anthropic": "sk-ant-...",
    "openai": "sk-..."
  }
}

网络安全¶

# 仅允许本地访问
pyclaw gateway --bind 127.0.0.1

# 防火墙规则
sudo ufw allow 18777/tcp

8. 监控¶

健康检查¶

# HTTP 健康检查
curl http://localhost:18777/health

# WebSocket 探测
pyclaw gateway probe

日志¶

# 实时日志
pyclaw logs tail

# 查看系统日志
journalctl -u pyclaw -f

指标¶

# 使用统计
pyclaw gateway call usage.get --params '{"days": 7}'

9. 备份¶

配置备份¶

# 导出备份
pyclaw gateway call backup.export

# 手动备份
tar -czf pyclaw-backup.tar.gz ~/.pyclaw

会话备份¶

# 会话目录
~/.pyclaw/state/sessions/

10. 故障排除¶

常见问题¶

问题	解决方法
无法连接	检查端口和防火墙
认证失败	检查 token 配置
模型不可用	检查 API Key 配置
内存不足	增加 `--max-workers` 或优化模型

诊断命令¶

# 运行诊断
pyclaw doctor

# 检查 Gateway 状态
pyclaw gateway status --deep

# 查看日志
pyclaw logs tail --lines 100

11. 更新¶

# 更新到最新版本
pip install --upgrade openclaw-py

# 检查更新
pyclaw gateway call update.check

12. TypeScript 客户端部署¶

PyClaw 提供基于 TypeScript 的跨平台客户端，使用 Next.js (Web)、Tauri (Desktop) 和 Expo (Mobile) 构建。

支持的平台¶

平台	技术栈	输出格式
Web	Next.js	静态站点 / SSR
Desktop	Tauri	`.msi` / `.dmg` / `.AppImage`
Mobile	Expo	`.apk` / `.ipa`

前置条件¶

# 安装 pnpm（推荐）
npm install -g pnpm

# 安装依赖
pnpm install

Web 构建¶

# 构建 Web 客户端
pnpm --filter @pyclaw/web build

# 输出目录: apps/web/.next/
# 静态导出（可选）
pnpm --filter @pyclaw/web next export

Desktop 构建¶

# 构建 Desktop 客户端
pnpm --filter @pyclaw/desktop tauri build

# 开发模式
pnpm --filter @pyclaw/desktop tauri dev

# 输出目录: apps/desktop/src-tauri/target/release/bundle/

平台特定说明¶

Windows: 输出 .msi 安装包
macOS: 输出 .dmg 和 .app
Linux: 输出 .AppImage 和 .deb

Mobile 构建¶

# 构建 Mobile 客户端
pnpm --filter @pyclaw/mobile build

# Android APK
pnpm --filter @pyclaw/mobile expo build:android

# iOS IPA（需要 macOS）
pnpm --filter @pyclaw/mobile expo build:ios

# 开发模式
pnpm --filter @pyclaw/mobile expo start

GitHub Actions 自动构建¶

项目配置了 .github/workflows/build.yml，可在发布标签时自动构建所有平台包：

# 创建标签触发构建
git tag v0.2.0
git push origin v0.2.0

构建产物会自动上传到 GitHub Releases。