riba2534 / happyclaw

HappyClaw 自托管的多用户本地 AI Agent 系统 — Powered By Claude Code. 介绍 · 核心能力 · 快速开始 · 技术架构 · 贡献 --- | 聊天界面 — 工具调用追踪 | 聊天界面 — Markdown 渲染 | 聊天界面 — 图片生成 + 文件管理 | |:--------------------:|:-------------------:|:----------------------:| | | | | 📸 更多截图 **设置向导** | 创建管理员 | 配置接入（飞书 + Claude） | |:--------:|:---------------------:| | | | **移动端 PWA** | 登录 | 工作区 | 系统监控 | 设置 | |:---:|:-----:|:------:|:---:| | | | | | **飞书集成** | Bot 聊天 | 富文本卡片回复 | |:-------:|:----------:| | | | HappyClaw 是什么 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 渠道送达。 核心能力 多渠道接入 | 渠道 | 连接方式 | 消息格式 | 特色 | |------|---------|---------|------| | **飞书** | WebSocket 长连接 | 富文本卡片 | 图片消息（Vision）、文件消息自动下载到工作区、Reaction 反馈、自动注册群组 | | **Telegram** | Bot API (Long Polling) | Markdown → HTML | 长消息自动分片（3800 字符）、图片走 Vision（base64）、文档文件自动下载到工作区 | | **QQ** | WebSocket (Bot API v2) | 纯文本 | 私聊 + 群聊 @Bot、图片消息（Vision）、配对码绑定 | | **Web** | WebSocket 实时通信 | 流式 Markdown | 图片粘贴/拖拽上传、虚拟滚动 | 每个用户可独立配置自己的 IM 通道（飞书应用凭据、Telegram Bot Token、QQ Bot 凭据），互不干扰。消息统一路由：飞书来源回飞书，Telegram 来源回 Telegram，QQ 来源回 QQ，Web 来源回 Web。 Agent 执行引擎 基于 Claude Agent SDK 构建，SDK 底层调用完整的 Claude Code CLI。 • **Per-user 主工作区** — 每个用户拥有一个固定的主工作区（admin 使用宿主机模式，member 使用容器模式），IM 消息路由到各自的主工作区 • **宿主机模式** — Agent 直接在宿主机运行，访问本地文件系统，零 Docker 依赖（admin 主工作区默认模式） • **容器模式** — Docker 隔离执行，非 root 用户，预装 40+ 工具（member 主工作区默认模式） • **多会话并发** — 最多 20 个容器 + 5 个宿主机进程同时运行，会话级队列调度 • **自定义工作目录** — 每个会话可配置 指向不同项目 • **失败自动恢复** — 指数退避重试（5s → 80s，最多 5 次），上下文溢出自动压缩并归档历史 实时流式体验 Agent 的思考和执行过程实时推送到前端，而非等待最终结果： • **思考过程** — 可折叠的 Extended Thinking 面板，逐字推送 • **工具调用追踪** — 工具名称、执行耗时、嵌套层级、输入参数摘要 • **调用轨迹时间线** — 最近 30 条工具调用记录，快速回溯 • **Hook 执行状态** — PreToolUse / PostToolUse Hook 的启动、进度、结果 • **流式 Markdown 渲染** — GFM 表格、代码高亮、图片 Lightbox 12 个 MCP 工具 Agent 在运行时可通过内置 MCP Server 与主进程通信： | 工具 | 说明 | |------|------| | | 运行期间即时发送消息给用户/群组 | | | 创建定时/周期/一次性任务（cron / interval / once） | | | 列出定时任务 | | / / | 暂停、恢复、取消任务 | | | 注册新群组（仅 admin 主工作区） | | | 安装 Skill 到工作区（仅主工作区） | | | 卸载已安装的 Skill（仅主工作区） | | | 追加时效性记忆到 | | | 全文检索工作区记忆文件 | | | 读取记忆文件内容 | 定时任务 • 三种调度模式：**Cron 表达式** / **固定间隔** / **一次性执行** • 两种上下文模式： （在指定会话中执行）/ （独立隔离环境） • 完整的执行日志（耗时、状态、结果），Web 界面管理 记忆系统 Agent 自主维护跨会话的持久记忆： • **用户全局记忆** — ，每个用户独立的全局记忆，所有会话可读 • **会话记忆** — ，会话私有 • **日期记忆** — ，时效性信息 • **对话归档** — PreCompact Hook 在上下文压缩前自动归档到 • **全文检索** — Web 界面在线编辑 + 搜索 Skills 系统 • **项目级 Skills** — 放在 ，所有容器自动挂载 • **用户级 Skills** — 放在 ，所有容器自动挂载 • 无需重建镜像，volume 挂载 + 符号链接自动发现 Web 终端 基于 xterm.js + node-pty 的完整终端：WebSocket 连接，可拖拽调整面板，直接在 Web 界面中操作服务器。 移动端 PWA 专为移动端优化的 Progressive Web App，手机浏览器一键安装到桌面： • **原生体验** — 全屏模式运行，独立的应用图标，视觉上与原生 App 无异 • **响应式布局** — 移动端优先设计，聊天界面、设置页面、监控面板均适配小屏幕 • **iOS / Android 适配** — 安全区域适配、滚动优化、字体渲染、触摸交互 • **随时可用** — 任何时间、任何地点，掏出手机就能与 AI Agent 对话、查看执行状态、管理任务 文件管理 上传（50MB 限制）/ 下载 / 删除，目录管理，图片预览，拖拽上传。路径遍历防护 + 系统路径保护。 安全与多用户 | 能力 | 说明 | |------|------| | **用户隔离** | 每个用户拥有独立的主工作区（ ）、工作目录、IM 通道 | | **个性化设置** | 用户可自定义 AI 名称、头像 emoji 和颜色 | | **RBAC** | 5 种权限，4 种角色模板（admin_full / member_basic / ops_manager / user_admin） | | **注册控制** | 开放注册 / 邀请码注册 / 关闭注册 | | **审计日志** | 18 种事件类型，完整操作追踪 | | **加密存储** | API 密钥 AES-256-GCM 加密，Web API 仅返回掩码值 | | **挂载安全** | 白名单校验 + 黑名单模式匹配（ 、 等敏感路径） | | **终端权限** | 用户可访问自己容器的 Web 终端（宿主机模式不支持） | | **登录保护** | 5 次失败锁定 15 分钟，bcrypt 12 轮，HMAC Cookie，30 天会话有效期 | | **PWA** | 一键安装到手机桌面，移动端深度优化，随时随地使用 AI Agent | 快速开始 前置要求 开始之前，请确保以下依赖已安装： **必需** • **Node.js >= 20** — 运行主服务和前端构建 • macOS: • Linux: 参考 NodeSource 或使用 • Windows: 官网下载 • **Docker** — 容器模式运行 Agent（member 用户需要；admin 仅宿主机模式可不装） • macOS: 推荐 OrbStack（更轻量），也可用 Docker Desktop • Linux: • 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 运行时， 首次启动时自动安装。 安装启动 按照设置向导完成初始化： • **创建管理员** — 自定义用户名和密码（无默认账号） • **配置 Claude API** — 填入 API 密钥和模型（支持中转服务） • **配置 IM 通道**（可选）— 飞书 App ID/Secret、Telegram Bot Token 或 QQ Bot 凭据 • **开始对话** — 在 Web 聊天页面直接发送消息 > 所有配置通过 Web 界面完成，不依赖任何配置文件。API 密钥 AES-256-GCM 加密存储。 启用容器模式 admin 用户默认使用宿主机模式（无需 Docker），开箱即用。如果需要容器模式（member 用户注册后自动使用）： 新用户注册后会自动创建容器模式的主工作区（ ），无需额外配置。 配置飞书集成 • 前往 飞书开放平台，创建企业自建应用 • 在应用的「事件订阅」中添加： （接收消息） • 在应用的「权限管理」中开通以下权限： • （发送消息） • （接收群聊 @消息） • （接收群聊所有消息）— **敏感权限**，需管理员审批。如不开通，群聊中只有 @机器人 的消息才会被处理 • （接收私聊消息） • 发布应用版本并等待审批通过 • 在 HappyClaw Web 界面的「设置 → IM 通道 → 飞书」中填入 App ID 和 App Secret 每个用户可在个人设置中独立配置飞书应用凭据，实现 per-user 的飞书 Bot。 > **群聊 Mention 控制**：默认群聊中需要 @机器人 才会响应。可通过 命令切换为全量响应（需要 权限）。 配置 Telegram 集成 • 在 Telegram 中搜索 @BotFather，发送 创建 Bot • 记录返回的 Bot Token • 在 HappyClaw Web 界面的「设置 → IM 通道 → Telegram」中填入 Bot Token • **群聊使用**：如需在 Telegram 群中使用 Bot，需在 BotFather 中发送 → 选择 Bot → Bot Settings → Group Privacy → Turn off，否则 Bot 只能接收 命令消息 配置 QQ 集成 • 前往 QQ 开放平台，使用手机 QQ 扫码注册登录 • 创建机器人，设置名称和头像 • 在机器人管理页面获取 **App ID** 和 **App Secret** • 在 HappyClaw Web 界面的「设置 → IM 通道 → QQ」中填入 App ID 和 App Secret • **配对绑定**：在设置页生成配对码，然后在 QQ 中向 Bot 发送 完成绑定 > QQ Bot 使用官方 API v2 协议，支持 C2C 私聊和群聊 @Bot 消息。群聊中 Bot 仅接收 @Bot 的消息。 IM 斜杠命令 飞书/Telegram/QQ 中以 开头的消息会被拦截为斜杠命令（未知命令继续作为普通消息处理）： | 命令 | 缩写 | 用途 | |------|------|------| | | | 查看所有工作区和对话列表 | | | - | 查看当前工作区/对话状态 | | | - | 查看当前绑定位置和回复策略 | | | - | 绑定到指定工作区或 Age…