什么是HappyClaw:完整解析这款自托管多用户Claude Code智能体工作台
什么是HappyClaw:完整解析这款自托管多用户Claude Code智能体工作台
HappyClaw 是一款自托管、多用户、智能体优先的 Claude Code 工作台:它把完整的 Claude Code 运行时封装成可持续运行的服务,让你从浏览器或飞书、Telegram、QQ、钉钉等 8 种消息渠道,长期、安全地使用同一套 AI 智能体。对于想"自己掌控 AI 编程助手"的新手和团队来说,它就是那台 7×24 小时在线的 AI 工作站。
🎯 30秒理解:HappyClaw 解决了什么问题
普通 AI 聊天工具只能"动嘴",而 Claude Code 能真正读写文件、执行命令、浏览网页。但原生的 Claude Code 只能在你自己的终端里跑,无法多人共享、无法手机访问、无法定时干活。
HappyClaw 智能体工作台 正是补上这一环:
| 痛点 | HappyClaw 的解法 |
|---|---|
| 智能体只活在终端里 | Web + PWA + 8 种 IM 渠道统一接入,任务完成主动回推结果 |
| 一个人用 | 多用户、多账号,彼此的工作区与数据完全隔离 |
| 怕智能体搞坏本机 | 普通成员默认在 Docker 沙箱容器内执行,管理员可用授权的本机目录 |
| 任务跑完就忘 | 定时任务、运行历史、故障恢复、用量统计一应俱全 |
| 模型账号不稳定 | 多 Provider 池,支持轮询、加权、故障转移与自动健康恢复 |
它不是简单的聊天 API 包装:智能体运行在真实的 Claude Code 环境中,拥有读写文件、执行终端命令、调用 MCP、加载 Skills 的完整工具能力。详见 README.md。
🧩 核心概念:智能体优先的三层工作模型
理解 HappyClaw 的关键,是记住一条清晰的层级链:
智能体 Agent(身份、提示词、Skills、MCP)
└── Workspace 工作区(项目目录、执行模式、环境变量)
├── Workspace Memory(跨会话复用的事实、决策、经验)
├── Main Session(工作区主会话)
├── Runtime Session(独立对话或渠道话题)
└── Scheduled Run(定时任务运行)
- 智能体(Agent) 管"它是谁、会什么":名称、头像、结构化提示词、Skills 与 MCP,还支持 AI 辅助生成提示词和版本历史。
- 工作区(Workspace) 管"在哪干活":每个工作区是私有的文件与执行隔离边界,文件、会话、渠道绑定和记忆都随工作区走。
- 会话(Session) 管"聊到哪了":同属一个工作区的多段独立对话上下文,互不串台。
这条链路的完整业务规则(包括渠道如何绑定到工作区/会话)写在 docs/BUSINESS-MODEL.md,建议部署团队前通读。
🚀 快速上手:3 条命令跑起来
环境要求:macOS / Linux(Windows 推荐 WSL2)、Node.js 20+、npm、GNU Make,普通成员场景再装 Docker。
git clone https://gitcode.com/gh_mirrors/ha/happyclaw
cd happyclaw
make start
首次启动会自动安装三端依赖、编译后端/Web/Agent Runner,并在 Docker 可用时拉取多架构智能体镜像。完成后打开 http://localhost:3000,按向导完成 4 步:
- 创建第一个管理员账户;
- 配置 Anthropic 官方账号或第三方 Claude 兼容 Provider;
- 可选:接入飞书、Telegram、QQ、钉钉、微信、企业微信、Discord、WhatsApp;
- 进入工作台,创建智能体、工作区和会话。
常用运维命令都集中在 Makefile:make status 看状态、make stop 停服务、make backup 一键一致性备份、make restore FILE=xxx.tar.gz 恢复实例。生产部署与回滚的完整流程见 DEPLOYMENT.md。
💬 8 大消息渠道:让智能体住进你的聊天软件
这是 HappyClaw 最有体感的能力——同一个智能体,你在手机上用飞书、电脑前用 Web,看到的都是同一个工作区和记忆。
| 渠道 | 接入方式 | 亮点能力 |
|---|---|---|
| 飞书 | App ID/Secret + WebSocket | 流式卡片、图片文件、群聊 @ 控制、话题映射 |
| Telegram | Bot Token | Markdown/HTML、长消息分片、代理配置 |
| App ID/Secret | 私聊、群聊 @Bot、配对码绑定 | |
| 钉钉 | Client ID/Secret | AI Card 流式回复、群聊 @ 控制 |
| 微信 | Web 界面扫码 | 二维码授权、媒体收发、断线恢复 |
| 企业微信 | Bot ID/Secret | Markdown 流式回复、配对码绑定 |
| Discord | Bot Token | 服务器频道路由、多账号隔离 |
| Web 界面扫码 | 二维码登录、会话持久化、断线恢复 |
安全细节做得很克制:连接账号或发现聊天都不会自动绑定、不会触发回复,必须显式绑定到具体会话后才会响应;未绑定/已解绑的渠道保持静默。每个渠道账号的凭据按用户隔离,发送时不借用其他 Bot 的凭据。渠道适配层的实现位于 src/im-manager.ts,各渠道懒加载注册逻辑在 src/channel-registry.ts。
绑定后还可以在渠道里用斜杠命令管理上下文:/list、/status、/where、/bind、/unbind、/new、/clear、/fresh,以及群聊中 @Bot /steer 引导任务、@Bot /break 停止任务。
⚖️ 双执行模式:宿主机与容器各得其所
| 模式 | 适用对象 | 行为 |
|---|---|---|
| Host | 管理员授权的宿主机工作区 | 直接在指定本机目录运行,适合已有代码仓库和本机工具链 |
| Container | 普通成员与需隔离的工作区 | 非 root Docker 容器运行,独立工作目录 + 预装工具链 |
规则简单明确:普通成员不能把容器工作区降级为宿主机执行,Script 定时任务也只允许管理员在有权限的 Host 工作区运行。这样既保护了多人场景下的宿主机安全,又没牺牲管理员的灵活性。容器侧的执行器代码见 container/agent-runner/。
🔌 能力治理:Skills、MCP 与 Plugins 分层生效
HappyClaw 把智能体能力来源分成清晰的几层,最终在工作区里合并生效:
- 内置能力:随系统或智能体容器提供的基础工具与 Skills;
- 用户 Skills:从技能市场、Git 仓库或 ZIP 导入,按用户隔离并记录来源版本;
- 项目上下文:工作区目录里的
CLAUDE.md、.claude/skills和 MCP 配置; - 用户 / 系统 MCP:个人维护或管理员共享的 MCP Server;
- Claude Code Plugins:系统目录与用户启用状态分离,按版本化快照加载。
配置页可以直接预览最终生效能力,避免"以为配了,实际没生效"的困惑。远端 MCP 的配置与排查步骤见 docs/REMOTE-MCP.md。
🤖 模型提供商:多 Provider 池 + 智能负载均衡
HappyClaw 支持同时配置多个 Claude Provider,为新会话按策略挑选健康的那个:
| 策略 | 说明 |
|---|---|
| Round Robin | 健康 Provider 间轮询 |
| Weighted Round Robin | 按权重分配新会话 |
| Failover | 主 Provider 优先,故障自动切换 |
| 健康恢复 | 连续失败暂时摘除,过恢复窗口再探测 |
| 会话粘性 | 已开始会话固定 Provider,上下文不漂移 |
| 默认模型 | 手动指定后不参与自动分配 |
Provider 类型覆盖 Anthropic 官方(OAuth 一键登录或 API Key)和第三方兼容端点(填 Endpoint + Token + 模型名即可,1M 上下文等兼容环境变量系统自动预填)。密钥用 AES-256-GCM 加密存储,API 只返回"是否已配置",不返回明文。
⏰ 定时任务:让智能体替你值班
定时任务复用与交互会话完全相同的智能体、工作区和执行策略:
- 调度方式:Cron、固定间隔(最短 60 秒)、一次性时间点;
- 执行类型:完整 Claude Agent 任务,或管理员的 Script 任务;
- 上下文模式:注入工作区主会话,或每次独立隔离运行;
- 幂等运行:Web、REST、MCP 共用幂等键,网络重试不会重复执行;
- 通知重试:结果与通知状态分离,通知失败只重发通知,不重跑任务;
- 异常恢复:服务重启后靠持久化记录和租约识别、恢复或终止遗留任务。
接口与状态字段见 docs/API.md 的任务章节。
🔐 安全模型:多用户隔离是底线
会执行代码、会碰第三方平台的服务,安全边界必须讲清楚:
- 资源隔离:用户、渠道账号、工作区及其 Memory、Skills、MCP、用量记录全部按 owner 隔离,admin 也不自动绕过工作区所有权;
- 密钥加密:Provider 与渠道密钥 AES-256-GCM 加密,密钥文件权限
0600; - 接口鉴权:REST、WebSocket、IM 命令、MCP 工具各自独立执行身份、owner、角色与能力检查;
- 上传校验:Skill ZIP、文件上传、备份恢复、Git 操作都含路径、符号链接、大小与目标校验;
- 公网建议:HTTPS 反向代理(
/ws需放行 WebSocket Upgrade)、强密码、关闭开放注册、定期备份data/。
完整接口权限表见 docs/ACL-MATRIX.md,模块边界与性能预算见 docs/RUNTIME-ARCHITECTURE.md。
📂 项目结构与延伸阅读
happyclaw/
├── src/ # 主服务:路由、调度、渠道、权限与持久化
├── web/ # React Web / PWA 前端
├── container/
│ └── agent-runner/ # Host/Container 共用的 Agent 执行器
├── shared/ # 主服务与前端/Runner 共享的事件类型
├── scripts/ # 构建、校验、备份与恢复脚本
├── tests/ # 后端、前端契约、迁移与安全回归测试
├── docs/ # API、权限与设计文档
├── Makefile # 统一开发、构建和运维入口
└── data/ # 本地运行数据(不进 Git)
所有持久化数据默认落在 data/(SQLite 数据库、配置、工作区文件、会话数据等),迁移实例优先使用 make backup / make restore,不要在服务运行时直接复制 SQLite 文件。
主要文档入口:
- 产品与功能:README.md
- REST API:docs/API.md
- 运行时架构:docs/RUNTIME-ARCHITECTURE.md
- 权限矩阵:docs/ACL-MATRIX.md
- 生产部署:DEPLOYMENT.md
- 安全说明:SECURITY.md
总结:谁应该用 HappyClaw?
一句话画像:需要"能动手"的 AI、且要长期运行、多人共用的开发者或小团队。
- 想在手机/聊天软件里随时指挥 AI 干活 → 8 大渠道接入开箱即用;
- 想给团队搭私有 AI 工作台 → 多用户隔离 + RBAC + 审计日志;
- 想让 AI 定时巡检、自动汇报 → 定时任务 + 通知重试;
- 担心 AI 执行代码伤及本机 → Docker 沙箱 + Host/Container 双模式;
- 想自托管、数据不出内网 → 自部署 + 一键备份恢复。
make start 之后,你的自托管 Claude Code 智能体工作台就可以 7×24 小时在线了。