DEPLOY_GUIDE_zh.md

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

来源: tenfy's blog - 用 Hugging Face Spaces 部署 OpenClaw（含自动备份与恢复）（经本项目定制改编）

原文作者: tenfyzhong（https://tenfy.cn）

改编作者: ClawCopilot Team（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

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

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

本地可先登录并校验：

hf auth login
hf auth whoami

bootstrap-hf.sh 提示 HF_TOKEN for backup dataset 时：

• 可以直接粘贴新建 token
• 也可以留空，让脚本复用当前 hf auth login 的本地凭证

---

二、一键部署（推荐）

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

1. 克隆仓库

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

2. 运行引导脚本

macOS / Linux：

./scripts/bootstrap-hf.sh

Windows 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

---

四、部署前准备

脚本依赖以下命令：

git --version
hf version
python3 --version

还需要 Python 包：

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	24	保留最新备份数量
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>

例如：

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
5. 配置完成后，记得回到 Settings -> Variables and secrets，将 OPENCLAW_SSHX_AUTO_START 改为 false（或删除该变量），然后重启 Space，把 sshx 关闭

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

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 个时间戳归档（默认 24）

---

十一、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/。

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

1. 创建任务

1. 打开 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. 自动启动（环境变量）

OPENCLAW_SSHX_AUTO_START=true

2. 容器内手动启动

sshx

3. 让 OpenClaw 终端后台启动

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

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

使用结束后建议及时清理

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

查看进程状态

容器内执行：

supervisorctl status

查看日志

# 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://tenfy.cn/posts/openclaw-hf-space-deploy/
• OpenClaw 官方向导：https://docs.openclaw.ai/start/wizard
• BT Panel 官网：https://www.bt.cn/