1. 从一句模糊指令说起为什么 Agent 接管智能家居需要统一 API 通道“朋友要来家里了帮我把灯都开一下然后调到晚上适合的颜色。”这句话里没有设备名、没有亮度值、没有色温参数传统语音助手大概率会匹配失败。但如果你把 OpenClaw 这类 Agent 运行时接到 Home Assistant 上它就能自己查设备列表、推断参数、调用接口、回查状态最后给你一个“已完成”的反馈。问题在于Agent 要访问 Home Assistant 的 REST API就需要一个稳定的鉴权入口。如果你把 Home Assistant 的长期访问令牌直接写进 Agent 的配置文件一旦配置文件泄露或者 Agent 被诱导执行越权操作整个家居系统就暴露了。更麻烦的是如果你同时还在用 Claude Code、Cursor 或者其他编码工具每个工具都要单独配一套 Key 和 Base URL管理成本会迅速膨胀。我试过把 Home Assistant 的 Token 直接塞进 OpenClaw 的 TOOLS.md结果每次换模型或者换工具都要重新改一遍配置而且没法统一控制调用量和权限边界。后来换成 TaoToken 作为统一的 API 通道Agent 只认一个 Base URL 和一个 KeyHome Assistant 的访问令牌留在 TaoToken 侧做转发配置文件里不再出现敏感凭据。这样既满足了 Agent 的调用需求又把权限收拢到了一个可控的入口。这篇文章面向的是已经在跑 Home Assistant、想用 OpenClaw 做智能家居自动化的开发者。你会看到一套可复制的 config.toml 骨架、settings.json 关键字段说明以及一次真实的设备开关验证动作。目标不是让 Agent “能聊天”而是让它“能干活”并且在受控权限下干活。2. TaoToken 前置统一 Key 与 API 通道的接入准备在把 OpenClaw 接到 Home Assistant 之前你需要先有一个能统一管理模型调用和 API 转发的入口。TaoToken 在这里扮演的角色是Agent 不直接持有 Home Assistant 的长期令牌而是通过 TaoToken 的 API 通道去访问 Home Assistant 的 REST 接口。同时Agent 调用大模型进行推理时也走同一个 Base URL省去多套 Key 来回切换的麻烦。2.1 获取 API Key 与确认 Base URL首先到 TaoToken 控制台创建一个 API Key。地址是https://taotoken.net/api-keys登录后点“创建新密钥”复制生成的 Key后面会写进 OpenClaw 的配置文件。注意这个 Key 只显示一次丢了就重新生成。Base URL 固定为https://taotoken.net/api不要加任何路径后缀。OpenClaw 的模型调用和 Home Assistant 的 API 转发都走这个入口。如果你之前用过其他中转服务记得把旧的 Base URL 全部替换掉否则会出现 401 或者模型找不到的错误。注意API Key 不要提交到 Git 仓库也不要写进 TOOLS.md 这种会被 Agent 读取的文件。推荐用环境变量注入或者放在 OpenClaw 的 secrets 配置里。2.2 在 Home Assistant 侧准备长期访问令牌Home Assistant 这边你需要生成一个长期访问令牌路径是左下角用户头像 → 安全 → 长期访问令牌 → 创建令牌。复制这个令牌它会在 TaoToken 的通道配置里用到用来让 TaoToken 代表 Agent 去调用 Home Assistant 的 REST API。这里的关键设计是Agent 只知道 TaoToken 的 Key不知道 Home Assistant 的令牌。TaoToken 侧配置好转发规则后Agent 发往https://taotoken.net/api的请求会被路由到你的 Home Assistant 实例。这样即使 Agent 的配置文件泄露攻击者也拿不到 Home Assistant 的直接控制权。2.3 确认 OpenClaw 版本与依赖OpenClaw 建议用最新稳定版旧版本对自定义 Base URL 的支持不完整。检查你的 OpenClaw 版本openclaw --version如果低于 0.9.x先升级。另外确认你的环境里已经装了curl和jq后面验证请求会用到。Home Assistant 的 REST API 默认端口是 8123确保 OpenClaw 所在的容器或主机能访问到这个端口。3. 可复制配置config.toml 骨架与 settings.json 关键字段这一节给出完整的配置文件骨架。你可以直接复制然后把尖括号里的内容替换成你自己的值。配置文件分两部分config.toml负责 OpenClaw 的运行时和模型通道settings.json负责 Home Assistant 的工具定义和权限边界。3.1 config.toml 骨架# OpenClaw 运行时配置 [agent] name home-assistant-agent runtime openclaw max_steps 12 timeout_seconds 120 # 模型通道统一走 TaoToken [model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model_name claude-sonnet-4-20250514 temperature 0.2 # Home Assistant 工具通道 [tools.home_assistant] enabled true base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} ha_instance http://192.168.1.100:8123 ha_token ${HA_LONG_LIVED_TOKEN} allowed_services [ light.turn_on, light.turn_off, switch.turn_on, switch.turn_off, sensor.get_state ] denied_services [ lock.unlock, lock.open, camera.enable_motion_detection ] # 安全边界 [security] require_confirmation false max_daily_tokens 500000 sandbox docker几个关键点说明。base_url在[model]和[tools.home_assistant]里都指向https://taotoken.net/api这样 Agent 的推理请求和设备控制请求走同一个入口Key 也复用同一个。allowed_services是白名单只允许灯和开关的控制以及传感器状态读取。denied_services是黑名单门锁和摄像头相关操作直接禁止即使模型推理出要调用也会被拦截。max_daily_tokens限制每天的总 Token 消耗防止 Agent 陷入死循环把额度跑光。sandbox docker表示 OpenClaw 跑在 Docker 容器里和 NAS 上的其他数据隔离。3.2 settings.json 关键字段settings.json放在 OpenClaw 的工作目录下定义 Home Assistant 的设备映射和工具描述。Agent 每次 loop 会读取这个文件知道有哪些设备可用、每个设备支持什么操作。{ home_assistant: { entities: { light.living_room: { friendly_name: 客厅主灯, supported_features: [brightness, color_temp], color_temp_range: [2700, 6300] }, light.bedroom: { friendly_name: 卧室灯, supported_features: [brightness, color_temp], color_temp_range: [2700, 6300] }, switch.balcony_fan: { friendly_name: 阳台风扇, supported_features: [on_off] } }, scene_presets: { evening_guest: { description: 朋友来访时的晚间灯光, targets: [light.living_room, light.bedroom], brightness_pct: 75, color_temp_kelvin: 3000 } } }, tool_descriptions: { ha_call_service: 调用 Home Assistant 服务控制设备参数为 entity_id 和 service, ha_get_state: 查询指定实体的当前状态 } }entities里把家里常用的灯和开关列出来并标注支持的功能和色温范围。这样 Agent 不需要每次任务都去遍历查询所有设备直接从这个文件里读节省推理 step 和 Token。scene_presets定义了一个“晚间待客”预设Agent 在收到模糊指令时可以参考这个预设来推断参数。tool_descriptions是给模型看的工具说明写得越清楚模型调用越准确。不要在这里写敏感信息因为 Agent 会把这个文件的内容加载到上下文里。3.3 环境变量注入不要把 Key 和 Token 硬编码在配置文件里。用环境变量export TAOTOKEN_API_KEYsk-你的TaoToken密钥 export HA_LONG_LIVED_TOKEN你的HomeAssistant长期令牌然后在config.toml里用${TAOTOKEN_API_KEY}引用。OpenClaw 启动时会自动读取环境变量并替换。如果你用 Docker 部署在docker-compose.yml的environment段里传入这两个变量。4. 验证请求一次设备开关的完整动作配置写好后先别急着让 Agent 处理模糊指令。用一条明确的开关指令验证整条链路是否通畅。这一步的目的是确认 TaoToken 通道能正确转发到 Home Assistant并且 Agent 能拿到状态回查结果。4.1 用 curl 直接验证 TaoToken 到 Home Assistant 的通道在 OpenClaw 所在的机器上执行curl -X POST https://taotoken.net/api/ha/services/light/turn_on \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { entity_id: light.living_room, brightness_pct: 75, color_temp_kelvin: 3000 }如果返回200 OK并且 Home Assistant 里的客厅灯亮了说明 TaoToken 的转发通道配置正确。如果返回401检查 API Key 是否正确如果返回404检查 Home Assistant 的实例地址和端口是否可达。4.2 通过 OpenClaw 发起一次 Agent 调用直接用 OpenClaw 的 CLI 发起一次任务openclaw run --config ./config.toml \ --task 打开客厅主灯亮度调到75%色温3000K观察输出日志。正常的执行流程应该是[step 1] 解析任务目标控制 light.living_room [step 2] 调用 ha_call_service: light.turn_on [step 3] 参数: brightness_pct75, color_temp_kelvin3000 [step 4] 调用 ha_get_state: light.living_room [step 5] 状态回查: stateon, brightness191, color_temp3000 [step 6] 任务完成反馈用户关键看第 4 步和第 5 步。很多 Agent 实现只做到第 3 步就返回“已完成”但实际上设备可能因为网络延迟或者服务调用失败并没有真正执行。状态回查是确认任务闭环的必要动作。如果第 5 步返回的state是off或者unavailableAgent 应该重试或者报告失败而不是直接说“已完成”。4.3 验证模糊指令的处理明确指令跑通后再试模糊指令openclaw run --config ./config.toml \ --task 朋友要来家里了帮我把灯都开一下然后调到晚上适合的颜色这次 Agent 会先读取settings.json里的entities和scene_presets找到evening_guest预设然后对light.living_room和light.bedroom分别调用light.turn_on参数用预设里的brightness_pct75和color_temp_kelvin3000。最后对两个实体做状态回查确认都变成on之后才反馈完成。如果 Agent 没有按预设执行而是去遍历查询所有设备说明settings.json里的entities没有被正确加载。检查文件路径是否在 OpenClaw 的工作目录下以及 JSON 格式是否合法。5. 本篇常见错排查配置过程中最容易踩的坑集中在通道鉴权、服务白名单和状态回查三个环节。下面按报错现象分类说明。5.1 401 UnauthorizedKey 或 Token 无效现象curl 请求返回401OpenClaw 日志里出现authentication failed。排查步骤先确认TAOTOKEN_API_KEY环境变量是否在当前 shell 里生效用echo $TAOTOKEN_API_KEY检查。如果为空说明环境变量没导出重新执行export或者写进.bashrc。如果 Key 正确但仍然 401检查 TaoToken 控制台里这个 Key 是否被禁用或者过期。另一个常见原因是 Home Assistant 的长期令牌失效。到 Home Assistant 的“安全”页面重新创建一个令牌替换HA_LONG_LIVED_TOKEN环境变量然后重启 OpenClaw。5.2 403 Forbidden服务被白名单拦截现象Agent 日志显示service not allowed: lock.unlock或者switch.turn_on被拒绝。排查检查config.toml里的allowed_services列表。如果你要控制的设备是switch类型但白名单里只写了light.turn_on就会被拦截。把需要的服务加进去。反过来如果你发现 Agent 试图调用门锁或者摄像头操作说明denied_services生效了这是预期行为不要为了“方便”把门锁加进白名单。5.3 404 Not FoundHome Assistant 实例地址错误现象TaoToken 返回404日志里出现ha_instance unreachable。排查确认ha_instance的 IP 和端口是否正确。Home Assistant 默认端口是8123如果你改了端口这里要同步改。另外确认 OpenClaw 所在的容器能 ping 通这个 IP。如果 OpenClaw 跑在 Docker 里而 Home Assistant 跑在宿主机上localhost是不通的要用宿主机的局域网 IP比如192.168.1.100。5.4 状态回查返回 unavailable现象Agent 调用ha_get_state返回state: unavailable但设备实际上已经开了。排查这种情况通常是 Home Assistant 的实体注册有问题或者设备离线但缓存状态没更新。先到 Home Assistant 的“开发者工具 → 状态”里手动查一下这个实体确认它的真实状态。如果 Home Assistant 里显示也是unavailable说明设备本身离线跟 Agent 无关。如果 Home Assistant 里显示on但 Agent 拿到unavailable检查 TaoToken 的转发路径是否命中了正确的 Home Assistant 实例。5.5 Agent 陷入循环Token 消耗过快现象日志里反复出现ha_get_state和ha_call_service任务迟迟不结束max_daily_tokens很快被耗尽。排查这种情况通常是因为settings.json里的entities没有覆盖到目标设备Agent 每次都要遍历查询。把常用设备全部写进entities并标注supported_features。另外检查max_steps是否设得太大建议不超过 15。如果任务确实复杂拆成多个子任务分步执行而不是让 Agent 在一个 loop 里跑到底。6. 让 Agent 安全接管从通道统一到权限收拢回到最初的问题Agent 要接管智能家居难点不在“能不能调 API”而在“怎么在受控权限下调 API”。TaoToken 在这里的作用是把模型调用和设备控制统一到一个 Base URL 和一个 Key 上Agent 的配置文件里不再出现 Home Assistant 的长期令牌权限边界通过allowed_services和denied_services在通道侧收拢。你现在可以做的下一步把config.toml和settings.json复制到你的 OpenClaw 工作目录替换环境变量先用一条明确的开关指令跑通链路再试模糊指令。如果遇到 401 或者 403回到第 5 节按报错现象排查。需要长期跑编码和 Agent 任务的可以到https://taotoken.net/api-keys创建一个专用 Key配合max_daily_tokens做额度控制。模型对话验证走https://taotoken.net/models接入文档在https://taotoken.net/doc。门锁可以读状态但不开放开锁能力摄像头可以读流但不开放写和删。这条红线在配置文件里写死比在提示词里叮嘱模型“不要开锁”可靠得多。
平方复杂度无法被常规优化消除)
