HealthClaw

面向国内用户的私人 AI 助手，融合 CoPaw 与 OpenClaw 优势，支持技能树、国内通道（钉钉/飞书/QQ）与一体式 Web 控制台。

（本项目由 SangClaw 更名而来，产品名、包名、配置目录与环境变量已统一为 HealthClaw。）

项目结构

• bff/ - BFF 层（HTTP API，对接 OpenClaw Gateway WebSocket；未配置时使用 mock）
• console/ - 前端控制台（React + Vite + Ant Design）

快速开始

方式一：一键启动（内嵌 OpenClaw，推荐）

安装后无需单独部署 OpenClaw，Gateway 由 HealthClaw 自动拉起：

cd /path/to/healthclaw
npm install
npm run dev:with-gateway

或使用安装/启动脚本（需先 chmod +x scripts/*.sh）：

./scripts/install.sh   # 检查环境、安装依赖
./scripts/start.sh     # 启动 Gateway + BFF + Console，并尝试打开浏览器

首次使用请先在浏览器打开 http://127.0.0.1:5174（若 5174 被占用会使用 5175 等），进入侧边栏「初始化」，选择模型提供商、填写 API Key 并保存（模型 ID 会按提供商自动带出，可留空）。保存后连接会自动重试，无需重启；若未连接可点「刷新状态」或展开「连接诊断」查看配置路径。

• 配置写入：项目目录或 OPENCLAW_HOME/HEALTHCLAW_CONFIG_HOME 下的 .openclaw/openclaw.json（模型）、.healthclaw/.env（API Key，仅本机，不入库）
• Gateway 由 HealthClaw 自动拉起（通过 npx openclaw gateway，首次运行可能拉取 openclaw），端口默认 18789
• 项目不将 openclaw 列为依赖，以保持 npm audit 无漏洞；Gateway 由 npx 或用户全局安装的 openclaw 提供

方式二：仅启动 BFF + Console（连接已有 Gateway）

若你已在其他终端启动了 OpenClaw Gateway（例如 openclaw gateway --port 18789），只需：

npm install
npm run dev

• BFF: http://127.0.0.1:3080
• Console: http://127.0.0.1:5174（代理 /api 到 BFF）

浏览器打开 http://127.0.0.1:5174 即可使用。未连接 Gateway 时，聊天为 mock 回复，页面会提示「去初始化」。

若连接时报「invalid connect params」或「device identity required」：在 OpenClaw 的 ~/.openclaw/openclaw.json 中配置 gateway.auth.token，并在 BFF 的 bff/.env 中设置 OPENCLAW_GATEWAY_TOKEN 为同一值即可。详见 docs/openclaw-minimax.md。

---

对接真实 OpenClaw Gateway（含 Minimax，方式二时参考）

若你选择方式二，要让聊天使用真实模型（如 Minimax），需要先单独启动 OpenClaw Gateway。

1. 安装并配置 OpenClaw

npm install -g openclaw@latest
openclaw onboard --install-daemon   # 按向导完成，或手动配置

2. 配置 Minimax 模型与 API Key

在 OpenClaw 的配置目录（如 ~/.openclaw/openclaw.json）中配置默认模型为 Minimax，并通过环境变量传入 API Key（不要写进代码库）：

export MINIMAX_API_KEY="你的-Minimax-API-Key"
openclaw gateway --port 18789 --verbose

或在 openclaw.json 里配置 agent.model 为 Minimax 对应模型标识，并在运行 openclaw gateway 的终端/环境中设置 MINIMAX_API_KEY。具体字段名以 OpenClaw 官方文档为准。

3. 启动 HealthClaw

在另一个终端执行 npm run dev（或使用方式一的 npm run dev:with-gateway 由 HealthClaw 自动起 Gateway）。浏览器打开 http://127.0.0.1:5174，在「聊天」里发送消息即可走真实 Gateway + Minimax。

4. 环境变量（可选）

• BFF 启动前：在项目根或 bff/ 下通过 .env 或环境变量配置：
  • OPENCLAW_GATEWAY_URL：Gateway WebSocket 地址，默认 ws://127.0.0.1:18789
  • OPENCLAW_GATEWAY_TOKEN：若 Gateway 需要鉴权则填写（也可在 openclaw.json 的 gateway.auth.token 中配置，BFF 会多路径读取）
  • OPENCLAW_HOME：OpenClaw 配置目录，默认使用项目目录下的 .openclaw
  • HEALTHCLAW_CONFIG_HOME：HealthClaw 配置目录，默认使用项目目录下的 .healthclaw
  • BFF_PORT：BFF 端口，默认 3080
• 注意：API Key 通过「初始化」或「设置」页写入 .healthclaw/.env，不要提交到仓库；.env、.openclaw、.healthclaw 已加入 .gitignore。

---

技能导入与安全扫描

从「技能树」页通过从文件导入（ZIP/.skill）或从 URL 安装时，会在导入当时进行健康检查：

• 轻量扫描（内置）：扩展名与文本内容检查，允许含脚本的技能包，仅禁止二进制。
• 深度扫描（可选）：若已安装 cisco-ai-defense/skill-scanner 并配置 HEALTHCLAW_SKILL_SCANNER_CLI（或系统 PATH 中存在 skill-scanner），会对其执行扫描；未配置时不阻断导入。安装方式示例：pip install cisco-ai-skill-scanner 或见官方仓库。

扫描时机：仅在导入/安装时执行，不在技能执行时再次扫描。详见 docs/产品安全方案-技能与AI应用.md。

---

后续迭代

• 国内通道扩展（钉钉、飞书、QQ）真实收发
• 技能树、Playbook、AI 应用对接等见根目录策略文档。