该文章已生成可运行项目，
预览并下载项目源码
OpenClaw Gateway 配置与使用
🎯 博主简介
CSDN 「新星创作者」 人工智能技术领域博主，码龄5年，累计发布 180+篇原创 文章，博客总访问量 24万+浏览!
🚀 持续更新AI前沿实战知识，专注于 AI 技术实战，多个专栏详细解析，包括：
🔥 生产级 RAG 系统— 架构设计、多路召回、混合检索、生产优化
🤖 多 Agent 协作系统 — Swarm 架构、任务编排、状态管理
🔌 MCP 协议 — 协议规范与深度实现
⚡ OpenClaw超详细教程 — AI 助手框架进阶应用
✨ Agent记忆系统 — 深度解析Agent记忆系统
同时也涉猎计算机视觉、Java 后端与 Spring 生态、Transformer 等深度学习技术。坚持从架构到代码、从原理到部署的实战风格。每篇文章配套代码与扩展资料，欢迎交流探讨。
📱 公众号： Anyi研习社— 每天一点AI：资料、笔记、工具、趋势，一起进步。
🤝 商务合作：请搜索关注微信公众号 「Anyi研习社」
一、Gateway 是什么？
OpenClaw Gateway 是 OpenClaw 的核心服务组件，作为 AI 代理系统的控制中心和通信枢纽。
1.1 主要作用
Gateway 承担以下关键职责：
路由与控制平面：处理所有 AI 会话的路由、调度和状态管理
通道连接管理：维护与各消息平台（WhatsApp、Telegram、Discord、Slack 等）的连接
WebSocket 控制：提供 WebSocket 接口用于远程控制和监控
HTTP API 服务：提供 OpenAI 兼容 API、Responses API、工具调用 API 等
配置热加载：自动监测配置文件变化并应用更新。
安全认证：管理访问令牌、密码认证和配对机制。
1.2 架构概览
┌─────────────────────────────────────────────────────────────┐
│ OpenClaw Gateway │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │
│ │WebSocket│ │HTTP API │ │Control UI│ │Channel Connectors│ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────────┬────────┘ │
│ └────────────┴──────────┴─────────────────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ │Agent Core │ │
│ └───────────┘ │
└─────────────────────────────────────────────────────────────┘
二、启动和停止 Gateway
2.1 基本启动
# 默认端口启动
openclaw gateway
# 指定端口启动
openclaw gateway --port 18789
# 详细日志模式
openclaw gateway --port 18789 --verbose
# 强制启动（杀死占用端口的进程）
openclaw gateway --force
2.2 后台服务模式（推荐）
macOS (launchd)
# 安装为后台服务
openclaw gateway install
# 查看服务状态
openclaw gateway status
# 重启服务
openclaw gateway restart
# 停止服务
openclaw gateway stop
服务标签为 ai.openclaw.gateway（默认）或 ai.openclaw.<profile>（命名配置文件）。
Linux (systemd 用户服务)
# 安装服务
openclaw gateway install
# 启用并启动
systemctl --user enable --now openclaw-gateway.service
# 查看状态
openclaw gateway status
systemctl --user status openclaw-gateway
# 持久化（注销后仍运行）
sudo loginctl enable-linger <用户名>
Linux (系统服务)
# 重新加载服务配置
sudo systemctl daemon-reload
# 启用并启动
sudo systemctl enable --now openclaw-gateway.service
2.3 验证服务健康状态
# 查看网关状态
openclaw gateway status
# 查看详细状态
openclaw gateway status --deep
# JSON 格式输出
openclaw gateway status --json
# 实时日志
openclaw logs --follow
# 诊断检查
openclaw doctor
# 验证通道就绪
openclaw channels status --probe
健康基线：Runtime: running 和 RPC probe: ok
2.4 开发者快速启动
# 使用开发配置
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
开发配置默认使用隔离的状态目录和基础端口 19001。
三、端口配置
3.1 端口优先级
端口配置按以下顺序解析：
优先级 来源 示例
1 CLI 参数 --port 18789
2 环境变量 OPENCLAW_GATEWAY_PORT=18789
3 配置文件 gateway.port
4 默认值 18789
3.2 绑定模式
{
gateway: {
port: 18789,
bind: "loopback", // loopback | lan | tailnet | custom IP
},
}
绑定模式 说明
loopback (默认) 仅本地访问 (127.0.0.1)
lan 局域网可访问
tailnet Tailscale 网络可访问
自定义 IP 绑定到指定地址
3.3 多网关实例
大多数情况下只需运行一个 Gateway。如需多实例隔离：
// ~/.openclaw/a.json
{
gateway: { port: 19001 },
agents: { defaults: { workspace: "~/.openclaw/workspace-a" } },
}
// ~/.openclaw/b.json
{
gateway: { port: 19002 },
agents: { defaults: { workspace: "~/.openclaw/workspace-b" } },
}
启动命令：
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json \
OPENCLAW_STATE_DIR=~/.openclaw-b \
openclaw gateway --port 19002
四、模型配置
4.1 基本模型配置
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.2"],
},
models: {
"anthropic/claude-opus-4-6": { alias: "opus" },
"anthropic/claude-sonnet-4-5": { alias: "sonnet" },
"openai/gpt-5.2": { alias: "gpt" },
},
},
},
}
4.2 内置模型别名
别名 模型
opus anthropic/claude-opus-4-6
sonnet anthropic/claude-sonnet-4-5
gpt openai/gpt-5.2
gpt-mini openai/gpt-5-mini
gemini google/gemini-3-pro-preview
gemini-flash google/gemini-3-flash-preview
4.3 自定义模型提供商
{
models: {
mode: "merge",
providers: {
"custom-proxy": {
baseUrl: "http://localhost:4000/v1",
apiKey: "${CUSTOM_API_KEY}",
api: "openai-responses",
authHeader: true,
headers: { "X-Proxy-Region": "us-west" },
models: [
{
id: "llama-3.1-8b",
name: "Llama 3.1 8B",
api: "openai-responses",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 128000,
maxTokens: 32000,
},
],
},
},
},
}
4.4 本地模型配置
{
agents: {
defaults: {
model: { primary: "lmstudio/minimax-m2.1-gs32" },
},
},
models: {
mode: "merge",
providers: {
lmstudio: {
baseUrl: "http://127.0.0.1:1234/v1",
apiKey: "lmstudio",
api: "openai-responses",
models: [
{
id: "minimax-m2.1-gs32",
name: "MiniMax M2.1 GS32",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 196608,
maxTokens: 8192,
},
],
},
},
},
}
4.5 API 密钥配置
推荐使用环境变量：
# ~/.openclaw/.env
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-...
运行项目并下载源码
bash
1
2
3
4
或在配置文件中使用环境变量引用：
{
gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
models: {
providers: {
custom: { apiKey: "${CUSTOM_API_KEY}" },
},
},
}
运行项目并下载源码
json5
1
2
3
4
5
6
7
8
4.6 OAuth 认证配置
{
auth: {
profiles: {
"anthropic:subscription": {
provider: "anthropic",
mode: "oauth",
email: "user@example.com",
},
"anthropic:api": {
provider: "anthropic",
mode: "api_key",
},
},
order: {
anthropic: ["anthropic:subscription", "anthropic:api"],
},
},
}
运行项目并下载源码
json5
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
五、安全设置
5.1 认证配置
Gateway 默认要求认证。
{
gateway: {
auth: {
mode: "token", // token | password
token: "your-secure-token",
// 或使用密码
// password: "your-secure-password",
allowTailscale: true,
},
},
}
运行项目并下载源码
json5
1
2
3
4
5
6
7
8
9
10
11
也可以使用环境变量：
export OPENCLAW_GATEWAY_TOKEN="your-secure-token"
# 或
export OPENCLAW_GATEWAY_PASSWORD="your-secure-password"
运行项目并下载源码
bash
1
2
3
5.2 DM 访问策略
{
channels: {
whatsapp: {
dmPolicy: "pairing", // pairing | allowlist | open | disabled
allowFrom: ["+15555550123"],
},
telegram: {
enabled: true,
botToken: "YOUR_TOKEN",
dmPolicy: "allowlist",
allowFrom: ["tg:123456789"],
},
},
}
运行项目并下载源码
json5
1
2
3
4
5
6
7
8
9
10
11
12
13
14
DM 策略 说明
pairing (默认) 未知发送者收到配对码，需所有者批准
allowlist 仅允许 allowFrom 列表中的发送者
open 允许所有入站 DM（需设置 allowFrom: ["*"]）
disabled 忽略所有入站 DM
5.3 群组访问策略
{
channels: {
whatsapp: {
groupPolicy: "allowlist", // allowlist | open | disabled
groupAllowFrom: ["+15551234567"],
groups: {
"*": { requireMention: true },
},
},
},
}
运行项目并下载源码
json5
1
2
3
4
5
6
7
8
9
10
11
5.4 提及触发配置
群组消息默认要求提及才响应：
{
agents: {
list: [
{
id: "main",
groupChat: {
mentionPatterns: ["@openclaw", "openclaw"],
},
},
],
},
channels: {
whatsapp: {
groups: { "*": { requireMention: true } },
},
},
}
运行项目并下载源码
json5
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
5.5 远程访问配置
SSH 隧道方式
ssh -N -L 18789:127.0.0.1:18789 user@host
运行项目并下载源码
bash
1
然后客户端连接本地 ws://127.0.0.1:18789。
Tailscale 方式
{
gateway: {
bind: "tailnet",
auth: {
token: "your-token",
allowTailscale: true,
},
tailscale: {
mode: "serve",
resetOnExit: false,
},
},
}
5.6 沙箱配置（工具隔离）
{
agents: {
defaults: {
sandbox: {
mode: "non-main", // off | non-main | all
scope: "agent", // session | agent | shared
workspaceAccess: "none", // none | ro | rw
docker: {
image: "openclaw-sandbox:bookworm-slim",
workdir: "/workspace",
readOnlyRoot: true,
tmpfs: ["/tmp", "/var/tmp", "/run"],
network: "none",
user: "1000:1000",
},
},
},
},
}
六、常见问题排查
6.1 诊断命令阶梯
按顺序执行：
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
6.2 常见错误及解决方案
Gateway 无法启动
错误信息 原因 解决方案
refusing to bind gateway ... without auth 非 loopback 绑定但未配置认证 配置 gateway.auth.token 或 gateway.auth.password
another gateway instance is already listening / EADDRINUSE 端口被占用 使用 --force 或更换端口
Gateway start blocked: set gateway.mode=local 配置为远程模式 设置 gateway.mode="local"
unauthorized during connect 客户端与网关认证不匹配 检查令牌/密码配置
服务运行但无响应
# 检查通道状态
openclaw channels status --probe
# 检查配对状态
openclaw pairing list --channel whatsapp
# 查看配置
openclaw config get channels
# 实时日志
openclaw logs --follow
常见原因：
配对请求待批准
群组提及策略过滤 (requireMention)
通道/群组白名单不匹配
升级后问题
# 检查配置漂移
openclaw doctor
# 检查网关模式
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
# 重新安装服务
openclaw gateway install --force
openclaw gateway restart
6.3 配置热加载
Gateway 自动监测配置文件变化：
模式 行为
hybrid (默认) 安全更改立即生效，需重启的更改自动重启
hot 仅热加载安全更改，记录重启警告
restart 任何更改都重启 Gateway
off 禁用文件监测，需手动重启
{
gateway: {
reload: {
mode: "hybrid",
debounceMs: 300,
},
},
}
热加载 vs 需重启的字段：
类别 字段 需重启
通道、代理、模型、工具、会话 全部 否
Gateway 服务端 gateway.* (端口、绑定、认证、TLS) 是
基础设施 discovery, canvasHost, plugins 是
6.4 日志与调试
# 实时日志
openclaw logs --follow
# 启动时详细日志
openclaw gateway --verbose
# 深度诊断
openclaw doctor
openclaw gateway status --deep
6.5 完整配置示例
{
// 身份配置
identity: {
name: "MyAssistant",
theme: "helpful assistant",
emoji: "🤖",
},
// Gateway 配置
gateway: {
mode: "local",
port: 18789,
bind: "loopback",
auth: {
mode: "token",
token: "${OPENCLAW_GATEWAY_TOKEN}",
},
reload: { mode: "hybrid", debounceMs: 300 },
controlUi: { enabled: true, basePath: "/openclaw" },
},
// 代理配置
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: ["openai/gpt-5.2"],
},
timeoutSeconds: 600,
heartbeat: {
every: "30m",
target: "last",
},
},
},
// 通道配置
channels: {
whatsapp: {
dmPolicy: "pairing",
allowFrom: ["+15555550123"],
groups: { "*": { requireMention: true } },
},
telegram: {
enabled: true,
botToken: "${TELEGRAM_BOT_TOKEN}",
allowFrom: ["123456789"],
groups: { "*": { requireMention: true } },
},
},
// 会话配置
session: {
dmScope: "per-channel-peer",
reset: {
mode: "daily",
atHour: 4,
idleMinutes: 120,
},
},
// 定时任务
cron: {
enabled: true,
maxConcurrentRuns: 2,
sessionRetention: "24h",
},
// 日志配置
logging: {
level: "info",
consoleLevel: "info",
consoleStyle: "pretty",
},
}
附录：常用命令速查
操作 命令
启动网关 openclaw gateway
安装后台服务 openclaw gateway install
查看状态 openclaw gateway status
重启服务 openclaw gateway restart
停止服务 openclaw gateway stop
实时日志 openclaw logs --follow
诊断检查 openclaw doctor
通道状态 openclaw channels status --probe
获取配置 openclaw config get <path>
设置配置 openclaw config set <path> <value>
交互式配置 openclaw configure
查看模型状态 openclaw models status
————————————————
版权声明：本文为CSDN博主「安逸 i」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/sgr011215/article/details/158461927
(责任编辑：admin)本文地址：http://www.codehy.com/info/AI/2026/0410/27503.html
