—— 参考罐头的Openclaw笔记
看不懂？让小龙虾帮你快速落地：
本文及本站大部分openclaw相关文章，都可以让Openclaw agent阅读，然后进行应用，参考Prompt如下：
请阅读这篇文章：https://www.aiec.fun/%e6%89%93%e9%80%a0%e4%b8%93%e5%b1%9e%e5%b7%a5%e4%bd%9c%e5%a4%a7%e8%84%91%ef%bc%9a%e8%ae%a9openclaw%e4%bc%98%e5%85%88%e4%bd%bf%e7%94%a8%e4%bd%a0%e7%9a%84%e7%a7%81%e6%9c%89%e5%b7%a5%e4%bd%9c%e7%9f%a5/ 分析有哪些内容，对我们优化工作流程有价值。并严格根据openclaw最新官方文档核对，排除错误及过时信息，制定落地计划。
详细方法，参考文章 >>>
使用 OpenClaw 时，子 Agent 创建后群聊仍由主 Agent 回复、多群聊绑定串台、Agent 无响应、绑定配置不生效是最常见的问题，这些问题 90% 都源于对工作目录、配置文件结构和 Agent 绑定逻辑不理解。本文基于OpenClaw 2026.3.23-2最新版本，从目录结构、核心配置、绑定规则、问题排查全维度拆解，让你零基础也能吃透 OpenClaw 配置，彻底告别配置难题。
一、前置准备：版本与插件规范
1. 版本要求
本教程适配OpenClaw 2026.3.23-2版本，建议使用最新版，避免旧版本兼容问题导致配置失效。
2. 飞书插件必选（核心）
严禁使用 OpenClaw 自带飞书插件，功能缺失流式输出、多维表格、日历、文档操作等核心能力；必须安装飞书官方插件，安装命令：
npx -y @larksuite/openclaw-lark-tools install3. 官方文档参考
配置更新与最新功能以官方文档为准：https://docs.openclaw.ai/
二、定位 OpenClaw 工作目录
OpenClaw 所有配置、数据、日志均存放在固定工作目录，找不到目录 = 无法完成配置。
1. 默认路径
- Mac/Linux 系统：
~/.openclaw（隐藏目录，需先开启系统「显示隐藏文件」） - 快速查找：向主 Agent 发送指令
帮我列出openclaw的工作目录，直接获取精准路径
2. VSCode 可视化管理配置
推荐用 VSCode 编辑配置，支持本地 / 远程两种部署场景：
- 本地安装：直接打开 VSCode → 加载
~/.openclaw目录 - 远程安装（服务器 / 虚拟机）
- 点击 VSCode 左下角远程连接图标
- 选择「Connect to Host」，输入
用户名@服务器IP - 输入服务器密码完成连接
- 点击「Open Folder」，输入远程路径
~/.openclaw
三、.openclaw 目录结构深度拆解
打开目录后，所有文件夹 / 文件均有明确分工，以下是完整目录作用 + 细节说明，附速查表：
重点：子 Agent 独立工作空间核心文件
每个workspace-xxx（子 Agent 工作区）都包含以下核心文件，是 Agent 的「灵魂」：
关键区分：全局技能 vs 私有技能
- 全局技能（根目录 skills）：所有 Agent 共享，适合通用能力（如：整理早报）
- 私有技能（工作空间内 skills）：仅当前 Agent 可用，节省上下文 Token，实现「专人专事」
四、openclaw.json 核心配置逐段精讲
openclaw.json是 OpenClaw 的总控配置文件（支持 JSON5 格式，可加注释），所有绑定、模型、渠道配置均在此定义，也是问题高发区。
1. 基础配置模块
- meta：元信息（配置版本、修改时间），无需手动修改
- env：环境变量，集中管理 API Key、服务地址，支持动态添加
- wizard：运行向导记录，无需修改
- browser：浏览器自动化（Playwright）配置
- auth：模型认证，统一管理大模型提供商的 API 密钥
- acp：智能体通信协议，对接外部编码工具（Claude、OpenCode 等）
2. 模型配置（models）
- mode：
merge（融合模式），多模型兜底，一个失败自动切换下一个 - providers：模型提供商配置（baseUrl、apiKey、模型列表）
- 模型参数：上下文窗口、最大 Token、输入类型（文本 / 图片）、计费标准，自动生成无需手动调整
3. 智能体配置（agents）【核心】
分为全局默认模板（defaults）和子 Agent 列表（list）两部分：
- defaults：所有 Agent 继承的默认配置
- 优先模型、备选模型、默认工作目录
- 上下文压缩：
safeguard模式，Token 上限自动折叠历史，避免报错 - 心跳：每 10 分钟检查
heartbeat.md，执行定时指令 - 并发数：单 Agent 最大会话、子 Agent 最大并发
- list：子 Agent 自定义配置
- 必配项：
id（唯一标识）、workspace（独立工作区）、agentDir（配置目录） - 关键：workspace 必须独立，否则必串台
- 必配项：
4. 工具配置（tools）
全局工具权限，profile: full表示开启完整工具集，子 Agent 可单独覆盖。
5. 会话绑定（bindings）【绑定逻辑核心】
用于将Agent 与飞书机器人 / 群聊绑定，分两种规则：
- 飞书机器人绑定：
agentId+channel:feishu+accountId（机器人 ID） - 飞书群聊绑定：
agentId+channel:feishu+peer.kind:group+peer.id（群聊 ID）✅ 铁律：agentId必须与agents.list中的 ID完全一致
6. 消息与会话配置
- messages：
ackReactionScope: group-mentions，群聊 @Agent 时显示处理表情 - session：会话隔离，
dmScope: per-account-channel-peer，为每个用户生成独立上下文，彻底避免串台
7. 飞书渠道配置（channels.feishu）
支持多机器人同时运行：
- 主机器人：
appId+appSecret accounts：多机器人配置（accountId、机器人名称、私聊权限）requireMention: false：群聊无需 @即可回复streaming: true：开启流式输出
8. 网关与插件配置
- gateway：默认端口
18789，bind: lan支持局域网访问，配置访问令牌 - skills/plugins：技能安装、插件白名单（仅开启官方插件）
{
// 元信息
"meta": {
"lastTouchedVersion": "2026.3.23-2",
"lastTouchedAt": "2026-03-26T03:50:01.895Z"
},
// 环境变量信息
"env": {
"shellEnv": {
"enabled": true
},
"vars": {
"TAVILY_API_KEY": "xxxxxx",
"SEARXNG_URL": "http://192.168.5.19:4000",
"xx":"xx"
}
},
// 运行向导记录
"wizard": {
"lastRunAt": "2026-03-25T09:48:03.489Z",
"lastRunVersion": "2026.3.2",
"lastRunCommand": "doctor",
"lastRunMode": "local"
},
"browser": {
"attachOnly": false
},
// 认证信息
"auth": {
// 各个模型的配置信息
"profiles": {
"minimax:default": {
"provider": "minimax",
"mode": "api_key"
},
"minimax-cn:default": {
"provider": "minimax-cn",
"mode": "api_key"
},
"kimi-coding:default": {
"provider": "kimi-coding",
"mode": "api_key"
}
}
},
// ACP协议配置 可以控制连接不在openclaw范围内的Agent
"acp": {
"enabled": true,
"dispatch": {
"enabled": true
},
"backend": "acpx",
"defaultAgent": "claude",
"allowedAgents": [
"pi",
"claude",
"codex",
"opencode",
"gemini"
],
"maxConcurrentSessions": 8
},
// 模型配置信息
"models": {
"mode": "merge",
"providers": {
"minimax-cn": {
"baseUrl": "https://api.minimaxi.com/anthropic",
"apiKey": "xxxxx",
"api": "anthropic-messages",
"models": [
{
"id": "MiniMax-M2.5-highspeed",
"name": "MiniMax-M2.5-highspeed",
"api": "anthropic-messages",
"reasoning": true,
"input": [
"text",
"image"
],
"cost": {
"input": 0.3,
"output": 1.2,
"cacheRead": 0.03,
"cacheWrite": 0.12
},
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "MiniMax-M2.7",
"name": "MiniMax-M2.7",
"api": "anthropic-messages",
"reasoning": true,
"input": [
"text",
"image"
],
"cost": {
"input": 0.3,
"output": 1.2,
"cacheRead": 0.03,
"cacheWrite": 0.12
},
"contextWindow": 200000,
"maxTokens": 8192
}
]
},
"kimi-coding": {
"baseUrl": "https://api.kimi.com/coding/",
"api": "anthropic-messages",
"models": [
{
"id": "k2p5",
"name": "Kimi for Coding",
"reasoning": true,
"input": [
"text",
"image"
],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 262144,
"maxTokens": 32768
}
]
}
}
},
// Agent定义
"agents": {
// 全局默认配置模版 可以被继承
"defaults": {
"model": {
// 优先使用哪个模型
"primary": "kimi-coding/k2p5"
},
// 可用模型
"models": {
"minimax/MiniMax-M2.5": {
"alias": "Minimax"
},
"minimax-cn/MiniMax-M2.5": {
"alias": "Minimax"
},
"kimi-coding/k2p5": {
"alias": "Kimi for Coding"
}
},
// 工作目录
"workspace": "/home/guantou/.openclaw/workspace",
// 大模型的上下文窗口（Token）是有限的，聊得太长会爆满。`safeguard`（安全卫士）模式意味着当对话快达到 Token 上限时，OpenClaw 会自动对前面的聊天记录进行摘要、折叠或清理，保证新消息能正常发出去而不报错。
"compaction": {
"mode": "safeguard"
},
// 心跳时间间隔
"heartbeat": {
"every": "10m"
},
// 使用这个Agent最多并发多少会话
"maxConcurrent": 4,
// 调用子Agent的并发数量
"subagents": {
"maxConcurrent": 8
}
},
// 子Agent列表
"list": [
{
"id": "main",
"tools": {
"profile": "full", // 权限级别为全部
"alsoAllow": [
"feishu_bitable_app",
"feishu_bitable_app_table",
"feishu_bitable_app_table_field",
"feishu_bitable_app_table_record",
"feishu_bitable_app_table_view",
"feishu_calendar_calendar",
"feishu_calendar_event",
"feishu_calendar_event_attendee",
"feishu_calendar_freebusy",
"feishu_chat",
"feishu_chat_members",
"feishu_create_doc",
"feishu_doc_comments",
"feishu_doc_media",
"feishu_drive_file",
"feishu_fetch_doc",
"feishu_get_user",
"feishu_im_bot_image",
"feishu_im_user_fetch_resource",
"feishu_im_user_get_messages",
"feishu_im_user_get_thread_messages",
"feishu_im_user_message",
"feishu_im_user_search_messages",
"feishu_oauth",
"feishu_oauth_batch_auth",
"feishu_search_doc_wiki",
"feishu_search_user",
"feishu_sheet",
"feishu_task_comment",
"feishu_task_subtask",
"feishu_task_task",
"feishu_task_tasklist",
"feishu_update_doc",
"feishu_wiki_space",
"feishu_wiki_space_node"
],
"deny": [
"web_search",
"web_fetch"
]
}
},
{
"id": "video-cut",
"name": "video-cut",
"workspace": "/home/guantou/.openclaw/workspace-video-cut",
"agentDir": "/home/guantou/.openclaw/agents/video-cut/agent",
"tools": {
"alsoAllow": [
"group:runtime",
"feishu_bitable_app",
"feishu_bitable_app_table",
"feishu_bitable_app_table_field",
"feishu_bitable_app_table_record",
"feishu_bitable_app_table_view",
"feishu_calendar_calendar",
"feishu_calendar_event",
"feishu_calendar_event_attendee",
"feishu_calendar_freebusy",
"feishu_chat",
"feishu_chat_members",
"feishu_create_doc",
"feishu_doc_comments",
"feishu_doc_media",
"feishu_drive_file",
"feishu_fetch_doc",
"feishu_get_user",
"feishu_im_bot_image",
"feishu_im_user_fetch_resource",
"feishu_im_user_get_messages",
"feishu_im_user_get_thread_messages",
"feishu_im_user_message",
"feishu_im_user_search_messages",
"feishu_oauth",
"feishu_oauth_batch_auth",
"feishu_search_doc_wiki",
"feishu_search_user",
"feishu_sheet",
"feishu_task_comment",
"feishu_task_subtask",
"feishu_task_task",
"feishu_task_tasklist",
"feishu_update_doc",
"feishu_wiki_space",
"feishu_wiki_space_node"
],
"deny": [
"group:web",
"group:fs"
]
}
},
{
"id": "claude-code",
"name": "claude-code",
"workspace": "/home/guantou/.openclaw/workspace-claude-code",
"agentDir": "/home/guantou/.openclaw/agents/claude-code/agent",
"model": "kimi-coding/k2p5",
"tools": {
"alsoAllow": [*]
},
// ACP类型的Agent
"runtime": {
"type": "acp",
"acp": {
"agent": "claude",
"backend": "acpx",
"mode": "persistent"
}
}
},
{
"id": "recruiter",
"name": "recruiter",
"workspace": "/home/guantou/.openclaw/workspace-recruiter",
"agentDir": "/home/guantou/.openclaw/agents/recruiter/agent",
"tools": {
"alsoAllow": [
"feishu_bitable_app",
"feishu_bitable_app_table",
"feishu_bitable_app_table_field",
"feishu_bitable_app_table_record",
"feishu_bitable_app_table_view",
"feishu_calendar_calendar",
"feishu_calendar_event",
"feishu_calendar_event_attendee",
"feishu_calendar_freebusy",
"feishu_chat",
"feishu_chat_members",
"feishu_create_doc",
"feishu_doc_comments",
"feishu_doc_media",
"feishu_drive_file",
"feishu_fetch_doc",
"feishu_get_user",
"feishu_im_bot_image",
"feishu_im_user_fetch_resource",
"feishu_im_user_get_messages",
"feishu_im_user_get_thread_messages",
"feishu_im_user_message",
"feishu_im_user_search_messages",
"feishu_oauth",
"feishu_oauth_batch_auth",
"feishu_search_doc_wiki",
"feishu_search_user",
"feishu_sheet",
"feishu_task_comment",
"feishu_task_subtask",
"feishu_task_task",
"feishu_task_tasklist",
"feishu_update_doc",
"feishu_wiki_space",
"feishu_wiki_space_node"
]
}
},
{
"id": "copywriter",
"name": "copywriter",
"workspace": "/home/guantou/.openclaw/workspace-copywriter",
"agentDir": "/home/guantou/.openclaw/agents/copywriter/agent",
"tools": {
"alsoAllow": [
"feishu_bitable_app",
"feishu_bitable_app_table",
"feishu_bitable_app_table_field",
"feishu_bitable_app_table_record",
"feishu_bitable_app_table_view",
"feishu_calendar_calendar",
"feishu_calendar_event",
"feishu_calendar_event_attendee",
"feishu_calendar_freebusy",
"feishu_chat",
"feishu_chat_members",
"feishu_create_doc",
"feishu_doc_comments",
"feishu_doc_media",
"feishu_drive_file",
"feishu_fetch_doc",
"feishu_get_user",
"feishu_im_bot_image",
"feishu_im_user_fetch_resource",
"feishu_im_user_get_messages",
"feishu_im_user_get_thread_messages",
"feishu_im_user_message",
"feishu_im_user_search_messages",
"feishu_oauth",
"feishu_oauth_batch_auth",
"feishu_search_doc_wiki",
"feishu_search_user",
"feishu_sheet",
"feishu_task_comment",
"feishu_task_subtask",
"feishu_task_task",
"feishu_task_tasklist",
"feishu_update_doc",
"feishu_wiki_space",
"feishu_wiki_space_node"
]
}
},
{
"id": "product-manager",
"name": "product-manager",
"workspace": "/home/guantou/.openclaw/workspace-product-manager",
"agentDir": "/home/guantou/.openclaw/agents/product-manager/agent",
"tools": {
"alsoAllow": [
"feishu_bitable_app",
"feishu_bitable_app_table",
"feishu_bitable_app_table_field",
"feishu_bitable_app_table_record",
"feishu_bitable_app_table_view",
"feishu_calendar_calendar",
"feishu_calendar_event",
"feishu_calendar_event_attendee",
"feishu_calendar_freebusy",
"feishu_chat",
"feishu_chat_members",
"feishu_create_doc",
"feishu_doc_comments",
"feishu_doc_media",
"feishu_drive_file",
"feishu_fetch_doc",
"feishu_get_user",
"feishu_im_bot_image",
"feishu_im_user_fetch_resource",
"feishu_im_user_get_messages",
"feishu_im_user_get_thread_messages",
"feishu_im_user_message",
"feishu_im_user_search_messages",
"feishu_oauth",
"feishu_oauth_batch_auth",
"feishu_search_doc_wiki",
"feishu_search_user",
"feishu_sheet",
"feishu_task_comment",
"feishu_task_subtask",
"feishu_task_task",
"feishu_task_tasklist",
"feishu_update_doc",
"feishu_wiki_space",
"feishu_wiki_space_node"
]
}
},
// 还有很多子Agent 配置都差不多 先不列了
]
},
// 默认工具使用权限 这里设置的都是full
"tools": {
"profile": "full"
},
// ⭐️ 会话绑定！！
"bindings": [
// 飞书机器人绑定 AgentId对应上面的子AgentId
// channel选择飞书
// accountId对应下面的飞书机器人的accountId
{
"agentId": "copywriter",
"match": {
"channel": "feishu",
"accountId": "postwriter"
}
},
{
"agentId": "ops-monitor",
"match": {
"channel": "feishu",
"accountId": "devops"
}
},
// 飞书群聊绑定 AgentId对应上面的子AgentId
// peer.kind 为group 标识群聊渠道
// peer.id 标识你需要把Agent绑定到哪个群聊
{
"agentId": "recruiter",
"match": {
"channel": "feishu",
"peer": {
"kind": "group",
"id": "oc_d327c72f3bbd38ba6707afce5a73109b"
}
}
},
{
"agentId": "copywriter",
"match": {
"channel": "feishu",
"peer": {
"kind": "group",
"id": "oc_1e1977a0053a86eba1d7211f387f5be2"
}
}
},
{
"agentId": "product-manager",
"match": {
"channel": "feishu",
"peer": {
"kind": "group",
"id": "oc_866a40a31dd7005cecbb13e478cfe20d"
}
}
},
// 后面还有很多 不列了。。。
],
// 意思是你发了消息之后 是否使用一个小表情告诉你他正在处理 这里是默认值 群聊中艾特或者私聊的时候 你的消息上都会出现回复表情
"messages": {
"ackReactionScope": "group-mentions"
},
"commands": {
"native": "auto",
"nativeSkills": "auto",
"restart": true,
"ownerDisplay": "raw"
},
// 会话隔离机制
"session": {
// 为每一个 [机器人账号] + [接入渠道] + [对方用户] 生成一个独立的会话上下文
"dmScope": "per-account-channel-peer"
},
"hooks": {
"internal": {
"enabled": true,
"entries": {
"session-memory": {
"enabled": true
},
"command-logger": {
"enabled": true
},
"bootstrap-extra-files": {
"enabled": true
},
"boot-md": {
"enabled": true
}
}
}
},
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_a915a37896b8dbd7",
"appSecret": "xxxxx",
"domain": "feishu",
"requireMention": false,
"footer": {
"elapsed": true,
"status": true
},
"streaming": true,
"threadSession": true,
"groups": {
"*": {
"requireMention": false,
"groupPolicy": "open"
}
},
"accounts": {
// 多账户绑定 下面的每个键都对应上面binding里的Agent才行
"whetherbot": {
"appId": "cli_a93ff5a011381bcd",
"appSecret": "xxxxx",
"botName": "真天气助手",
"dmPolicy": "open",
"allowFrom": [
"*"
],
"enabled": true
},
"devops": {
"appId": "cli_a93ce0d904b8dbde",
"appSecret": "xxxxx",
"botName": "运维助手",
"dmPolicy": "open",
"allowFrom": [
"*"
],
"enabled": true
},
"postwriter": {
"appId": "cli_a93cd11ed679dbd9",
"appSecret": "xxxxx",
"botName": "真文案助手",
"dmPolicy": "open",
"allowFrom": [
"*"
],
"enabled": true
},
"default": {
"groupPolicy": "open",
"dmPolicy": "open",
"allowFrom": [
"*"
]
}
},
"groupPolicy": "open", // 群聊权限 任何机器人被拉入任何群都可以对话
"replyMode": {
"group": "streaming",
"direct": "streaming"
}
}
},
// 网关配置
"gateway": {
"port": 18789,
"mode": "local",
"bind": "lan", // 是否可以外部访问
"controlUi": {
"enabled": true,
// 外部访问必须要开的设置
"allowedOrigins": [
"*"
],
"dangerouslyAllowHostHeaderOriginFallback": true,
"allowInsecureAuth": true,
"dangerouslyDisableDeviceAuth": true
},
// 访问秘钥
"auth": {
"mode": "token",
"token": "xxxxxx"
},
"tailscale": {
"mode": "off",
"resetOnExit": false
},
"reload": {
"mode": "hot"
}
},
"skills": {
"install": {
"nodeManager": "npm"
},
// skill中如果有需要配置参数的 可以在这里配置
"entries": {
"minimax-search": {
"enabled": true,
"apiKey": "xxx"
},
"searxng": {
"enabled": true,
"env": {
"SEARXNG_URL": "http://192.168.5.19:4000"
}
}
}
},
"plugins": {
"allow": [
"acpx",
"openclaw-lark"
],
"load": {
"paths": [
"/home/guantou/.nvm/versions/node/v24.14.0/lib/node_modules/openclaw/dist/extensions/acpx"
]
},
"entries": {
"acpx": {
"enabled": true,
"config": {
"permissionMode": "approve-all",
"nonInteractivePermissions": "deny"
}
},
"openclaw-lark": {
"enabled": true
}
},
// 安装的插件都在这里
"installs": {
"acpx": {
"source": "path",
"spec": "acpx",
"sourcePath": "/home/guantou/.nvm/versions/node/v24.14.0/lib/node_modules/openclaw/dist/extensions/acpx",
"installPath": "/home/guantou/.nvm/versions/node/v24.14.0/lib/node_modules/openclaw/dist/extensions/acpx",
"installedAt": "2026-03-25T14:04:10.887Z"
},
"openclaw-lark": {
"source": "archive",
"sourcePath": "/tmp/openclaw-lark-dU1Gxd/larksuite-openclaw-lark-2026.3.25.tgz",
"installPath": "/home/guantou/.openclaw/extensions/openclaw-lark",
"version": "2026.3.25",
"installedAt": "2026-03-25T13:59:56.040Z"
}
}
}
}五、飞书机器人绑定自查：三要素对应法
绑定失败、串台、不响应，99% 是三要素不匹配，按以下步骤自查：
1. 绑定三要素（必须一一对应）
2. 标准绑定流程
- 创建子 Agent：配置独立
workspace和agentDir - 配置飞书多机器人：在
accounts中添加appId、appSecret、accountId - 配置绑定规则：在
bindings中关联 Agent、飞书渠道、机器人 / 群聊 - 必做操作：修改后重启网关，否则配置不生效
3. 常见问题根治表
六、OpenClaw 常用运维命令速查
配置修改、问题排查必备命令，建议收藏：
七、新手避坑终极指南
- .openclaw是隐藏目录，必须先开启系统显示隐藏文件
- 修改openclaw.json前先备份，用
backups文件快速恢复 - 飞书插件仅用官方版，禁用 OpenClaw 自带插件
- 所有子 Agent 必须分配独立 workspace，禁止共用主 Agent 目录
- 私有技能仅安装在对应 Agent 工作空间，节省上下文 Token
- 任何配置修改后，必须执行重启网关命令
- 敏感密钥（API Key、AppSecret）切勿泄露，统一存于credentials或环境变量
总结
OpenClaw 配置的核心逻辑，就是目录隔离、配置精准、绑定对应：
- 用独立workspace实现 Agent 数据隔离，解决串台
- 用bindings精准关联 Agent 与飞书渠道，解决绑定失效
- 用logs+ 运维命令快速排查问题，解决无响应
只要吃透本文内容，无需依赖他人，即可独立完成 OpenClaw 的全量配置与问题修复。
阅读量：
462