openclaw.json 配置文件解析

目录

整体结构

1. Models 配置
2. Gateway 配置
3. Channels 配置
4. Agents 配置
5. Tools 配置
6. Bindings 路由绑定
7. Messages 配置
8. Commands 配置
9. Hooks 配置
10. Skills 配置
11. Plugins 配置

Models 配置

"models":{"mode":"merge",# 合并模式：将此配置与现有配置合并，而非完全覆盖。可选值： merge（合并）、replace（替换）"providers":{# 模型提供商配置，定义一个或多个模型提供者（如 OpenAI、智谱、Anthropic 等）"zai":{"baseUrl":"https://open.bigmodel.cn/api/coding/paas/v4",# 智谱 API 的基础 URL，所有模型请求都发往此地址"api":"openai-completions",# API 协议类型：使用 OpenAI 兼容的 completions 接口格式，OpenClaw 会自动转换请求格式"models":[# 该提供者下可用的模型列表{"id":"glm-5-turbo",# 模型唯一标识，调用时使用（如 zai/glm-5）"name":"GLM-5-turbo",# 模型显示名称，用于 UI 展示和日志"reasoning":true,# 推理能力标记：true 表示该模型支持深度推理/思维链（CoT），OpenClaw 会启用相应功能"input":["text"# 支持的输入类型：text 表示纯文本输入，还可以是 ["text", "image"] 支持多模态],"cost":{# 模型费用配置，用于计算使用成本"input":0,# 输入 token 单价（元/千 token）"output":0,# 输出 token 单价（元/千 token）"cacheRead":0,# 缓存读取费用（如果支持 prompt caching）"cacheWrite":0# 缓存写入费用},"contextWindow":204800,# 上下文窗口大小（tokens）：模型能处理的最大输入 token 数（约 20 万 token）"maxTokens":131072# 最大输出 token 数：单次生成最多输出 13 万 token},]}}},

Auth 配置

"auth":{# 定义了不同 AI 模型提供者（如智谱、OpenAI、Anthropic 等）的认证方式，让 OpenClaw 能够调用这些 API。"profiles":{# 认证配置档案列表"zai:default":{# 档案名称：provider:profileId 格式"provider":"zai",# 提供者：智谱 AI"mode":"api_key"# 认证模式：api_key - 使用静态 API Key 认证；oauth - OAuth 授权流程；env - 从环境变量读取。}}},

Gateway 配置

"gateway":{"port":18987,# 监听端口：OpenClaw Gateway 服务监听的 TCP 端口号"mode":"local",# 运行模式：local 表示仅本地访问，还可选 public（公网暴露）"bind":"loopback",# 绑定地址：loopback 即 127.0.0.1，只监听本地回环地址，不接受外部连接"auth":{# 认证配置容器"mode":"token",# 认证模式：使用静态 token 认证"token":"XXX"# 认证令牌：客户端连接时必须携带此 token（48 位十六进制）},"tailscale":{# Tailscale VPN 配置（用于远程安全访问）"mode":"off",# 状态：已禁用 Tailscale 集成"resetOnExit":false# 退出时重置：服务停止时是否清理 Tailscale 状态},"nodes":{# 配对节点（手机/平板等设备）的控制权限"denyCommands":[# 禁止执行的命令列表"camera.snap",# 拍照"camera.clip",# 录制视频片段"screen.record",# 录屏"calendar.add",# 添加日历事件"contacts.add",# 添加联系人"reminders.add"# 添加提醒]}},

Channels 配置

"channels":{"feishu":{# 飞书渠道配置，用于连接飞书/Lark 即时通讯平台"enabled":true,# 启用状态：飞书渠道已激活，可以收发消息"groupPolicy":"open",# 群聊策略：open = 允许所有群聊消息，不限制来源"dmPolicy":"pairing",# 私聊策略：pairing = 仅允许已配对用户的私聊消息（需先绑定身份）"allowFrom":[# 白名单：* 表示允许所有来源（通配符），可配置具体用户 ID 限制"*"],"connectionMode":"websocket",# 连接模式：使用 WebSocket 长连接接收飞书事件推送"accounts":{"default":{"appId":"XXX",# 飞书应用的 App ID"appSecret":"XXX",# 飞书应用的 App Secret（用于 API 认证）"domain":"feishu"# 域名标识：feishu = 中国版飞书（非 Lark 国际版）},}}},

Agents 配置

"agents":{"defaults":{"model":{"primary":"zai/glm-5"# 默认主模型：所有智能体默认使用智谱 GLM-5},"models":{"zai/glm-4.7":{"alias":"GLM"},"zai/glm-5":{"alias":"GLM"}},"workspace":"XXX",# 默认工作目录：智能体操作文件的根目录"compaction":{# 上下文压缩（compaction）"mode":"safeguard"# 压缩模式：当上下文接近窗口上限时自动压缩历史消息。off - 禁用压缩；safeguard - 安全压缩（保留关键信息）；aggressive - 激进压缩（节省更多 token）},"heartbeat":{"every":"1h",# 心跳间隔：每小时检查一次"activeHours":{"start":"09:00",# 心跳活跃时段开始：早上 9 点起"end":"23:00"# 心跳活跃时段结束：晚上 11 点止},"target":"last"# 目标会话：心跳报告发送到最近活跃的会话},"maxConcurrent":4,# 主智能体最大并发数：最多同时运行 4 个主会话"subagents":{"maxConcurrent":8# 子智能体最大并发数：每个主智能体最多同时运行 8 个子任务},"sandbox":{# 沙箱配置（sandbox）"mode":"off",# 沙箱模式：当前已禁用（直接在宿主机执行命令）"workspaceAccess":"rw",# 工作区权限：读写权限"scope":"agent",# 沙箱作用域：agent - 每个智能体独立沙箱"docker":{"image":"openclaw-sandbox-browser:bookworm-slim",# Docker 镜像名称"workdir":"/workspace",# 容器内工作目录"readOnlyRoot":false,# 根文件系统可写"network":"bridge",# 网络模式（隔离网络）"capDrop":[],# 不丢弃任何 Linux Kernel 能力"pidsLimit":256,# 最大进程数限制"memory":"2g",# 内存限制 2GB"cpus":2,# CPU 核心限制"binds":[]# 无额外挂载卷}}},"list":[# 智能体列表（list）{"id":"main",# 智能体 ID：唯一标识符"subagents":{"allowAgents":[# 允许调用的子智能体：只能调用 claudecode。主智能体是用户直接交互的默认智能体，可以将编程任务委托给 claudecode"claudecode"]}},{"id":"claudecode","name":"claudecode","workspace":"XXX",# 独立工作目录（与主智能体分离）"agentDir":"XXX",# 智能体配置目录（存放 prompts、skills 等）"model":"zai/glm-5"}]},

Tools 配置

"tools":{# 控制智能体能调用哪些工具、能访问哪些范围"sessions":{"visibility":"all"# 控制当前智能体使用 sessions_list / sessions_history 工具时能看到哪些会话。# "all" - 可以看到系统中所有智能体的所有会话（包括其他用户/智能体的）# "own" - 只能看到当前智能体创建或参与的会话# "none" - 无法使用会话列表功能，禁用 sessions_list 等工具},"agentToAgent":{# Multi-Agent A2A 通信工具"enabled":true,# 启用 A2A"allow":[# 限定生效：仅 main 和 claudecode 可互通"main","claudecode"]}},

Bindings 路由绑定

"bindings":[# 定义消息路由规则：将来自不同渠道的消息绑定到对应的智能体。{"type":"route",# 绑定类型。route 路由绑定：将消息路由到智能体; pairing 配对绑定：将用户与智能体配对（私聊场景）"agentId":"main",# 目标智能体：消息路由到 main"match":{"channel":"feishu",# 匹配渠道：飞书渠道"accountId":"default"# 匹配账号：default 飞书应用}},{"type":"route","agentId":"claudecode","match":{"channel":"feishu","accountId":"claudecode"}}],

Messages 配置

"messages":{"ackReactionScope":"group-mentions"# 确认反应范围：仅在群聊中被提及时添加"已收到"表情反应# "all" - 所有消息都添加确认反应# "group-mentions" - 仅群聊中被 @提及时添加反应# "none" - 禁用确认反应},

Commands 配置

"commands":{# 斜杆命令配置"native":"auto",# 内置命令：自动检测并启用系统内置命令（如 /help、/status）"nativeSkills":"auto",# 内置技能命令：自动启用技能相关命令（如 /skill install）"restart":true,# 重启命令：允许用户通过命令重启 OpenClaw（/restart）"ownerDisplay":"raw"# 所有者显示模式：raw - 显示原始用户信息（不做脱敏处理）；masked - 脱敏显示（隐藏部分信息）},

Hooks 配置

"hooks":{"internal":{"enabled":true,# 启用内部钩子系统"entries":{# 具体钩子列表"boot-md":{# 智能体启动时读取启动文件（如 AGENTS.md、USER.md）"enabled":true},"command-logger":{# 执行命令时记录命令日志"enabled":true},"session-memory":{# 会话记忆管理"enabled":true}}}},

Skills 配置

"skills":{"install":{"nodeManager":"npm"# 包管理器：使用 npm 或 pnpm 安装技能包；}},

Plugins 配置

"plugins":{"entries":{# 插件列表"feishu":{# 飞书插件"enabled":true# 已启用}},"installs":{# 已安装列表"feishu":{"source":"npm",# 安装来源：npm 仓库"spec":"@m1heng-clawd/feishu",# npm 包名"installPath":"/Users/fanguiju/.openclaw/extensions/feishu",# 本地安装路径"version":"0.1.16",# 安装版本"resolvedName":"@m1heng-clawd/feishu",# 解析后的包名"resolvedVersion":"0.1.16",# 解析后的版本"resolvedSpec":"@m1heng-clawd/feishu@0.1.16",# 完整规格字符串"integrity":"sha512-BRbAdogf0NrjAX8HTPHcgMQ4zsx0SEFfWgoPcFYOTeq4muvGRkAXfPR14zS0ZtTGImcijatlZvgexWB7unj/pw==",# 完整性校验码（SHA512）"shasum":"47780b9ee0d1b9a8585612e6072fbd787402e03d",# SHA1 校验码"resolvedAt":"2026-03-11T16:15:44.443Z",# npm 解析时间"installedAt":"2026-03-11T16:15:52.629Z"# 本地安装时间}}}