Home Claw

家爪

通过AI助手、终端和自动化工具控制您的Apple HomeKit智能家居。

HomeClaw通过 命令行工具一 stdio MCP服务器，以及插件 克劳德代码 和 龙虾。它作为一个轻量级的macOS菜单栏应用程序运行。

为什么是HomeClaw？

Apple HomeKit没有公共的API，没有CLI，也没有办法与人工智能助手或自动化管道集成。HomeClaw通过Mac Catalyst应用程序弥合了这一差距，该应用程序代表您与HomeKit对话，并公开了一个干净的API表面。

• 让克劳德或OpenClaw“关闭所有灯”或“将恒温器设置为72”
• 从终端编写智能家居脚本
• 构建超越Home应用程序提供的自动化功能
• 按名称、房间、类别或语义类型搜索和控制设备

建筑

Claude Code --> Plugin (.claude-plugin/) --> stdio MCP server (Node.js) --+
Claude Desktop --> stdio MCP server (Node.js) ----------------------------+
OpenClaw --> Plugin (openclaw/) --> homeclaw-cli --------------------------+
                                                                          v
                                               Unix socket (JSON newline-delimited)
                                                                          |
                                               HomeClaw (Mac Catalyst app)
                                                 +-- HomeKitManager (direct, in-process)
                                                 +-- SocketServer (for CLI/MCP clients)
                                                 +-- macOSBridge.bundle (NSStatusItem menu bar)

单工艺设计。 苹果的 HMHomeManager 需要具有HomeKit权限的UIKit/Catalyst应用程序。通过使整个应用程序成为Catalyst，HomeKit的访问是直接的（没有IPC），签名是统一的（单个存档），app Store的提交是干净的。这 macOSBridge 插件包通过以下方式提供本地macOS菜单栏 NSStatusItem.

安装

试飞（推荐）

安装HomeClaw最简单的方法是通过TestFlight：

1. 加入试飞测试
2. 从TestFlight安装HomeClaw
3. 启动应用程序——在系统提示时授予HomeKit访问权限
4. 菜单栏图标出现。点击它查看您的互联家庭。

TestFlight版本已为App Store发行版签名，因此HomeKit无需任何开发人员帐户设置即可工作。

运行后，设置您的AI集成：

• 克劳德桌面版 --从“设置”>“集成”单击安装，或手动添加MCP服务器配置
• 克劳德代码 --从GitHub安装插件
• 龙虾 --从“设置”>“集成”单击安装，或手动设置

从源代码构建

Prerequisites and setup for building from source

先决条件

• macOS 26（Tahoe）或更高版本
• Xcode 26+与Swift 6.2
• Xcodegen: brew install xcodegen
• Node.js 20+（用于MCP服务器包装器）
• Apple开发者帐户 启用HomeKit功能

为什么需要开发人员帐户？ 苹果没有为macOS提供公共的HomeKit API。访问HomeKit的唯一方法是通过 HMHomeManager，这需要 com.apple.developer.homekit 授权和涵盖Mac硬件UDID的配置文件。Apple将此权限限制在开发签名和App Store分发中——它不能包含在开发人员ID（经过公证）构建中。这意味着运行HomeClaw的每台Mac都必须在您的Apple Developer门户中注册为开发设备，并且应用程序必须使用您团队的签名身份构建。这是没有办法的；这是苹果平台的限制，而不是HomeClaw的限制。

设置

git clone https://github.com/omarshahine/HomeClaw.git
cd HomeClaw

# Configure your Apple Developer Team ID (one-time setup)
echo "HOMEKIT_TEAM_ID=YOUR_TEAM_ID" > .env.local

# Install Node.js dependencies
npm install

# Build everything and install
scripts/build.sh --release --install

在以下网址查找您的团队ID developer.apple.com/account 在“会员详细信息”下。

发射自 /Applications 或者： open "/Applications/HomeClaw.app"

首次启动时，在系统提示时授予HomeKit访问权限。此时会出现菜单栏图标——单击它可以查看您连接的家庭。

注： 苹果公司限制了HomeKit在开发签名和App Store分发方面的权利。开发人员ID构建无法访问HomeKit。看 为什么要签署开发协议？ 了解详情。

MCP工具

stdio MCP服务器封装 homeclaw-cli 并公开了这些工具：

连接MCP客户端

任何兼容MCP的客户端都可以通过 stdio服务器，包裹 homeclaw-cli 并且不需要身份验证（HomeClaw应用程序必须为套接字运行）。将此添加到MCP客户端配置中（例如。 claude_desktop_config.json):

{
  "mcpServers": {
    "homeclaw": {
      "command": "node",
      "args": ["/Applications/HomeClaw.app/Contents/Resources/mcp-server.js"]
    }
  }
}

这 mcp-server.js 捆绑在应用程序中。您还可以使用“设置”中的“集成”选项卡自动安装。

命令行界面

这 homeclaw-cli 命令行工具直接通过Unix域套接字进行通信。支持所有读取命令 --json 用于机器可读输出。

# List accessories
homeclaw-cli list
homeclaw-cli list --room "Kitchen"
homeclaw-cli list --category thermostat

# Control devices
homeclaw-cli set "Living Room Light" brightness 75
homeclaw-cli set "Front Door Lock" lock_target_state locked
homeclaw-cli set "Thermostat" target_temperature 72

# Disambiguate when a characteristic exists on multiple services (e.g. bridged TVs)
homeclaw-cli set "TV" active 0 --service-type 000000D8-0000-1000-8000-0026BB765291

# Get detailed device info
homeclaw-cli get "Kitchen Light" --json

# Search across all homes
homeclaw-cli search "bedroom" --category lightbulb

# Scenes
homeclaw-cli scenes
homeclaw-cli get-scene "Good Night" --json        # Full detail: all actions
homeclaw-cli trigger "Good Night"

# Scene management
homeclaw-cli delete-scene "Old Scene"
homeclaw-cli import-scene scene.json --dry-run   # Preview before creating
homeclaw-cli import-scene scene.json              # Create scene from JSON
homeclaw-cli assign-rooms rooms.json --dry-run    # Preview room assignments
homeclaw-cli assign-rooms rooms.json              # Bulk-assign accessories to rooms

# Home management
homeclaw-cli rename "Front Door" "Front Door Lock"          # Rename accessory
homeclaw-cli rename-room "Bedroom" "Primary Bedroom"        # Rename room
homeclaw-cli create-room "Nursery"                          # Create room
homeclaw-cli remove-room "Old Room"                         # Remove room
homeclaw-cli remove-accessory "Broken Sensor"               # Remove accessory
homeclaw-cli create-zone "Upstairs"                         # Create zone
homeclaw-cli remove-zone "Old Zone"                         # Remove zone
homeclaw-cli add-room-to-zone "Bedroom" "Upstairs"          # Add room to zone
homeclaw-cli remove-room-from-zone "Bedroom" "Upstairs"     # Remove room from zone
homeclaw-cli rename "Front Door" "New Name" --dry-run       # Preview any mutation

# Automations (button programming)
homeclaw-cli automations                                     # List all automations
homeclaw-cli automations get ""                # Detail view

# Scene-based: trigger an existing scene
homeclaw-cli automations create --name "Gym Lights" \
  --accessory "Gym Button" --scene "Gym On" --press single

# Inline actions: use UUIDs for target accessories to avoid name collisions
homeclaw-cli automations create --name "Sarah's Room Open" \
  --accessory "Office Button" \
  --action "BE21C139-413A-50F9-B97F-B9BDA06302A8:power:true" \
  --action "52195C6F-6FAA-5E52-AA56-840A6605EEAA:target_position:100" \
  --press single --service-index 1

# Multi-button preview
homeclaw-cli automations create --name "Open Blinds" \
  --accessory "Blinds Button" --scene "Open" \
  --service-index 1 --dry-run

homeclaw-cli automations delete ""             # Delete automation
homeclaw-cli automations enable ""             # Enable
homeclaw-cli automations disable ""            # Disable

# LLM-optimized device map
homeclaw-cli device-map

# Status and configuration
homeclaw-cli status
homeclaw-cli config --default-home "Main House"
homeclaw-cli config --filter-mode allowlist
homeclaw-cli config --list-devices

# Event log
homeclaw-cli events                         # Recent events (last 50)
homeclaw-cli events --since 1h              # Events from the last hour
homeclaw-cli events --since 2d --json       # Last 2 days, JSON output
homeclaw-cli events --type scene_triggered  # Filter by event type

# Webhook configuration
homeclaw-cli config --webhook-url "http://127.0.0.1:18789"
homeclaw-cli config --webhook-token "your-secret-token"
homeclaw-cli config --webhook-enabled true
homeclaw-cli config --webhook-test           # Send test event, show HTTP response
homeclaw-cli config --webhook-reset          # Reset circuit breaker without toggling

# Webhook triggers
homeclaw-cli triggers                        # List all triggers
homeclaw-cli triggers add --label "Front Door" --accessory-id ""
homeclaw-cli triggers add --label "Mailbox Open" --accessory-id "" --characteristic contact_state
homeclaw-cli triggers update "" --wake-mode now
homeclaw-cli triggers remove ""

# Dry-run mutations (validate without actuating)
homeclaw-cli set "Front Door" lock_target_state locked --dry-run
homeclaw-cli delete-scene "Movie Night" --dry-run

# Auto-JSON: all commands output JSON when piped or when env var is set
homeclaw-cli status | jq .                   # Auto-detects non-TTY
OUTPUT_FORMAT=json homeclaw-cli list          # Force JSON via env var

按钮编程注意事项

内联vs场景： 使用 --action 用于简单的按钮到设备映射。这将创建一个以自动化命名的场景。使用 --scene 以触发现有场景。注意：苹果的Home应用程序使用了一个专用的API，用于隐藏的仅自动操作集；通过HomeClaw创建的内联操作将在Home应用程序中显示为可见场景。

按钮模式： 一些按钮（如Aqara AR009）支持快速模式（2个按钮，每个按钮单按，即时响应）或多事件模式（1个按钮，单按/双按/长按，~300ms延迟）。使用 --service-index 以快速模式定位特定按钮。

交互式TUI

homeclaw-cli ui

启动全屏、键盘驱动的家居视图。浏览房间和配件，一目了然地查看实时状态，并切换任何具有二进制状态的东西（灯、开关、风扇、插座、锁、百叶窗）。

🦞 HomeClaw                                    21 rooms · 112 accessories

┌──────────────────────────────────────────────────────────────────────┐
│ ▾ Living Room (4)                                                     │
│   ├─ ● Floor Lamp                       On                            │
│   ├─ ● TV Light Strip                   On                            │
│   ├─ ◐ Thermostat                       70.5°F                        │
│   └─ ○ Window Blinds                    100%                          │
│                                                                       │
│ ▾ Kitchen (3)                                                         │
│   ├─ ○ Counter Light                    Off                           │
│   ...                                                                 │
└──────────────────────────────────────────────────────────────────────┘
^D quit  ↑↓ navigate  Enter toggle

状态颜色编码：灯亮为黄色，插座/开关为青色，风扇为蓝色，锁定时为绿色/解锁时为红色，运动为红色，传感器为青色，关闭/怠速变暗。

使用Claude代码

HomeClaw与 克劳德代码 作为 插件 它提供MCP工具和HomeKit技能，以实现更丰富的自然语言理解。

安装插件

从本地克隆或直接从GitHub安装。

从本地克隆：

# Clone if you haven't already
git clone https://github.com/omarshahine/HomeClaw.git ~/GitHub/HomeClaw

# Inside Claude Code, register the marketplace and install
/plugin marketplace add ~/GitHub/HomeClaw
/plugin install homeclaw@homeclaw

从GitHub（不需要本地克隆）：

# Inside Claude Code, add the GitHub repo as a marketplace
/plugin marketplace add https://github.com/omarshahine/HomeClaw

# Install the plugin
/plugin install homeclaw@homeclaw

安装后，重新启动Claude Code。然后问：

“打开厨房灯，将其设置为50%的亮度” “把所有的门都锁上” “恒温器的设定值是多少？” “运行电影时间场景” “客厅里有什么灯？”

验证连接

安装后，验证Claude是否可以访问HomeKit：

# Check MCP server status inside Claude Code
/mcp

使用OpenClaw

HomeClaw包括一个 龙虾 在网关上注册HomeKit技能的插件。技能召唤 homeclaw-cli 按名称，所以它必须在您的PATH中。

相同的Mac安装（推荐）

如果HomeClaw和OpenClaw在同一台Mac上运行，请使用一键安装程序：

1. 打开 设置>集成 然后单击 安装 在OpenClaw部分。

这会自动处理所有四个步骤：安装插件、启用插件、符号链接 homeclaw-cli 并重新启动网关。

或者从终端：

# 1. Install the plugin from the bundled files
openclaw plugins install "/Applications/HomeClaw.app/Contents/Resources/openclaw/"
openclaw plugins enable homeclaw

# 2. Symlink the CLI into PATH (the skill calls homeclaw-cli by name)
# Apple Silicon (M1/M2/M3/M4):
ln -sf '/Applications/HomeClaw.app/Contents/MacOS/homeclaw-cli' /opt/homebrew/bin/homeclaw-cli
# Intel:
ln -sf '/Applications/HomeClaw.app/Contents/MacOS/homeclaw-cli' /usr/local/bin/homeclaw-cli

# 3. Restart the gateway to load the plugin
openclaw gateway restart

远程网关

如果OpenClaw在另一台机器上运行：

# Clone the repo on the gateway
git clone https://github.com/omarshahine/HomeClaw.git ~/GitHub/HomeClaw

# Install the plugin
openclaw plugins install ~/GitHub/HomeClaw/openclaw
openclaw plugins enable homeclaw

# Symlink the CLI into PATH
ln -sf /path/to/homeclaw-cli /opt/homebrew/bin/homeclaw-cli

# Restart the gateway
openclaw gateway restart

注： 这 homeclaw-cli 二进制文件必须可以从网关（在PATH中）访问，HomeClaw应用程序必须在同一台Mac上运行（通过Unix套接字连接）。

支持的配件

HomeClaw支持各种HomeKit配件类别：

场景导入格式

这 import-scene 命令接受一个定义场景及其动作的JSON文件：

{
  "name": "Movie Night",
  "actions": [
    {"accessory": "Living Room Light", "room": "Living Room", "property": "brightness", "value": "30%"},
    {"accessory": "TV Backlight", "room": "Living Room", "property": "power_state", "value": "ON"},
    {"accessory": "Overhead", "room": "Living Room", "property": "power_state", "value": "OFF"}
  ]
}

这 assign-rooms 命令接受将附件映射到房间的JSON文件。使用 uuid 为了在多个配件同名时进行精确匹配（例如，风扇+吊扇的光线）：

{
  "assignments": [
    {"accessory": "Kitchen Light", "room": "Kitchen"},
    {"uuid": "790A359D-27A6-5738-A92E-F4380CC6BA07", "room": "Front Door"},
    {"accessory": "Desk Lamp", "room": "Office"}
  ]
}

两个命令都支持 --dry-run 预览更改而不修改HomeKit。

菜单栏应用程序

菜单栏提供一目了然的状态和快速操作：

• HomeKit连接状态 --连接时显示家庭名称，或显示错误状态和原因
• 登录时启动 切换
• 设置 链接和 退出

设置

可从菜单栏访问五个配置选项卡：

HomeKit

查看连接状态，浏览您的主页，并为所有MCP和CLI命令选择哪个主页处于活动状态。

设备

控制哪些附件暴露给MCP客户端和CLI。切换 所有附件 （一切可见）和 仅选择 （满负荷模式）。配件按房间分组，带有搜索过滤器和房间级别开关，可快速批量选择。

集成

安装和管理与AI助手的连接。该应用程序检测现有配置并指导您完成设置：

• 克劳德桌面版 --一键安装捆绑的stdio MCP服务器（需要Node.js）
• 克劳德代码 --检测已安装的插件(homeclaw@homeclaw)
• 龙虾 --检测远程网关上的插件配置并提供设置说明

事件日志

HomeClaw将所有HomeKit事件记录到JSONL文件中 ~/Library/Application Support/HomeClaw/events.jsonl事件包括特征变化（灯打开）、场景触发以及来自CLI或MCP的控制操作。

配置

打开 设置>事件日志 配置：

• 启用/禁用 事件记录
• 最大文件大小 （10-500MB）--当日志达到此大小时，它会被轮换
• 旋转备份 （0-10）--删除最旧的日志文件之前要保留多少旧日志文件
• 清除 --删除所有事件日志文件
• 在Finder中显示 --显示日志目录

或者通过CLI进行配置：

homeclaw-cli events                         # Show recent events
homeclaw-cli events --since 1h              # Last hour
homeclaw-cli events --type characteristic_change  # Filter by type
homeclaw-cli events --limit 200 --json      # JSON output

事件类型： characteristic_change, scene_triggered, accessory_controlled, homes_updated

这 --since 标志接受ISO 8601时间戳或持续时间简写： 1h, 30m, 2d.

网络钩子

HomeClaw将HomeKit活动推到 龙虾 通过 映射的webhooks。只有配置了触发器的附件和场景才会触发webhooks——未触发的事件会记录到磁盘上，但不会被推送。专用的HomeClaw代理接收所有事件，按严重程度对其进行分类，并将值得注意的事件上报给主代理。

注： OpenClaw 2026.3.x有一个已知的错误 /hooks/wake 默默地放下事件(#33271).家爪用途 映射的webhooks (/hooks/homeclaw)通过哪条路线 hooks.mappings 并且是 不影响.

运作原理

HomeClaw POST将所有触发的事件都发送到一个映射的端点： /hooks/homeclawOpenClaw的 hooks.mappings config解析 "homeclaw" 将每个事件按关键字和路线发送到 专门的HomeClaw代理商 对事件进行分类和分类。

HomeKit event --> HomeClaw event logger --> POST /hooks/homeclaw
    --> OpenClaw hooks.mappings --> HomeClaw Agent (dedicated)
        --> Classifies: CRITICAL / NOTABLE / AMBIENT
        --> If notable/critical: a2a to main agent
        --> If ambient: log to agent memory only

HomeClaw不需要知道 agentId, channel，或 sessionKey --所有路由智能都存在于OpenClaw配置中。

触发交付模式

每个触发器都有一个 交付模式 控制时序：

在 设置>Webhook，每个启用的触发器显示一个 分批/立即 拾取器。对于您想立即做出反应的事件（泄漏传感器、门锁、场景触发器），请使用“立即”。使用Batch处理环境事件（灯光切换、温度变化）以避免噪音。

使用AI助手进行设置

将此提示粘贴到 龙虾 或 克劳德代码 端到端配置webhooks。提示符是幂等的——它验证每个步骤并跳过已配置的任何内容：

先决条件： HomeClaw必须安装并运行（菜单栏图标可见）。如果使用克劳德代码 homeclaw 插件必须注册(/plugin install homeclaw@homeclaw).这 homeclaw-cli 二进制文件必须在PATH中。 使用专用的HomeClaw代理设置HomeClaw映射的webhooks。 请先验证每个步骤——跳过任何已配置的步骤。 1.HomeClaw代理工作区： - 检查是否 homeclaw 代理存在： openclaw agents list - 如果缺少，请从捆绑的应用程序安装： openclaw agents install homeclaw /Applications/HomeClaw.app/Contents/Resources/openclaw/agents/homeclaw - 将代理文档（IDENTITY/SOUL/AGENTS/TOOLS.md）从应用程序捆绑包复制到本地代理目录（如果更新） - 配置代理：型号 claude-sonnet-4，受限工具（内存、会话/a2a、只读/写——无exec、无浏览器、无外部服务） 2.OpenClaw网关挂钩配置： - 检查 ~/.openclaw/openclaw.json 为了一个 hooks.mappings.homeclaw 进入 - 如果缺失，请添加： ``json "hooks": { "enabled": true, "token": "${HOMECLAW_WEBHOOK_TOKEN}", "mappings": { "homeclaw": { "agentId": "homeclaw", "sessionKey": "hook:homeclaw", "deliver": true, "channel": "last", "allowUnsafeExternalContent": true } } } ` - 在以下位置创建转换 ~/.openclaw/hooks/transforms/homeclaw-transform.js 将HomeClaw状态更改有效负载转换为代理消息 - 检查 ~/.openclaw/.env 为了 HOMECLAW_WEBHOOK_TOKEN.如果缺少，则生成一个： openssl rand -base64 24 | tr '+/' '-_' | tr -d '=' 并添加它 - 删除任何遗留内容 defaultSessionKey 使用专用映射不再需要的条目 - 仅当配置更改时重新启动网关： openclaw gateway restart **3.HomeClaw webhook配置：** - 检查当前配置： homeclaw-cli config --json - 验证： webhook.enabled 是真的， webhook.url 是 http://127.0.0.1:18789, webhook.token 匹配 HOMECLAW_WEBHOOK_TOKEN 从步骤2开始，以及 webhook_endpoint 是 /hooks/homeclaw - 通过HomeClaw设置UI或CLI修复任何不匹配 - 如果断路器显示旧故障，请将其重置 **4.端到端测试：** - 跑 homeclaw-cli config --webhook-test --期待HTTP 200 - 验证电路状态是否 closed 和 last_success` 最近 报告已配置的内容、更改的内容和测试结果。

手动设置

Step-by-step without an AI assistant

1.创建代理工作区

代理文档被捆绑在HomeClaw应用程序中。由于应用程序包是只读的，因此您需要 本地副本 让OpenClaw用作代理目录：

# Create local agent dir with workspace
mkdir -p ~/.openclaw/agents/homeclaw/{agent,workspace}

# Copy agent docs from app bundle
cp /Applications/HomeClaw.app/Contents/Resources/openclaw/agents/homeclaw/*.md \
   ~/.openclaw/agents/homeclaw/agent/

# Register the agent
openclaw agents add homeclaw \
  --agent-dir ~/.openclaw/agents/homeclaw/agent \
  --workspace ~/.openclaw/agents/homeclaw/workspace
openclaw agents list   # verify it appears

注： openclaw agents add （不是 install)是正确的CLI命令。这 --workspace 在非交互模式下需要标记。

2.配置OpenClaw

添加 hooks 块状 mappings 到 ~/.openclaw/openclaw.json:

"hooks": {
  "enabled": true,
  "token": "${HOMECLAW_WEBHOOK_TOKEN}",
  "mappings": {
    "homeclaw": {
      "agentId": "homeclaw",
      "sessionKey": "hook:homeclaw",
      "deliver": true,
      "channel": "last",
      "allowUnsafeExternalContent": true
    }
  }
}

这 mappings 所有入境路线 /hooks/homeclaw POST在一个持久的过程中发送给专门的HomeClaw代理 hook:homeclaw 会议。

创建转换 将HomeClaw有效载荷转换为代理消息。钩子映射需要 message 有效载荷中的字段——没有转换，有效载荷只有 text + mode 将出现400错误：

mkdir -p ~/.openclaw/hooks/transforms
cat > ~/.openclaw/hooks/transforms/homeclaw-transform.js ' >> ~/.openclaw/.env

重新启动网关： openclaw gateway restart

警告： 网关重写 openclaw.json 重新启动时。重新启动后，通过检查文件来验证映射和转换条目是否有效。如果新添加的映射被剥离，请重新启动一次——第一次映射可能会出现竞争情况。

3.配置HomeClaw

选项A-GUI： 打开“设置”>“Webhook”。切换启用，输入 http://127.0.0.1:18789 将步骤2中的相同令牌粘贴为基本URL。

选项B--CLI （注意：CLI仅更新正在运行的守护进程，它不会持续到 config.json。使用设置UI或直接编辑配置文件以进行持久更改）：

homeclaw-cli config --webhook-url "http://127.0.0.1:18789" \
                    --webhook-token "your-token" \
                    --webhook-enabled true

4.测试管道

homeclaw-cli config --webhook-test

您应该看到HTTP 200响应。如果失败，请检查令牌是否匹配，以及OpenClaw网关是否正在运行。

注： 测试事件更新 total_delivered 和 last_http_status 在断路器的统计数据中。运行后 --webhook-test，检查 homeclaw-cli config --json 以确认值已更新。

5.创建触发器

在 设置>Webhook，检查您要启动webhooks的配件和场景。只有选中的项目才会生成事件。具有多种特征的配件（例如，具有接触状态和运动的传感器）显示单独的开关，因此您可以准确选择哪个状态会改变消防挂钩。与电池相关的特性会自动排除。

注： 触发器创建仅限于GUI。CLI可以列出和管理现有触发器(homeclaw-cli triggers list, triggers remove)，但必须在HomeClaw应用程序的“设置”>“Webhook”选项卡中创建新的触发器。

6.端到端测试

# Verify HomeClaw is connected and webhook is healthy
homeclaw-cli status

# Toggle a light from the Home app, then check events
homeclaw-cli events --since 5m

# Check webhook delivery log
homeclaw-cli webhook-log

# Check HomeClaw delivery logs
log show --predicate 'process == "HomeClaw" AND category == "webhook"' --last 5m --style compact

断路器

webhook系统包括 分层断路器 这可以防止失控的交付失败摧毁端点，同时确保关键事件永远不会被悄无声息地丢弃。

关键触发器 (critical: true)无论电路状态如何，始终尝试交付。

电路状态可见于：

• 菜单栏 --暂停或禁用时的警告图标
• 设置>Webhook --带有倒计时的橙色（暂停）或红色（禁用）横幅
• 命令行界面 -- homeclaw-cli status 显示电路状态、下降计数和恢复提示

事件如何流动

Home app / physical device / Siri
        |
        v
HomeKit (HMAccessoryDelegate callback)
        |
        +-- Cache warmup? --> Update cache only (no logging, no webhooks)
        |
        +-- Battery event? --> Update cache only (silently dropped)
        |
        v
HomeClaw event logger (writes to events.jsonl)
        |
        +-- Trigger matches? --> POST /hooks/homeclaw
        |
        +-- No trigger --> Logged to disk only (no webhook sent)

        v  (trigger matched)
OpenClaw gateway validates Bearer token
        |
        v
hooks.mappings resolves "homeclaw"
        |
        v
HomeClaw Agent (dedicated)
        +-- Classifies: CRITICAL / NOTABLE / AMBIENT
        +-- If notable/critical: a2a to main agent
        +-- If ambient: log to agent memory only

认证

用途 Authorization: Bearer 带有幂等性标头(X-Request-ID, X-Event-Timestamp).看 技能.md 有关完整触发字段的参考、场景烹饪书和故障排除。

设备筛选

使用 设备选项卡 在设置或命令行界面（CLI）中，控制显示哪些附件：

homeclaw-cli config --filter-mode allowlist
homeclaw-cli config --allow-accessories "uuid1,uuid2,uuid3"
homeclaw-cli config --list-devices  # shows allowed/filtered status

建筑

构建脚本使用XcodeGen生成Xcode项目 xcodebuild 编译所有目标（HomeClaw Catalyst应用程序、macOSBridge捆绑包、HomeClaw cli工具）：

# Full release build + install to /Applications
scripts/build.sh --release --install

# Override team ID on the command line
scripts/build.sh --release --install --team-id ABCDE12345

# Debug build (faster)
scripts/build.sh --debug

# Clean build artifacts first
scripts/build.sh --clean

您的Apple开发者团队ID是必需的，通过提供 .env.local, --team-id，或 HOMEKIT_TEAM_ID 环境变量。

App Store/TestFlight的存档

释放管道由以下驱动 快车道.车道：

fastlane archive       # Build a release .xcarchive (no upload)
fastlane upload        # Archive + upload to App Store Connect (no external submission)
fastlane beta          # Archive + upload + submit to external TestFlight (full release loop)
fastlane status        # Show TestFlight processing/external state for the latest build
fastlane submit_only build:NNN   # Recovery: submit an already-uploaded build
fastlane auth_check    # Validate ASC API key setup

# Pass tester notes (used by `beta` and `submit_only`):
fastlane beta notes_file:/tmp/notes.txt
fastlane beta notes:"Bug fixes and improvements"

# App Store screenshot pipeline (XCUITest-driven, demo mode, zero personal data):
fastlane screenshots          # Run HomeClawUITests in demo mode, extract PNGs to fastlane/screenshots/en-US/
fastlane upload_screenshots   # Push screenshots to App Store Connect

截图管道使用 演示模式 — HomeKitManager.isDemoMode （门打开 --ui-test-demo 启动arg或 HOMECLAW_DEMO=1)绕过HomeKit，从以下位置提供合成数据 Sources/homeclaw/HomeKit/DemoFixtures.swift真正的HomeKit数据永远不会被读取或显示。需要 xcparse (brew install chargepoint/xcparse/xcparse).

已知的后续操作：菜单栏下拉菜单为 NSMenu （AppKit），因此无法通过SwiftUI自动渲染 ImageRenderer。使用手动捕获 screencapture -x 运行演示模式应用程序，或构建下拉菜单的SwiftUI模型。

Auth使用来自的App Store Connect API密钥 ~/.secrets.env (ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_PATH).团队ID来自 .env.local (HOMEKIT_TEAM_ID).

要在Xcode Organizer中打开存档而不是上传：

fastlane archive
open '.build/archives/HomeClaw.xcarchive'

版本颠簸

版本是在构建时从git标签派生出来的。要发布新版本，请执行以下操作：

scripts/bump-version.sh 0.2.0   # Updates source files + prints tag commands
npm run build:mcp                # Rebuild MCP server with new version
git add -A && git commit -m "Bump version to 0.2.0"
git tag -a v0.2.0 -m "HomeClaw v0.2.0"
git push && git push origin v0.2.0

在其他Mac上安装

开发签名版本与注册设备绑定。要在另一台Mac上运行HomeClaw：

1. 获取目标Mac的配置UDID --在Mac上，运行：

   system_profiler SPHardwareDataType | grep "Provisioning UDID"

1. 注册设备 在 developer.apple.com/account/resources/devices/add:

- 平台：macOS - 设备名称：描述性名称（例如“客厅MacBook Air”） - 设备标识符：步骤1中的配置UDID

1. 重建 在您的开发机器上（Xcode重新生成配置文件以包含新设备）：

   scripts/build.sh --release --install --clean

1. 复制 /Applications/HomeClaw.app 到目标Mac（AirDrop、USB、网络共享等）

1. 授予HomeKit访问权限 在首次启动时收到提示。

注： 目标Mac必须使用具有HomeKit家庭数据的帐户登录iCloud。HomeKit家庭与iCloud帐户绑定，而不是与应用程序绑定。

为什么要签署开发协议？

苹果限制 com.apple.developer.homekit 有权 开发签约 和 Mac 应用商店 分布。它不能包含在开发人员ID配置文件中。开发人员ID构建将通过Gatekeeper，但无法访问HomeKit(HMHomeManager 返回零个房屋）。这是一个 苹果平台限制，不是虫子。

项目结构

Sources/
  homeclaw/                Unified Catalyst app (Xcode target via XcodeGen)
    App/                   UIApplicationDelegate entry point, scene delegates
    Bridge/                BridgeProtocols.swift (Mac2iOS, iOS2Mac)
    HomeKit/               HomeKitManager, SocketServer, CharacteristicMapper,
                           AccessoryModel, DeviceMap, CharacteristicCache,
                           HomeEventLogger, WebhookCircuitBreaker
    Views/                 SettingsView, IntegrationsSettingsView
    Shared/                AppConfig, AppLogger, HomeClawConfig
  macOSBridge/             AppKit bundle (NSStatusItem menu bar)
    MacOSController.swift  NSStatusItem + NSMenu via iOS2Mac protocol
    Info.plist             NSPrincipalClass: MacOSController
  homeclaw-cli/            CLI tool (SPM executable + Xcode target)
    Commands/              list, get, set, search, scenes, get-scene, status, config, device-map,
                           events, triggers, delete-scene, import-scene, assign-rooms
    SocketClient.swift     Direct socket communication
Resources/                 Info.plist, entitlements, app icons
scripts/
  build.sh                 Build, sign, and install
  bump-version.sh          Update version across source files
fastlane/
  Fastfile                 Release pipeline: archive, upload, beta (TestFlight)
  Appfile                  Bundle ID + team ID
  Gymfile                  Mac Catalyst archive defaults
mcp-server/                Node.js stdio MCP server (wraps homeclaw-cli)
openclaw/                  OpenClaw plugin (HomeClaw)
  skills/homekit/          HomeKit skill with full characteristic reference

App bundle layout (after build):
  Contents/MacOS/HomeClaw              Catalyst app executable
  Contents/MacOS/homeclaw-cli          Bundled CLI binary
  Contents/Resources/macOSBridge.bundle  AppKit menu bar plugin
  Contents/Resources/mcp-server.js       Node.js stdio MCP server
  Contents/Resources/openclaw/           Bundled OpenClaw plugin files

调试

# Check if HomeClaw is running and HomeKit is ready
echo '{"command":"status"}' | nc -U ~/Library/Group\ Containers/group.com.shahine.homeclaw/homeclaw.sock

# Or via the CLI
homeclaw-cli status

# Verify HomeKit entitlement on installed app
codesign -d --entitlements :- "/Applications/HomeClaw.app"

# View HomeClaw logs
log show --predicate 'process == "HomeClaw"' --last 10m --style compact

# Check TCC (privacy) permissions
sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db \
  "SELECT client, auth_value FROM access WHERE service = 'kTCCServiceWillow'"

技术栈

• Swift 6 具有严格的并发性(@MainActor, actor 隔离）
• Mac Catalyst （UIKit）用于HomeKit框架访问
• 应用 套件 （通过macOSBridge捆绑包）用于本机菜单栏
• Swift参数解析器 对于CLI
• Node.js + @模型上下文协议/sdk 用于stdio MCP服务器
• Xcodegen 用于Xcode项目生成
• 最大公约数 +用于CLI/MCP通信的Unix域套接字

常见问题

spctl --assess 说“拒绝”——这有问题吗？

号码 spctl 检查Gatekeeper，它只信任Developer ID和App Store签名。家爪用途 开发签约 （macOS上HomeKit需要），因此Gatekeeper将始终拒绝它。这是意料之中的，不会阻止应用程序运行——AMFI通过嵌入式配置文件单独处理开发签名的应用程序。

我可以为HomeKit使用与我的开发者帐户不同的Apple ID吗？

对。这两个账户的用途完全不同：

• Apple开发者帐户 --只有在构建时才重要。Xcode使用它来创建配置文件并对代码进行签名。
• Icloud帐户 （在运行HomeClaw的Mac上）--确定显示哪些HomeKit主页。这是链接到您的Home应用程序数据的帐户。

这些是独立的。您可以使用您的开发者帐户构建HomeClaw，并在登录到具有HomeKit主页的完全不同的iCloud帐户的Mac上运行它。HomeKit数据遵循iCloud帐户，而不是签名身份。

我什么时候用 --clean?

使用 scripts/build.sh --clean 什么时候：

• 切换Apple开发团队ID
• Xcode主要版本更新后
• 构建失败，出现签名或权限错误
• 重建后您会看到代码签名错误

这 --clean flag在重新构建之前删除所有构建工件。

HomeKit显示0个房屋

应用程序正在运行，但看不到任何HomeKit数据。按顺序检查：

1. iCloud已登录？ HomeKit数据存储在iCloud中。打开系统设置>Apple帐户并验证。
2. HomeKit权利是否存在？ 运行：

   codesign -d --entitlements :- "/Applications/HomeClaw.app"

你应该看到 com.apple.developer.homekit -> true.

1. 是否授予TCC许可？ 首次启动时，macOS会要求访问HomeKit。如果您拒绝了，请在“系统设置”>“隐私和安全”>“HomeKit”中重新授予。
2. 使用开发人员ID签名？ 只有开发签名支持HomeKit权利。看 为什么要签署开发协议？.

如何在另一台Mac上安装？

开发签名应用程序与注册设备绑定。看 在其他Mac上安装 完整的演练。

我怎么知道发生了什么？

# HomeClaw app logs
log show --predicate 'process == "HomeClaw"' --last 10m --style compact

# Check HomeKit status directly over the socket
homeclaw-cli status

# Verify code signature and entitlements
codesign -d --entitlements :- "/Applications/HomeClaw.app"

许可证

麻省理工学院 --版权所有（c）2025奥马尔·沙欣