网关配置

约 1023 字大约 3 分钟

配置详解

OpenClaw 配置文件位于 ~/.openclaw/openclaw.json。

配置格式

使用 JSON5 格式（支持注释）：

{
  // 网关配置
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "auth": {
      "token": "your-secret-token"
    }
  },
  
  // 智能体配置
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-20250514"
      }
    }
  },
  
  // 通道配置
  "channels": {
    "whatsapp": {
      "enabled": true
    }
  }

配置命令

## 获取配置值
openclaw config get gateway.port

## 设置配置值
openclaw config set gateway.port 19000

## 删除配置值
openclaw config unset gateway.auth.password

主要配置项

gateway

配置项	类型	默认值	说明
port	number	18789	端口
bind	string	loopback	绑定模式
auth.token	string	-	认证 token
auth.password	string	-	认证密码

agents.defaults

配置项	类型	说明
model.primary	string	主模型
model.fallbacks	array	故障转移模型
workspace	string	工作区路径
timeoutSeconds	number	超时时间

channels

各通道独立配置，参见通道文档。

环境变量

支持通过环境变量覆盖配置：

OPENCLAW_GATEWAY_PORT
OPENCLAW_GATEWAY_TOKEN
OPENCLAW_CONFIG_PATH
OPENCLAW_STATE_DIR

配置优先级

命令行参数
环境变量
配置文件
默认值

认证鉴权

网关支持多种认证方式保护访问。

认证方式

Token 认证

推荐方式，使用共享密钥：

{
  "gateway": {
    "auth": {
      "token": "your-secret-token"
    }
  }

或通过环境变量：

export OPENCLAW_GATEWAY_TOKEN="your-secret-token"

密码认证

{
  "gateway": {
    "auth": {
      "password": "your-password"
    }
  }

连接认证

WebSocket 连接时在 connect 帧中提供认证：

{
  "type": "req",
  "method": "connect",
  "params": {
    "auth": {
      "token": "your-secret-token"
    }
  }

设备配对

新设备需要配对审批：

设备发起连接
网关生成配对请求
操作员审批或拒绝
审批后颁发设备 token

## 查看待审批请求
openclaw nodes pending

## 审批
openclaw nodes approve requestId>

## 拒绝

本地信任

本地连接（回环或同主机 tailnet 地址）可以自动审批：

{
  "gateway": {
    "auth": {
      "allowLocalAutoApprove": true
    }
  }

Tailscale 认证

允许 Tailscale 身份认证：

{
  "gateway": {
    "auth": {
      "allowTailscale": true
    }
  }

安全建议

始终设置认证（即使本地）
使用强 token/密码
非本地访问启用 TLS
定期轮换凭据

安全加固

OpenClaw 安全最佳实践。

安全审计

运行安全审计：

openclaw security audit
openclaw security audit --deep

认证

始终启用认证

即使本地部署也应启用认证：

{
  "gateway": {
    "auth": {
      "token": "strong-random-token"
    }
  }

强密码/Token

使用至少 32 字符的随机 token
不要使用可猜测的密码
定期轮换

访问控制

限制发送者

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15551234567"],
      "dmPolicy": "allowlist"
    }
  }

群组访问

{
  "channels": {
    "whatsapp": {
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }

沙箱

启用沙箱限制智能体能力：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "enabled": true,
        "mode": "docker"
      }
    }
  }

参见沙箱。

工具策略

限制危险工具：

{
  "agents": {
    "defaults": {
      "toolPolicy": {
        "elevated": ["system.run", "browser.*"],
        "disabled": ["exec.sudo"]
      }
    }
  }

网络安全

绑定模式

loopback - 仅本地（最安全）
tailnet - Tailscale 网络
lan - 局域网
避免绑定到公网

TLS

远程访问应启用 TLS：

{
  "gateway": {
    "tls": {
      "enabled": true,
      "cert": "/path/to/cert.pem",
      "key": "/path/to/key.pem"
    }
  }

提示注入防护

使用强模型（更好的指令遵循）
限制工具权限
审查敏感操作
不公开给不受信任的用户

文件权限

确保配置文件权限：

chmod 600 ~/.openclaw/openclaw.json

远程访问

从远程位置访问 OpenClaw 网关。

方式

SSH 隧道

最简单的远程访问方式：

ssh -N -L 18789:127.0.0.1:18789 user@host

然后本地访问：

http://127.0.0.1:18789/?token=your-token

Tailscale（推荐）

使用 Tailscale 私有网络：

## 启动时启用 Tailscale Serve
openclaw gateway --tailscale serve

## 或 Funnel（公网访问）
openclaw gateway --tailscale funnel

配置：

{
  "gateway": {
    "bind": "tailnet",
    "auth": {
      "allowTailscale": true
    }
  }

直接绑定（不推荐）

绑定到局域网或公网（需要额外安全措施）：

{
  "gateway": {
    "bind": "lan",
    "auth": {
      "token": "strong-token"
    }
  }

远程模式设置

在客户端机器上：

openclaw setup --mode remote --remote-url ws://192.168.1.100:18789 --remote-token your-token

节点连接

远程节点连接到网关：

openclaw node run --host gateway-host --port 18789

或作为服务安装：

openclaw node install --host gateway-host --port 18789

TLS 配置

远程访问应启用 TLS：

{
  "gateway": {
    "tls": {
      "enabled": true,
      "cert": "/path/to/cert.pem",
      "key": "/path/to/key.pem"
    }
  }

节点连接时验证：

openclaw node run --host gateway-host --tls --tls-fingerprint sha256:xxx

防火墙

如果需要开放端口：

## Linux (ufw)
sudo ufw allow 18789/tcp

## macOS

最佳实践

优先使用 SSH 隧道或 Tailscale
始终启用认证
远程访问启用 TLS
避免直接暴露到公网
使用强 token