OpenClaw 实战 01｜总览：一个 config 驱动、会自己做梦的 Agent 工作区原创

# 总览：一个 config 驱动、会自己做梦的 Agent 工作区

这是 OpenClaw 实战系列的开篇。后面几篇全部基于两套真实部署——一台海外容器（supervisor + Kong）和一台家里的 NAS（裸机 + systemd）——不讲"官网怎么说"，只讲"我把它跑起来、翻它的 trajectory 日志、踩了坑之后，它到底是怎么构成的"。

这一篇先把整张图讲清楚：OpenClaw 不是几份文件，而是 一个 config + 一套插件 + 几十个 skill + 一个会自我维护的 workspace。

# §1 先纠正一个流传很广的误解

很多入门文章（包括我自己最早写的一版）会告诉你：OpenClaw 是"完全文件驱动"的，核心是几份 markdown，新会话一开就按顺序把它们读一遍，顺序错了人格就不生效。

翻完真实的 trajectory 日志之后，我得收回这个说法——它有两处硬伤：

OpenClaw 的主体是配置，不是 markdown。 它的"大脑"是一个 JSON 配置文件 ~/.openclaw/openclaw.json，外加一套插件和几十个 skill。markdown 文件（AGENTS.md / MEMORY.md / DREAMS.md / HEARTBEAT.md）确实存在，但它们是 workspace 里的少数几份，大多还是 OpenClaw 自己写、自己读的，不是你手搓的"人格五件套"。
"读取顺序决定红线生效"是想当然。 这些文件最终会被拼进同一个上下文一次性喂给模型——模型在生成第一个 token 之前，整个上下文已经全部在场。不存在"我正按 A 文件的语气回应、但 B 文件还没加载"这个时间点；那需要模型在两次文件读取之间就开始输出，它不会。把两份短文件在清单里换个位置，不会让某条规则"还没加载"。

顺序唯一轻微的影响来自长上下文的位置效应（开头/结尾的内容注意力权重略高，即所谓 lost in the middle）。所以把关键约束放在上下文最前或最后算个弱实践——但这是概率性的、很弱的效应，和"顺序错了就翻车"完全是两码事。真正会让 Agent 不听话的是配置写错或规则内容互相打架，不是文件排序。

把这两点放下，我们来看 OpenClaw 真正的样子。

# §2 为什么要先搞清这张图

因为绝大多数 OpenClaw 翻车，都来自对这张图的误解：

以为改了模型要重启服务 → 其实是热重载，重启反而打断；
以为 wiki status 里那 9 个报告是知识 → 其实是空的监控仪表盘；
以为截图发给 Agent 它就"看见"了 → 其实主模型 qwen3-coder 根本不支持图片输入，它在脑补；
以为配了 dreaming.model 就生效 → 漏了一个 allowModelOverride 开关，子代理照样用默认模型。

这四个坑后面 §7 会逐个拆。先记住一句话：OpenClaw 是一个"配置 + 自治"的系统，不是一个"读文件"的脚本。 搞清它由哪几块组成，比背任何启动协议都有用。

# §3 走一遍：OpenClaw 的五个组成部分

实测版本 2026.6.x，harness 类型就叫 openclaw，工作区根目录 ~/.openclaw/。它的五块是：

组成	在哪	谁维护	一句话定位
harness / agent 运行时	`~/.openclaw/agents/main/`	OpenClaw	会话循环、模型调度，会话存为 `*.trajectory.jsonl`
主配置 `openclaw.json`	`~/.openclaw/openclaw.json`	你（CLI/编辑）	模型、provider、插件、浏览器——一切开关。热重载
*插件 `plugins.entries.`**	`openclaw.json` 内	你启用	memory-core（记忆/做梦）、memory-wiki（结构化知识库）等
技能 skills	`~/.openclaw/workspace/skills/`	内置 + ClawHub	自带 57 个，外加注册表按需装
workspace 自治文件	`~/.openclaw/workspace/`	多数 OpenClaw 自己写	`AGENTS.md` / `MEMORY.md` / `DREAMS.md` / `HEARTBEAT.md`

# 3.1 配置中枢：`openclaw.json` + 热重载

这是 OpenClaw 的真正中心。一个很说明问题的真实片段——把后台"做梦"任务的模型从云端默认模型换成本地 qwen3-coder：

{
  "plugins": {
    "entries": {
      "memory-core": {
        "enabled": true,
        "config": {
          "dreaming": { "enabled": true, "model": "alibaba/qwen3-coder" }
        },
        "subagent": {
          "allowModelOverride": true,
          "allowedModels": ["alibaba/qwen3-coder"]
        }
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

关键点：这个改动不用重启。 plugins.entries 下的插件配置（比如这里 dreaming 的 model）是热重载的——openclaw.json 一保存，下个 dreaming 周期就用新模型，手动重启反而打断正在跑的会话。但别把"热重载"当成整个 openclaw.json 的通则：gateway / models.providers / channel / TTS 这些改完仍要重启（详见 §5 坑4）。这条"哪些热重载、哪些要重启"的边界，是后面几篇反复踩的坑。

还有一层容易忽略：真正的 API key 不在 openclaw.json 里（那里通常是占位串），而是存在 agent 的 sqlite 里、按 provider 名做索引。所以"改 provider 名"是个大坑——这个留到配置管理那一篇细讲。配置改坏了也别慌，OpenClaw 会留一份 openclaw.json.last-good 兜底。

# 3.2 插件：能力的"大模块"

插件挂在 plugins.entries.* 下，是 OpenClaw 的功能大件。最常打交道的两个：

memory-core — 记忆系统。它管两样东西：① MEMORY.md（主动记忆 / 语义搜索的落地文件）；② dreaming（做梦）——一个后台反思任务，默认每天凌晨扫一遍当天的工作，把反思写进 DREAMS.md。
memory-wiki — 结构化知识库（和 MEMORY.md 是两套东西）。它把知识组织成带 YAML frontmatter 的图谱：sources（原始材料）/ entities（实体）/ concepts（概念）/ syntheses（综合）。启用方式：

openclaw plugins enable memory-wiki
openclaw wiki init      # 在 ~/.openclaw/wiki/main 下建结构

1
2

记住分层：MEMORY.md 是"主动记忆"，memory-wiki 是"结构化知识 + 仪表盘"。 别把后者当笔记本用。

# 3.3 技能：自带 57 个 + ClawHub 按需装

skill 是 OpenClaw 包装好的一个个具体能力（多数是对某个 CLI 的封装）。裸装就自带 57 个，覆盖笔记（obsidian / bear-notes）、通讯（slack / discord / imsg）、开发（coding-agent / oracle / 各类 debugger）、媒体（video-frames / diagram-maker / 各种 TTS）、智能家居等等。

要的能力不在自带列表里，用 ClawHub 注册表装：

npx clawhub install <skill-name>
# 例：npx clawhub install freshrss-reader
# 装到 ~/.openclaw/workspace/skills/<skill-name>

1
2
3

凭证一律走环境变量注入，不要硬编码进 skill 代码或对话历史。

# 3.4 workspace：少数几份、且多半是它自己写

~/.openclaw/workspace/ 里你会真正接触到的 markdown，就这几份——而且注意"谁维护"那一列：

文件	谁写	作用
`AGENTS.md`	你	Agent 的操作指令 / 框架，含 heartbeat 守则
`MEMORY.md`	OpenClaw 追加	主动记忆落地（见 §3.2）
`DREAMS.md`	OpenClaw 自动	凌晨 dreaming 任务写的反思日记
`HEARTBEAT.md`	你（内容即开关）	周期自检——见下

HEARTBEAT.md 是个开关文件：文件"空 / 纯注释" → OpenClaw 跳过心跳（=关）；一旦加进非注释内容 → 启用周期心跳轮询（默认 ~30min）。但要警惕：心跳"会被戳"≠"一定执行"——Agent 自己判断要不要动，所以它是尽力而为，不是确定性 cron。要可靠定时用 cron（下一篇专讲）。HEARTBEAT.md 和这些 workspace 文件一样，运行时动态读取，改完无需重启。

# 3.5 验证：怎么确认它真在这么跑

openclaw memory status          # 看记忆系统状态
openclaw wiki status            # 看 memory-wiki（注意空报告，见 §7）
ls ~/.openclaw/workspace/       # 看 DREAMS.md / MEMORY.md / AGENTS.md / HEARTBEAT.md 真实存在
ls ~/.openclaw/agents/main/sessions/   # 会话 trajectory.jsonl 落地在这

1
2
3
4

trajectory 文件里能直接读到当前会话用的 provider/model（如 alibaba / qwen3-coder）、workspaceDir、harness 版本——这是排障时的第一手真相，比任何文档都准。

# §4 五块之间的关系（一图）

                ┌──────────────────────────┐
                │   openclaw.json (热重载)   │  ← 一切开关的中枢
                └─────────────┬────────────┘
            ┌─────────────────┼─────────────────┐
            │                 │                 │
     ┌──────┴──────┐   ┌──────┴──────┐   ┌──────┴───────┐
     │  plugins    │   │   skills    │   │  agent 运行时 │
     │ memory-core │   │ 57 内置 +   │   │ 会话循环/调度 │
     │ memory-wiki │   │ ClawHub     │   │ trajectory   │
     └──────┬──────┘   └─────────────┘   └──────┬───────┘
            │ 读写                                │ 读写
            └──────────────┬─────────────────────┘
                  ┌────────┴─────────┐
                  │  ~/.openclaw/    │
                  │   workspace/     │  ← AGENTS / MEMORY / DREAMS / HEARTBEAT
                  └──────────────────┘

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

三条关键事实：

openclaw.json 是中枢，插件/模型/浏览器都从这里开关，且热重载；
后台是自治的：dreaming（写 DREAMS.md）+ heartbeat（HEARTBEAT.md 门控）会在没人盯着时自己跑；
workspace 多数文件是 OpenClaw 自己写的，你手搓的主要是 AGENTS.md 和 HEARTBEAT.md。

# §5 四个真实的坑（症状 / 原因 / 解药）

# 坑 1：配了 dreaming 模型却不生效

症状：在 openclaw.json 写了 dreaming.model: alibaba/qwen3-coder，凌晨生成的 DREAMS.md 还是用默认模型。
原因：只设 dreaming.model 不够，子代理默认不允许覆盖模型。
解药：同时设 memory-core.subagent.allowModelOverride: true，并把目标模型加进 allowedModels 白名单。

# 坑 2：截图发了，Agent 却在脑补

症状：让 Agent 看一个网页截图，它"看到"了一堆页面上根本没有的内容（比如凭空说出几个订阅频道）。
原因：主模型是 qwen3-coder 这类纯文本/代码模型，不支持图片输入（工具会提示 model does not support images）。截图文件生成了，但模型读不到，只能基于文本上下文瞎编。
解药：涉及视觉的任务必须切到带视觉的模型（识图走 imageModel，是独立配置）；否则让 Agent 明确说"我看不到截图"，而不是假装看到。

# 坑 3：`wiki status` 里的 9 个"空报告"

症状：openclaw wiki init 后看到 9 个 reports（contradictions.md / lint.md / low-confidence.md …）却全是空的，以为知识库坏了。
原因：这些是知识库引擎的监控仪表盘，在你 ingest 内容之前本来就是空模板，不是用户笔记。
解药：先往库里写实体页面 / ingest 材料，这些报告才会填上分析数据。空 = 预期行为。

# 坑 4：以为"改配置要重启"

症状：要么改完 openclaw.json 习惯性重启、打断了正在跑的会话；要么反过来——改完不重启，以为生效了，结果 Agent 还在用旧配置。
原因：把"要不要重启"一刀切了。真相是看你改什么：
- 热重载（不用重启）：workspace 里的 markdown（AGENTS.md / HEARTBEAT.md / MEMORY.md）、以及 plugins.entries 下的插件配置（如 dreaming 的 model）——运行时动态读，下个周期就生效。
- 必须重启：gateway（端口/鉴权）、models.providers（provider/模型/key）、Telegram channel、TTS——这些在进程启动时读，改完要 supervisorctl restart openclaw（容器）/ systemctl --user restart openclaw-gateway（裸机）。
解药：改 markdown / 插件配置 → 等下个周期；改 gateway/provider/model/TTS → 重启，并看应用层 ready 日志确认，别只看进程状态。

# §6 复用规则（一句话带走）

OpenClaw 是"一个 config + 一套自治系统"，不是"几份要按顺序读的人格文件"。 先理解 openclaw.json 和插件，再谈 workspace。

展开 3 条：

改配置走 openclaw.json——markdown / 插件配置热重载，gateway/provider/model/TTS 改完要重启；别迷信文件读取顺序。
分清三套"记忆"：MEMORY.md（主动记忆）≠ memory-wiki（结构化知识 + 仪表盘）≠ DREAMS.md（后台反思）。
能力先查自带 57 个 skill，再用 npx clawhub install 补——凭证只进环境变量。

# §7 下一篇

下一篇：02｜定时任务——Heartbeat（尽力而为）vs Cron（确定性），以及那个 approve 怎么点都没用的设备 scope 死循环。

# §8 Agent 可直接解析的元数据块

{
  "_meta": {
    "doc_version": "2026-06-27",
    "article_id": "openclaw-01-overview",
    "profile_context": "any",
    "estimated_read_time": "8min",
    "openclaw_version_observed": "2026.6.x"
  },
  "architecture": {
    "central_config": "~/.openclaw/openclaw.json (hot-reload; last-good backup at openclaw.json.last-good)",
    "plugins": ["memory-core (MEMORY.md + dreaming → DREAMS.md)", "memory-wiki (structured knowledge + report dashboards)"],
    "skills": "57 built-in + ClawHub registry (npx clawhub install <name>)",
    "workspace_files": ["AGENTS.md (you)", "MEMORY.md (auto)", "DREAMS.md (auto)", "HEARTBEAT.md (you; content = on/off switch)"],
    "sessions": "~/.openclaw/agents/main/sessions/*.trajectory.jsonl"
  },
  "verification": {
    "memory": "openclaw memory status",
    "wiki": "openclaw wiki status",
    "workspace": "ls ~/.openclaw/workspace/",
    "model_in_use": "read provider/modelId from the latest *.trajectory.jsonl"
  },
  "safety_rules": [
    "Config edits hot-reload — do NOT restart the service by reflex",
    "API keys live in the agent sqlite, not in openclaw.json (placeholder strings there)",
    "Credentials go in env vars, never in skill code or chat history",
    "File read ORDER does not gate rule activation — the whole context loads at once"
  ],
  "common_pitfalls": [
    { "pitfall": "dreaming.model 配了不生效", "symptom": "DREAMS.md 仍用默认模型", "fix": "同时设 subagent.allowModelOverride:true 并把模型加进 allowedModels" },
    { "pitfall": "截图发了 Agent 却脑补", "symptom": "描述出页面上没有的内容", "fix": "主模型 qwen3-coder 不支持图片输入，视觉任务切到 imageModel" },
    { "pitfall": "wiki status 9 个空报告", "symptom": "report 全空以为坏了", "fix": "那是监控仪表盘，ingest 内容后才填充——空=预期" },
    { "pitfall": "改配置习惯性重启", "symptom": "打断正在跑的会话", "fix": "openclaw.json 与 workspace 文件热重载，无需重启" }
  ],
  "reusable_rule": "OpenClaw 是 config+自治系统，不是按顺序读的人格文件——先懂 openclaw.json 和插件，再谈 workspace"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

AI Agent 使用指南：

当用户说"OpenClaw 装好了怎么看它由什么组成" → 引导先看 openclaw.json、openclaw plugins、ls ~/.openclaw/workspace/
当用户说"改了模型/配置没生效" → 先确认是不是漏了 allowModelOverride，并提醒配置是热重载、别急着重启
当用户说"Agent 看不到截图却在乱说" → 检查主模型是否支持图片输入，视觉任务走 imageModel
当用户说"wiki 报告都是空的" → 说明那是监控仪表盘，ingest 内容后才填充
当用户纠结"文件读取顺序" → 告诉他顺序不门控规则生效，整段上下文一次性加载；真正的问题是配置或规则内容冲突

#OpenClaw #AI Agent #系统架构 #配置管理 #入门

上次更新: 6/28/2026

OpenClaw 实战 02｜定时任务：Heartbeat vs Cron，与那个 approve 救不了的死循环→