Gateway 配置

Gateway 是 OpenClaw 的核心调度中枢。掌握它的配置，就等于掌握了整个 OpenClaw 的行为。

Gateway 是什么

Gateway 是一个常驻后台的守护进程（daemon），相当于 OpenClaw 的「心脏」。它负责：

消息路由：接收来自飞书、微信、Telegram 等通道的消息，分发给对应的 Agent
模型调度：连接 DeepSeek、Anthropic、OpenAI 等 AI 模型提供商
API 暴露：提供兼容 OpenAI 格式的 HTTP API（/v1/chat/completions 等）和 WebSocket 控制接口
状态管理：维护会话上下文、记忆索引、设备配对
配置热重载：监听 openclaw.json 变化，自动应用（hybrid 模式）

mermaid

flowchart LR
    subgraph 入口
        C[聊天通道<br/>飞书/微信/Telegram]
        D[Dashboard<br/>Control UI]
        N[Node 节点<br/>iOS/Android]
    end

    GW[Gateway<br/>127.0.0.1:18789]

    subgraph 后端
        AG[Agent 主循环]
        M[模型层<br/>DeepSeek/Anthropic/OpenAI]
        SK[Skills]
        MM[Memory]
    end

    C & D & N --> GW
    GW --> AG
    AG --> M & SK & MM

Gateway 默认绑定 127.0.0.1:18789，仅本地可访问。远程访问应通过 Tailscale VPN 或 SSH 隧道，不要直接暴露到公网。

配置文件结构

配置文件位于 ~/.openclaw/openclaw.json，使用 JSON5 格式（支持注释和尾逗号）。

配置格式：JSON5

与严格 JSON 不同，JSON5 允许行注释 //、块注释 /* */ 和尾逗号。这让你可以在配置文件中留下说明，方便后续维护。

顶层结构

配置键	说明
`agents`	Agent 定义：默认配置、模型、工具集
`channels`	通道配置：飞书、微信、Telegram 等
`gateway`	Gateway 自身配置：端口、绑定、认证、UI
`plugins`	插件配置：安装的插件参数
`messages`	消息行为：群聊触发规则、回复可见性
`tools`	工具配置：浏览器、执行、搜索等工具的参数

模型 Provider 配置

以最常用的 DeepSeek 为例：

json5

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      model: {
        primary: "deepseek/deepseek-v4-pro",
        fallbacks: ["deepseek/deepseek-chat"],
      },
      models: {
        "deepseek/deepseek-v4-pro": {
          alias: "DeepSeek V4 Pro",
          // 可选：如果 API 地址与默认不同
          // baseUrl: "https://api.deepseek.com/v1",
          // 可选：自定义请求头
          // headers: { "X-Custom-Header": "value" },
        },
        "deepseek/deepseek-chat": {
          alias: "DeepSeek Chat（备用）",
        },
      },
    },
  },
}

多模型 + 故障转移

json5

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: [
          "openai/gpt-5.4",
          "deepseek/deepseek-v4-pro",
        ],
      },
    },
  },
}

模型引用格式为 provider/model，常见组合：

引用	说明
`deepseek/deepseek-chat`	DeepSeek V3
`deepseek/deepseek-v4-pro`	DeepSeek V4 Pro
`anthropic/claude-sonnet-4-6`	Claude Sonnet
`openai/gpt-5.4`	GPT-5.4
`openai/gpt-5.3`	GPT-5.3
`google/gemini-2.7-pro`	Gemini 2.7 Pro

API Key 配置

每个 Provider 的 API Key 通过环境变量或 openclaw onboard 向导设置，不直接写在 openclaw.json 中：

bash

export DEEPSEEK_API_KEY="sk-xxxxxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxx"

工作区路径

工作区是 Agent 的「家」—— 所有项目文件、Skills、Memory 都在这里：

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

工作区内的标准目录结构：

~/.openclaw/workspace/
├── AGENTS.md          # Agent 操作规程
├── TOOLS.md           # 工具和环境配置
├── USER.md            # 用户偏好
├── MEMORY.md          # 长期记忆
├── memory/            # 记忆归档
└── projects/          # 项目文件

Agent 定义和配置

你可以定义多个 Agent，按发送者或群组路由：

json5

{
  agents: {
    defaults: {
      // 所有 Agent 的默认配置
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "deepseek/deepseek-v4-pro",
      },
      heartbeat: {
        every: "2h",     // 心跳间隔
        prompt: "ping",  // 心跳内容
      },
    },
    list: [
      // 特定 Agent 的覆盖配置（注意：实际配置键是 "list"，数组格式）
      { id: "coding-agent",
        model: { primary: "anthropic/claude-sonnet-4-6" },
        workspace: "~/.openclaw/workspace-coding",
      },
    ],
  },
}

Agent 路由

消息到达后，Gateway 按以下优先级决定由哪个 Agent 处理：

消息中显式指定的 Agent
发送者绑定的 Agent（配对时设置）
默认 Agent（agents.defaults）

启停命令

bash

# 前台运行（适合调试，日志输出到终端）
openclaw gateway --port 18789 --verbose

# 首次安装系统服务（注册到 systemd）
openclaw gateway install

# 后台运行（systemd 管理）
sudo systemctl start openclaw-gateway
sudo systemctl stop openclaw-gateway
sudo systemctl restart openclaw-gateway

# 查看状态
openclaw gateway status

# 实时日志
openclaw logs --follow

# 强制释放端口并启动
openclaw gateway run --force

重启注意

用 openclaw gateway restart 代替 stop + start 组合。直接 chain 命令可能导致 LaunchAgent/systemd 状态不同步。

配置热重载

Gateway 默认使用 hybrid 模式自动检测配置变化：

模式	行为
`off`	不监听配置变更
`hot`	仅应用热更新安全的变更
`restart`	检测到变更后自动重启
`hybrid`（默认）	安全的用热更新，需要重启的自动重启

修改 openclaw.json 后保存，Gateway 会自动加载。如果新配置有语法错误，Gateway 拒绝加载并保留当前运行的配置。

完整示例

以下是一个生产环境可用的 openclaw.json 完整示例：

json5

// ~/.openclaw/openclaw.json
// OpenClaw Gateway 完整配置示例
{
  // ========== Gateway 自身配置 ==========
  gateway: {
    port: 18789,              // 监听端口
    bind: "loopback",         // 仅本地访问
    auth: {
      mode: "token",          // 认证模式：token | password | trusted-proxy | none
      // token 通过环境变量 OPENCLAW_GATEWAY_TOKEN 设置
    },
    reload: {
      mode: "hybrid",         // 热重载模式
    },
    controlUi: {
      enabled: true,          // 启用 Web 控制面板
    },
  },

  // ========== Agent 配置 ==========
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "deepseek/deepseek-v4-pro",
        fallbacks: ["deepseek/deepseek-chat"],
      },
      models: {
        "deepseek/deepseek-v4-pro": {
          alias: "DeepSeek V4 Pro",
        },
        "deepseek/deepseek-chat": {
          alias: "DeepSeek Chat（备用）",
        },
      },
      heartbeat: {
        every: "2h",
      },
    },

    // 按需添加更专业的 Agent（使用 list 数组，不是 entries 对象）
    // list: [
    //   { id: "code-reviewer", model: { primary: "..." } },
    // ],
  },

  // ========== 工具配置（根级键，不在 agents 下） ==========
  tools: {
    exec: { enabled: true },
    browser: { enabled: true },
    web: {
      search: { enabled: true },
    },
  },

  // ========== 通道配置 ==========
  channels: {
    // Lark/飞书配置
    "openclaw-lark": {
      enabled: false,
      dmPolicy: "pairing",    // 私聊策略：pairing | allowlist | open | disabled
      groupPolicy: "open",    // 群聊策略：allowlist | open | disabled
    },

    // Telegram 配置（最快的接入方式）
    telegram: {
      enabled: false,
      botToken: "YOUR_BOT_TOKEN",
      dmPolicy: "pairing",
    },

    // 微信配置（需要 Node 节点）
    "openclaw-weixin": {
      enabled: false,
      dmPolicy: "pairing",
    },
  },

  // ========== 消息行为 ==========
  messages: {
    // 群聊回复策略
    groupChat: {
      mentionPatterns: ["@openclaw", "@小龙虾"],
    },
    // 回复可见性
    visibleReplies: "automatic",
  },

  // ========== 插件配置 ==========
  plugins: {
    entries: {
      // Lark/飞书插件（如需使用飞书通道）
      "openclaw-lark": {
        enabled: false,
        config: {
          appId: "YOUR_APP_ID",
          appSecret: "YOUR_APP_SECRET",
        },
      },
    },
  },
}

安全提醒

不要把 API Key 明文写在配置文件里，使用环境变量
公网部署时必须启用 Gateway 认证（gateway.auth.mode 不能为 none）
非回环地址绑定时（如 0.0.0.0），务必配置 gateway.auth.mode: "trusted-proxy" 并配合反向代理
Lark/飞书/微信等通道的密钥也建议通过环境变量注入

快速初始化

如果你是第一次使用 OpenClaw，推荐使用 openclaw onboard 向导完成初始配置：

bash

# 启动交互式配置向导
openclaw onboard

该向导会引导你一步步完成：

Gateway 模式选择：openclaw gateway install 注册 systemd 服务，或直接前台运行
模型 Provider 配置：填写 DeepSeek、Anthropic、OpenAI 等 API Key
通道接入：配置飞书、微信、Telegram 等聊天通道
工作区初始化：创建默认工作区目录结构和基础文件

完成向导后，你的 ~/.openclaw/openclaw.json 就已经包含了一个可工作的基础配置，可以直接启动 Gateway。

配置验证

修改配置后，先验证再启动：

bash

# 检查配置有效性
openclaw doctor

# 查看当前生效的配置
openclaw config get agents.defaults.workspace

# 通过 CLI 安全修改配置（推荐）
openclaw config set agents.defaults.model.primary "deepseek/deepseek-v4-pro"

# 删除配置项
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

下一步

Gateway 配好了，接下来了解工作区结构和项目组织。（文章待补充）

加载练习题中...

Gateway 配置 ​

Gateway 是什么 ​

配置文件结构 ​

顶层结构 ​

模型 Provider 配置 ​

多模型 + 故障转移 ​

工作区路径 ​

Agent 定义和配置 ​

启停命令 ​

配置热重载 ​

完整示例 ​

快速初始化 ​

配置验证 ​

下一步 ​

有问题或补充？欢迎留言

Gateway 配置

Gateway 是什么

配置文件结构

顶层结构

模型 Provider 配置

多模型 + 故障转移

工作区路径

Agent 定义和配置

启停命令

配置热重载

完整示例

快速初始化

配置验证

下一步