@termix-it/cryptoclaw 1.0.0

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

@@ -0,0 +1,337 @@
+---
+read_when:
+  - 你想让 OpenClaw 在云 VPS 上 24/7 运行（而不是你的笔记本电脑）
+  - 你想在自己的 VPS 上运行生产级、永久在线的 Gateway 网关
+  - 你想完全控制持久化、二进制文件和重启行为
+  - 你在 Hetzner 或类似提供商上用 Docker 运行 OpenClaw
+summary: 在廉价的 Hetzner VPS（Docker）上 24/7 运行 OpenClaw 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 上运行 OpenClaw（Docker，生产 VPS 指南）
+
+## 目标
+
+使用 Docker 在 Hetzner VPS 上运行持久的 OpenClaw Gateway 网关，带持久状态、内置二进制文件和安全的重启行为。
+
+如果你想要"约 $5 实现 OpenClaw 24/7"，这是最简单可靠的设置。
+Hetzner 定价会变化；选择最小的 Debian/Ubuntu VPS，如果遇到 OOM 再扩容。
+
+## 我们在做什么（简单说明）？
+
+- 租用一台小型 Linux 服务器（Hetzner VPS）
+- 安装 Docker（隔离的应用运行时）
+- 在 Docker 中启动 OpenClaw Gateway 网关
+- 在主机上持久化 `~/.openclaw` + `~/.openclaw/workspace`（重启/重建后保留）
+- 通过 SSH 隧道从你的笔记本电脑访问控制 UI
+
+Gateway 网关可以通过以下方式访问：
+
+- 从你的笔记本电脑进行 SSH 端口转发
+- 如果你自己管理防火墙和令牌，可以直接暴露端口
+
+本指南假设在 Hetzner 上使用 Ubuntu 或 Debian。
+如果你使用其他 Linux VPS，请相应地映射软件包。
+通用 Docker 流程请参见 [Docker](/install/docker)。
+
+---
+
+## 快速路径（有经验的运维人员）
+
+1. 配置 Hetzner VPS
+2. 安装 Docker
+3. 克隆 OpenClaw 仓库
+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) 克隆 OpenClaw 仓库
+
+```bash
+git clone https://github.com/openclaw/openclaw.git
+cd openclaw
+```
+
+本指南假设你将构建自定义镜像以保证二进制文件持久化。
+
+---
+
+## 4) 创建持久化主机目录
+
+Docker 容器是临时的。
+所有长期状态必须存储在主机上。
+
+```bash
+mkdir -p /root/.openclaw
+mkdir -p /root/.openclaw/workspace
+
+# 将所有权设置为容器用户（uid 1000）：
+chown -R 1000:1000 /root/.openclaw
+chown -R 1000:1000 /root/.openclaw/workspace
+```
+
+---
+
+## 5) 配置环境变量
+
+在仓库根目录创建 `.env`。
+
+```bash
+OPENCLAW_IMAGE=openclaw:latest
+OPENCLAW_GATEWAY_TOKEN=change-me-now
+OPENCLAW_GATEWAY_BIND=lan
+OPENCLAW_GATEWAY_PORT=18789
+
+OPENCLAW_CONFIG_DIR=/root/.openclaw
+OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace
+
+GOG_KEYRING_PASSWORD=change-me-now
+XDG_CONFIG_HOME=/home/node/.openclaw
+```
+
+生成强密钥：
+
+```bash
+openssl rand -hex 32
+```
+
+**不要提交此文件。**
+
+---
+
+## 6) Docker Compose 配置
+
+创建或更新 `docker-compose.yml`。
+
+```yaml
+services:
+  openclaw-gateway:
+    image: ${OPENCLAW_IMAGE}
+    build: .
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      - HOME=/home/node
+      - NODE_ENV=production
+      - TERM=xterm-256color
+      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
+      - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
+      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_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:
+      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
+      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
+    ports:
+      # 推荐：在 VPS 上保持 Gateway 网关仅限 loopback；通过 SSH 隧道访问。
+      # 要公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
+      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
+
+      # 可选：仅当你对此 VPS 运行 iOS/Android 节点并需要 Canvas 主机时。
+      # 如果你公开暴露此端口，请阅读 /gateway/security 并相应配置防火墙。
+      # - "18793:18793"
+    command:
+      [
+        "node",
+        "dist/index.js",
+        "gateway",
+        "--bind",
+        "${OPENCLAW_GATEWAY_BIND}",
+        "--port",
+        "${OPENCLAW_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 openclaw-gateway
+```
+
+验证二进制文件：
+
+```bash
+docker compose exec openclaw-gateway which gog
+docker compose exec openclaw-gateway which goplaces
+docker compose exec openclaw-gateway which wacli
+```
+
+预期输出：
+
+```
+/usr/local/bin/gog
+/usr/local/bin/goplaces
+/usr/local/bin/wacli
+```
+
+---
+
+## 9) 验证 Gateway 网关
+
+```bash
+docker compose logs -f openclaw-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 网关令牌。
+
+---
+
+## 持久化位置（事实来源）
+
+OpenClaw 在 Docker 中运行，但 Docker 不是事实来源。
+所有长期状态必须在重启、重建和重启后保留。
+
+| 组件             | 位置                              | 持久化机制    | 说明                        |
+| ---------------- | --------------------------------- | ------------- | --------------------------- |
+| Gateway 网关配置 | `/home/node/.openclaw/`           | 主机卷挂载    | 包括 `openclaw.json`、令牌  |
+| 模型认证配置文件 | `/home/node/.openclaw/`           | 主机卷挂载    | OAuth 令牌、API 密钥        |
+| Skill 配置       | `/home/node/.openclaw/skills/`    | 主机卷挂载    | Skill 级别状态              |
+| 智能体工作区     | `/home/node/.openclaw/workspace/` | 主机卷挂载    | 代码和智能体产物            |
+| WhatsApp 会话    | `/home/node/.openclaw/`           | 主机卷挂载    | 保留二维码登录              |
+| Gmail 密钥环     | `/home/node/.openclaw/`           | 主机卷 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
+| 外部二进制文件   | `/usr/local/bin/`                 | Docker 镜像   | 必须在构建时烘焙            |
+| Node 运行时      | 容器文件系统                      | Docker 镜像   | 每次镜像构建时重建          |
+| 操作系统包       | 容器文件系统                      | Docker 镜像   | 不要在运行时安装            |
+| Docker 容器      | 临时的                            | 可重启        | 可以安全销毁                |

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

@@ -0,0 +1,193 @@
+---
+read_when:
+  - 安装 OpenClaw
+  - 你想从 GitHub 安装
+summary: 安装 OpenClaw（推荐安装器、全局安装或从源代码安装）
+title: 安装
+x-i18n:
+  generated_at: "2026-02-03T10:07:43Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b26f48c116c26c163ee0090fb4c3e29622951bd427ecaeccba7641d97cfdf17a
+  source_path: install/index.md
+  workflow: 15
+---
+
+# 安装
+
+除非有特殊原因，否则请使用安装器。它会设置 CLI 并运行新手引导。
+
+## 快速安装（推荐）
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+Windows（PowerShell）：
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex
+```
+
+下一步（如果你跳过了新手引导）：
+
+```bash
+openclaw onboard --install-daemon
+```
+
+## 系统要求
+
+- **Node >=22**
+- macOS、Linux 或通过 WSL2 的 Windows
+- `pnpm` 仅在从源代码构建时需要
+
+## 选择安装路径
+
+### 1）安装器脚本（推荐）
+
+通过 npm 全局安装 `openclaw` 并运行新手引导。
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+安装器标志：
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
+```
+
+详情：[安装器内部原理](/install/installer)。
+
+非交互式（跳过新手引导）：
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
+```
+
+### 2）全局安装（手动）
+
+如果你已经有 Node：
+
+```bash
+npm install -g openclaw@latest
+```
+
+如果你全局安装了 libvips（macOS 上通过 Homebrew 安装很常见）且 `sharp` 安装失败，请强制使用预构建二进制文件：
+
+```bash
+SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
+```
+
+如果你看到 `sharp: Please add node-gyp to your dependencies`，要么安装构建工具（macOS：Xcode CLT + `npm install -g node-gyp`），要么使用上面的 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 变通方法来跳过原生构建。
+
+或使用 pnpm：
+
+```bash
+pnpm add -g openclaw@latest
+pnpm approve-builds -g                # 批准 openclaw、node-llama-cpp、sharp 等
+pnpm add -g openclaw@latest           # 重新运行以执行 postinstall 脚本
+```
+
+pnpm 需要显式批准带有构建脚本的包。在首次安装显示"Ignored build scripts"警告后，运行 `pnpm approve-builds -g` 并选择列出的包，然后重新运行安装以执行 postinstall 脚本。
+
+然后：
+
+```bash
+openclaw onboard --install-daemon
+```
+
+### 3）从源代码（贡献者/开发）
+
+```bash
+git clone https://github.com/openclaw/openclaw.git
+cd openclaw
+pnpm install
+pnpm ui:build # 首次运行时自动安装 UI 依赖
+pnpm build
+openclaw onboard --install-daemon
+```
+
+提示：如果你还没有全局安装，请通过 `pnpm openclaw ...` 运行仓库命令。
+
+### 4）其他安装选项
+
+- Docker：[Docker](/install/docker)
+- Nix：[Nix](/install/nix)
+- Ansible：[Ansible](/install/ansible)
+- Bun（仅 CLI）：[Bun](/install/bun)
+
+## 安装后
+
+- 运行新手引导：`openclaw onboard --install-daemon`
+- 快速检查：`openclaw doctor`
+- 检查 Gateway 网关健康状态：`openclaw status` + `openclaw health`
+- 打开仪表板：`openclaw dashboard`
+
+## 安装方式：npm vs git（安装器）
+
+安装器支持两种方式：
+
+- `npm`（默认）：`npm install -g openclaw@latest`
+- `git`：从 GitHub 克隆/构建并从源代码 checkout 运行
+
+### CLI 标志
+
+```bash
+# 显式 npm
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
+
+# 从 GitHub 安装（源代码 checkout）
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
+```
+
+常用标志：
+
+- `--install-method npm|git`
+- `--git-dir <path>`（默认：`~/openclaw`）
+- `--no-git-update`（使用现有 checkout 时跳过 `git pull`）
+- `--no-prompt`（禁用提示；CI/自动化中必需）
+- `--dry-run`（打印将要执行的操作；不做任何更改）
+- `--no-onboard`（跳过新手引导）
+
+### 环境变量
+
+等效的环境变量（对自动化有用）：
+
+- `OPENCLAW_INSTALL_METHOD=git|npm`
+- `OPENCLAW_GIT_DIR=...`
+- `OPENCLAW_GIT_UPDATE=0|1`
+- `OPENCLAW_NO_PROMPT=1`
+- `OPENCLAW_DRY_RUN=1`
+- `OPENCLAW_NO_ONBOARD=1`
+- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1`（默认：`1`；避免 `sharp` 针对系统 libvips 构建）
+
+## 故障排除：找不到 `openclaw`（PATH）
+
+快速诊断：
+
+```bash
+node -v
+npm -v
+npm prefix -g
+echo "$PATH"
+```
+
+如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不**在 `echo "$PATH"` 的输出中，你的 shell 无法找到全局 npm 二进制文件（包括 `openclaw`）。
+
+修复：将其添加到你的 shell 启动文件（zsh：`~/.zshrc`，bash：`~/.bashrc`）：
+
+```bash
+# macOS / Linux
+export PATH="$(npm prefix -g)/bin:$PATH"
+```
+
+在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH。
+
+然后打开新终端（或在 zsh 中执行 `rehash` / 在 bash 中执行 `hash -r`）。
+
+## 更新/卸载
+
+- 更新：[更新](/install/updating)
+- 迁移到新机器：[迁移](/install/migrating)
+- 卸载：[卸载](/install/uninstall)

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

@@ -0,0 +1,128 @@
+---
+read_when:
+  - 你想了解 `openclaw.ai/install.sh` 的工作机制
+  - 你想自动化安装（CI / 无头环境）
+  - 你想从 GitHub 检出安装
+summary: 安装器脚本的工作原理（install.sh + install-cli.sh）、参数和自动化
+title: 安装器内部机制
+x-i18n:
+  generated_at: "2026-02-01T21:07:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 9e0a19ecb5da0a395030e1ccf0d4bedf16b83946b3432c5399d448fe5d298391
+  source_path: install/installer.md
+  workflow: 14
+---
+
+# 安装器内部机制
+
+OpenClaw 提供两个安装器脚本（托管在 `openclaw.ai`）：
+
+- `https://openclaw.ai/install.sh` — "推荐"安装器（默认全局 npm 安装；也可从 GitHub 检出安装）
+- `https://openclaw.ai/install-cli.sh` — 无需 root 权限的 CLI 安装器（安装到带有独立 Node 的前缀目录）
+- `https://openclaw.ai/install.ps1` — Windows PowerShell 安装器（默认 npm；可选 git 安装）
+
+查看当前参数/行为，运行：
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
+```
+
+Windows (PowerShell) 帮助：
+
+```powershell
+& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -?
+```
+
+如果安装器完成但在新终端中找不到 `openclaw`，通常是 Node/npm PATH 问题。参见：[安装](/install#nodejs--npm-path-sanity)。
+
+## install.sh（推荐）
+
+功能概述：
+
+- 检测操作系统（macOS / Linux / WSL）。
+- 确保 Node.js **22+**（macOS 通过 Homebrew；Linux 通过 NodeSource）。
+- 选择安装方式：
+  - `npm`（默认）：`npm install -g openclaw@latest`
+  - `git`：克隆/构建源码检出并安装包装脚本
+- 在 Linux 上：必要时将 npm 前缀切换到 `~/.npm-global`，以避免全局 npm 权限错误。
+- 如果是升级现有安装：运行 `openclaw doctor --non-interactive`（尽力执行）。
+- 对于 git 安装：安装/更新后运行 `openclaw doctor --non-interactive`（尽力执行）。
+- 通过默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 来缓解 `sharp` 原生安装问题（避免使用系统 libvips 编译）。
+
+如果你*希望* `sharp` 链接到全局安装的 libvips（或你正在调试），请设置：
+
+```bash
+SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+### 可发现性 / "git 安装"提示
+
+如果你在**已有的 OpenClaw 源码检出目录中**运行安装器（通过 `package.json` + `pnpm-workspace.yaml` 检测），它会提示：
+
+- 更新并使用此检出（`git`）
+- 或迁移到全局 npm 安装（`npm`）
+
+在非交互式上下文中（无 TTY / `--no-prompt`），你必须传入 `--install-method git|npm`（或设置 `OPENCLAW_INSTALL_METHOD`），否则脚本将以退出码 `2` 退出。
+
+### 为什么需要 Git
+
+`--install-method git` 路径（克隆 / 拉取）需要 Git。
+
+对于 `npm` 安装，Git *通常*不是必需的，但某些环境仍然需要它（例如通过 git URL 获取软件包或依赖时）。安装器目前会确保 Git 存在，以避免在全新发行版上出现 `spawn git ENOENT` 错误。
+
+### 为什么在全新 Linux 上 npm 会报 `EACCES`
+
+在某些 Linux 设置中（尤其是通过系统包管理器或 NodeSource 安装 Node 后），npm 的全局前缀指向 root 拥有的位置。此时 `npm install -g ...` 会报 `EACCES` / `mkdir` 权限错误。
+
+`install.sh` 通过将前缀切换到以下位置来缓解此问题：
+
+- `~/.npm-global`（并在存在时将其添加到 `~/.bashrc` / `~/.zshrc` 的 `PATH` 中）
+
+## install-cli.sh（无需 root 权限的 CLI 安装器）
+
+此脚本将 `openclaw` 安装到前缀目录（默认：`~/.openclaw`），同时在该前缀下安装专用的 Node 运行时，因此可以在不想改动系统 Node/npm 的机器上使用。
+
+帮助：
+
+```bash
+curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help
+```
+
+## install.ps1（Windows PowerShell）
+
+功能概述：
+
+- 确保 Node.js **22+**（winget/Chocolatey/Scoop 或手动安装）。
+- 选择安装方式：
+  - `npm`（默认）：`npm install -g openclaw@latest`
+  - `git`：克隆/构建源码检出并安装包装脚本
+- 在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力执行）。
+
+示例：
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex
+```
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git
+```
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw"
+```
+
+环境变量：
+
+- `OPENCLAW_INSTALL_METHOD=git|npm`
+- `OPENCLAW_GIT_DIR=...`
+
+Git 要求：
+
+如果你选择 `-InstallMethod git` 但未安装 Git，安装器会打印 Git for Windows 的链接（`https://git-scm.com/download/win`）并退出。
+
+常见 Windows 问题：
+
+- **npm error spawn git / ENOENT**：安装 Git for Windows 并重新打开 PowerShell，然后重新运行安装器。
+- **"openclaw" 不是可识别的命令**：你的 npm 全局 bin 文件夹不在 PATH 中。大多数系统使用 `%AppData%\\npm`。你也可以运行 `npm config get prefix` 并将 `\\bin` 添加到 PATH，然后重新打开 PowerShell。