LG ThinQ设备自动化控制：基于OpenClaw的通用管理器与安全集成方案-深圳市維司達科技有限公司

1. 项目概述：一个为LG ThinQ设备打造的自动化管家

如果你和我一样，家里有几台LG的智能家电，比如空调、冰箱、洗衣机，每次想用语音或者自动化控制它们，都得在手机App里点来点去，或者依赖某个封闭的智能音箱生态，那感觉确实不够“智能”。更别提想把这些设备接入自己搭建的自动化流程里了，官方API文档要么难找，要么调用复杂。最近我在折腾OpenClaw这个本地AI助手时，发现了一个名为“LG ThinQ Universal Skill”的项目，它完美地解决了这个痛点。简单来说，这是一个通用管理器，它能自动发现你LG账户下的所有智能设备，并为每一台设备生成一个独立的、轻量级的控制技能。最终实现的效果是，你可以直接用自然语言对OpenClaw说“把客厅空调调到26度”，而你的账户密码等敏感信息全程都得到了安全隔离。

这个项目的核心价值在于“自动化”和“安全”。它不是一个简单的API封装，而是一个智能的集成流水线。你只需要提供一次身份凭证，剩下的设备发现、技能生成、配置分发全部由它自动完成。这对于想要构建高度定制化智能家居，又注重隐私和本地化控制的玩家来说，是一个非常优雅的解决方案。无论你是Home Assistant的重度用户，还是喜欢用Node-RED编排自动化，亦或是单纯想给OpenClaw增加一些实体控制能力，这个项目都能提供一个坚实、安全的基础。

2. 核心原理与架构设计解析

2.1 为什么需要“通用管理器”而非单一技能？

在接触这个项目前，我尝试过直接为我的LG空调写一个控制脚本。很快我就遇到了几个棘手的问题：第一，每台设备的控制指令和状态参数都不尽相同，冰箱和空调的API结构天差地别；第二，如果为每台设备都单独配置一遍密钥，管理起来会是一场噩梦；第三，当新增设备时，又得重复整个开发流程。

LG ThinQ Universal Skill采用了一种“工厂模式”的架构。它本身（我们称之为通用管理器）并不直接控制任何设备。它的职责非常明确：

认证与发现：利用你提供的统一凭证（Personal Access Token），向LG官方服务器发起请求，拉取账户下所有已注册的设备列表及其详细信息。
技能模板化生成：项目内预设了针对不同类型设备（如AC、Washer）的“技能模板”。当发现一个设备后，管理器会根据其类型，选择一个对应的模板。
实例化与隔离：管理器将设备特定的信息（如唯一的deviceId、型号、支持的功能集）填充到模板中，生成一个独立的、只属于这台设备的技能文件夹。最关键的一步是，它不会将你的主令牌（LG_PAT）复制进去，从而实现了权限隔离。

这样做的好处显而易见。对于用户，你只需关心一个入口（通用管理器）的配置。对于系统，每个设备技能都是轻量、专注且无敏感信息的，即使其中一个技能的配置被泄露，也不会危及你的整个LG账户。

2.2 安全通信与凭证流转机制

安全是这个项目的设计基石。我们来拆解一下整个流程中，敏感的LG_PAT是如何被保护和使用的：

凭证注入点唯一：LG_PAT和LG_COUNTRY这两个核心凭证，仅且必须在通用管理器运行时被提供。按照文档，最佳实践是通过Shell的环境变量（export）来设置。这意味着凭证只存在于当前Shell会话的内存中，不会写入任何技能文件夹的磁盘。
设备技能的无状态设计：生成的设备技能（如lg-ac-livingroom）内部，只包含该设备的LG_DEVICE_ID和一些静态配置。当OpenClaw加载这个技能并需要执行操作时（例如“开机”），该技能会向OpenClaw运行时环境“请求”执行一个命令。这个命令的执行上下文，仍然是当初启动OpenClaw的那个Shell环境。因此，设备技能本身不需要、也不存储LG_PAT，但它运行时却能“继承”到Shell环境中已有的LG_PAT，从而完成API调用。
API调用的乐观锁：项目提到了“optimistic locking (x-conditional-control)”。这是一个非常重要的细节。在物联网控制中，网络延迟可能导致命令乱序到达。例如，你先发送“开机”，紧接着发送“设置温度到26度”。如果第二个命令先到，而设备尚未开机，可能会出错。x-conditional-control是一种HTTP请求头，你可以附带一个期望的设备状态值（如"power": "off"）。服务器只有在设备当前状态与期望值匹配时，才会执行命令。这确保了命令执行的确定性和安全性，避免了因状态同步问题导致的误操作。

注意：务必理解环境变量的作用域。如果你在终端A中设置了export LG_PAT=xxx，然后在这个终端启动了OpenClaw，那么所有操作都是正常的。但如果你关闭了这个终端，或者从图形界面点击图标启动了一个新的OpenClaw实例，新的进程将无法获取这些环境变量，会导致设备技能报401错误。因此，建议将环境变量设置写入Shell的启动配置文件（如~/.bashrc或~/.zshrc），或者使用更专业的秘密管理工具。

3. 从零开始的详细配置与实操指南

纸上得来终觉浅，下面我结合自己的搭建过程，把每一步的细节、可能遇到的坑都捋一遍。我的环境是Ubuntu 22.04，但步骤在macOS和WSL上也是通用的。

3.1 前期准备：获取关键令牌（LG_PAT）

这是整个流程中最关键，也是唯一需要与LG官方交互的一步。文档中给的链接https://connect-pat.lgthinq.com是入口。

实操细节与避坑：

登录账户：确保使用你手机LG ThinQ App上登录的同一个账户。地区选择可能影响可用设备，建议与App内设置一致。
创建令牌：点击“ADD NEW TOKEN”后，你会看到一个权限选择列表。这里有个重要技巧：不要无脑全选。根据最小权限原则，只勾选你计划通过OpenClaw控制的功能。例如，对于空调，勾选“Control”和“Monitor”通常就够了。这能在一定程度上降低令牌泄露的风险。令牌名称可以随意，比如“My-OpenClaw”。
立即复制：点击“CREATE TOKEN”后，令牌只会显示一次。请务必立即将其复制到剪贴板或一个临时安全的地方。关闭页面后就再也找不回来了，只能重新创建。这个令牌是一长串看起来像乱码的字符串。

3.2 核心环境配置：两种方式的深度对比

项目推荐了两种方式设置凭证：Shell环境变量和.env文件。我强烈推荐并详细解释第一种（Shell环境变量），因为它更安全、更符合Linux哲学。

方式一：Shell环境变量（推荐）打开你的终端，执行：

export LG_PAT="你刚才复制的长长令牌" export LG_COUNTRY="CN" # 例如中国用CN，美国用US，英国用GB

验证是否设置成功：echo $LG_PAT，应该能回显你的令牌（部分显示）。

为什么推荐这种方式？

安全性：变量存储在进程内存中，不会在磁盘上留下明文文件。
灵活性：可以为不同的终端会话设置不同的变量。
符合流程：后续OpenClaw进程会继承这个环境，生成的设备技能在运行时也能自然读取到。

为了让这个配置永久生效，你需要将其添加到Shell的配置文件中：

# 如果是bash echo 'export LG_PAT="你的令牌"' >> ~/.bashrc echo 'export LG_COUNTRY="CN"' >> ~/.bashrc source ~/.bashrc # 使当前终端立即生效 # 如果是zsh echo 'export LG_PAT="你的令牌"' >> ~/.zshrc echo 'export LG_COUNTRY="CN"' >> ~/.zshrc source ~/.zshrc

方式二：.env文件（需谨慎）文档提到可以在通用技能目录下创建.env文件。但这里有一个大坑：这个.env文件绝对不能被提交到版本控制系统（如Git），也绝对不能被复制到其他目录。

# 首先，找到通用技能目录，通常安装后在： cd ~/.openclaw/workspace/skills/lg-thinq-universal # 然后创建.env文件 cat > .env << EOF LG_PAT=你的令牌 LG_COUNTRY=CN EOF

使用这种方式后，你必须在这个特定目录下运行管理脚本，脚本才能读取到.env文件。如果你在其他地方调用，或者OpenClaw从其他路径加载技能，就会找不到凭证。

重要警告：无论用哪种方式，都绝对不要将LG_PAT明文写入任何设备技能文件夹内的文件。设备技能文件夹应该看起来是“干净”的，只包含设备ID和逻辑代码。

3.3 安装与初始发现流程

安装过程很简单，用OpenClaw的包管理工具clawhub即可：

clawhub install lg-thinq-universal

安装完成后，先不急着运行OpenClaw。我们可以先用通用管理器自带的工具脚本验证一下配置，并查看设备列表：

# 切换到技能目录（如果使用.env方式，必须在此目录下执行） cd ~/.openclaw/workspace/skills/lg-thinq-universal # 验证令牌和国家码配置是否正确 python scripts/lg_api_tool.py check-config # 预期输出应显示你的国家码和令牌（部分掩码），确认配置已加载。 # 执行设备发现，这是最激动人心的一步 python scripts/lg_api_tool.py list-devices

如果一切顺利，list-devices命令会返回一个JSON格式的列表，包含你家里所有在LG ThinQ App中注册的设备的详细信息，比如设备ID、别名、类型、型号等。请记录下这些信息，尤其是deviceId，后续每个生成的技能都会基于这个ID。

常见问题排查：

返回空列表[]：99%的情况是设备未在LG ThinQ App中成功注册或当前离线。请打开手机App，确认设备状态为“在线”。有时需要等待几分钟让云端同步。
报错401 Unauthorized：说明LG_PAT无效或过期。请回到connect-pat.lgthinq.com重新生成令牌，并更新你的环境变量或.env文件。
报错Invalid country code：确认LG_COUNTRY使用的是两位大写ISO国家代码，并且与你LG账户的地区设置一致。

3.4 触发OpenClaw自动化工作流

验证发现流程没问题后，就可以请出主角OpenClaw了。按照文档提示，你需要向OpenClaw发送一个特定的指令来触发它的自动化集成流程。这个设计的精妙之处在于，它将复杂的后续步骤（如根据发现结果生成多个技能、组装工作区）封装成了一个简单的自然语言指令。

启动你的OpenClaw，然后在聊天框中输入：

I have installed the lg-thinq-universal skill and added the tokens. Please follow the SKILL.md to run the discovery setup and help me assemble the workspace for my LG devices.

发送后，OpenClaw（具体来说是背后的AI Agent）会识别这个指令，并自动执行SKILL.md（通常是技能目录下的一个说明文档）中定义的操作序列。这通常包括：

再次运行设备发现，确保信息最新。
为每一个发现的设备，在OpenClaw的技能工作区（workspace）内，创建一个独立的技能文件夹，例如lg-ac-livingroom,lg-washer-utility。
将设备特定的配置（主要是LG_DEVICE_ID）和对应的控制逻辑模板写入这些文件夹。
可能还会进行一些技能注册或刷新的操作，让OpenClaw能立刻识别到这些新技能。

这个过程完全是自动化的。你只需要泡杯茶等待一会儿，然后就能在OpenClaw的技能列表里看到以“lg-”开头的、以你设备命名的专属技能了。

4. 技能使用、维护与高级技巧

4.1 与你的设备自然对话

自动化设置完成后，乐趣才真正开始。你不再需要记忆复杂的命令或参数，直接像对人说话一样对OpenClaw下达指令：

基础控制：“打开客厅空调。”、“关闭洗衣机。”
状态查询：“卧室空调现在多少度？”、“冰箱运行是否正常？”
高级设置：“把书房空调设为除湿模式，风速调到自动。”、“让客厅空调两小时后关闭。”

OpenClaw会将这些自然语言解析成意图，然后路由到对应的设备技能去执行。技能内部会构建出符合LG API规范的HTTP请求，并利用Shell环境中的LG_PAT完成认证和发送。

4.2 设备列表的更新与技能管理

家电不是一成不变的。你可能新买了一台LG烘干机，或者淘汰了旧冰箱。这时就需要更新设备列表。

操作流程：

首先，在LG ThinQ App中完成新设备的添加和配置，确保其在线。
然后，回到通用管理器目录，重新运行发现脚本（或者直接再次运行./setup.sh如果脚本提供了更新功能）：
```
cd ~/.openclaw/workspace/skills/lg-thinq-universal python scripts/lg_api_tool.py list-devices # 查看新设备是否出现
```
最后，再次通过OpenClaw触发自动化工作流（发送同样的指令）。OpenClaw的Agent应该能智能地识别出已有技能和新增设备，并为新设备生成技能，而不会影响旧的。

如何管理已生成的技能？生成的设备技能位于类似~/.openclaw/workspace/skills/的目录下，以独立的文件夹存在。你可以：

查看技能配置：进入技能文件夹，查看skill.py或config.json，了解其控制逻辑。
手动调试：在技能目录下，有时会有测试脚本，你可以手动运行来调试某个特定命令。
删除技能：如果设备已移除，直接删除对应的技能文件夹即可。下次运行发现时，它不会再被创建。

4.3 深入原理：理解生成的技能如何工作

生成了一个设备技能后，我们不妨深入其内部，看看它到底是怎么运作的。以空调技能为例，其核心可能包含以下几个部分：

意图定义：在skill.py中，会定义一系列OpenClaw能识别的“意图”，如SetTemperatureIntent、ChangeModeIntent、TurnOnOffIntent。
参数提取：从用户语句中提取关键参数，例如从“调到26度”中提取温度值26。
API请求构造：根据意图和参数，构造一个发送给LG服务器的HTTP POST请求。请求体中包含了具体的控制指令，其格式需要匹配LG API的文档。例如，设置温度的请求体可能是{"command": "Set", "value": "26", "type": "Temperature"}。
安全头注入：请求中会包含X-Device-ID头（即本技能的LG_DEVICE_ID）和X-conditional-control头（用于乐观锁）。而最关键的Authorization头（Bearer Token），技能代码里并没有硬编码，它依赖于一个运行时从环境变量读取LG_PAT的函数。
执行与响应处理：发送请求，解析LG服务器返回的JSON响应，将其转换为一句人类可读的回复，如“已成功将空调设置为26度”。

这个模式使得每个技能都极其轻量且安全。你甚至可以手动复制一个空调技能文件夹，修改其中的LG_DEVICE_ID，就快速创建出控制第二台空调的技能（当然，通用管理器已经帮你自动化了这事）。

4.4 故障排除与深度调试记录

在实际使用中，你可能会遇到一些超出基础FAQ的问题。以下是我踩过的一些坑和解决方案：

问题一：命令执行成功，但设备无反应。

可能原因1：设备状态同步延迟。LG云端或设备本地响应有延迟。可以尝试在发送命令后，等待10-15秒，再通过App或再次查询状态确认。
可能原因2：x-conditional-control乐观锁冲突。可能当前设备状态不符合命令执行的前提条件。例如，在设备已经关机的状态下发送设置温度的命令，可能会被服务器静默忽略。解决方案是，对于关键操作，采用“先查询状态，再发送命令”的两步法。或者，在技能逻辑中，对于开机类命令，不添加条件锁。
排查方法：打开技能目录下的日志文件（如果配置了），或者临时在skill.py的请求函数前后添加打印语句，查看发送的请求体和收到的响应体，确认API调用是否真的返回了成功。

问题二：OpenClaw偶尔回复“技能执行出错”。

可能原因：环境变量丢失。这通常发生在非交互式启动OpenClaw，或者从系统服务启动时。环境变量没有被正确继承。
解决方案：
1. 确保OpenClaw是从一个已经设置了LG_PAT的终端中启动的。
2. 如果必须作为服务启动，考虑使用系统级的环境变量配置文件（如/etc/environment）或在服务单元文件（如systemd的.service文件）中直接设置Environment字段。
3. 在设备技能代码的开头，添加一个环境变量检查，如果不存在则给出明确的错误提示，而不是让它在调用API时才失败。

问题三：如何控制非标准或新型号设备？项目内置的模板可能无法覆盖所有LG设备型号，特别是较新或较冷门的型号。

探索方法：使用通用管理器中的lg_api_tool.py脚本，有一个潜在的高级功能是monitor或get-capabilities，可以获取指定设备的完整能力列表和可用的命令集。通过分析这些数据，你可以了解该设备支持的API。
扩展技能：你可以基于已有的最接近的设备模板（如同样是空调），复制一份，然后根据新设备的能力JSON，修改其请求构造逻辑。这需要一定的Python和HTTP API知识。修改后，可以手动将其放入技能目录，并确保其元数据（如技能名称、意图定义）是唯一的。

问题四：性能与网络延迟考虑所有命令都需要经过你的本地主机 -> 互联网 -> LG云端 -> 设备，这个链路较长。

优化建议：对于需要频繁查询状态的场景（如温度传感器），不要设计成每秒查询一次。合理的轮询间隔是30秒到几分钟。对于控制命令，做好异步处理和超时设置，避免OpenClaw对话界面长时间卡住。
本地缓存：可以考虑在技能中增加一个简单的内存缓存，对于短时间内重复的查询（如“当前温度”），直接返回缓存值，并后台异步更新，以提升对话响应速度。

5. 项目评价与未来扩展思考

经过一段时间的深度使用，我认为LG ThinQ Universal Skill项目代表了一种非常务实的智能家居集成思路：以自动化工具解决重复劳动，以架构设计保障安全底线。它没有尝试去逆向工程或破解本地协议，而是规规矩矩地利用官方提供的API接口，这保证了长期的稳定性和合法性。其“管理器-子技能”的架构，也体现了很好的软件工程思想，解耦了认证、发现和控制逻辑。

对于想要进一步扩展的开发者，这个项目也留下了清晰的接口和模式。例如，你可以：

贡献新的设备模板：如果你成功适配了一个新的设备类型（如LG的智能灯或烤箱），可以向项目提交Pull Request，丰富其官方支持的设备列表。
集成到更广的生态：既然每个设备技能本质是一个独立的、可通过自然语言触发的模块，那么理论上也可以被其他兼容OpenClaw协议的系统调用。你可以编写一个桥接服务，将这些技能暴露给Home Assistant的Conversation组件，或者做成一个HTTP API服务，供Node-RED调用。
增强本地化与上下文：目前的技能可能还比较“机械”，你可以为其增加更多的上下文理解。例如，当用户说“我有点热”，技能可以结合房间温湿度传感器的历史数据（如果接入了其他系统），智能地决定是将空调降温2度，还是先开启风扇。

最后，一个重要的提醒是，任何依赖云服务的集成，其可用性都受制于服务提供商。LG有权更改其API接口或令牌发放策略。因此，对于核心的家庭自动化逻辑，建议增加一层本地状态缓存和降级处理。例如，当检测到LG API连续不可用时，可以自动切换到预设的本地场景模式。

这个项目最大的价值，在于它为你打开了一扇门，让你能用自己熟悉的工具和语言，去安全、灵活地控制那些原本封闭在厂商生态里的设备。这种“夺回控制权”的感觉，正是DIY智能家居的乐趣所在。