读懂 .openclaw，搭好你的虾塘

海狸养虾记 · 第 1 期

全文约3200字，阅读约 14 分钟

养虾先挖塘

养虾先挖塘，养 OpenClaw 先建 .openclaw。

如果你还没听说过 OpenClaw，简单说：它是一个 AI Agent 多人协作框架。你可以在里面养一群 AI Agent——有的写代码，有的写文章，有的发公众号，有的帮你盯数据——它们各司其职，互相配合。

但这一缸虾养在哪里？答案就是 ~/.openclaw/ 这个文件夹。它是所有 Agent 共享的”虾塘”——水质、温度、饲料分配、虾的房间号，全都记在这里。

一条命令就能挖好这个塘：

openclaw init

执行后，你的 home 目录下会多出一个 .openclaw/ 文件夹。别急，我们先站在塘边看看全景。

虾塘全景图

~/.openclaw/
├── openclaw.json              # 全局配置文件（中控台）
├── workspace/                 # 默认 Agent 的工作空间
│   ├── SOUL.md
│   ├── AGENTS.md
│   ├── USER.md
│   ├── TOOLS.md
│   ├── IDENTITY.md
│   ├── MEMORY.md
│   ├── HEARTBEAT.md
│   ├── BOOTSTRAP.md
│   ├── BOOT.md
│   ├── memory/
│   │   └── YYYY-MM-DD.md
│   ├── skills/
│   └── canvas/
├── workspace-<name>/          # 多 Agent 时各自的独立空间
├── agents/
│   └── <agentId>/
│       ├── agent/             # 认证信息、模型注册
│       └── sessions/          # 聊天记录、路由状态
├── skills/                    # 所有 Agent 共享的技能
├── credentials/               # OAuth tokens、API keys 等凭证
├── sandboxes/                 # 沙箱工作空间（开启沙箱时使用）
└── .env                       # 全局环境变量（可选）

看起来东西不少。别急，我们挨个拆解。

.openclaw 目录结构全景图

openclaw.json — 虾塘的中控台

openclaw.json 是整个虾塘的核心配置文件，放在 ~/.openclaw/ 根目录下。

格式：JSON5

它用的是 JSON5 格式，不是标准 JSON。这意味着你可以：

{
  // 写注释
  name: "my-agent",     // key 不用加引号
  list: [1, 2, 3,],     // 末尾可以有逗号
}

写起来比纯 JSON 舒服很多，也更容易维护。

热重载

Gateway 会持续监听这个文件的变化。大部分修改保存后自动生效，不需要手动重启。具体来说：

热生效：channels、agents、models、bindings、hooks、cron、tools、skills 的修改
需重启：gateway 本身的配置（端口、绑定地址、TLS 证书等）

热重载模式可以在配置中调整：

{
  gateway: {
    hotReload: "hybrid",  // 默认值：安全改动热生效，关键改动自动重启
  },
}

配置结构总览

{
  agents: { ... },     // Agent 定义
  models: { ... },     // 模型供应商配置（API keys、base URLs）
  tools: { ... },      // 工具开关与权限
  channels: { ... },   // 通信渠道（Discord 等）
  bindings: [ ... ],   // 消息路由规则
  gateway: { ... },    // Gateway 服务端设置
  skills: { ... },     // 技能配置
  cron: { ... },       // 定时任务
}

环境变量

配置中的字符串值支持环境变量替换：

{
  channels: {
    discord: {
      token: {
        source: "env",
        provider: "default",
        id: "DISCORD_BOT_TOKEN",
      },
    },
  },
}

OpenClaw 按以下顺序查找环境变量：

父进程的环境变量
当前工作目录下的 .env 文件
~/.openclaw/.env 文件

强烈建议：所有敏感信息（bot token、API key）都用环境变量，不要明文写在配置里。

配置优先级

当你有多个配置来源时，按”就近覆盖”原则：

项目级 openclaw.json（最高）
  > 全局 ~/.config/openclaw/config.json
    > 内置默认值（最低）

workspace/ — 虾的房间

workspace/ 是 Agent 的”家”，也是它启动时的默认工作目录。每只 Agent 可以有自己独立的 workspace（如 workspace-dev/、workspace-ink/），也可以多个 Agent 共享同一个。

Workspace 里住着谁？

Workspace 文件系统全景图

一个标准的 workspace 目录包含以下文件：

workspace/
├── SOUL.md          # Agent 的人格与性格
├── AGENTS.md        # Agent 的操作指令与协作规则
├── USER.md          # 用户信息与偏好
├── TOOLS.md         # 工具使用笔记
├── IDENTITY.md      # Agent 的名字和标识（可选）
├── MEMORY.md        # 长期记忆（策展过的精华）
├── HEARTBEAT.md     # 心跳任务清单（可选）
├── BOOTSTRAP.md     # 首次运行仪式（完成后删除）
├── BOOT.md          # Gateway 重启时执行的 checklist（可选）
├── memory/          # 每日日志（原始记录）
│   └── YYYY-MM-DD.md
├── skills/          # Agent 专属技能（最高优先级）
└── canvas/          # Canvas UI 文件（可选）

我们一个个看。

SOUL.md — Agent 的人格基因

加载时机：每次 session 开始时。

SOUL.md 定义了 Agent “是谁”。它包含：

字段	说明
Personality	Agent 的性格描述：冷静务实？活泼幽默？严谨精确？
Tone	Agent 的语气风格：正式？口语化？技术讨论用代码说话？
Principles	Agent 的行为准则：安全底线、工作方式、决策逻辑
Boundaries	Agent 的禁区：哪些操作绝对不能做
Expertise	Agent 的专业领域

简单来说，SOUL.md 决定了这只虾的”先天性格”。你可以把它理解成 Agent 的出厂设置。同一种工作（比如写代码），不同的 SOUL.md 会产生截然不同的交互风格——一个是严格的教学派，一个是动手的实战派。

注意：SOUL.md 不是写一次就固定的。随着你和 Agent 的磨合，你会不断调整它，让它越来越符合你的工作习惯。建议定期回顾和优化。

AGENTS.md — Agent 的工作手册

加载时机：每次 session 开始时。

如果说 SOUL.md 是”先天性格”，AGENTS.md 就是”后天训练”。它定义了 Agent 怎么做事：

角色定位：这只 Agent 负责什么？编码？写作？数据分析？
工作流程：接任务的步骤、交付物的格式、验收标准
协作规则：跟其他 Agent 怎么分工、怎么交接
代码/内容规范：代码风格、commit 规范、文章格式等

一个实用的 AGENTS.md 应该具体到可执行的粒度。比如不要只写”负责编码”，而是写清楚”收到任务 → 分析需求 → 设计方案 → 实现测试 → 提交交付”的完整流程。

USER.md — 你是谁

加载时机：每次 session 开始时。

USER.md 告诉 Agent 它的用户是谁。通常包含：

怎么称呼你
你的时区和语言偏好
你的工作习惯和喜好
你的技术栈和常用工具

这让 Agent 知道”我在帮谁”，从而调整自己的行为。比如你习惯用中文沟通、时区是东八区、技术栈是 TypeScript + React——这些信息写在 USER.md 里，Agent 就不用每次都问。

TOOLS.md — 工具使用笔记

加载时机：每次 session 开始时。

TOOLS.md 是工具使用的备忘录，不是工具开关。它记录的是：

本地安装了哪些工具、版本是什么
常用命令的快捷方式
工具使用中的注意事项和踩坑经验

注意：TOOLS.md 不控制工具的实际启用/禁用。工具权限由 openclaw.json 中的 tools.allow / tools.deny 控制。TOOLS.md 只是给 Agent 看的”工具说明书”。

IDENTITY.md — Agent 的名片

可选文件。

记录 Agent 的名字、主题和 emoji 标识。通常在 openclaw onboard 或 openclaw configure 时自动生成。你也可以手动创建它，给 Agent 一个自定义的身份标识。

MEMORY.md — 长期记忆

加载时机：仅在主 session（与用户的私聊）中加载。不在共享环境（群组会话）中加载。

MEMORY.md 是 Agent 的”策展记忆”。不同于 memory/ 目录下的每日原始日志，MEMORY.md 里存的是经过筛选、提炼的长期重要信息：

你的偏好和习惯
重要的项目决策记录
反复出现的问题和解法
值得保留的经验教训

安全规则很重要：MEMORY.md 只在私聊中加载，群聊中不加载。这是为了防止你的个人信息和偏好泄露给群里的其他人。如果你发现 Agent 在群聊中提到了你 MEMORY.md 里的私人信息，这是一个 bug，应该报告。

Session 启动流程：Agent 醒来时读取文件的顺序

HEARTBEAT.md — 定期体检清单

可选文件。

加载时机：心跳触发时。

HEARTBEAT.md 是 Agent 定期醒来时要检查的清单。比如：

## 定期检查项（轮流执行，不要每次全做）
- [ ] 检查平台数据是否有异常波动
- [ ] 检查是否有待处理的任务
- [ ] 如发现异常，通知相关 Agent

最佳实践：保持 HEARTBEAT.md 短小精悍。心跳时 Agent 只加载这个文件（如果 lightContext: true），不会加载完整的 SOUL.md 和 AGENTS.md，目的是省 Token。如果写太多，反而浪费。

BOOTSTRAP.md 和 BOOT.md

BOOTSTRAP.md 是 Agent 首次启动时的初始化仪式。它定义了 Agent 第一次醒来需要做什么——自我介绍、确认配置、建立初始记忆等。仪式完成后，这个文件应该被删除，后续启动不再执行。

BOOT.md 是 Gateway 重启时执行的 checklist。当你修改了 Gateway 配置导致重启时，BOOT.md 里的内容会被执行一遍，用于恢复状态或执行初始化检查。

两个文件都是可选的。如果你不需要特殊的启动逻辑，可以不创建。

memory/ — 每日原始日志

memory/
├── 2026-04-06.md    # 昨天发生了什么
├── 2026-04-07.md    # 今天发生了什么
└── ...

加载时机：Session 开始时，读取今天和昨天的日志。

memory/ 目录存储的是 Agent 的每日原始记忆——像人的短期记忆，记录每天发生了什么事、做了什么决定、遇到了什么问题。

这些日志是 MEMORY.md 的数据源。Agent 会在心跳期间周期性地从 memory/ 中提炼值得长期保留的信息，更新到 MEMORY.md 里。

重要原则：Agent 的记忆必须写文件，不能”心里记”。因为 Agent 的 session 重启后，文件是唯一的连续性来源。没有写进文件的记忆，下次醒来就忘了。

skills/ — Agent 专属技能

workspace 下的 skills/ 目录存放这只 Agent 专属的技能。技能以 SKILL.md 格式定义：

---
name: my-skill
description: 当用户提到 "xxx" 时使用此技能
metadata: {"openclaw": {"requires": {"bins": ["bun"], "env": ["API_KEY"]}}}
---

# 技能说明
## 使用方法
...

workspace skills 具有最高优先级——当与共享技能或内置技能同名时，workspace 的版本会覆盖它们。这使得你可以为特定 Agent 定制专属的技能行为。

Bootstrap 文件的尺寸限制

所有 bootstrap 文件（SOUL.md、AGENTS.md、USER.md 等）有尺寸上限，防止 Token 浪费：

单个文件上限：agents.defaults.bootstrapMaxChars，默认 20,000 字符
所有文件总计上限：agents.defaults.bootstrapTotalMaxChars，默认 150,000 字符

超出部分会被截断。如果你的 SOUL.md 写得太长，后面的内容 Agent 就看不到了。所以保持 bootstrap 文件精炼很重要。

agents/ — 虾的档案柜

~/.openclaw/agents/ 目录存放每只 Agent 的管理数据，与 workspace 的区别是：workspace 是 Agent 的”生活空间”，agents/ 是”行政档案”。

目录结构

agents/
└── <agentId>/
    ├── agent/
    │   └── auth-profiles.json    # 认证信息（OAuth tokens、API keys）
    └── sessions/
        └── <session-id>.json     # 聊天记录与路由状态

agent/ — 认证与配置

agent/auth-profiles.json 存储这只 Agent 的认证信息，包括：

OAuth tokens（用于连接第三方服务）
API keys（用于调用大模型 API）
模型注册表（Agent 可用的模型列表）

关键规则：认证信息按 Agent 隔离。 不同 Agent 之间的凭证是完全独立的。Agent A 的 API key 不会泄露给 Agent B。

也因此，绝对不要跨 Agent 复用 agentDir。 如果两只 Agent 指向同一个 agents/<id>/ 目录，会导致认证冲突和 session 错乱。

sessions/ — 对话历史

sessions/ 目录存储这只 Agent 的所有对话记录和路由状态。每次 Agent 被唤醒并产生对话，都会在这里留下记录。

这些 session 文件支持：

历史回看：通过 openclaw sessions history --agent <id> 查看
跨 session 连续性：Agent 重启后可以读取之前的对话
问题排查：Agent 行为异常时，检查 session 文件可以定位原因

如果某只 Agent 的行为突然异常（比如持续报错），可以让另一只 Agent 帮忙检查它的 session 文件，找到问题并修复。

skills/ — 共享技能库

~/.openclaw/skills/ 目录存放所有 Agent 共享的技能。

技能加载优先级

workspace/skills/        （Agent 专属技能，最高优先级）
  > ~/.openclaw/skills/  （全虾塘共享技能）
    > 内置 skills        （OpenClaw 自带，最低优先级）

当同一技能名在不同层级都存在时，高优先级的版本会覆盖低优先级。

怎么选放哪里？

只有某个 Agent 用 → 放在该 Agent 的 workspace/skills/ 里
多个 Agent 都可能用 → 放在 ~/.openclaw/skills/ 共享目录
还需要更多共享目录 → 通过 skills.load.extraDirs 配置额外路径

credentials/ — 凭证保险柜

~/.openclaw/credentials/ 存储通信渠道的认证状态：

Discord bot 的连接信息与配对数据
第三方服务的 OAuth tokens
API keys 等敏感凭证

这个目录应该严格保护。建议：

不要把它加入 Git 仓库
使用 openclaw security audit 命令检查权限
操作系统层面确保只有你的用户账户可以读取

OpenClaw 提供了安全审计工具：

# 只读检查
openclaw security audit

# 深度检查（含 WebSocket 探测）
openclaw security audit --deep

# 自动修复权限问题（如 chmod 600/700）
openclaw security audit --fix

sandboxes/ — 隔离池

当你开启了沙箱模式，Agent 不会直接在宿主机上运行，而是在隔离的容器环境中执行。沙箱工作空间就在 ~/.openclaw/sandboxes/ 下生成。

沙箱模式

模式	说明
`off`	无沙箱，完全访问宿主机（默认）
`non-main`	非主 session 使用沙箱
`all`	所有 session 都在沙箱中运行

Workspace 访问级别（沙箱内）

级别	说明
`rw`	可读写自己的 workspace
`ro`	workspace 只读挂载在 `/agent`
`none`	完全隔离的沙箱 workspace

沙箱是个进阶话题。刚开始养虾时用 off 模式就好，等你需要把 Agent 开放给其他人使用时，再考虑开启沙箱。

.env — 全局环境变量

~/.openclaw/.env 是可选的环境变量文件。你可以在这里集中管理所有敏感配置：

DISCORD_BOT_TOKEN=你的_bot_token
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

配置文件中通过 ${VAR_NAME} 引用即可。也可以用 $${VAR} 语法表示”不要替换”的原始 $ 符号。

一只虾起步：最小可运行配置

虾塘的每个角落都看过了。现在让我们从零开始，用最小配置把虾塘跑起来。

从零搭建虾塘的完整流程

Step 1：安装并初始化

# 安装 OpenClaw
brew install openclaw

# 初始化虾塘
openclaw init

Step 2：创建 Discord Bot

前往 Discord Developer Portal，点击 New Application 创建应用
点击左侧 Bot，设置用户名，然后开启以下 Privileged Gateway Intents：
- Message Content Intent（必须）
- Server Members Intent（推荐）
点击 Reset Token 复制 Bot Token（只显示一次，妥善保存）
在 OAuth2 页面生成邀请链接，勾选 bot + applications.commands，权限选择：
- View Channels、Send Messages、Read Message History、Embed Links、Attach Files
用邀请链接将 Bot 添加到你的 Discord 服务器
在 Discord 设置中开启 Developer Mode（User Settings → Advanced），右键复制你的 Server ID 和 User ID

Step 3：安全地配置 Bot Token

不要把 token 明文写在配置文件或聊天里。 使用环境变量：

export DISCORD_BOT_TOKEN="你的_bot_token"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set channels.discord.enabled true --strict-json

这会将 token 以 SecretRef 形式存储在配置中，实际值从环境变量 DISCORD_BOT_TOKEN 读取：

// openclaw.json 中生成的内容
{
  channels: {
    discord: {
      enabled: true,
      token: {
        source: "env",
        provider: "default",
        id: "DISCORD_BOT_TOKEN",
      },
    },
  },
}

Step 4：添加服务器白名单

让你的 Bot 能在服务器频道中响应，而不仅是私聊：

# 通过 CLI 设置（推荐）
# 或直接编辑 openclaw.json：

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "YOUR_SERVER_ID": {
          requireMention: false,       // 私人服务器不需要 @mention
          users: ["YOUR_USER_ID"],     // 只允许你自己
        },
      },
    },
  },
}

Step 5：写最简 SOUL.md

## Personality
你是一个全能 AI 助手，风格简洁务实。

## Tone
- 直接回答问题，不说废话
- 技术讨论用代码说话
- 遇到不确定的事情主动询问

## Boundaries
- 不执行危险操作（删除文件、force push 等）除非明确确认
- 不编造不确定的信息

Step 6：启动 Gateway

openclaw gateway

Step 7：配对

在 Discord 中给你的 Bot 发一条私信。Bot 会回复一个配对码（pairing code），用以下命令批准：

openclaw pairing list discord
openclaw pairing approve discord <配对码>

配对码 1 小时内有效。批准后，你的虾塘正式开张了——在 Discord 里跟你的 Agent 聊天吧。

避坑清单

坑	后果	解法
Token 明文写在 openclaw.json 里	泄露风险	用 `${ENV_VAR}` 环境变量替换
跨 Agent 复用 agentDir	认证冲突、session 错乱	每个 Agent 独立的 `agents/<id>/`
把 workspace 当硬沙箱	绝对路径仍可访问宿主机	需要隔离时显式开启 sandbox
SOUL.md 写太长	超出 bootstrapMaxChars 被截断	保持精炼，控制在 20,000 字符内
忘了备份 workspace	配置丢失从头来	用 Git 管理 workspace，推到私有仓库
BOOTSTRAP.md 没删	每次启动都执行初始化仪式	仪式完成后删除该文件

回顾一下

我们从 openclaw init 开始，逐一认识了虾塘的每个角落——中控台（openclaw.json）、虾的房间（workspace）、档案柜（agents）、共享技能库（skills）、凭证保险柜（credentials），最后用一个最小配置把虾塘跑了起来。

.openclaw 的设计哲学可以概括为三个词：渐进式（先简后繁）、可扩展（从单 Agent 到多 Agent）、安全第一（环境变量隔离、沙箱、权限控制）。

如果你想动手试试，打开终端，一条 openclaw init 就能开始。5 分钟挖好虾塘，剩下的事情我们后续慢慢聊。

海狸养虾记，持续更新中。关注海狸实验室，一起养虾。

发布于: 2026年4月5日 · 修改于: 2026年4月7日

AI 智能体

读懂 .openclaw，搭好你的虾塘

养虾先挖塘

虾塘全景图

openclaw.json — 虾塘的中控台

格式：JSON5

热重载

配置结构总览

环境变量

配置优先级

workspace/ — 虾的房间

Workspace 里住着谁？

SOUL.md — Agent 的人格基因

AGENTS.md — Agent 的工作手册

USER.md — 你是谁

TOOLS.md — 工具使用笔记

IDENTITY.md — Agent 的名片

MEMORY.md — 长期记忆

HEARTBEAT.md — 定期体检清单

BOOTSTRAP.md 和 BOOT.md

memory/ — 每日原始日志

skills/ — Agent 专属技能

Bootstrap 文件的尺寸限制

agents/ — 虾的档案柜

目录结构

agent/ — 认证与配置

sessions/ — 对话历史

skills/ — 共享技能库

技能加载优先级

怎么选放哪里？

credentials/ — 凭证保险柜

sandboxes/ — 隔离池

沙箱模式

Workspace 访问级别（沙箱内）

.env — 全局环境变量

一只虾起步：最小可运行配置

Step 1：安装并初始化

Step 2：创建 Discord Bot

Step 3：安全地配置 Bot Token

Step 4：添加服务器白名单

Step 5：写最简 SOUL.md

Step 6：启动 Gateway

Step 7：配对

避坑清单

回顾一下

相关文章

为了防止龙虾暴毙，海狸们给 AI 助手搓了个备份工具

我在AI Agent世界里摸索了三个月，直到看到这五种模式