HappyClaw

---

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 对话式创建/编辑、自定义智能体、内置模板、复制与导入导出、头像、结构化提示词、AI 优化
工作区	智能体归属、宿主机/容器执行、独立目录、项目环境变量、项目 Claude 上下文、多会话、会话级 git worktree、只读代码 Review
能力治理	用户 Skills、系统/用户 MCP、Claude Code Plugins 与最终生效预览；智能体工具权限完整开放
消息渠道	飞书、Telegram、QQ、钉钉、微信、企业微信、Discord、WhatsApp，多账号、扫码登录、工作区/会话绑定
模型提供商	Anthropic 官方、ChatGPT 订阅、20 余家厂商预设与自定义兼容端点，一个连接多个模型，轮询/加权/故障转移
自动化	按计划在真实会话里运行一轮：绑定当前会话或新建会话，停止条件、安静模式、前置检查，失败去重通知，撞额度后自动继续
记忆与文件	Workspace Memory（事实、决策、经验、待跟进）、按相关性召回与常驻目录、非主人写入待确认、来源与修订、CAS 编辑、搜索、文件与终端
用量与计费	Token 分类统计、缓存命中率、智能体/工作区/模型筛选、明细与 CSV 导出、订阅、余额、兑换码与配额
运维与安全	RBAC、邀请注册、登录设备、审计日志、运行监控、Docker 镜像管理、备份与安全恢复
客户端体验	实时流式输出、工具轨迹、富文本输入框（列表、/ 技能、@ 文件、长文本折叠、排队）、Markdown/Mermaid/KaTeX、PWA

智能体优先工作模型

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

智能体（身份、提示词、Skills、MCP）
└── Workspace（项目目录、执行模式、环境变量、渠道挂载）
    ├── Workspace Memory（跨 Session 的事实、决策、经验、待跟进）
    ├── Main Session（工作区主会话）
    ├── Runtime Session（独立对话或渠道原生话题）
    └── Automation（自动化，每次运行都是某个会话里的一轮）

• 内置 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。完整规则见业务模型。

执行模式

模式	适用对象	行为
Host	管理员授权的宿主机工作区	直接在指定本机目录运行，适合已有代码仓库和本机工具链
Container	普通成员与需要隔离的工作区	在非 root Docker 容器中运行，使用独立工作目录和预装工具链

普通成员不能把容器工作区降级为宿主机执行。自动化的脚本和前置检查也只允许管理员在有权限的 Host 工作区运行。

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

智能体与能力治理

智能体配置（Agent Profile）

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

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

智能体可以从内置模板新建、复制，或导出为 JSON 再导入；导入时引用不到的 Skill 或 MCP 会逐项列出，由用户确认去掉后再创建。

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

Skills、MCP 与 Plugins

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

来源	说明
内置能力	随 HappyClaw 或智能体容器提供的基础工具与 Skills
用户 Skills	从技能市场、HTTPS Git 仓库或 ZIP 导入，按用户隔离并记录来源与版本
项目上下文	工作区目录里的 CLAUDE.md、.claude/skills 和 MCP 配置
用户 MCP	当前用户维护的 MCP Server，只进入允许使用它的智能体
系统 MCP	管理员维护，默认仅管理员可用，显式共享后普通成员才能使用
Claude Code Plugins	系统 catalog 与用户启用状态分离，通过版本化运行快照加载

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

添加远端服务时，参见远端 MCP 配置与排查，按步骤填写 HTTP/SSE URL 与 Headers、选择作用域，并在指定智能体的最终生效能力中确认来源。

渠道接入

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

渠道	接入方式	主要能力
飞书	App ID / App Secret，WebSocket	流式卡片、图片与文件、Reaction、群聊 @ 控制、话题映射
Telegram	Bot Token，Long Polling	Markdown/HTML、长消息分片、图片与文件、代理配置
QQ	App ID / App Secret，WebSocket	私聊、群聊 @Bot、图片消息、配对码绑定
钉钉	Client ID / Client Secret，Stream	AI Card 流式回复、图片与文件、群聊 @ 控制
微信	Web 界面扫码，iLink	二维码授权、媒体收发、Typing、断线恢复
企业微信	Bot ID / Secret，WebSocket	Markdown 流式回复、图片与文件、群聊 @ 控制、配对码绑定
Discord	Bot Token，Gateway	私聊与服务器频道路由、多账号隔离、频道信息查询
WhatsApp	Web 界面扫码，Baileys	二维码登录、文本与媒体、会话持久化、断线恢复
Web	浏览器与 WebSocket	实时 Markdown、文件、终端、工具轨迹、PWA

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

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 可以同时配置多个模型连接。一个连接对应一份凭据和一个地址，可以提供多个模型； 聊天和智能体按「连接 · 模型」选择。在「设置 → 模型配置」点「添加模型连接」，向导会依次 选择来源、连接、选择模型、测试并保存：

类型	配置方式
Anthropic 官方	Claude 订阅（OAuth、setup-token / .credentials.json）或 API Key
ChatGPT 订阅	登录 ChatGPT，按账号可用的模型目录选择模型和推理力度
厂商预设	DeepSeek、智谱 GLM、Kimi、MiniMax、阿里云百炼、火山、腾讯、OpenRouter 等，只需填 API Key
自定义兼容端点	填写地址和密钥，自动识别预设、判断认证方式、获取模型列表，可启用 1M 上下文

保存前会测试连接，密钥无效时不能保存；连接列表显示最近一次测试的结果。

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

负载均衡支持：

• Round Robin — 在健康 Provider 之间轮询。
• Weighted Round Robin — 按权重分配新会话。
• Failover — 优先使用主 Provider，故障时切换。
• 健康恢复 — 连续失败后暂时摘除，经过恢复窗口重新探测。
• 会话粘性 — 已开始的会话保持 Provider 一致，避免上下文在模型之间漂移。
• 默认模型 — 在模型配置页点击某个配置的「默认」，未手动选择模型的会话固定使用它， 不再参与上述分配；再次点击取消，恢复自动分配。对话页的模型选择器默认选中「默认」。

自动化

自动化按计划把一段提示词作为真实的一轮发进会话，用法与 cindy 的 Automations 一致。 在聊天里直接说「每天 21 点检查新剧集，全部下完就停」，Agent 就会建一个绑定当前会话的 自动化；也可以在 Web 的「自动化」页、会话菜单或 ⌘K 里创建。

• 计划 — 每 N 分钟、每小时、每天、工作日、每周、每月（Cron 定时）、上次完成后 再等一段时间（相对间隔，至少 1 分钟）、一次，或只手动运行。
• 运行会话 — 绑定已有会话（默认当前会话，回复回到它的来源，例如飞书话题）、每次 新建或持续会话；每次运行都能「打开会话」继续聊。
• 结束 — 可写停止条件，Agent 每次运行先核实，满足后自己结束自动化；也可设结束时间。
• 安静模式 — 检查没事不说话：没有变化的运行不通知；失败总是通知，同一错误只通知 一次，恢复后再通知一次。
• 前置检查与脚本 — 管理员的 Host 工作区可加一条命令，退出码 0 执行、2 跳过（不耗 token）；也可以只运行脚本。
• 可靠性 — 同一自动化不会重叠运行；服务停机期间错过的周期运行记为「已错过」， 不补跑；撞用量上限时排队等待自动继续。

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 可用时拉取最新的多架构智能体镜像。启动完成后打开：

http://localhost:3000

首次访问按照向导完成：

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

开发模式

make dev

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

• Web 前端：http://localhost:5173
• API / WebSocket：http://localhost:3000

常用运行命令

命令	说明
make start	构建必要产物并以前台生产模式启动
WEB_PORT=8080 make start	使用自定义端口启动
make status	查看端口、健康状态、日志文件和 Docker 容器
make stop	停止当前端口上的 HappyClaw 服务
make docker-pull	拉取 GitHub Actions 发布的最新 Agent 镜像
make install-host-tools	安装 Host 工具并刷新 Host/Container 共用的内置 Skills
make backup	创建一致性运行数据备份
make restore FILE=happyclaw-backup-xxx.tar.gz	停止服务后恢复指定备份
make help	查看完整命令列表

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-<sha> 和 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 设置入口

页面	内容
设置 → 模型配置	模型连接、每个连接的模型、连接测试和负载均衡
设置 → 消息渠道	渠道账号、扫码登录、连接状态和会话绑定
设置 → 主 HappyClaw	默认智能体的 Skills 与 MCP
设置 → 执行与容量	超时、并发、上下文窗口和运行限制
设置 → 宿主机集成	管理员纯宿主机模式、Host 目录与 Claude 上下文来源
设置 → 注册策略	开放注册、邀请码注册或关闭注册
设置 → 用户与访问	用户、权限、邀请码与审计日志

可选环境变量

变量	默认值	说明
WEB_PORT	3000	Web、REST API 与 WebSocket 端口
WEB_SESSION_SECRET	自动生成并持久化	Web 登录会话签名密钥
CONTAINER_IMAGE	riba2534/happyclaw-agent:latest	智能体容器镜像
CONTAINER_IMAGE_HEADROOM	从 core 标签派生 -headroom	启用 Headroom MCP 时使用的同版本能力镜像
CONTAINER_TIMEOUT	1800000	容器硬超时，毫秒
IDLE_TIMEOUT	1800000	容器空闲保活时间，毫秒
STUCK_RUNNER_FORCE_RESTART_MINUTES	10	IPC 债务强制恢复上限（整数分钟，范围 4–120；非法值回退默认）
ADMIN_HOST_ONLY_MODE	false	管理员工作区与任务强制使用宿主机
MAX_CONCURRENT_CONTAINERS	20	最大并发容器数
MAX_FILE_SIZE_MB	50	Web 和 IM 入站文件大小上限
CORS_ALLOWED_ORIGINS	仅 localhost	公网部署的 WebSocket Origin 白名单
TRUST_PROXY	false	位于可信反向代理后时设为 true
TRUST_PROXY_HOPS	1	X-Forwarded-For 中可信代理层数（Cloudflare 在 Caddy 之前时设为 2）
TZ	系统时区	日志与自动化时区（建议 IANA 名称，如 Asia/Shanghai）；无效值回退并告警
HTTPS_PROXY / HTTP_PROXY	未设置	独立配置 HTTPS/HTTP 出站代理；主进程与每个智能体容器都会使用，也接受对应的小写变量
NO_PROXY	未设置	独立配置不走代理的地址列表，也接受 no_proxy

Provider 与渠道凭据建议只在 Web 设置中填写。它们使用 AES-256-GCM 加密存储，相关 API 只返回是否已配置，不返回密钥明文。

容器代理值（包括 URL 中的用户名和密码）通过权限为 0600 的每容器运行时环境文件注入，不会出现在 docker run 参数或容器参数调试日志中。macOS 的 Docker Desktop/OrbStack 与 Windows Docker Desktop 会把代理 URL 中的 localhost、127.0.0.1、::1 改写为 host.docker.internal。Linux bridge 容器无法访问宿主机仅绑定在回环地址的代理；请将代理绑定到 Docker bridge 可达接口，并在代理变量中使用该接口的 IP 或 DNS 名称，否则容器会在启动前给出错误。

运行数据

所有持久化运行数据默认位于 data/：

data/
├── db/messages.db     # SQLite 主数据库（含 Workspace Memory v2）
├── config/            # 加密配置、密钥与系统设置
├── groups/            # 工作区目录和项目文件
├── memory/            # 旧版文件记忆，仅供离线迁移/归档
├── sessions/          # 主会话与 Runtime Session 的 Claude 数据
├── ipc/               # Runner 输入、工具请求和回执
├── skills/            # 用户 Skills
├── builtin-skills/    # 固定版本内置 Skills 清单
├── mcp-servers/       # 用户 MCP 配置
├── plugins/           # Plugin catalog、用户状态与运行快照
└── extra/             # Container 工作区持久工具数据

不要把 data/ 提交到 Git。迁移实例时优先使用 make backup 和 make restore；恢复流程会检查归档路径、文件类型、符号链接、清单和数据库完整性。

系统架构

flowchart LR
    Web["Web / PWA"] --> Core["HappyClaw Node Service"]
    IM["8 个 IM 渠道"] --> Core

    Core --> Auth["Auth / RBAC"]
    Core --> Router["消息路由与会话队列"]
    Core --> Scheduler["任务调度与恢复"]
    Core --> DB[("SQLite + Workspace Data")]

    Router --> Providers["Provider Pool"]
    Scheduler --> Router
    Providers --> Host["Host Runner"]
    Providers --> Container["Docker Agent Runner"]

    Host --> SDK["Claude Agent SDK / Claude Code"]
    Container --> SDK
    SDK <--> MCP["Built-in MCP / IPC"]
    MCP --> Core

    Core --> Stream["WebSocket / Channel Reply"]
    Stream --> Web
    Stream --> IM

主服务始终使用 Node.js 运行，负责认证、路由、队列、调度、渠道连接、Provider 池、用量和持久化。Docker 只用于隔离智能体执行环境，不承载 HappyClaw 主服务。

技术栈

层	技术
主服务	Node.js、TypeScript、Hono、WebSocket、SQLite
智能体运行时	Claude Agent SDK、Claude Code CLI、MCP、文件 IPC
Web	React 19、Vite、Tailwind CSS、Radix UI、Zustand、原生 SVG 图表、xterm.js
渠道	Feishu SDK、grammY、QQ Bot API、DingTalk Stream、企业微信智能机器人 SDK、Discord.js、Baileys、微信 iLink
隔离执行	Docker、非 root Node.js 容器、Chromium、常用开发与浏览器工具
质量保障	TypeScript、Vitest、Prettier、GitHub Actions

安全模型

HappyClaw 会执行代码和访问第三方消息平台，部署前请理解以下边界：

• 用户、渠道账号、工作区及其 Memory、Skills、MCP、Plugin 状态和用量记录按 owner 隔离。
• Provider 与渠道密钥使用本机 AES-256-GCM 密钥加密，密钥文件权限限制为 0600。
• REST、WebSocket、IM 命令和 MCP 工具分别执行身份、owner、角色与能力策略检查。
• 普通成员固定使用 Container 模式；管理员 Host 模式只允许访问授权目录。
• 智能体的通用代码与文件工具不提供全局只读模式；Skills 与 MCP 是否启用由用户显式选择。Workspace Memory 控制面是例外：自动化运行与群成员轮次只能提议（待主人确认），Sub-Agent 只能读取，只有顶层交互式 Session 可以按 Workspace ACL 写入。
• 自动化的脚本与前置检查只允许管理员在授权的 Host 工作区执行。
• Skill ZIP、文件上传、备份恢复和 Git 操作包含路径、符号链接、大小与目标校验。
• 对公网开放时，建议使用 HTTPS 反向代理、强密码、关闭开放注册，并定期备份 data/。

完整接口权限见 ACL 权限矩阵。

反向代理配置

Web 界面依赖 /ws 上的 WebSocket 推送流式输出和运行状态。反向代理必须放行 Upgrade 并把该连接的读超时设得足够长，否则前端会周期性弹出「连接中断，正在重连...」。

服务端已内置 30 秒心跳（ping/pong），既用于保活，也用于回收半开的死连接， 因此代理侧只需把读超时设得高于心跳间隔即可。nginx 示例：

location /ws {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 3600s;   # 默认 60s 会掐断长连接
    proxy_send_timeout 3600s;
}

注意 Connection 应固定为 "upgrade"，不要写成 $http_connection——后者依赖 客户端如实发送该头部，行为不稳定。

若代理位于 Cloudflare 等平台之后，还需确认其空闲超时高于 30 秒心跳间隔。 上传大文件时另需放宽 client_max_body_size（不小于 MAX_FILE_SIZE_MB，并预留 multipart 开销）与 client_body_timeout。

位于反向代理之后必须设置 TRUST_PROXY=true，否则所有请求都显示为代理自身的地址： 代理在另一台主机时，全部用户共用同一个按 IP 的登录限流桶，几十次失败即可锁住所有人； 代理在本机（loopback）时，按 IP 的限流不生效。开启后，客户端 IP（登录限流与审计日志 使用）取自 X-Forwarded-For 中由可信代理追加的那一项：右数第 TRUST_PROXY_HOPS 个 （默认 1，即 Caddy 或 nginx 直接面向用户时）。更靠左的条目由客户端提供，不被信任。

密码哈希与校验（登录、注册、初始化、修改密码、管理员创建用户或重置密码）在一个有界的 bcrypt 工作线程池中执行，最多同时排队 32 个任务。超出的突发请求会立即收到 HTTP 503 （服务繁忙，请稍后重试，带 Retry-After: 1），且不计入登录或注册限流次数； 客户端稍后重试即可。

开发与测试

常用命令

make install          # 安装主服务、Web 与 Agent Runner 依赖
make dev              # 启动开发环境
make typecheck        # 三端类型检查 + 共享类型/Prompt 引用校验
make test             # 运行 Vitest 测试
make format-check     # 检查本次改动涉及文件的格式
make build            # 构建后端、Web 与 Agent Runner
npm run self-test     # 构建 + Agent Runner 自检 + 全量测试

项目只使用 Node.js/npm 工具链，不使用 Bun。主服务依赖 Node.js 的 HTTP Upgrade 与 ws 完成 WebSocket 握手。

项目结构

happyclaw/
├── src/                         # 主服务、路由、调度、渠道、权限与持久化
├── web/                         # React Web/PWA
├── container/
│   └── agent-runner/            # Host/Container 共用的 Agent 执行器
├── shared/                      # 主服务与前端/Runner 共享的事件类型源
├── scripts/                     # 构建、校验、备份和恢复脚本
├── tests/                       # 后端、前端契约、迁移与安全回归测试
├── docs/                        # API、权限与设计文档
├── Makefile                     # 统一开发、构建和运维入口
└── data/                        # 本地运行数据，不进入 Git

CI 合并门槛

每个 Pull Request 都会执行：

1. 三端 npm ci 可复现安装。
2. 改动文件格式检查。
3. 共享事件类型一致性检查。
4. 后端、Web 和 Agent Runner 类型检查。
5. 全量 Vitest 测试。
6. 三端生产构建。
7. Agent Runner 自检。

文档

文档	用途
Web API	REST API、认证、任务、渠道账号、智能体、用量等接口
运行时架构	模块边界、依赖规则和性能预算
ACL 权限矩阵	HTTP、WebSocket 与 IM 命令的权限要求
远端 MCP 配置与排查	HTTP/SSE、Header、作用域、智能体生效确认与凭据保护
Workspace Memory v2	Workspace 知识边界、数据模型、并发和 UI 语义
智能体优先架构记录	智能体、工作区、运行会话与渠道挂载的迁移背景
Plugin 自动化设计记录	Claude Code Plugin catalog 与运行快照的历史设计

常见问题

不一定。管理员只使用 Host 工作区时可以不安装 Docker；普通成员和所有 Container 工作区需要 Docker。

不需要。官方 Agent 镜像会在每次发布时安装最新稳定版 Claude Agent SDK 和 Claude Code，并把实际版本写入 /usr/local/share/happyclaw-tool-versions.txt。固定版本的内置 Skills 会在 make install、make dev 和 make start 时自动物化，并由 Host/Container 共用同一 Manifest；其他 Host 工具可通过 make install-host-tools 安装。

可以。在“设置 → 模型配置”点“添加模型连接”：常见厂商直接选预设，只填 API Key；其他兼容接口选“自定义兼容地址”，填写地址和密钥后系统会识别认证方式、获取模型列表并测试连接。1M 上下文及 Claude Code 兼容环境变量由系统预填，也允许在连接设置中编辑。

运行 make backup 创建一致性归档。在目标实例停止服务后运行 make restore FILE=<备份文件>。不要在服务运行时直接复制 SQLite 文件。

生产模式运行 WEB_PORT=8080 make start。开发模式需要同时设置后端端口和 Vite 的 API/WebSocket 代理目标。

两类旧安装可能需要此工具：一是 #666 之前的受支持版本曾把 WhatsApp @c.us 及 device @c.us 私聊留在 workspace main；二是曾在 #659 的 WhatsApp LID 分类 修复之前单独部署或 cherry-pick #655/schema v73 的非正式安装。升级到当前版本后运行 make leftover-direct-mounts。诊断严格只读，并且只接受当前 schema；发现残留或 存在无法自动判定的 WhatsApp alias 路由冲突时以退出码 2 返回。为保证读取完整且绝不 创建 SQLite sidecar，诊断前也必须先干净停止 HappyClaw。

修复前还必须停止 launchd/systemd 等进程守护，然后运行 make leftover-direct-mounts APPLY=1。修复会把可判定私聊迁到独立 channel_direct session，并永久清除受污染 workspace main 的模型恢复资格和 SDK/runtime session；不会创建备份，也不能安全撤销。工具若无法确认数据库无人占用， 会拒绝执行。如果同一 WhatsApp canonical 用户的多个 alias 指向不同 owner、workspace 或 session，工具会 fail closed；请按诊断输出人工解绑冲突 alias 后重试，不会自动猜测 应保留哪条路由。

贡献

欢迎提交 Issue 和 Pull Request：

1. Fork 本仓库并从 main 创建功能分支。
2. 完成修改并补充相应测试。
3. 运行 make typecheck && make test && make build。
4. 确认 make format-check 通过。
5. 提交 Pull Request，说明用户影响、验证方式和兼容性变化。

提交信息建议使用 Conventional Commits：

feat: add a new capability
fix: prevent duplicate task runs
docs: update provider setup guide

致谢

• Anthropic Claude Code 与 Claude Agent SDK for TypeScript 提供完整的智能体运行时。
• 感谢所有渠道 SDK、开源依赖、Issue 提交者和贡献者。

HappyClaw 是独立开源项目，与 Anthropic 及各消息平台不存在官方隶属、授权或背书关系。相关名称和商标归各自权利人所有。

License

MIT License © 2025–present riba2534

---