---

OpenClaw（大龙虾） 系列教程
安装教程

• OpenClaw 云服务器/虚拟机部署安装教程+常见报错与解决方案（2026最新版，保姆级教程）
• OpenClaw 云服务器30秒快速部署（无需远程连接）
• OpenClaw（大龙虾）新手摸透这几个命令，就能解决90%的日常使用问题（干货满满）

---

OpenClaw 接入QQ-Bot + Feishu（飞书）

• OpenClaw 接入QQ-Bot + 接入Feishu（飞书）

---

OpenClaw 切换大模型

• Ubuntu 系统安装 Ollama 教程
• 正在写…

---

OpenClaw 目录详解

• OpenClaw 目录结构详细介绍（出自阿程）
• ~/.openclaw — OpenClaw 的“家目录（出自阿程）“

---

常见报错与解决方案

• OpenClaw 常见报错与解决方案

🏠 ~/.openclaw — OpenClaw 的"家"

这是 OpenClaw 的运行时数据目录，所有配置、状态、会话、记忆都存储在这里。

位置：/home/ubuntu/.openclaw/

---

📂 完整目录结构

~/.openclaw/
│
├── 📄 openclaw.json              # 主配置文件 ⭐
├── 📄 openclaw.json.bak          # 配置备份
├── 📄 openclaw.json.bak.1        # 旧配置备份
├── 📄 update-check.json          # 更新检查状态
│
├── 📁 workspace/                 # Agent 工作区 (你的文件)
│   ├── SOUL.md                   # 人格定义
│   ├── USER.md                   # 用户信息
│   ├── IDENTITY.md               # 身份定义
│   ├── AGENTS.md                 # 工作区指南
│   ├── TOOLS.md                  # 本地工具笔记
│   ├── HEARTBEAT.md              # 心跳任务
│   ├── memory/                   # 每日记忆笔记
│   └── .git/                     # Git 版本控制
│
├── 📁 agents/                    # Agent 运行时数据
│   └── main/                     # 主 Agent (默认)
│       ├── sessions/             # 会话存储 ⭐
│       │   ├── sessions.json     # 会话索引
│       │   └── *.jsonl           # 会话转录 (完整对话历史)
│       └── agent/                # Agent 状态
│           ├── auth-profiles.json
│           └── models.json
│
├── 📁 devices/                   # 设备配对信息
│   ├── paired.json               # 已配对设备
│   └── pending.json              # 待批准设备
│
├── 📁 logs/                      # 日志文件
│   └── config-audit.jsonl        # 配置审计日志
│
├── 📁 cron/                      # Cron 任务状态
│
├── 📁 identity/                  # 身份标识
│
├── 📁 canvas/                    # Canvas 画布文件
│
└── 📁 completions/               # 代码补全缓存

---

🔍 关键目录详解

1️⃣ openclaw.json — 主配置文件

这是 OpenClaw 的核心配置，包含：

{
  "auth": { ... },           // 认证配置 (API Keys, OAuth)
  "models": { ... },         // 模型提供商配置
  "agents": { ... },         // Agent 默认设置
  "tools": { ... },          // 工具配置
  "session": { ... },        // 会话管理
  "gateway": { ... },        // Gateway 配置 (端口、认证、Tailscale)
  "plugins": { ... }         // 插件启用状态
}

---

2️⃣ workspace/ — Agent 工作区 ⭐

这是 你的文件 ，Agent 在这里读写、记忆、工作。

workspace/
├── SOUL.md           # Agent 的人格和行为规范
├── USER.md           # 你的信息
├── IDENTITY.md       # Agent 的身份
├── AGENTS.md         # 工作区使用指南
├── TOOLS.md          # 本地工具笔记 (相机、SSH 等)
├── HEARTBEAT.md      # 周期性任务清单
└── memory/
    └── YYYY-MM-DD.md # 每日笔记

---

3️⃣ agents/main/sessions/ — 会话存储 ⭐

这里存储所有对话历史。

sessions/
├── sessions.json              # 会话索引 (元数据)
└── dfghgsaef-....jsonl         # 会话转录 (完整对话)

sessions.json 内容示例：

{
  "agent:main:webchat:direct:openclaw-control-ui": {
    "sessionId": "1234-5678-910-1234-5678910",
    "updatedAt": 12345678910,
    "inputTokens": 15000,
    "outputTokens": 8000,
    "totalTokens": 23000,
    "contextTokens": 18000
  }
}

*.jsonl 文件：

• 每行是一个 JSON 对象
• 记录完整的对话历史 (user/assistant 消息)

---

4️⃣ devices/ — 设备配对

存储已配对的设备信息。

paired.json 内容：

{
  "ushj8sk6...": {
    "deviceId": "ushj8sk6...",
    "platform": "linux",
    "clientId": "cli",
    "role": "operator",
    "scopes": ["operator.admin", "operator.write", ...],
    "tokens": { ... }
  },
  "hd4k5oygs...": {
    "deviceId": "hd4k5oygs...",
    "platform": "Win32",
    "clientId": "openclaw-control-ui",
    "role": "operator",
    ...
  }
}

你的设备：

1. Linux CLI — 你的 Ubuntu 终端
2. Windows Web UI — 你的浏览器 (openclaw-control-ui)

每个设备有：

• 🔑 公钥/私钥对
• 🔐 OAuth Token
• 📋 权限范围 (scopes)

---

5️⃣ logs/ — 日志

logs/
└── config-audit.jsonl    # 配置审计日志

记录配置变更、安全审计事件。

---

6️⃣ 其他目录

目录	用途
cron/	定时任务状态和运行历史
identity/	设备身份标识
canvas/	Canvas 交互界面文件
completions/	代码补全缓存
memory/ (根目录)	向量索引 SQLite 数据库

---

🔐 权限说明

注意目录权限：

• drwx------ (700) — 只有所有者可读写执行
• drwxrwxr-x (775) — 组用户可读写

敏感目录 (agents/, logs/, openclaw.json) 使用 700 权限，保护你的：

• API Keys
• 对话历史
• 设备 Token

---

📊 目录大小估算

目录	大小	说明
workspace/	~50KB	你的文件
agents/main/sessions/	~260KB	会话数据 (会增长)
openclaw.json*	~8KB	配置 + 备份
devices/	~2KB	设备配对
总计	~320KB+	轻量级

---

🎯 与安装目录的关系

┌─────────────────────────────────────────────────┐
│  /home/ubuntu/.npm-global/.../openclaw/         │
│  — 程序代码 (只读，npm 管理)                      │
│  — dist/, extensions/, skills/, docs/           │
└─────────────────────────────────────────────────┘
                      │
                      │ 运行时读写
                      ▼
┌─────────────────────────────────────────────────┐
│  /home/ubuntu/.openclaw/                        │
│  — 你的数据 (可写，用户管理)                      │
│  — openclaw.json, workspace/, agents/, ...      │
└─────────────────────────────────────────────────┘

简单说：

• /home/ubuntu/.npm-global/.../openclaw/ = 程序本身 (代码)
• ~/.openclaw/ = 你的数据 (配置、会话、记忆)

---

💡 常用操作

查看配置

cat ~/.openclaw/openclaw.json

查看会话

openclaw sessions --json
# 或
ls -la ~/.openclaw/agents/main/sessions/

备份工作区

cd ~/.openclaw/workspace
git add .
git commit -m "Backup"

查看配对设备

cat ~/.openclaw/devices/paired.json

重置配置

cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

---

这就是 ~/.openclaw 的完整说明！这是你的"数据家园"，所有个人配置、对话历史、记忆都存在这里。

---

End

你好，少年，未来可期~

本文由作者最佳伙伴——阿程，赞助推出！！