永久免费2C16G VPS 安装部署 OpenClaw 全过程指南 (2026年2月版)

一、 环境准备与核心需求

• 平台​：Hugging Face Spaces (Docker Runtime)
• 可用资源​：2C，16GB内存、100GB存储私有，8TB共享存储
• 模型供应商​：SiliconFlow、
• 持久化需求​：利用 HF Dataset 实现对话记录和配置的增量备份与恢复。
• 安全认证​：通过网关令牌（Gateway Token）进行安全访问。 ## 一、 基础设施准备步骤

1. 创建 Hugging Face Space

1. 登录 Hugging Face。
2. 点击右上角的 + New -> Space​。
3. Space Name: 自定义（如 my-openclaw）。
4. SDK: 选择 Docker​。
5. Template: 选择 Blank​。
6. Privacy: 建议选择 Private（保护你的 Agent 对话和 API 地址）。
7. 点击 Create Space​。创建完成之后，记得修改readme.md文件内容为：

title: Openclaw
emoji: 🐨
colorFrom: pink
colorTo: red
sdk: docker
port: 18789
pinned: false

注意，可以不需要license，有时候选择错了会导致出错。

2. 创建持久化 Dataset

1. 点击右上角的 + New -> Dataset​。
2. Dataset Name: 自定义（如 openclaw-data）。
3. Privacy: 必须选择 Private（因为备份包里含有你的 API Key 和聊天隐私）。
4. 点击 Create Dataset​。

3. 创建 Access Token (写入权限)

1. 点击个人头像 -> Settings -> Access Tokens​。
2. 点击 Create new token​。
3. Name: openclaw-sync。
4. Token Type: 选择 Write（这是关键，Read 权限无法上传备份）。
5. 复制保存这个 hf_… 开头的字符串。 ## 二、 全量环境变量配置表 (Variables & Secrets)

在 Space 的 Settings -> Variables and Secrets 中配置：

二、 系统架构：从部署到持久化的三阶段方案描述

我们将整个实现过程分为三个逻辑阶段，每个阶段解决了不同的技术痛点。

阶段 1：基础容器化与环境适配 (The Foundation)

目标​：在 Hugging Face 的 node:22-slim 镜像上跑通 OpenClaw。

• 功能实现​： 补齐编译链​：安装 build-essential 等工具，解决 Node.js 原生模块（如加密、压缩库）在安装时的编译失败问题。 协议重定向​：通过 Git 配置将 ssh:// 强制转换为 https://，绕过镜像构建时因缺少 SSH Key 导致的依赖拉取中断。 端口对齐​：强制 OpenClaw 监听 7860 端口，通过 Hugging Face 的负载均衡检查。

阶段 2：网关认证与网络穿透 (The Gateway)

目标​：解决反向代理环境下的 disconnected (1008) 和 Unknown model 错误。

• 功能实现​： 信任代理链​：通过在 trustedProxies 中设置 0.0.0.0/0，允许 OpenClaw 接收来自 Hugging Face 内部负载均衡器的请求头，解决“身份无法识别”问题。 硬编码注入​：不依赖 UI 动态配置，而是通过启动脚本在 /root/.openclaw/openclaw.json 中预埋 models.providers 结构。这解决了 OpenClaw 对未知模型 ID 的自动拒绝行为。 锁定 Auth 模式​：显式声明 mode: “token”，避免浏览器在反向代理环境下尝试无效的自动配对，确保 pairing required 错误可以通过手动输入密码或 URL 参数解决。 ## 三、 数据持久化深度解析

1. Space 重启会导致哪些数据丢失？

Hugging Face Spaces 使用的是容器快照技术，每次重启都会回到“出厂设置”。

• 丢弃的数据​：在 /root/.openclaw/sessions 下产生的所有新对话记录、所有在 Web UI 里临时修改的设置、浏览器插件产生的 Cookie 和任务进度。
• 原因​：容器的根文件系统是非持久化的。

2. 哪些数据会持久存储？

• 代码层​：你写在 Dockerfile 里的代码和启动脚本。
• 配置层​：通过脚本硬编码生成的 openclaw.json。
• 备份包​：已经成功通过脚本上传到 Dataset 里的 .tar.gz 压缩包。

3. 为什么要采用“Dataset 备份恢复机制”？

我们没有采用传统的数据库或付费存储，而是选择了 Dataset 方案，主要为了解决以下问题：

• 成本规避​：Hugging Face 的 Persistent Storage（持久化硬盘）通常是按量计费且需要绑定信用卡。Dataset 存储是完全免费的。
• 冷启动恢复​：解决了 Space 闲置自动关机后“失忆”的问题。
• 多端同步​：你可以把这个 Dataset 挂载到任何地方，实现记录的跨平台迁移。
• 安全性​：通过 Dataset 的 Private 属性，确保只有你自己能访问这些敏感数据。 ## 四、 核心 Dockerfile (增量备份增强版)

# 核心镜像选择
FROM node:22-slim

# 1. 基础依赖补全
RUN apt-get update && apt-get install -y --no-install-recommends \
    git openssh-client build-essential python3 python3-pip \
    g++ make ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# 2. 安装 HF 数据交互工具
RUN pip3 install --no-cache-dir huggingface_hub --break-system-packages

# 3. 构建环境与 Git 协议优化
RUN update-ca-certificates && \
    git config --global http.sslVerify false && \
    git config --global url."https://github.com/".insteadOf ssh://[email protected]/

# 4. OpenClaw 核心安装
RUN npm install -g openclaw@latest --unsafe-perm

# 5. 环境变量预设
ENV PORT=7860 \
    OPENCLAW_GATEWAY_MODE=local \
    HOME=/root

# 6. Python 同步引擎 (sync.py)
RUN echo 'import os, sys, tarfile\n\
from huggingface_hub import HfApi, hf_hub_download\n\
from datetime import datetime, timedelta\n\
api = HfApi()\n\
repo_id = os.getenv("HF_DATASET")\n\
token = os.getenv("HF_TOKEN")\n\
def restore():\n\
    try:\n\
        files = api.list_repo_files(repo_id=repo_id, repo_type="dataset", token=token)\n\
        now = datetime.now()\n\
        for i in range(5):\n\
            day = (now - timedelta(days=i)).strftime("%Y-%m-%d")\n\
            name = f"backup_{day}.tar.gz"\n\
            if name in files:\n\
                path = hf_hub_download(repo_id=repo_id, filename=name, repo_type="dataset", token=token)\n\
                with tarfile.open(path, "r:gz") as tar: tar.extractall(path="/root/.openclaw/")\n\
                print(f"Success: Restored from {name}")\n\
                return True\n\
    except Exception as e: print(f"Restore Error: {e}")\n\
def backup():\n\
    try:\n\
        day = datetime.now().strftime("%Y-%m-%d")\n\
        name = f"backup_{day}.tar.gz"\n\
        with tarfile.open(name, "w:gz") as tar:\n\
            if os.path.exists("/root/.openclaw/sessions"): tar.add("/root/.openclaw/sessions", arcname="sessions")\n\
            tar.add("/root/.openclaw/openclaw.json", arcname="openclaw.json")\n\
        api.upload_file(path_or_fileobj=name, path_in_repo=name, repo_id=repo_id, repo_type="dataset", token=token)\n\
        print(f"Backup {name} Success.")\n\
    except Exception as e: print(f"Backup Error: {e}")\n\
if __name__ == "__main__":\n\
    if len(sys.argv) > 1 and sys.argv[1] == "backup": backup()\n\
    else: restore()' > /usr/local/bin/sync.py

# 7. 启动控制逻辑
RUN echo "#!/bin/bash\n\
set -e\n\
mkdir -p /root/.openclaw/sessions\n\
\n\
# 阶段 3: 执行启动前恢复\n\
python3 /usr/local/bin/sync.py restore\n\
\n\
# 处理地址逻辑\n\
CLEAN_BASE=\$(echo \"\$OPENAI_API_BASE\" | sed \"s|/chat/completions||g\" | sed \"s|/v1/|/v1|g\" | sed \"s|/v1\$|/v1|g\")\n\
\n\
# 阶段 2: 生成网关与模型配置\n\
cat > /root/.openclaw/openclaw.json <<EOF\n\
{\n\
  \"models\": {\n\
    \"providers\": {\n\
      \"siliconflow\": {\n\
        \"baseUrl\": \"\$CLEAN_BASE\", \"apiKey\": \"\$OPENAI_API_KEY\", \"api\": \"openai-completions\",\n\
        \"models\": [{ \"id\": \"\$MODEL\", \"name\": \"DeepSeek\", \"contextWindow\": 128000 }]\n\
      }\n\
    }\n\
  },\n\
  \"agents\": { \"defaults\": { \"model\": { \"primary\": \"siliconflow/\$MODEL\" } } },\n\
  \"gateway\": {\n\
    \"mode\": \"local\", \"bind\": \"lan\", \"port\": \$PORT,\n\
    \"trustedProxies\": [\"0.0.0.0/0\", \"10.0.0.0/8\", \"172.16.0.0/12\", \"192.168.0.0/16\"],\n\
    \"auth\": { \"mode\": \"token\", \"token\": \"\$OPENCLAW_GATEWAY_PASSWORD\" },\n\
    \"controlUi\": { \"allowInsecureAuth\": true }\n\
  }\n\
}\n\
EOF\n\
\n\
# 增量备份循环 (每 6 小时)\n\
(while true; do sleep 21600; python3 /usr/local/bin/sync.py backup; done) &\n\
\n\
openclaw doctor --fix\n\
exec openclaw gateway run --port \$PORT\n\
" > /usr/local/bin/start-openclaw && chmod +x /usr/local/bin/start-openclaw

EXPOSE 7860
CMD ["/usr/local/bin/start-openclaw"]

“