@termix-it/cryptoclaw 1.0.0

package/docs/zh-CN/install/macos-vm.md

@@ -0,0 +1,288 @@
+---
+read_when:
+  - 你想让 OpenClaw 与你的主 macOS 环境隔离
+  - 你想在沙箱中集成 iMessage（BlueBubbles）
+  - 你想要一个可重置、可克隆的 macOS 环境
+  - 你想比较本地与托管 macOS VM 选项
+summary: 在沙箱隔离的 macOS VM（本地或托管）中运行 OpenClaw，当你需要隔离或 iMessage 时
+title: macOS 虚拟机
+x-i18n:
+  generated_at: "2026-02-03T07:53:09Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 4d1c85a5e4945f9f0796038cd5960edecb71ec4dffb6f9686be50adb75180716
+  source_path: platforms/macos-vm.md
+  workflow: 15
+---
+
+# 在 macOS 虚拟机上运行 OpenClaw（沙箱隔离）
+
+## 推荐默认方案（大多数用户）
+
+- **小型 Linux VPS** 用于永久在线的 Gateway 网关，成本低。参见 [VPS 托管](/vps)。
+- **专用硬件**（Mac mini 或 Linux 机器）如果你想要完全控制和**住宅 IP** 用于浏览器自动化。许多网站会屏蔽数据中心 IP，所以本地浏览通常效果更好。
+- **混合方案：** 将 Gateway 网关保持在廉价 VPS 上，当你需要浏览器/UI 自动化时，将你的 Mac 作为**节点**连接。参见[节点](/nodes)和 [Gateway 网关远程](/gateway/remote)。
+
+当你特别需要 macOS 独有功能（iMessage/BlueBubbles）或想要与日常 Mac 严格隔离时，使用 macOS VM。
+
+## macOS VM 选项
+
+### 在你的 Apple Silicon Mac 上运行本地 VM（Lume）
+
+使用 [Lume](https://cua.ai/docs/lume) 在你现有的 Apple Silicon Mac 上的沙箱 macOS VM 中运行 OpenClaw。
+
+这为你提供：
+
+- 隔离的完整 macOS 环境（你的主机保持干净）
+- 通过 BlueBubbles 支持 iMessage（在 Linux/Windows 上不可能）
+- 通过克隆 VM 即时重置
+- 无需额外硬件或云成本
+
+### 托管 Mac 提供商（云）
+
+如果你想要云端的 macOS，托管 Mac 提供商也可以：
+
+- [MacStadium](https://www.macstadium.com/)（托管 Mac）
+- 其他托管 Mac 供应商也可以；按照他们的 VM + SSH 文档操作
+
+一旦你有了 macOS VM 的 SSH 访问权限，继续下面的步骤 6。
+
+---
+
+## 快速路径（Lume，有经验的用户）
+
+1. 安装 Lume
+2. `lume create openclaw --os macos --ipsw latest`
+3. 完成设置助手，启用远程登录（SSH）
+4. `lume run openclaw --no-display`
+5. SSH 进入，安装 OpenClaw，配置渠道
+6. 完成
+
+---
+
+## 你需要什么（Lume）
+
+- Apple Silicon Mac（M1/M2/M3/M4）
+- 主机上安装 macOS Sequoia 或更高版本
+- 每个 VM 约 60 GB 可用磁盘空间
+- 约 20 分钟
+
+---
+
+## 1) 安装 Lume
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
+```
+
+如果 `~/.local/bin` 不在你的 PATH 中：
+
+```bash
+echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
+```
+
+验证：
+
+```bash
+lume --version
+```
+
+文档：[Lume 安装](https://cua.ai/docs/lume/guide/getting-started/installation)
+
+---
+
+## 2) 创建 macOS VM
+
+```bash
+lume create openclaw --os macos --ipsw latest
+```
+
+这会下载 macOS 并创建 VM。VNC 窗口会自动打开。
+
+注意：下载可能需要一段时间，取决于你的网络连接。
+
+---
+
+## 3) 完成设置助手
+
+在 VNC 窗口中：
+
+1. 选择语言和地区
+2. 跳过 Apple ID（或者如果你以后想要 iMessage 就登录）
+3. 创建用户账户（记住用户名和密码）
+4. 跳过所有可选功能
+
+设置完成后，启用 SSH：
+
+1. 打开系统设置 → 通用 → 共享
+2. 启用"远程登录"
+
+---
+
+## 4) 获取 VM 的 IP 地址
+
+```bash
+lume get openclaw
+```
+
+查找 IP 地址（通常是 `192.168.64.x`）。
+
+---
+
+## 5) SSH 进入 VM
+
+```bash
+ssh youruser@192.168.64.X
+```
+
+将 `youruser` 替换为你创建的账户，IP 替换为你 VM 的 IP。
+
+---
+
+## 6) 安装 OpenClaw
+
+在 VM 内：
+
+```bash
+npm install -g openclaw@latest
+openclaw onboard --install-daemon
+```
+
+按照新手引导提示设置你的模型提供商（Anthropic、OpenAI 等）。
+
+---
+
+## 7) 配置渠道
+
+编辑配置文件：
+
+```bash
+nano ~/.openclaw/openclaw.json
+```
+
+添加你的渠道：
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "dmPolicy": "allowlist",
+      "allowFrom": ["+15551234567"]
+    },
+    "telegram": {
+      "botToken": "YOUR_BOT_TOKEN"
+    }
+  }
+}
+```
+
+然后登录 WhatsApp（扫描二维码）：
+
+```bash
+openclaw channels login
+```
+
+---
+
+## 8) 无头运行 VM
+
+停止 VM 并在无显示器模式下重启：
+
+```bash
+lume stop openclaw
+lume run openclaw --no-display
+```
+
+VM 在后台运行。OpenClaw 的守护进程保持 Gateway 网关运行。
+
+检查状态：
+
+```bash
+ssh youruser@192.168.64.X "openclaw status"
+```
+
+---
+
+## 额外：iMessage 集成
+
+这是在 macOS 上运行的杀手级功能。使用 [BlueBubbles](https://bluebubbles.app) 将 iMessage 添加到 OpenClaw。
+
+在 VM 内：
+
+1. 从 bluebubbles.app 下载 BlueBubbles
+2. 用你的 Apple ID 登录
+3. 启用 Web API 并设置密码
+4. 将 BlueBubbles webhooks 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）
+
+添加到你的 OpenClaw 配置：
+
+```json
+{
+  "channels": {
+    "bluebubbles": {
+      "serverUrl": "http://localhost:1234",
+      "password": "your-api-password",
+      "webhookPath": "/bluebubbles-webhook"
+    }
+  }
+}
+```
+
+重启 Gateway 网关。现在你的智能体可以发送和接收 iMessage 了。
+
+完整设置详情：[BlueBubbles 渠道](/channels/bluebubbles)
+
+---
+
+## 保存黄金镜像
+
+在进一步自定义之前，快照你的干净状态：
+
+```bash
+lume stop openclaw
+lume clone openclaw openclaw-golden
+```
+
+随时重置：
+
+```bash
+lume stop openclaw && lume delete openclaw
+lume clone openclaw-golden openclaw
+lume run openclaw --no-display
+```
+
+---
+
+## 24/7 运行
+
+通过以下方式保持 VM 运行：
+
+- 保持你的 Mac 插电
+- 在系统设置 → 节能中禁用睡眠
+- 如需要使用 `caffeinate`
+
+对于真正的永久在线，考虑专用 Mac mini 或小型 VPS。参见 [VPS 托管](/vps)。
+
+---
+
+## 故障排除
+
+| 问题                    | 解决方案                                                         |
+| ----------------------- | ---------------------------------------------------------------- |
+| 无法 SSH 进入 VM        | 检查 VM 的系统设置中是否启用了"远程登录"                         |
+| VM IP 未显示            | 等待 VM 完全启动，再次运行 `lume get openclaw`                   |
+| 找不到 Lume 命令        | 将 `~/.local/bin` 添加到你的 PATH                                |
+| WhatsApp 二维码扫描失败 | 确保运行 `openclaw channels login` 时你是登录到 VM（而不是主机） |
+
+---
+
+## 相关文档
+
+- [VPS 托管](/vps)
+- [节点](/nodes)
+- [Gateway 网关远程](/gateway/remote)
+- [BlueBubbles 渠道](/channels/bluebubbles)
+- [Lume 快速入门](https://cua.ai/docs/lume/guide/getting-started/quickstart)
+- [Lume CLI 参考](https://cua.ai/docs/lume/reference/cli-reference)
+- [无人值守 VM 设置](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup)（高级）
+- [Docker 沙箱隔离](/install/docker)（替代隔离方案）

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

@@ -0,0 +1,199 @@
+---
+read_when:
+  - 你正在将 OpenClaw 迁移到新的笔记本电脑/服务器
+  - 你想保留会话、认证和渠道登录（WhatsApp 等）
+summary: 将 OpenClaw 安装从一台机器迁移到另一台
+title: 迁移指南
+x-i18n:
+  generated_at: "2026-02-03T07:49:55Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 604d862c4bf86e7924d09028db8cc2514ca6f1d64ebe8bb7d1e2dde57ef70caa
+  source_path: install/migrating.md
+  workflow: 15
+---
+
+# 将 OpenClaw 迁移到新机器
+
+本指南将 OpenClaw Gateway 网关从一台机器迁移到另一台，**无需重新进行新手引导**。
+
+迁移在概念上很简单：
+
+- 复制**状态目录**（`$OPENCLAW_STATE_DIR`，默认：`~/.openclaw/`）— 这包括配置、认证、会话和渠道状态。
+- 复制你的**工作区**（默认 `~/.openclaw/workspace/`）— 这包括你的智能体文件（记忆、提示等）。
+
+但在**配置文件**、**权限**和**部分复制**方面有常见的陷阱。
+
+## 开始之前（你要迁移什么）
+
+### 1）确定你的状态目录
+
+大多数安装使用默认值：
+
+- **状态目录：** `~/.openclaw/`
+
+但如果你使用以下方式，可能会不同：
+
+- `--profile <name>`（通常变成 `~/.openclaw-<profile>/`）
+- `OPENCLAW_STATE_DIR=/some/path`
+
+如果你不确定，在**旧**机器上运行：
+
+```bash
+openclaw status
+```
+
+在输出中查找 `OPENCLAW_STATE_DIR` / profile 的提及。如果你运行多个 Gateway 网关，对每个配置文件重复此操作。
+
+### 2）确定你的工作区
+
+常见默认值：
+
+- `~/.openclaw/workspace/`（推荐的工作区）
+- 你创建的自定义文件夹
+
+你的工作区是 `MEMORY.md`、`USER.md` 和 `memory/*.md` 等文件所在的位置。
+
+### 3）了解你将保留什么
+
+如果你复制**两者**——状态目录和工作区，你将保留：
+
+- Gateway 网关配置（`openclaw.json`）
+- 认证配置文件 / API 密钥 / OAuth 令牌
+- 会话历史 + 智能体状态
+- 渠道状态（例如 WhatsApp 登录/会话）
+- 你的工作区文件（记忆、Skills 笔记等）
+
+如果你**只**复制工作区（例如通过 Git），你**不会**保留：
+
+- 会话
+- 凭证
+- 渠道登录
+
+这些存储在 `$OPENCLAW_STATE_DIR` 下。
+
+## 迁移步骤（推荐）
+
+### 步骤 0 — 备份（旧机器）
+
+在**旧**机器上，首先停止 Gateway 网关，这样文件不会在复制过程中发生变化：
+
+```bash
+openclaw gateway stop
+```
+
+（可选但推荐）归档状态目录和工作区：
+
+```bash
+# 如果你使用配置文件或自定义位置，请调整路径
+cd ~
+tar -czf openclaw-state.tgz .openclaw
+
+tar -czf openclaw-workspace.tgz .openclaw/workspace
+```
+
+如果你有多个配置文件/状态目录（例如 `~/.openclaw-main`、`~/.openclaw-work`），分别归档每个。
+
+### 步骤 1 — 在新机器上安装 OpenClaw
+
+在**新**机器上，安装 CLI（如果需要还有 Node）：
+
+- 参见：[安装](/install)
+
+在这个阶段，如果新手引导创建了一个新的 `~/.openclaw/` 也没关系 — 你将在下一步覆盖它。
+
+### 步骤 2 — 将状态目录 + 工作区复制到新机器
+
+复制**两者**：
+
+- `$OPENCLAW_STATE_DIR`（默认 `~/.openclaw/`）
+- 你的工作区（默认 `~/.openclaw/workspace/`）
+
+常见方法：
+
+- `scp` 压缩包并解压
+- 通过 SSH 使用 `rsync -a`
+- 外部驱动器
+
+复制后，确保：
+
+- 包含了隐藏目录（例如 `.openclaw/`）
+- 文件所有权对于运行 Gateway 网关的用户是正确的
+
+### 步骤 3 — 运行 Doctor（迁移 + 服务修复）
+
+在**新**机器上：
+
+```bash
+openclaw doctor
+```
+
+Doctor 是"安全可靠"的命令。它修复服务、应用配置迁移，并警告不匹配问题。
+
+然后：
+
+```bash
+openclaw gateway restart
+openclaw status
+```
+
+## 常见陷阱（以及如何避免）
+
+### 陷阱：配置文件/状态目录不匹配
+
+如果你在旧 Gateway 网关上使用了配置文件（或 `OPENCLAW_STATE_DIR`），而新 Gateway 网关使用了不同的配置，你会看到如下症状：
+
+- 配置更改不生效
+- 渠道丢失/已登出
+- 会话历史为空
+
+修复：使用你迁移的**相同**配置文件/状态目录运行 Gateway 网关/服务，然后重新运行：
+
+```bash
+openclaw doctor
+```
+
+### 陷阱：只复制 `openclaw.json`
+
+`openclaw.json` 是不够的。许多提供商在以下位置存储状态：
+
+- `$OPENCLAW_STATE_DIR/credentials/`
+- `$OPENCLAW_STATE_DIR/agents/<agentId>/...`
+
+始终迁移整个 `$OPENCLAW_STATE_DIR` 文件夹。
+
+### 陷阱：权限/所有权
+
+如果你以 root 身份复制或更改了用户，Gateway 网关可能无法读取凭证/会话。
+
+修复：确保状态目录 + 工作区由运行 Gateway 网关的用户拥有。
+
+### 陷阱：在远程/本地模式之间迁移
+
+- 如果你的 UI（WebUI/TUI）指向**远程** Gateway 网关，远程主机拥有会话存储 + 工作区。
+- 迁移你的笔记本电脑不会移动远程 Gateway 网关的状态。
+
+如果你处于远程模式，请迁移 **Gateway 网关主机**。
+
+### 陷阱：备份中的密钥
+
+`$OPENCLAW_STATE_DIR` 包含密钥（API 密钥、OAuth 令牌、WhatsApp 凭证）。将备份视为生产密钥：
+
+- 加密存储
+- 避免通过不安全的渠道共享
+- 如果怀疑泄露，轮换密钥
+
+## 验证检查清单
+
+在新机器上，确认：
+
+- `openclaw status` 显示 Gateway 网关正在运行
+- 你的渠道仍然连接（例如 WhatsApp 不需要重新配对）
+- 仪表板打开并显示现有会话
+- 你的工作区文件（记忆、配置）存在
+
+## 相关内容
+
+- [Doctor](/gateway/doctor)
+- [Gateway 网关故障排除](/gateway/troubleshooting)
+- [OpenClaw 在哪里存储数据？](/help/faq#where-does-openclaw-store-its-data)

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

@@ -0,0 +1,99 @@
+---
+read_when:
+  - 你想要可复现、可回滚的安装
+  - 你已经在使用 Nix/NixOS/Home Manager
+  - 你想要所有内容都固定并以声明式管理
+summary: 使用 Nix 声明式安装 OpenClaw
+title: Nix
+x-i18n:
+  generated_at: "2026-02-03T07:49:51Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f1452194cfdd74613b5b3ab90b0d506eaea2d16b147497987710d6ad658312ba
+  source_path: install/nix.md
+  workflow: 15
+---
+
+# Nix 安装
+
+使用 Nix 运行 OpenClaw 的推荐方式是通过 **[nix-openclaw](https://github.com/openclaw/nix-openclaw)** — 一个开箱即用的 Home Manager 模块。
+
+## 快速开始
+
+将此粘贴给你的 AI 智能体（Claude、Cursor 等）：
+
+```text
+I want to set up nix-openclaw on my Mac.
+Repository: github:openclaw/nix-openclaw
+
+What I need you to do:
+1. Check if Determinate Nix is installed (if not, install it)
+2. Create a local flake at ~/code/openclaw-local using templates/agent-first/flake.nix
+3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
+4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
+5. Fill in the template placeholders and run home-manager switch
+6. Verify: launchd running, bot responds to messages
+
+Reference the nix-openclaw README for module options.
+```
+
+> **📦 完整指南：[github.com/openclaw/nix-openclaw](https://github.com/openclaw/nix-openclaw)**
+>
+> nix-openclaw 仓库是 Nix 安装的权威来源。本页只是一个快速概述。
+
+## 你将获得
+
+- Gateway 网关 + macOS 应用 + 工具（whisper、spotify、cameras）— 全部固定版本
+- 重启后仍能运行的 Launchd 服务
+- 带有声明式配置的插件系统
+- 即时回滚：`home-manager switch --rollback`
+
+---
+
+## Nix 模式运行时行为
+
+当设置 `OPENCLAW_NIX_MODE=1` 时（nix-openclaw 会自动设置）：
+
+OpenClaw 支持 **Nix 模式**，使配置确定性并禁用自动安装流程。
+通过导出以下环境变量启用：
+
+```bash
+OPENCLAW_NIX_MODE=1
+```
+
+在 macOS 上，GUI 应用不会自动继承 shell 环境变量。你也可以通过 defaults 启用 Nix 模式：
+
+```bash
+defaults write bot.molt.mac openclaw.nixMode -bool true
+```
+
+### 配置 + 状态路径
+
+OpenClaw 从 `OPENCLAW_CONFIG_PATH` 读取 JSON5 配置，并将可变数据存储在 `OPENCLAW_STATE_DIR` 中。
+
+- `OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）
+- `OPENCLAW_CONFIG_PATH`（默认：`$OPENCLAW_STATE_DIR/openclaw.json`）
+
+在 Nix 下运行时，将这些显式设置为 Nix 管理的位置，以便运行时状态和配置不会进入不可变存储。
+
+### Nix 模式下的运行时行为
+
+- 自动安装和自我修改流程被禁用
+- 缺失的依赖会显示 Nix 特定的修复消息
+- 存在时 UI 会显示只读 Nix 模式横幅
+
+## 打包注意事项（macOS）
+
+macOS 打包流程期望在以下位置有一个稳定的 Info.plist 模板：
+
+```
+apps/macos/Sources/OpenClaw/Resources/Info.plist
+```
+
+[`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 将此模板复制到应用包中并修补动态字段（bundle ID、版本/构建号、Git SHA、Sparkle 密钥）。这使 plist 对于 SwiftPM 打包和 Nix 构建保持确定性（它们不依赖完整的 Xcode 工具链）。
+
+## 相关内容
+
+- [nix-openclaw](https://github.com/openclaw/nix-openclaw) — 完整设置指南
+- [向导](/start/wizard) — 非 Nix CLI 设置
+- [Docker](/install/docker) — 容器化设置

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

@@ -0,0 +1,85 @@
+---
+read_when:
+  - 你已安装 OpenClaw 但 `openclaw` 提示"command not found"
+  - 你正在新机器上配置 Node.js/npm
+  - npm install -g ... 因权限或 PATH 问题失败
+summary: Node.js + npm 安装完整性检查：版本、PATH 及全局安装
+title: Node.js + npm（PATH 安装完整性检查）
+x-i18n:
+  generated_at: "2026-02-01T21:16:20Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 9f6d83be362e3e148ddf07d47e57c51679c22687263d3b5131cccbef2e37c598
+  source_path: install/node.md
+  workflow: 15
+---
+
+# Node.js + npm（PATH 安装完整性检查）
+
+OpenClaw 的运行时基线要求为 **Node 22+**。
+
+如果你能运行 `npm install -g openclaw@latest`，但之后看到 `openclaw: command not found`，这几乎总是 **PATH** 问题：npm 存放全局二进制文件的目录不在你 shell 的 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`）。
+
+## 修复：将 npm 的全局 bin 目录添加到 PATH
+
+1. 查找你的全局 npm 前缀：
+
+```bash
+npm prefix -g
+```
+
+2. 将全局 npm bin 目录添加到你的 shell 启动文件中：
+
+- zsh：`~/.zshrc`
+- bash：`~/.bashrc`
+
+示例（将路径替换为你的 `npm prefix -g` 输出）：
+
+```bash
+# macOS / Linux
+export PATH="/path/from/npm/prefix/bin:$PATH"
+```
+
+然后打开一个**新终端**（或在 zsh 中运行 `rehash` / 在 bash 中运行 `hash -r`）。
+
+在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH 中。
+
+## 修复：避免 `sudo npm install -g` / 权限错误（Linux）
+
+如果 `npm install -g ...` 因 `EACCES` 失败，请将 npm 的全局前缀切换到用户可写的目录：
+
+```bash
+mkdir -p "$HOME/.npm-global"
+npm config set prefix "$HOME/.npm-global"
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
+
+将 `export PATH=...` 这一行持久化到你的 shell 启动文件中。
+
+## 推荐的 Node 安装方式
+
+如果 Node/npm 的安装方式满足以下条件，你将遇到最少的问题：
+
+- 保持 Node 更新（22+）
+- 使全局 npm bin 目录稳定且在新 shell 中位于 PATH 中
+
+常见选择：
+
+- macOS：Homebrew（`brew install node`）或版本管理器
+- Linux：你偏好的版本管理器，或提供 Node 22+ 的发行版支持的安装方式
+- Windows：官方 Node 安装程序、`winget` 或 Windows Node 版本管理器
+
+如果你使用版本管理器（nvm/fnm/asdf 等），请确保它在你日常使用的 shell（zsh 或 bash）中已初始化，这样它设置的 PATH 在你运行安装程序时才会生效。