自部署指南

在你自己的机器上部署 ClawButler

在你的服务器或本地机器上运行 ClawButler，治理你的 OpenClaw Agent。数据完全私有。原生支持 Windows、macOS 和 Linux —— Windows 无需 WSL。

一键安装（推荐）#

只需一行命令，自动完成环境检测、依赖安装、密钥生成和服务启动。支持 Linux 和 macOS。

bash
curl -fsSL https://raw.githubusercontent.com/Octo-o-o-o/clawbutler/main/scripts/install.sh | bash

零配置本地试用

不想回答配置问题？QUICK 模式跳过所有交互，使用安全默认值直接启动：

bash
curl -fsSL https://raw.githubusercontent.com/Octo-o-o-o/clawbutler/main/scripts/install.sh | QUICK=1 bash

Windows 用户请先安装 WSL2（推荐 Ubuntu），然后在 WSL2 终端中运行上述命令。

安装脚本自动完成：系统环境检测 → Docker 安装检查 → 克隆仓库 → 自动发现本地 OpenClaw → 生成安全密钥 → 端口冲突检测 → 构建并启动服务 → 运行数据库迁移 → 健康检查 → 安装管理 CLI

管理工具 (clawbutlerctl)#

安装脚本会自动将 clawbutlerctl 命令安装到 /usr/local/bin。日常管理常用命令：

CommandDescription
clawbutlerctl startStart all services
clawbutlerctl stopStop all services
clawbutlerctl restartRestart all services
clawbutlerctl statusCheck service health & status
clawbutlerctl logs [service]View logs (all or specific service)
clawbutlerctl updatePull latest version & rebuild
clawbutlerctl configShow current configuration
clawbutlerctl rollback <sha>Rollback to a specific commit

手动安装（开发者）#

如果你需要更细粒度的控制，或想以开发模式运行，可以按以下步骤手动安装。

前置条件#

你需要四个工具：Docker（运行数据库）、Node.js 22+（Web 前端）、pnpm（包管理器）和 uv（Python 环境管理器）。以下是各平台的安装方式。

Docker
Node.js 22+
pnpm
uv

Windows

从官网下载安装 Docker Desktop 和 Node.js，再通过 PowerShell 安装 pnpm 和 uv。

powershell
# 1. Docker Desktop → docker.com/products/docker-desktop/ (download & install)
# 2. Node.js 22 LTS → nodejs.org (download & install)
# 3. pnpm
npm install -g pnpm
# 4. uv (Python package manager — auto-installs Python 3.12)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Restart PowerShell after install, or refresh PATH:
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"

macOS

先安装 Homebrew，再用它安装 Node.js。容器用 Docker Desktop 或 OrbStack。uv 通过 curl 安装。

bash
# 1. Docker Desktop → docker.com/products/docker-desktop/ (Apple Silicon / Intel)
#    Alternative: OrbStack (orbstack.dev) — lighter resource usage
# 2. Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 3. Node.js 22+
brew install node@22
# 4. pnpm
npm install -g pnpm
# 5. uv (Python package manager — auto-installs Python 3.12)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env   # refresh PATH

Linux

通过官方脚本安装 Docker Engine。Node.js 用 NodeSource（Ubuntu/Debian）或发行版包管理器。uv 通过 curl 安装。

bash
# 1. Docker Engine
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER && newgrp docker
# 2. Node.js 22+ (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
# Fedora: sudo dnf install -y nodejs
# Arch:   sudo pacman -S nodejs npm
# 3. pnpm
npm install -g pnpm
# 4. uv (Python package manager — auto-installs Python 3.12)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env   # refresh PATH

验证环境#

运行以下命令确认所有工具就绪：

bash
docker --version          # Docker 20+
docker info 2>&1 | grep "Server Version"   # confirms daemon is running
node --version            # v22.x.x+
pnpm --version            # 10.x.x+
uv --version              # 0.6.x+

如果 uv 找不到：Windows — 重启 PowerShell 或刷新 $env:Path；macOS/Linux — 执行 source $HOME/.local/bin/env 或重启终端。

安装步骤#

1

克隆仓库

bash
git clone https://github.com/Octo-o-o-o/clawbutler.git
cd clawbutler
2

启动数据库

通过 Docker 启动 PostgreSQL 17 和 Valkey 8（Redis 兼容缓存）。首次运行需下载约 100-150 MB 镜像。

bash
docker compose -f deploy/docker-compose.dev.yml up -d

验证两个容器均在运行：

bash
docker compose -f deploy/docker-compose.dev.yml ps
# Both deploy-db-1 (port 5432) and deploy-valkey-1 (port 6379) should be "Up"
3

部署 API 后端

复制环境配置文件

.env.example 已包含本地开发所需的全部默认配置，无需修改。

macOS / Linux

bash
cp .env.example apps/api/.env

Windows (PowerShell)

powershell
Copy-Item ".env.example" "apps\api\.env"

安装 Python 3.12 和依赖

bash
cd apps/api
uv python install 3.12
uv sync --all-extras

初始化数据库

bash
uv run alembic upgrade head

启动 API 服务

bash
cd ../..   # back to project root
cd apps    # MUST be in apps/ directory
uv run --project api uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

常见陷阱 — 相对导入报错

API 使用了 Python 相对导入（from .config import ...），你必须从 apps/ 目录运行 uvicorn，使用模块路径 api.main:app。在 apps/api/ 目录下直接运行 uvicorn main:app 会报错：ImportError: attempted relative import with no known parent package。

如果端口 8000 被占用，使用 --port 8001 并同步修改 Web 前端的 .env.local。保持此终端窗口打开，新开一个终端进行步骤 4。

检查端口 8000 是否被占用

macOS / Linux

bash
lsof -i :8000

Windows (PowerShell)

powershell
Get-NetTCPConnection -LocalPort 8000 -ErrorAction SilentlyContinue
4

部署 Web 前端

打开一个新的终端标签页或窗口操作 Web 前端。

安装前端依赖

bash
cd apps/web    # from project root
pnpm install

创建前端环境配置

如果 API 运行在其他端口（如 8001），请将 8000 替换为实际端口号。

macOS / Linux

bash
cat > .env.local << 'EOF'
AUTH_SECRET=local-dev-secret-change-in-prod
AUTH_TRUST_HOST=true
AUTH_URL=http://localhost:3000
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
API_BASE_URL_INTERNAL=http://localhost:8000
EOF

Windows (PowerShell)

powershell
@"
AUTH_SECRET=local-dev-secret-change-in-prod
AUTH_TRUST_HOST=true
AUTH_URL=http://localhost:3000
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
API_BASE_URL_INTERNAL=http://localhost:8000
"@ | Out-File -Encoding utf8 .env.local

启动 Web 服务

bash
pnpm dev
5

验证部署

服务地址
Web Dashboardhttp://localhost:3000
API Docs (Swagger)http://localhost:8000/docs
Health Checkhttp://localhost:8000/health

macOS / Linux

bash
curl http://localhost:8000/health
# Expected: JSON with status="ok" and a non-empty version field

Windows (PowerShell)

powershell
Invoke-RestMethod -Uri "http://localhost:8000/health"
# Expected: status: ok, plus a non-empty version field

日常使用#

每次开机后，在 3 个独立终端中启动服务：

bash
# Terminal 1: Start databases (if not running)
docker compose -f deploy/docker-compose.dev.yml up -d

# Terminal 2: Start API (from project-root/apps/)
cd apps
uv run --project api uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

# Terminal 3: Start Web (from project-root/apps/web/)
cd apps/web
pnpm dev

停止：在 API 和 Web 终端按 Ctrl+C。停止数据库：docker compose -f deploy/docker-compose.dev.yml down（数据保存在 Docker Volume 中不会丢失）。

生产环境配置#

生产部署时，需要生成安全密钥并配置以下环境变量到 .env 文件中：

变量生成方式
DB_PASSWORDopenssl rand -base64 24
JWT_SECRET_KEYopenssl rand -hex 32
AUTH_SECRETopenssl rand -base64 32
ENCRYPTION_KEYopenssl rand -hex 32
SMTP_HOST邮件服务商提供
SMTP_PASSWORD邮件服务商提供
CORS_ORIGINS手动填写
AUTH_URL手动填写

生产环境必须配置 SMTP_HOST，否则 API 启动校验不通过。推荐 Resend（免费 100 封/天）。

生产环境 HTTPS (Caddy)#

推荐使用 Caddy 自动申请 Let's Encrypt 证书。Linux 用 apt/yum 安装，macOS 用 brew install caddy。

bash
# Install Caddy
# Linux (Debian/Ubuntu): sudo apt install caddy
# Linux (RHEL/Fedora):   sudo dnf install caddy
# macOS:                 brew install caddy
# Windows:               choco install caddy (or scoop install caddy)

# Edit Caddyfile
# Linux:  sudo nano /etc/caddy/Caddyfile
# macOS:  nano /opt/homebrew/etc/Caddyfile
caddyfile
your-domain.com {
    handle /api/auth/* { reverse_proxy localhost:3000 }
    handle /api/*      { reverse_proxy localhost:8000 }
    handle /health     { reverse_proxy localhost:8000 }
    handle /docs       { reverse_proxy localhost:8000 }
    handle             { reverse_proxy localhost:3000 }
}
bash
# Production: bind ports to 127.0.0.1
docker compose -f docker-compose.yml \
  -f deploy/docker-compose.production.yml up -d --build

sudo systemctl enable caddy && sudo systemctl start caddy

系统要求#

最低配置

  • 2 vCPU / 4 GB RAM / 20 GB SSD
  • Docker Engine 24+ / Docker Desktop
  • Linux / macOS / Windows
  • amd64 / arm64

推荐配置

  • 4 vCPU / 8 GB RAM / 40 GB SSD
  • 固定公网 IP + 域名
  • SMTP 邮件服务
云平台参考：GCP e2-medium ~$25/月 | AWS t3.medium ~$30/月 | 阿里云 ecs.c7.large ~¥150/月 | Hetzner CX22 ~€6/月

运维操作#

升级

bash
# Recommended: use management CLI
clawbutlerctl update

# Or manually:
cd ~/clawbutler && git pull
docker compose build && docker compose up -d

备份

bash
docker compose exec -T postgres \
  pg_dump -U postgres agentplanet \
  | gzip > backup_$(date +%Y%m%d).sql.gz

云端连接#

将本地自部署的 OpenClaw 连接到 ClawButler Cloud（clawbutler.cc），实现远程管理、对话和监控 —— 无需向公网暴露任何本地端口。

架构：Edge Agent 隧道

Cloud (clawbutler.cc)              Your Machine
┌──────────────────┐               ┌──────────────────┐
│  ClawButler API  │   WSS (443)   │  Edge Agent      │
│  ◄════════════════════════════►  │    ↕              │
│  Dashboard / Chat│   outbound    │  OpenClaw Gateway │
└──────────────────┘   tunnel      │  (127.0.0.1:18789) │
                                   └──────────────────┘
1

安装 Edge Agent

安装脚本会自动检测本地 OpenClaw 网关，并下载 Edge Agent。

bash
curl -fsSL https://clawbutler.cc/install | bash -s -- --edge-only

macOS / Linux 桌面

在本机终端中执行上面的命令。 脚本会自动打开浏览器完成配对。

Windows (WSL2)

打开 WSL2 终端 (Ubuntu)，执行上面的命令。 配对链接会自动在 Windows 浏览器中打开。

前提条件：在 PowerShell (管理员) 中运行 wsl --install

Linux 服务器 (SSH)

通过 SSH 连接到服务器后，执行上面的命令。 脚本会显示一个配对链接，在本地浏览器中打开即可。

2

与云端配对

运行配对命令。Edge Agent 会显示一个短时效的配对码。

bash
cd ~/.clawbutler/edge-agent
python3 clawbutler_edge.py pair \
  --cloud-url https://clawbutler.cc \
  --openclaw-url ws://127.0.0.1:18789

如果 OpenClaw 配置了网关认证，--openclaw-token 参数会自动检测。你也可以手动指定。

3

在浏览器中审批

在浏览器中打开 Edge Agent 显示的 URL（需要登录 clawbutler.cc）。输入连接器名称并点击「审批」。Edge Agent 会自动收到凭证。

4

启动 Edge Agent

启动 Edge Agent。它会建立一条到云端的出站 WSS 隧道。你的本地 Agent 现在可以从 clawbutler.cc 访问了。

bash
python3 clawbutler_edge.py

Edge Agent 在连接断开时会自动重连。建议将其配置为后台服务运行（systemd、launchd 或 nohup）。

连接安全#

Edge Agent 采用零入站端口架构设计。你的 OpenClaw 网关无需从互联网可达。

直接暴露端口（不安全）

将 18789 端口开放到公网会使 OpenClaw 网关暴露在端口扫描、暴力攻击和未授权访问的风险下。像 18789 这样的默认端口会在暴露后数分钟内被自动化工具扫描到。

Edge Agent 隧道（推荐）

Edge Agent 仅通过 WSS（443 端口）建立出站连接。OpenClaw 保持绑定在 127.0.0.1。无需配置防火墙规则或端口转发。隧道全程使用 TLS 加密。

安全层级

1
仅出站连接

Edge Agent 主动向云端发起 WSS 连接。你的机器上不会打开任何入站端口。OpenClaw 仅在 localhost（127.0.0.1）上监听，对外部网络完全不可见。

2
TLS 加密隧道

Edge Agent 与 ClawButler Cloud 之间的所有流量都通过 WSS（WebSocket Secure）传输，使用与 HTTPS 相同的 TLS 加密。帧数据在传输过程中无法被截获或篡改。

3
令牌认证

Edge Agent 使用配对时颁发的 48 字节加密随机令牌向云端认证。云端在每次 WebSocket 连接时都会验证该令牌。

4
Ed25519 设备认证

Edge Agent 使用 Ed25519 挑战-响应签名向本地 OpenClaw 网关认证，与 SSH 使用的加密协议相同。不存储或传输任何密码。

数据留在本地

你的 Agent 配置、对话历史和 OpenClaw 数据始终保留在你的机器上。云端仅在活跃使用期间看到通过隧道传输的 API 请求和响应。Edge Agent 不会同步或上传你的数据。

默认端口#

服务端口说明
PostgreSQL5432主数据库
Valkey6379缓存 / 会话存储
FastAPI Backend8000REST API + SSE
Next.js Frontend3000Web 控制面板

常见问题#

准备好了？

查看源码或直接使用云服务。

GitHub使用云服务
自部署指南 — ClawButler