搭配视频教程观看体验更佳！

为什么出这期？因为很多朋友之前配机器人的时候总出现. 创建 HR Agent 后，群聊里还是主 Agent 在回复.多个群聊绑定后，Agent "串台"（身份混乱）问题.问"你是谁"时，Agent 仍然回答自己是主 Agent

或者就是Agent说绑定成功了，但是却没绑定上。这次直接带大家开盒openclaw，看看蟹壳下面是什么构造，看看它的工作目录是怎样的，配置文件应该怎么配。靠人不如靠自己，了解原理，才能更稳妥的折腾。

版本自查

折腾之前先自查一下版本，我做这个教程的时候使用的版本是openclaw的v2026.3.23-2。

如果你有使用飞书作为消息渠道，那么飞书插件是飞书官方提供的openclaw-lark插件，安装方式可以使用命令安装:

npx -y @larksuite/openclaw-lark-tools install

确保你的飞书插件是上面的插件，因为openclaw自带的飞书插件支持的功能不如飞书官方的多,比如流式输出，多维表格等。

官方文档

推荐大家可以多看看官方文档，了解最新资讯 https://docs.openclaw.ai/

找到配置目录位置

在mac或者Linux上，一般是在这个目~/.openclaw,如果没有就直接问你的主Agent要路径"帮我列出openclaw的工作目录"。

红框标注的就是openclaw的工作目录了。

使用vscode来访问

直接下载一下vscode https://code.visualstudio.com/ ，这是个超级受欢迎的代码编辑器，可以更好的帮助你查看代码文件。

本地安装

如果你是本机安装的openclaw，就直接使用vscode，打开 .openclaw 目录就行，注意，这个目录是一个隐藏目录，需要你提前把显示隐藏目录打开才能找到。

远程安装

如果你和我一样是在别的机器上安装的，比如我就是在局域网内的虚拟机上安装的，需要使用vscode的远程连接功能去连接那台服务器上的.openclaw目录。

具体做法是打开vscode后，点左下角的这个图标，启动远程连

然后输入路径，注意，它默认就会打开你的家目录，你只需要在后面接上.opencla

 browser
├── canvas
├── completions
├── cred

p...:
- 含义：系统的核心配置文件，包含 API 密钥、模型设置、渠道（如飞书、微信）配置等。
- 能力：定义了智能体能用什么模型、连接哪个平台。
- 用法：建议通过控制台修改。你看到的 .bak 和 .2026... 是系统自动生成的版本备份，配置出错时可将其重命名回 openclaw.json 进行恢复。
credentials: 存储敏感的身份凭证，如 OAuth 令牌、API Keys 等。通常由系统管理，无需手动操作。
logs: 存放系统运行日志。当智能体报错或任务失败时，在此查看具体原因。

智能体与能力扩展

agents / subagents:
- 含义：存储主智能体及子智能体的定义和状态。
- 能力：OpenClaw 支持父智能体生成子智能体来处理特定任务（如代码编写或信息搜集）。
- 用法：系统在运行时自动维护，反映了当前活跃的 AI 实例。
skills:
- 含义：全局技能库，通常为 Markdown 格式的指令集。直接在目录最高层级写，说明所有的子Agent都可以使用这些skill
- 能力：赋予 AI “专业知识”或固定操作流程SOP（如“如何整理早报”），它是按需加载的增强插件。
- 用法：你可以将自定义的 .md 技能文件放入此目录，并在对话中通过技能名称调用。
extensions: 存放安装的第三方扩展插件，如特定平台的适配器或新工具。

任务执行与自动化

cron: 存储定时任务配置。允许 Agent 在特定时间（如每天早 7 点）自动执行任务。
browser: 存放浏览器自动化的持久化数据（如 Cookie、Session）。它支持通过 Playwright 操作网页。
delivery-queue: 发送队列，用于管理发送到飞书、微信等渠道的消息，确保在高频或网络波动时消息不丢失。
exec-approvals.json: 存储命令执行授权。当 AI 尝试运行高风险命令时，如果你在控制台点击了“总是允许”，记录会存放在这里。

记忆与数据存储

memory: 长短期记忆系统，通常存放 AI 记录的知识片段或历史事实。
canvas: 用于存放 AI 生成的“画布”内容（类似于 Claude Artifacts），如代码预览、文档草稿等。
media: 存放 AI 处理或生成的多媒体文件（图片、音频、截图）。

工作空间 (Workspace)

每一个子Agent都有一个属于自己的工作目录，和其他Agent相互隔离。

workspace: 默认的本地操作区。AI 读写文件、运行代码都在此沙盒中进行。
workspace-xxx (如 workspace-claude, workspace-stock-guru 等):
- 含义：这是 OpenClaw 的多任务/项目隔离机制。
- 能力：针对不同的角色（如招聘专员 recruiter、股票专家 stock-guru）分配独立的文件环境。
- 用法：当你在对话中切换到某个特定 Agent 时，它只能看到并操作对应的 workspace-xxx 文件夹，确保数据不互相干扰。

通讯渠道

feishu / openclaw-weixin: 存放对应即时通讯平台的适配数据和会话状态。
identity: 存储智能体在这些平台上的身份标识信息。

建议： 如果你需要调整 AI 的行为，优先修改 skills 里的 Markdown 文件；如果系统运行异常，先检查 logs。

你想深入了解其中哪个工作空间（Workspace）或技能（Skills）的具体配置吗？

openclaw.json详解

{
  // 元信息
  "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"
      }
    }
  }
}

绑定飞书机器人问题自查

三个地方需要查，agent.list，bindings中的agentId和match。

确认Agents中存在这个Agent，然后工作目录是独立的。

确认绑定配置bindings，AgentId要和一个渠道channel绑定，指定accountId就是绑定单个机器人

指定了peer就是绑定私聊或者群聊。

绑定多机器人的话，需要在account中存在机器人信息。

这三块配置需要仔细检查

最后最重要的！！！修改配置后记得重启网关！！！

"agents": {
  // 子Agent列表
  "list": [
    {
      "id": "recruiter",
      "name": "recruiter",
      "workspace": "/home/guantou/.openclaw/workspace-recruiter",
      "agentDir": "/home/guantou/.openclaw/agents/recruiter/agent"
    }
  ]
},
"bindings": [
  // 和机器人绑定
  {
    "agentId": "recruiter",
    "match": {
      "channel": "feishu",
      "accountId": "recruiter"
    }
  },
  // 和某个群聊绑定
  {
    "agentId": "recruiter",
    "match": {
      "channel": "feishu",
      "peer": {
        "kind": "group",
        "id": "oc_d327c72f3bbd38ba6707afce5a73109b"
      }
    }
  },
],
// 账号绑定
"channels": {
  "feishu": {
    "accounts": {
      "recruiter": {
        "appId": "cli_xxxxx",
        "appSecret": "xxxxx",
        "botName": "招聘HR",
        "dmPolicy": "open",
        "allowFrom": [
          "*"
        ],
        "enabled": true
      },
    }
  }
}

常用自查命令

重启网关使配置生效

openclaw gateway restart

查看日志

openclaw logs --follow --grep "config\|error"

检查网关状态

openclaw gateway status

运行诊断

openclaw doctor --repair

创建Agent

openclaw agents add
openclaw agents list # 查看Agent列表

Ctrl + `

OpenClaw 配置文件完整指南

基于官方文档: https://docs.openclaw.ai/

你的配置文件路径: ~/.openclaw/openclaw.json (JSON5 格式，支持注释和尾随逗号)

1`meta` - 元数据

字段	类型	说明
`lastTouchedVersion`	string	最后修改配置的 OpenClaw 版本号
`lastTouchedAt`	ISO 8601	最后修改时间

作用: 记录配置文件的版本追溯信息，便于排查兼容性问题。

2`env` - 环境变量配置

env.shellEnv - Shell 环境继承

字段	类型	选项	说明
`enabled`	boolean	`true` / `false`	是否继承系统 Shell 环境变量
`timeoutMs`	number	毫秒值	导入 Shell 环境的超时时间（默认 15000ms）

env.vars - 内联环境变量

{
  "env": {
    "vars": {
      "TAVILY_API_KEY": "xxxxxx",
      "SEARXNG_URL": "http://192.168.5.19:4000"
    }
  }
}

作用: 集中管理环境变量，避免散落在系统中。内联变量仅在进程环境缺少该键时才应用。

环境变量优先级:

进程已有环境变量（最高优先级）
env.vars 内联变量
.env 文件（CWD 和 ~/.openclaw/.env）
shellEnv 导入的 Shell 环境

3`wizard` - 设置向导状态

字段	类型	说明
`lastRunAt`	ISO 8601	上次运行向导的时间
`lastRunVersion`	string	上次运行向导时的版本
`lastRunCommand`	string	上次执行的命令 (`onboard` / `configure` / `doctor`)
`lastRunMode`	string	运行模式 (`local` / `remote`)
`lastRunCommit`	string	上次运行的 Git commit hash

作用: 跟踪用户是否已完成初始化设置向导。

4`browser` - 浏览器配置

字段	类型	选项	说明
`enabled`	boolean	`true` / `false`	是否启用浏览器自动化
`attachOnly`	boolean	`true` / `false`	是否仅附加到现有浏览器实例
`evaluateEnabled`	boolean	`true` / `false`	是否启用页面 JavaScript 执行
`defaultProfile`	string	配置文件名称	默认使用的浏览器配置文件
`ssrfPolicy.dangerouslyAllowPrivateNetwork`	boolean	`true` / `false`	是否允许访问私有网络（默认 true）

浏览器配置文件 `browser.profiles`)

配置项	说明
`driver`	驱动类型: `"existing-session"` / `"chrome"` / `"chromium"`
`attachOnly`	仅附加到现有会话
`userDataDir`	用户数据目录路径
`cdpPort`	Chrome DevTools Protocol 端口
`cdpUrl`	远程 CDP 地址
`color`	配置文件颜色标识
`headless`	是否无头模式
`noSandbox`	是否禁用沙箱

5`auth` - 认证配置

auth.profiles - 认证配置文件

{
  "auth": {
    "profiles": {
      "provider:profileName": {
        "provider": "provider-name",
        "mode": "api_key"
      }
    }
  }
}

字段	类型	选项	说明
`provider`	string	任意	AI 提供商标识
`mode`	string	`"api_key"` / `"oauth"`	认证模式

作用: 统一管理不同 AI 提供商的认证方式。

6`acp` - Agent Communication Protocol（智能体通信协议）

字段	类型	选项	说明
`enabled`	boolean	`true` / `false`	启用 ACP 协议
`dispatch.enabled`	boolean	`true` / `false`	启用请求分发
`backend`	string	`"acpx"`	ACP 后端实现
`defaultAgent`	string	智能体 ID	默认智能体（如 `claude`, `codex`, `pi`）
`allowedAgents`	string[]	智能体 ID 列表	允许的智能体白名单
`maxConcurrentSessions`	number	整数	最大并发会话数

ACP 流配置 `acp.stream`)

字段	类型	说明
`coalesceIdleMs`	number	流合并空闲时间（默认 300ms）
`maxChunkChars`	number	最大分块字符数（默认 1200）

ACP 运行时配置 `acp.runtime`)

字段	类型	说明
`ttlMinutes`	number	会话存活时间（默认 120 分钟）

作用: ACPx 是 OpenClaw 的智能体运行时协议，支持多智能体协同和任务调度，可连接 Pi、Claude Code、Codex、Cursor、Copilot、OpenCode、Gemini CLI 等外部编码工具。

7`models` - AI 模型配置

models.mode - 提供商目录行为

选项	说明
`"merge"` (默认)	将自定义配置与默认配置合并
`"replace"`	完全替换默认配置

models.providers - 自定义提供商

{
  "models": {
    "providers": {
      "provider-id": {
        "baseUrl": "https://api.example.com/v1",
        "apiKey": "your-api-key",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "model-id",
            "name": "Display Name",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.03,
              "cacheWrite": 0.12
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

模型字段说明

字段	类型	说明
`id`	string	模型唯一标识
`name`	string	显示名称
`reasoning`	boolean	是否支持推理
`input`	string[]	支持的输入类型: `"text"`, `"image"`, `"audio"`, `"video"`
`cost.input`	number	输入 token 成本（每百万）
`cost.output`	number	输出 token 成本（每百万）
`cost.cacheRead`	number	缓存读取成本（每百万）
`cost.cacheWrite`	number	缓存写入成本（每百万）
`contextWindow`	number	上下文窗口大小（tokens）
`maxTokens`	number	最大输出 tokens

API 适配器选项 `api`)

选项	说明
`"openai-completions"`	OpenAI Completions API
`"openai-responses"`	OpenAI Responses API
`"anthropic-messages"`	Anthropic Messages API
`"google-generative-ai"`	Google Generative AI API

8`agents` - 智能体定义

agents.defaults - 默认配置

工作空间配置

字段	类型	说明
`workspace`	string	默认工作目录
`repoRoot`	string	代码仓库根目录

启动配置

字段	类型	选项	说明
`skipBootstrap`	boolean	`true` / `false`	跳过工作空间引导文件加载
`bootstrapMaxChars`	number	字符数	每个引导文件最大字符数（默认 20000）
`bootstrapTotalMaxChars`	number	字符数	所有引导文件总字符数上限（默认 150000）
`bootstrapPromptTruncationWarning`	string	`"off"` / `"once"` / `"always"`	引导截断警告模式

媒体配置

字段	类型	说明
`imageMaxDimensionPx`	number	图片最大边长像素（默认 1200）

时区和时间格式

字段	类型	选项	说明
`userTimezone`	string	时区字符串	系统提示时区（如 `"America/Chicago"`）
`timeFormat`	string	`"auto"` / `"12"` / `"24"`	时间格式（默认 auto）

模型配置

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "provider/model-id",
        "fallback": "provider/fallback-model"
      }
    }
  }
}

CLI 后端配置 `agents.defaults.cliBackends`)

用于文本-only 回退运行（无工具调用）：

{
  "cliBackends": {
    "claude-cli": {
      "command": "/opt/homebrew/bin/claude"
    },
    "my-cli": {
      "command": "my-cli",
      "args": ["--json"],
      "output": "json",
      "modelArg": "--model",
      "sessionArg": "--session",
      "sessionMode": "existing",
      "systemPromptArg": "--system",
      "systemPromptWhen": "first",
      "imageArg": "--image",
      "imageMode": "repeat"
    }
  }
}

心跳配置 `agents.defaults.heartbeat`)

字段	类型	选项	说明
`every`	string	时长字符串	心跳间隔（如 `"30m"`, `"10m"`, `"0m"` 禁用）
`model`	string	模型 ID	心跳使用的模型
`includeReasoning`	boolean	`true` / `false`	是否包含推理输出
`lightContext`	boolean	`true` / `false`	轻量级上下文（仅保留 HEARTBEAT.md）
`isolatedSession`	boolean	`true` / `false`	每次心跳使用独立会话
`session`	string	会话名称	心跳会话标识
`to`	string	目标地址	心跳消息发送目标
`directPolicy`	string	`"allow"` / `"block"`	私聊投递策略
`target`	string	`"none"` / `"last"` / 频道名	投递目标
`prompt`	string	文本	心跳提示词
`ackMaxChars`	number	字符数	确认消息最大字符数
`suppressToolErrorWarnings`	boolean	`true` / `false`	抑制工具错误警告

压缩配置 `agents.defaults.compaction`)

字段	类型	选项	说明
`mode`	string	`"off"` / `"safeguard"` / `"auto"`	会话压缩模式

模式说明:

"off": 禁用压缩
"safeguard": 保护模式（推荐）
"auto": 自动压缩

上下文修剪 `agents.defaults.contextPruning`)

字段	类型	选项	说明
`enabled`	boolean	`true` / `false`	启用上下文修剪
`strategy`	string	`"summarize"` / `"truncate"`	修剪策略

输入指示器 `agents.defaults.typing`)

字段	类型	选项	说明
`mode`	string	`"instant"` / `"message"` / `"off"`	打字指示器模式
`intervalSeconds`	number	秒数	打字指示器间隔

模式说明:

"instant": 私聊/提及时立即显示（默认）
"message": 未提及的群聊消息时显示
"off": 禁用

沙箱配置 `agents.defaults.sandbox`)

字段	类型	选项	说明
`mode`	string	`"off"` / `"non-main"` / `"all"`	沙箱模式
`backend`	string	`"docker"` / `"ssh"` / `"openshell"`	沙箱后端
`scope`	string	`"session"` / `"agent"` / `"shared"`	沙箱作用域
`workspaceAccess`	string	`"none"` / `"ro"` / `"rw"`	工作空间访问权限
`workspaceRoot`	string	路径	沙箱工作空间根目录

沙箱模式说明:

"off": 禁用沙箱
"non-main": 非主智能体使用沙箱
"all": 所有智能体使用沙箱

agents.list - 智能体列表

{
  "agents": {
    "list": [
      {
        "id": "agent-id",
        "name": "Display Name",
        "default": true,
        "workspace": "~/.openclaw/workspace-agent",
        "agentDir": "~/.openclaw/agents/agent-id/agent",
        "model": "provider/model-id",
        "identity": {
          "name": "Agent Name",
          "theme": "helpful assistant",
          "emoji": "🤖",
          "avatar": "avatars/agent.png"
        },
        "tools": {
          "profile": "full",
          "alsoAllow": ["tool1", "tool2"],
          "deny": ["web_search", "web_fetch"]
        },
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "claude",
            "backend": "acpx",
            "mode": "persistent"
          }
        },
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        }
      }
    ]
  }
}

智能体字段说明

字段	类型	说明
`id`	string	智能体唯一标识（必需）
`name`	string	显示名称
`default`	boolean	是否为默认智能体
`workspace`	string	工作目录路径
`agentDir`	string	智能体配置目录
`model`	string	使用的模型（`provider/model-id`）
`identity`	object	身份配置（名称、主题、表情、头像）
`tools.profile`	string	工具配置文件
`tools.alsoAllow`	string[]	额外允许的工具
`tools.deny`	string[]	禁止的工具
`runtime.type`	string	运行时类型: `"acp"` / `"subagent"`
`runtime.acp.agent`	string	ACP 智能体 ID
`runtime.acp.backend`	string	ACP 后端
`runtime.acp.mode`	string	`"persistent"` / `"oneshot"`

9`tools` - 工具配置

tools.profile - 工具配置文件

选项	说明
`"full"`	启用完整工具集
`"read-only"`	只读工具
`"minimal"`	最小工具集

tools.loopDetection - 工具循环检测

字段	类型	说明
`enabled`	boolean	启用循环检测（默认 false）
`historySize`	number	循环分析保留的最大工具调用历史
`warningThreshold`	number	重复无进展模式警告阈值
`criticalThreshold`	number	阻止关键循环的更高阈值
`globalCircuitBreakerThreshold`	number	任何无进展运行的硬停止阈值
`detectors.genericRepeat`	boolean	警告重复相同工具/参数调用
`detectors.knownPollNoProgress`	boolean	警告已知轮询工具无进展
`detectors.pingPong`	boolean	警告交替无进展成对模式

tools.web - Web 工具配置

{
  "tools": {
    "web": {
      "search": {
        "enabled": true,
        "apiKey": "brave_api_key",
        "maxResults": 5,
        "timeoutSeconds": 30,
        "cacheTtlMinutes": 15
      },
      "fetch": {
        "enabled": true,
        "maxChars": 50000,
        "maxCharsCap": 50000,
        "timeoutSeconds": 30,
        "cacheTtlMinutes": 15,
        "userAgent": "custom-ua"
      }
    }
  }
}

tools.media - 媒体理解配置

字段	类型	说明
`concurrency`	number	并发处理数
`audio.enabled`	boolean	启用音频处理
`audio.maxBytes`	number	最大音频字节数
`audio.scope`	object	音频处理范围规则

10`bindings` - 频道绑定（路由规则）

{
  "bindings": [
    {
      "agentId": "agent-id",
      "type": "route",
      "match": {
        "channel": "whatsapp",
        "accountId": "personal",
        "peer": {
          "kind": "direct",
          "id": "+15555550123"
        }
      }
    },
    {
      "agentId": "agent-id",
      "type": "acp",
      "match": {
        "channel": "discord",
        "peer": {
          "kind": "channel",
          "id": "123456789012345678"
        }
      },
      "acp": {
        "mode": "persistent",
        "label": "My Session",
        "cwd": "/workspace",
        "backend": "acpx"
      }
    }
  ]
}

绑定字段说明

字段	类型	选项	说明
`type`	string	`"route"` / `"acp"`	绑定类型
`agentId`	string	智能体 ID	绑定的智能体
`match.channel`	string	频道名称	频道标识（whatsapp, telegram, discord, feishu 等）
`match.accountId`	string	账号 ID	账号标识（`*` = 任意账号）
`match.peer.kind`	string	`"direct"` / `"group"` / `"channel"`	对等方类型
`match.peer.id`	string	ID	对等方标识

ACP 绑定额外字段

字段	类型	选项	说明
`acp.mode`	string	`"persistent"` / `"oneshot"`	会话模式
`acp.label`	string	文本	会话标签
`acp.cwd`	string	路径	工作目录
`acp.backend`	string	后端名称	ACP 后端

11`messages` - 消息配置

messages.ackReaction - 确认反应表情

选项	说明
`"always"`	总是发送确认反应
`"group-mentions"`	仅在群聊中被 @ 时发送
`"never"`	从不发送

messages.tts - 文本转语音

字段	类型	选项	说明
`auto`	string	`"off"` / `"always"` / `"inbound"` / `"tagged"`	自动 TTS 模式
`mode`	string	`"final"` / `"all"`	TTS 模式
`provider`	string	`"elevenlabs"` / `"openai"`	TTS 提供商
`maxTextLength`	number	字符数	最大文本长度
`timeoutMs`	number	毫秒	超时时间

messages.talk - 语音对话模式

字段	类型	说明
`voiceId`	string	语音 ID
`voiceAliases`	object	语音别名映射
`modelId`	string	模型 ID
`outputFormat`	string	输出格式
`silenceTimeoutMs`	number	静音超时
`interruptOnSpeech`	boolean	检测到语音时中断

12`commands` - 命令配置

字段	类型	选项	说明
`native`	string/boolean	`"auto"` / `true` / `false`	原生命令
`nativeSkills`	string/boolean	`"auto"` / `true` / `false`	原生技能命令
`restart`	boolean	`true` / `false`	允许重启命令
`ownerDisplay`	string	`"raw"` / `"masked"`	所有者显示方式

13`session` - 会话配置

字段	类型	选项	说明
`scope`	string	`"per-sender"` / `"shared"`	会话范围
`dmScope`	string	`"main"` / `"per-peer"` / `"per-channel-peer"` / `"per-account-channel-peer"`	私聊会话范围

会话重置配置 `session.reset`)

字段	类型	选项	说明
`mode`	string	`"daily"` / `"idle"`	重置模式
`atHour`	number	0-23	每日重置小时
`idleMinutes`	number	分钟数	空闲超时

会话线程绑定 `session.threadBindings`)

字段	类型	说明
`enabled`	boolean	启用线程绑定
`idleHours`	number	空闲自动解绑时间（0 禁用）
`maxAgeHours`	number	最大存活时间（0 禁用）

14`hooks` - 钩子（生命周期事件）

hooks.enabled - 启用钩子

hooks.internal - 内部钩子

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "session-memory": {
          "enabled": true
        },
        "command-logger": {
          "enabled": true
        },
        "bootstrap-extra-files": {
          "enabled": true
        },
        "boot-md": {
          "enabled": true
        }
      }
    }
  }
}

内部钩子条目

钩子名称	功能
`session-memory`	会话记忆持久化
`command-logger`	命令日志记录
`bootstrap-extra-files`	启动时加载额外文件
`boot-md`	Markdown 启动文档

外部钩子配置

{
  "hooks": {
    "enabled": true,
    "token": "shared-secret",
    "path": "/hooks",
    "maxBodyBytes": 262144,
    "defaultSessionKey": "hook:ingress",
    "allowRequestSessionKey": false,
    "allowedSessionKeyPrefixes": ["hook:"],
    "allowedAgentIds": ["hooks", "main"],
    "presets": ["gmail"],
    "transformsDir": "~/.openclaw/hooks/transforms",
    "mappings": [
      {
        "match": {
          "path": "gmail"
        },
        "action": "agent",
        "agentId": "hooks",
        "wakeMode": "now",
        "name": "Gmail",
        "sessionKey": "hook:gmail:{{messages[0].id}}",
        "messageTemplate": "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        "deliver": true,
        "channel": "last",
        "model": "openai/gpt-5.2-mini"
      }
    ]
  }
}

15`channels` - 频道配置

通用频道字段

字段	类型	选项	说明
`enabled`	boolean	`true` / `false`	启用频道
`dmPolicy`	string	`"pairing"` / `"allowlist"` / `"open"` / `"disabled"`	私聊策略
`groupPolicy`	string	`"allowlist"` / `"open"` / `"disabled"`	群组策略
`allowFrom`	string[]	地址列表	允许的发送者列表（`["*"]` = 所有）
`requireMention`	boolean	`true` / `false`	群聊中是否需要 @
`streaming`	string/boolean	`true` / `false` / `"partial"` / `"block"` / `"progress"`	流式响应
`threadSession`	boolean	`true` / `false`	线程级会话隔离

DM 策略选项

选项	说明
`"pairing"` (默认)	未知发送者获取一次性配对码，所有者必须批准
`"allowlist"`	仅在 `allowFrom` 中的发送者
`"open"`	允许所有入站私聊（需要 `allowFrom: ["*"]`）
`"disabled"`	忽略所有入站私聊

群组策略选项

选项	说明
`"allowlist"` (默认)	仅匹配允许列表的群组
`"open"`	绕过群组允许列表（提及门控仍然适用）
`"disabled"`	阻止所有群组消息

飞书频道 `channels.feishu`)

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",
      "appSecret": "secret",
      "domain": "feishu",
      "requireMention": false,
      "footer": {
        "elapsed": true,
        "status": true
      },
      "streaming": true,
      "threadSession": true,
      "groups": {
        "*": {
          "requireMention": false,
          "groupPolicy": "open"
        }
      },
      "accounts": {
        "account-id": {
          "appId": "cli_xxx",
          "appSecret": "secret",
          "botName": "Bot Name",
          "dmPolicy": "open",
          "allowFrom": ["*"],
          "enabled": true
        }
      },
      "groupPolicy": "open",
      "replyMode": {
        "group": "streaming",
        "direct": "streaming"
      }
    }
  }
}

飞书频道字段

字段	类型	说明
`appId`	string	飞书应用 ID
`appSecret`	string	飞书应用密钥
`domain`	string	域名（feishu/larksuite）
`footer.elapsed`	boolean	显示耗时
`footer.status`	boolean	显示状态
`replyMode.group`	string	群聊回复模式
`replyMode.direct`	string	私聊回复模式

回复模式选项

选项	说明
`"streaming"`	流式回复
`"block"`	块式回复
`"off"`	关闭

16`gateway` - 网关配置

字段	类型	选项	说明
`port`	number	端口号	网关监听端口（默认 18789）
`mode`	string	`"local"` / `"remote"`	网关模式
`bind`	string	`"lan"` / `"localhost"` / `"tailscale"`	绑定接口

控制面板 `gateway.controlUi`)

字段	类型	选项	说明
`enabled`	boolean	`true` / `false`	启用 Web 控制面板
`allowedOrigins`	string[]	来源列表	允许的 CORS 来源（`["*"]` = 所有）
`dangerouslyAllowHostHeaderOriginFallback`	boolean	`true` / `false`	允许 Host 头回退
`allowInsecureAuth`	boolean	`true` / `false`	允许不安全认证
`dangerouslyDisableDeviceAuth`	boolean	`true` / `false`	禁用设备认证

认证 `gateway.auth`)

字段	类型	选项	说明
`mode`	string	`"token"` / `"oauth"` / `"none"`	认证模式
`token`	string	令牌	访问令牌

Tailscale `gateway.tailscale`)

字段	类型	选项	说明
`mode`	string	`"off"` / `"client"` / `"server"`	Tailscale 模式
`resetOnExit`	boolean	`true` / `false`	退出时重置

热重载 `gateway.reload`)

字段	类型	选项	说明
`mode`	string	`"hot"` / `"manual"` / `"off"`	重载模式

重载模式说明:

"hot": 热重载（自动应用配置变更）
"manual": 手动重载
"off": 禁用重载

17`skills` - 技能配置

skills.install - 安装配置

字段	类型	选项	说明
`nodeManager`	string	`"npm"` / `"yarn"` / `"pnpm"`	Node 包管理器

skills.entries - 技能条目

{
  "skills": {
    "entries": {
      "skill-name": {
        "enabled": true,
        "apiKey": "xxx",
        "env": {
          "KEY": "value"
        }
      }
    }
  }
}

18`plugins` - 插件配置

plugins.allow / plugins.deny - 插件白名单/黑名单

{
  "plugins": {
    "allow": ["acpx", "openclaw-lark"],
    "deny": ["blocked-plugin"]
  }
}

plugins.load.paths - 插件加载路径

{
  "plugins": {
    "load": {
      "paths": [
        "/path/to/extensions"
      ]
    }
  }
}

plugins.entries - 插件条目

{
  "plugins": {
    "entries": {
      "plugin-id": {
        "enabled": true,
        "apiKey": "plugin-api-key",
        "env": {
          "KEY": "value"
        },
        "config": {
          "permissionMode": "approve-all",
          "nonInteractivePermissions": "deny"
        },
        "hooks": {
          "allowPromptInjection": false
        },
        "subagent": {
          "allowModelOverride": true,
          "allowedModels": ["*"]
        }
      }
    }
  }
}

插件权限配置

字段	类型	选项	说明
`config.permissionMode`	string	`"approve-all"` / `"approve-reads"` / `"prompt"`	权限模式
`config.nonInteractivePermissions`	string	`"fail"` / `"deny"`	非交互式权限处理

权限模式说明:

"approve-all": 自动批准所有权限
"approve-reads": 自动批准读取权限，写入需要确认
"prompt": 每个权限都提示确认

非交互式权限说明:

"fail": 权限提示不可用时失败（默认）
"deny": 权限提示不可用时拒绝（优雅降级）

plugins.slots - 插件插槽

字段	类型	选项	说明
`memory`	string	插件 ID / `"none"`	活跃的内存插件
`contextEngine`	string	插件 ID / `"legacy"`	活跃的上下文引擎

plugins.installs - 插件安装元数据

由 CLI 管理，包含以下字段：

字段	说明
`source`	来源: `"npm"` / `"path"` / `"archive"`
`spec`	包规格
`sourcePath`	源路径
`installPath`	安装路径
`version`	版本
`resolvedName`	解析后的名称
`resolvedVersion`	解析后的版本
`integrity`	完整性哈希
`shasum`	SHA 校验和
`resolvedAt`	解析时间
`installedAt`	安装时间

19`cron` - 定时任务配置

{
  "cron": {
    "enabled": true,
    "maxConcurrentRuns": 2,
    "webhook": "https://example.com/webhook",
    "webhookToken": "token",
    "sessionRetention": "24h",
    "runLog": {
      "maxBytes": "2mb",
      "keepLines": 2000
    }
  }
}

字段	类型	说明
`enabled`	boolean	启用定时任务
`maxConcurrentRuns`	number	最大并发运行数
`webhook`	string	Webhook URL（已弃用）
`webhookToken`	string	Webhook 令牌
`sessionRetention`	string/false	会话保留时间或 false
`runLog.maxBytes`	string	运行日志最大字节数
`runLog.keepLines`	number	保留日志行数

20`identity` - 身份配置

{
  "agents": {
    "list": [
      {
        "id": "main",
        "identity": {
          "name": "Samantha",
          "theme": "helpful sloth",
          "emoji": "🦥",
          "avatar": "avatars/samantha.png"
        }
      }
    ]
  }
}

字段	类型	说明
`name`	string	智能体名称
`theme`	string	角色主题
`emoji`	string	表情符号
`avatar`	string	头像路径/URL/data URI

作用:

messages.ackReaction 从 identity.emoji 派生（回退到 👀）
mentionPatterns 从 identity.name / identity.emoji 派生

21. 环境变量引用

在配置字符串中使用 ${VAR_NAME} 引用环境变量：

{
  "gateway": {
    "auth": {
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

规则:

仅匹配大写名称: [A-Z_][A-Z0-9_]*
缺失/空变量会在配置加载时抛出错误
使用 $${VAR} 转义为字面量 ${VAR}

22. SecretRef（密钥引用）

使用对象形式引用密钥：

{
  "source": "env" | "file" | "exec",
  "provider": "default",
  "id": "..."
}

来源类型

来源	ID 格式	说明
`"env"`	`^[A-Z][A-Z0-9_]{0,127}$`	环境变量名
`"file"`	JSON Pointer 路径	文件内路径
`"exec"`	命令标识符	执行命令获取

23. 配置文件包含 `$include`)

将配置拆分到多个文件：

{
  "gateway": {
    "port": 18789
  },
  "agents": {
    "$include": "./agents.json5"
  },
  "broadcast": {
    "$include": [
      "./clients/mueller.json5",
      "./clients/schmidt.json5"
    ]
  }
}

合并行为:

单个文件: 替换包含的对象
文件数组: 按顺序深度合并（后面的覆盖前面的）
兄弟键: 在包含后合并（覆盖包含的值）
嵌套包含: 最多 10 层深度
路径: 相对于包含文件解析，必须保持在顶级配置目录内

24. 热重载行为

热应用（无需重启）

频道配置变更
智能体列表变更
工具配置变更
绑定规则变更
心跳配置变更

需要重启

网关端口/绑定变更
插件加载/卸载
沙箱后端变更
ACP 后端变更

[高级]龙虾开壳到配置详解 OpenClaw完全指南

版本自查

官方文档

找到配置目录位置

使用vscode来访问

本地安装

远程安装

智能体与能力扩展

任务执行与自动化

记忆与数据存储

工作空间 (Workspace)

通讯渠道

openclaw.json详解

绑定飞书机器人问题自查

常用自查命令

重启网关使配置生效

查看日志

检查网关状态

运行诊断

创建Agent

OpenClaw 配置文件完整指南

1meta - 元数据

2env - 环境变量配置

3wizard - 设置向导状态

4browser - 浏览器配置

浏览器配置文件 browser.profiles)

5auth - 认证配置

6acp - Agent Communication Protocol（智能体通信协议）

ACP 流配置 acp.stream)

ACP 运行时配置 acp.runtime)

7models - AI 模型配置

模型字段说明

API 适配器选项 api)

8agents - 智能体定义

工作空间配置

启动配置

媒体配置

时区和时间格式

模型配置

CLI 后端配置 agents.defaults.cliBackends)

心跳配置 agents.defaults.heartbeat)

压缩配置 agents.defaults.compaction)

上下文修剪 agents.defaults.contextPruning)

输入指示器 agents.defaults.typing)

沙箱配置 agents.defaults.sandbox)