OpenClaw 官网 https://openclaw.ai/ 开源地址：https://github.com/openclaw/openclaw/ 本文安装不使用sandbox
安装(建议)
该向导会安装 Gateway 守护进程，使其保持运行状态。
#Runtime: Node ≥22.
npm install -g openclaw@latest
openclaw onboard --install-daemon
从源码安装，参考 https://github.com/openclaw/openclaw#from-source-development 网关（gateway）完整安全指南参考 https://docs.openclaw.ai/gateway/security
更新
npm i -g openclaw@latest
#或
pnpm add -g openclaw@latest
启动
openclaw gateway --port 18789 --verbose
Nginx代理
http {
##
# Basic Settings
##
sendfile on;
tcp_nopush on;
types_hash_max_size 2048;
# server_tokens off;
# server_names_hash_bucket_size 64;
# server_name_in_redirect off;
include /etc/nginx/mime.types;
default_type application/octet-stream;
include /etc/nginx/mime.types;
default_type application/octet-stream;
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
map "$http_upgrade$arg_token" $should_redirect {
default 0;
"" 1;
}
server {
listen 8080;
server_name _;
location / {
proxy_pass http://127.0.0.1:18789/;
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_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 86400;
proxy_connect_timeout 86400;
}
}
}
简单OpenClaw.json
{
"agents": {
"defaults": {
"workspace": "/root/.openclaw/workspace",
"compaction": {
"mode": "safeguard"
},
"maxConcurrent": 4,
"subagents": {
"maxConcurrent": 8
}
}
},
"tools": {
"profile": "coding"
},
"messages": {
"ackReactionScope": "group-mentions"
},
"commands": {
"native": "auto",
"nativeSkills": "auto",
"restart": true,
"ownerDisplay": "raw"
},
"session": {
"dmScope": "per-channel-peer"
},
"gateway": {
"port": 18789,
"mode": "local",
"bind": "lan",
"controlUi": {
"allowedOrigins": ["http://127.0.0.1:18789"],
"dangerouslyAllowHostHeaderOriginFallback": true
},
"auth": {
"mode": "token",
"token": "12345678912345678923123123123"
},
"tailscale": {
"mode": "off",
"resetOnExit": false
},
"nodes": {
"denyCommands": [
"camera.snap",
"camera.clip",
"screen.record",
"contacts.add",
"calendar.add",
"reminders.add",
"sms.send"
]
}
},
"meta": {
"lastTouchedVersion": "2026.3.7",
"lastTouchedAt": "2026-03-08T11:47:44.804Z"
}
}
pairing required 错误
-
核心原理：OpenClaw 采用基于设备的访问控制模型。当任何客户端（浏览器、CLI、手机 App 或 Node 节点）首次连接到 Gateway 时：
-
设备识别：Gateway 生成唯一的设备身份标识
-
请求创建：创建待审批的配对请求（Pending Request）
-
连接挂起：连接被挂起，等待管理员显式批准
-
超时断开：若 30 秒内未批准，WebSocket 返回 1008 错误码并断开
在终端中执行以下命令（保持 Gateway 运行）：
openclaw devices list
若列表为空，说明请求已过期，需刷新浏览器或重启 CLI 重新触发配对
- Role 列显示设备类型：
- browser（浏览器）- 通过网页界面访问的设备
- node（节点）- macOS/iOS/Android 节点设备
- cli（命令行）- 通过命令行工具访问的设备
复制你要批准的 Request ID
openclaw devices approve <Request ID>
批量与脚本化处理
# 自动批准所有待处理的浏览器设备
openclaw devices list --json | jq -r '.[] | select(.role=="browser") | .id' | \
xargs -I {} openclaw devices approve {}
# 自动批准所有设备（非常危险，仅用于测试环境）
openclaw devices list --json | jq -r '.[].id' | \
xargs -I {} openclaw devices approve {}
control ui requires device identity (use HTTPS or localhost secure context)
- 启用 HTTPS（必需） 即使是局域网访问，也需要 HTTPS 来进行正确的设备身份验证：
openclaw config set gateway.tls.enabled true
OpenClaw 将在~/.openclaw/gateway/tls/创建证书.
- 配置 trustedProxies 将所有连接视为本地连接
openclaw config set gateway.trustedProxies '["0.0.0.0/0"]'
- 确保已启用 allowInsecureAuth
openclaw config set gateway.controlUi.allowInsecureAuth true
- 重启网关
openclaw gateway restart
配置预览
{
"gateway": {
"port": 18789,
"mode": "local",
"bind": "lan",
"controlUi": {
"enabled": true,
"allowInsecureAuth": true,
"dangerouslyDisableDeviceAuth": false
},
"auth": {
"mode": "token",
"token": "Your-Token"
},
"trustedProxies": [
"0.0.0.0/0"
],
"tls": {
"enabled": true,
"autoGenerate": true
}
}
}
重置Token
# 生成新 Token
openclaw config set gateway.auth.token $(openssl rand -hex 16)
docker restart openclaw
# 重新获取 URL
openclaw dashboard --print-url
关于gateway的bind
origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)
如果您只需要本地访问（推荐）：强制环回绑定并重启：
gateway: { bind: "loopback" }
如果需要 LAN/反向代理访问：设置一个显式的源允许列表（源格式为协议 + 主机 + 端口，不包含路径），然后重启：
gateway: {
bind: "lan",
controlUi: {
allowedOrigins: ["http://127.0.0.1:18789","http://<your-host>:18789"],
},
}
如果只是在本地进行测试，暂时不关心源安全
{
"gateway": {
"controlUi": {
"dangerouslyAllowHostHeaderOriginFallback": true
}
}
}
如果use HTTPS or localhost secure context
"gateway": {
"controlUi": {
"allowedOrigins": ["http://127.0.0.1:18789", "http://YOUR_SERVER_IP:18789"],
"allowInsecureAuth": true,
"dangerouslyDisableDeviceAuth": true
}
Gateway 管理
# 查看状态
openclaw gateway status
# 启动/停止/重启
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
配置管理
# 运行配置向导
openclaw onboard
# 获取/设置配置值
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.model.primary "openai/gpt-5.2"
诊断工具
# 健康检查
openclaw doctor
# 自动修复
openclaw doctor --fix
# 查看日志
openclaw logs --follow
引用：
OpenClaw Pairing required 错误解决方案详解 https://zhuanlan.zhihu.com/p/2005687480976970296
有用的issues: https://github.com/openclaw/openclaw/issues/25009
本地优先网关——会话、通道、工具和事件的单一控制平台：https://docs.openclaw.ai/gateway
多渠道收件箱——WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、BlueBubbles（iMessage）、iMessage（旧版）、IRC、Microsoft Teams、Matrix、飞书、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Tlon、Twitch、Zalo、Zalo Personal、WebChat、macOS、iOS/Android。 https://docs.openclaw.ai/channels
多代理路由— 将入站通道/帐户/对等体路由到隔离的代理（工作区 + 每个代理的会话）。 https://docs.openclaw.ai/gateway/configuration
其它 https://github.com/openclaw/openclaw#highlights
Docker OpenClaw 生产环境部署指南（单机架构版） https://bbs.huaweicloud.com/blogs/474393
一键安装 https://oneclaw.cn/
评论