OpenClaw04_Gateway常见问题

文章目录

OpenClaw04_Gateway常见问题
- 一、基础概念篇
- - [Q1: OpenClaw Gateway 是什么？它的核心职责是什么？](#Q1: OpenClaw Gateway 是什么？它的核心职责是什么？)
  - [Q2: Gateway 与 Agent 的关系是什么？为什么不能把 Gateway 当作 OpenClaw 的核心？](#Q2: Gateway 与 Agent 的关系是什么？为什么不能把 Gateway 当作 OpenClaw 的核心？)
  - [Q3: Gateway 的默认端口是什么？Canvas Host 又是什么？](#Q3: Gateway 的默认端口是什么？Canvas Host 又是什么？)
- 二、配置管理篇
- - [Q4: OpenClaw 的配置文件在哪里？是什么格式？](#Q4: OpenClaw 的配置文件在哪里？是什么格式？)
  - [Q5: 如何修改 Gateway 的监听端口和绑定地址？](#Q5: 如何修改 Gateway 的监听端口和绑定地址？)
  - [Q6: 配置更改后需要重启 Gateway 吗？](#Q6: 配置更改后需要重启 Gateway 吗？)
  - [Q7: 如何启动多个 Gateway 实例进行隔离测试？](#Q7: 如何启动多个 Gateway 实例进行隔离测试？)
- 三、路由与会话篇
- - [Q8: 什么是 Binding？它是如何工作的？](#Q8: 什么是 Binding？它是如何工作的？)
  - [Q9: 会话（Session）是如何标识和管理的？](#Q9: 会话（Session）是如何标识和管理的？)
  - [Q10: 什么是广播组（Broadcast Group）？](#Q10: 什么是广播组（Broadcast Group）？)
- 四、认证与安全篇
- - [Q11: 为什么即使在 localhost 访问也需要 Token？](#Q11: 为什么即使在 localhost 访问也需要 Token？)
  - [Q12: 如何配置密码认证和局域网访问？](#Q12: 如何配置密码认证和局域网访问？)
  - [Q13: 非 localhost 绑定（lan/tailnet）后提示"未授权"怎么办？](#Q13: 非 localhost 绑定（lan/tailnet）后提示"未授权"怎么办？)
- 五、多智能体架构篇
- - [Q14: 什么是多智能体（Multi-Agent）架构？与单智能体有什么区别？](#Q14: 什么是多智能体（Multi-Agent）架构？与单智能体有什么区别？)
  - [Q15: 如何添加新的智能体？](#Q15: 如何添加新的智能体？)
  - [Q16: 智能体之间的认证配置是共享的吗？](#Q16: 智能体之间的认证配置是共享的吗？)
- [六、API 与集成篇](#六、API 与集成篇)
- - [Q17: Gateway 如何提供 OpenAI 兼容的 API？](#Q17: Gateway 如何提供 OpenAI 兼容的 API？)
  - [Q18: 什么是 OpenResponses API？如何启用？](#Q18: 什么是 OpenResponses API？如何启用？)
  - [Q19: 如何通过环境变量配置第三方模型（如 Claude、OpenAI）？](#Q19: 如何通过环境变量配置第三方模型（如 Claude、OpenAI）？)
- 七、故障排查篇
- - [Q20: 报错 `HTTP 403 Forbidden: Request not allowed` 如何解决？](#Q20: 报错 HTTP 403 Forbidden: Request not allowed 如何解决？)
  - [Q21: Dashboard Chat 界面无响应怎么办？](#Q21: Dashboard Chat 界面无响应怎么办？)
  - [Q22: 如何查看 Gateway 的实时日志和状态？](#Q22: 如何查看 Gateway 的实时日志和状态？)
  - [Q23: 如何排查"技能找不到"的问题？](#Q23: 如何排查"技能找不到"的问题？)
- 附录：快速参考表
- - [Gateway 配置速查](#Gateway 配置速查)
  - 重要路径速查
  - 关键环境变量
- 总结

一、基础概念篇

Q1: OpenClaw Gateway 是什么？它的核心职责是什么？

A: Gateway 是 OpenClaw 的控制面进程，是整个架构的核心枢纽。它承担以下关键职责：

消息接入：接收来自各种 Channel（Telegram、WhatsApp、Slack、WebChat 等）的入站消息
智能路由：根据 Binding 规则将消息路由到对应的 Agent 和 Session
会话管理：维护 Agent 和 Session 的状态，管理聊天历史
设备调度 ：通过 node.invoke 调用已连接的 Node（设备/能力端点）执行具体操作
认证授权：管理所有接入的认证与权限控制
驱动 Agent 运行：协调 LLM 调用、工具执行、技能加载等

一句话记忆：Gateway 是 OpenClaw 的"交通指挥中心"，所有消息、设备、智能体都由它统一调度。

Q2: Gateway 与 Agent 的关系是什么？为什么不能把 Gateway 当作 OpenClaw 的核心？

A: 这是一个常见误区。正确的理解是：

组件	角色定位	关系
Gateway	控制面/调度中心	负责"接消息、做路由、管会话"
Agent	执行大脑	负责"理解、推理、执行"，由 Gateway 驱动运行

Gateway 不直接处理业务逻辑：它只是将消息路由到合适的 Agent，然后"启动"该 Agent 运行一轮对话
Agent 是资源建模的"大脑"：每个 Agent 有独立的 workspace、配置、会话目录和人格设定
Agent 不常驻运行：被路由选中后才挂载运行，运行完即退出，不是持续运行的多进程服务

误区警示：认为 "Gateway 就是 OpenClaw 核心" 是错误的。Gateway 是基础设施，Agent 才是业务逻辑的执行者。

Q3: Gateway 的默认端口是什么？Canvas Host 又是什么？

A: Gateway 默认使用以下端口：

主端口 ：18789（HTTP + WebSocket 复用）
Canvas Host 端口 ：18793（提供 HTTP 文件服务，为节点 WebView 提供界面能力）

Canvas Host 是 Gateway 同时承担的另一项职责：

提供路径 /__openclaw__/canvas/ 的 HTTP 文件服务
为 WebChat、iOS 节点、Android 节点等提供 WebView 界面渲染能力
节点不直接暴露业务逻辑，而是通过 Gateway 统一调度

二、配置管理篇

Q4: OpenClaw 的配置文件在哪里？是什么格式？

A: 配置文件位置和格式：

路径：~/.openclaw/openclaw.json（可通过环境变量 $OPENCLAW_CONFIG_PATH 自定义）
格式：JSON5（支持注释、尾随逗号等宽松语法）
热重载：默认启用，修改后自动生效（无需重启）

如果文件不存在，系统会使用安全的默认值（包括默认工作区 ~/.openclaw/workspace）

Q5: 如何修改 Gateway 的监听端口和绑定地址？

A: 在 openclaw.json 中配置 gateway 对象：

json5 复制代码

{
  "gateway": {
    "port": 18789,           // 修改监听端口
    "bind": "lan",           // 绑定模式：local(仅本地) | lan(局域网) | tailnet(_tailscale_)
    "mode": "local"          // 运行模式
  }
}

绑定模式说明：

"local"：仅监听 127.0.0.1（默认，最安全）
"lan"：监听所有网卡，允许局域网访问（需要配置认证）
"tailnet"：监听 Tailscale 网络接口

Q6: 配置更改后需要重启 Gateway 吗？

A: 通常不需要。Gateway 支持配置热重载：

json5 复制代码

{
  "gateway": {
    "reload": {
      "mode": "hybrid"   // 默认：安全更改热应用，关键更改重启
      // 可选： "hot"(全部热重载) | "restart"(全部重启) | "off"(禁用热重载)
    }
  }
}

hybrid 模式：大多数配置（如路由规则、认证令牌）可热生效
需要重启的场景：端口更改、绑定模式切换等关键配置

Q7: 如何启动多个 Gateway 实例进行隔离测试？

A: 通过环境变量启动多实例：

bash 复制代码

# 实例 A
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

# 实例 B
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json \
OPENCLAW_STATE_DIR=~/.openclaw-b \
openclaw gateway --port 19002

关键环境变量：

OPENCLAW_CONFIG_PATH：指定配置文件路径
OPENCLAW_STATE_DIR：指定状态目录（隔离会话、缓存等）

三、路由与会话篇

Q8: 什么是 Binding？它是如何工作的？

A: Binding（绑定） 是 OpenClaw 的路由规则，决定入站消息进入哪个 Agent 和 Session。

匹配优先级（从高到低）：

精确对等匹配 ：peer.kind + peer.id（特定用户/群组）
父级对等匹配：线程继承（如 Telegram 话题）
公会 + 角色匹配 （Discord）：guildId + roles
公会匹配 （Discord）：guildId
团队匹配 （Slack）：teamId
账户匹配 ：通道上的 accountId
通道匹配 ：该通道任意账户（accountId: "*"）
默认智能体 ：agents.list[].default，否则列表第一个，最后回退到 main

配置示例：

json5 复制代码

{
  "bindings": [
    {
      "channel": "whatsapp",
      "accountId": "+1234567890",
      "peer": { "kind": "group", "id": "120363403215116621@g.us" },
      "agent": "support-bot"
    }
  ]
}

Q9: 会话（Session）是如何标识和管理的？

A: 会话是 Agent 下的一条独立对话，由 sessionKey 标识：

默认会话键格式 ：agent:<agentId>:<mainKey>
存储位置 ：~/.openclaw/agents/<agentId>/sessions/
包含内容：聊天历史、路由状态、上下文记忆

会话隔离策略：

私聊：默认折叠到共享的 main 会话（同一发送者历史连续）
群聊：默认隔离（每个群组独立会话）
基于提及的群激活 ：可配置 requireMention: true，只有 @机器人时才响应

Q10: 什么是广播组（Broadcast Group）？

A: 广播组允许为同一个对等方 运行多个智能体（例如 WhatsApp 群组中同时运行 Alfred 和 Bärbel 两个 Agent）。

配置示例：

json5 复制代码

{
  "broadcast": {
    "strategy": "parallel",  // 并行执行
    "120363403215116621@g.us": ["alfred", "baerbel"],  // 群组 ID → Agent 列表
    "+15555550123": ["support", "logger"]               // 个人号码 → Agent 列表
  }
}

使用场景：

一个 Agent 负责主要回复，另一个负责记录日志
多人格 Agent 同时响应，提供不同视角的回答

四、认证与安全篇

Q11: 为什么即使在 localhost 访问也需要 Token？

A: 这是 2026 版本的安全强化：

向导默认生成 Gateway 令牌（即使在 local loopback 上）
目的：阻止其他本地进程随意调用 Gateway，防止恶意软件滥用
解决方案：在 Control UI 设置或客户端配置中粘贴令牌以连接

如果你确实想开放 local loopback（不推荐生产环境）：

json5 复制代码

{
  "gateway": {
    // 移除 auth 配置，或设置为 null
    "auth": null
  }
}

或使用 Doctor 生成令牌：

bash 复制代码

openclaw doctor --generate-gateway-token

Q12: 如何配置密码认证和局域网访问？

A: 生产环境推荐配置（允许局域网访问 + 密码认证）：

json5 复制代码

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",                    // 允许局域网访问
    "controlUi": {
      "allowInsecureAuth": true       // 允许 HTTP 协议访问 Control UI（如需）
    },
    "auth": {
      "mode": "password",             // 启用密码认证
      "token": "29c4f73a9798b050122508fcdd72309db44fec0859857833",  // WS 连接令牌
      "password": "YourSecurePassword" // Control UI 登录密码
    }
  }
}

认证模式对比：

模式	用途	配置项
`token`	仅令牌认证	`gateway.auth.token`
`password`	密码 + 令牌	`gateway.auth.password` + `gateway.auth.token`

注意：gateway.remote.token 仅用于远程 CLI 调用，不启用本地 Gateway 认证

Q13: 非 localhost 绑定（lan/tailnet）后提示"未授权"怎么办？

A: 非本地回环绑定强制要求认证：

配置 gateway.auth.mode（token 或 password）
设置 gateway.auth.token 或 gateway.auth.password
也可通过环境变量设置：OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD

错误示例（只配置了远程令牌，没配本地认证）：

json5 复制代码

// 错误：这不会启用 Gateway 认证！
{
  "gateway": {
    "bind": "lan",
    "remote": { "token": "xxx" }  // 这只是远程 CLI 用的！
  }
}

正确配置：

json5 复制代码

{
  "gateway": {
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "your-secure-token-here"
    }
  }
}

五、多智能体架构篇

Q14: 什么是多智能体（Multi-Agent）架构？与单智能体有什么区别？

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	共享	每智能体独立 + 可共享

多智能体的核心价值：

多人共享 Gateway：每个人有自己的隔离"大脑"和数据
多身份管理：工作号、个人号完全隔离
不同人格设定 ：每个 Agent 有自己的 AGENTS.md / SOUL.md

Q15: 如何添加新的智能体？

A: 使用 Agent 向导：

bash 复制代码

# 添加名为 "work" 的智能体
openclaw agents add work

# 查看所有智能体及其绑定
openclaw agents list --bindings

手动配置 （在 openclaw.json 中）：

json5 复制代码

{
  "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，这会导致认证/会话冲突！

Q16: 智能体之间的认证配置是共享的吗？

A: 不共享。每个智能体有独立的认证配置文件：

路径：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
主智能体凭证不会自动共享给其他智能体

如果需要共享凭证：

bash 复制代码

# 手动复制认证配置到另一个智能体
cp ~/.openclaw/agents/main/agent/auth-profiles.json \
   ~/.openclaw/agents/work/agent/auth-profiles.json

共享 Skills 则可以通过 ~/.openclaw/skills 目录实现，供所有 Agent 使用。

六、API 与集成篇

Q17: Gateway 如何提供 OpenAI 兼容的 API？

A: Gateway 可以启用 OpenAI Chat Completions 兼容端点（默认禁用）：

启用配置：

json5 复制代码

{
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": true }
      }
    }
  }
}

调用方式：

端点：POST http://<gateway-host>:<port>/v1/chat/completions
认证：Authorization: Bearer <token>
选择 Agent ：在 model 字段中编码 openclaw:<agentId> 或 agent:<agentId>

示例请求：

bash 复制代码

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"}]
  }'

高级控制：

通过 Header x-openclaw-agent-id: <agentId> 指定 Agent
通过 Header x-openclaw-session-key: <sessionKey> 完全控制会话路由

Q18: 什么是 OpenResponses API？如何启用？

A: OpenResponses 是 OpenClaw 提供的另一兼容层，支持 POST /v1/responses 端点。

启用配置：

json5 复制代码

{
  "gateway": {
    "http": {
      "endpoints": {
        "responses": { 
          "enabled": true,
          "maxBodyBytes": 20000000,        // 20MB
          "files": { "maxBytes": 5242880 }, // 5MB
          "images": { "maxBytes": 10485760 } // 10MB
        }
      }
    }
  }
}

与 Chat Completions 的区别：

底层都作为普通 Gateway agent 运行执行
路由/权限/配置与 Gateway 完全一致
支持文件、图片上传等更丰富的功能

Q19: 如何通过环境变量配置第三方模型（如 Claude、OpenAI）？

A: 不推荐仅使用环境变量，OpenClaw 的架构要求在配置文件中显式定义：

错误方式（不生效）：

bash 复制代码

# 这不会生效！
export ANTHROPIC_BASE_URL=https://third-party-api.com

正确方式 （在 openclaw.json 中）：

json5 复制代码

{
  "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"  // 必须包含 provider 前缀！
      }
    }
  }
}

关键要点 ：agents.defaults.model.primary 必须包含自定义 Provider 的前缀（如 xingjiabiapi/），否则系统会默认使用官方 Anthropic 路由，导致 403 错误。

七、故障排查篇

Q20: 报错 `HTTP 403 Forbidden: Request not allowed` 如何解决？

A: 最常见原因：OpenClaw 将请求发送到了官方 Anthropic API，而非你配置的第三方地址。

排查步骤：

检查 agents.defaults.model.primary 的值
确认包含 Provider 前缀 ：如 xingjiabiapi/claude-3-5-sonnet
错误示例 ：只写 claude-3-5-sonnet（会路由到官方 API）
正确示例 ：xingjiabiapi/claude-3-5-sonnet

验证配置：

bash 复制代码

openclaw models status  # 查看模型是否挂载成功

查看日志确认路由：

bash 复制代码

# 日志路径（示例）
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep "agent model:"

Q21: Dashboard Chat 界面无响应怎么办？

A: 排查步骤：

检查 Gateway 状态：

bash 复制代码

openclaw gateway status
openclaw doctor  # 全面诊断

查看日志：

bash 复制代码

# 找到日志文件路径
ls -la /tmp/openclaw/
tail -f /tmp/openclaw/openclaw-<日期>.log

确认模型配置：
- 搜索日志中的 agent model: 行
- 确认当前加载的模型是否为你配置的第三方模型
验证认证：
- 检查 Control UI 设置中的 connect.params.auth.token 是否正确
- 避免将令牌放在 URL 中（不安全）

Q22: 如何查看 Gateway 的实时日志和状态？

A: 常用诊断命令：

bash 复制代码

# 查看 Gateway 状态
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-<日期>.log
可通过配置自定义日志路径

Q23: 如何排查"技能找不到"的问题？

A: 排查清单：

确认技能安装位置：
- 每智能体技能：~/.openclaw/agents/<agentId>/workspace/skills/
- 共享技能：~/.openclaw/skills/

检查技能加载日志：

bash 复制代码

openclaw agent --local  # 本地运行查看详细加载日志

验证技能配置：
- 技能需要在 Agent 的 workspace 中正确配置
- 检查 skills.json 或相关元数据文件

确认 Gateway 已启动：

bash 复制代码

openclaw gateway status
# 如果未运行，先启动 Gateway
openclaw gateway start

常见误区 ：技能找不到往往是因为 Gateway 未启动 或 技能安装在错误的 Agent workspace 中。

附录：快速参考表

Gateway 配置速查

配置项	说明	默认值
`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 是整个系统的控制中枢，理解它的核心概念对后续学习至关重要：

Gateway ≠ Agent：Gateway 是调度中心，Agent 是执行大脑
路由通过 Binding 实现：优先级从高到低匹配，最终落到具体 Agent 和 Session
多智能体实现隔离：每个 Agent 有独立的工作区、认证、会话，适合多人共享
安全默认强化：即使是 localhost 也需要认证，生产环境务必配置密码/令牌
配置热重载：大多数修改无需重启，但关键更改（如端口）仍需重启

建议在学习过程中结合 openclaw doctor 和日志排查问题，遇到报错优先检查 模型路由配置 和 认证令牌设置。

OpenClaw04_Gateway常见问题