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_PATxxx然后在这个终端启动了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_COUNTRYCN # 例如中国用CN美国用US英国用GB验证是否设置成功echo $LG_PAT应该能回显你的令牌部分显示。为什么推荐这种方式安全性变量存储在进程内存中不会在磁盘上留下明文文件。灵活性可以为不同的终端会话设置不同的变量。符合流程后续OpenClaw进程会继承这个环境生成的设备技能在运行时也能自然读取到。为了让这个配置永久生效你需要将其添加到Shell的配置文件中# 如果是bash echo export LG_PAT你的令牌 ~/.bashrc echo export LG_COUNTRYCN ~/.bashrc source ~/.bashrc # 使当前终端立即生效 # 如果是zsh echo export LG_PAT你的令牌 ~/.zshrc echo export LG_COUNTRYCN ~/.zshrc source ~/.zshrc方式二.env文件需谨慎文档提到可以在通用技能目录下创建.env文件。但这里有一个大坑这个.env文件绝对不能被提交到版本控制系统如Git也绝对不能被复制到其他目录。# 首先找到通用技能目录通常安装后在 cd ~/.openclaw/workspace/skills/lg-thinq-universal # 然后创建.env文件 cat .env EOF LG_PAT你的令牌 LG_COUNTRYCN 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或再次查询状态确认。可能原因2x-conditional-control乐观锁冲突。可能当前设备状态不符合命令执行的前提条件。例如在设备已经关机的状态下发送设置温度的命令可能会被服务器静默忽略。解决方案是对于关键操作采用“先查询状态再发送命令”的两步法。或者在技能逻辑中对于开机类命令不添加条件锁。排查方法打开技能目录下的日志文件如果配置了或者临时在skill.py的请求函数前后添加打印语句查看发送的请求体和收到的响应体确认API调用是否真的返回了成功。问题二OpenClaw偶尔回复“技能执行出错”。可能原因环境变量丢失。这通常发生在非交互式启动OpenClaw或者从系统服务启动时。环境变量没有被正确继承。解决方案确保OpenClaw是从一个已经设置了LG_PAT的终端中启动的。如果必须作为服务启动考虑使用系统级的环境变量配置文件如/etc/environment或在服务单元文件如systemd的.service文件中直接设置Environment字段。在设备技能代码的开头添加一个环境变量检查如果不存在则给出明确的错误提示而不是让它在调用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智能家居的乐趣所在。