OpenClaw Gateway 常见问题与配置实战

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

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

在 openclaw.json 中配置 gateway 对象即可：

{
  "gateway": {
    "port": 18789,
    "bind": "lan",
    "mode": "local"
  }
}

绑定模式说明：

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

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

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

{
  "gateway": {
    "reload": {
      "mode": "hybrid"
    }
  }
}

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

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

通过环境变量启动多实例是最常用的方法：

# 实例 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？它是如何工作的？

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

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

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

配置示例：

{
  "bindings": [
    {
      "channel": "whatsapp",
      "accountId": "+1234567890",
      "peer": {
        "kind": "group",
        "id": "[email protected]"
      },
      "agent": "support-bot"
    }
  ]
}

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

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

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

会话隔离策略：

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

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

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

配置示例：

{
  "broadcast": {
    "strategy": "parallel",
    "[email protected]": ["alfred", "baerbel"],
    "+15555550123": ["support", "logger"]
  }
}

使用场景：

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

四、认证与安全篇

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

这是 2026 版本的安全强化：

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

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

{
  "gateway": {
    "auth": null
  }
}

或使用 Doctor 生成令牌：

openclaw doctor --generate-gateway-token

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

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

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "allowInsecureAuth": true
    },
    "auth": {
      "mode": "password",
      "token": "29c4f73a9798b050122508fcdd72309db44fec0859857833",
      "password": "YourSecurePassword"
    }
  }
}

认证模式对比：

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

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

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

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

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

{
  "gateway": {
    "bind": "lan",
    "remote": {
      "token": "xxx"
    }
  }
}

正确配置：

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

五、多智能体架构篇

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

OpenClaw 支持两种运行模式：

多智能体的核心价值：

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

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

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

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

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

• 路径：~/.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 使用。

六、API 与集成篇

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

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

启用配置：

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

调用方式：

• 端点：POST http://<gateway-host>:<port>/v1/chat/completions
• 认证：Authorization: Bearer <token>
• 选择 Agent：在 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"}] }'

高级控制：

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

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

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

启用配置：

{
  "gateway": {
    "http": {
      "endpoints": {
        "responses": {
          "enabled": true,
          "maxBodyBytes": 20000000,
          "files": { "maxBytes": 5242880 },
          "images": { "maxBytes": 10485760 }
        }
      }
    }
  }
}

与 Chat Completions 的区别：

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

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

不推荐仅使用环境变量，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 错误。

七、故障排查篇

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

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

排查步骤：

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

验证配置：

openclaw models status

查看日志确认路由：

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep "agent model:"

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

排查步骤：

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

查看日志：

ls -la /tmp/openclaw/
tail -f /tmp/openclaw/openclaw-<日期>.log

检查 Gateway 状态：

openclaw gateway status
openclaw doctor

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

常用诊断命令：

# 查看 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: 如何排查'技能找不到'的问题？

排查清单：

1. 确认技能安装位置：
   • 每智能体技能：~/.openclaw/agents/<agentId>/workspace/skills/
   • 共享技能：~/.openclaw/skills/
2. 验证技能配置：技能需要在 Agent 的 workspace 中正确配置，检查 skills.json 或相关元数据文件。

确认 Gateway 已启动：

openclaw gateway status
openclaw gateway start

检查技能加载日志：

openclaw agent --local

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

附录：快速参考表

Gateway 配置速查

重要路径速查

关键环境变量

总结

OpenClaw Gateway 是整个系统的控制中枢，理解它的核心概念对后续学习至关重要：

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

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