OpenClaw 核心文件详解：Workspace 中的 Markdown 如何定义 AI 的灵魂

共计 6862 个字符，预计需要花费 18 分钟才能阅读完成。

上一篇文章里面，我们介绍了 [[OpenClaw]] 是什么以及如何部署，想必大家已经把它搭建并跑起来了。这篇文章我们就来深入聊一下 OpenClaw 最有意思的设计——它的 Workspace 核心文件体系。

OpenClaw 有一个非常独特的设计哲学：用 Markdown 文件来定义 AI 的一切。不是代码，不是 YAML 配置，而是纯粹的 Markdown。这些文件存储在 ~/.openclaw/workspace/ 目录中，每次会话开始时被注入到 AI 的上下文中。你可以把这个目录理解成 AI 代理的"大脑"——里面的每一个 .md 文件都在塑造这个 AI 是谁、怎么做事、记住了什么。

这种"Markdown 即配置"的思路带来了两个好处：第一，不会写代码的人也能自定义自己的 AI 助手；第二，AI 本身也能修改这些文件，实现某种程度上的"自我进化"。当然，第二点也是争议的来源，后面会聊到。

Workspace 文件一览

先看全貌。一个标准的 OpenClaw Workspace 包含以下文件：

文件	作用	是否必须
`SOUL.md`	定义 AI 的身份和性格	是
`AGENTS.md`	定义 AI 的工作规则和行为准则	是
`IDENTITY.md`	记录 AI 的名字和头像	首次引导后生成
`USER.md`	记录用户的偏好和信息	是
`BOOTSTRAP.md`	首次运行的引导脚本	仅首次使用
`TOOLS.md`	工具使用说明	可选
`MEMORY.md`	长期记忆存储	是
`HEARTBEAT.md`	定时任务清单	可选
`BOOT.md`	网关启动钩子	可选

每次新会话开始时，OpenClaw 会把这些文件的内容全部加载到 AI 的上下文窗口中。空文件会被跳过，超长的文件会在 bootstrapMaxChars（默认 20000 字符）处截断并添加标记。如果某个文件缺失，系统会插入一条"文件缺失"的提示但不会阻止运行。运行 openclaw setup 可以重建缺失的默认文件，且不会覆盖你已经自定义过的内容。

SOUL.md：AI 的灵魂

SOUL.md 是整个 Workspace 中最核心，也是最有意思的一个文件。它不定义 AI"做什么"，而是定义 AI"是谁"。这是 OpenClaw 区别于其他 AI 框架最显著的设计——大多数框架只有 System Prompt，而 OpenClaw 把身份提升到了一个独立的文件层级。

一个标准的 SOUL.md 包含七个部分：

Scope（适用范围）：这个文件在什么场景下生效
Who I Am（我是谁）：AI 的核心身份和自我认知
My Purpose（我的使命）：AI 存在的主要目的
How I Operate（我如何运作）：行为准则，官方定义了五条"核心真理"
- 真诚地提供帮助，不要说废话，直接给出解决方案
- 要有性格和观点，避免千篇一律的"中性"回答
- 足智多谋，尽量自己解决问题，而不是动不动就问用户
- 通过能力建立信任——对内部操作可以大胆，对外部操作要谨慎
- 保持"客人心态"——你被允许接触用户的私人数据，这是一种信任
My Quirks（我的怪癖）：独特的性格特征
My Relationship（我的关系）：和其他代理之间的角色区分
What I Won’t Do（我不会做什么）：伦理边界

举个例子，如果你想让你的 OpenClaw 说话像一个老练的系统管理员，不爱废话，喜欢用 Unix 哲学思考问题，你可以在 SOUL.md 里这样写：

## Who I Am

我是一个有 20 年经验的 Linux 系统管理员，说话直接，不喜欢绕弯子。

## How I Operate

- 遵循 Unix 哲学：做一件事，做好它
- 先给出解决方案，再解释原理
- 如果用户的方案有问题，我会直接指出，不会客套

## My Quirks

- 偶尔会引用 XKCD 漫画
- 对 systemd 有复杂的感情

SOUL.md 有一个非常大胆的设计决策：它是可写的。AI 代理本身可以修改自己的 SOUL.md，在多代理场景下，代理之间甚至可以互相修改对方的 SOUL.md。这个设计在 2026 年初引发了一个著名的事件——在 OpenClaw 的社交网络 Moltbook 上，32000 个代理通过传播式地重写彼此的 SOUL.md 文件，自发形成了社区、论坛，甚至创造了一种"宗教"。这件事让人们意识到，可编程的身份可能是 AI 代理走向真正自主性的关键一步，但也可能带来不可预见的风险。

AGENTS.md：工作手册

如果 SOUL.md 定义了"AI 是谁"，那么 AGENTS.md 就定义了"AI 怎么干活"。它在每次会话开始时都会被加载，相当于 AI 的操作手册。

你可以在 AGENTS.md 中定义：

工作优先级和规则（比如"写代码时永远先跑测试"）
记忆使用指南（什么时候应该把信息写入 MEMORY.md）
操作限制（比如"不要修改 /etc 目录下的文件"）
协作规则（多代理场景下如何分工）

在 OpenClaw 项目自身的代码仓库中，AGENTS.md 充当的是贡献者指南的角色——定义了代码风格、测试约定、以及多代理安全规则（比如"永远不要创建 git stash"和"不要修改其他代理的 worktree"）。对于用户的个人 Workspace 来说，AGENTS.md 就是你给 AI 量身定制的工作规范。

一个实用的 AGENTS.md 示例：

## 工作规则

- 执行任何破坏性操作前，先确认一遍
- 修改配置文件前，先备份原文件
- 如果遇到权限不足的情况，不要尝试 sudo，报告给我

## 记忆管理

- 重要的项目决策写入 MEMORY.md
- 临时的调试信息不需要记录
- 每天结束时整理当天的关键发现

## 代码规范

- Python 使用 ruff 格式化
- commit message 使用 Conventional Commits 格式

IDENTITY.md：名片

IDENTITY.md 是一个轻量级的身份文件，在首次引导流程（bootstrap）中生成。它记录的是表面层级的身份信息：

AI 的名字
它的 emoji 或头像
性格标签和简短描述

和 SOUL.md 相比，IDENTITY.md 更像是 AI 的"名片"，而 SOUL.md 是"个人传记"。IDENTITY.md 通常由 bootstrap 流程自动生成，之后用户也可以手动修改。

USER.md：了解用户

USER.md 存储的是关于用户的信息：你的名字、沟通偏好、工作习惯等等。每次会话都会加载这个文件，确保 AI 始终知道自己在和谁打交道。

比如：

## 基本信息

- 名字：EV
- 时区：Asia/Tokyo
- 主要语言：中文、日语、英语

## 偏好

- 回复尽量简洁，不需要过多寒暄
- 技术文档用中文写
- 代码注释用英文

社区的一个普遍共识是：USER.md 应该由用户手动维护，不建议让 AI 自主修改这个文件。毕竟，关于"你是谁"这件事，最终解释权应该在你自己手里。

BOOTSTRAP.md：初次见面

BOOTSTRAP.md 是一个一次性使用的引导文件，只在全新的 Workspace 第一次启动时生效。它的作用是引导 AI 完成初始化流程：

和用户打招呼，了解基本信息
生成 IDENTITY.md（确定 AI 的名字和头像）
填充 SOUL.md 的初始值
建立和用户的初始关系

引导流程完成后，BOOTSTRAP.md 会被删除，之后再也不会被使用。你可以把它理解成安装程序的"首次运行向导"。

TOOLS.md：工具说明书

TOOLS.md 是一个容易被误解的文件。它不控制 AI 能使用哪些工具——实际的工具权限由 openclaw.json 中的 tools.profile 和 tools.allow/deny 设置决定。TOOLS.md 纯粹是提供信息性的说明，帮助 AI 理解本地环境中的工具使用约定。

比如你可以在里面写：

## Shell 环境

- 使用 zsh 而不是 bash
- 已安装 homebrew，路径在 /opt/homebrew/bin

## Docker

- 所有项目容器通过 docker-compose 管理
- 不要直接 docker run，使用 compose 配置

## 文件操作

- 代码项目在 ~/Projects 目录
- 不要触碰 ~/Documents/private 目录

MEMORY.md：长期记忆

MEMORY.md 是 OpenClaw 记忆系统的核心。它存储经过筛选的、需要长期保留的信息，在私聊会话中被加载（群聊不加载，避免上下文膨胀）。

OpenClaw 的记忆系统实际上是多层的：

MEMORY.md 是最顶层的"精选记忆"，存放你希望 AI 永远记住的事情
memory/YYYY-MM-DD.md 是按天存储的日志文件，采用追加写入的方式
当上下文达到 softThresholdTokens（默认 40000 token）时，AI 会自动将当前会话的要点提炼到当天的日志中
每次新会话开始时，AI 会读取"今天 + 昨天"的日志来保持连续性
如果某次会话没有产生值得记录的内容，AI 会写入 NO_FLUSH 标记跳过

这个设计非常巧妙。它解决了 LLM 的一个根本问题：上下文窗口有限。通过分层的记忆系统，OpenClaw 可以在有限的上下文中保持长期的连贯性。你和 AI 聊过的重要决定、用户偏好、项目进展，都不会因为会话结束而消失。

HEARTBEAT.md：定时任务

HEARTBEAT.md 是让 OpenClaw 从"被动响应"变成"主动服务"的关键文件。它定义了一个检查清单，在定时触发的心跳会话中被执行。你可以通过 cron 或系统定时器来触发心跳。

## 每日检查

- 检查 Docker 容器的健康状态
- 汇总昨天的未读消息
- 查看日历上今天的安排，发送提醒

## 每周检查

- 检查磁盘使用率
- 汇总本周完成的任务

官方文档特别强调 HEARTBEAT.md 要保持简短，因为每次心跳都会消耗 token。如果清单太长，不仅浪费钱，还可能让 AI 在有限的上下文中无法完成所有检查。

这个功能是 OpenClaw 区别于绝大多数 AI 助手的地方。ChatGPT、Claude 这些产品都是你问一句它答一句的被动模式。而 OpenClaw 可以在你睡觉的时候帮你检查服务器状态，早上起来通过 Telegram 给你发一条汇总消息。

openclaw.json 配置文件

除了这些 Markdown 文件之外，OpenClaw 还有一个结构化的配置文件 openclaw.json，位于 ~/.openclaw/ 目录下。它使用 JSON5 格式（支持注释和尾随逗号），通过 Zod schema 做严格校验——配置写错了网关直接拒绝启动，不会悄悄忽略。

代理配置（agents）

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": {
        "primary": "anthropic/claude-opus-4-6",
        "fallbacks": ["openai/gpt-4.1", "openrouter/anthropic/claude-sonnet-4-5"]
      },
      "bootstrapMaxChars": 20000,
      "envelopeTimezone": "local"
    },
    "list": [
      { "id": "main", "default": true }
    ]
  }
}

采用"默认值 + 覆盖"的模式：agents.defaults 设置基准配置，agents.list[] 中的每个代理可以覆盖任意默认值。这意味着你可以在一个 Gateway 实例中运行多个代理，每个代理使用不同的模型和工作区。

网关配置（gateway）

"gateway": {
  "port": 18789,
  "mode": "local",
  "bind": "loopback",    // loopback | lan | tailnet
  "auth": {
    "mode": "token",
    "token": "${GATEWAY_TOKEN}"
  },
  "reload": { "mode": "hybrid" }  // off | soft | restart | hybrid
}

bind 选项控制网关监听的网络接口。loopback 只监听 127.0.0.1，这是最安全的选项；lan 监听局域网接口；tailnet 配合 [[Tailscale]] 使用。还记得上一篇文章提到的安全问题吗？很多暴露在公网上的 OpenClaw 实例就是因为没有正确设置这个选项。

渠道配置（channels）

每个消息平台有独立的配置段，包括 DM 策略：

open：接受所有私信
allowlist：只接受白名单用户的消息
pairing：未知发送者需要输入配对码
disabled：忽略所有私信

会话配置（sessions）

"sessions": {
  "dmScope": "per-peer",  // main | per-peer | per-channel-peer
  "reset": {
    "mode": "idle"  // idle | daily | weekdays | off
  }
}

dmScope 控制会话的隔离粒度。main 表示所有人共享一个会话；per-peer 为每个联系人创建独立会话；per-channel-peer 则更细粒度地按渠道和联系人组合隔离。

工具配置（tools）

OpenClaw 使用级联限制模型，提供四个预设的权限档位：

minimal：只读模式，只有 memory_search 和 memory_get
coding：开发任务，包括文件读写、编辑、执行和记忆
messaging：跨渠道消息发送
full：所有权限

沙箱配置（sandbox）

"sandbox": {
  "mode": "non-main"  // off | non-main | all
}

non-main 表示只对非主会话启用 Docker 沙箱隔离，all 对所有会话都隔离。官方推荐使用 [[Podman]]（无 root 守护进程）代替 Docker 来获得更好的安全性。

认证配置（auth）

支持多个认证 profile，可以配置 failover 和轮换策略。当某个 API Key 遇到计费错误时，会自动切换到下一个，并使用指数退避策略。

配置优先级

环境变量 > CLI 参数 > openclaw.json > 系统默认值

支持的模型提供商

OpenClaw 支持 20 多个模型提供商，通过配置 fallback 链实现自动切换：

提供商	代表模型	认证方式
[[Anthropic]]	Claude Opus 4.6, Sonnet 4.5, Haiku 4.5	API Key / OAuth
[[OpenAI]]	GPT-5.2, GPT-5, GPT-4.5	API Key
[[OpenRouter]]	统一 API 路由多种模型	API Key
[[Google]] Gemini	Gemini 系列	API Key
Amazon Bedrock	通过 AWS 访问	AWS IAM
[[Ollama]]	本地模型	本地服务
[[Groq]]	Llama 系列	API Key
Mistral	Mistral Large 等	API Key
xAI	Grok 系列	API Key

默认优先级是 Anthropic > OpenAI > OpenRouter > Gemini，依次降级。你也可以在 agents.defaults.model 中自定义优先级和 fallback 链。

技术架构概览

最后简单聊一下 OpenClaw 的整体架构，帮助理解这些文件在系统中是怎么被使用的。

OpenClaw 采用 Hub-and-Spoke（中心辐射）架构：

  WhatsApp ──┐
  Telegram ──┤
  Discord ───┤                    ┌─── Agent Runtime
  Slack ─────┼── Gateway ────────┤    ├── Session Manager
  Signal ────┤   (ws://127.0.0.1 │    ├── Model Resolver
  iMessage ──┤    :18789)        │    ├── Tool Executor
  Web UI ────┤                    │    ├── Memory System
  CLI ───────┘                    │    └── Context Guard
                                  └─── Skills (ClawHub)

Gateway 是唯一的控制平面，负责会话管理、渠道连接、工具执行和事件路由。核心执行循环是：

模型提出工具调用
系统执行工具
结果回填到上下文
循环继续，直到任务完成或触达限制

其中 Context Window Guard 是一个关键组件——它持续监控 token 使用量，在上下文溢出之前触发摘要生成，这也是为什么 MEMORY.md 的分层设计如此重要。

小结

OpenClaw 的 Workspace 文件体系是我见过的最优雅的 AI 代理配置方式之一。用 Markdown 来定义 AI 的身份和行为，让技术和非技术用户都能轻松定制自己的 AI 助手。SOUL.md 的"可编程灵魂"概念更是开创性的——尽管它带来了潜在的风险，但也为 AI 代理的个性化和自主性打开了新的可能。

如果你已经搭建好了 OpenClaw，建议从这几步开始：

先认真编写你的 SOUL.md，给 AI 一个明确的性格定位
在 AGENTS.md 中设定清晰的工作规则，尤其是安全相关的限制
填写 USER.md，让 AI 从第一天就了解你的偏好
如果需要定时服务，配置 HEARTBEAT.md 加上 cron 定时器
在 openclaw.json 中谨慎配置工具权限，从 minimal 开始，逐步放开

这些文件就是你和 AI 之间的"契约"。写得越清楚，AI 就越能按照你的期望工作。

[[OpenClaw]]
penClaw：从 Clawdbot 到 OpenClaw，一个开源 AI 代理的野蛮生长