在 https://console.cloud.google.com/billing 启用账单（需要 Compute Engine）。

启用 Compute Engine API：
bash
gcloud services enable compute.googleapis.com```
**控制台：**

1. 进入 IAM & Admin > 创建项目
2. 命名并创建
3. 为项目启用账单
4. 导航到 APIs & Services > 启用 APIs > 搜索 "Compute Engine API" > 启用

---

## 3) 创建虚拟机

**机器类型：**

| 类型 | 规格 | 成本 | 备注 |
|------|-------|------|-------|
| e2-small | 2 个 vCPU，2GB 内存 | ~$12/月 | 推荐使用 |
| e2-micro | 2 个 vCPU（共享），1GB 内存 | 免费套餐可选 | 在高负载下可能会出现内存不足（OOM） |```bash
gcloud compute instances create clawdbot-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small \
  --boot-disk-size=20GB \
  --image-family=debian-12 \
  --image-project=debian-cloud

**控制台：**

点击 Compute Engine 仪表板中你的虚拟机 (VM) 旁边的 "SSH" 按钮。

注意：在创建虚拟机后，SSH 密钥可能需要 1-2 分钟才能传播。如果连接被拒绝，请等待后重试。
---

## 5) 在虚拟机上安装 Docker```bash
sudo apt-get update
sudo apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
```
注销并重新登录以使组更改生效：
bash
exit

验证：
bash
docker --version
docker compose version

本指南假设您将构建一个自定义镜像以确保二进制文件的持久性。

---

## 7）创建持久化的主机目录

Docker 容器是短暂的。
所有需要长期保存的状态都必须存储在主机上。
bash
mkdir -p ~/.clawdbot
mkdir -p ~/clawd

生成强密码：
openssl rand -hex 32```
**不要提交此文件。**

---

## 9) Docker Compose 配置

创建或更新 `docker-compose.yml`。```yaml
services:
  clawdbot-gateway:
    image: ${CLAWDBOT_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - CLAWDBOT_GATEWAY_BIND=${CLAWDBOT_GATEWAY_BIND}
      - CLAWDBOT_GATEWAY_PORT=${CLAWDBOT_GATEWAY_PORT}
      - CLAWDBOT_GATEWAY_TOKEN=${CLAWDBOT_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ${CLAWDBOT_CONFIG_DIR}:/home/node/.clawdbot
      - ${CLAWDBOT_WORKSPACE_DIR}:/home/node/clawd
    ports:
      # Recommended: keep the Gateway loopback-only on the VM; access via SSH tunnel.
      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
      - "127.0.0.1:${CLAWDBOT_GATEWAY_PORT}:18789"

      # Optional: only if you run iOS/Android nodes against this VM and need Canvas host.
      # If you expose this publicly, read /gateway/security and firewall accordingly.
      # - "18793:18793"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${CLAWDBOT_GATEWAY_BIND}",
        "--port",
        "${CLAWDBOT_GATEWAY_PORT}"
      ]

## 11）构建和启动```bash
docker compose build
docker compose up -d clawdbot-gateway
```
验证二进制文件：
bash
docker compose exec clawdbot-gateway which gog
docker compose exec clawdbot-gateway which goplaces
docker compose exec clawdbot-gateway which wacli

在浏览器中打开：

`http://127.0.0.1:18789/`

粘贴你的网关令牌。

---

## 哪些组件在哪里持久化（真相来源）

Clawdbot 在 Docker 中运行，但 Docker 不是真相来源。
所有需要长期保存的状态必须在重启、重建和重启后仍然存在。

| 组件 | 位置 | 持久化机制 | 说明 |
|---|---|---|---|
| 网关配置 | `/home/node/.clawdbot/` | 主机卷挂载 | 包括 `clawdbot.json` 和令牌 |
| 模型认证配置文件 | `/home/node/.clawdbot/` | 主机卷挂载 | OAuth 令牌、API 密钥 |
| 技能配置 | `/home/node/.clawdbot/skills/` | 主机卷挂载 | 技能级别的状态 |
| 代理工作区 | `/home/node/clawd/` | 主机卷挂载 | 代码和代理生成物 |
| WhatsApp 会话 | `/home/node/.clawdbot/` | 主机卷挂载 | 保留二维码登录状态 |
| Gmail 密钥环 | `/home/node/.clawdbot/` | 主机卷挂载 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
| 外部二进制文件 | `/usr/local/bin/` | Docker 镜像 | 必须在构建时打包进去 |
| Node 运行时 | 容器文件系统 | Docker 镜像 | 每次镜像构建时都会重新构建 |
| OS 包 | 容器文件系统 | Docker 镜像 | 不应在运行时安装 |
| Docker 容器 | 临时 | 可重启 | 可以安全地销毁 |
bash
cd ~/clawdbot
git pull
docker compose build
docker compose up -d

确保您的账户拥有所需的 IAM 权限（Compute OS Login 或 Compute OS Admin Login）。

**内存不足（OOM）**

如果使用 e2-micro 实例并遇到 OOM，请升级到 e2-small 或 e2-medium。
bash
# 首先停止虚拟机
gcloud compute instances stop clawdbot-gateway --zone=us-central1-a

# 更改机器类型
gcloud compute instances set-machine-type clawdbot-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small

# 启动虚拟机
gcloud compute instances start clawdbot-gateway --zone=us-central1-a