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 对话式创建/编辑、自定义智能体、内置模板、复制与导入导出、头像、结构化提示词、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，拥有代码级固定身份，理解

• 首次唤醒 只面向 Home Workspace 中经过宿主验证的实际 owner。HappyClaw

• 智能体 保存长期身份和能力策略。主 HappyClaw 智能体始终存在，也可以创建代码审查、研究、运维等自定义智能体。
• 对话式智能体构建器 在主 HappyClaw 名下的所有 Workspace 主会话与普通 Runtime Session 中生效，允许用户多轮讨论需求、保存并预览智能体草稿，并在后续人类消息逐字回复一次性确认口令后创建或更新智能体；自动化运行与 Sub-Agent 不能代替用户发布。
• Home Workspace 是不可删除的系统工作区，并永久归属内置 HappyClaw。
• 自定义 Agent 创建后没有隐式 Workspace、Session 或 Memory；用户需要显式

• Workspace 是私有的文件与执行隔离边界。创建时必须选择智能体，非 Home

• 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；智能体始终拥有完整工具权限。

配置页可以针对具体工作区预览最终生效能力，包括项目 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. 未绑定或已经解绑的渠道保持静默；默认工作区和历史话题记录不会恢复绑定。

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

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

模型与提供商

HappyClaw 可以同时配置多个模型连接。一个连接对应一份凭据和一个地址，可以提供多个模型。 「设置 → 模型配置」只负责添加和维护连接；用哪个模型由智能体决定：主 HappyClaw 和每个 智能体各有自己的默认模型和推理等级，聊天时还可以临时换成任何一个已添加的模型。

点「添加模型连接」，向导会依次选择来源、连接、选择模型、测试并保存：

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

选择模型这一步可以搜索、全选或清空，并为每个模型设置上下文长度和可选的推理等级； 能力表不认识的模型会按同系列推断，也可以手动声明。子代理和后台轻量调用默认跟随当前 模型，也可以指定为本连接的另一个模型。上下文长度大于 200K 时，运行时自动给模型名加 Claude Code 的 [1m] 开关，再按实际长度设置压缩窗口，模型名本身不需要改。

环境变量只预填 API_TIMEOUT_MS、CLAUDE_CODE_NO_FLICKER 和 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC，可以修改或删除，也可以增加自定义 Header 等； 没有保存的变量运行时不会注入。保存前会测试连接，密钥无效时不能保存；连接列表显示最近 一次测试的结果。

自动化

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

• 计划 — 每 N 分钟、每小时、每天、工作日、每周、每月（Cron 定时）、上次完成后

• 运行会话 — 绑定已有会话（默认当前会话，回复回到它的来源，例如飞书话题）、每次

• 结束 — 可写停止条件，Agent 每次运行先核实，满足后自己结束自动化；也可设结束时间。
• 安静模式 — 检查没事不说话：没有变化的运行不通知；失败总是通知，同一错误只通知

• 前置检查与脚本 — 管理员的 Host 工作区可加一条命令，退出码 0 执行、2 跳过（不耗

• 可靠性 — 同一自动化不会重叠运行；服务停机期间错过的周期运行记为「已错过」，

REST 接口见 API 文档。

快速开始

环境要求

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

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：

常用运行命令

| 命令 | 说明 | | ----------------------------------------------- | ----------------------------------------------------- | | 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- 和 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/。

反向代理配置

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 与运行快照的历史设计 |

常见问题

贡献

欢迎提交 Issue 和 Pull Request：

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

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 提交者和贡献者。

License

MIT License © 2025–present riba2534

如果 HappyClaw 对你有帮助，欢迎点一个 Star ⭐