HappyClaw Logo

自托管的多用户本地 AI Agent 系统 — Powered By Claude Code.

License Node.js TypeScript GitHub Stars

介绍 · 核心能力 · 快速开始 · 技术架构 · 贡献

HappyClaw 是一个基于 Claude Agent SDK 构建的自托管多用户 AI Agent 系统。它将完整的 Claude Code 运行时封装为可通过飞书、Telegram、QQ 和 Web 界面访问的服务,支持文件读写、终端操作、浏览器自动化、多轮推理及 MCP 工具生态。

核心设计原则:不重新实现 Agent 能力,直接复用 Claude Code。底层调用的是完整的 Claude Code CLI 运行时,而非 API Wrapper 或 Prompt Chain。Claude Code 的每次升级——新工具、更强的推理、更多的 MCP 支持——HappyClaw 零适配自动受益。

• 原生 Claude Code 驱动 — 基于 Claude Agent SDK,底层为完整的 Claude Code CLI 运行时,继承其全部能力
• 多用户隔离 — Per-user 工作区、Per-user IM 通道、RBAC 权限体系、邀请码注册、审计日志,每个用户拥有独立的执行环境
• 移动端 PWA — 针对移动端深度优化,支持一键安装到桌面,iOS / Android 均已适配,随时随地通过手机访问 AI Agent
• 四端消息统一路由 — 飞书 WebSocket 长连接(富文本卡片、Reaction 反馈)、Telegram Bot API、QQ Bot API v2(私聊 + 群聊 @Bot)、Web 界面,四端消息统一路由

项目借鉴了 OpenClaw 的容器化架构,并融合了 Claude Code 官方 Cowork 的多会话协作思路:多个独立 Agent 会话并行工作,各自拥有隔离的工作空间和持久记忆,结果通过 IM 渠道送达。

每个用户可独立配置自己的 IM 通道(飞书应用凭据、Telegram Bot Token、QQ Bot 凭据),互不干扰。消息统一路由:飞书来源回飞书,Telegram 来源回 Telegram,QQ 来源回 QQ,Web 来源回 Web。

基于 Claude Agent SDK 构建,SDK 底层调用完整的 Claude Code CLI。

• Per-user 主工作区 — 每个用户拥有一个固定的主工作区(admin 使用宿主机模式,member 使用容器模式),IM 消息路由到各自的主工作区
• 宿主机模式 — Agent 直接在宿主机运行,访问本地文件系统,零 Docker 依赖(admin 主工作区默认模式)
• 容器模式 — Docker 隔离执行,非 root 用户,预装 40+ 工具(member 主工作区默认模式)
• 多会话并发 — 最多 20 个容器 + 5 个宿主机进程同时运行,会话级队列调度
• 自定义工作目录 — 每个会话可配置 customCwd 指向不同项目
• 失败自动恢复 — 指数退避重试(5s → 80s,最多 5 次),上下文溢出自动压缩并归档历史

Agent 的思考和执行过程实时推送到前端,而非等待最终结果:

• 思考过程 — 可折叠的 Extended Thinking 面板,逐字推送
• 工具调用追踪 — 工具名称、执行耗时、嵌套层级、输入参数摘要
• 调用轨迹时间线 — 最近 30 条工具调用记录,快速回溯
• Hook 执行状态 — PreToolUse / PostToolUse Hook 的启动、进度、结果
• 流式 Markdown 渲染 — GFM 表格、代码高亮、图片 Lightbox

Agent 在运行时可通过内置 MCP Server 与主进程通信:

• 三种调度模式:Cron 表达式 / 固定间隔 / 一次性执行
• 两种上下文模式:group(在指定会话中执行)/ isolated(独立隔离环境)
• 完整的执行日志(耗时、状态、结果),Web 界面管理

Agent 自主维护跨会话的持久记忆:

• 用户全局记忆 — data/groups/user-global/{userId}/CLAUDE.md,每个用户独立的全局记忆,所有会话可读
• 会话记忆 — data/groups/{folder}/CLAUDE.md,会话私有
• 日期记忆 — memory/YYYY-MM-DD.md,时效性信息
• 对话归档 — PreCompact Hook 在上下文压缩前自动归档到 conversations/
• 全文检索 — Web 界面在线编辑 + 搜索

• 项目级 Skills — 放在 container/skills/,所有容器自动挂载
• 用户级 Skills — 放在 ~/.claude/skills/,所有容器自动挂载
• 无需重建镜像,volume 挂载 + 符号链接自动发现

基于 xterm.js + node-pty 的完整终端:WebSocket 连接,可拖拽调整面板,直接在 Web 界面中操作服务器。

专为移动端优化的 Progressive Web App,手机浏览器一键安装到桌面:

• 原生体验 — 全屏模式运行,独立的应用图标,视觉上与原生 App 无异
• 响应式布局 — 移动端优先设计,聊天界面、设置页面、监控面板均适配小屏幕
• iOS / Android 适配 — 安全区域适配、滚动优化、字体渲染、触摸交互
• 随时可用 — 任何时间、任何地点,掏出手机就能与 AI Agent 对话、查看执行状态、管理任务

上传(50MB 限制)/ 下载 / 删除,目录管理,图片预览,拖拽上传。路径遍历防护 + 系统路径保护。

开始之前,请确保以下依赖已安装:

必需

• Node.js >= 20 — 运行主服务和前端构建

  • macOS: brew install node
  • Linux: 参考 NodeSource 或使用 nvm
  • Windows: 官网下载

• Docker — 容器模式运行 Agent(member 用户需要;admin 仅宿主机模式可不装)

  • macOS: 推荐 OrbStack(更轻量),也可用 Docker Desktop
  • Linux: curl -fsSL https://get.docker.com | sh
  • Windows: Docker Desktop

• Claude API 密钥 — Anthropic 官方或兼容的中转服务(各种 Coding Plan),启动后在 Web 界面中配置

可选

• 飞书企业自建应用凭据 — 仅飞书集成需要,前往 飞书开放平台 创建
• Telegram Bot Token — 仅 Telegram 集成需要,通过 @BotFather 获取
• QQ Bot 凭据 — 仅 QQ 集成需要,前往 QQ 开放平台 创建

Claude Code CLI 无需手动安装——项目依赖的 Claude Agent SDK 已内置完整的 CLI 运行时,make start 首次启动时自动安装。

# 1. 克隆仓库
git clone https://github.com/riba2534/happyclaw.git
cd happyclaw
# 2. 一键启动(首次自动安装依赖 + 编译)
make start
访问: http://localhost:3000
如需公网访问,可以自行使用 nginx/caddy 配置反向代理

按照设置向导完成初始化:

1. 创建管理员 — 自定义用户名和密码(无默认账号)
2. 配置 Claude API — 填入 API 密钥和模型(支持中转服务)
3. 配置 IM 通道(可选)— 飞书 App ID/Secret、Telegram Bot Token 或 QQ Bot 凭据
4. 开始对话 — 在 Web 聊天页面直接发送消息

所有配置通过 Web 界面完成,不依赖任何配置文件。API 密钥 AES-256-GCM 加密存储。

admin 用户默认使用宿主机模式(无需 Docker),开箱即用。如果需要容器模式(member 用户注册后自动使用):

# 构建容器镜像
./container/build.sh

新用户注册后会自动创建容器模式的主工作区(home-{userId}),无需额外配置。

1. 前往 飞书开放平台,创建企业自建应用

2. 在应用的「事件订阅」中添加:im.message.receive_v1(接收消息)

3. 在应用的「权限管理」中开通以下权限:

   • cardkit:card:write(创建和更新卡片)
   • im:chat(获取与更新群组信息)
   • im:chat:read(获取群组信息)
   • im:chat:readonly(以应用身份读取群组信息)
   • im:message(发送消息)
   • im:message.group_at_msg:readonly(接收群聊 @消息)
   • im:message.group_msg(接收群聊所有消息)— 敏感权限,需管理员审批。如不开通,群聊中只有 @机器人 的消息才会被处理
   • im:message.p2p_msg:readonly(接收私聊消息)
   • im:resource(获取与上传图片或文件资源)
   📋 权限 JSON(可直接导入飞书开放平台)

   {
    "scopes": {
    "tenant": [
    "cardkit:card:write",
    "im:chat",
    "im:chat:read",
    "im:chat:readonly",
    "im:message",
    "im:message.group_at_msg:readonly",
    "im:message.group_msg",
    "im:message.p2p_msg:readonly",
    "im:resource"
    ],
    "user": []
    }
   }

4. 发布应用版本并等待审批通过

5. 在 HappyClaw Web 界面的「设置 → IM 通道 → 飞书」中填入 App ID 和 App Secret

每个用户可在个人设置中独立配置飞书应用凭据,实现 per-user 的飞书 Bot。

群聊 Mention 控制:默认群聊中需要 @机器人 才会响应。可通过 /require_mention false 命令切换为全量响应(需要 im:message.group_msg 权限)。

1. 在 Telegram 中搜索 @BotFather,发送 /newbot 创建 Bot
2. 记录返回的 Bot Token
3. 在 HappyClaw Web 界面的「设置 → IM 通道 → Telegram」中填入 Bot Token
4. 群聊使用:如需在 Telegram 群中使用 Bot,需在 BotFather 中发送 /mybots → 选择 Bot → Bot Settings → Group Privacy → Turn off,否则 Bot 只能接收 / 命令消息

1. 前往 QQ 开放平台,使用手机 QQ 扫码注册登录
2. 创建机器人,设置名称和头像
3. 在机器人管理页面获取 App ID 和 App Secret
4. 在 HappyClaw Web 界面的「设置 → IM 通道 → QQ」中填入 App ID 和 App Secret
5. 配对绑定:在设置页生成配对码,然后在 QQ 中向 Bot 发送 /pair <配对码> 完成绑定

QQ Bot 使用官方 API v2 协议,支持 C2C 私聊和群聊 @Bot 消息。群聊中 Bot 仅接收 @Bot 的消息。

飞书/Telegram/QQ 中以 / 开头的消息会被拦截为斜杠命令(未知命令继续作为普通消息处理):

admin 主工作区默认使用宿主机模式,member 注册后自动创建容器模式的主工作区。也可在 Web 界面的会话管理中手动切换执行模式。

容器镜像基于 node:22-slim,预装以下工具:

flowchart TD
 subgraph 接入层
 Feishu("飞书<br/>(WebSocket 长连接)")
 Telegram("Telegram<br/>(Bot API)")
 QQ("QQ<br/>(Bot API v2)")
 Web("Web 界面<br/>(React 19 SPA)")
 end
 subgraph 主进程["主进程 (Node.js + Hono)"]
 Router["消息路由<br/>(2s 轮询 + 去重)"]
 Queue["并发队列<br/>(20 容器 + 5 宿主机进程)"]
 Scheduler["定时调度器<br/>(Cron / 间隔 / 一次性)"]
 WS["WebSocket Server<br/>(流式推送 + 终端)"]
 Auth["认证 & RBAC<br/>(bcrypt + HMAC Cookie)"]
 Config["配置管理<br/>(AES-256-GCM 加密)"]
 end
 subgraph 执行层
 Host["宿主机进程<br/>(Claude Code CLI)"]
 Container["Docker 容器<br/>(agent-runner)"]
 end
 subgraph Agent["Agent 运行时"]
 SDK["Claude Agent SDK<br/>(query 循环)"]
 MCP["MCP Server<br/>(12 个工具)"]
 Stream["流式事件<br/>(12 种类型)"]
 end
 DB[("SQLite<br/>(WAL 模式)")]
 IPC["IPC 文件通道<br/>(原子读写)"]
 Memory["记忆系统<br/>(CLAUDE.md + memory/)"]
 Feishu --> Router
 Telegram --> Router
 QQ --> Router
 Web --> Router
 Router --> Queue
 Queue --> Host
 Queue --> Container
 Scheduler --> Queue
 Host --> SDK
 Container --> SDK
 SDK --> MCP
 SDK --> Stream
 MCP --> IPC
 IPC --> Router
 Stream --> WS
 WS --> Web
 Router --> DB
 Auth --> DB
 SDK --> Memory
 class Feishu,Telegram,QQ,Web fe
 class Router,Queue,Scheduler,WS,Auth,Config svc
 class DB db
 class Host,Container faas
 class SDK,MCP,Stream faas
 class IPC cfg
 class Memory cfg

数据流:消息从接入层进入主进程,经去重和路由后分发到并发队列。队列启动宿主机进程或 Docker 容器,内部的 agent-runner 调用 Claude Agent SDK 的 query() 函数。流式事件(思考、文本、工具调用等 12 种类型)通过 stdout 标记协议传回主进程,再经 WebSocket 广播到 Web 客户端或通过 IM API 回复到飞书/Telegram。MCP Server 通过基于文件的 IPC 通道提供 12 个工具,实现 Agent 与主进程的双向通信。

所有运行时数据统一在 data/ 目录下,启动时自动创建,无需手动初始化。

happyclaw/
├── src/ # 后端源码
│ ├── index.ts # 入口:消息轮询、IPC 监听、容器生命周期
│ ├── web.ts # Hono 应用、WebSocket、静态文件
│ ├── routes/ # 路由(auth / groups / files / config / monitor / memory / tasks / skills / admin / browse / agents / mcp-servers)
│ ├── feishu.ts # 飞书连接工厂(WebSocket 长连接)
│ ├── telegram.ts # Telegram 连接工厂(Bot API)
│ ├── qq.ts # QQ 连接工厂(Bot API v2 WebSocket)
│ ├── im-manager.ts # IM 连接池(per-user 飞书/Telegram/QQ 连接管理)
│ ├── im-downloader.ts # IM 文件下载工具(保存到工作区 downloads/)
│ ├── container-runner.ts # Docker / 宿主机进程管理
│ ├── group-queue.ts # 并发控制队列
│ ├── runtime-config.ts # AES-256-GCM 加密配置
│ ├── task-scheduler.ts # 定时任务调度
│ ├── file-manager.ts # 文件安全(路径遍历防护)
│ ├── mount-security.ts # 挂载白名单 / 黑名单
│ └── db.ts # SQLite 数据层(Schema v1→v18)
│
├── web/ # 前端 (React + Vite)
│ └── src/
│ ├── pages/ # 13 个页面
│ ├── components/ # UI 组件(shadcn/ui)
│ ├── stores/ # 10 个 Zustand Store
│ └── api/client.ts # 统一 API 客户端
│
├── container/ # Agent 容器
│ ├── Dockerfile # 容器镜像定义
│ ├── build.sh # 构建脚本
│ ├── agent-runner/ # 容器内执行引擎
│ │ └── src/
│ │ ├── index.ts # Agent 主循环 + 流式事件
│ │ └── mcp-tools.ts # 12 个 MCP 工具
│ └── skills/ # 项目级 Skills
│
├── shared/ # 跨项目共享类型定义
│ └── stream-event.ts # StreamEvent 类型单一真相源
│
├── scripts/ # 构建辅助脚本
│ ├── sync-stream-event.sh # 同步 shared/ 类型到各子项目
│ └── check-stream-event-sync.sh# 校验类型副本一致性
│
├── config/ # 项目配置
│ ├── default-groups.json # 预注册群组
│ └── mount-allowlist.json # 容器挂载白名单
│
├── data/ # 运行时数据(启动时自动创建)
│ ├── db/messages.db # SQLite 数据库(WAL 模式)
│ ├── groups/{folder}/ # 会话工作目录(Agent 可读写)
│ │ ├── downloads/{channel}/ # IM 文件下载(feishu/telegram/qq,按日期分子目录)
│ │ └── CLAUDE.md # 会话私有记忆
│ ├── groups/user-global/{id}/ # 用户全局记忆目录
│ ├── sessions/{folder}/.claude/# Claude 会话持久化
│ ├── ipc/{folder}/ # IPC 通道(input / messages / tasks)
│ ├── env/{folder}/env # 容器环境变量文件
│ ├── memory/{folder}/ # 日期记忆
│ └── config/ # 加密配置文件
│
└── Makefile # 常用命令

make dev # 前后端并行启动(热更新)
make dev-backend # 仅启动后端
make dev-web # 仅启动前端
make build # 编译全部(后端 + 前端 + agent-runner)
make start # 一键启动生产环境
make typecheck # TypeScript 全量类型检查
make format # 代码格式化(Prettier)
make clean # 清理构建产物
make reset-init # 重置为首装状态(清空数据库、配置、工作区、记忆、会话)
make backup # 备份运行时数据到 happyclaw-backup-{date}.tar.gz
make restore # 从备份恢复数据(make restore 或 make restore FILE=xxx.tar.gz)

生产模式(make start):只有后端服务,前端作为静态文件由后端托管,通过 WEB_PORT 环境变量修改端口:

WEB_PORT=8080 make start
# 访问 http://localhost:8080

开发模式(make dev):前端 Vite 开发服务器(5173)和后端(3000)分别运行,开发时访问 5173。

修改后端端口:

# 后端改为 8080(通过环境变量)
WEB_PORT=8080 make dev-backend
# 前端需同步修改代理目标,否则 API 请求会发到默认的 3000
VITE_API_PROXY_TARGET=http://127.0.0.1:8080 VITE_WS_PROXY_TARGET=ws://127.0.0.1:8080 make dev-web

修改前端端口:通过 Vite CLI 参数覆盖:

cd web && npx vite --port 3001

以下为可选覆盖项。推荐使用 Web 设置向导配置 Claude API 和 IM 凭据(加密存储)。

npm run reset:admin -- <用户名> <新密码>

make reset-init
# 或手动:
rm -rf data store groups

欢迎提交 Issue 和 Pull Request!

1. Fork 仓库并克隆到本地
2. 创建功能分支:git checkout -b feature/your-feature
3. 开发并测试:make dev 启动开发环境,make typecheck 检查类型
4. 提交代码并推送到 Fork
5. 创建 Pull Request 到 main 分支

Commit message 使用简体中文,格式:类型: 描述

修复: 侧边栏下拉菜单无法点击
新增: Telegram Bot 集成
重构: 统一消息路由逻辑

项目包含三个独立的 Node.js 项目,各有独立的 package.json 和 tsconfig.json:

Star History Chart

MIT