目录
文章目录
- 目录
- 整体结构
- [Models 配置](#Models 配置)
- [Auth 配置](#Auth 配置)
- [Gateway 配置](#Gateway 配置)
- [Channels 配置](#Channels 配置)
- [Agents 配置](#Agents 配置)
- [Tools 配置](#Tools 配置)
- [Bindings 路由绑定](#Bindings 路由绑定)
- [Messages 配置](#Messages 配置)
- [Commands 配置](#Commands 配置)
- [Hooks 配置](#Hooks 配置)
- [Skills 配置](#Skills 配置)
- [Plugins 配置](#Plugins 配置)
- 配置验证与调试
整体结构
- Models 配置
- Gateway 配置
- Channels 配置
- Agents 配置
- Tools 配置
- Bindings 路由绑定
- Messages 配置
- Commands 配置
- Hooks 配置
- Skills 配置
- Plugins 配置
Models 配置
bash
复制代码
"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 配置
bash
复制代码
"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 配置
bash
复制代码
"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 位十六进制）
},
"reload": { "mode": "hybrid" } # hybrid - （默认）安全变更热应用，关键变更自动重启；hot - 仅热应用安全变更，需重启时记录警告；restart - 任何变更都重启；off - 禁用热重载，手动重启生效。
"tailscale": { # Tailscale VPN 配置（用于远程安全访问）
"mode": "off", # 状态：已禁用 Tailscale 集成
"resetOnExit": false # 退出时重置：服务停止时是否清理 Tailscale 状态
},
"nodes": { # 配对节点（手机/平板等设备）的控制权限
"denyCommands": [ # 禁止执行的命令列表
"camera.snap", # 拍照
"camera.clip", # 录制视频片段
"screen.record",# 录屏
"calendar.add", # 添加日历事件
"contacts.add", # 添加联系人
"reminders.add" # 添加提醒
]
}
},
Channels 配置
bash
复制代码
"channels": {
"feishu": { # 飞书渠道配置，用于连接飞书/Lark 即时通讯平台
"enabled": true, # 启用状态：飞书渠道已激活，可以收发消息
"groupPolicy": "open", # 群聊策略：open = 允许所有群聊消息，不限制来源；disabled - 阻止所有群聊消息；allowlist - （默认）仅允许配置中的群组。
"dmPolicy": "pairing", # 私聊策略：pairing = 仅允许已配对用户的私聊消息（需先绑定身份）；allowlist - 仅允许 allowFrom 列表中的用户；open - 允许所有 DM（需设置 allowFrom: ["*"]）； disabled - 忽略所有 DM。
"allowFrom": [ # 白名单：* 表示允许所有来源（通配符），可配置具体用户 ID 限制
"*"
],
"connectionMode": "websocket", # 连接模式：使用 WebSocket 长连接接收飞书事件推送
"accounts": {
"default": {
"appId": "XXX", # 飞书应用的 App ID
"appSecret": "XXX", # 飞书应用的 App Secret（用于 API 认证）
"domain": "feishu" # 域名标识：feishu = 中国版飞书（非 Lark 国际版）
},
}
}
},
Agents 配置
bash
复制代码
"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"
}
]
},
bash
复制代码
"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 路由绑定
bash
复制代码
"bindings": [ # 定义消息路由规则：将来自不同渠道的消息绑定到对应的智能体。
{
"type": "route", # 绑定类型。route 路由绑定：将消息路由到智能体; pairing 配对绑定：将用户与智能体配对（私聊场景）
"agentId": "main", # 目标智能体：消息路由到 main
"match": {
"channel": "feishu", # 匹配渠道：飞书渠道
"accountId": "default" # 匹配账号：default 飞书应用
}
},
{
"type": "route",
"agentId": "claudecode",
"match": {
"channel": "feishu",
"accountId": "claudecode"
}
}
],
Messages 配置
bash
复制代码
"messages": {
"ackReactionScope": "group-mentions" # 确认反应范围：仅在群聊中被提及时添加"已收到"表情反应
# "all" - 所有消息都添加确认反应
# "group-mentions" - 仅群聊中被 @提及时添加反应
# "none" - 禁用确认反应
},
Commands 配置
bash
复制代码
"commands": { # 斜杆命令配置
"native": "auto", # 内置命令：自动检测并启用系统内置命令（如 /help、/status）
"nativeSkills": "auto", # 内置技能命令：自动启用技能相关命令（如 /skill install）
"restart": true, # 重启命令：允许用户通过命令重启 OpenClaw（/restart）
"ownerDisplay": "raw" # 所有者显示模式：raw - 显示原始用户信息（不做脱敏处理）；masked - 脱敏显示（隐藏部分信息）
},
Hooks 配置
bash
复制代码
"hooks": {
"internal": {
"enabled": true, # 启用内部钩子系统
"entries": { # 具体钩子列表
"boot-md": { # 智能体启动时读取启动文件（如 AGENTS.md、USER.md）
"enabled": true
},
"command-logger": { # 执行命令时记录命令日志
"enabled": true
},
"session-memory": { # 会话记忆管理
"enabled": true
}
}
}
},
Skills 配置
bash
复制代码
"skills": {
"install": {
"nodeManager": "npm" # 包管理器：使用 npm 或 pnpm 安装技能包；
}
},
Plugins 配置
bash
复制代码
"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" # 本地安装时间
}
}
}
配置验证与调试
bash
复制代码
# 检查配置有效性
openclaw doctor
# 自动修复配置问题
openclaw doctor --fix