编程语言Node.jsAI
OpenClaw Gateway 常见问题解答
本文解答了 OpenClaw Gateway 的核心概念、配置管理、路由会话、安全认证、多智能体架构及 API 集成等常见问题。重点阐述了 Gateway 作为控制面与 Agent 执行大脑的区别，介绍了配置文件位置、端口绑定模式、Token 认证机制以及多智能体隔离方案。同时提供了 OpenAI 兼容 API 调用方式和故障排查指南，帮助用户快速上手并解决常见部署问题。
本文解答了 OpenClaw Gateway 的核心概念、配置管理、路由会话、安全认证、多智能体架构及 API 集成等常见问题。重点阐述了 Gateway 作为控制面与 Agent 执行大脑的区别，介绍了配置文件位置、端口绑定模式、Token 认证机制以及多智能体隔离方案。同时提供了 OpenAI 兼容 API 调用方式和故障排查指南，帮助用户快速上手并解决常见部署问题。
A: Gateway 是 OpenClaw 的控制面进程，是整个架构的核心枢纽。它承担以下关键职责：
node.invoke 调用已连接的 Node（设备/能力端点）执行具体操作Gateway 是 OpenClaw 的"交通指挥中心"，所有消息、设备、智能体都由它统一调度。
A: 这是一个常见误区。正确的理解是：
| 组件 | 角色定位 | 关系 |
|---|---|---|
| Gateway | 控制面/调度中心 | 负责"接消息、做路由、管会话" |
| Agent | 执行大脑 | 负责"理解、推理、执行"，由 Gateway 驱动运行 |
认为 "Gateway 就是 OpenClaw 核心" 是错误的。Gateway 是基础设施，Agent 才是业务逻辑的执行者。
A: Gateway 默认使用以下端口：
18789（HTTP + WebSocket 复用）18793（提供 HTTP 文件服务，为节点 WebView 提供界面能力）Canvas Host 是 Gateway 同时承担的另一项职责：
/__openclaw__/canvas/ 的 HTTP 文件服务A: 配置文件位置和格式：
~/.openclaw/openclaw.json（可通过环境变量 $OPENCLAW_CONFIG_PATH 自定义）如果文件不存在，系统会使用安全的默认值（包括默认工作区 ~/.openclaw/workspace）
A: 在 openclaw.json 中配置 gateway 对象：
{
"gateway": {
"port": 18789,
"bind": "lan",
"mode": "local"
}
}
绑定模式说明：
"local"：仅监听 127.0.0.1（默认，最安全）"lan"：监听所有网卡，允许局域网访问（需要配置认证）"tailnet"：监听 Tailscale 网络接口A: 通常不需要。Gateway 支持配置热重载：
{
"gateway": {
"reload": {
"mode": "hybrid"
}
}
}
A: 通过环境变量启动多实例：
# 实例 A
export OPENCLAW_CONFIG_PATH=~/.openclaw/a.json
export OPENCLAW_STATE_DIR=~/.openclaw-a
openclaw gateway --port 19001
# 实例 B
export OPENCLAW_CONFIG_PATH=~/.openclaw/b.json
export OPENCLAW_STATE_DIR=~/.openclaw-b
openclaw gateway --port 19002
关键环境变量：
OPENCLAW_CONFIG_PATH：指定配置文件路径OPENCLAW_STATE_DIR：指定状态目录（隔离会话、缓存等）A: Binding（绑定）是 OpenClaw 的路由规则，决定入站消息进入哪个 Agent 和 Session。
匹配优先级（从高到低）：
peer.kind + peer.id（特定用户/群组）guildId + rolesguildIdteamIdaccountIdaccountId: "*"）agents.list[].default，否则列表第一个，最后回退到 main配置示例：
{
"bindings": [
{
"channel": "whatsapp",
"accountId": "+1234567890",
"peer": {
"kind": "group",
"id": "[email protected]"
},
"agent": "support-bot"
}
]
}
A: 会话是 Agent 下的一条独立对话，由 sessionKey 标识：
agent:<agentId>:<mainKey>~/.openclaw/agents/<agentId>/sessions/会话隔离策略：
main 会话（同一发送者历史连续）requireMention: true，只有 @机器人时才响应A: 广播组允许为同一个对等方运行多个智能体（例如 WhatsApp 群组中同时运行 Alfred 和 Bärbel 两个 Agent）。
配置示例：
{
"broadcast": {
"strategy": "parallel",
"[email protected]": ["alfred", "baerbel"],
"+15555550123": ["support", "logger"]
}
}
使用场景：
A: 这是 2026 版本的安全强化：
如果你确实想开放 local loopback（不推荐生产环境）：
{
"gateway": {
"auth": null
}
}
或使用 Doctor 生成令牌：
openclaw doctor --generate-gateway-token
A: 生产环境推荐配置（允许局域网访问 + 密码认证）：
{
"gateway": {
"port": 18789,
"mode": "local",
"bind": "lan",
"controlUi": {
"allowInsecureAuth": true
},
"auth": {
"mode": "password",
"token": "29c4f73a9798b050122508fcdd72309db44fec0859857833",
"password": "YourSecurePassword"
}
}
}
认证模式对比：
| 模式 | 用途 | 配置项 |
|---|---|---|
token | 仅令牌认证 | gateway.auth.token |
password | 密码 + 令牌 | gateway.auth.password + gateway.auth.token |
注意：gateway.remote.token 仅用于远程 CLI 调用，不启用本地 Gateway 认证
A: 非本地回环绑定强制要求认证：
gateway.auth.mode（token 或 password）gateway.auth.token 或 gateway.auth.passwordOPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD错误示例（只配置了远程令牌，没配本地认证）：
{
"gateway": {
"bind": "lan",
"remote": {
"token": "xxx"
}
}
}
正确配置：
{
"gateway": {
"bind": "lan",
"auth": {
"mode": "token",
"token": "your-secure-token-here"
}
}
}
A: OpenClaw 支持两种运行模式：
| 特性 | 单智能体模式（默认） | 多智能体模式 |
|---|---|---|
| AgentId | 默认为 main | 多个自定义 ID（如 work, personal） |
| 工作区 | ~/.openclaw/workspace | ~/.openclaw/workspace-<agentId> |
| 状态目录 | ~/.openclaw/agents/main/agent | ~/.openclaw/agents/<agentId>/agent |
| 会话存储 | ~/.openclaw/agents/main/sessions | ~/.openclaw/agents/<agentId>/sessions |
| 认证配置 | 共享 | 每智能体独立（auth-profiles.json） |
| Skills | 共享 | 每智能体独立 + 可共享 |
多智能体的核心价值：
AGENTS.md / SOUL.mdA: 使用 Agent 向导：
# 添加名为 "work" 的智能体
openclaw agents add work
# 查看所有智能体及其绑定
openclaw agents list --bindings
手动配置（在 openclaw.json 中）：
{
"agents": {
"list": [
{ "id": "main", "default": true },
{ "id": "work", "agentDir": "~/.openclaw/agents/work/agent" },
{ "id": "personal", "agentDir": "~/.openclaw/agents/personal/agent" }
]
},
"bindings": [
{ "channel": "whatsapp", "accountId": "+123", "agent": "work" },
{ "channel": "telegram", "accountId": "+456", "agent": "personal" }
]
}
重要警告：切勿在智能体之间重用 agentDir，这会导致认证/会话冲突！
A: 不共享。每个智能体有独立的认证配置文件：
~/.openclaw/agents/<agentId>/agent/auth-profiles.json如果需要共享凭证：
cp ~/.openclaw/agents/main/agent/auth-profiles.json ~/.openclaw/agents/work/agent/auth-profiles.json
共享 Skills 则可以通过 ~/.openclaw/skills 目录实现，供所有 Agent 使用。
A: Gateway 可以启用 OpenAI Chat Completions 兼容端点（默认禁用）：
启用配置：
{
"gateway": {
"http": {
"endpoints": {
"chatCompletions": {
"enabled": true
}
}
}
}
}
调用方式：
POST http://<gateway-host>:<port>/v1/chat/completionsAuthorization: Bearer <token>model 字段中编码 openclaw:<agentId> 或 agent:<agentId>示例请求：
curl http://localhost:18789/v1/chat/completions \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{ "model": "openclaw:main", "messages": [{"role": "user", "content": "Hello"}] }'
高级控制：
x-openclaw-agent-id: <agentId> 指定 Agentx-openclaw-session-key: <sessionKey> 完全控制会话路由A: OpenResponses 是 OpenClaw 提供的另一兼容层，支持 POST /v1/responses 端点。
启用配置：
{
"gateway": {
"http": {
"endpoints": {
"responses": {
"enabled": true,
"maxBodyBytes": 20000000,
"files": { "maxBytes": 5242880 },
"images": { "maxBytes": 10485760 }
}
}
}
}
}
与 Chat Completions 的区别：
A: 不推荐仅使用环境变量，OpenClaw 的架构要求在配置文件中显式定义：
错误方式（不生效）：
export ANTHROPIC_BASE_URL=https://third-party-api.com
正确方式（在 openclaw.json 中）：
{
"models": {
"providers": [
{
"id": "xingjiabiapi",
"name": "Third Party API",
"baseUrl": "https://api.third-party.com/v1",
"apiKey": "your-api-key"
}
]
},
"agents": {
"defaults": {
"model": {
"primary": "xingjiabiapi/claude-3-5-sonnet"
}
}
}
}
关键要点：agents.defaults.model.primary必须包含自定义 Provider 的前缀（如 xingjiabiapi/），否则系统会默认使用官方 Anthropic 路由，导致 403 错误。
HTTP 403 Forbidden: Request not allowed 如何解决？A: 最常见原因：OpenClaw 将请求发送到了官方 Anthropic API，而非你配置的第三方地址。
排查步骤：
agents.defaults.model.primary 的值xingjiabiapi/claude-3-5-sonnetclaude-3-5-sonnet（会路由到官方 API）xingjiabiapi/claude-3-5-sonnet验证配置：
openclaw models status
查看日志确认路由：
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep "agent model:"
A: 排查步骤：
agent model: 行connect.params.auth.token 是否正确查看日志：
ls -la /tmp/openclaw/
tail -f /tmp/openclaw/openclaw-<日期>.log
检查 Gateway 状态：
openclaw gateway status
openclaw doctor
A: 常用诊断命令：
openclaw gateway status
openclaw doctor
openclaw models status
openclaw agents list --bindings
openclaw message send --target +15555550123 --message "Test"
openclaw devices list
openclaw devices approve <requestId>
日志位置：
/tmp/openclaw/openclaw-<日期>.logA: 排查清单：
~/.openclaw/agents/<agentId>/workspace/skills/~/.openclaw/skills/skills.json 或相关元数据文件确认 Gateway 已启动：
openclaw gateway status
openclaw gateway start
检查技能加载日志：
openclaw agent --local
常见误区：技能找不到往往是因为 Gateway 未启动 或 技能安装在错误的 Agent workspace 中。
| 配置项 | 说明 | 默认值 |
|---|---|---|
gateway.port | 监听端口 | 18789 |
gateway.bind | 绑定模式 | local |
gateway.auth.mode | 认证模式 | token |
gateway.reload.mode | 热重载模式 | hybrid |
| Canvas Host 端口 | WebView 服务 | 18793 |
| 路径 | 用途 |
|---|---|
~/.openclaw/openclaw.json | 主配置文件 |
~/.openclaw/workspace | 默认工作区 |
~/.openclaw/agents/<agentId>/agent | 智能体状态目录 |
~/.openclaw/agents/<agentId>/sessions | 会话存储 |
/tmp/openclaw/ | 日志文件 |
| 变量 | 用途 |
|---|---|
OPENCLAW_CONFIG_PATH | 自定义配置文件路径 |
OPENCLAW_STATE_DIR | 自定义状态目录 |
OPENCLAW_GATEWAY_TOKEN | Gateway 认证令牌 |
OPENCLAW_GATEWAY_PASSWORD | Gateway 认证密码 |
OPENCLAW_PROFILE | 配置文件后缀（如 work → openclaw-work.json） |
OpenClaw Gateway 是整个系统的控制中枢，理解它的核心概念对后续学习至关重要：
建议在学习过程中结合 openclaw doctor 和日志排查问题，遇到报错优先检查 模型路由配置 和 认证令牌设置。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online