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 余家厂商预设与自定义兼容端点，一个连接多个模型，轮询/加权/故障转移 |
| 定时任务 | Cron、固定间隔、一次性任务，智能体/Script 执行，隔离上下文，幂等立即运行，通知重试与失败去重，撞额度后自动继续 |
| 记忆与文件 | 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（独立对话或渠道原生话题）
└── 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。完整规则见业务模型。
执行模式
| 模式 | 适用对象 | 行为 |
|---|
| Host | 管理员授权的宿主机工作区 | 直接在指定本机目录运行，适合已有代码仓库和本机工具链 |
| Container | 普通成员与需要隔离的工作区 | 在非 root Docker 容器中运行，使用独立工作目录和预装工具链 |
普通成员不能把容器工作区降级为宿主机执行。Script 定时任务也只允许管理员在有权限的 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 |
渠道账号的凭据和扫码会话按用户、账号隔离。绑定规则为：
- 私聊和普通群绑定到工作区内的指定 Session，也可以选择主会话。
- 飞书话题群、Telegram Forum 绑定到 Workspace，每个原生话题映射独立 Session。
- 未绑定或已经解绑的渠道保持静默；默认工作区和历史话题记录不会恢复绑定。
飞书的“是否需要 @”与“响应所有人/仅主人”是两个独立维度。普通群始终沿用所绑定的
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 一致，避免上下文在模型之间漂移。
- 默认模型 — 在模型配置页点击某个配置的「默认」，未手动选择模型的会话固定使用它，
不再参与上述分配；再次点击取消，恢复自动分配。对话页的模型选择器默认选中「默认」。
定时任务
定时任务使用与交互会话相同的智能体、工作区和执行策略：
- 调度方式 — 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 可用时拉取最新的多架构智能体镜像。启动完成后打开：
http://localhost:3000
首次访问按照向导完成：
- 创建第一个管理员账户。
- 配置 Anthropic 官方账号或第三方 Claude 兼容 Provider。
- 可选添加飞书、Telegram、QQ、钉钉、微信、企业微信、Discord 或 WhatsApp 渠道账号。
- 进入工作台创建智能体、工作区和会话。
开发模式
make dev
开发模式同时启动后端和 Vite 前端：
常用运行命令
| 命令 | 说明 |
|---|
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 写入。
- Script 定时任务只允许管理员在授权的 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 都会执行：
- 三端
npm ci 可复现安装。
- 改动文件格式检查。
- 共享事件类型一致性检查。
- 后端、Web 和 Agent Runner 类型检查。
- 全量 Vitest 测试。
- 三端生产构建。
- Agent Runner 自检。
文档
常见问题
不一定。管理员只使用 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：
- Fork 本仓库并从
main 创建功能分支。
- 完成修改并补充相应测试。
- 运行
make typecheck && make test && make build。
- 确认
make format-check 通过。
- 提交 Pull Request，说明用户影响、验证方式和兼容性变化。
提交信息建议使用 Conventional Commits：
feat: add a new capability
fix: prevent duplicate task runs
docs: update provider setup guide
致谢
HappyClaw 是独立开源项目，与 Anthropic 及各消息平台不存在官方隶属、授权或背书关系。相关名称和商标归各自权利人所有。
License
MIT License © 2025–present riba2534
