Lobster-HomeAgent（龙虾家庭AI管家）

English documentation: README.en.md

⚠️ 强制说明：这是测试版本，请酌情使用

当前版本 v0.1.0-alpha.1 是测试版本：只完成了方案的第一阶段， 且从未在真实 Home Assistant 上验证过（所有测试都跑在内置的模拟环境上）。

请勿直接用于真实家庭，更不要依赖它做安全相关的判断。 这个软件会向真实设备下发控制指令，一次误判就可能造成后果。 燃气、门锁、安防等安全相关设备默认已被策略拒绝， 但请不要为了"试试看"去放开它们——那是本项目明确不负责的范围。

使用前请先读 DISCLAIMER.md（免责声明与安全警告）， 自行评估风险后酌情决定是否使用。作者不对使用后果负责。 强烈建议先用 HA_DRY_RUN=true 预演模式观察一段时间。

开发者：YeXiaoYe ｜ 联系：zqjqyq123@qq.com

基于 OpenClaw 二次开发、MCP 协议驱动、对接 Home Assistant 的全屋 AI 家庭管家。 本仓库是能力层：把 Home Assistant 的全屋设备能力，以 MCP 服务 + OpenClaw 插件两种形式暴露给 Agent， 并内置安全策略——只控制家电类设备（灯、窗帘、影音、空调等）； 燃气、阀门、门锁、安防等安全相关设备默认直接拒绝，不交给 AI。

只完成方案「第 1-2 个月：基础链路验证」阶段，详见已知限制。

授权模式为个人使用免费、企业商用收费（PolyForm Noncommercial 1.0.0）—— 源码可见，但不是 OSI 认证的开源项目，详见许可证。

Related MCP server: Enhanced Home Assistant MCP

当前进度

第一阶段已实现并通过测试的能力：

• 设备控制：查询实体、查状态、调服务、场景激活、模板统计、历史查询，共 10 个工具。

• 安全策略（范围控制）：只控制家电类设备。燃气 / 阀门 / 门锁 / 警报 / 安防面板 / 热水器 / 门窗类 cover 默认直接拒绝，模型连执行入口都拿不到；无法识别的敏感设备走 一次性令牌二次确认；shell_command 等能执行任意命令的 domain 一律拒绝。 支持预演模式与 domain 黑白名单，全部规则可配置。

• 两种接入方式：MCP stdio 服务器（方案里的「MCP 服务层」）与 OpenClaw 原生插件。

• 无硬件开发：内置 Mock Home Assistant（REST + WebSocket + 区域注册表），没有真设备也能跑通全链路。

• 区域语义：通过 WebSocket 注册表把「客厅」「主卧」解析成实体，支持自然语言按房间控制。

测试：59 项自动化测试全部通过，含 MCP 协议端到端用例（真起子进程、走完整 JSON-RPC 协议）。

已知限制（重要）

请在动手之前先读这一节，这个版本还不能当作可用的家庭管家。

已经做了但没有验证的：断线自动重连、区域过滤、历史查询在真实环境下的表现。

故障排查

认证失败：HA_TOKEN 无效或已过期 长期访问令牌不对或已撤销。在 Home Assistant「个人资料 → 安全性 → 长期访问令牌」重新生成。 注意令牌只在创建时显示一次。

无法访问 Home Assistant（...）：fetch failed 地址不通。确认 HA_BASE_URL 带上了端口（http://homeassistant.local:8123）， 且本机能访问该地址；HA 默认拒绝跨域以外的直连，但局域网内应当可达。

Agent 说找不到工具 / 工具列表里没有 ha_* 按顺序检查：openclaw mcp status --verbose 看 MCP 服务器是否连接成功； openclaw mcp tools lobster-home 看工具是否注册； 再确认没有同时启用 MCP 与插件（两条路工具同名，同时开会冲突）。

ha_list_entities 的 area 参数不生效 区域信息只能通过 WebSocket 注册表获取。如果 WebSocket 连不上（例如只允许 REST 的反向代理）， 工具会降级为忽略 area 并在返回里注明原因。检查 ws:// / wss:// 是否可达。

高危设备没有被拒绝，或者想控制的设备被拒绝了 先确认 HA_POLICY 或插件 policy 配置没有覆盖掉默认规则—— 一旦设置了 denyDomains / confirmDomains / denyCoverClasses， 它会替换默认值而不是追加。用 node dist/cli.js doctor 可以看到当前生效的规则。

想让某类设备从不允许变成允许，改 denyDomains；想从"直接执行"变成"必须确认"， 改 confirmDomains。注意安全兜底：即使把 lock 从 denyDomains 里去掉， 它仍会强制进入确认流程，不会被静默放行。

想让 Agent 先"空跑"看看它会做什么 设 HA_DRY_RUN=true（插件配置里是 dryRun: true），策略照常判定但不会真正下发指令。

Windows 上路径含空格 配置 mcp.servers 时 args 里的路径要写成 JSON 字符串（含转义反斜杠）， 用 openclaw mcp add 时把整个路径放在引号里。

环境要求

• Node.js ≥ 24.16（用到原生 TypeScript 运行、内置 WebSocket）

• 一个可访问的 Home Assistant 实例（本地部署即可），或使用内置 Mock 免硬件体验

一键安装

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/yxy123a/lobster-homeagent/main/install.sh | bash

Windows（PowerShell）

irm https://raw.githubusercontent.com/yxy123a/lobster-homeagent/main/install.ps1 | iex

脚本会检查 Node 版本（需 ≥ 24.16）、拉取代码、安装依赖、构建，并在检测到 openclaw 命令与 HA_BASE_URL / HA_TOKEN 时自动注册 MCP 服务。

不想盲跑脚本的话，先把脚本下载下来看一眼再执行：

curl -fsSL https://raw.githubusercontent.com/yxy123a/lobster-homeagent/main/install.sh -o install.sh
less install.sh          # 看完再执行
bash install.sh

常用参数与环境变量：

⚠️ 安装脚本目前尚未被任何人实际执行过（写完之后没跑过，包括作者）。 它会在 CI 里做冒烟测试（Linux + Windows 各跑一遍）， 但第一次在你机器上运行时如果报错，请直接提 issue。

快速开始

# 1. 安装依赖
npm install

# 2. 构建
npm run build

# 3. 无硬件体验：另开一个终端启动 Mock Home Assistant
npm run mock-ha            # 默认监听 8123，输出 HA_BASE_URL 与 HA_TOKEN

# 4. 用 CLI 验证链路
set HA_BASE_URL=http://127.0.0.1:8123
set HA_TOKEN=mock-token
node dist/cli.js doctor
node dist/cli.js states light
node dist/cli.js call light turn_on light.zhuwo_deng "{\"brightness_pct\":70}"

Linux / macOS 把 set VAR=value 换成 export VAR=value。 仓库里的代码不依赖任何平台特有 API，Windows / Linux / macOS 都能跑。

接入真实 Home Assistant：在 HA 里「个人资料 → 安全性 → 长期访问令牌」新建令牌， 然后设置 HA_BASE_URL（如 http://homeassistant.local:8123）与 HA_TOKEN。

接入 OpenClaw

两种方式注册的工具完全相同，二选一即可，同时启用会出现重名工具。

方式 A：MCP 服务（推荐，对应方案的「MCP 服务层」）

# Windows (cmd)
openclaw mcp add lobster-home ^
  --command node ^
  --arg "C:\path\to\lobster-homeagent\dist\mcp\server.js" ^
  --env HA_BASE_URL=http://homeassistant.local:8123 ^
  --env HA_TOKEN=<你的长期访问令牌>

# Linux / macOS
openclaw mcp add lobster-home \
  --command node \
  --arg "/home/pi/lobster-homeagent/dist/mcp/server.js" \
  --env HA_BASE_URL=http://homeassistant.local:8123 \
  --env HA_TOKEN=<你的长期访问令牌>

# 验证
openclaw mcp status --verbose
openclaw mcp tools lobster-home

等价的 ~/.openclaw/openclaw.json 配置（两种写法等价，用其中一种即可）：

{
  mcp: {
    servers: {
      "lobster-home": {
        command: "node",
        args: ["C:\\Users\\as\\lobster-homeagent\\dist\\mcp\\server.js"],
        env: {
          HA_BASE_URL: "http://homeassistant.local:8123",
          HA_TOKEN: "你的长期访问令牌"
        }
      }
    }
  }
}

方式 B：OpenClaw 插件（进程内，后续挂 Hook 用这个）

openclaw plugins install -l "C:\path\to\lobster-homeagent" --force
openclaw plugins enable lobster-homeagent
openclaw plugins inspect lobster-homeagent --runtime --json

然后在 ~/.openclaw/openclaw.json 的 plugins.entries.lobster-homeagent.config 里填写：

{
  plugins: {
    entries: {
      "lobster-homeagent": {
        enabled: true,
        config: {
          haBaseUrl: "http://homeassistant.local:8123",
          haToken: "你的长期访问令牌",
          dryRun: false
        }
      }
    }
  }
}

为什么两条路都留着：MCP 是方案里的架构主干，跨 Agent 通用； 插件是进程内的，后续「上下文压缩」「模型混合路由」需要挂 OpenClaw 的 before_prompt_build / before_compaction / agent_end 等 Hook，只能在插件里做。

工具清单

控制范围与安全策略

本项目的定位是控制家电，不是看管家里的安全设备。 燃气、阀门、门锁、警报、安防面板、热水器、门窗类设备默认直接被拒绝， 模型连执行入口都拿不到——不是"确认后可用"，而是"不归 AI 管"。

模型调用 ha_call_service
        │
        ├── 允许（allow）─────→ 直接执行，返回设备新状态
        │
        ├── 需确认（confirm）──→ 不执行！返回一次性确认令牌与操作摘要
        │                        模型必须把操作复述给用户
        │                        用户明确同意后调用 ha_confirm_action 才真正执行
        │
        └── 拒绝（deny）──────→ 直接拒绝并说明原因，不给确认入口

默认拒绝（不在本项目控制范围内）：

• 安全相关 domain：lock、valve、siren、alarm_control_panel、gas、water_heater

• 门窗类 cover：device_class 为 window / door / garage / gate

• 命名命中 燃气、阀门、总阀、门锁、报警、烟雾 等规则的实体 （很多家庭把燃气阀接在 switch 上，靠这条兜住）

• 能执行任意命令的 domain：shell_command、python_script、command_line、 rest_command、hassio、homeassistant、recorder、system_log

默认放行（家电类）：灯光、窗帘（curtain / blind / shade / shutter）、 空调、风扇、影音、扫地机、开关、场景、脚本。

需要确认：无法识别类型的 cover（比如没设 device_class 的投影幕布）。 确认令牌一次性、默认 5 分钟有效、可跨进程传递。

想让 AI 控制某个安全设备（例如只在你在家时允许开门锁）？ 把它从 denyDomains 移到 confirmDomains 即可，行为会变成"每次执行前必须经你确认"。 但请先读 DISCLAIMER.md——不建议这么做。

规则可通过配置覆盖，详见 docs/safety-policy.md。

配置项

也兼容 HOMEASSISTANT_URL / HASS_URL、HOMEASSISTANT_TOKEN / HASS_TOKEN 别名。

CLI

node dist/cli.js doctor                     # 连接与策略自检
node dist/cli.js states [domain] [--area 客厅] [--search 关键词]
node dist/cli.js get <entity_id>
node dist/cli.js call <domain> <service> [entity_id] [json]
node dist/cli.js confirm <token>            # 配合上一条完成敏感操作
node dist/cli.js scenes
node dist/cli.js watch [domain]             # 实时订阅状态变化
node dist/cli.js mock-ha [--port 8123]      # 启动内置 Mock HA

CLI 的确认队列落在文件里（LOBSTER_HA_CONFIRM_FILE），因此 call 与 confirm 分两条命令也能完成一次需要确认的操作。

开发

npm run typecheck    # tsc --noEmit
npm test             # 59 项测试
npm run build        # 输出到 dist/

测试不需要任何硬件（全部跑在内置 Mock 上），任何操作系统都能跑。 仓库配了 GitHub Actions（.github/workflows/ci.yml）， 在 Ubuntu 与 Windows 上各跑一遍类型检查、测试、构建， 并额外验证构建产物 dist/mcp/server.js 能作为 MCP 服务器被真实协议调通—— 所以不想在本地装环境的话，推上去让 CI 跑就行。

单独验证构建产物：

# Windows
set LOBSTER_TEST_MCP_ENTRY=%CD%\dist\mcp\server.js
# Linux / macOS
export LOBSTER_TEST_MCP_ENTRY=$PWD/dist/mcp/server.js

node --test test/mcp-server.test.ts

目录结构

src/
  core/            与 Agent 无关的核心（可被任何前端复用）
    config.ts        配置加载与校验（环境变量 / JSON 文件 / 插件配置）
    policy.ts        风险判定、确认令牌队列（内存版 + 文件版）
    gateway.ts       动作网关：串起策略判定、确认流程与实际执行
    ha-rest.ts       Home Assistant REST 客户端
    ha-ws.ts         WebSocket 客户端、区域注册表、实时状态缓存
    format.ts        面向中文对话的状态格式化
    types.ts         领域类型
    errors.ts        统一错误与可读翻译
  mcp/             MCP 服务层
    tools.ts         10 个工具的定义（MCP 与插件共用同一份规格）
    server.ts        MCP stdio 服务器
  plugin/          OpenClaw 插件适配器（进程内）
  dev/mock-ha.ts   Mock Home Assistant（REST + WebSocket）
  cli.ts           调试 CLI
test/              单元测试与 MCP 协议端到端测试
docs/              架构、安全策略、路线图
.github/           CI 工作流与 issue 模板

根目录的说明性文件：

文档

• DISCLAIMER.md —— 免责声明与安全警告（使用前必读）

• docs/architecture.md —— 分层架构与关键设计决策

• docs/safety-policy.md —— 安全策略细则与配置方式

• docs/roadmap.md —— 后续阶段落点（语音层 / 场景 Skill / 模型路由）

• CHANGELOG.md —— 版本变更记录

• CONTRIBUTING.md —— 开发环境、代码约定、贡献者授权声明

• COMMERCIAL.md —— 商业授权说明

许可证

本项目采用 PolyForm Noncommercial License 1.0.0： 个人及非商业用途免费，企业/商业用途需购买授权。

需要说明的是：这不是一份 OSI 认证的开源协议，而是「源码可见 + 非商业免费」的授权模式。 之所以这么选，是因为方案里的商业模式要求「企业商用需付费」—— 宽松协议（MIT / Apache-2.0）允许企业免费商用，无法支撑收费； AGPL-3.0 虽然能迫使企业开源自己的修改，但企业只要愿意开源就依然可以免费商用。 PolyForm Noncommercial 让「个人免费、商用付费」成为可执行的授权条款。 详见 COMMERCIAL.md。

贡献

欢迎帮忙测试和提 issue。当前阶段最有价值的贡献是真实 Home Assistant 下的兼容性反馈 ——所有测试都跑在 Mock 上，真实环境的问题只有你能发现。

提 PR 前请先读 CONTRIBUTING.md， 其中包含一条贡献者授权声明（因为项目是双授权模式， 提交 PR 即表示同意你的贡献可用于商业授权版本）。

开发者与联系方式

再次强调：当前是测试版本（v0.1.0-alpha.1），请酌情使用。 使用前请务必阅读 DISCLAIMER.md。 如果你在真实 Home Assistant 上跑通了，或者遇到了问题，欢迎邮件或提 issue 告诉我 ——这正是当前阶段最需要的信息。