OpenClaw 核心配置映射逻辑

本文专为 OpenClaw 整理，核心是把 openclaw.json 所有顶级字段与中文官网模块对应，用通俗的语言解释每个字段的作用、配置逻辑和关联关系，搭配简单示例，无需翻官网，一看就懂、一用就会。

导出OpenClaw 官方标准配置规范(openclaw.json)：

命令：openclaw config schema > openclaw-schema.json

openclaw-schema.json 是OpenClaw的JSON Schema 规范文件，定义了 openclaw.json 所有顶级字段以及子项的可配置项，包括：
 - 字段描述
 - 字段名、数据类型（string/number/boolean/object/array）
 - 必填 / 可选、枚举值（可填参数）、格式约束、嵌套结构规则

一、配置映射速查表

openclaw.json 顶级字段	对应官网模块	核心作用（一句话总结）	配置范围
gateway + hooks	网关与运维	系统入口，控制服务启动、访问方式	全局
auth	网关与运维 → 认证配置	系统安全门，管控访问权限	全局
models	模型（提供商）	Agent 大脑数据源，绑定 Ollama/OpenAI 等	全局
agents	Pi（代理 / 智能体）	业务大脑，创建主管、员工等 Agent	全局 + 单个
tools	工具	Agent 手脚，配置工具使用权限	全局 + 单个
channels	消息渠道	消息出入口，绑定飞书等平台	全局
session	网关与运维 → 会话管理	Agent 记忆开关，管理会话生命周期	全局
logging	网关与运维 → 日志配置	排障助手，记录系统运行状态	全局
env	参考 → 环境变量	安全管家，管理敏感信息	全局
platforms	平台	系统外观与全局设置，配置 UI 与功能开关	全局
cron	网关与运维 → 定时任务	自动管家，设置定时任务	全局
plugins	插件	功能扩展包，扩展系统能力	全局
meta	参考 → 配置元数据	系统身份卡，自动维护，禁止修改	系统自动维护

二、核心配置映射逻辑（按字段优先级排序）

所有配置围绕「系统运行 → 安全管控 → 智能体工作 → 功能扩展」展开，每个字段对应官网具体模块，可按这个逻辑记忆，配置时不迷路。

官网参考文档：OpenClaw - 中文官网

1. 网关与运维（gateway + hooks）→ 系统“入口”

对应官网模块：网关与运维
🔍 核心作用：相当于 OpenClaw 系统的“大门”，控制系统如何启动、如何被访问，是所有配置的基础，所有请求（Control UI、消息渠道、API）都需经过网关。
📌 关键关联：

• 管控端口（gateway.port）、访问地址（gateway.bind），决定谁能访问系统
• 热重载策略（gateway.reload），控制修改配置后是否需要重启系统
• WebHook 回调（hooks.webhooks），实现与外部系统的联动
• 关联 auth 字段，实现网关访问的身份认证

💡 通俗理解：网关就是“守门人”，负责开门（启动服务）、验身份（认证）、指路（路由请求），修改它的配置（如端口、认证），必须重启网关才能生效。

极简示例（核心参数）：

{
  "gateway": {
    "port": 18789,          // 网关端口，固定用这个即可
    "bind": "127.0.0.1",    // 仅本机访问，外网访问改为 0.0.0.0
    "reload": { "mode": "hybrid" } // 热重载模式，无需手动重启
  },
  "hooks": {
    "webhooks": [
      { "event": "chat.message", "url": "https://your-server.com/webhook" }
    ]
  }
}

2. 全局认证（auth）→ 系统“安全门”

对应官网模块：网关与运维 → 配置与运维 → 认证
🔍 核心作用：管控整个 OpenClaw 系统的访问权限，相当于“安全密码”，所有 Agent、Control UI、消息渠道都必须通过认证才能访问系统，是系统安全的核心。
📌 关键关联：

• 依赖网关（gateway）生效，认证失败会直接拒绝所有请求
• 支持 3 种认证方式：Bearer Token（首选）、API Key（多用户）、OAuth2（企业级）
• 仅全局配置，不能给单个 Agent 单独配置，修改后需重启网关

💡 通俗理解：auth 就是“大门的密码”，只有输入正确密码（Token/API Key），才能进入系统操作 Agent、配置工具，避免陌生人访问。

极简示例（首选 Bearer Token）：

{
  "auth": {
    "type": "bearer",
    "token": "abcdef1234567890abcdef1234567890" // 32位随机字符串，建议随机生成
  }
}

3. 模型（models）→ 智能体“大脑数据源”

对应官网模块：模型（提供商）
🔍 核心作用：给所有 Agent 提供“思考能力”，配置 AI 模型提供商（如本地 Ollama、云端 OpenAI），是 Agent 能回答问题、执行任务的基础。
📌 关键关联：

• 所有 Agent 共用一个 models 配置，无需给单个 Agent 重复配置模型源
• 核心配置模型地址（baseUrl）、认证密钥（apiKey）、模型列表（models）
• 关联 agents 字段，Agent 通过 model.primary 绑定具体模型

💡 通俗理解：models 就是“大脑仓库”，里面存放着 Ollama、OpenAI 等各种“大脑”，Agent 需要思考时，就从这个仓库里调用对应的“大脑”。

极简示例（本地 Ollama）：

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://127.0.0.1:11434", // Ollama 本地默认地址
        "apiKey": "ollama",                  // Ollama 默认密钥
        "models": [{"id": "qwen2:7b", "name": "通义千问7B"}] // 本地模型
      }
    }
  }
}

4. 智能体（agents）→ 系统“业务大脑”

对应官网模块：Pi（代理 / 智能体）
🔍 核心作用：OpenClaw 的核心业务载体，你创建的“主管”“员工”等智能体都在这里定义，负责执行具体任务（如回答问题、调用工具）。
📌 关键关联：

• 支持全局默认配置（agents.defaults），所有 Agent 都遵循这个基础规则
• 支持单个 Agent 单独配置（agents.list），可覆盖全局默认配置（如绑定不同模型、配置专属工具）
• 关联 models 字段（绑定模型）、tools 字段（配置工具权限）、session 字段（管理会话）

💡 通俗理解：agents 就是“员工团队”，有主管、有普通员工，每个员工（Agent）有自己的职责（模型）和权限（工具），全局配置就是“公司通用规则”，单个配置就是“员工专属权限”。

极简示例（主管 + 普通员工 Agent）：

{
  "agents": {
    "defaults": {
      "model": {"primary": "ollama/qwen2:7b"} // 所有 Agent 默认模型
    },
    "list": [
      {
        "id": "zhuguan",
        "name": "主管机器人",
        "model": {"primary": "ollama/llama3:8b"}, // 覆盖默认模型
        "tools": {"profile": "full"} // 专属工具权限（全部工具可用）
      },
      {
        "id": "yuangong",
        "name": "员工机器人" // 遵循全局默认配置
      }
    ]
  }
}

5. 工具（tools）→ 智能体“手脚”

对应官网模块：工具
🔍 核心作用：给 Agent 提供“执行能力”，比如命令执行、文件读写、网页搜索等，相当于 Agent 的“手脚”，没有工具，Agent 只能回答问题，无法执行实际操作。
📌 关键关联：

• 支持全局配置（tools）：定义所有 Agent 的默认工具权限（基础规则）
• 支持单个 Agent 覆盖配置（agents.list[].tools）：给特殊 Agent 配置专属工具权限
• 优先级：单个 Agent 工具配置 > 全局工具配置
• 工具名称必须与官网一致（如 exec、file_read），不能自定义

💡 通俗理解：tools 就是“工具包”，全局配置是“公司通用工具包”（所有人都能用到的基础工具），单个 Agent 配置是“个人专属工具包”（主管能用到更多工具，普通员工只能用基础工具）。

极简示例（全局 + 单个 Agent 工具配置）：

// 全局工具配置（所有 Agent 默认遵循）
"tools": {
  "profile": "basic", // 基础工具集
  "deny": ["exec"]    // 全局禁止命令执行工具
},
// 单个 Agent 覆盖配置（主管 Agent）
"agents": {
  "list": [
    {
      "id": "zhuguan",
      "name": "主管机器人",
      "tools": {
        "profile": "full", // 覆盖全局，启用全部工具
        "allow": ["exec"]  // 允许命令执行（覆盖全局禁止）
      }
    }
  ]
}

6. 消息渠道（channels）→ 智能体“消息出入口”

对应官网模块：消息渠道
🔍 核心作用：让 Agent 能接收和发送消息，比如通过飞书、Discord、Telegram 等平台与用户互动，相当于 Agent 的“嘴巴和耳朵”。
📌 关键关联：

• 仅全局配置，所有 Agent 共用一个渠道配置，无需单独给 Agent 配置
• 核心配置平台 AppID/Secret、连接模式、消息权限等
• 依赖 auth 字段，渠道访问需通过系统认证

💡 通俗理解：channels 就是“通讯软件”，Agent 通过它（飞书、Telegram 等）接收用户的消息，再把回答发送给用户，没有渠道，用户无法和 Agent 互动。

极简示例（飞书机器人）：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "${FEISHU_APP_ID}", // 飞书 AppID（环境变量引用，更安全）
      "appSecret": "${FEISHU_APP_SECRET}",
      "dmPolicy": "allowlist", // 仅允许白名单用户访问
      "allowFrom": ["feishu:12345678"]
    }
  }
}

7. 会话（session）→ 智能体“记忆开关”

对应官网模块：代理 → 会话工具
🔍 核心作用：管理所有 Agent 的会话生命周期，比如会话隔离、空闲超时、每日重置，避免不同用户、不同 Agent 的会话混乱，相当于 Agent 的“记忆管理”。
📌 关键关联：

• 仅全局配置，管控所有 Agent 的会话规则
• 核心配置会话隔离（isolation）、超时时间（idle_timeout）、重置策略（reset_strategy）
• 关联 agents 字段，Agent 的会话都受此配置管控

💡 通俗理解：session 就是“记忆本”，每个用户和 Agent 的对话都会记在“记忆本”上，超时后“记忆本”会清空，避免 Agent 记混不同用户的对话内容。

极简示例：

{
  "session": {
    "isolation": true,        // 不同 Agent 会话互不干扰
    "idle_timeout": 3600,     // 会话空闲1小时后清空
    "reset_strategy": "daily" // 每天自动重置所有会话
  }
}

8. 日志（logging）→ 系统“排障助手”

对应官网模块：网关与运维 → 日志概览
🔍 核心作用：记录系统运行状态、错误信息、Agent 操作记录，当系统出现故障（如 Agent 无法调用工具、网关启动失败）时，通过日志能快速找到问题原因。
📌 关键关联：

• 仅全局配置，管控所有系统日志的输出规则
• 核心配置日志级别（level）、存储路径（path）、输出格式（format）
• 建议日志级别设为 info，既不冗余，又能记录关键信息

💡 通俗理解：logging 就是“日记本”，系统每天的运行情况、出现的问题，都会记在里面，出问题时翻“日记本”，就能知道哪里错了。

极简示例：

{
  "logging": {
    "level": "info",   // 日志级别：info（正常）/ debug（调试）/ error（错误）
    "path": "~/.openclaw/logs", // 日志存储路径（默认路径，无需修改）
    "format": "json"    // 日志输出格式，默认即可
  }
}

9. 环境变量（env）→ 敏感信息“安全管家”

对应官网模块：网关与运维 →配置与运维 → 配置 → 环境变量
🔍 核心作用：安全管理敏感信息（如 API Key、Token、AppSecret），避免把敏感信息直接写死在 openclaw.json 里，降低泄露风险。
📌 关键关联：

• 仅全局配置，管控系统环境变量的加载规则
• 核心配置是否启用加载（load）、环境变量前缀（prefix）
• 关联 models、channels 等字段，可通过 ${变量名} 引用环境变量

💡 通俗理解：env 就是“密码箱”，把 API Key、Token 等敏感信息放在“密码箱”里，openclaw.json 只留“密码箱”的引用，别人看不到具体密码，更安全。

极简示例：

{
  "env": {
    "load": true,          // 启用环境变量加载
    "prefix": "OPENCLAW_"  // 环境变量前缀，如 OPENCLAW_API_KEY
  }
}

10. 平台（platforms）→ 系统“外观与全局特性”

对应官网模块：平台
🔍 核心作用：配置 Control UI、WebChat 的外观样式（如标题、主题）、全局功能开关，相当于系统的“外观与全局设置”，不影响核心功能运行。
📌 关键关联：

• 仅全局配置，所有 Agent 共用一个平台配置
• 核心配置 WebChat 标题、主题、控制面板开关、前端资源路径等

💡 通俗理解：platforms 就是“系统的外观与全局设置”，比如修改 WebChat 的标题、切换浅色/深色主题、开启/关闭控制面板，不影响 Agent 工作，只影响用户看到的界面。

极简示例：

{
  "platforms": {
    "webchat": {
      "title": "我的 OpenClaw 机器人", // WebChat 标题
      "theme": "light"                // 浅色主题（dark 为深色）
    },
    "dashboard": { "enabled": true }  // 启用 Control UI 控制面板
  }
}

11. 定时任务（cron）→ 系统“自动管家”

对应官网模块：工具 → 自动化与任务 → 计划任务
🔍 核心作用：设置系统自动执行的任务，比如每日备份、自动巡检、定时发送日报，相当于系统的“自动管家”，减少手动操作。
📌 关键关联：

• 仅全局配置，管控所有定时任务的执行规则
• 核心配置任务名称（name）、执行时间（schedule，Cron 表达式）、执行任务（task）

💡 通俗理解：cron 就是“闹钟”，设置好时间（如每天凌晨0点）和任务（如备份配置），到点系统会自动执行，不用手动操作。

极简示例（每日备份）：

{
  "cron": {
    "jobs": [
      {
        "name": "backup",
        "schedule": "0 0 * * *", // Cron 表达式：每天凌晨0点执行
        "task": "backup --all"   // 执行备份任务
      }
    ]
  }
}

12. 插件（plugins）→ 系统“功能扩展包”

对应官网模块：工具 → 扩展
🔍 核心作用：扩展系统功能，比如新增自定义工具、集成第三方服务，相当于给系统“装插件”，初期可不用配置，后期按需扩展。
📌 关键关联：

• 仅全局配置，管控插件的加载、启用/禁用
• 核心配置插件 ID（id）、插件路径（path）、启用状态（enabled）

💡 通俗理解：plugins 就是“系统的扩展功能”，比如给系统装一个“PDF 解析插件”，Agent 就能实现 PDF 解析功能，不装插件也不影响基础使用。

极简示例：

{
  "plugins": {
    "entries": [
      {
        "id": "pdf-parser",
        "path": "./plugins/pdf-parser", // 插件路径
        "enabled": true                // 启用插件
      }
    ]
  }
}

13. 元数据（meta）→ 系统“身份卡”

对应官网模块：无
🔍 核心作用：系统自动维护的元数据，记录系统版本、配置更新时间等信息，禁止手动修改，修改会导致系统异常。

💡 通俗理解：meta 就是“系统的身份证”，记录系统的版本、更新时间，不用管它，系统会自动维护。

系统默认示例（无需修改）：

{
  "meta": {
    "version": "1.2.3",
    "updatedAt": "2026-04-10T10:00:00Z"
  }
}

三、配置优先级与生效规则

整理最关键的 3 条规则，避免配置错误，直接记牢：

1. 配置优先级：单个 Agent 配置（如 agents.list[].tools）> 全局配置（如 tools），特殊需求优先给单个 Agent 单独配置。
2. 生效规则：修改 auth、gateway、logging、session、cron、plugins 字段后，需重启网关（openclaw gateway restart）才能生效；修改 tools、agents、channels、platforms 字段可热重载，无需重启。
3. 安全规则：敏感信息（API Key、Token）优先用 env 字段引用环境变量，不要直接写死在 openclaw.json；禁止手动新增未知顶级字段，会导致网关启动失败。

四、结尾总结

本文完整梳理了 OpenClaw 所有顶级字段的核心配置映射逻辑，从“系统入口”（gateway）到“业务大脑”（agents），再到“功能扩展”（plugins），每个字段都对应官网具体模块，搭配能看懂的通俗解释和可直接复制的示例。

配置时，可按「网关 → 认证 → 模型 → Agent → 工具 → 渠道 → 平台」的顺序配置，优先完成核心字段（gateway、auth、models、agents、tools），再根据需求配置其他字段。