happyclaw

HappyClaw

自托管、多用户、智能体优先的 Claude Code 工作台

让 Claude Code 通过 Web 与 8 种消息渠道长期在线，在宿主机或 Docker 沙箱中安全执行任务。

介绍 · 功能 · 快速开始 · 渠道 · 架构 · 开发 · 贡献

访问官网 · API 文档 · 运行时架构 · 权限矩阵 · 生产部署 · 问题反馈

HappyClaw 是什么

HappyClaw 是一个基于 Claude Agent SDK for TypeScript 的自托管 AI 智能体系统。它把完整的 Claude Code 运行时封装成一个可持续运行的多用户服务，让你可以从浏览器、飞书、Telegram、QQ、钉钉、微信、企业微信、Discord 或 WhatsApp 使用同一套智能体、工作区、能力和自动化任务。

HappyClaw 不是一个简单的聊天 API Wrapper。智能体运行在真实的 Claude Code 环境中，可以读写项目文件、执行终端命令、使用浏览器、调用 MCP、加载 Skills，并在多个独立工作区和会话之间保持清晰的权限与上下文边界。

为什么使用 HappyClaw

• Claude Code 原生运行时 — 直接使用版本锁定的 Claude Agent SDK 与 Claude Code CLI，不重新实现工具调用和运行循环。
• 智能体优先工作台 — 智能体管身份和能力，工作区管文件与执行环境，会话管对话上下文，产品层级清晰。
• 随时可访问 — Web、PWA 和 8 种 IM 渠道统一接入，任务完成后可以主动把结果送回消息渠道。
• 多用户与多账号 — 用户、渠道凭据、工作区及其 Memory、Skills、MCP 和运行数据彼此隔离。
• 宿主机与容器双模式 — 管理员可以使用授权的本机项目目录，普通成员默认在 Docker 沙箱中运行。
• 面向长期运行 — 提供调度任务、运行历史、消息回执、故障恢复、用量统计、监控与一致性备份。

功能总览

智能体优先工作模型

HappyClaw 使用统一的 智能体 → Workspace → Runtime Session 层级：

智能体（身份、提示词、Skills、MCP）
└── Workspace（项目目录、执行模式、环境变量、渠道挂载）
    ├── Workspace Memory（跨 Session 的事实、决策、经验、待跟进）
    ├── Main Session（工作区主会话）
    ├── Runtime Session（独立对话或渠道原生话题）
    └── Scheduled Run（定时任务的普通或隔离运行）

• 内置 HappyClaw 是不可删除的平台主 Agent，拥有代码级固定身份，理解 Workspace、Session、Agent Builder、渠道、任务、Skills/MCP、Provider 和权限 模型；这些规则不存放在可遗忘的 Memory 中。
• 首次唤醒 只面向 Home Workspace 中经过宿主验证的实际 owner。HappyClaw 用简短的“刚醒来”话语询问称呼，并通过专用 Owner Profile 保存；并发会话使用 onboarding lease，后续新 Session 或服务重启不会重复表演。清空称呼也不会重置 onboarding。
• 智能体 保存长期身份和能力策略。主 HappyClaw 智能体始终存在，也可以创建代码审查、研究、运维等自定义智能体。
• 对话式智能体构建器 在主 HappyClaw 名下的所有 Workspace 主会话与普通 Runtime Session 中生效，允许用户多轮讨论需求、保存并预览智能体草稿，并在后续人类消息逐字回复一次性确认口令后创建或更新智能体；定时任务与 Sub-Agent 不能代替用户发布。
• Home Workspace 是不可删除的系统工作区，并永久归属内置 HappyClaw。
• 自定义 Agent 创建后没有隐式 Workspace、Session 或 Memory；用户需要显式 新建 Workspace 或迁移一个非 Home Workspace，避免继承 HappyClaw 上下文。
• Workspace 是私有的文件与执行隔离边界。创建时必须选择智能体，非 Home Workspace 后续可以迁移归属；文件、Session、渠道绑定和 Memory 会随 Workspace 保留。
• Workspace Memory 是该工作区跨 Session 复用的结构化知识，不是用户全局记忆，也不是任意文件或日期归档。主人称呼由 Home 专用 Owner Profile facade 管理，不出现在通用 Memory 搜索、快照或修改接口中。
• Runtime Session 是工作区内的一段独立对话上下文，不是另一个顶层智能体；Session 历史与 Workspace Memory 分开保存，忘记一条 Memory 不会删除聊天历史。
• Channel Mount 将私聊、普通群显式绑定到具体 Session，将话题群绑定到 Workspace，再按话题映射 Session。完整规则见业务模型。

执行模式

普通成员不能把容器工作区降级为宿主机执行。Script 定时任务也只允许管理员在有权限的 Host 工作区运行。

管理员可在 设置 → 宿主机集成 开启“管理员纯宿主机模式”。开启时，当前管理员拥有的 工作区和定时任务会统一迁移为 Host，后续也不能再选择 Docker；普通成员继续使用 Docker 隔离。关闭开关只恢复混合模式的选择能力，不会自动迁回已有工作区。

智能体与能力治理

智能体配置（Agent Profile）

每个自定义智能体都可以配置：

• 名称、头像和 Claude 原生 preset。
• 身份、目标、工作方式和输出要求等结构化提示词。
• AI 生成提示词、局部优化、版本记录和历史版本恢复。
• 托管 Claude 上下文或管理员宿主机 Claude 上下文。
• 用户 Skills、HappyClaw MCP 与 Claude Code Plugins；智能体始终拥有完整工具权限。

配置页可以针对具体工作区预览最终生效能力，包括项目 CLAUDE.md、.claude/skills、项目 MCP、用户能力和同名覆盖来源。

Skills、MCP 与 Plugins

HappyClaw 区分不同层级的能力来源：

内置 MCP 工具覆盖消息发送、定时任务、渠道查询、Skill 管理和记忆读写；实际开放的工具会根据用户权限、智能体策略、工作区模式和渠道上下文动态裁剪。

渠道接入

每个用户都可以为同一渠道创建多个 Bot 账号，并为渠道会话显式选择绑定目标。 连接账号或发现聊天不会自动绑定，也不会触发回复。账号身份会写入渠道地址和 mount， 发送时不会借用其他 Bot 的凭据。

渠道账号的凭据和扫码会话按用户、账号隔离。绑定规则为：

1. 私聊和普通群绑定到工作区内的指定 Session，也可以选择主会话。
2. 飞书话题群、Telegram Forum 绑定到 Workspace，每个原生话题映射独立 Session。
3. 未绑定或已经解绑的渠道保持静默；默认工作区和历史话题记录不会恢复绑定。

飞书的“是否需要 @”与“响应所有人/仅主人”是两个独立维度。普通群始终沿用所绑定的 Session，需要 @ 时也不会另建话题 Session。话题群按话题隔离上下文。

每条输入独立保存回复来源：私聊、群聊、话题回复回到收到该输入的同一聊天、话题和 Bot 账号；Web 输入只在对应 Web Session 回复。多个渠道可以共享一个 Session， 但不同来源的输入分批执行，旧渠道归属或后续输入不能改写当前回复目标。

在已经绑定且支持斜杠命令的渠道中，可以使用 /list、/status、/where、/bind、/unbind、/new、/clear 和 /fresh 管理当前上下文。/fresh [备注] 会开启新的 SDK 窗口并写入零摘要交接说明，旧历史仍留在库中。飞书里，Agent 忙碌时的普通消息会静默自然排队；在群聊中真实 @Bot /steer 可立即引导当前任务，真实 @Bot /break 可停止当前任务并取消此前已经排队的消息。两条 Runtime 控制命令只接受精确小写形式。写操作受工作区 owner 和渠道发言者策略约束。

模型与提供商

HappyClaw 可以同时配置多个 Claude Provider，并为新会话按策略选择健康的 Provider。

第三方 Provider 会自动预填 Claude Code 兼容环境变量，包括主模型映射、上下文窗口、自动压缩、超时和非必要流量设置。高级设置会展示所有预填值，用户可以编辑、恢复默认值或增加自定义 Header 等环境变量。

负载均衡支持：

• Round Robin — 在健康 Provider 之间轮询。
• Weighted Round Robin — 按权重分配新会话。
• Failover — 优先使用主 Provider，故障时切换。
• 健康恢复 — 连续失败后暂时摘除，经过恢复窗口重新探测。
• 会话粘性 — 已开始的会话保持 Provider 一致，避免上下文在模型之间漂移。

定时任务

定时任务使用与交互会话相同的智能体、工作区和执行策略：

• 调度方式 — Cron、固定间隔和一次性时间点；间隔任务最短 60 秒。
• 执行类型 — 智能体任务运行完整 Claude Agent；Script 任务直接执行 Shell。
• 上下文模式 — group 注入工作区主会话；isolated 每次创建独立队列、Claude session 和 IPC 命名空间。
• 立即运行 — Web、REST 和 MCP 共用幂等键与稳定 runId，网络重试不会重复执行。
• 运行控制 — 支持暂停、恢复、编辑、停止当前运行、软删除和恢复任务。
• 持久化历史 — 记录执行状态、耗时、结果、尝试次数、通知状态和错误。
• 通知重试 — 执行结果和通知状态分离；通知失败只重试通知，不会重新执行任务。
• 异常恢复 — 服务重启后通过持久化运行记录和租约识别、恢复或终止遗留任务。

REST 接口和状态字段见 API 文档。

快速开始

环境要求

• macOS 或 Linux；Windows 推荐使用 WSL2。
• Node.js 20 或更高版本，推荐使用 CI 同款 Node.js 24。
• npm 与 GNU Make。
• Docker：普通成员和 Container 工作区需要；仅使用管理员 Host 工作区时可不安装。

macOS 可以使用 OrbStack 或 Docker Desktop，Linux 可以使用 Docker Engine。

Claude Code CLI 不需要单独安装。项目依赖中已经包含与 Claude Agent SDK 配套、版本锁定的 Claude Code 运行时。

安装并启动

git clone https://github.com/riba2534/happyclaw.git
cd happyclaw
make start

首次启动会自动安装三端依赖、编译后端/Web/Agent Runner，并在 Docker 可用时拉取最新的多架构智能体镜像。启动完成后打开：

首次访问按照向导完成：

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

开发模式

make dev

开发模式同时启动后端和 Vite 前端：

• Web 前端：
• API / WebSocket：

常用运行命令

Agent 镜像只在 GitHub Actions 中构建和发布，用户机器不执行 docker build。 make dev 和 make start 启动时都会从 Docker Hub 拉取 CONTAINER_IMAGE； 也可以提前直接执行：

docker pull riba2534/happyclaw-agent:latest

main 分支每次推送都会重新构建 riba2534/happyclaw-agent（amd64/arm64）。两个架构会分别在 GitHub 原生 x64 与 ARM64 Hosted Runner 上并行构建，不使用 QEMU 模拟。每个 runner 先推送没有 用户标签的 digest candidate，真实启动不可变 Runner、执行本地 fake provider SDK/CLI query，并在首次调用 agent-browser 后验证 /json/version；两边都验证通过 后才合并、签名并提升 git- 和 latest manifest。默认 core 镜像不携带未启用 的 Headroom Python 依赖；配置了 headroom MCP 的智能体会选择同版本 -headroom 镜像。Claude Code、Claude Agent SDK、agent-browser、feishu-cli、uv 和 Headroom 均使用源码锁定版本；实际安装版本记录在镜像内的 /usr/local/share/happyclaw-tool-versions.txt，需要回滚时也可以通过 Docker build args 在发布工作流中指定精确版本。

配置与数据

HappyClaw 优先通过 Web 设置管理配置，不要求用户维护一组庞大的环境变量。

Web 设置入口

可选环境变量