OpenClaw 用户必修课：Claude Code 配置系统详解

作为 OpenClaw 的用户，你可能已经发现 OpenClaw 很多设计理念来自 Claude Code。本文将带你深入了解 Claude Code 的配置系统，这既是它的"第一课"，也是理解 OpenClaw 很多设计来源的关键。

---

前言：为什么 OpenClaw 用户需要学 Claude Code？

OpenClaw 在设计时借鉴了很多 Claude Code 的理念，特别是记忆系统这一块。某种程度上，你可以把理解 Claude Code 配置系统当作理解 OpenClaw 内在逻辑的一把钥匙。

剧透：你正在使用的 MEMORY.md、SOUL.md、USER.md、memory/YYYY-MM-DD.md 这些文件体系，最初就来自 Claude Code 社区的最佳实践。

---

一、Claude Code 配置体系全景

Claude Code 的配置系统可以理解成三层架构：

┌─────────────────────────────────────────┐
│  记忆层：Markdown 文件（CLAUDE.md 等）  │  ← 决定"怎么思考"
├─────────────────────────────────────────┤
│  设置层：JSON / 环境变量                │  ← 决定"怎么运行"
├─────────────────────────────────────────┤
│  技能层：Skills / MCP                  │  ← 决定"能做什么"
└─────────────────────────────────────────┘

真正决定"手感"的主要是记忆层，这也是本文的重点。

---

二、记忆层：CLAUDE.md 体系

2.1 CLAUDE.md 是什么？

CLAUDE.md 是 Claude Code 的核心"记忆文件"。当你进入一个目录工作时，Claude Code 会自动读取这个文件，把它当成比普通对话更"硬"的规则。

官方文档定义：

• 是一个项目配置/上下文文件
• 会被自动读取，当成项目的"系统提示"
• 可以多层叠加（项目级 + 全局级）

2.2 记忆层级结构

Claude Code 按特定顺序查找和加载这些文件：

级别	位置	作用域	典型用途
Enterprise	/etc/claude-code/CLAUDE.md	全组织	企业级安全策略
Global	~/.claude/CLAUDE.md	全用户	你的个人习惯
Project	./CLAUDE.md	当前项目	项目特有规则
Local	./CLAUDE.local.md	本机	个人覆盖，不进 Git

加载顺序：从当前目录往上递归查找，合并所有找到的 CLAUDE.md

💡 Monorepo 提示：可以在根目录和子包分别放 CLAUDE.md，形成分层规则。

2.3 CLAUDE.md 应该写什么？

根据官方和社区实践，推荐结构如下：

# 项目名称

## 项目简介
这是干什么的，主要业务域

## 目录结构
- src/：源代码
- tests/：测试文件
- docs/：文档

## 构建 & 运行
- 开发：npm run dev
- 构建：pnpm build
- 测试：npm test

## 代码规范
- 使用 TypeScript
- ESLint + Prettier
- 提交前必须通过测试

## 安全边界
- 禁止修改 config/
- 禁止提交 .env 到 git

---

三、社区创新：SOUL / USER / MEMORY 体系

⚠️ 这是本文最核心的部分——OpenClaw 正是借鉴了这套体系！

这不是官方标准，而是中文/英文社区自发形成的最佳实践，目前已经非常成熟。

3.1 核心思想

每次会话前，Claude 按顺序做四件事：

1. 读取 SOUL.md     → "你是谁"（角色定位）
2. 读取 USER.md     → "你在帮助谁"（用户画像）
3. 读取 memory/     → "最近发生了什么"（短期记忆）
4. 读取 MEMORY.md   → "长期记住什么"（长期记忆）

3.2 各文件职责

SOUL.md — “你是谁”

定义 Claude 在这个项目里的角色、价值观、工作风格。

# SOUL.md - 我是谁

- **角色**：严谨的资深后端工程师
- **偏好**：可读性 > 短期速度
- **原则**：
  - 保证测试通过是硬约束
  - 变更前必须先给计划
  - 不确定的地方要主动提问
- **禁区**：不要动 .env 配置

USER.md — “你在帮助谁”

描述用户的背景、技术栈、偏好。

# USER.md - 关于你

- **背景**：全栈开发者，熟悉 React/Node.js
- **偏好**：
  - 喜欢清晰的代码结构
  - 不喜欢过度"魔法"
- **习惯**：每天上午 10 点会来看进度

memory/YYYY-MM-DD.md — 短期记忆

记录最近一两天的重要决策和上下文。

# 2026-03-12

## 项目启动
- 决定用 React 18 + TypeScript
- 选型讨论结论：Next.js 太重，用 Vite

## 下午会议
- 确认了 UI 库用 Ant Design
- 下周任务：完成登录模块

MEMORY.md — 长期记忆

记录项目长期的约定、踩过的坑、关键决策。

# MEMORY.md - 长期记忆

## 技术选型
- 状态管理：用 Zustand（比 Redux 轻量）
- HTTP 客户端：Axios（有拦截器需求）

## 踩坑记录
- ⚠️ ESLint 和 Prettier 冲突：统一用 Prettier 格式化
- ⚠️ Node 版本：必须用 18+，16 跑不起来

3.3 为什么要这样分层？

问题	传统方式	SOUL 体系
每次都要重新解释"你是谁"	✅ 不用	❌ 要
长期约定怎么保留	❌ 记不住	✅ MEMORY.md
项目切换要重新配置	❌ 很麻烦	✅ 全局 + 项目分层

---

四、设置层：JSON 配置（简单了解）

在"记忆文件"之外，还有一层是JSON 设置文件：

# 查看当前配置
claude config list

# 设置默认模型
claude config set preferredModel claude-sonnet-4-6

# 设置主题
claude config set theme dark

常用配置项：

• preferredModel：默认模型
• autoUpdate：是否自动更新
• logLevel：日志级别

💡 这层对"手感"影响主要是默认模型选择和工具权限边界，初学者先把 CLAUDE.md 体系做好就够了。

---

五、实操：第一课该怎么做？

第一步：创建你的全局配置

在你的 home 目录创建：

mkdir -p ~/.claude
mkdir -p ~/memory

然后创建以下文件：

• ~/.claude/CLAUDE.md — 全局规则
• ~/SOUL.md — 你是谁
• ~/USER.md — 你在帮助谁
• ~/MEMORY.md — 长期记忆
• ~/memory/YYYY-MM-DD.md — 短期记忆

第二步：让 Claude 帮你写第一版

进入一个项目，运行：

/init

然后加一句：「请用中文生成详细的 CLAUDE.md 项目说明文档」

第三步：对照官方文档优化

参考官方示例：

• Using CLAUDE.md Files

把自动生成的版本优化成结构清晰的小节。

第四步：迭代更新

在日常使用中不断补充：

• 踩过的坑 → 写入 MEMORY.md
• 新决定 → 写入 memory/YYYY-MM-DD.md
• 角色调整 → 更新 SOUL.md

---

六、OpenClaw 与 Claude Code 的对应关系

OpenClaw 文件	Claude Code 对应	说明
MEMORY.md	CLAUDE.md / MEMORY.md	长期记忆
SOUL.md	SOUL.md	角色定义
USER.md	USER.md	用户画像
memory/YYYY-MM-DD.md	memory/YYYY-MM-DD.md	短期记忆
Skills	Skills / SKILL.md	技能系统

🎯 理解了这层对应关系，你就能理解 OpenClaw 很多设计背后的思考。

---

七、推荐资源

1. 官方文档

   • Claude Code 设置说明
   • Using CLAUDE.md Files

2. 中文实践

   • Claude Code 最佳实践 - feisky
   • 一周深度使用 Claude Code 的总结 - CSDN

3. V2EX 讨论

   • SOUL/USER/MEMORY 体系起源

---

总结

• Claude Code 配置体系核心是三层：记忆层 + 设置层 + 技能层
• 记忆层的 Markdown 文件组织决定了使用"手感"
• SOUL/USER/MEMORY 体系是社区成熟实践，OpenClaw 借鉴了这一设计
• 第一步：先建立全局的 CLAUDE.md + SOUL.md + USER.md + MEMORY.md

📢 下节课剧透：我们将学习 MCP 服务器和 Skills 技能系统，这是 Claude Code 扩展能力的核心。

---

附录：CLAUDE.md 工程实践模板

以下是 CLAUDE.md 文件的完整模板，整理自官方文档和社区最佳实践。你可以复制直接使用。

附录：CLAUDE.md 完整模板

A.1 项目级 CLAUDE.md 模板

# 项目名称

## 项目简介
简要描述这个项目是干什么的、主要业务域、目标用户。

## 技术栈
- 前端：React 18 + TypeScript + Vite
- 后端：Node.js 18 + Express
- 数据库：PostgreSQL 15
- 其他：Redis、Nginx

## 目录结构

├── src/                 # 源代码
│   ├── components/      # React 组件
│   ├── pages/           # 页面组件
│   ├── hooks/           # 自定义 Hooks
│   ├── utils/           # 工具函数
│   ├── services/        # API 服务
│   └── stores/          # 状态管理
├── public/              # 静态资源
├── tests/               # 测试文件
├── docs/                # 项目文档
├── scripts/             # 脚本文件
└── config/              # 配置文件


## 构建 & 运行

### 开发环境

npm install
npm run dev


### 生产构建

npm run build


### 测试

npm test              # 运行单元测试
npm run test:e2e      # 运行端到端测试
npm run lint          # 代码检查


## 开发规范

### 代码风格
- 使用 ESLint + Prettier
- TypeScript 严格模式
- 函数式组件 + Hooks

### Git 提交规范
- 提交前运行 `npm run lint` 和 `npm test`
- 使用 Conventional Commits：
  - `feat:` 新功能
  - `fix:` Bug 修复
  - `docs:` 文档更新
  - `refactor:` 重构

### 分支策略
- main：生产分支
- develop：开发分支
- feature/*：功能分支
- bugfix/*：Bug 修复分支

## 测试策略

### 测试目录约定
- 单元测试：`src/**/*.test.ts`
- 组件测试：`src/**/*.test.tsx`
- E2E 测试：`tests/e2e/`

### 覆盖率要求
- 整体覆盖率 > 70%
- 核心业务覆盖率 > 80%

## 安全边界

### 禁止操作
- 禁止修改 `.env` 文件
- 禁止提交 `secrets.json` 到 git
- 禁止直接操作生产数据库

### 敏感文件
- `.env` — 环境变量（本地配置）
- `secrets/` — 密钥目录
- `config/prod.*` — 生产配置

## 常用任务

### 创建新功能
1. 创建分支：`git checkout -b feature/xxx`
2. 开发完成后提交 PR
3. 代码 review 通过后合并

### 运行测试

npm test -- --coverage  # 带覆盖率
npm run test:watch      # 监听模式


### 重构注意
- 确保测试通过后再提交
- 大型重构先提交 plan

A.2 全局 CLAUDE.md 模板

# 全局设置

## 身份认证

### GitHub
- 始终使用 YourUsername
- SSH: git@github.com:YourUsername/<repo>.git

### Docker Hub
用户名：your-docker-hub-username

## 安全规则

### 绝对禁止
1. 永不发布敏感数据到 git/npm/docker
   - 密码、API 密钥、Token
   - 任何形式的凭据文件
   
2. 永不提交 .env 文件
   - 确保 .gitignore 包含 .env
   
3. 提交前必须检查
   - 运行 lint
   - 检查无 secrets

## 代码偏好

### 语言
- TypeScript（优先）
- Python（脚本）

### 工具
- 包管理：pnpm
- 代码检查：ESLint + Prettier
- 测试：Vitest / Jest

### 架构
- 倾向函数式编程
- 优先组合优于继承
- 保持函数短小单一

## 项目模板

### 新项目结构
project/
├── src/
├── tests/
├── docs/
├── scripts/
├── .env
├── .env.example
├── .gitignore
└── README.md


### Node.js 项目额外要求

// 入口文件必须包含
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection:', reason);
  process.exit(1);
});


## 工作流程

### 一般任务
1. 先理解需求
2. 给出实现计划
3. 确认后再执行
4. 完成后验证

### 代码修改
1. 小改：直接提交
2. 大改：先 /plan
3. 重构：确保测试通过

---

A.3 SOUL.md 模板

# SOUL.md - 角色定义

## 角色定位
- **身份**：严谨的资深软件工程师
- **专长**：全栈开发、系统架构、DevOps
- **经验**：5+ 年开发经验

## 决策原则
1. 代码可读性 > 短期速度
2. 测试通过是硬约束
3. 变更前必须先给计划
4. 不确定的地方主动提问

## 工作风格
- 喜欢清晰的结构
- 重视代码注释
- 倾向于渐进式改进
- 重构必须有测试覆盖

## 协作习惯
- 先解释再动手
- 大改前先确认
- 主动汇报进度
- 遇到阻塞及时说

## 禁区
- 不要删除重要日志
- 不要修改生产配置
- 不要跳过测试

## 偏好
- TypeScript > JavaScript
- 显式 > 隐式
- 单元测试 > 集成测试 > E2E

---

A.4 USER.md 模板

# USER.md - 用户画像

## 基本信息
- **名字**：YourName
- **背景**：全栈开发者
- **经验**：3-5 年

## 技术栈
- **前端**：React, Vue, TypeScript
- **后端**：Node.js, Python
- **云**：AWS, Docker, Kubernetes
- **其他**：Git, Linux

## 偏好
- 喜欢：清晰的代码、完善的文档、自动化测试
- 不喜欢：过度"魔法"、黑盒操作、不清晰的错误信息

## 工作习惯
- 每天上午查看项目进度
- 习惯先看文档再动手
- 重视代码 review

## 特殊要求
- 重要决策需要先讨论
- 改动大的时候多确认
- 完成后给总结

---

A.5 MEMORY.md 模板

# MEMORY.md - 长期记忆

## 技术选型

### 状态管理
- **决定**：使用 Zustand
- **原因**：比 Redux 轻量，适合中小项目
- **日期**：2026-01-15

### UI 库
- **决定**：Ant Design Pro
- **原因**：组件丰富，适合后台系统
- **日期**：2026-01-20

## 踩坑记录

### ESLint + Prettier 冲突
- **问题**：保存时格式化和 lint 冲突
- **解决**：统一用 Prettier，关闭 ESLint 格式化
- **日期**：2026-02-01

### Node 版本问题
- **问题**：项目需要 Node 18+，生产环境是 16
- **解决**：升级生产环境到 Node 18
- **日期**：2026-02-10

## 重要约定

### Git 工作流
- feature 分支从 develop 拉
- PR 需要 code review
- 合并后删除分支

### 代码规范
- 函数长度不超过 50 行
- 超过 100 行必须拆分
- 公共方法必须写 JSDoc

---

A.6 使用建议

1. 从简单开始：先用 A.2 全局模板，有项目再加 A.1
2. 渐进完善：A.3-A.5 可以在日常使用中逐步补充
3. 团队共享：项目级 CLAUDE.md 可以进 Git，团队一起维护
4. 定期回顾：每月检查 MEMORY.md，清理过时内容