README_zh.md

---
title: OpenClaw HF Space
emoji: 🦞
colorFrom: blue
colorTo: indigo
sdk: docker
sdk_version: 29.0.4
app_port: 7860
app_file: mian.py
pinned: false
---

# OpenClaw HF Space 部署工具（中文版）

> **Languages:** [English](./README.md) · [简体中文](./README_zh.md)
> **部署指南:** [English](./DEPLOY_GUIDE.md) · [中文部署指南](./DEPLOY_GUIDE_zh.md)

本项目提供在 Hugging Face Space 上部署 OpenClaw 的完整解决方案。

## 功能特性

- 基于 `ubuntu:24.04` 构建 OpenClaw 容器镜像
- 默认通过 BT Panel（宝塔面板）管理服务，端口 `7860`
- OpenClaw Gateway 运行在独立端口 `18789`（默认）
- 默认使用第三方 OpenAI 兼容接口（`base_url + api_key`），通过环境变量注入
- OpenClaw 配置和工作目录存储在 `/root/.openclaw`
- 启动时自动从 Hugging Face Dataset 恢复状态
- 通过 `cron` 定时备份 OpenClaw 数据到 Hugging Face Dataset
- 增量备份 + 动态备份策略 + AES-256-CBC 加密 + 大文件分卷
- 备份看门狗（兜底保障，cron 失效时自动触发备份）
- SSH 服务自动守护（看门狗监控自愈 + 自动生成主机密钥）
- CCMR（Claude Code Model Router）支持，自动配置 10 个平台 API Key
- 多数据集恢复支持（可从不同 Dataset 恢复）
- 预装工具：`python3`、`uv`、`vim`、`neovim`、`chromium`（Chrome for Testing）、`gh`、`hf`、`opencode`、`codex`、`claude`（Claude Code CLI）、`@larksuite/cli`、`sshx`
- 内置 DDNS-GO，支持动态 DNS 更新（非关键功能，安装失败不影响构建）

## 项目结构

- `Dockerfile`: Space 运行时镜像
- `scripts/openclaw-entrypoint.sh`: 主启动流程（恢复、配置生成、cron 设置、gateway 启动）
- `scripts/hf-entrypoint.sh`: HF Spaces 容器入口（PID 1，管理 supervisord + SSH + PM2 + BT Panel）
- `scripts/supervisord.conf`: Supervisord 配置，管理 cron、backup-watchdog、openclaw-gateway、ccmr-gateway
- `openclaw_hf/backup.py`: 备份/恢复实现（全量/增量、加密、分卷、动态策略、断点续传）
- `scripts/openclaw-backup-cron.sh`: Cron 备份任务入口
- `scripts/openclaw-backup-watchdog.sh`: 备份看门狗，兜底保障自动触发备份
- `scripts/openclaw-backup-health.sh`: 备份健康检查与自动修复
- `scripts/openclaw-restore.sh`: 启动恢复入口
- `scripts/openclaw-gateway-ctl`: Gateway 进程管理（start/stop/restart/reload）
- `scripts/openclaw-env-sync.sh`: 从 HF API 同步环境变量
- `scripts/update-env-from-secrets.sh`: 从 HF API 获取最新环境变量
- `scripts/bt_install_panel_custom.sh`: BT Panel 安装脚本
- `scripts/bootstrap-hf.sh`: 交互式引导脚本（macOS/Linux）
- `scripts/bootstrap-hf.ps1`: 交互式引导脚本（Windows PowerShell）
- `scripts/rebuild-space.sh`: 强制推送最新代码到 Space 并触发重建
- `scripts/delete-backups.sh`: 批量清理 Dataset 中的旧备份
- `scripts/delete-hf.py`: HF 资源删除工具（Space/Dataset/文件/存储）
- `scripts/find-largest-backup.py`: 查找 Dataset 中最佳备份
- `scripts/ssh_service_watchdog.sh`: SSH 服务看门狗（进程监控 + 自动恢复）
- `scripts/check_ssh_health.sh`: SSH 健康检查脚本（Docker HEALTHCHECK 使用）
- `scripts/ssh-agent-autostart.sh`: SSH Agent 自动启动和加载密钥
- `scripts/optimize_ssh.sh`: SSH 配置优化
- `scripts/save-env.sh`: 保存环境变量到 `/etc/profile.d`
- `scripts/hf-storage.sh` / `scripts/hf-storage.py`: HuggingFace 公共存储工具
- `scripts/ccmr-setup.sh`: CCMR 配置生成脚本
- `scripts/ccmr-wrapper.sh`: CCMR Supervisor 启动包装（文件热加载 + 崩溃恢复）
- `scripts/server.js`: PID 1 存活 HTTP 服务
- `pm2/ecosystem.config.js`: PM2 配置文件（可选扩展）
- `tests/test_backup.py`: 备份模块单元测试
- `tests/test_entrypoint_config.py`: Gateway 配置生成行为单元测试

## 必填变量（Space Settings）

在 Hugging Face Space 的 `Settings -> Variables and secrets` 中配置：

- 变量: `OPENCLAW_BACKUP_DATASET_REPO`: 备份目标 Dataset，格式 `username/dataset-name`
- 密钥: `HF_TOKEN`: 用于向 Dataset 写入备份（必须对该 Dataset 有写权限）
- 密钥: `OPENCLAW_GATEWAY_TOKEN`: Gateway 令牌（建议填写；留空则自动生成 32 位随机值）
- 密钥: `OPENCLAW_GATEWAY_PASSWORD`: Gateway 密码（可选；留空则自动生成 16 位随机值）

使用 `./scripts/bootstrap-hf.sh` 或 `./scripts/bootstrap-hf.ps1` 时，这些值会自动配置到目标 Space。

## BT Panel 变量

- `BT_PANEL_PORT`（默认: `7860`）: BT Panel 监听端口
- `BT_PANEL_USERNAME`（默认: `btadmin`）: BT Panel 用户名，**必须以小写字母开头，只能包含小写字母和数字，长度 3-32 位**
- `BT_PANEL_PASSWORD`: BT Panel 密码，留空则自动生成
- `BT_PANEL_SAFE_PATH`: BT Panel 安全入口路径（默认: `lauer3912`）
- `BT_PANEL_TIMEZONE`（默认: `Asia/Shanghai`）: BT Panel 时区

## SSH 服务

容器内置 SSH 服务守护体系，确保 SSH 持续可用：

- **自动启动**: 入口点自动生成主机密钥、清理残留 PID、启动 sshd
- **SSH 看门狗** (`ssh_service_watchdog.sh`): 每 30 秒监控 sshd 进程，异常时自动恢复
- **多级修复**: 配置损坏→使用备份配置→生成最小配置→自动重装 openssh-server
- **指数退避**: 连续失败时逐步增加等待时间，避免频繁重试
- **健康检查** (`check_ssh_health.sh`): 配合 Docker HEALTHCHECK 使用
- **SSH Agent 自动加载**: 自动启动 ssh-agent 并加载 `/root/.ssh/` 下的私钥
- **ROOT 密码**: 通过 `ROOT_PASSWORD` 环境变量设置

## CCMR（Claude Code Model Router）

集成 CCMR 网关，通过 Supervisor 管理，支持热加载：

- **自动配置**: 设置 `CCMR_*_API_KEY` 环境变量即可启用
- **10 个 API Key 支持**: DeepSeek、通义千问、Kimi、智谱 GLM、MiniMax（CN/Global）、MiMo（SGP/CN/AMS/PAYG）
- **文件热加载**: 编辑 `/root/.env.d/ccmr.env` 后立即生效，无需重启
- **崩溃恢复**: Supervisor 自动重启 CCMR 进程

## 可选 LLM 变量（全有或全无）

只有在需要 OpenClaw 预配置自定义第三方模型时才设置这三个：

- 变量: `OPENCLAW_LLM_BASE_URL`: 第三方 base URL（如 OpenAI 兼容的 `/v1`）
- 变量: `OPENCLAW_LLM_MODEL`: 第三方模型 ID
- 密钥: `OPENCLAW_LLM_API_KEY`: 第三方 API key

三者任一缺失则跳过自定义模型生成，此时仍可在容器内通过 `sshx` 配置 LLM。

## 常用可选变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `OPENCLAW_VERSION` | `latest` | OpenClaw 版本，用于 Docker 安装步骤 |
| `OPENCLAW_GATEWAY_PORT` | `18789` | Gateway 监听端口（避免与 BT Panel 的 7860 冲突） |
| `OPENCLAW_GATEWAY_BIND` | `lan` | Gateway 绑定方式（`lan`/`local`） |
| `OPENCLAW_STATE_DIR` | `/root/.openclaw` | OpenClaw 状态目录 |
| `OPENCLAW_USER` | `root` | Gateway 和 cron 任务的运行时用户 |
| `OPENCLAW_GROUP` | `root` | 运行时用户组 |
| `OPENCLAW_CONFIG_PATH` | `/root/.openclaw/openclaw.json` | Gateway 配置文件路径 |
| `OPENCLAW_WORKSPACE_DIR` | `/root/.openclaw/workspace` | 工作目录 |
| `OPENCLAW_BACKUP_CRON` | `*/10 * * * *` | 备份 cron 表达式（默认每 10 分钟） |
| `OPENCLAW_BACKUP_SOURCE_DIR` | `/root/.openclaw` | 备份/恢复基础目录 |
| `OPENCLAW_BACKUP_ROOT_*_DIR` | 各有默认值 | 额外备份目录（config、codex、claude、agents、ssh、npm、lark-cli） |
| `OPENCLAW_BACKUP_PATH_PREFIX` | `backups` | 备份路径前缀 |
| `OPENCLAW_BACKUP_KEEP_COUNT` | `24` | 保留的最新备份数量 |
| `OPENCLAW_BACKUP_ENCRYPTION_ENABLED` | `false` | 启用 AES-256-CBC 加密备份 |
| `OPENCLAW_BACKUP_SPLIT_SIZE` | `500M` | 大文件分卷大小 |
| `OPENCLAW_INCREMENTAL_BACKUP` | `true` | 启用增量备份 |
| `OPENCLAW_DYNAMIC_BACKUP` | `true` | 启用动态备份策略 |
| `OPENCLAW_FULL_BACKUP_INTERVAL_HOURS` | `1` | 强制全量备份间隔 |
| `OPENCLAW_MAX_INCREMENTAL_BACKUPS` | `15` | 增量备份次数上限 |
| `OPENCLAW_RESTORE_TIMEOUT` | `5400` | 恢复超时（秒，默认 90 分钟） |
| `WATCHDOG_INTERVAL` | `600` | 备份看门狗检查间隔（秒） |
| `MAX_BACKUP_AGE_MINUTES` | `30` | 备份最大间隔（分钟） |
| `FORCE_BACKUP_INTERVAL` | `14400` | 强制备份间隔（秒） |
| `OPENCLAW_SSHX_AUTO_START` | `false` | 设为 `true` 启动时自动后台运行 `sshx` |
| `OPENCLAW_GATEWAY_AUTH_MODE` | `token` | 认证模式（`token`/`password`） |
| `OPENCLAW_GATEWAY_CONTROLUI_ALLOW_INSECURE_AUTH` | `false` | 允许不安全认证 |
| `OPENCLAW_GATEWAY_CONTROLUI_DANGEROUSLY_DISABLE_DEVICE_AUTH` | `false` | 禁用设备配对（**强烈不建议在公网开启**） |
| `ROOT_PASSWORD` | `lauer3912` | SSH root 用户密码 |
| `CCMR_ENABLED` | `false` | 启用 Claude Code Model Router |
| `CCMR_PORT` | `8080` | CCMR 网关端口 |

## 快速部署

从仓库根目录运行交互式引导脚本：

```bash
./scripts/bootstrap-hf.sh
```

```powershell
powershell -ExecutionPolicy ByPass -File .\scripts\bootstrap-hf.ps1
```

`bootstrap-hf.sh` / `bootstrap-hf.ps1` 会执行以下操作：

1. 检查/安装 `hf` CLI
2. 解析 HF 认证状态（未登录则提示输入 `HF_TOKEN` 并登录；已登录则询问是否使用当前用户）
3. 询问 `space_name`、`dataset_name`、`OPENCLAW_VERSION`、Gateway 令牌/密码及可选 LLM 配置
4. 自动生成 `OPENCLAW_GATEWAY_TOKEN`（32 位）和 `OPENCLAW_GATEWAY_PASSWORD`（16 位）
5. 创建私有 Space + Dataset 并上传仓库
6. 自动配置 Space 的 `Variables and secrets`
7. 显示部署设置并要求确认
8. 输出 Hugging Face Space 页面地址、应用地址和 `/healthz` 健康检查地址

如自动生成了令牌/密码，脚本结束时会自动显示。

## Hugging Face Space 保活策略

Space 保活策略取决于硬件套餐：

- 免费 `cpu-basic`：Space 在不活跃后进入休眠（约 48 小时），无法配置为永久运行
- 付费硬件：Space 默认持续运行。在 `Settings -> Hardware` 中将 `Sleep time` 设为 `Never` 可实现真正的 24/7 可用性
- 付费硬件节能模式：设置自定义 `Sleep time`（如 `3600` 秒），实现自动休眠和自动唤醒

Space URL 构成：

- Space Repo ID 格式: `<owner>/<space_name>`（示例: `username/openclaw-hf`）
- 公开运行时地址: `https://<owner>-<space_name>.hf.space`
- 健康检查地址: `https://<owner>-<space_name>.hf.space/healthz`

定时健康检查保持活跃：

```bash
*/12 * * * * HF_TOKEN=hf_xxx /path/to/repo/scripts/check-space-health.sh username/openclaw-hf >/dev/null || true
```

注意：
- 私有 Space 的 `https://<owner>-<space_name>.hf.space/healthz` 返回 Hub 404，这是正常的访问控制行为
- 私有 Space 请求需要包含 `Authorization: Bearer <HF_TOKEN>`

## 备份/恢复流程

### 恢复流程

**启动时从 Dataset 自动恢复**，容器重启或重建时必定执行：

- `openclaw-state` -> `OPENCLAW_BACKUP_SOURCE_DIR`（默认 `/root/.openclaw`）
- `root-config` -> `OPENCLAW_BACKUP_ROOT_CONFIG_DIR`（默认 `/root/.config`）
- `root-codex` -> `OPENCLAW_BACKUP_ROOT_CODEX_DIR`（默认 `/root/.codex`）
- `root-claude` -> `OPENCLAW_BACKUP_ROOT_CLAUDE_DIR`（默认 `/root/.claude`）
- `root-agents` -> `OPENCLAW_BACKUP_ROOT_AGENTS_DIR`（默认 `/root/.agents`）
- `root-ssh` -> `OPENCLAW_BACKUP_ROOT_SSH_DIR`（默认 `/root/.ssh`）
- `root-env` -> `OPENCLAW_BACKUP_ROOT_ENV_DIR`（默认 `/root/.env.d`）
- `root-npm` -> `OPENCLAW_BACKUP_ROOT_NPM_DIR`（默认 `/root/.npm`）
- `root-lark-cli` -> `OPENCLAW_BACKUP_ROOT_LARK_CLI_DIR`（默认 `/root/.lark-cli`）

支持多数据集恢复：设置 `OPENCLAW_RESTORE_DATASET_REPO` 可以从不同 Dataset 恢复。

### 备份流程

- **定时备份**：根据 `OPENCLAW_BACKUP_CRON`（默认每 10 分钟）执行
- **增量备份**（默认开启）：全量备份后只备份变化文件，大幅减少数据量
- **动态备份策略**（默认开启）：根据文件大小和变化率自动调整压缩级别和分卷策略
- **手动强制全备份**：`python3 backup.py backup --force-full` 可跳过增量检查强制执行全量备份
- **AES-256-CBC 加密**：可选开启，加密后的备份可安全存储在公开 Dataset
- **大文件分卷**：默认 500MB 分卷，避免单文件过大导致上传失败
- **断点续传**：上传过程中创建 checkpoint 文件，中断后可恢复
- **关机备份**：容器收到停止信号时，执行最后一次备份后再退出
- **保留策略**：上传后只保留最新的 `OPENCLAW_BACKUP_KEEP_COUNT`（默认 24 个）带时间戳的备份归档，自动删除更旧的

### 备份看门狗

`openclaw-backup-watchdog.sh` 作为备份系统的**兜底保障**：

- 即使 cron 失效，看门狗也会在超过 `MAX_BACKUP_AGE_MINUTES`（默认 30 分钟）无备份时自动触发
- 每 `FORCE_BACKUP_INTERVAL`（默认 4 小时）强制执行一次备份
- 使用文件锁防止并发执行
- 连续失败时自动退避

## 在容器内使用 sshx

`sshx` 已预装在镜像中。

1. 通过环境变量自动启动：
   ```bash
   OPENCLAW_SSHX_AUTO_START=true
   ```
   启用后入口脚本会在后台启动 `sshx`，输出直接发送到容器 stdout/stderr

2. 在容器内手动启动：
   ```bash
   sshx
   ```

3. 通过 OpenClaw 终端/工具启动：
   ```bash
   nohup sshx >/proc/1/fd/1 2>/proc/1/fd/2 &
   ```

4. 使用完毕后及时关闭：
   ```bash
   pgrep -fa sshx
   pkill -TERM -f '(^|/)sshx($| )'
   ```

## 本地测试

```bash
python3 -m unittest discover -s tests -p 'test_*.py'
```

## CI/CD

向 `main` 分支提交 Pull Request 后，GitHub Actions CI 会自动运行（`.github/workflows/pr-ci.yml`）：
- 单元测试：`python3 -m unittest discover -s tests -p 'test_*.py'`
- Docker 镜像构建：`docker build`（通过 Buildx），使用 `OPENCLAW_VERSION=latest`

## 架构说明

容器启动顺序（`hf-entrypoint.sh` 作为 PID 1）：

```
PID 1 (node hf-server.js)
├── supervisord (后台)
│   ├── cron
│   ├── backup-watchdog
│   ├── openclaw-gateway (via openclaw-entrypoint.sh)
│   │   └── openclaw (gateway 进程管理器)
│   └── ccmr-gateway (via ccmr-wrapper.sh, 启用时)
├── sshd
├── ssh_service_watchdog.sh (SSH 看门狗)
├── PM2 (可选，ecosystem.config.js 有配置时)
└── BT Panel
```

进程管理使用 **Supervisord** 管理后台服务，原因：
- Supervisord 是为"进程管理者"设计的，适合 PID 1 下运行
- 信号传递正确，SIGTERM 能正确传递给子进程
- 相比 PM2 更轻量，职责单一

关键启动步骤：
1. `supervisord` 后台启动，管理 cron/backup-watchdog/openclaw-gateway/ccmr-gateway
2. 生成 SSH 主机密钥，启动 sshd + SSH 看门狗
3. 等待 openclaw-gateway 完成备份恢复
4. 可选启动 PM2 管理附加进程
5. 启动 BT Panel
6. `node hf-server.js` 作为 PID 1 前台进程接管容器生命周期

## License

MIT. See `LICENSE`.