OpenClaw 配置体系全解析:从 JSON 到 MD,让 AI 真正懂你

OpenClaw 的配置分两层：JSON 文件管"系统能做什么"，MD 文件管"AI 是谁"。两层配合，才能让 AI 既连得上、又懂你心。本文从零开始，带你搭建一套完整的配置体系。

很多人第一次用 OpenClaw，容易走两个极端：要么只配 JSON，AI 能跑但不知道你是谁；要么只改 MD 文件，AI 认识你了但连不上消息渠道。这两个其实是整体——JSON 是"骨架"，MD 是"血肉"。

🏗️ 配置体系总览

OpenClaw 的配置文件分布在两个位置：

两层配置的协作关系：

┌─────────────────────────────────────────────────────┐
│                  OpenClaw 配置体系                    │
├─────────────────────────────────────────────────────┤
│                                                     │
│  系统层 (JSON)              人格层 (MD)              │
│  ────────────              ────────────             │
│  • channels (消息渠道)      • IDENTITY.md (身份)     │
│  • models (模型配置)        • USER.md (用户档案)     │
│  • agents (Agent定义)       • SOUL.md (语气边界)     │
│  • gateway (网关设置)       • AGENTS.md (行为规则)   │
│  • cron (定时任务)          • MEMORY.md (长期记忆)   │
│  • bindings (路由规则)      • memory/ (每日日志)     │
│                            • HEARTBEAT.md (定时)    │
│                            • BOOT.md (启动检查)     │
│                                                     │
│  ↑ 系统层决定"能不能"     ↑ 人格层决定"好不好"       │
│                                                     │
└─────────────────────────────────────────────────────┘

⚙️ 系统层：openclaw.json 配置详解

配置文件基础

文件位置：~/.openclaw/openclaw.json

格式：JSON5（支持注释、尾随逗号）

⚠️ 重要提醒：OpenClaw 对配置很严格，出现未知字段会导致 Gateway 直接拒绝启动。不要从网上乱抄配置，字段名要和官方文档一致。

核心模块一览

Channels：消息渠道配置

channels 决定两件事：接入哪个平台、谁可以来找你。

通用字段速查：

DM Policy（私聊策略）选择：

Telegram 配置示例：

{
  "channels": {
    "telegram": {
      "botToken": "123456:ABC...",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      },
      "streaming": "partial"
    }
  }
}

关键点：requireMention: true 表示群聊中必须 @ 机器人才会响应，避免刷屏。

Models：模型配置

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}",
        "models": ["gpt-4o", "gpt-4o-mini"]
      },
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}",
        "models": ["claude-sonnet-4-20250514"]
      }
    }
  }
}

技巧：API Key 通过 ${环境变量名} 引用，不要硬编码。在 env 模块或系统环境变量中设置。

Bindings：路由配置

当你有多个渠道或多个 Agent 时，需要用 bindings 指定路由：

{
  "bindings": [
    {
      "channel": "telegram",
      "agent": "default"
    },
    {
      "channel": "discord",
      "account": "work-bot",
      "agent": "work-assistant"
    }
  ]
}

逻辑：某渠道/账号的消息 → 路由到某 Agent。

🧠 人格层：8 个 MD 文件配置详解

如果说 JSON 是让 AI"连得上"，MD 文件就是让 AI"懂你心"。8 个文件各司其职：

配置文件清单

IDENTITY.md：AI 的身份证

这是 OpenClaw 初始化时第一个创建的文件，告诉 AI：你是谁、叫什么、什么风格。

# IDENTITY
Name: 小虾
Role: 个人AI助理
Vibe: 高效、冷静、务实，偶尔有点幽默
Emoji: 🦞

配置要点：

• • Name：AI 在对话中对自己的称呼
• • Role：身份定位，决定处理问题的角度
• • Vibe：风格描述，影响措辞习惯

USER.md：你在 AI 眼里的档案

这是最容易被忽略、却最重要的文件。把你的背景、职业、习惯、目标全部写进去——相当于给 AI 发一张你的"员工卡"。

# USER
Name: 张明
Role: 互联网产品经理
Experience: 5年，B端后台方向
Language: 中文，书面表达偏简洁
Tools: 飞书文档、墨刀原型、Jira、Notion
Preferences: 优先用要点列表回复，不要纯文字段落
Goal: 当前正在准备B端产品面试，主攻SaaS方向

配置要点：

• • Preferences 最重要，决定 AI 给你结果的呈现形式
• • Goal 每 1-2 个月更新一次，保持同步
• • 不要写太多条，抓住最重要的 3-4 条

SOUL.md：AI 的语气和边界

定义 AI 怎么说话、什么能说、什么不能说。配置好后，无论谁在什么时间发起对话，AI 的风格都是一致的。

# SOUL
## 语气
- 简洁，不废话，直接给结论
- 专业但不说教，用类比解释复杂概念
- 适当幽默，但不在严肃话题上开玩笑

## 边界
- 不提供法律、医疗、金融投资建议
- 不承诺具体的价格或交付时间
- 遇到不确定的问题，直接说"我不确定"，不瞎编

## 格式规则
- 回答以结论开头，再展开说明
- 使用表格呈现对比信息，列表呈现步骤

关键点：SOUL 是"怎么说"，AGENTS 是"做什么"，两者互补。

AGENTS.md：AI 的操作手册

规定 AI 在你这个工作流里的角色定位、优先级判断、关键操作的行为规则。

# AGENTS
## 角色定位
你是张明的个人AI助理，负责：
- 起草和润色工作文档（周报、PRD、用户故事）
- 整理和归纳会议记录、邮件内容
- 解答工作相关的专业知识问题

## 优先级
1. 准确性 > 速度（宁可慢5分钟，也要保证信息正确）
2. 用户时间 > AI 完美性（给出80分答案比等20分钟更好）
3. 主动提问 > 被动回答（发现信息缺失时先问清楚）

## 操作规则
- 起草对外邮件前，先展示草稿，等用户确认再发送
- 涉及时间、数字等关键信息时，在回答末尾标注"请核实"

关键点：草稿确认那条最重要——防止 AI 擅自行动。

HEARTBEAT.md：定时自动执行

这是 OpenClaw 最强大的功能之一。设定每隔 N 分钟/小时，AI 自动启动，按清单执行任务——不需要你发消息。

# HEARTBEAT
频率：每4小时自动执行一次

## 检查清单
1. 检查过去4小时的新邮件
   → 识别需要回复的邮件，起草回复草稿，写入草稿箱
2. 检查飞书未读消息
   → 整理 Top 3 重要消息，生成一句话摘要
3. 更新每日记忆
   → 将今天的待办和决策追加到 memory/YYYY-MM-DD.md

安全设计：HEARTBEAT 不能直接发送消息，只能起草。避免 AI 自动发送错误内容。

MEMORY.md 与 memory/：记忆系统

MEMORY.md 示例：

# MEMORY
## 业务知识
- 产品定位：面向制造业的SaaS订单管理系统
- 目标用户：制造企业生产管理人员

## 个人偏好记录
- 回复用户消息时，不要用"当然可以"开头
- 周报格式：先用三句话总结，再列要点列表

memory/YYYY-MM-DD.md 示例：

# 2026-04-18 工作日志
## 今日决策
- 决定把订单模块优先级从 P1 降到 P2

## 待办事项
- [ ] 跟进客户反馈（截止：周五）
- [x] 给供应商发送确认邮件

🔧 配置顺序与调试技巧

推荐配置顺序

第一步：系统层（JSON）
├── 1. models（必填，配置模型和 API Key）
├── 2. agents（必填，定义 Agent）
├── 3. channels（建议，接入消息渠道）
├── 4. bindings（多渠道时必填）
└── 5. gateway / cron（可选）

第二步：人格层（MD）
├── 1. IDENTITY.md（必填，定义 AI 身份）
├── 2. USER.md（必填，定义你的信息）
├── 3. SOUL.md（必填，定义语气边界）
├── 4. AGENTS.md（必填，定义行为规则）
└── 5. HEARTBEAT.md / MEMORY.md（进阶）

常见启动失败排查

配置生效时机

技巧：修改 MD 文件后，下次对话自动生效。修改 JSON 文件后，需要重启 Gateway。

📊 快速模板：复制即用

最小化 JSON 配置

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}",
        "models": ["gpt-4o-mini"]
      }
    }
  },
  "agents": {
    "default": {
      "model": "gpt-4o-mini"
    }
  },
  "channels": {
    "telegram": {
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "pairing"
    }
  },
  "env": {
    "OPENAI_API_KEY": "sk-xxx",
    "TELEGRAM_BOT_TOKEN": "123456:ABC..."
  }
}

最小化 MD 配置

IDENTITY.md：

Name: 小助手
Role: 个人AI助理
Vibe: 简洁、高效、友好

USER.md：

Name: [你的名字]
Role: [你的职位]
Goal: [当前最重要的目标]
Preferences: [回复格式偏好]

SOUL.md：

## 语气
- 简洁回复，不废话

## 边界
- 不确定的事情直接说"我不确定"

💡 总结

OpenClaw 的配置体系分两层：JSON 管"系统能做什么"，MD 管"AI 是谁"。

配置优先级：先配 JSON 让系统能跑，再配 MD 让 AI 懂你。USER.md 是最容易被忽略但最重要的文件——它会直接影响 AI 给你的每一次回复。

新手建议：从最小化配置开始，逐步添加模块。不要一次性把所有字段都配满，容易出错且难以排查。