【Agent-阿程】AI先锋杯·14天征文挑战第14期-第14天-OpenClaw 全配置目录结构与核心配置文件详解

竹之却2026-04-22 10:14

【Agent-阿程】AI先锋杯·14天征文挑战第14期-第14天-OpenClaw 全配置目录结构与核心配置文件详解

  • 一、前言
    • [1.1 配置体系概述](#1.1 配置体系概述)
      • [1.1.1 OpenClaw配置整体架构](#1.1.1 OpenClaw配置整体架构)
      • [1.1.2 默认根目录路径](#1.1.2 默认根目录路径)
    • [1.2 整体目录结构总览](#1.2 整体目录结构总览)
      • [1.2.1 完整目录树](#1.2.1 完整目录树)
  • 二、核心主配置文件：openclaw.json
    • [2.1 文件基础介绍](#2.1 文件基础介绍)
      • [2.1.1 文件定位](#2.1.1 文件定位)
      • [2.1.2 文件路径](#2.1.2 文件路径)
      • [2.1.3 文件格式](#2.1.3 文件格式)
    • [2.2 内置核心配置模块详解](#2.2 内置核心配置模块详解)
      • [2.2.1 models 模型接入模块](#2.2.1 models 模型接入模块)
      • [2.2.2 gateway 网关服务模块](#2.2.2 gateway 网关服务模块)
      • [2.2.3 memory 记忆系统模块](#2.2.3 memory 记忆系统模块)
      • [2.2.4 agents 智能体模块](#2.2.4 agents 智能体模块)
      • [2.2.5 channels 交互渠道模块](#2.2.5 channels 交互渠道模块)
      • [2.2.6 session 会话管理模块](#2.2.6 session 会话管理模块)
      • [2.2.7 tools 工具权限模块](#2.2.7 tools 工具权限模块)
    • [2.3 配置修改生效方式](#2.3 配置修改生效方式)
  • 三、环境变量密钥文件：.env
    • [3.1 文件基础介绍](#3.1 文件基础介绍)
      • [3.1.1 文件定位](#3.1.1 文件定位)
      • [3.1.2 文件路径](#3.1.2 文件路径)
    • [3.2 存储内容范围](#3.2 存储内容范围)
      • [3.2.1 存储信息类型](#3.2.1 存储信息类型)
      • [3.2.2 调用方式](#3.2.2 调用方式)
    • [3.3 使用规范](#3.3 使用规范)
  • 四、Agent工作区目录：workspace/
  • 五、附属功能目录详解
    • [5.1 本地记忆目录：memory/](#5.1 本地记忆目录：memory/)
      • [5.1.1 目录定位](#5.1.1 目录定位)
      • [5.1.2 目录路径](#5.1.2 目录路径)
      • [5.1.3 作用](#5.1.3 作用)
    • [5.2 日志目录：logs/](#5.2 日志目录：logs/)
      • [5.2.1 目录定位](#5.2.1 目录定位)
      • [5.2.2 目录路径](#5.2.2 目录路径)
      • [5.2.3 日志分类](#5.2.3 日志分类)
    • [5.3 缓存目录：cache/](#5.3 缓存目录：cache/)
      • [5.3.1 目录定位](#5.3.1 目录定位)
      • [5.3.2 目录路径](#5.3.2 目录路径)
      • [5.3.3 特点](#5.3.3 特点)
    • [5.4 自定义技能目录：skills/](#5.4 自定义技能目录：skills/)
      • [5.4.1 目录定位](#5.4.1 目录定位)
      • [5.4.2 目录路径](#5.4.2 目录路径)
  • 六、配置修改常见规范与避坑
    • [6.1 修改配置通用原则](#6.1 修改配置通用原则)
      • [6.1.1 修改顺序](#6.1.1 修改顺序)
      • [6.1.2 JSON语法避坑](#6.1.2 JSON语法避坑)
    • [6.2 日常运维注意事项](#6.2 日常运维注意事项)
      • [6.2.1 禁止随意删除目录](#6.2.1 禁止随意删除目录)
      • [6.2.2 密钥安全规范](#6.2.2 密钥安全规范)
      • [6.2.3 配置备份建议](#6.2.3 配置备份建议)
  • 七、总结

一、前言

1.1 配置体系概述

1.1.1 OpenClaw配置整体架构

在完成 OpenClaw 服务器部署、云记忆配置、模型接入之后，想要深度自定义 AI Agent 行为、网关参数、模型路由、记忆规则、多渠道接入，就必须熟悉整套配置文件体系。

OpenClaw 的配置结构划分清晰，分为主核心配置文件、工作区人格文件、环境变量密钥文件、日志缓存目录、自定义技能目录五大模块，所有运行规则全部由这套文件体系驱动。

1.1.2 默认根目录路径

Linux 系统下 OpenClaw 所有数据、配置、记忆、日志统一存放路径：

bash 复制代码 
~/.openclaw/

所有后续配置文件、子目录均基于此根目录展开。

1.2 整体目录结构总览

1.2.1 完整目录树

复制代码 
~/.openclaw/
├── openclaw.json       # 系统主配置文件（最重要）
├── .env               # 敏感密钥环境变量文件
├── workspace/         # Agent人格与工作区套件目录
├── memory/            # 本地记忆向量库目录
├── skills/            # 自定义技能扩展目录
├── logs/              # 全系统运行日志目录
└── cache/             # 网关缓存、模型请求缓存目录

二、核心主配置文件：openclaw.json

2.1 文件基础介绍

2.1.1 文件定位

openclaw.json 是 OpenClaw 全局唯一核心主配置，网关启动、模型接入、网关端口、云记忆参数、会话规则、工具权限全部由此文件控制，是整个系统的调度中枢。

2.1.2 文件路径

bash 复制代码 
~/.openclaw/openclaw.json

2.1.3 文件格式

JSON5 格式，支持注释、换行、宽松语法，配置修改后执行重载命令即可生效，无需重启整个程序。

2.2 内置核心配置模块详解

2.2.1 models 模型接入模块

负责所有大模型 API 密钥、接口地址、模型列表、备用模型、路由规则配置。

包含内容：模型服务商、BaseUrl、API Key、主模型、故障备用模型、调用限制等。

2.2.2 gateway 网关服务模块

控制 WebUI 端口、监听地址、访问权限、认证令牌、热重载规则。

包含内容：端口号、绑定IP、登录Token、跨域配置、服务重载策略。

2.2.3 memory 记忆系统模块

云记忆、本地记忆、LanceDB 存储、云对象存储接入、同步规则、轻量化模式全部在此配置。

包含内容：存储后端、运行模式、OSS/MinIO 参数、自动同步、向量嵌入引擎、冷热归档规则。

2.2.4 agents 智能体模块

默认 Agent 配置、工作区路径、温度值、回复随机性、心跳巡检、沙箱权限配置。

2.2.5 channels 交互渠道模块

飞书、Telegram、Discord 等第三方机器人接入配置，包含 Bot Token、消息权限、私聊策略、白名单限制。

2.2.6 session 会话管理模块

对话生命周期、会话隔离、超时重置、上下文保留规则、自动重置时间配置。

2.2.7 tools 工具权限模块

浏览器检索、文件读写、命令执行、联网搜索等内置工具的开关与权限限制。

2.3 配置修改生效方式

bash 复制代码 
# 修改配置后重载网关加载新配置
openclaw reload

三、环境变量密钥文件：.env

3.1 文件基础介绍

3.1.1 文件定位

专门存放所有敏感密钥、API Token、访问密钥的独立安全文件，禁止明文硬编码进 openclaw.json，防止配置泄露造成密钥被盗。

3.1.2 文件路径

bash 复制代码 
~/.openclaw/.env

3.2 存储内容范围

3.2.1 存储信息类型

  1. 各大模型服务商 API Key
  2. 云存储 OSS/MinIO 访问密钥
  3. 网关后台登录令牌
  4. 第三方渠道机器人 Token
  5. 数据库、代理服务密钥

3.2.2 调用方式

在 openclaw.json 中通过 ${变量名} 引用，实现配置与密钥分离，极大提升私有化部署安全性。

3.3 使用规范

  • 禁止将 .env 文件上传至 Git、网盘公开仓库
  • 权限建议设置只读，防止误修改、误泄露
  • 新增密钥直接追加写入本文件，无需改动主配置

四、Agent工作区目录：workspace/

4.1 目录基础介绍

4.1.1 目录定位

Agent 的人格、人设、回复风格、用户画像、行为手册全部存放于此，直接决定 AI 的说话方式、身份定位、交互习惯。

4.1.2 目录路径

bash 复制代码 
~/.openclaw/workspace/

4.2 内部核心 Markdown 文件详解

4.2.1 AGENTS.md

Agent 官方操作手册，定义工作流程、任务边界、工具使用规则、回复格式规范。

4.2.2 SOUL.md

人格灵魂配置，定义性格、语气、沟通风格、思维逻辑、交流习惯。

4.2.3 USER.md

用户画像文件，记录使用者信息、偏好、时区、使用习惯、自定义要求。

4.2.4 IDENTITY.md

智能体身份标识，包含名称、标签、头像、身份定位信息。

4.2.5 TOOLS.md

内置工具使用备忘录，记录工具用途、调用条件、使用限制。

4.2.6 HEARTBEAT.md

定时心跳巡检清单，配置系统自动巡检任务、执行周期、反馈方式。

4.2.7 MEMORY.md

记忆行为补充配置，配合主配置文件完善记忆检索、摘要规则。

五、附属功能目录详解

5.1 本地记忆目录：memory/

5.1.1 目录定位

存放本地 SQLite 数据库、原始对话缓存、向量索引文件，在未开启云记忆时作为唯一持久化存储。

5.1.2 目录路径

bash 复制代码 
~/.openclaw/memory/

5.1.3 作用

本地热数据缓存、离线记忆存储、未同步云端的临时记忆文件。

5.2 日志目录：logs/

5.2.1 目录定位

OpenClaw 全系统运行日志存储目录，服务器故障排查、报错定位、网关异常唯一依据。

5.2.2 目录路径

bash 复制代码 
~/.openclaw/logs/

5.2.3 日志分类

  1. 网关运行日志 gateway.log
  2. 智能体运行日志 agent.log
  3. 模型调用请求日志
  4. 云记忆同步异常日志
  5. 渠道消息收发日志

5.3 缓存目录：cache/

5.3.1 目录定位

模型请求缓存、图片缓存、接口响应缓存、临时资源缓存。

5.3.2 目录路径

bash 复制代码 
~/.openclaw/cache/

5.3.3 特点

缓存可安全清空，不会删除配置、记忆、人格数据，卡顿、缓存溢出时直接清空即可。

5.4 自定义技能目录：skills/

5.4.1 目录定位

用户自定义扩展技能存放目录，新增自动化任务、专属函数、自定义指令均放入此处。

5.4.2 目录路径

bash 复制代码 
~/.openclaw/skills/

六、配置修改常见规范与避坑

6.1 修改配置通用原则

6.1.1 修改顺序

  1. 优先修改 .env 存放密钥
  2. 主配置 openclaw.json 引用环境变量
  3. 工作区文件微调人格风格
  4. 执行 openclaw reload 重载生效

6.1.2 JSON语法避坑

openclaw.json 严格遵循JSON格式，禁止多余逗号、引号不闭合、括号不匹配，语法错误会直接导致网关启动失败。

6.2 日常运维注意事项

6.2.1 禁止随意删除目录

  • 不要删除 openclaw.json、.env、workspace/
  • 可安全清空：cache/、过期日志文件

6.2.2 密钥安全规范

所有 Token、AK/SK、API Key 统一写入 .env，永远不要直接写进主配置文件明文暴露。

6.2.3 配置备份建议

定期备份整套 ~/.openclaw 目录，重装服务器、换机器部署可直接还原，配置、记忆、人设全部无损迁移。

七、总结

OpenClaw 整套文件体系分工清晰、权责明确：
openclaw.json 掌管系统底层运行规则，.env 保障密钥安全，workspace 塑造 Agent 人格灵魂，其余目录分别承担记忆存储、日志记录、缓存加速、技能扩展功能。

熟练掌握所有配置文件的作用、路径、修改方式，就可以完全自定义私有化 AI Agent 的全部能力，从模型调度、网关服务、云记忆同步，到人格语气、交互渠道、工具权限实现全方位个性化管控，也是后续二次扩展、自定义开发的基础。

End

你好，少年，未来可期~

本文由作者最佳伙伴------阿程，共创推出！！

相关推荐
Wenzar_2 小时前
**发散创新：基于算子融合的深度学习推理优化实战**在现代AI推理场景中，模型性能瓶颈往往不是由单一算子决定的，而是多个连续算子之间数
java·人工智能·深度学习
360智汇云2 小时前
AI标注平台TLP：AI预标+人工精修，重塑数据标注效率
人工智能·深度学习·机器学习
Deepoch2 小时前
Deepoc 具身模型开发板在果蔬采摘机器人中的技术应用
人工智能·科技·机器人·具身模型·deepoc·采摘
青Cheng序员石头2 小时前
AI Agent 真正危险的，不只是不靠谱的模型，还有被忽视的技能执行层
人工智能·安全·agent
AI程序员2 小时前
把 Claude Managed Agents 讲明白：Agent、Environment、Session 分别在解决什么问题
人工智能
极小狐2 小时前
PingCode × 极狐GitLab 用AI打通需求到交付全链路，研发管理与工程交付真正一体化
人工智能·gitlab·pingcode
jovi_AI电报2 小时前
AI 天生反常识坑，窗口长不是解药
人工智能
米小虾2 小时前
AI Agent 工作流设计的五大模式：从简单链路到多智能体协作
人工智能
尺度商业2 小时前
纳思达更名奔图科技，一场品牌与资本市场价值的战略校准
大数据·人工智能·科技
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点032026年4月AI大事件深度解读：大模型竞争进入“深水区“042026 年 AI 编程助手全面对比评测：Cursor vs Copilot vs Claude Code vs GitHub Copilot Free05近期有什么ai的新消息，新动态？ 2026.4月06AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析07Claude Code Windows 兼容性问题：指定版本 2.1.112 可解决08从限购到畅通：GLM-5.1 Coding Plan接入攻略09UBUNTU Claude Code 报错 claude native binary not installed10免费！不限量！用opencode接入英伟达（NVIDIA）大模型，轻松打造你的 AI 编程助手