跳到主要内容

DuckyClaw 连接 TuyaClaw

1. 概述​

DuckyClaw 是运行在物联网设备上的 AI 语音助手固件，通过 ACP 协议（Agent Client Protocol，基于 WebSocket） 连接到 TuyaClaw Gateway，实现与 AI Agent 的实时对话。

TuyaClaw 是涂鸦智能推出的 AI Agent 桌面客户端，支持 Windows、macOS 和 Linux 系统。其内置了 OpenClaw 核心，并通过 Gateway 服务（默认监听 18789 端口）与 DuckyClaw 设备建立连接。

连接架构：

DuckyClaw (IoT 设备)
    │  WebSocket (ACP 协议)
    ▼
TuyaClaw Gateway (PC)
    │  
    ▼
AI Agent (LLM 对话)

2. 前置条件​

2.1 软件准备​

软件说明获取方式
TuyaClawAI Agent 平台（支持 Windows / macOS / Linux），需已安装并能正常启动官网下载
DuckyClaw 固件开发环境编译固件所需工具链参考 DuckyClaw 快速入门

2.2 网络要求​

  • DuckyClaw 设备与运行 TuyaClaw 的 PC 处于同一局域网，或同一 Wi-Fi 网络
  • 如果使用公网连接，需将 TuyaClaw Gateway 通过端口映射等方式暴露到公网

2.3 DuckyClaw 基础配置​

在进行本文配置前，请先完成 DuckyClaw 的基础配置（Wi-Fi 联网、固件烧录等）。

备注

参考：DuckyClaw 与 T5-AI 快速入门

3. TuyaClaw 配置文件位置​

TuyaClaw 的核心配置文件为 openclaw.json，不同系统的默认路径如下：

操作系统配置文件路径
Linux~/.tuyaclaw/openclaw.json
macOS~/.tuyaclaw/openclaw.json
WindowsC:\Users\<用户名>\.tuyaclaw\openclaw.json
备注

~ 表示当前用户的主目录，如 /home/username（Linux）或 /Users/username（macOS）。Windows 中 <用户名> 替换为你的登录用户名。

TuyaClaw 还有一个 Electron 层设置文件，存有 Token 供 UI 读取：

操作系统Electron 设置文件路径
Linux~/.config/tuyaclaw/settings.json
macOS~/Library/Application Support/tuyaclaw/settings.json
WindowsC:\Users\<用户名>\AppData\Roaming\tuyaclaw\settings.json

快速打开配置目录：

# 在终端中打开配置目录
xdg-open ~/.tuyaclaw

或直接在文件管理器中按 Ctrl+L 并输入 ~/.tuyaclaw。

4. 修改 TuyaClaw Gateway 配置​

4.1 备份配置文件​

cp ~/.tuyaclaw/openclaw.json ~/.tuyaclaw/openclaw.json.backup

4.2 编辑配置文件​

nano ~/.tuyaclaw/openclaw.json

也可以用任意文本编辑器打开该文件：在文件管理器中进入 ~/.tuyaclaw/ 目录，右键点击 openclaw.json，选择用文本编辑器打开。

4.3 修改 Gateway 配置段​

找到文件中的 "gateway" 字段，将其替换为以下内容（保留文件中其他配置不变）：

"gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
        "mode": "token",
        "token": "your_token_here"
    },
    "controlUi": {
        "dangerouslyAllowHostHeaderOriginFallback": true,
        "allowInsecureAuth": true,
        "dangerouslyDisableDeviceAuth": true
    }
}
注意

"token" 字段保持原有值不变，不要将 your_token_here 写入文件，填入你自己的 Token（见第 5.2 节获取方法）。

各字段说明：

字段说明
"bind": "lan"让 Gateway 监听局域网网卡 IP，而非仅 127.0.0.1（默认仅本机可访问），这是允许 DuckyClaw 连接的关键配置
dangerouslyAllowHostHeaderOriginFallback: true允许非 UI 来源（如 IoT 设备）发起 WebSocket 连接
allowInsecureAuth: true允许局域网非 HTTPS 环境下的认证
dangerouslyDisableDeviceAuth: true禁用设备级二次认证，仅凭 Token 完成鉴权

4.4 重启 TuyaClaw Gateway​

配置修改后，需重启 Gateway 使配置生效。

方法一：使用内置 CLI

~/.config/tuyaclaw/resources/cli/openclaw gateway restart

方法二：完全退出并重新启动 TuyaClaw

在系统托盘右键点击 TuyaClaw 图标，选择退出，然后重新启动程序。

5. 获取 IP 地址和 Token​

5.1 获取局域网 IP​

ip addr show | grep -E "inet " | awk '{print $2}' | cut -d'/' -f1 | grep -v "^127"

或：

hostname -I
提示

从输出结果中，选择与 DuckyClaw 设备处于同一局域网段的 IP 地址（通常是 192.168.x.x 或 10.x.x.x）。有线网络（以太网）比 Wi-Fi 更稳定，建议优先使用有线网络的 IP。

5.2 获取 Gateway Token​

Token 存储在 openclaw.json 的 gateway.auth.token 字段中。

grep '"token"' ~/.tuyaclaw/openclaw.json

或读取完整值：

python3 -c "import json; d=json.load(open('$HOME/.tuyaclaw/openclaw.json')); print(d['gateway']['auth']['token'])"

5.3 验证 Gateway 可访问性​

配置修改并重启后，在同网络中的浏览器访问：

http://<你的局域网IP>:18789/

若返回任意 HTTP 响应（包括错误页面），说明 Gateway 已成功监听局域网地址。若连接超时，请检查防火墙（见第 7.3 节）。

6. 配置 DuckyClaw 固件参数​

6.1 创建配置文件​

在 DuckyClaw 项目根目录下，将示例文件复制并重命名：

cp include/tuya_app_config_secrets.h.example include/tuya_app_config_secrets.h
备注

tuya_app_config_secrets.h 已被加入 .gitignore，不会被提交到版本库，适合存放敏感配置。

6.2 修改配置内容​

编辑 include/tuya_app_config_secrets.h，找到以下 ACP Gateway 相关宏定义，填入实际值：

/* openclaw / tuyaclaw gateway configuration */
#define OPENCLAW_GATEWAY_HOST            "xxx.xxx.xxx.xxx"   /* 替换为 TuyaClaw 所在主机的局域网 IP */
#define OPENCLAW_GATEWAY_PORT            18789
#define OPENCLAW_GATEWAY_TOKEN           "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  /* 替换为第 5.2 节获取的 Token */
#define DUCKYCLAW_DEVICE_ID              "duckyclaw-001"     /* 设备唯一标识，可自定义 */

各字段说明：

宏定义说明
OPENCLAW_GATEWAY_HOSTTuyaClaw 所在主机的局域网 IP（第 5.1 节获取）
OPENCLAW_GATEWAY_PORT固定为 18789，无需修改
OPENCLAW_GATEWAY_TOKEN第 5.2 节获取的 Token
DUCKYCLAW_DEVICE_ID设备名称，建议使用唯一标识（如 MAC 地址），用于在 TuyaClaw 中区分多台设备

6.3 重新编译并烧录​

完成配置后，重新编译固件并烧录到 DuckyClaw 设备。

7. 常见问题​

7.1 DuckyClaw 连接失败排查​

设备日志中的错误信息可能原因解决方法
acp tcp connect failedIP 不可达或端口未开放检查 IP 是否正确；检查防火墙是否放行 18789 端口
acp upgrade rejectedWebSocket 握手被 Gateway 拒绝确认 dangerouslyAllowHostHeaderOriginFallback: true 已设置并已重启 Gateway
acp connect res ok=falseToken 鉴权失败对比 openclaw.json 中的 Token 与固件 OPENCLAW_GATEWAY_TOKEN 是否完全一致
acp connect timeout网络不通或 Gateway 未启动确认 TuyaClaw 正在运行；用浏览器访问 http://<IP>:18789/ 验证
acp dns resolve failed主机名无法解析使用 IP 地址代替主机名

7.2 确认 Gateway 是否已绑定局域网地址​

修改配置并重启后，验证 Gateway 是否已绑定局域网地址：

netstat -tlnp | grep 18789
# 或
ss -tlnp | grep 18789

若 Local Address 显示 0.0.0.0:18789，说明 Gateway 已成功绑定所有网卡（包括局域网），DuckyClaw 可以连接。

若显示 127.0.0.1:18789，说明 bind: lan 未生效，请重新检查 openclaw.json 修改是否正确，并重启 TuyaClaw。

7.3 防火墙放行 18789 端口​

ufw：

sudo ufw allow 18789/tcp

firewalld：

sudo firewall-cmd --add-port=18789/tcp --permanent
sudo firewall-cmd --reload

7.4 配置修改未生效​

  • 确认编辑的是正确的 openclaw.json 文件路径（见第 3 节）
  • 确认 JSON 格式正确，可用在线 JSON 校验工具检查语法
  • 确认已完整重启 Gateway（退出 TuyaClaw 进程后重新启动，而非仅刷新页面）

7.5 与连接原生 OpenClaw 的区别​

对比项OpenClawTuyaClaw
支持系统Linux / macOS / WindowsLinux / macOS / Windows
核心配置文件~/.openclaw/openclaw.json~/.tuyaclaw/openclaw.json
Gateway 默认绑定local（需改为 lan）local（同样需改为 lan）
端口1878918789（相同）
获取 Tokengrep '"token"' ~/.openclaw/openclaw.jsongrep '"token"' ~/.tuyaclaw/openclaw.json
重启 Gatewayopenclaw gateway restartTuyaClaw UI 或内置 CLI
DuckyClaw 固件配置完全相同的宏定义完全相同的宏定义