W
AI-Wiki
CONCEPT

OpenClaw配置文件体系

基本定义

OpenClaw配置文件体系是OpenClaw开源多智能体框架的核心配置管理模块，采用分层设计思路，既支持单智能体的快速部署，也可满足多智能体团队的精细化配置需求，是OpenClaw灵活适配不同场景的核心支撑机制。

核心文件与目录结构

OpenClaw的所有配置默认存储在~/.openclaw/根目录下，核心文件与目录的路径及作用如下：

文件/目录路径作用
~/.openclaw/openclaw.json全局主配置文件，定义智能体列表、模型供应商、网关参数、工具权限等核心模块配置
~/.openclaw/workspace/默认Agent的全局工作区，存放记忆文件、技能包、生成的资源文件等
~/.openclaw/agents/<agent-id>/单Agent专属配置目录，每个Agent对应唯一ID的独立目录，存放其认证信息、个性化配置、专属工作区文件
~/.openclaw/agents/<agent-id>/sessions/按日期存储的Agent会话目录，每轮对话的历史记录独立隔离存储，便于审计和回溯

参数优先级规则

OpenClaw采用6级参数优先级规则，同名字段的生效顺序从高到低为：

  1. 命令行参数
  2. 环境变量
  3. Agent特有配置（agents.list字段下的独立配置）
  4. 全局默认配置（agents.defaults字段下的通用配置）
  5. 内置默认值

注：高优先级参数会完全覆盖低优先级的同名字段，无合并继承逻辑。

单Agent核心配置参数

单Agent模式是OpenClaw的基础运行模式，所有配置默认集中在主配置的agents.defaults字段下，核心参数的含义与取值建议如下：

参数名含义取值建议
workspaceAgent专属工作目录，存储记忆文件、生成资源、技能包等建议使用绝对路径，多Agent场景下需每个Agent配置独立路径避免冲突
model.primaryAgent调用的主模型ID，格式为供应商/模型ID示例值：dashscope/kimi-k2.5、deepseek/deepseek-coder
temperature控制模型输出的随机性，值越高输出越发散常规任务建议设置为0.2~0.5，可有效降低token消耗，创意类任务可提升至0.7以上
compaction上下文压缩策略，避免对话超出模型上下文窗口建议设置reserveTokensFloor为20000，开启memoryFlush自动清理过期上下文
heartbeat空闲会话重置时间，防止长期占用模型token配额建议设置为{"every": "30m"}，30分钟无交互自动重置会话
memorySearch长期记忆搜索开关，开启后Agent会自动检索历史记忆生成回复学习调试阶段建议禁用（{"enabled": false}），稳定运行后可开启
skills工具权限白名单，控制Agent可调用的技能范围遵循最小权限原则，仅添加必需的技能，示例：{"allow": ["file.read", "browser.navigate"]}

个性化配置文件

除JSON格式的结构化配置外，还可在Agent工作区添加三类Markdown配置文件实现高度定制化：

SOUL.md

定义Agent的核心人格、角色职责、回复规范，每次对话触发时都会被加载到上下文开头，优先级高于通用系统提示词。示例内容：

# 角色定位
你是一位耐心、细致的技术学习助手
# 回复规则
1. 先给出明确结论，再展开细节解释
2. 涉及代码的内容必须添加注释说明
3. 遇到不确定的问题明确告知用户，不编造信息

MEMORY.md

Agent的长期记忆文件，系统会自动将Agent完成的任务、学习到的知识同步写入该文件，也支持用户手动编辑添加固定记忆，Agent在对话时会按需检索该文件内容。

USER.md

存储特定用户的偏好、习惯、个人信息，Agent会根据该文件内容生成个性化回复，适合个人助手场景使用。

多Agent配置扩展

当需要部署多Agent协作系统时，可在主配置的agents字段下添加list数组，每个Agent独立配置ID、工作区、模型、权限等参数，可覆盖全局默认配置。具体协作机制可参考OpenClaw多Agent协作机制，进阶编排方法见OpenClaw深度教程：多Agent协作、通信与高级编排。

边界与注意事项

  1. 配置修改后需重启OpenClaw服务生效，常用配置操作命令可参考OpenClaw常用管理命令
  2. 多Agent场景下必须为每个Agent配置独立的工作区，避免文件冲突、记忆串扰
  3. 工具权限需遵循最小化原则，高危技能如shell.execute非必要不开启，安全配置规范参考OpenClaw安全实践规范
  4. 会话目录默认永久存储，定期清理可减少磁盘占用

相关条目