本研究旨在深入对比两款 AI 编程/助手工具——OpenClaw（原名 Clawdbot/Moltbot，跨平台个人 AI 助手，昵称"龙虾"🦞）与 OpenCode（开源终端 AI 编程 Agent）的文件结构与配置系统，帮助用户理解如何手动添加记忆、背景资料和自定义配置。

🦞 第一部分：OpenClaw 文件结构详解

1.1 产品定位与核心特点

OpenClaw（原名 Clawdbot → Moltbot → OpenClaw）是一款隐私优先的个人 AI 助手，可以在你自己的设备上运行，并通过你已经使用的渠道与你交互：

📱 支持渠道：WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat、Matrix、Zalo、BlueBubbles 等

名称变更历史：

核心设计理念：

• 🔒 隐私优先：数据存储在本地，无需云端
• 📄 记忆即 Markdown：所有记忆都是纯文本文件，可版本控制
• 🔌 插件化架构：通过 Skills 和 Plugins 扩展功能
• 🌐 多渠道统一：一个 AI，多个聊天入口
• 🧠 持久记忆：不像其他工具每次会话都从空白开始，OpenClaw 保存文件、面包屑和聊天历史，支持跨越数小时甚至数天的任务

项目热度：根据 Wikipedia，OpenClaw 在 GitHub 上已获得 超过 145,000 颗星 和 20,000+ forks，是 2026 年增长最快的开源项目之一。

1.2 📁 整体目录结构

OpenClaw 采用双目录分离设计：工作区（Workspace）存放"大脑内容"，状态目录存放"运行数据"。

┌─────────────────────────────────────────────────────────────────┐
│                    OpenClaw 目录架构                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ~/workspace/                ← 🧠 Agent 工作区（可版本控制）     │
│  ├── AGENTS.md              ← 操作指令/行为规范                  │
│  ├── SOUL.md                ← 人格定义/语气风格（内部良知）       │
│  ├── IDENTITY.md            ← 身份信息（外部形象）               │
│  ├── USER.md                ← 关于用户的知识                     │
│  ├── MEMORY.md              ← 长期核心记忆                       │
│  ├── TOOLS.md               ← 工具使用说明                       │
│  ├── HEARTBEAT.md           ← 定时任务清单（可选）               │
│  ├── memory/                ← 📅 每日记忆日志                    │
│  │   ├── 2026-01-25.md                                         │
│  │   ├── 2026-01-26.md                                         │
│  │   └── ...                                                   │
│  └── skills/                ← 🛠️ 工作区级技能                   │
│      └── my-skill/                                             │
│          └── SKILL.md                                          │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ~/.openclaw/               ← ⚙️ 状态目录（系统数据）            │
│  ├── openclaw.json          ← 主配置文件                        │
│  ├── credentials/           ← 🔑 认证凭据                       │
│  │   ├── oauth.json                                            │
│  │   └── whatsapp/                                             │
│  │       └── default/                                          │
│  │           └── creds.json                                    │
│  ├── agents/                ← 🤖 Agent 配置与会话                │
│  │   └── main/                                                 │
│  │       ├── agent/                                            │
│  │       │   └── auth-profiles.json                            │
│  │       └── sessions/      ← 💬 聊天历史                       │
│  │           └── session-xxx.json                              │
│  ├── memory/                ← 🔍 向量索引数据库                  │
│  │   └── <agentId>.sqlite                                      │
│  ├── skills/                ← 🛠️ 全局共享技能                   │
│  │   └── shared-skill/                                         │
│  │       └── SKILL.md                                          │
│  └── plugins/               ← 🔌 已安装插件                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

⚠️ v2026.1.29 更新说明：配置目录已从 ~/.clawdbot/ 迁移至 ~/.openclaw/，旧路径会自动迁移。

1.3 🧠 记忆文件系统详解

OpenClaw 的核心设计哲学是：记忆 = 纯 Markdown 文件。没有数据库，没有私有格式，没有供应商锁定。

核心记忆文件一览

💡 SOUL.md vs IDENTITY.md 的区别：

• SOUL.md 定义你的 AI 是谁——它的价值观、行为准则（内部良知）
• IDENTITY.md 定义世界如何体验它——名字、emoji、语气风格（外部形象）

每日记忆日志：memory/YYYY-MM-DD.md

这是追加式的每日流水账，记录当天发生的一切：

# 2026-02-03

## 上午
- 用户询问了关于 React 性能优化的问题
- 建议使用 useMemo 和 React.memo

## 下午
- 帮用户预订了周五晚上 7 点的餐厅
- 餐厅：望京小腰，6 人位

## 决策记录
- 用户确认以后所有代码示例都用 TypeScript

MEMORY.md vs memory/YYYY-MM-DD.md 的区别

1.4 📝 手动添加记忆的方法

方法一：直接编辑 Markdown 文件

# 添加长期偏好
echo "- 代码示例优先使用 Python" >> ~/workspace/MEMORY.md

# 修改人格
nano ~/workspace/SOUL.md

# 添加操作指令
echo "- 每次回复结尾加一个表情" >> ~/workspace/AGENTS.md

方法二：通过对话让 Agent 自己写入

在任意渠道（WhatsApp/Telegram 等）对 OpenClaw 说：

"请记住：我更喜欢简洁的回复，不需要太多解释。把这个写到 MEMORY.md 里。"

Agent 会自动将这条偏好写入 MEMORY.md。

方法三：使用 CLI 命令

# 进入 OpenClaw CLI
openclaw

# 使用 memory 相关命令
openclaw memory list
openclaw memory status
openclaw memory search "用户偏好"
openclaw memory index  # 重建向量索引

1.5 🔍 向量搜索与语义记忆

OpenClaw 会为 MEMORY.md 和 memory/*.md 建立向量索引，支持语义搜索：

配置位置： ~/.openclaw/openclaw.json

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "local",
        "local": {
          "modelPath": "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf"
        }
      }
    }
  }
}

索引存储位置： ~/.openclaw/memory/<agentId>.sqlite

memory_search 工具特性（根据 官方文档）：

• 对 Markdown 块进行语义搜索（目标约 400 token，80 token 重叠）
• 搜索范围：MEMORY.md + memory/**/*.md
• 返回内容：片段文本（上限约 700 字符）、文件路径、行范围、分数
• 支持本地 → 远程嵌入的回退机制

1.6 🛠️ Skills 系统

Skills 是可复用的工具使用指南，教 Agent 如何使用特定工具。

Skills 加载优先级（高→低）：

1. ~/workspace/skills/ — 工作区级（仅当前 Agent）
2. ~/.openclaw/skills/ — 全局共享（所有 Agent）
3. 内置 Skills — 随安装包提供

Skill 文件结构：

my-calendar-skill/
├── SKILL.md           # 必需：YAML frontmatter + 指令
├── scripts/           # 可执行脚本
├── references/        # 参考文档
└── assets/            # 输出资源

SKILL.md 示例：

---
name: calendar-manager
# ⚠️ 用引号包裹描述，避免 YAML 解析错误
description: "管理 Google 日历的技能"
tools:
  - gcal-create
  - gcal-list
  - gcal-update
---

# 日历管理技能

## 使用指南
1. 创建事件时，确认用户时区
2. 邀请他人前先询问确认
3. 默认提前 30 分钟提醒

## 常见场景
- 用户说"约会议"→ 使用 gcal-create
- 用户说"看看日程"→ 使用 gcal-list

1.7 ⚙️ 主配置文件 openclaw.json

位置： ~/.openclaw/openclaw.json

完整配置示例：

{
  "agent": {
    "model": "anthropic/claude-sonnet-4",
    "workspace": "~/workspace",
    "temperature": 0.7
  },
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    },
    "openai": {
      "apiKey": "sk-..."
    }
  },
  "gateway": {
    "bind": "lan",
    "port": 18789,
    "controlUi": {
      "allowInsecureAuth": true
    }
  },
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "local"
      },
      "sandbox": {
        "mode": "all"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "xxx"
    },
    "whatsapp": {
      "enabled": true
    }
  }
}

🖥️ 第二部分：OpenCode 文件结构详解

2.1 产品定位与核心特点

OpenCode 是一款开源的终端 AI 编程 Agent，专注于代码开发场景，提供 TUI（终端用户界面）体验。

核心特点：

• 🔓 完全开源：GitHub 60,000+ Stars，650,000+ 月活用户
• 🤖 多模型支持：Claude、GPT-4、Gemini、Ollama 等本地模型
• 💻 Terminal-First：Vim/Neovim 用户友好，由 neovim 用户和 terminal.shop 创建者开发
• 🧩 兼容 Claude Code：支持 CLAUDE.md 作为 fallback
• 🐙 GitHub 集成：可在 GitHub issue 中 @opencode 触发任务

项目热度：根据 GitHub，OpenCode 已获得 60,000+ 颗星，并与 GitHub 建立了官方合作关系。

2.2 📁 整体目录结构

┌─────────────────────────────────────────────────────────────────┐
│                     OpenCode 目录架构                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  your-project/              ← 📂 项目目录                        │
│  ├── opencode.json          ← ⚙️ 项目配置（或 opencode.jsonc）   │
│  ├── AGENTS.md              ← 🧠 项目规则/记忆                   │
│  └── .opencode/             ← 📁 项目扩展目录                    │
│      ├── agents/            ← 🤖 自定义 Agent（复数形式）        │
│      │   ├── reviewer.md                                       │
│      │   └── tasks/                                            │
│      │       └── research.md                                   │
│      ├── commands/          ← ⌨️ 自定义命令                     │
│      │   ├── deploy.md                                         │
│      │   └── test.md                                           │
│      ├── skills/            ← 💡 项目级技能                      │
│      │   └── react-patterns/                                   │
│      │       └── SKILL.md                                      │
│      ├── plugins/           ← 🔌 项目级插件                      │
│      │   └── custom-tool.ts                                    │
│      ├── modes/             ← 🎭 自定义模式                      │
│      ├── tools/             ← 🔧 自定义工具                      │
│      └── themes/            ← 🎨 自定义主题                      │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ~/.config/opencode/        ← ⚙️ 全局配置目录                    │
│  ├── opencode.json          ← 全局配置                          │
│  ├── AGENTS.md              ← 🌍 全局规则（跨项目）              │
│  ├── agents/                ← 🤖 全局 Agent                     │
│  ├── commands/              ← ⌨️ 全局命令                       │
│  ├── skills/                ← 💡 全局技能                        │
│  ├── plugins/               ← 🔌 全局插件                        │
│  ├── modes/                 ← 🎭 全局模式                        │
│  ├── tools/                 ← 🔧 全局工具                        │
│  └── themes/                ← 🎨 全局主题                        │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ~/.local/share/opencode/   ← 💾 数据存储目录                    │
│  ├── opencode.db            ← SQLite 数据库（会话、消息）        │
│  └── session/               ← 会话数据                          │
│      └── <project-id>/                                         │
│          └── session-1.json                                    │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ~/.cache/opencode/         ← 📦 缓存目录                        │
│  └── node_modules/          ← npm 插件缓存                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

💡 目录命名说明：.opencode 和 ~/.config/opencode 目录使用复数形式的子目录名（agents/、commands/、modes/、plugins/、skills/、tools/、themes/）。单数形式也支持，但推荐使用复数。

2.3 🧠 规则/记忆文件：AGENTS.md

AGENTS.md 是 OpenCode 的核心规则文件，类似于 Cursor 的 rules。

文件查找优先级

⚠️ 重要：如果同一目录下同时存在 AGENTS.md 和 CLAUDE.md，只有 AGENTS.md 会被加载。

AGENTS.md 示例

# 项目概述
这是一个使用 Go + gRPC 的微服务项目。

# 技术栈
- 语言：Go 1.22
- 框架：Gin + gRPC
- 数据库：PostgreSQL + Redis
- 部署：Kubernetes

# 编码规范
- 遵循 Effective Go
- 错误处理使用 errors.Wrap
- 所有导出函数必须有注释

# 目录结构
cmd/           # 入口程序
internal/      # 内部包
pkg/           # 可复用包
api/           # Proto 定义

# 常用命令
- make test    # 运行测试
- make build   # 构建二进制
- make proto   # 生成 protobuf

2.4 📝 手动添加规则的方法

方法一：直接创建/编辑文件

# 创建项目级规则
touch AGENTS.md
nano AGENTS.md

# 创建全局规则
mkdir -p ~/.config/opencode
touch ~/.config/opencode/AGENTS.md

方法二：使用 /init 命令

opencode
> /init

OpenCode 会扫描项目并自动生成 AGENTS.md。

方法三：在配置中引用外部文件

opencode.json：

{
  "instructions": [
    "./docs/architecture.md",
    "./docs/coding-standards.md",
    "packages/*/AGENTS.md"
  ]
}

这允许复用已有的文档作为规则来源。

2.5 🤖 自定义 Agent

Agent 定义文件放在 .opencode/agents/ 目录下。

文件命名规则：

• .opencode/agents/reviewer.md → Agent 名称：reviewer
• .opencode/agents/tasks/research.md → Agent 名称：tasks/research

Agent 定义示例（.opencode/agents/code-reviewer.md）：

---
description: 代码审查专家，专注于质量和安全
model: claude-sonnet-4
temperature: 0.3
maxTokens: 8192
tools:
  - Read
  - Grep
  - Glob
---

你是一位经验丰富的代码审查专家。

## 审查重点
1. 代码可读性和可维护性
2. 潜在的性能问题
3. 安全漏洞
4. 测试覆盖率

## 输出格式
- 🔴 严重问题
- 🟡 建议改进
- 🟢 良好实践

2.6 💡 Skills 系统

根据 OpenCode Skills 文档，Skills 让 Agent 按需加载可复用的指令。

Skills 加载路径（优先级从低到高）：

1. ~/.opencode/skills/ — 全局级（最低）
2. ./.opencode/skills/ — 项目级（最高）

💡 优先级说明：同名 Skill 存在于两个位置时，项目级版本胜出。

Skill 目录结构

react-patterns/
├── SKILL.md           # 必需
├── scripts/           # 可执行脚本
├── references/        # 参考文档
└── assets/            # 资源文件

SKILL.md 格式要求

根据官方文档，SKILL.md 必须包含 YAML frontmatter：

• name：必须与目录名匹配
• description：最少 20 个字符
• 可选字段：license、allowed-tools、metadata

知名 Skills 插件

根据 GitHub 社区：

1. opencode-skillful — Anthropic Agent Skills 规范的 OpenCode 实现，支持懒加载 Skill 发现和注入
2. opencode-agent-skills — 提供 Skill 使用工具的 OpenCode 插件
3. Superpowers — 自动设置 Skills，无需修改 AGENTS.md

2.7 ⚙️ 配置文件 opencode.json

根据 OpenCode Config 文档，完整配置示例：

{
  "$schema": "https://opencode.ai/config.json",

  // 主题配置
  "theme": "opencode",

  // 模型配置
  "provider": "anthropic",
  "model": "claude-sonnet-4",

  // Agent 配置
  "agents": {
    "coder": {
      "model": "claude-sonnet-4",
      "maxTokens": 8192,
      "temperature": 0
    },
    "researcher": {
      "model": "gemini-2.5-flash",
      "maxTokens": 16000
    }
  },

  // 外部规则引用
  "instructions": [
    "./docs/standards.md"
  ],

  // MCP 服务器
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  },

  // 权限
  "permissions": {
    "autoApprove": ["Read", "Glob", "Grep"]
  },

  // 快捷键（部分）
  "keybinds": {
    "leader": "ctrl+x",
    "app_exit": "ctrl+c,ctrl+d,<leader>q",
    "session_new": "<leader>n",
    "model_list": "<leader>m",
    "agent_list": "<leader>a"
  },

  // 自动更新
  "autoupdate": true
}

2.8 🎹 快捷键系统

OpenCode 提供丰富的 Vim 风格快捷键（根据配置 schema）：

💡 默认 Leader 键为 ctrl+x

⚖️ 第三部分：对比分析

3.1 📊 核心定位对比

3.2 📁 文件结构对比

3.3 🧠 记忆系统对比

┌─────────────────────────────────────────────────────────────────────┐
│                         记忆系统对比                                 │
├───────────────────────────────┬─────────────────────────────────────┤
│        OpenClaw 🦞            │              OpenCode               │
├───────────────────────────────┼─────────────────────────────────────┤
│ 📜 AGENTS.md — 操作指令       │ 📜 AGENTS.md — 项目规则             │
│ 👻 SOUL.md — 人格/语气        │ ❌ 无独立人格文件                    │
│ 🪪 IDENTITY.md — 身份信息     │ ❌ 无独立身份文件                    │
│ 👤 USER.md — 用户知识         │ ❌ 无独立用户文件                    │
│ 🧠 MEMORY.md — 长期核心记忆   │ ❌ 无独立记忆文件                    │
│ 📅 memory/YYYY-MM-DD.md      │ ❌ 无每日日志                        │
│    — 每日流水账               │                                     │
│ 🔍 向量语义搜索               │ ❌ 无内置向量搜索                    │
│    (memory_search 工具)       │    (需插件扩展)                     │
├───────────────────────────────┼─────────────────────────────────────┤
│ 💡 设计哲学：全方位人格化助手  │ 💡 设计哲学：轻量编程工具            │
└───────────────────────────────┴─────────────────────────────────────┘

3.4 🎯 手动添加记忆/规则的操作对比

OpenClaw 🦞

# 1. 添加长期记忆
echo "- 用户喜欢早起" >> ~/workspace/MEMORY.md

# 2. 修改人格
echo "保持幽默风趣，像老朋友一样聊天" >> ~/workspace/SOUL.md

# 3. 添加操作规则
echo "- 回复使用简体中文" >> ~/workspace/AGENTS.md

# 4. 添加用户信息
echo "- 用户是一名 Python 开发者" >> ~/workspace/USER.md

# 5. 通过对话自动写入
# 对 Agent 说："请记住我喜欢咖啡，写到 MEMORY.md"

# 6. 使用 CLI 命令
openclaw memory status
openclaw memory search "偏好"

OpenCode

# 1. 添加项目规则
echo "- 使用 TypeScript 编写代码" >> ./AGENTS.md

# 2. 添加全局规则
echo "- 所有注释使用英文" >> ~/.config/opencode/AGENTS.md

# 3. 引用外部规则（opencode.json）
{
  "instructions": ["./docs/coding-standards.md"]
}

# 4. 使用 /init 自动生成
opencode
> /init

3.5 🔧 适用场景对比

3.6 🔐 安全性对比

根据 SafePasswordGenerator 的分析：

⚠️ 安全建议：OpenClaw 更适合有安全意识的高级用户。如果主要用于编程任务且担心安全问题，OpenCode 是更轻量的选择。

📚 第四部分：实践建议

4.1 🦞 OpenClaw 记忆管理最佳实践

1. 分层管理记忆
   • MEMORY.md：存放精炼的长期知识
   • memory/YYYY-MM-DD.md：让 Agent 自动记录每日细节
   • 定期整理：将每日日志中的重要内容提炼到 MEMORY.md
2. 善用人格文件
   • SOUL.md：定义 Agent 的说话风格（内部良知）
   • IDENTITY.md：给 Agent 一个名字和身份（外部形象）
   • 这两个文件让你的助手更有"人味儿"

3. 版本控制工作区

   cd ~/workspace
   git init
   git add AGENTS.md SOUL.md MEMORY.md
   git commit -m "Initial workspace setup"

4. 启用安全配置

   {
     "agents": {
       "defaults": {
         "sandbox": {
           "mode": "all"
         }
       }
     }
   }

4.2 🖥️ OpenCode 规则管理最佳实践

1. 项目级 vs 全局级分离
   • ./AGENTS.md：项目特定规则
   • ~/.config/opencode/AGENTS.md：个人通用偏好

2. 复用已有文档

   {
     "instructions": [
       "./README.md",
       "./docs/CONTRIBUTING.md"
     ]
   }

3. 善用 Claude Code 兼容性
   • 如果团队同时使用 Claude Code 和 OpenCode
   • 可以共用 CLAUDE.md，OpenCode 会自动识别
4. 利用插件扩展记忆能力
   • 安装 opencode-agent-memory 插件
   • 实现类似 OpenClaw 的持久记忆功能

4.3 🤝 同时使用两者

根据 对比分析：

"高效的工程师会同时运行两个工具，不是作为替代品，而是作为互补的自动化层。问题不在于哪个更好，而在于何时使用哪个。"

• OpenClaw：用于消息平台上的日常任务、持久记忆、跨天工作流
• OpenCode：用于终端中的编程任务、代码审查、项目开发

📚 参考资源

OpenClaw 官方资源

• OpenClaw 官方网站
• OpenClaw Memory 文档
• OpenClaw Skills 文档
• OpenClaw GitHub（145k+ ⭐）
• OpenClaw Wikipedia

OpenCode 官方资源

• OpenCode 官方文档
• OpenCode Config 配置
• OpenCode Rules 规则
• OpenCode Agents 自定义
• OpenCode Skills 技能
• OpenCode GitHub（60k+ ⭐）

社区资源

• Awesome OpenClaw Skills
• oh-my-opencode — 多模型 Agent 编排插件
• Superpowers for OpenCode
• opencode-skillful — 懒加载 Skills 插件

📝 总结表

🎯 选择建议

• 需要跨平台全能助手（聊天 + 任务管理 + 持久记忆）→ OpenClaw 🦞
• 需要轻量终端编程工具（专注代码开发）→ OpenCode
• 两者都需要？可以同时使用！OpenClaw 处理日常任务，OpenCode 专注编程。