README.md

---
title: ClawDBot Gateway on Hugging Face (Docker)
emoji: "🦞"
colorFrom: red
colorTo: yellow
sdk: docker
pinned: false
---

# 🦞 ClawDBot - 免费 AI 助手（支持 Telegram）

**完全免费的 AI 助手，支持网页和 Telegram 双端使用！**

基于 Claude AI 技术，部署在 Hugging Face Space，无需付费 API 即可使用。

## ✨ 特性

- 🌐 **网页控制台** - 在浏览器中直接使用
- 📱 **Telegram Bot** - 随时随地在手机上对话
- 📁 **文件生成** - 自动保存和发送生成的文件
- 🆓 **完全免费** - 使用免费的 AI 模型（Groq/HF）
- ☁️ **云端部署** - 部署在 Hugging Face，无需自己的服务器
- 🔄 **自动同步** - 文件可同步到 HF Dataset 永久保存

## 🚀 快速开始

**5 分钟部署：**查看 [QUICKSTART.md](QUICKSTART.md)

**详细配置：**查看 [SETUP_GUIDE_CN.md](SETUP_GUIDE_CN.md)

**Telegram 配置：**查看 [TELEGRAM_GUIDE.md](TELEGRAM_GUIDE.md)

## 💰 完全免费方案

- ✅ Hugging Face Space（免费）
- ✅ Groq API（每天 14,400 次免费请求）
- ✅ Telegram Bot（完全免费）
- ✅ **总成本：$0/月**

## 📖 文档目录

- [QUICKSTART.md](QUICKSTART.md) - 5 分钟快速部署
- [SETUP_GUIDE_CN.md](SETUP_GUIDE_CN.md) - 完整配置指南
- [TELEGRAM_GUIDE.md](TELEGRAM_GUIDE.md) - Telegram Bot 配置
- [deploy.py](deploy.py) - 一键部署脚本
- [check_config.py](check_config.py) - 配置检查工具

> 注意：请**不要**把任何私密 Token（例如 Hugging Face Token、Groq API Key、Telegram Bot Token 等）提交到 Git 仓库，而是通过 Hugging Face 的 Secrets 或本地环境变量注入。

---

## 1. 本地构建与运行

在 `0126project` 目录下：

```bash
cd /home/luck/xzy/0126project

docker build -t clawdbot-hf .

docker run \
  -p 7860:7860 \
  -e CLAWBOT_GATEWAY_TOKEN="your-gateway-token" \
  --name clawdbot-hf \
  clawdbot-hf
```

然后在浏览器打开：

```text
http://localhost:7860
```

首次启动时，容器会：

- 使用 `npm install -g clawdbot@latest` 安装最新版 ClawDBot
- 在容器内部启动 Gateway（Web UI + WebSocket）
- 监听 `PORT`（默认 7860，对应 Hugging Face Spaces 的默认端口）

如需持久化配置和会话，可以绑定本地目录到容器的 `/data`：

```bash
docker run \
  -p 7860:7860 \
  -e CLAWBOT_GATEWAY_TOKEN="your-gateway-token" \
  -v "$PWD/data:/data" \
  --name clawdbot-hf \
  clawdbot-hf
```

---

## 2. 推送到 Hugging Face Spaces（以 `acpr123` 为例）

1. 在 Hugging Face 网页上创建一个新的 **Space**：
   - Owner：`acpr123`
   - Space 名称：例如 `clawdbot`
   - SDK：选择 **Docker**

2. 在本机初始化 Git 仓库（在 `0126project` 下）：

   ```bash
   cd /home/luck/xzy/0126project
   git init
   git add .
   git commit -m "Initial ClawDBot Docker space"
   ```

3. 将 Hugging Face Space 作为远程仓库添加（URL 示例）：

   ```bash
   git remote add origin https://huggingface.co/spaces/acpr123/clawdbot
   ```

4. 使用你的 Hugging Face 账户凭证（用户名 + Token）推送代码：

   ```bash
   git push -u origin main  # 或 master，视你本地默认分支而定
   ```

   推送时会提示输入用户名和密码：

   - 用户名：`acpr123`
   - 密码：你的 Hugging Face Access Token（形如 `hf_...`）

   > 不要在本仓库的任何文件中明文写入 Token；仅在 Git 推送认证或 HF 控制台的 Secrets 中使用。

5. 推送完成后，Hugging Face 会自动根据 `Dockerfile` 构建镜像并启动 Space。构建完成后，访问 Space 页面即可打开 ClawDBot 控制台。

---

## 3. 在 Hugging Face 配置环境变量 / Secrets

在 Space 的 **Settings → Variables and secrets** 中添加：

- `CLAWDBOT_GATEWAY_TOKEN`（Secret）
  - 用作 Gateway 控制台登录 Token
  - 建议设置为随机长字符串

- 模型相关 API Key（按需）：
  - `ANTHROPIC_API_KEY`
  - `OPENAI_API_KEY`
  - `GOOGLE_API_KEY`（Gemini）
  - 其他你计划使用的模型提供商 Key

在容器内，ClawDBot 会自动读取这些环境变量，无需修改代码。

> 提示：Hugging Face 上设置为 **Secrets** 的变量不会出现在构建日志中，也不会存入仓库。

---

## 4. `.env` 示例（本地开发可选）

如果你想在本地用 `docker run --env-file .env` 的方式启动，可以在本目录下创建 `.env` 文件，例如：

```env
PORT=7860

# ClawDBot Gateway 安全 Token（用于控制台登录）
CLAWDBOT_GATEWAY_TOKEN=your-gateway-token

# 可选：模型提供商配置
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-openai-...
GOOGLE_API_KEY=AIza...
```

> 再次强调：**不要**提交实际的密钥到任何公共仓库。

---

## 5. 目录说明

当前仓库仅包含运行 ClawDBot Gateway 所需的最小 Docker 配置：

- `Dockerfile`：构建使用最新 npm 版本 ClawDBot 的镜像
- `README.md`：本说明文档

ClawDBot 自身的代码和 UI 由 `npm install -g clawdbot@latest` 在镜像构建时自动获取，无需手动拷贝源码。

---

## 6. 后续可扩展方向

- 在 `/data/workspace` 中挂载自定义 `AGENTS.md` / `SOUL.md` / `USER.md` / `MEMORY.md` 等，打造专属 Lobster Personality
- 通过 ClawDBot 控制台配置 WhatsApp / Telegram / Slack / Discord 等消息渠道
- 配置本地模型或其他托管模型，实现多模型路由

如果你需要，我也可以在本目录中再补一份：

- **一页式部署速查表（中文版）**
- 或按 **Windows / macOS / Linux** 分平台的推送与调试说明