multiuserclaw

MultiUserClaw - 多用户 AI SaaS Hermes Agent 平台

基于 Hermes 改造的轻量级 AI 助手框架，可以快速打造商用 SaaS 平台，支持多租户隔离部署、多平台渠道接入、工具调用、定时任务和 Web 实时通信。

在线体验地址：https://ai.infox-med.com:13080/ （直接注册即可使用） 当前默认内核后端：Hermes Agent

---

📌 版本分支说明

• main 分支：当前主分支，基于hermes 6月底版本，因为hermes比openclaw快很多，所以全面切换为hermes分支
• openclaw 分支：旧主分支（已归档），基于 OpenClaw 2026.5.10
• nanobot014v3 分支：nanobot 的 0.1.4 post v3 版本

---

🎯 核心原理

架构设计：新增 platform 作为控制容器的网关，每个用户单独创建容器进行管理。

Frontend (前端界面) → Platform (平台网关) → Hermes Agent (AI 引擎)

• Frontend：前端页面进行显示，调用 platform 进行交互
• Platform：控制容器管理，调用 hermes agent 进行 AI 交互
• Hermes Agent：基于 Hermes 的 AI Agent 运行时

升级 Hermes：重建 hermes 镜像即可

---

📝 最新更新

main 分支已全面切换为 Hermes Agent，相比之前的 OpenClaw，Hermes 具有更快的启动速度和响应性能。

---

📖 目录

1. 功能特性
2. 界面预览
3. 运行流程概览
4. 多租户部署（Docker Compose）
5. 单用户本地运行
6. 整体架构
7. 核心组件详解
8. 安全设计
9. 前端
10. deploy_copy — 预置 Agent 与技能
11. 文件索引
12. API 调用示例
13. 升级 Hermes
14. 容器端口映射
15. 渠道配置
16. 可选改进建议
17. 相关文档
18. 联系方式

---

✨ 功能特性

本平台是一个功能丰富的多租户 AI 助手平台，支持以下核心功能：

🤖 AI Agent 管理

• 创建、配置和管理多个 AI Agents
• 每个 Agent 独立的对话上下文
• Agent 身份设置（名称、Emoji 图标）
• Agent 详情查看和删除

💬 智能对话

• WebSocket 实时通信
• Markdown 消息渲染（支持代码高亮）
• 斜杠命令自动补全
• 多会话管理
• 语音输入支持
• 文件/图片上传发送

⏰ 定时任务 (Cron Jobs)

• 固定间隔执行
• Cron 表达式调度
• 单次定时执行
• 任务启用/禁用
• 手动立即执行
• 执行结果通知（可选发送到渠道）

📚 知识库

• 每个 Agent 独立的知识库目录
• 支持上传文档、PDF、图片、数据文件
• 文件夹创建和管理
• 文件预览（支持文本、代码、JSON 等）
• 文件下载和删除

⚡ 技能商店 (Skills)

• 搜索和安装来自 skills.sh 的 AI 技能
• 技能启用/禁用
• 内置技能 + 用户自定义技能

🔌 多渠道支持

• Telegram
• Discord
• Email (SMTP)
• WhatsApp Web
• Signal
• Slack
• iMessage
• 其他扩展渠道
• 配置文档：https://my.feishu.cn/wiki/KfTlwurh7ix0PHkQmHic2L0Snue

🔑 API 访问

• API Token 生成和管理
• 支持命令行调用 Agent
• 会话复用
• 外部系统集成

🧠 多模型支持

提供商	模型示例
DashScope	qwen3-coder-plus, qwen-turbo
Anthropic	claude-sonnet-4-5, claude-opus-4-5
OpenAI	gpt-4o, gpt-4o-mini, o3-mini
DeepSeek	deepseek-chat, deepseek-reasoner
AiHubMix	aihubmix/模型名
Evolink	evolink/gpt-5.2, evolink/deepseek-chat
OpenRouter	openrouter/任意模型（兜底）

📊 仪表盘

• Agent 总数统计
• 会话总数统计
• 技能总数统计
• Agent 状态概览

📁 文件管理

• 工作空间文件浏览
• 文件上传/下载
• 目录创建/删除

⚙️ 系统管理

• 用户管理
• 渠道配置
• AI 模型配置
• 审计日志
• 系统设置

🏢 多租户隔离

• 每个用户独立 Docker 容器
• 容器级资源隔离（2GB RAM, 4 CPU）
• 按需创建，空闲自动暂停
• 数据完全隔离

---

🖼️ 界面预览

仪表盘与聊天界面

技能管理

聊天与管理界面

容器修复

定时任务管理

Agent 管理

技能商店

插件管理

浏览器访问

管理界面

API 调用示例

vLLM 支持

---

🔄 运行流程概览

本项目的核心思路：用 Hermes 作为每个用户的 AI Agent 运行时，通过容器化方式将 Hermes 接入到平台的多租户体系中。

一条消息的完整旅程

用户在浏览器输入消息
    |
    v
[Frontend] Vite+React (端口 3080)
    | WebSocket 连接
    v
[Platform Gateway] FastAPI (端口 8080) --对应platform目录和项目
    | 1. JWT 认证
    | 2. 查找/启动用户容器
    | 3. WebSocket 代理
    v
[用户容器] — 每个 dedicated 用户一个独立 Docker 容器
    |
    |  容器内部结构:
    |  ┌─────────────────────────────────────────┐
    |  │  Hermes API Server (端口 18080)           │
    |  │    - HTTP / SSE API                       │
    |  │    - Session / Run 管理                   │
    |  │    - 工具调用 (bash/文件/搜索等)           │
    |  │    - Skills 系统                          │
    |  └─────────────────────────────────────────┘
    |
    | Agent 需要调用 LLM 时:
    v
[Platform Gateway] /llm/v1/chat/completions
    | 1. 验证容器 Token
    | 2. 检查用户配额
    | 3. 根据模型名匹配 Provider
    | 4. 注入真实 API Key
    v
[LLM 提供商] (Anthropic / OpenAI / DashScope / DeepSeek / ...)
    |
    | 响应沿原路返回
    v
用户在浏览器看到回复

核心转发兼容 API 的流程

   1. Frontend (前端)
      - 运行在 3080 端口
      - Vite 配置将 /api 代理到 http://localhost:8080（gateway）

   2. Gateway / Platform (平台后端)
      - 运行在 8080 端口，由 ./platform 构建
      - 处理认证、用户管理、数据库
      - 对于 /api/openclaw/* 和 /api/shared-openclaw/* 路径，通过 platform/app/api_compat/openclaw_compat.py 调用当前 runtime backend

   3. Hermes Runtime (用户容器内或 shared runtime)
      - Dedicated 用户有独立 Docker 容器；shared 用户共用 shared runtime，并由平台校验 session/run 归属
      - Hermes API 服务运行在 18080 端口（dedicated）或 8080 端口（shared）
      - 提供 sessions、runs、skills、workspace 等 runtime 能力

1.2 关键设计决策

决策	说明
Hermes 作为默认 Agent 核心	dedicated / shared runtime 默认走 Hermes Agent 容器；OpenClaw backend 作为显式 fallback 保留
OpenClaw-compatible API 适配层	对外继续保留 /api/openclaw/*、/api/shared-openclaw/*，底层由 runtime backend selector 分流
API Key 不进容器	所有 LLM API Key 只存在于 Gateway 环境变量中，容器通过 Token 代理访问
Dedicated 容器级隔离	dedicated 用户独立容器、独立 Volume，互不干扰
Shared 逻辑隔离	shared 用户共用 runtime；平台按 agent/session/workspace 前缀隔离，并记录 run ownership 防止跨用户读取 run 结果或事件
按需创建	用户首次聊天时才创建容器，空闲 30 分钟暂停，30 天归档

---

2. 多租户部署（Docker Compose）

2.1 架构

浏览器 --> frontend:3080 --(JS请求)--> gateway(platform):8080 --> 用户容器(hermes)
                                            |                   |
                                       postgres:5432      gateway/llm/v1
                                       (用户/配额)         (注入API Key)
                                                               |
                                                         实际 LLM 提供商

• Frontend：Vite + React Web 界面，用户注册、登录、聊天
• Gateway：平台网关（Python FastAPI），负责认证、用户容器管理、LLM 代理、配额控制
• 用户容器：每个用户一个独立的 Hermes 实例，自动创建，数据隔离
• PostgreSQL：存储用户账户、容器元数据、用量记录

2.2 前置条件

• Docker & Docker Compose
• 至少一个 LLM 提供商的 API Key

2.3 配置 .env 文件

在项目根目录创建 .env 文件，填入你的 API Key 和配置：

# .env — docker compose 自动读取此文件

# ========== 必填：至少配置一个 LLM 提供商 ==========

# 阿里 DashScope（通义千问系列）
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxx

# Anthropic（Claude 系列）
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx

# OpenAI（GPT 系列）
OPENAI_API_KEY=sk-xxxxxxxxxxxx

# DeepSeek
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx

# OpenRouter（支持路由到任意模型，作为兜底）
OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxx

# AiHubMix
AIHUBMIX_API_KEY=sk-xxxxxxxxxxxx

# Evolink（OpenAI 兼容聚合代理，支持 GPT-5 / DeepSeek / Gemini 等）
EVOLINK_API_KEY=sk-xxxxxxxxxxxx

# ========== 可选配置 ==========

# 默认模型（新用户容器使用此模型）
DEFAULT_MODEL=dashscope/qwen3-coder-plus

# 平台代理模型输入能力（要支持图片识别请保留 text,image）
# 可选：text 或 text,image
NANOBOT_PROXY__MODEL_INPUT=text,image

# JWT 密钥（生产环境务必修改）
JWT_SECRET=your-secure-random-string

2.4 支持的模型

配置对应的 API Key 后，用户可以使用以下模型：

提供商	模型示例	.env 变量
DashScope	dashscope/qwen3-coder-plus, dashscope/qwen-turbo	DASHSCOPE_API_KEY
Anthropic	claude-sonnet-4-5, claude-opus-4-5	ANTHROPIC_API_KEY
OpenAI	gpt-4o, gpt-4o-mini, o3-mini	OPENAI_API_KEY
DeepSeek	deepseek/deepseek-chat, deepseek/deepseek-reasoner	DEEPSEEK_API_KEY
MiniMax	minimax/MiniMax-M2.7, minimax/MiniMax-M2.7-highspeed	MINIMAX_API_KEY
AiHubMix	aihubmix/模型名	AIHUBMIX_API_KEY
Evolink	evolink/gpt-5.2, evolink/deepseek-chat	EVOLINK_API_KEY
OpenRouter	openrouter/任意模型（兜底）	OPENROUTER_API_KEY

Gateway 根据模型名自动匹配提供商并注入对应的 API Key，用户容器内不存储任何密钥。 MiniMax 默认将 MiniMax-M2.7 路由到同族 highspeed 变体以降低回答等待时间； 需要严格使用原始模型时设置 MINIMAX_M27_USE_HIGHSPEED=false。

2.5 构建与启动

方式1：一键部署脚本

# 准备环境（检查 Docker、下载镜像等）
python prepare.py

# === Docker 部署（推荐） ===

# 本地 Docker 部署（localhost 访问）,推荐python 3.10以上版本
bash build_base_image.sh  #基础镜像先构建，构建hermes镜像，以后修改hermes下的内容，都以直接使用python deploy_docker.py进行基于基础镜像进行build就可以了,可以大大节约build的时间，每次build大概只需要1-2分钟。
build_base_image.sh构建的是hermes-base:lastest
python deploy_docker.py --rebuild hermes 
它构建的是hermes_agent:latest

# 重新构建指定服务（Hermes 是默认底层 runtime 镜像）
python deploy_docker.py --rebuild hermes,gateway,frontend --fast

# 默认 Hermes 镜像跳过 Chromium 预装，并禁用浏览器相关 npm 安装脚本以加快构建；需要 browser 工具时显式打开
python deploy_docker.py --rebuild hermes --with-browser
PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright python deploy_docker.py --rebuild hermes --with-browser

# 默认也跳过 WhatsApp bridge 的 GitHub npm 依赖；需要时显式打开
HERMES_INSTALL_WHATSAPP_BRIDGE=true python deploy_docker.py --rebuild hermes

# 仅重建某个服务
python deploy_docker.py --rebuild frontend

# 完全清理重建
python deploy_docker.py --clean

=== 本地开发模式 ===

legacy 本地开发 helper（Docker 部署默认走 Hermes）

python start_local.py

仅启动部分服务

python start_local.py --only db,gateway,frontend

测试打包 Hermes dedicated runtime

docker build -f hermes-agent/Dockerfile.bridge -t nanobot-hermes-agent:latest hermes-agent/

检查服务状态

python check_status.py

> **提示**：换网不需要重新 build 前端。前端使用相对路径 `/api/...`，由 nginx 反代转发，与 IP 无关。

本地测试启动后：

本地开发环境已启动 PostgreSQL http://127.0.0.1:5432 (Docker 容器) Hermes Agent http://127.0.0.1:18080 (PID xxxxx) Platform Gateway http://127.0.0.1:8080 Frontend Dev http://127.0.0.1:3080

### 2.6 使用

1. 打开浏览器访问 `http://localhost:3080`
2. 注册账号并登录
3. 开始聊天 — Gateway 会自动为你创建隔离的 Hermes 容器

### 2.7 服务端口

| 服务 | 端口 | 说明 |
|------|------|------|
| Frontend | 3080 (映射 3000) | Web 界面 |
| Gateway | 8080 | API 网关（浏览器直接请求） |
| PostgreSQL | 15432 (映射 5432) | 内部数据库 |
| Hermes Runtime (dedicated 容器内) | 18080 | 容器对外 HTTP + SSE |
| Hermes Runtime (shared 容器内) | 8080 | shared runtime API |

### 2.8 数据持久化

| 数据 | 存储方式 |
|------|---------|
| 用户账户、配额、容器元数据 | PostgreSQL（`pgdata` volume） |
| 用户工作区和会话 | Docker named volumes + `/data/hermes-users` |

### 2.9 常用运维命令

```bash
# 查看所有容器
docker ps -a --filter "name=hermes"

# 查看某个用户容器的日志
docker logs -f hermes-user-xxxxxxxx

# 重建 gateway（修改后端代码后）
docker compose build --no-cache gateway && docker compose up -d

# 重建 frontend（修改前端代码或 API 地址后）
docker compose build --no-cache frontend && docker compose up -d

# 完全重置（删除所有数据）
docker compose down -v
docker rm -f $(docker ps -a --filter "name=hermes-user-" -q) 2>/dev/null

---

4. 整体架构

                        ┌──────────────────────┐
                        │   浏览器 (Frontend)    │
                        │   Vite+React :3080        │
                        └──────────┬───────────┘
                                   │ HTTP + WebSocket
                                   v
                        ┌──────────────────────┐
                        │  Platform Gateway     │
                        │  FastAPI :8080         │
                        │  ┌────────────────┐   │
                        │  │ Auth (JWT)      │   │
                        │  │ Container Mgr   │   │
                        │  │ LLM Proxy       │   │
                        │  │ Quota Control   │   │
                        │  └────────────────┘   │
                        └───┬──────────┬───────┘
                            │          │
                  ┌─────────┘          └──────────┐
                  v                               v
        ┌──────────────┐               ┌──────────────────┐
        │  PostgreSQL   │               │  用户容器 (N个)    │
        │  :5432        │               │  ┌──────────────┐ │
        │  用户/配额/    │               │  │ Bridge :18080│ │