1. 为什么要在 Hugging Face Space 上跑小龙虾Hugging Face Space 提供免费的 CPU 2核16G 运行环境对于想零成本跑通 AI 工具链的开发者来说这是一个很实在的入口。小龙虾OpenClaw作为一套可自托管的 AI 助手框架本身对资源要求不算高放在 Space 上跑通配置骨架完全可行。但真正动手时很多人会卡在同一个地方环境变量怎么填、config.toml 和 settings.json 怎么写、API Key 和通道怎么统一管理。我试过直接在 Space 里硬编码 Key结果每次改配置都要重新提交仓库调试效率很低。后来把 TaoToken 作为统一 Key/API 通道接进来配置骨架一次写好后面换模型、换通道只改环境变量就行。这篇就按“部署 鉴权 一次可验证调用”的路径把可复制的配置骨架给出来。适合谁看想在 Hugging Face Space 上免费部署 OpenClaw、又不想在 Key 管理上反复折腾的开发者。你需要对 Space 的基本操作有概念比如创建 Space、改文件、看 Logs但不需要提前懂 OpenClaw 的全部细节。核心检索词先明确Hugging Face Space 免费部署小龙虾指的是在 Space 的免费 CPU 实例上运行 OpenClaw并通过统一 API 通道完成鉴权。下面从 TaoToken 的前置准备开始。2. TaoToken 前置准备统一 Key 与 API 通道TaoToken 在这里的角色是统一 Key 和 API 通道。你不需要在 Space 里分别配置多个模型厂商的 Key而是把 TaoToken 的 API 地址和 Key 写进环境变量OpenClaw 通过它去调用后端模型。这样做的直接好处是Space 仓库里不出现任何真实厂商 Key换模型只改一个环境变量。先拿到 API Key。打开 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建后复制 Key形如sk-开头的一串字符。注意这个 Key 只显示一次先存到本地密码管理器。API 通道地址用https://taotoken.net/api这个地址不加 UTM 参数直接作为base_url使用。如果你后续要接 Claude Code 或 Anthropic 风格的接口文档入口在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意Space 的免费实例是公开仓库时环境变量在 Settings 里配置是加密存储的不会出现在代码里。但不要把 Key 写进任何提交到仓库的文件。前置准备清单一个 TaoToken API Key、一个 Hugging Face 账号、一个新建的 SpaceSDK 选 Docker 或 Gradio 均可后面按 Docker 讲。接下来进入可复制配置。3. 可复制配置Space 环境变量与 config.toml/settings.json 骨架这一节是全文重点。配置分三层Space 环境变量、OpenClaw 的 config.toml、以及 settings.json。三层职责不同不要混。3.1 Space 环境变量在 Space 页面进入 Settings → Variables and secrets添加以下 secrets变量名值说明TAOTOKEN_API_KEYsk-你的KeyTaoToken 控制台创建TAOTOKEN_BASE_URLhttps://taotoken.net/api固定通道地址OPENCLAW_MODELgpt-4o-mini按需替换模型名OPENCLAW_PORT7860Space 默认暴露端口这些变量在容器启动时注入OpenClaw 启动脚本读取后写入运行时配置。不要把TAOTOKEN_API_KEY写进config.toml否则一旦仓库公开就泄露了。3.2 config.toml 骨架在 Space 仓库根目录创建config.toml内容如下[server] host 0.0.0.0 port 7860 [model] provider openai-compatible base_url ${TAOTOKEN_BASE_URL} api_key ${TAOTOKEN_API_KEY} model_name ${OPENCLAW_MODEL} timeout 120 [logging] level info关键点是base_url和api_key用${}占位由启动脚本从环境变量替换。这样仓库里只有占位符真实值在 Space Secrets 里。3.3 settings.json 骨架部分 OpenClaw 版本用settings.json管理运行时偏好放在data/settings.json{ auth: { mode: api_key, header: Authorization, prefix: Bearer }, endpoints: { chat: /v1/chat/completions, models: /v1/models }, runtime: { max_tokens: 2048, temperature: 0.7 } }auth段告诉 OpenClaw 用 Bearer 方式带 Keyendpoints段指向 OpenAI 兼容路径。TaoToken 的 API 通道兼容这套路径所以不用改。3.4 启动脚本替换占位符在entrypoint.sh里加一段替换逻辑#!/bin/bash set -e sed -i s|\${TAOTOKEN_BASE_URL}|${TAOTOKEN_BASE_URL}|g config.toml sed -i s|\${TAOTOKEN_API_KEY}|${TAOTOKEN_API_KEY}|g config.toml sed -i s|\${OPENCLAW_MODEL}|${OPENCLAW_MODEL}|g config.toml exec python -m openclaw --config config.tomlsed用|作分隔符避免 URL 里的/冲突。启动后config.toml里就是真实值但仓库里的版本仍是占位符。提示如果你用 Dockerfile把entrypoint.sh设为ENTRYPOINT并确保有执行权限chmod x entrypoint.sh。配置骨架到这里就完整了。下一步验证请求。4. 验证请求一次可跑通的调用配置写完先别急着开前端。用一条最小请求验证鉴权通道是否通。在 Space 的 Logs 或本地终端执行curl -sS https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { model: ${OPENCLAW_MODEL}, messages: [{role: user, content: ping}], max_tokens: 16 }预期返回类似{ id: chatcmpl-xxx, object: chat.completion, choices: [ { index: 0, message: {role: assistant, content: pong}, finish_reason: stop } ] }只要choices[0].message.content有内容说明 Key 和通道都通。如果返回 401检查 Key 是否复制完整返回 404检查base_url是否多了或少了/v1。通道验证通过后再启动 OpenClaw 本体访问https://你的用户名-space空间名称.hf.space前端能打开、发一条消息能收到回复就说明 Space 部署 TaoToken 鉴权一次性跑通了。如果你更想先在对话界面里确认模型行为可以走模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite长期在 Space 上跑编码类任务或 Agent建议看 Coding Plan避免频繁手动换 Keyhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite5. 本篇常见错排查部署过程中最容易踩的坑集中在环境变量、路径和端口三处。下面按报错现象给排查路径。5.1 401 Unauthorized现象curl 或前端返回 401。原因通常是 Key 没注入或注入成了字面量${TAOTOKEN_API_KEY}。排查进 Space Logs看启动脚本有没有执行sed替换再确认 Secrets 里变量名拼写和config.toml里的占位符完全一致大小写敏感。5.2 404 Not Found现象请求打到https://taotoken.net/api返回 404。原因多是base_url末尾路径不对。TaoToken 的通道地址是https://taotoken.net/apiOpenClaw 会在后面拼/v1/chat/completions。如果你在base_url里又加了/v1就会变成/api/v1/v1/...。检查config.toml里base_url只写到/api。5.3 Space 启动后端口不通现象Logs 显示服务已启动但.hf.space打不开。原因通常是监听地址写成了127.0.0.1。Space 要求容器监听0.0.0.0config.toml里host 0.0.0.0不能省。另外确认OPENCLAW_PORT和 Space 默认端口一致Docker Space 默认是 7860。5.4 模型名报错 model not found现象返回model not found。原因是你填的OPENCLAW_MODEL在 TaoToken 通道里不存在。换一个可用模型名或到模型对话页面确认当前可用模型列表。模型名大小写和连字符要完全匹配。5.5 配置文件被覆盖现象重启 Space 后配置回到占位符状态。这是正常的因为仓库里存的就是占位符每次启动由entrypoint.sh重新替换。如果你手动改了容器内文件重启会丢。正确做法是改仓库里的模板不要改运行时文件。注意排查时优先看 Space Logs 的前 50 行启动脚本的报错基本都在那里。不要一上来就改代码。6. 接入文档与后续扩展配置骨架跑通后后续扩展主要围绕两件事换模型和加通道。换模型只改OPENCLAW_MODEL环境变量不用动config.toml。加通道则在 TaoToken 侧管理Space 里始终只认一个base_url和一个 Key。完整的接入参数和字段说明以官方文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你要管理多个 Space 或多个项目的 Key控制台里可以按项目分 Key方便单独吊销https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite接 Claude Code 或 Anthropic 风格接口的场景参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_anthropicutm_campaignrewrite最后给一个实用技巧把config.toml、settings.json、entrypoint.sh三个文件放在仓库根目录Space 每次构建都会重新读取配合 Secrets 就能做到“仓库公开也不泄露 Key”。这套骨架我在多个 Space 上复用改的只是模型名和端口鉴权部分一次写好就不用再动。
