跳到主要内容

DuckyClaw 连接 OpenClaw

1. 概述​

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

OpenClaw 是一款开源 AI Agent 平台，可部署在 Linux / macOS / Windows 等系统上。其内置的 Gateway 服务默认监听 18789 端口，DuckyClaw 通过局域网（或公网）与其建立连接。

连接架构：

DuckyClaw (IoT 设备)
    │  WebSocket (ACP 协议)
    ▼
OpenClaw Gateway (PC / 服务器)
    │
    ▼
AI Agent (LLM 对话)

2. 前置条件​

2.1 软件准备​

软件说明下载
OpenClawAI Agent 平台，需在 PC 或服务器上安装官网下载
DuckyClaw 固件开发环境编译固件所需工具链参考 DuckyClaw 快速入门

2.2 网络要求​

  • 局域网模式：DuckyClaw 设备与安装 OpenClaw 的 PC 处于同一局域网，或同一 Wi-Fi 网络
  • 公网模式：OpenClaw 部署在服务器上，需获取服务器公网 IP 地址

2.3 DuckyClaw 基础配置​

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

备注

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

3. OpenClaw 配置文件位置​

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

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

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

快速打开配置目录：

方法一：终端命令

xdg-open ~/.openclaw

方法二：图形界面

打开文件管理器，按 Ctrl+L，在地址栏中输入 ~/.openclaw，然后按回车。

提示

.openclaw 是隐藏文件夹（以 . 开头）。如果在文件管理器中看不到它，按 Ctrl+H 显示隐藏文件。

4. 修改 OpenClaw Gateway 配置​

4.1 备份配置文件​

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

4.2 编辑配置文件​

终端编辑：

nano ~/.openclaw/openclaw.json

图形界面操作：

  1. 打开 ~/.openclaw 文件夹（参考第 3 节）
  2. 右键点击 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
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  }
}
注意

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

各字段说明：

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

4.4 重启 Gateway​

openclaw gateway restart
备注

若 openclaw 命令不可用，可完全退出并重新启动 OpenClaw 应用程序。

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"' ~/.openclaw/openclaw.json

5.3 验证 Gateway 可访问性​

在与 DuckyClaw 同网络的设备浏览器中访问：

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

如果返回 HTTP 响应（即便是错误页面），说明 Gateway 已成功监听局域网地址。若连接超时，请检查防火墙设置（见第 7 节）。

6. 配置 DuckyClaw 固件参数​

6.1 创建配置文件​

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

cp include/tuya_app_config_secrets.h.example include/tuya_app_config_secrets.h

6.2 修改配置内容​

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

/* openclaw gateway configuration */
#define OPENCLAW_GATEWAY_HOST            "xxx.xxx.xxx.xxx"   /* 替换为 OpenClaw 主机的局域网 IP */
#define OPENCLAW_GATEWAY_PORT            18789
#define OPENCLAW_GATEWAY_TOKEN           "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  /* 替换为实际 Token */
#define DUCKYCLAW_DEVICE_ID              "duckyclaw-001"     /* 设备唯一标识，可自定义 */

各字段说明：

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

6.3 重新编译并烧录​

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

7. 常见问题​

7.1 DuckyClaw 连接失败​

日志中的错误信息可能原因解决方法
acp tcp connect failedIP 不可达或端口未开放检查 IP 是否正确；检查防火墙是否放行 18789 端口
acp upgrade rejectedWebSocket 握手被拒绝确认 dangerouslyAllowHostHeaderOriginFallback: true 已设置并已重启 Gateway
acp connect res ok=falseToken 鉴权失败对比 openclaw.json 中的 Token 与固件 OPENCLAW_GATEWAY_TOKEN 是否一致
acp connect timeout网络不通或 Gateway 未启动确认 OpenClaw 正在运行；用浏览器访问 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，说明已成功绑定所有网卡（包括局域网）。

7.3 放行防火墙端口​

ufw：

sudo ufw allow 18789/tcp

firewalld：

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

7.4 配置修改未生效​

  • 确认修改的是正确的配置文件路径（参考第 3 节）
  • 确认已完整重启 Gateway（不只是刷新页面），命令：openclaw gateway restart
  • 如重启后仍未生效，尝试完全退出并重新启动 OpenClaw 应用