@quantumclaw/quantumclaw 2026.3.22

package/docs/zh-CN/install/hetzner.md

@@ -0,0 +1,337 @@
+---
+read_when:
+  - 你想让 QuantumClaw 在云 VPS 上 24/7 运行（而不是你的笔记本电脑）
+  - 你想在自己的 VPS 上运行生产级、永久在线的 Gateway 网关
+  - 你想完全控制持久化、二进制文件和重启行为
+  - 你在 Hetzner 或类似提供商上用 Docker 运行 QuantumClaw
+summary: 在廉价的 Hetzner VPS（Docker）上 24/7 运行 QuantumClaw Gateway 网关，带持久状态和内置二进制文件
+title: Hetzner
+x-i18n:
+  generated_at: "2026-02-03T07:52:17Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 84d9f24f1a803aa15faa52a05f25fe557ec3e2c2f48a00c701d49764bd3bc21a
+  source_path: platforms/hetzner.md
+  workflow: 15
+---
+
+# 在 Hetzner 上运行 QuantumClaw（Docker，生产 VPS 指南）
+
+## 目标
+
+使用 Docker 在 Hetzner VPS 上运行持久的 QuantumClaw Gateway 网关，带持久状态、内置二进制文件和安全的重启行为。
+
+如果你想要"约 $5 实现 QuantumClaw 24/7"，这是最简单可靠的设置。
+Hetzner 定价会变化；选择最小的 Debian/Ubuntu VPS，如果遇到 OOM 再扩容。
+
+## 我们在做什么（简单说明）？
+
+- 租用一台小型 Linux 服务器（Hetzner VPS）
+- 安装 Docker（隔离的应用运行时）
+- 在 Docker 中启动 QuantumClaw Gateway 网关
+- 在主机上持久化 `~/.quantumclaw` + `~/.quantumclaw/workspace`（重启/重建后保留）
+- 通过 SSH 隧道从你的笔记本电脑访问控制 UI
+
+Gateway 网关可以通过以下方式访问：
+
+- 从你的笔记本电脑进行 SSH 端口转发
+- 如果你自己管理防火墙和令牌，可以直接暴露端口
+
+本指南假设在 Hetzner 上使用 Ubuntu 或 Debian。
+如果你使用其他 Linux VPS，请相应地映射软件包。
+通用 Docker 流程请参见 [Docker](/install/docker)。
+
+---
+
+## 快速路径（有经验的运维人员）
+
+1. 配置 Hetzner VPS
+2. 安装 Docker
+3. 克隆 QuantumClaw 仓库
+4. 创建持久化主机目录
+5. 配置 `.env` 和 `docker-compose.yml`
+6. 将所需二进制文件烘焙到镜像中
+7. `docker compose up -d`
+8. 验证持久化和 Gateway 网关访问
+
+---
+
+## 你需要什么
+
+- 具有 root 访问权限的 Hetzner VPS
+- 从你的笔记本电脑进行 SSH 访问
+- 基本熟悉 SSH + 复制/粘贴
+- 约 20 分钟
+- Docker 和 Docker Compose
+- 模型认证凭证
+- 可选的提供商凭证
+  - WhatsApp 二维码
+  - Telegram 机器人令牌
+  - Gmail OAuth
+
+---
+
+## 1) 配置 VPS
+
+在 Hetzner 中创建一个 Ubuntu 或 Debian VPS。
+
+以 root 身份连接：
+
+```bash
+ssh root@YOUR_VPS_IP
+```
+
+本指南假设 VPS 是有状态的。
+不要将其视为一次性基础设施。
+
+---
+
+## 2) 安装 Docker（在 VPS 上）
+
+```bash
+apt-get update
+apt-get install -y git curl ca-certificates
+curl -fsSL https://get.docker.com | sh
+```
+
+验证：
+
+```bash
+docker --version
+docker compose version
+```
+
+---
+
+## 3) 克隆 QuantumClaw 仓库
+
+```bash
+git clone https://github.com/quantumclaw/quantumclaw.git
+cd quantumclaw
+```
+
+本指南假设你将构建自定义镜像以保证二进制文件持久化。
+
+---
+
+## 4) 创建持久化主机目录
+
+Docker 容器是临时的。
+所有长期状态必须存储在主机上。
+
+```bash
+mkdir -p /root/.quantumclaw
+mkdir -p /root/.quantumclaw/workspace
+
+# 将所有权设置为容器用户（uid 1000）：
+chown -R 1000:1000 /root/.quantumclaw
+chown -R 1000:1000 /root/.quantumclaw/workspace
+```
+
+---
+
+## 5) 配置环境变量
+
+在仓库根目录创建 `.env`。
+
+```bash
+QUANTUMCLAW_IMAGE=quantumclaw:latest
+QUANTUMCLAW_GATEWAY_TOKEN=change-me-now
+QUANTUMCLAW_GATEWAY_BIND=lan
+QUANTUMCLAW_GATEWAY_PORT=18789
+
+QUANTUMCLAW_CONFIG_DIR=/root/.quantumclaw
+QUANTUMCLAW_WORKSPACE_DIR=/root/.quantumclaw/workspace
+
+GOG_KEYRING_PASSWORD=change-me-now
+XDG_CONFIG_HOME=/home/node/.quantumclaw
+```
+
+生成强密钥：
+
+```bash
+openssl rand -hex 32
+```
+
+**不要提交此文件。**
+
+---
+
+## 6) Docker Compose 配置
+
+创建或更新 `docker-compose.yml`。
+
+```yaml
+services:
+  quantumclaw-gateway:
+    image: ${QUANTUMCLAW_IMAGE}
+    build: .
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      - HOME=/home/node
+      - NODE_ENV=production
+      - TERM=xterm-256color
+      - QUANTUMCLAW_GATEWAY_BIND=${QUANTUMCLAW_GATEWAY_BIND}
+      - QUANTUMCLAW_GATEWAY_PORT=${QUANTUMCLAW_GATEWAY_PORT}
+      - QUANTUMCLAW_GATEWAY_TOKEN=${QUANTUMCLAW_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:
+      - ${QUANTUMCLAW_CONFIG_DIR}:/home/node/.quantumclaw
+      - ${QUANTUMCLAW_WORKSPACE_DIR}:/home/node/.quantumclaw/workspace
+    ports:
+      # 推荐：在 VPS 上保持 Gateway 网关仅限 loopback；通过 SSH 隧道访问。
+      # 要公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
+      - "127.0.0.1:${QUANTUMCLAW_GATEWAY_PORT}:18789"
+
+      # 可选：仅当你对此 VPS 运行 iOS/Android 节点并需要 Canvas 主机时。
+      # 如果你公开暴露此端口，请阅读 /gateway/security 并相应配置防火墙。
+      # - "18793:18793"
+    command:
+      [
+        "node",
+        "dist/index.js",
+        "gateway",
+        "--bind",
+        "${QUANTUMCLAW_GATEWAY_BIND}",
+        "--port",
+        "${QUANTUMCLAW_GATEWAY_PORT}",
+      ]
+```
+
+---
+
+## 7) 将所需二进制文件烘焙到镜像中（关键）
+
+在运行中的容器内安装二进制文件是一个陷阱。
+任何在运行时安装的东西都会在重启时丢失。
+
+所有 skills 所需的外部二进制文件必须在镜像构建时安装。
+
+以下示例仅展示三个常见二进制文件：
+
+- `gog` 用于 Gmail 访问
+- `goplaces` 用于 Google Places
+- `wacli` 用于 WhatsApp
+
+这些是示例，不是完整列表。
+你可以使用相同的模式安装任意数量的二进制文件。
+
+如果你以后添加依赖额外二进制文件的新 skills，你必须：
+
+1. 更新 Dockerfile
+2. 重新构建镜像
+3. 重启容器
+
+**示例 Dockerfile**
+
+```dockerfile
+FROM node:22-bookworm
+
+RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
+
+# 示例二进制文件 1：Gmail CLI
+RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog
+
+# 示例二进制文件 2：Google Places CLI
+RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces
+
+# 示例二进制文件 3：WhatsApp CLI
+RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli
+
+# 使用相同模式在下方添加更多二进制文件
+
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+COPY ui/package.json ./ui/package.json
+COPY scripts ./scripts
+
+RUN corepack enable
+RUN pnpm install --frozen-lockfile
+
+COPY . .
+RUN pnpm build
+RUN pnpm ui:install
+RUN pnpm ui:build
+
+ENV NODE_ENV=production
+
+CMD ["node","dist/index.js"]
+```
+
+---
+
+## 8) 构建并启动
+
+```bash
+docker compose build
+docker compose up -d quantumclaw-gateway
+```
+
+验证二进制文件：
+
+```bash
+docker compose exec quantumclaw-gateway which gog
+docker compose exec quantumclaw-gateway which goplaces
+docker compose exec quantumclaw-gateway which wacli
+```
+
+预期输出：
+
+```
+/usr/local/bin/gog
+/usr/local/bin/goplaces
+/usr/local/bin/wacli
+```
+
+---
+
+## 9) 验证 Gateway 网关
+
+```bash
+docker compose logs -f quantumclaw-gateway
+```
+
+成功：
+
+```
+[gateway] listening on ws://0.0.0.0:18789
+```
+
+从你的笔记本电脑：
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
+```
+
+打开：
+
+`http://127.0.0.1:18789/`
+
+粘贴你的 Gateway 网关令牌。
+
+---
+
+## 持久化位置（事实来源）
+
+QuantumClaw 在 Docker 中运行，但 Docker 不是事实来源。
+所有长期状态必须在重启、重建和重启后保留。
+
+| 组件             | 位置                              | 持久化机制    | 说明                        |
+| ---------------- | --------------------------------- | ------------- | --------------------------- |
+| Gateway 网关配置 | `/home/node/.quantumclaw/`           | 主机卷挂载    | 包括 `quantumclaw.json`、令牌  |
+| 模型认证配置文件 | `/home/node/.quantumclaw/`           | 主机卷挂载    | OAuth 令牌、API 密钥        |
+| Skill 配置       | `/home/node/.quantumclaw/skills/`    | 主机卷挂载    | Skill 级别状态              |
+| 智能体工作区     | `/home/node/.quantumclaw/workspace/` | 主机卷挂载    | 代码和智能体产物            |
+| WhatsApp 会话    | `/home/node/.quantumclaw/`           | 主机卷挂载    | 保留二维码登录              |
+| Gmail 密钥环     | `/home/node/.quantumclaw/`           | 主机卷 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
+| 外部二进制文件   | `/usr/local/bin/`                 | Docker 镜像   | 必须在构建时烘焙            |
+| Node 运行时      | 容器文件系统                      | Docker 镜像   | 每次镜像构建时重建          |
+| 操作系统包       | 容器文件系统                      | Docker 镜像   | 不要在运行时安装            |
+| Docker 容器      | 临时的                            | 可重启        | 可以安全销毁                |

package/docs/zh-CN/install/index.md

@@ -0,0 +1,235 @@
+---
+read_when:
+  - 你需要一种不同于“入门指南”快速开始的安装方式
+  - 你想部署到云平台
+  - 你需要更新、迁移或卸载
+summary: 安装 QuantumClaw —— 安装脚本、npm/pnpm、从源码、Docker 等
+title: 安装
+x-i18n:
+  generated_at: "2026-03-16T06:23:36Z"
+  model: gpt-5.4
+  provider: openai
+  source_hash: 14b80b6176b2a4ff5c60aad2db88460d8d980bd416faaa3103b38d90521496af
+  source_path: install/index.md
+  workflow: 15
+---
+
+# 安装
+
+已经按照 [入门指南](/start/getting-started) 操作过了吗？那你已经准备好了 —— 本页适用于其他安装方法、特定平台说明以及维护操作。
+
+## 系统要求
+
+- **[Node 24（推荐）](/install/node)**（出于兼容性考虑，仍支持 Node 22 LTS，目前为 `22.16+`；如果缺失，[安装脚本](#install-methods) 会安装 Node 24）
+- macOS、Linux 或 Windows
+- 仅当你从源码构建时需要 `pnpm`
+
+<Note>
+在 Windows 上，我们强烈建议你在 [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) 下运行 QuantumClaw。
+</Note>
+
+## 安装方法
+
+<Tip>
+**安装脚本** 是安装 QuantumClaw 的推荐方式。它会一步完成 Node 检测、安装和新手引导。
+</Tip>
+
+<Warning>
+对于 VPS/云主机，尽量避免使用第三方“一键式”市场镜像。优先选择干净的基础 OS 镜像（例如 Ubuntu LTS），然后使用安装脚本自行安装 QuantumClaw。
+</Warning>
+
+<AccordionGroup>
+  <Accordion title="安装脚本" icon="rocket" defaultOpen>
+    下载 CLI，通过 npm 全局安装，并启动设置向导。
+
+    <Tabs>
+      <Tab title="macOS / Linux / WSL2">
+        ```bash
+        curl -fsSL https://quantumclaw.ai/install.sh | bash
+        ```
+      </Tab>
+      <Tab title="Windows (PowerShell)">
+        ```powershell
+        iwr -useb https://quantumclaw.ai/install.ps1 | iex
+        ```
+      </Tab>
+    </Tabs>
+
+    就这样 —— 脚本会处理 Node 检测、安装和新手引导。
+
+    如果要跳过新手引导，只安装二进制文件：
+
+    <Tabs>
+      <Tab title="macOS / Linux / WSL2">
+        ```bash
+        curl -fsSL https://quantumclaw.ai/install.sh | bash -s -- --no-onboard
+        ```
+      </Tab>
+      <Tab title="Windows (PowerShell)">
+        ```powershell
+        & ([scriptblock]::Create((iwr -useb https://quantumclaw.ai/install.ps1))) -NoOnboard
+        ```
+      </Tab>
+    </Tabs>
+
+    所有标志、环境变量以及 CI/自动化选项，请参阅 [Installer internals](/install/installer)。
+
+  </Accordion>
+
+  <Accordion title="npm / pnpm" icon="package">
+    如果你已经自行管理 Node，我们推荐使用 Node 24。出于兼容性考虑，QuantumClaw 仍支持 Node 22 LTS，目前为 `22.16+`：
+
+    <Tabs>
+      <Tab title="npm">
+        ```bash
+        npm install -g quantumclaw@latest
+        quantumclaw onboard --install-daemon
+        ```
+
+        <Accordion title="sharp 构建错误？">
+          如果你全局安装了 libvips（在 macOS 上通过 Homebrew 很常见），并且 `sharp` 失败，请强制使用预构建二进制文件：
+
+          ```bash
+          SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g quantumclaw@latest
+          ```
+
+          如果你看到 `sharp: Please add node-gyp to your dependencies`，请安装构建工具链（macOS：Xcode CLT + `npm install -g node-gyp`），或者使用上面的环境变量。
+        </Accordion>
+      </Tab>
+      <Tab title="pnpm">
+        ```bash
+        pnpm add -g quantumclaw@latest
+        pnpm approve-builds -g        # 批准 quantumclaw、node-llama-cpp、sharp 等
+        quantumclaw onboard --install-daemon
+        ```
+
+        <Note>
+        `pnpm` 要求对带有构建脚本的包进行显式批准。首次安装出现 “Ignored build scripts” 警告后，运行 `pnpm approve-builds -g` 并选择列出的包。
+        </Note>
+      </Tab>
+    </Tabs>
+
+    想通过包管理器安装当前 GitHub `main` 分支最新版本？
+
+    ```bash
+    npm install -g github:quantumclaw/quantumclaw#main
+    ```
+
+    ```bash
+    pnpm add -g github:quantumclaw/quantumclaw#main
+    ```
+
+  </Accordion>
+
+  <Accordion title="从源码" icon="github">
+    适用于贡献者或任何想从本地检出运行的人。
+
+    <Steps>
+      <Step title="克隆并构建">
+        克隆 [QuantumClaw 仓库](https://github.com/quantumclaw/quantumclaw) 并构建：
+
+        ```bash
+        git clone https://github.com/quantumclaw/quantumclaw.git
+        cd quantumclaw
+        pnpm install
+        pnpm ui:build
+        pnpm build
+        ```
+      </Step>
+      <Step title="链接 CLI">
+        让 `quantumclaw` 命令在全局可用：
+
+        ```bash
+        pnpm link --global
+        ```
+
+        或者，你也可以跳过链接，直接在仓库内通过 `pnpm quantumclaw ...` 运行命令。
+      </Step>
+      <Step title="运行新手引导">
+        ```bash
+        quantumclaw onboard --install-daemon
+        ```
+      </Step>
+    </Steps>
+
+    更深入的开发工作流请参阅 [Setup](/start/setup)。
+
+  </Accordion>
+</AccordionGroup>
+
+## 其他安装方法
+
+<CardGroup cols={2}>
+  <Card title="Docker" href="/install/docker" icon="container">
+    容器化或无头部署。
+  </Card>
+  <Card title="Podman" href="/install/podman" icon="container">
+    无 root 容器：先运行一次 `setup-podman.sh`，然后运行启动脚本。
+  </Card>
+  <Card title="Nix" href="/install/nix" icon="snowflake">
+    通过 Nix 进行声明式安装。
+  </Card>
+  <Card title="Ansible" href="/install/ansible" icon="server">
+    自动化批量配置。
+  </Card>
+  <Card title="Bun" href="/install/bun" icon="zap">
+    通过 Bun 运行时进行仅 CLI 使用。
+  </Card>
+</CardGroup>
+
+## 安装后
+
+验证一切是否正常工作：
+
+```bash
+quantumclaw doctor         # 检查配置问题
+quantumclaw status         # Gateway 网关状态
+quantumclaw dashboard      # 打开浏览器 UI
+```
+
+如果你需要自定义运行时路径，请使用：
+
+- `QUANTUMCLAW_HOME` 用于基于主目录的内部路径
+- `QUANTUMCLAW_STATE_DIR` 用于可变状态位置
+- `QUANTUMCLAW_CONFIG_PATH` 用于配置文件位置
+
+有关优先级和完整细节，请参阅 [Environment vars](/help/environment)。
+
+## 故障排除：找不到 `quantumclaw`
+
+<Accordion title="PATH 诊断与修复">
+  快速诊断：
+
+```bash
+node -v
+npm -v
+npm prefix -g
+echo "$PATH"
+```
+
+如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不在**你的 `$PATH` 中，那么你的 shell 就找不到全局 npm 二进制文件（包括 `quantumclaw`）。
+
+修复方法 —— 将其添加到你的 shell 启动文件（`~/.zshrc` 或 `~/.bashrc`）中：
+
+```bash
+export PATH="$(npm prefix -g)/bin:$PATH"
+```
+
+在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH 中。
+
+然后打开一个新的终端（或者在 zsh 中运行 `rehash`，在 bash 中运行 `hash -r`）。
+</Accordion>
+
+## 更新 / 卸载
+
+<CardGroup cols={3}>
+  <Card title="更新" href="/install/updating" icon="refresh-cw">
+    让 QuantumClaw 保持最新。
+  </Card>
+  <Card title="迁移" href="/install/migrating" icon="arrow-right">
+    迁移到新机器。
+  </Card>
+  <Card title="卸载" href="/install/uninstall" icon="trash-2">
+    完全移除 QuantumClaw。
+  </Card>
+</CardGroup>