深入解析OpenClaw配置目录结构：从核心文件到最佳实践

April 19, 2026

OpenClaw 的所有核心配置、状态数据、工作区文件以及安装的技能，都统一存储在用户主目录下的一个中心位置：在 Linux 或 macOS 系统上是 ~/.openclaw/，而在 Windows 系统上则是 %USERPROFILE%\.openclaw\。

~/.openclaw/ 是整个系统的根配置目录，当你首次运行 openclaw onboard 或 openclaw onboard --install-daemon 命令时，该目录会被自动创建。

~/.openclaw/
├── openclaw.json                # 主配置文件（JSON/JSON5格式）
├── workspace/                   # 你的 AI “灵魂”工作文件夹（推荐进行 git 版本控制）
│   ├── SOUL.md                  # AI人格设定（语气、风格与行为准则）
│   ├── USER.md                  # 你的个人信息档案（让 AI 更了解你）
│   ├── MEMORY.md                # 长期记忆库（支持手动编辑）
│   ├── IDENTITY.md              # Agent 的名称与形象定义
│   ├── AGENTS.md                # 多智能体路由与协作规则
│   ├── BOOT.md                  # 系统启动提示词
│   ├── HEARTBEAT.md             # 每日自动化检查清单
│   └── skills/                  # 已安装的技能（每个技能一个独立的子文件夹）
├── agents/<cid>/                # 每个独立 Agent 实例的状态目录
├── memory/<cid>.sqlite          # 向量记忆数据库文件
├── credentials/                 # 旧版 API Key 与 OAuth 凭证存储位置
├── skills/                      # 全局共享技能包目录
└── secrets.json                 # 加密凭证文件（可选）

最核心的文件包括：

openclaw.json：存放所有全局设置（如模型、通信渠道、端口号、安全策略等）。
workspace/ 目录下的所有 .md 文件：这些 Markdown 文件可以直接用 VS Code 等编辑器修改，更改会实时生效。

查看或修改配置的常用命令：

openclaw configure      # 启动交互式配置向导
openclaw config file          # 显示主配置文件的完整路径
openclaw config validate      # 校验配置文件的合法性

路径	用途与说明
`~/.openclaw/openclaw.json`	核心主配置文件（最为关键！）存储所有全局设定，包括模型选择、Gateway 运行模式、网络绑定地址、Agents 默认参数、插件启用状态等。可用以下命令操作：• `openclaw config file`（显示文件完整路径）• `openclaw config get <json路径>` （获取特定配置项的值）• `openclaw config set <json路径> <值>` （设置特定配置项的值）
`~/.openclaw/workspace/`	默认工作区目录（Agent 的“灵魂”与人格所在地）存放一系列可直接编辑生效的 Markdown 文件：• `SOUL.md`：定义 AI 的人格特质与语言风格• `USER.md`：记录用户的个人偏好与背景信息• `MEMORY.md`：用于记录长期记忆• `AGENTS.md`：多智能体的指令与分工说明• `IDENTITY.md`：设定 Agent 的名称与主题形象• `BOOT.md`：系统启动时的初始化提示词• `HEARTBEAT.md`：定期执行的自动化检查清单
`~/.openclaw/agents/<cid>/`	单个智能体（Agent）实例的独立状态目录（其中 `<cid>` 为该实例的唯一标识 ID）
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`	新版推荐的 API Key 与 OAuth 凭证存储位置旧版本的凭证可能仍存放在 `~/.openclaw/credentials/` 目录下。
`~/.openclaw/memory/<cid>.sqlite`	向量索引存储数据库（用于实现记忆搜索功能）
`~/.openclaw/skills/`	全局技能目录通过 `openclaw skills install` 或 `clawhub install` 命令安装的所有技能包都集中存放在这里。每个技能是一个独立的子文件夹，其中包含定义该技能的 `SKILL.md` 文件。
`~/.openclaw/memory/`	长期记忆相关文件的存储目录（包含 SQLite 数据库及向量嵌入数据）
`/tmp/openclaw/*.log`	Gateway 网关服务的运行时日志文件（主要用于调试和问题排查）

核心配置文件详解

路径: ~/.openclaw/openclaw.json

说明: 这是 OpenClaw 最核心的配置文件，包含了所有系统级别的设置。

主要配置项概述:

gateway  - 网关服务的相关配置
  mode: 网关运行模式（例如 "local" 本地模式）
  port: 网关监听的端口号（默认为 18789）
  bind: 网关绑定的网络地址（默认为 127.0.0.1）
  token: 用于 Web UI 界面访问认证的安全令牌
models   - AI 模型的相关配置
  默认使用的模型设置
  各类模型 API 的认证信息
messages - 消息处理的相关配置
  TTS（文本转语音）功能的设置
  消息格式与处理流程的配置

示例配置片段:

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "bind": "127.0.0.1",
    "token": "c9917c5a066beeb26266d09baed99495e7563b33c771e89a"
  }
}

操作与维护建议:

首次安装系统后，建议通过运行 openclaw onboard 交互式向导来自动生成初始配置文件。
对配置文件进行任何修改后，都需要重启网关服务才能使新设置生效。
token 字段的值用于访问 Web 用户界面，请务必妥善保管，避免泄露。

工作区目录

路径: ~/.openclaw/workspace/

说明: 这是 OpenClaw 的默认工作目录，AI 生成的所有文件、临时处理数据以及用户请求的输出结果通常都保存在这个位置。

主要用途:

AI 智能体进行文件读写操作的默认根目录。
存储代码执行后产生的输出文件。
用于文档生成、编辑和暂存。
存放各类临时数据和中间文件。

权限与访问控制说明:

在默认安全策略下，AI 智能体仅被允许访问此目录及其下的所有子目录。
如果需要让 AI 访问系统其他路径的文件，需要额外配置并启用 filesystem-mcp 等技能，并显式授予相应的文件系统权限。
Windows 用户有时可能需要手动将工作区内的文件复制到其他位置以供其他程序使用。

使用与管理建议:

定期清理不再需要的临时文件，以释放磁盘空间。
对于重要的输出文件，建议在工作区之外进行额外备份。
可以在此目录下创建不同的项目子目录，以便更好地组织和管理文件。

智能体状态目录

路径: ~/.openclaw/agents/<cid>/

说明: 每个独立的会话（Conversation）都有一个对应的智能体状态目录，用于存储该会话的专属状态和配置。<cid> 是会话的唯一 ID，确保了不同会话之间的配置完全隔离。

典型的目录结构:

~/.openclaw/agents/<cid>/
├── agent/
│   ├── auth-profiles.json    # 存储该会话专用的 OAuth 令牌和 API 密钥
│   └── ...                    # 其他会话状态文件
└── ...                        # 可能的其他会话数据

关于 auth-profiles.json 文件:

专门用于存储该智能体实例所需的各种 API 认证信息。
其中包含了该会话所连接的各种外部服务的 OAuth 访问令牌。
这是新版本推荐的存储位置，旧版本中的凭证通常存放在 ~/.openclaw/credentials/ 目录。

数据隔离优势:

每个会话的认证信息和状态彼此独立，互不干扰。
允许用户为不同的会话或任务配置不同的 API 密钥，实现灵活的资源管理。
完美支持多个智能体实例并行运行，每个实例都有自己的“沙盒”环境。

认证凭据目录（旧版兼容）

路径: ~/.openclaw/credentials/

说明: 这是旧版本 OpenClaw 中用于存储所有认证凭据的默认目录。

版本升级与迁移说明:

新版本系统已将凭据存储机制迁移至 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 这个按会话隔离的位置。
从旧版本升级而来的用户，可能需要重新配置其 API 密钥和 OAuth 设置，或手动迁移凭证文件。
建议所有用户使用 openclaw models auth setup 命令来重新进行统一的认证设置。

记忆存储目录

路径: ~/.openclaw/memory/

说明: 这是 OpenClaw 持久化记忆系统的存储基地，包含了实现长期记忆和上下文关联所需的向量索引及历史对话记录。

目录下的主要文件类型:

<cid>.sqlite - 向量索引数据库文件
- 存储了历史对话经过嵌入模型处理后的语义向量。
- 为“记忆搜索”功能提供底层支持，实现基于语义的快速检索。
- 是构建智能体长期记忆能力的核心组件。
YYYY-MM-DD.md - 按日期归档的对话日志文件
- 以“年-月-日”格式命名的 Markdown 文件。
- 自动记录当天发生的所有对话内容，便于回溯。
- 为用户提供了人工查看、审计和归档对话历史的能力。

基于此目录的核心记忆功能:

语义向量搜索: 使用 memory search "关键词" 命令，可以在历史对话中进行基于语义而非简单字面匹配的搜索。
跨会话上下文关联: 系统能够利用存储的向量记忆，在不同会话间建立理解上的关联，保持对话的连续性。
个性化长期记忆: 智能体会逐渐“记住”用户的习惯、偏好和过往讨论的重要信息，并在后续交互中加以运用。

系统维护建议:

定期备份整个 memory 目录，以防数据丢失。
如果向量数据库变得非常庞大，可能会影响检索速度，可考虑定期将较旧的对话记录归档到其他位置。
日常的对话日志 Markdown 文件是进行问题排查和审计追踪的宝贵资源。

全局技能目录

路径: ~/.openclaw/skills/

说明: 所有全局共享技能（Skills）的安装目录。技能本质上是用于扩展 OpenClaw 核心功能的插件，使其能够与外部服务交互或执行复杂任务。

技能的管理命令:

安装新技能: npx clawhub install <skill-name>
列出已安装技能: openclaw skills list
在社区库中搜索技能: npx clawhub search <关键词>

一些常用技能示例:

filesystem-mcp - 增强的文件系统操作能力
github        - 与 GitHub 仓库进行集成和操作
nano-pdf      - PDF 文档的读取与编辑
notion / obsidian - 与主流笔记软件同步
weather       - 查询实时天气信息
summarize     - 对长文本内容进行自动摘要

技能生态与使用说明:

社区维护的 ClawHub 技能库提供了超过 500 种各式技能可供选择。
系统支持用户开发和安装自定义技能，以满足特定需求。
部分技能在运行时可能需要访问外部 API 或特定的系统资源。
配置注意事项:
- 许多技能需要单独配置其对应的 API Key 或进行 OAuth 授权。
- 部分技能（如 github）可能依赖系统上已安装的额外命令行工具（如 GitHub CLI）。
- 请注意，少数标为 macOS 专有的技能可能无法在 Windows 或 Linux 系统上正常运行。

网关服务日志目录

路径: /tmp/openclaw/*.log （通常位于系统临时目录）

说明: Gateway 网关服务在运行时产生的各种日志文件均存储于此，是排查系统问题的重要依据。

常见的日志类型包括:

网关服务的启动与停止过程记录。
所有 API 请求和响应的详细追踪信息。
运行过程中出现的错误、警告和异常堆栈信息。
系统性能与资源使用的监控数据。

日志查看与管理:

由于存储在系统临时目录，这些日志文件可能在计算机重启后被自动清除。
启动网关时使用 openclaw gateway --verbose 参数可以输出更详细的日志信息到控制台。
当遇到网关无法启动、连接异常或功能故障时，应首先检查此目录下的日志文件。

用户信息文件

路径: 通常位于工作区 (~/.openclaw/workspace/) 或用户自定义的位置。

说明: USER.md 是一个重要的个性化文件，其中包含了关于用户的详细描述信息，能够帮助 AI 更精准地理解用户的背景、需求和偏好，从而提供更贴切的回答和服务。

文件中可能包含的内容示例:

用户的个人偏好设置（如写作风格、回复长度等）。
常用的工作流程或项目背景介绍。
与 AI 协作时的特定习惯或自定义指令。
希望 AI 记住的关键个人信息。

配置文件管理最佳实践

制定有效的备份策略

需要定期备份的关键目录与文件:

# 备份整个 .openclaw 配置目录（推荐）
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# 仅备份最核心的配置文件和数据
cp ~/.openclaw/openclaw.json ~/backups/
cp -r ~/.openclaw/memory/ ~/backups/memory/

建议的备份频率:

主配置文件 (openclaw.json): 每次对其进行手动修改后立即备份。
记忆数据库 (memory/): 每周执行一次完整备份，因为其中积累了有价值的对话历史。
技能配置: 在安装或更新任何一个重要技能之后进行备份。

至关重要的安全建议

敏感信息的保护措施:

openclaw.json 文件中的 gateway.token 是访问 Web 界面的钥匙，切勿公开或泄露此文件。
auth-profiles.json 文件包含了各类服务的 API 密钥，其安全性至关重要，建议结合系统加密功能进行保护。
定期在相应的服务商后台更换重要的 API 密钥。
绝对不要将包含密钥的配置文件直接提交到 Git 等版本控制系统中。应使用 .gitignore 文件将其忽略。

系统权限设置建议（Unix/Linux/macOS 系统）:

# 确保配置目录仅对当前用户可读、写、执行
chmod 700 ~/.openclaw
# 确保核心配置文件仅对当前用户可读写
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/agents/*/agent/auth-profiles.json

平滑进行迁移与系统升级

版本升级前的准备工作:

在执行任何版本升级操作之前，务必备份整个 ~/.openclaw/ 目录。
仔细阅读新版本的发布说明（Release Notes），了解是否有不兼容的配置项变更。
对于从较旧版本升级的情况，部分凭证文件可能需要按照官方指南进行手动迁移。

实现跨设备配置同步:

可以通过同步 ~/.openclaw/ 目录（注意排除敏感凭证文件）来实现不同设备间 OpenClaw 配置的一致性。
同步时需注意操作系统间的路径差异（如 Windows 与 Unix 路径表示法的不同）。
对于 API 密钥等高度敏感信息，更安全的做法是在每台设备上独立配置，而非通过文件同步。

高效的系统故障排查

诊断配置与运行问题的命令:

# 检查主配置文件的 JSON 语法是否正确
cat ~/.openclaw/openclaw.json | json_pp

# 运行深度系统检查，诊断常见问题
openclaw doctor --deep

# 查看网关服务的当前运行状态
openclaw gateway status

一些常见问题及其解决思路:

认证突然失效: 尝试运行 openclaw models auth setup 命令，重新引导配置相关 API 密钥。
网关服务无法启动: 检查配置的端口（默认 18789）是否被其他程序占用，并查看 /tmp/openclaw/ 下的日志文件获取具体错误信息。
已安装的技能无法使用: 首先确认该技能所需的所有外部依赖（如命令行工具、库）均已正确安装，然后检查其对应的 API 密钥配置是否正确。

灵活运用环境变量配置

OpenClaw 支持通过环境变量来覆盖或补充配置文件中的设置，这在自动化部署或容器化环境中尤为有用。

设置常用 API 密钥的环境变量示例:

# 设置各类 AI 模型的 API 密钥
export ANTHROPIC_API_KEY="your-claude-key-here"
export OPENAI_API_KEY="your-openai-key-here"
export DEEPSEEK_API_KEY="your-deepseek-key-here"

# 自定义 OpenClaw 的配置根目录（不常用）
export OPENCLAW_HOME="~/my-custom-path/.openclaw"

环境变量的优先级规则:

在运行 openclaw onboard 配置向导时，系统会自动检测环境中已设置的这些 API 密钥变量。
通过环境变量设置的值通常会覆盖配置文件中对应的默认值。
这种方式非常适合在持续集成/持续部署（CI/CD）流程、Docker 容器或希望将密钥与配置文件分离的场景中使用。