Spaces:
Sleeping
Sleeping
| title: OpenClaw | |
| emoji: 🦞 | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: docker | |
| pinned: false | |
| license: apache-2.0 | |
| app_port: 7860 | |
| # OpenClaw on Hugging Face Spaces | |
| 这是一个在 Hugging Face Spaces 免费层上运行的完整 OpenClaw Gateway 实例。 | |
| ## 🔐 安全特性 | |
| ✅ **Gateway Token 保护** - 公开暴露 Gateway 时必须填写网关令牌 | |
| ✅ **WebSocket 直连** - HF 对外端口直接由 OpenClaw Gateway 处理 | |
| ✅ **中转站模型配置** - 支持 OpenAI-compatible API Base URL | |
| ## 资源配置 | |
| - **CPU**: 2 vCPU | |
| - **RAM**: 16 GB | |
| - **存储**: 50 GB + 100 GB Storage Bucket | |
| 完全满足 OpenClaw 运行要求！ | |
| ## 快速开始 | |
| ### 1. 配置环境变量 | |
| 在 Space 的 **Settings > Variables and Secrets** 中添加： | |
| **必需：** | |
| - `LLM_API_KEY`: 你的 LLM API 密钥（Anthropic/OpenAI/Google/OpenRouter） | |
| - `LLM_MODEL`: 模型名称，例如： | |
| - `claude-3-5-sonnet-20241022` (Anthropic) | |
| - `gpt-4o` (OpenAI) | |
| - `gemini-2.0-flash-exp` (Google) | |
| - `LLM_API_BASE_URL`: 中转站 API Base URL（可选，兼容 OpenAI 的中转站通常形如 `https://api.example.com/v1`） | |
| - `OPENCLAW_GATEWAY_TOKEN`: 网关令牌，用于连接 Gateway dashboard / WebSocket | |
| - `LLM_PROVIDER`: LLM 提供方标识（可选，默认 `openclaw-relay`） | |
| **可选：** | |
| - `GATEWAY_TOKEN`: `OPENCLAW_GATEWAY_TOKEN` 的兼容别名 | |
| ### 中转站接口 | |
| 如果你使用 API 中转站，在 Space 里添加： | |
| ```bash | |
| LLM_API_KEY=你的中转站 API Key | |
| LLM_MODEL=中转站支持的模型名 | |
| LLM_API_BASE_URL=https://你的中转站域名/v1 | |
| LLM_PROVIDER=openclaw-relay | |
| OPENCLAW_GATEWAY_TOKEN=你的网关令牌 | |
| ``` | |
| 部署脚本会把这些值写入 OpenClaw 的 `models.providers` 自定义 provider 配置，并导出为 `OPENAI_BASE_URL` / `OPENAI_API_BASE_URL` 等常见 SDK 环境变量。 | |
| ### 2. 启动 Space | |
| 保存环境变量后，Space 会自动重启并启动 OpenClaw。 | |
| ### 3. 访问 | |
| - **Gateway URL**: `https://YOUR_USERNAME-openclaw.hf.space` | |
| - **WebSocket URL**: `wss://YOUR_USERNAME-openclaw.hf.space` | |
| - 打开页面后在“网关令牌”里填入 `OPENCLAW_GATEWAY_TOKEN` | |
| ## 🎨 前端界面 | |
| 访问 Space 时，你会看到 OpenClaw Gateway dashboard。连接时填写 `OPENCLAW_GATEWAY_TOKEN`。 | |
| ## 功能支持 | |
| ✅ **完整功能**: | |
| - AI 对话和决策 | |
| - 工具调用和组合 | |
| - 多步骤工作流 | |
| - Telegram/WhatsApp 集成 | |
| - 持久化存储（配置 Storage Bucket） | |
| - **密码保护访问** | |
| ⚠️ **限制**: | |
| - 48小时无活动后休眠（访问时自动唤醒） | |
| - 浏览器扩展功能受限（无头环境） | |
| - 无本地桌面应用访问 | |
| ## 架构说明 | |
| 本部署使用单端口 Gateway 直连架构： | |
| ``` | |
| 用户请求 → https://your-space.hf.space | |
| ↓ | |
| OpenClaw Gateway (端口 7860, HTTP + WebSocket) | |
| ``` | |
| ## 持久化存储 | |
| 为了保存聊天历史和设置，建议配置 Storage Bucket： | |
| 1. 访问 https://huggingface.co/spaces/buckets | |
| 2. 创建新的 bucket | |
| 3. 在环境变量中添加 `HF_BUCKET_NAME` | |
| ## 故障排除 | |
| 查看 **Logs** 标签页获取详细日志。 | |
| 常见问题： | |
| - **启动失败**: 检查是否设置了 `LLM_API_KEY` | |
| - **API 错误**: 验证 API 密钥是否有效 | |
| - **中转站无响应**: 检查 `LLM_API_BASE_URL` 是否包含 `/v1`，以及模型名是否被中转站支持 | |
| - **无法连接**: 确认 WebSocket URL 是 `wss://YOUR_USERNAME-openclaw.hf.space`，并填写 `OPENCLAW_GATEWAY_TOKEN` | |
| - **提示设备配对**: 本 Space 部署已用网关令牌代替浏览器设备配对；刷新页面后重新填写 `OPENCLAW_GATEWAY_TOKEN` | |
| - **休眠**: 48小时无活动后自动休眠，访问即可唤醒 | |
| ## 安全建议 | |
| 🔒 **必须设置 `OPENCLAW_GATEWAY_TOKEN`**，否则公开 Gateway 不应启动。 | |
| 使用强密码，例如： | |
| ``` | |
| OPENCLAW_GATEWAY_TOKEN=your_strong_gateway_token_here_2026 | |
| ``` | |
| ## 相关链接 | |
| - [OpenClaw 官方文档](https://docs.openclaw.ai/) | |
| - [OpenClaw GitHub](https://github.com/openclaw/openclaw) | |
| - [部署指南](https://blog.laozhang.ai/en/posts/openclaw-installation-deployment-guide) | |
| ## License | |
| Apache 2.0 | |