DEPLOY_GUIDE_zh.md

# 用 Hugging Face Spaces 部署 OpenClaw（含自动备份与恢复）

> **来源**: [tenfy's blog - 用 Hugging Face Spaces 部署 OpenClaw（含自动备份与恢复）](https://tenfy.cn/posts/openclaw-hf-space-deploy/)（经本项目定制改编）
>
> **原文作者**: tenfyzhong（[https://tenfy.cn](https://tenfy.cn)）
>
> **改编作者**: ClawCopilot Team（[https://github.com/ClawCopilot/Openclaw-Hf-Docker](https://github.com/ClawCopilot/Openclaw-Hf-Docker)）
>
> **原文日期**: 2026-03-25

---

## 这个方案解决了什么问题

本项目在 tenfy's `openclaw-hf` 基础上，引入 **BT Panel（宝塔面板）** 作为 PID 1，提供更易用的 Web 管理界面：

- 基于 `ubuntu:24.04` 构建 OpenClaw 容器镜像
- **BT Panel（宝塔面板）** 作为容器 PID 1，监听端口 `7860`（Hugging Face Space 默认端口），提供 Web 管理界面
- **OpenClaw Gateway** 运行在独立端口 `18789`（默认）
- 支持通过环境变量预置第三方 OpenAI 兼容模型（`base_url + api_key`）
- OpenClaw 配置和工作目录存储在 `/root/.openclaw`
- 启动时自动从 HF Dataset 恢复最近备份
- 通过 `cron` 定时备份到 HF Dataset
- 通过 **Supervisord** 管理 `cron` 和 `openclaw-gateway` 进程
- 镜像内预装 `vim`、`opencode`、`codex`、`claude`、`sshx`，方便容器内排障与交互
- 内置 DDNS-GO，支持动态 DNS 更新（非关键功能，安装失败不影响构建）

---

## 容器架构

```
PID 1 (bt-panel)
└── /usr/local/bin/hf-entrypoint.sh
    ├── /usr/bin/supervisord
    │   ├── cron（定时备份任务）
    │   └── openclaw-gateway（OpenClaw Gateway，端口 18789）
    └── node hf-server.js（容器健康检查）
```

- **BT Panel**：端口 `7860`，Web 管理界面
- **OpenClaw Gateway**：端口 `18789`，AI Gateway API
- **Supervisord**：进程管理器，同时管理 `cron` 和 `openclaw-gateway`
- **健康检查**：`curl http://localhost:7860`，由 Hugging Face 平台调用

---

## 一、先注册 Hugging Face 并生成 HF_TOKEN

如果你还没有 Hugging Face 账号，先去注册：[https://huggingface.co/join](https://huggingface.co/join)

账号准备好后，按下面步骤创建 token（用于脚本配置备份与 Space）：

1. 打开 Hugging Face Token 页面：[https://huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)
2. 创建一个新 token（建议命名为 `deploy-openclaw`）
3. 授予所需权限（需要有创建 Space 和写 Dataset 的权限）
4. 复制 token（形如 `hf_xxx...`）

本地可先登录并校验：

```bash
hf auth login
hf auth whoami
```

`bootstrap-hf.sh` 提示 `HF_TOKEN for backup dataset` 时：
- 可以直接粘贴新建 token
- 也可以留空，让脚本复用当前 `hf auth login` 的本地凭证

---

## 二、一键部署（推荐）

仓库已提供交互式脚本，建议优先走脚本，不要手搓流程。

### 1. 克隆仓库

```bash
git clone https://github.com/ClawCopilot/Openclaw-Hf-Docker.git
cd Openclaw-Hf-Docker
```

### 2. 运行引导脚本

macOS / Linux：

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

Windows PowerShell：

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

### 3. 脚本会自动完成

- 检查并安装 `hf` CLI（如缺失）
- 检查 Hugging Face 登录状态（需要时触发 `hf auth login`）
- 询问并确认部署参数（包含一次最终 `Proceed with these settings?` 确认）
- 询问 BT Panel 端口、用户名和密码
- 创建私有 Space 与私有备份 Dataset，并上传当前仓库到 Space
- 自动写入 Variables / Secrets（含备份、网关凭据、BT Panel 配置等）
- 默认写入安全相关变量：
  - `OPENCLAW_GATEWAY_CONTROLUI_ALLOW_INSECURE_AUTH=false`
  - `OPENCLAW_GATEWAY_CONTROLUI_DANGEROUSLY_DISABLE_DEVICE_AUTH=false`

### 4. BT Panel 用户名规范

**必须满足以下条件**：
- 以小写字母开头
- 只能包含小写字母和数字
- 长度 3-32 位

例如：`btadmin`、`mypanel123`、`openclawspace`

---

## 三、使用 Agent 自动部署

适合不想手动点配置的用户。可以直接发给 AI Agent：

```
Please deploy OpenClaw to Hugging Face by strictly following the deployment skill in https://github.com/tenfyzhong/openclaw-hf/blob/main/SKILL.md
```

Agent 通常会做这些事：

1. 先检查依赖（`git`、`hf`、`python3`、`huggingface_hub`）
2. 按固定顺序向你收集部署参数
3. 调用 `bootstrap-hf.sh` / `bootstrap-hf.ps1` 执行部署
4. 回传 Space / Dataset / App / Health 地址与版本信息
5. 如果网关凭据是自动生成的，也会一并回传

如果你希望一次性把参数给全，可以发这个模板给 Agent：

```
space_name: openclaw-hf
dataset_name: openclaw-hf-backup
openclaw_version: latest
gateway_token: <留空自动生成或手动填写>
gateway_password: <留空自动生成或手动填写>
hf_token: <你的 HF_TOKEN，或留空复用本地登录>
configure_custom_llm: no
openclaw_sshx_auto_start: true
bt_panel_port: 7860
bt_panel_username: btadmin
bt_panel_password: <留空自动生成或手动填写>
proceed_with_settings: yes
```

---

## 四、部署前准备

脚本依赖以下命令：

```bash
git --version
hf version
python3 --version
```

还需要 Python 包：

```bash
python3 -c "import huggingface_hub" >/dev/null 2>&1 || \
  python3 -m pip install --user 'huggingface_hub[cli]'
```

---

## 五、关键变量与密钥

在 Space 的 `Settings -> Variables and secrets` 中，至少要有：

- 变量: `OPENCLAW_BACKUP_DATASET_REPO`（格式：`username/dataset-name`）
- 密钥: `HF_TOKEN`（需要对备份 Dataset 有写权限）
- 密钥: `OPENCLAW_GATEWAY_TOKEN`（推荐）
- 密钥: `OPENCLAW_GATEWAY_PASSWORD`（可选）
- 变量: `BT_PANEL_PORT`（默认 `7860`）
- 变量: `BT_PANEL_USERNAME`（默认 `btadmin`）
- 密钥: `BT_PANEL_PASSWORD`（BT Panel 密码）

如果你使用 `bootstrap-hf.sh` / `bootstrap-hf.ps1`，以上会自动配置。

### 可选：预置 LLM（三项必须同时提供）

- `OPENCLAW_LLM_BASE_URL`
- `OPENCLAW_LLM_MODEL`
- `OPENCLAW_LLM_API_KEY`

只填其中 1-2 项不会生效，入口脚本会跳过模型预配置。

### 常见可选变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `OPENCLAW_VERSION` | `latest` | OpenClaw 版本 |
| `OPENCLAW_BACKUP_CRON` | `*/30 * * * *` | 备份周期（默认每 30 分钟） |
| `OPENCLAW_BACKUP_KEEP_COUNT` | `48` | 保留最新备份数量 |
| `OPENCLAW_SSHX_AUTO_START` | `false` | 设为 `true` 自动启动 sshx |
| `OPENCLAW_GATEWAY_PORT` | `18789` | Gateway 监听端口 |
| `BT_PANEL_PORT` | `7860` | BT Panel 监听端口 |
| `BT_PANEL_USERNAME` | `btadmin` | BT Panel 用户名（小写字母开头） |
| `BT_PANEL_PASSWORD` | 自动生成 | BT Panel 密码 |

---

## 六、脚本会问哪些问题

按流程，主要输入如下：

1. `space_name`（默认 `openclaw-hf`）
2. `dataset_name`（默认 `<space_name>-backup`）
3. `OPENCLAW_VERSION`（默认自动探测最新版本）
4. `OPENCLAW_GATEWAY_TOKEN`（可留空自动生成 32 位随机值）
5. `OPENCLAW_GATEWAY_PASSWORD`（可留空自动生成 16 位随机值）
6. `HF_TOKEN`（可留空，复用本地已登录 token）
7. 是否立即配置 LLM（三项全填才生效）
8. 如果不配 LLM，是否启用 `OPENCLAW_SSHX_AUTO_START`
9. **BT Panel 端口**（默认 `7860`）
10. **BT Panel 用户名**（必须以小写字母开头，只能包含小写字母和数字，长度 3-32 位）
11. **BT Panel 密码**（可留空自动生成）
12. 最终确认：`Proceed with these settings?`（选 `no` 会退出，不做远端变更）

如果 token/password 由脚本自动生成，会在结束时打印出来，请及时保存。

---

## 七、部署完成后如何验证

假设 Space repo 是 `<owner>/<space_name>`，可用地址如下：

| 服务 | 地址 |
|------|------|
| BT Panel 管理界面 | `https://<owner>-<space_name>.hf.space:7860` |
| BT Panel 健康检查 | `https://<owner>-<space_name>.hf.space` |
| OpenClaw Gateway | `https://<owner>-<space_name>.hf.space:18789` |
| Space 页面 | `https://huggingface.co/spaces/<owner>/<space_name>` |

例如：

```bash
OPENCLAW_HF_SPACE_ID="yourname/openclaw-hf"
SPACE_HOST="${OPENCLAW_HF_SPACE_ID/\//-}.hf.space"
echo "BT Panel: https://${SPACE_HOST}:7860"
echo "Gateway:  https://${SPACE_HOST}:18789"
```

> **注意**：部分网络环境下直接访问 `:18789` 端口可能受限。BT Panel 管理界面（7860）是主要访问入口。

---

## 八、BT Panel 使用说明

### 登录 BT Panel

1. 部署完成后，等待容器启动（约 2-5 分钟）
2. 访问 `https://<owner>-<space_name>.hf.space:7860`
3. 使用部署时设置的 `BT_PANEL_USERNAME` 和 `BT_PANEL_PASSWORD` 登录

> 首次登录可能需要等待 BT Panel 服务完全启动，如果页面无法访问，请稍后再试。

### BT Panel 安全建议

- 部署完成后，建议在 `Settings -> Variables and secrets` 中修改 `BT_PANEL_PASSWORD`
- 避免在公网暴露 BT Panel 管理界面
- `BT_PANEL_USERNAME` 必须符合规范：以小写字母开头，只能包含小写字母和数字

---

## 九、如何进行 OpenClaw 首次配置

1. 打开 Hugging Face Space 页面，进入容器日志，找到 `sshx` 输出的临时访问链接
2. 在浏览器打开该链接进入容器 shell，执行 `openclaw onboard` 按引导完成配置
3. onboarding 过程中 OpenClaw 可能重启，`sshx` 链接也可能变化；若当前链接失效，回到日志获取新链接继续执行
4. 官方向导可参考：[https://docs.openclaw.ai/start/wizard](https://docs.openclaw.ai/start/wizard)
5. 配置完成后，记得回到 `Settings -> Variables and secrets`，将 `OPENCLAW_SSHX_AUTO_START` 改为 `false`（或删除该变量），然后重启 Space，把 `sshx` 关闭

如果你修改了 OpenClaw 配置并希望立即生效，可以重启对应进程（示例）：

```bash
ps -ef | grep 'openclaw-gateway' | grep -v 'grep' | awk '{print $2}' | xargs -I{} kill {}
```

---

## 十、备份与恢复机制

本项目的数据生命周期如下：

- **启动恢复**：容器启动时从 Dataset 获取 `latest-backup.json` 来定位最新备份并恢复
- **定时备份**：根据 `OPENCLAW_BACKUP_CRON` 周期上传（默认每 30 分钟）
- **退出兜底**：容器收到停止信号时再做一次最终备份
- **产物包含**：
  - `backups/openclaw-backup-<timestamp>.tar.gz`
  - `latest-backup.json`
- **保留策略**：只保留最近 `OPENCLAW_BACKUP_KEEP_COUNT` 个时间戳归档（默认 `48`）

---

## 十一、Keep-Alive 与 24/7 运行建议

- 免费 `cpu-basic` 会休眠（当前一般约 48 小时无访问后）
- 严格 24/7 需要付费硬件，并把 `Sleep time` 设为 `Never`
- 私有 Space 做健康检查必须带 `Authorization: Bearer <HF_TOKEN>`，否则会看到 404（正常权限行为）

如果你只是减少冷启动概率，可以定时请求 BT Panel 健康检查地址；在免费层这不是官方保证的常驻方案。

### 使用 cron-job.org 做保活

如果你不想自己维护定时任务，可以用 [https://cron-job.org/](https://cron-job.org/)。

根据其官方 FAQ（[https://cron-job.org/faq/](https://cron-job.org/faq/)），支持自定义 Header、HTTPS，以及最高每分钟一次调用。对 OpenClaw Space 来说，每 10-15 分钟 ping 一次通常就够。

#### 1. 创建任务

1. 打开 [https://cron-job.org/](https://cron-job.org/) 并注册/登录（控制台在 `console.cron-job.org`）
2. 新建 HTTP cron job
3. URL 填：`https://<owner>-<space_name>.hf.space`（BT Panel 健康检查）
4. Method 选 `GET`
5. 调度建议每 10-15 分钟一次

#### 2. 私有 Space 添加 Header

```
Authorization: Bearer <HF_TOKEN>
```

建议单独创建一个仅用于保活的低权限 token，不要复用高权限备份 token。

#### 3. 先做 Test Run 再开告警

创建任务后先手动测试一次，再启用失败通知（邮件等），方便第一时间发现 Space 不可用或 token 过期。

---

## 十二、sshx 用法（可选）

镜像已预装 `sshx`（以及 `vim`、`opencode`、`codex`、`claude`）。

### 1. 自动启动（环境变量）

```bash
OPENCLAW_SSHX_AUTO_START=true
```

### 2. 容器内手动启动

```bash
sshx
```

### 3. 让 OpenClaw 终端后台启动

```bash
nohup sshx >/proc/1/fd/1 2>/proc/1/fd/2 &
```

后续如果临时需要 `sshx`，也可以通过 IM 让 OpenClaw 启动一个；使用完成后，记得再通过 IM 让 OpenClaw 把 `sshx` 关掉。

### 使用结束后建议及时清理

```bash
pgrep -fa sshx
pkill -TERM -f '(^|/)sshx($| )'
```

---

## 十三、进程管理说明

本项目使用 **Supervisord** 管理进程，而非 PM2：

```
PID 1 (bt-panel)
└── supervisord
    ├── cron
    └── openclaw-gateway
```

- **Supervisord**：作为 bt-panel 的子进程，被正确管理
- **cron**：定时备份任务（每 30 分钟执行一次）
- **openclaw-gateway**：OpenClaw Gateway 服务，监听端口 18789
- **PM2**：已从本项目中移除，不再用于管理 Gateway

### 查看进程状态

容器内执行：

```bash
supervisorctl status
```

### 查看日志

```bash
# supervisord 日志
tail -f /var/log/hf-entrypoint/supervisord-stdout.log

# cron 日志
tail -f /var/log/hf-entrypoint/cron-stdout.log

# openclaw-gateway 日志
tail -f /var/log/hf-entrypoint/openclaw-gateway-stdout.log
```

---

## 十四、总结

如果你的目标是"在 Hugging Face 上快速跑起来一个可恢复的 OpenClaw 实例"，本项目已经覆盖了部署、配置、备份、恢复、保活和远程调试这些关键环节，并且通过 BT Panel 提供了更易用的 Web 管理界面。

建议优先使用仓库自带的 `bootstrap-hf` 脚本先跑通默认配置，再按需叠加 LLM、保活和 `sshx` 策略。

---

## 相关链接

- 仓库地址：[https://github.com/ClawCopilot/Openclaw-Hf-Docker](https://github.com/ClawCopilot/Openclaw-Hf-Docker)
- 原文链接：[https://tenfy.cn/posts/openclaw-hf-space-deploy/](https://tenfy.cn/posts/openclaw-hf-space-deploy/)
- OpenClaw 官方向导：[https://docs.openclaw.ai/start/wizard](https://docs.openclaw.ai/start/wizard)
- BT Panel 官网：[https://www.bt.cn/](https://www.bt.cn/)