openclaw目录结构与openclaw.json文件核心解析

一、OpenClaw 配置目录结构

OpenClaw 的所有配置、状态数据、⼯作区和技能均集中在用户主目录下的 ~/.openclaw/

markdown 复制代码

~/.openclaw/  
├── agents/                                  # 多智能体实例根目录  
│   └── main/                                # 默认主Agent实例  
│       └── agent/  
│           ├── plugins/  
│           │   └── zai/  
│           │       └── catalog.json         # ✅智谱插件清单：baseUrl、apiKey、全量模型/单价/上下文参数  
│           ├── auth-profiles.json           # 当前Agent私有模型密钥（优先级>全局models配置）  
│           ├── auth-state.json              # 密钥连通性运行缓存（自动生成）  
│           ├── models.json                  # Agent模型白名单：限定可用模型+默认调用模型  
│           └── sessions/                   # 全会话持久化目录  
│               ├── sessions.json            # 全会话索引台账：来源、计费、挂载技能、人设加载报告  
│               ├── skills-prompts/sha256/   # 技能提示词哈希缓存目录  
│               ├── *.jsonl                 # 原始一问一答聊天记录  
│               ├── *.trajectory.jsonl      # AI思考+工具调用全轨迹日志  
│               └── *.trajectory-path.json   # 会话步骤链路索引  
├── completions/                             # 各Shell终端Tab自动补全脚本  
│   ├── openclaw.bash  
│   ├── openclaw.zsh  
│   ├── openclaw.fish  
│   └── openclaw.ps1                         # Windows PowerShell专用补全  
├── credentials/                             # 渠道全局凭证（飞书白名单+配对缓存）  
│   ├── feishu-default-allowFrom.json        # 飞书用户/群聊白名单，名单外消息不响应  
│   └── feishu-pairing.json                  # 飞书AppID/Secret、长连接授权缓存  
├── cron/                                    # 系统定时任务调度目录  
│   ├── jobs.json                            # 定时任务静态配置：cron表达式、执行指令  
│   └── jobs-state.json                      # 任务运行状态缓存：上次/下次执行时间、运行结果  
├── devices/                                 # 多端设备配对鉴权  
│   ├── paired.json                          # 已授权绑定的设备清单  
│   └── pending.json                         # 待审核配对临时设备缓存  
├── feishu/                                  # 飞书附属缓存目录  
├── identity/                                # 网关本机唯一标识、签名证书配置  
├── logs/                                    # 全系统运行日志：网关、插件报错、模型调用日志  
├── npm/                                     # 插件NPM依赖本地缓存目录  
│   └── projects/openclaw-feishu-xxx/        # 飞书插件工程缓存  
│       ├── openclaw.plugin.json             # OpenClaw插件注册配置  
│       ├── package.json/package-lock.json   # npm依赖管理文件  
│       └── @openclaw/feishu/                # 插件源码+编译产物+技能代码  
├── plugins/                                 # 全局公共插件（所有Agent共用）  
├── plugin-skills/                           # 全局技能定义仓库（全部Agent默认加载）  
│   ├── browser-automation/  
│   │   └── SKILL.md                         # 浏览器自动化技能文档、函数入参  
│   ├── feishu-doc/  
│   │   ├── references/block-types.md        # 飞书文档格式参考  
│   │   └── SKILL.md  
│   ├── feishu-drive/  
│   ├── feishu-perm/  
│   └── feishu-wiki/  
├── tasks/                                   # 异步后台任务持久化数据库  
│   ├── runs.sqlite                          # 任务队列、运行记录、入参主库  
│   ├── runs.sqlite-shm  
│   └── runs.sqlite-wal  
├── tui/                                     # 终端控制台UI样式、交互配置  
├── workspace/                               # 全局人设&工作空间目录（全Agent共用系统提示词）  
│   ├── .openclaw/  
│   │   └── workspace-state.json             # 人设md文件哈希、字符统计、注入缓存  
│   ├── AGENTS.md                            # 多Agent调度、跨代理调用规则  
│   ├── IDENTITY.md                          # AI身份名称、对外人设名片  
│   ├── SOUL.md                              # 核心人格：语气、行为准则、应答规范  
│   ├── TOOLS.md                             # 本机环境、工具权限约束说明  
│   ├── USER.md                              # 用户画像、称呼、使用偏好  
│   └── HEARTBEAT.md                         # 全局心跳/定时自检规则  
├── gateway.cmd                              # Windows网关一键启动脚本  
├── openclaw.json                            # 项目顶层全局总配置（agents/gateway/session/tools/plugins/models/channels等10大配置块）  
└── update-check.json                        # OpenClaw版本更新检测缓存

二、openclaw.json 核心内容分析

1、"channels"{}

（目前配置飞书机器人）

规则：顶层 feishu 为全局默认配置；accounts 里单个 bot 字段会覆盖全局同参数 ；缺省字段自动继承顶层全局配置

! $\[Pasted image 20260604101208.png$ ]

一般包含以下参数：

enabled: true开启飞书整个消息通道，false 则所有飞书 bot 全部失效、收不到消息
connectionMode: websocket与webhook模式二选一;前者长连接，无需公网或内网穿透；后者需要公网域名配置回调地址内网直接运行
domain: "feishu"接口域名
dmPolicy：私聊权限策略 "pairing"/"allowlist"/"open"/"disabled"
"pairing"：陌生用户发消息需验证码配对
"allowlist"：仅白名单用户
"open"：全部放行
"disabled"：禁止私聊
groupPolicy：群聊权限策略 "allowlist"/"open"/"disabled"
"allowlist"：仅白名单群可用 bot，如果其他群聊拉机器人并@都不会回复
"open"：任意群加了机器人就能用
"disabled"：彻底关闭所有群聊回复
groupAllowFrom: $群ID$ 群白名单列表，填入飞书群 chat_id，只有列表内的群 @机器人才会应答，结合groupPolicy
requireMention: true群聊触发规则，true为必须 @机器人才回复；false 为群内随便发消息就自动回复
historyLimit：上下文携带历史消息条数，越大记忆越长、越耗 token，默认50
textChunkLimit：单次回复文字最大字符，超长自动拆分消息，数字 (默认 2000)
blockFrom：黑名单，优先级高于白名单，拉黑用户 / 群组

2、"agents"{}

优先级规则：list 单 Agent 配置 > defaults 全局配置 ，单 Agent 缺省参数自动继承 defaults

! $\[Pasted image 20260604101245.png$ ]

! $\[Pasted image 20260604081323.png$ ]

"defaults"{}：所有 Agent 不单独写配置姓名、功能时，自动用这里的默认值。
workspace：智能体工作目录，文件读写、项目生成、工具执行都在这里
models：列举有哪些可选择的大模型,alias为模型其别名
model：可使用大模型的顺序
skills：暂时未配置skill
list：智能体列表，main 智能体，全部继承 defaults 里的配置；agentss/main文件夹下面有一个json，配置自己模型的apikey
id: 智能体唯一 ID，飞书消息路由靠这个
name: 显示名称
temperature：全局模型随机性
agentDir：这个智能体的配置文件存放路径，包含人设、风格、工具，使用者的md文件
identity：基础人设，name职位，theme：任务拆解、进度跟踪，emoji：📋，（这些是写在 json 里的，并不在workspace里面的IDENTITY.md中）；可以先不配置在workspace的md文件配置，也可以在创建agents时给一个基础的信息（下文会单独来说）
subagents：允许这个智能体调用的子智能体

3、"bindings"\[\]

数组格式 ，每一项为一条路由规则，用来控制：哪个飞书账号 / 哪个群 / 哪个用户，消息交给哪个 bot (bot2/main/bot3) 处理。

! $\[Pasted image 20260604082857.png$ ]

type：绑定类型route/allowlist/blocklist，route为常规路由 (默认)，命中就把消息转发给 agentId；allowlist为白名单放行；blocklist：黑名单拦截消息，丢弃不处理
match.accoutnId：机器人账号 ID（bot1/bot2）；填"*"则当前渠道所有机器人账号全匹配

核心的三个部分channels、agents、bindings的配置就差不多了，一定要注意每个channels、agents的Id名，避免在bindings匹配混乱，练手的话建议一个agent只匹配一个bot，把agentId和每个account的bot的名字（也就是bindings的accountId）起一样的名字