未名手记

OpenClaw 的 Nginx 反向代理配置

VPS 上 OpenClaw 2026.7.1

6,880字
29–44 分钟

/

,
blog.t725.cn/?p=2105

Nginx 反代：独立域名 or 子目录

使用 Nginx 反向代理 OpenClaw Gateway 的 control-ui，对外访问有两种方案：使用独立域名（比如：https://claw.t725.cn），或使用子目录（比如：https://t725.cn/claw），各有优缺点，取决于你自己的情况。

如果需要使用子路径反代OpenClaw，需要在 OpenClaw 配置此路径，而独立域名方式不需要。

$ openclaw config set gateway.controlUi.basePath '"/claw"'

效果是：

{
  "gateway": {
    "controlUi": {
      "basePath": "/claw"
    }
  }
}

让 Nginx 对 .js.map 请求，静默返回 204，或不记录日志

无论使用那一种方式，在Nginx access.log里会留下大量的 "GET /assets/xxx.js.map HTTP/2.0" 404 或 "GET /claw/assets/xxx.js.map HTTP/2.0" 404 ，如果使用fail2ban监控了404日志，就需要提前处理，防止误封禁。

  • .js.map 文件是“Source Map”（源代码映射）文件。因为为了让浏览器加载更快、体积更小，项目在发布时会经过打包（如 Vite、Webpack）和压缩混淆处理。而 .js.map 文件记录了一个“翻译对照表”，当浏览器开发者工具（DevTools）开启时，它会自动请求这个 .map 文件，并在“Sources（来源）”面板中，将压缩后的代码反向还原成你熟悉的可读源码。这样，即使你在线上调试，看到的也是漂亮的原始代码，断点也能打在正确的行数上。
  • 由Nginx匹配机制，注意以下配置内容，在配置文件中的先后顺序。
location ~* ^/assets/.*\.js\.map$ {
#location ~* ^/claw/assets/.*\.js\.map$ {
#location ~* \.js\.map$ {    # 简单全局匹配
    access_log off;          # 不记录日志，如果记录就是 404
    return 204;              # 204 是不会有错误日志，注意：会让浏览器认为成功，但无内容，不影响功能。
}

OpenClaw Gateway 服务：验证方式与反代

gateway.auth.mode 验证方式有很多种，比如：none 最开放，token/password 靠共享密钥，trusted-proxy 则依赖前置代理来完成认证。

  • token是默认方式，但不支持反向代理访问，因为只支持 127.0.0.1:18789 访问。

OpenClaw Gateway 有个设备批准接入机制，无论是token/password 、trusted-proxy，在设备首次接入时，需要先批准，才能进入 。

注意：如果配置 trusted-proxy 在服务器上使用 CLI 与 TUI 都会被拒绝，所以使用token吧。

接入设备 devices 查看与批准

  • 设备ID：与设备+浏览器有关，但与IP地址无关；所以，同一台电脑上不同的浏览器，或同一个浏览里不同用户，deviceId都是不同的。
  • Control UI上，在配对移动设备 –> 设备管理 中做设备的查看与批准
  • CLI上的设备查看与批准：
$ openclaw devices list                  # 可以看到 requestId 或 deviceId
$ openclaw devices approve <requestId>   # 通过申请，授予设备永久访问令牌
$ openclaw devices reject <requestId>    # 拒绝申请
$ openclaw devices clear --yes --pending # 清空所有待审批申请
$ openclaw devices remove <deviceId>     # 移除设备

接入节点 nodes 管理

$ openclaw nodes list [--connected]
$ openclaw nodes rename --node <节点ID/旧名称/IP> --name "自定义新名称"  # 改名，而 devices 没有重命名功能。
$ openclaw nodes describe --node "办公Windows主机"                      # 查看单台设备详细信息（确认改名是否生效）
$ openclaw nodes remove --node node_abc123                             # 删除失效节点

devices 与 nodes 的区别和联系

  • devices：准入授权层（身份凭证 / 审批入口），管「谁有资格连进来」，对应配对申请、设备准入、权限令牌、黑名单；是接入身份凭证管理。
  • nodes：受控执行层（远端主机 / 终端实例），管「已经连进来的机器」，对应远程执行、节点名称、在线状态、操作系统、资源信息；是远程被控主机实体。
维度devicesnodes
核心职能准入鉴权、配对审批、密钥权限管理远端主机实例、远程操作载体、状态管理
出现时机扫码 / 配对码发起请求就生成（pending）设备 approve 且节点程序成功连接网关后才生成
唯一标识deviceId /requestId（申请阶段）nodeId
能否重命名无改名命令，不可自定义展示名支持 nodes rename 自定义别名
存储内容密钥、角色权限、配对状态、准入记录主机名、IP、在线状态、系统、自定义显示名
断开连接影响device 记录永久保留，令牌有效node 仅标记为离线，不会删除
删除后果devices remove：销毁所有密钥，彻底禁止该客户端接入nodes remove：仅清除节点展示记录，device 准入凭证仍有效，重连会重新生成 node
典型命令devices list / approve / reject / revoke / removenodes list / rename / describe / remove

默认配置内容

后面的操作，是以下面的内容为基础

  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "xxxxxx"           // 可以使用 https://claw.t725.cn/?token=xxxxxx 跳过登录界面
    },
    "port": 18789,
    "bind": "loopback",           // 只能在本地访问，就是 127.0.0.1
    "tailscale": {                // Tailscale 能把分布在不同地方、不同网络下的设备连成一个安全的“局域网”
      "mode": "off",              // off 表示 OpenClaw 不主动配置，但并不代表你本机的 Tailscale 服务被停止了
      "resetOnExit": false        // 当 OpenClaw 网关关闭时，是否自动清除它之前通过 Tailscale 创建的路由或服务配置
    },
    "controlUi": {
      "allowInsecureAuth": true   // 是否允许在非 HTTPS 环境下进行认证
    }
  },

token 验证 + Nginx 反代访问

配置 OpenClaw Gateway

# 信任反向代理服务器的IP
openclaw config set gateway.trustedProxies '["127.0.0.1","172.27.x.x"]'
# 信任跨域/CORS 源站白名单
openclaw config set gateway.controlUi.allowedOrigins '["https://claw.t725.cn"]'

最终效果：

  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "xxxx"
    },
    "port": 18789,
    "bind": "loopback",
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    },
    "controlUi": {
      "allowInsecureAuth": true,
      "allowedOrigins": [
        "https://claw.t725.cn"
      ]
    },
    "trustedProxies": [
      "127.0.0.1",
	  "172.27.x.x"
    ]
  },

配置Nginx

    root   /data/www/html;
    index  index.html;
    client_max_body_size 20m;

    location /.well-known/ { default_type "text/plain"; }
    location ~* \.js\.map$ { access_log off; return 204; }
    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;

        # WebSocket 支持
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        # WebSocket 长连接超时设置
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;

        # 必要 proxy headers，理解：https://chat.deepseek.com/share/ioshxi34di5kk4t0iy
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
    }

trusted-proxy 验证 + Nginx 反代访问

trusted-proxy 模式并不免除设备配对，它只是将用户识别委托给代理，但首次连接仍需用户交互确认（配对）。配对的目的是防止未授权的客户端（即使通过代理）滥用 Gateway。

要使用这种方式，提前在token模式下，对设备ID做批次；而且切换后，在OpenClaw Gateway 服务的本地，使用CLI与TUI都被拒绝。所以不推荐使用，至少在20260701版本上。

配置 OpenClaw Gateway：基于默认配置内容，做调整。

# 切换认证模式为 trusted-proxy
openclaw config set gateway.auth.mode '"trusted-proxy"'
# 删除 token（trusted-proxy 模式不能混用 token）
openclaw config unset gateway.auth.token

# 设置用户身份标头名称
openclaw config set gateway.auth.trustedProxy.userHeader '"x-forwarded-user"'
# 可选：用于代理校验标头
openclaw config set gateway.auth.trustedProxy.requiredHeaders '["x-forwarded-proto", "x-forwarded-host"]'
# 可选：限制允许的用户，空代表允许所有
openclaw config set gateway.auth.trustedProxy.allowUsers '["1@a.b","2@a.b"]'

# 启用 loopback 支持（比如：Nginx 和 Gateway 在同一台机器是从 127.0.0.1 转发）
openclaw config set gateway.auth.trustedProxy.allowLoopback true

# 信任的反向代理服务器
openclaw config set gateway.trustedProxies '["127.0.0.1","172.27.x.x"]'
# 信任的跨域/CORS 源站白名单
openclaw config set gateway.controlUi.allowedOrigins '["https://claw.t725.cn"]'

效果

  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "trusted-proxy",
      "trustedProxy": {
        "userHeader": "x-forwarded-user",
        "requiredHeaders": [
          "x-forwarded-proto",
          "x-forwarded-host"
        ],
        "allowUsers": [
        ],
        "allowLoopback": true
      }
    },
    "port": 18789,
    "bind": "loopback",
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    },
    "controlUi": {
      "allowInsecureAuth": true,
      "allowedOrigins": [
        "https://claw.t725.cn"
      ]
    },
    "trustedProxies": [
      "127.0.0.1",
      "172.27.250.13"
    ]
  },

配置 Nginx

    # 在token 验证 + Nginx 反代访问的配置基础上，必须增加下面一行，没有是登录不了的。
    proxy_set_header X-Forwarded-User $remote_user;

    # 当然还要加上Nginx的认证，且能不能登录进去，还受 gateway.auth.trustedProxy.allowUsers 控制。
    auth_basic "Restricted File Manager";
    auth_basic_user_file /etc/nginx/conf.d/module.htpasswd;

OpenClaw 移动版

准备工作

在网页里点击手机配对，提示：无法创建设置码，也给了三个解决办法，任选其一就可以了。

GatewayRequestError: Gateway is only bound to loopback. Set gateway.bind=lan, enable tailscale serve, or configure plugins.entries.device-pair.config.publicUrl.

已有Nginx反代：开启 plugins.entries.device-pair.config.publicUrl

$ openclaw config set plugins.entries.device-pair.config.publicUrl "https://claw.t725.cn"

# 如果提示 plugins.entries.device-pair: plugin disabled (bundled (disabled by default)) but config is present，则启用 device-pair 插件
$ openclaw config set plugins.entries.device-pair.enabled true

修改网关绑定模式

$ openclaw config set gateway.bind lan

# 允许不安全认证（局域网HTTP场景）
$ openclaw config set gateway.controlUi.allowInsecureAuth true
# 添加局域网IP到允许列表（替换为你电脑的局域网IP）
$ openclaw config set gateway.controlUi.allowedOrigins '["http://192.168.1.100:18789"]'

启用 Tailscale Serve

OpenClaw-Android.apk

<待续，因为手机版本低，不支持>

后续

添加 Channel、Agent、Hooks、等等，比如：

# Hooks
$ openclaw hooks list                  # 注意：ready是就绪，不是启用状态。
$ openclaw config get hooks.internal   # 查看有没有开启
$ openclaw hooks enable <Hook>         # 开启一个Hook

# Channels 配置
$ openclaw channels list
$ openclaw configure --section channels

# Web Search 配置
$ openclaw skills list        # 显示所有SKILL
$ openclaw skills info tavily # 查看指定SKILL信息
$ openclaw configure --section web

# Skills 配置
$ openclaw configure --section skills

# Agents 配置
$ openclaw agents list
$ openclaw agents add life --workspace ~/.openclaw/workspace/life --bind openclaw-weixin:xxx-im.bot
$ openclaw agents add work --workspace ~/.openclaw/workspace/work --bind Feishu

发表回复

更多文章与分类

Access Axure Cloud Axure RP Bash Bat CentOS crontab Excel FTP Git JMeter macOS MariaDB Markdown MS Office 2010 从入门到精通 Nginx Obsidian OpenClaw Oracle Outlook PAC PHP Postman PowerPoint PowerShell Project Rclone RDMS RustDesk SoapUI SQL SSH SVN Tomcat Ubuntu Visio VMware WebDav Win-ACME Windows Word WordPress WPS Office XPath 正则表达式