什么是HappyClaw:完整解析这款自托管多用户Claude Code智能体工作台

原创2026-10-25 23:39:492,175 阅读

什么是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 步:

  1. 创建第一个管理员账户;
  2. 配置 Anthropic 官方账号或第三方 Claude 兼容 Provider;
  3. 可选:接入飞书、Telegram、QQ、钉钉、微信、企业微信、Discord、WhatsApp;
  4. 进入工作台,创建智能体、工作区和会话。

常用运维命令都集中在 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、长消息分片、代理配置
QQ App ID/Secret 私聊、群聊 @Bot、配对码绑定
钉钉 Client ID/Secret AI Card 流式回复、群聊 @ 控制
微信 Web 界面扫码 二维码授权、媒体收发、断线恢复
企业微信 Bot ID/Secret Markdown 流式回复、配对码绑定
Discord Bot Token 服务器频道路由、多账号隔离
WhatsApp 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 文件。

主要文档入口:

总结:谁应该用 HappyClaw?

一句话画像:需要"能动手"的 AI、且要长期运行、多人共用的开发者或小团队。

  • 想在手机/聊天软件里随时指挥 AI 干活 → 8 大渠道接入开箱即用;
  • 想给团队搭私有 AI 工作台 → 多用户隔离 + RBAC + 审计日志;
  • 想让 AI 定时巡检、自动汇报 → 定时任务 + 通知重试;
  • 担心 AI 执行代码伤及本机 → Docker 沙箱 + Host/Container 双模式;
  • 想自托管、数据不出内网 → 自部署 + 一键备份恢复。

make start 之后,你的自托管 Claude Code 智能体工作台就可以 7×24 小时在线了。

登录后查看全文
happyclaw