企业官网建设流程全解析

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 和一个 Key，Home 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_KEY="sk-你的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_pct=75, color_temp_kelvin=3000 [step 4] 调用 ha_get_state: light.living_room [step 5] 状态回查: state=on, brightness=191, color_temp=3000 [step 6] 任务完成，反馈用户

关键看第 4 步和第 5 步。很多 Agent 实现只做到第 3 步就返回“已完成”，但实际上设备可能因为网络延迟或者服务调用失败并没有真正执行。状态回查是确认任务闭环的必要动作。如果第 5 步返回的state是off或者unavailable，Agent 应该重试或者报告失败，而不是直接说“已完成”。

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_pct=75和color_temp_kelvin=3000。最后对两个实体做状态回查，确认都变成on之后才反馈完成。

如果 Agent 没有按预设执行，而是去遍历查询所有设备，说明settings.json里的entities没有被正确加载。检查文件路径是否在 OpenClaw 的工作目录下，以及 JSON 格式是否合法。

5. 本篇常见错排查

配置过程中最容易踩的坑集中在通道鉴权、服务白名单和状态回查三个环节。下面按报错现象分类说明。

5.1 401 Unauthorized：Key 或 Token 无效

现象：curl 请求返回401，OpenClaw 日志里出现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 Found：Home 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。

门锁可以读状态，但不开放开锁能力；摄像头可以读流，但不开放写和删。这条红线在配置文件里写死，比在提示词里叮嘱模型“不要开锁”可靠得多。