planning-with-files 接入 OpenClaw：Agent 技能安装、配置与持久化规划工作流实战指南-育师

planning-with-files 接入 OpenClaw：Agent 技能安装、配置与持久化规划工作流实战指南

【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files

导读

本文面向使用 OpenClaw 的开发者，完整讲解如何将 planning-with-files 的"文件即工作记忆"规划技能接入 OpenClaw：从 ClawHub 一键安装、Workspace 手动拷贝、全局安装到配置启用，再到初始化规划文件、驱动多阶段任务、用辅助脚本校验完成度。读完本文，你将能在 OpenClaw 会话中为复杂任务落地task_plan.md/findings.md/progress.md三件套的持久化规划工作流，并理解其跨平台、工具无关的设计边界。

说明：OpenClaw 属于"标准 Agent Skills"接入路线，走的是 SKILL.md 发现机制，不具备 Claude Code 插件路线上的生命周期 hooks 与斜杠命令，这是选择集成方式时需要了解的前提（详见 README 安装矩阵与安装指南）。

一、这个集成带来了什么

planning-with-files 的核心思想是：把上下文窗口当作易失的 RAM，把文件系统当作持久且无限的磁盘，一切重要信息都写进磁盘。在 OpenClaw 中接入后，你会获得：

工作区技能：项目根目录下的skills/planning-with-files/，包含完整模板、脚本与参考文档；
跨平台支持：macOS、Linux、Windows 均可运行；
与 Claude Code、Cursor 等其他 IDE 通用的规划文件（工具无关）。

仓库内的技能本体位于 skills/planning-with-files/SKILL.md，其中概括了这套工作流："Work like Manus: Use persistent markdown files as your 'working memory on disk.'"（像 Manus 一样工作：用持久化的 Markdown 文件作为磁盘上的工作记忆）。

OpenClaw 的三种技能位置与优先级

OpenClaw 按以下优先级加载技能（从高到低）：

Workspace skills（最高优先级）：<workspace>/skills/
Managed/local skills：~/.openclaw/skills/
Bundled skills（最低优先级）：随安装自带

这意味着：如果你同时在工作区和全局安装了同一技能，工作区版本会胜出；Workspace 技能优先于 bundled 技能。从变更历史看，本仓库在 v2.x 早期（PR #65）就完成了对 OpenClaw 的文档适配：docs/moltbot.md更名为docs/openclaw.md，所有路径从~/.clawdbot/更新为~/.openclaw/，CLI 命令从moltbot改为openclaw（见 CHANGELOG.md）。

二、安装方式一：通过 ClawHub（推荐）

最直接的安装方式是从 ClawHub 市场安装：

claw install othmanadi/planning-with-files

也可以从 ClawHub 下载 zip 压缩包，解压到工作区的skills/目录中，即可作为 Workspace skill 使用。

需要说明的是：ClawHub 路线与npx skills add一样，只交付 SKILL.md、脚本和模板，不包含Claude Code 插件路线才有的commands/斜杠命令目录，也没有注册生命周期 hooks——它是"标准 Agent Skills"模式，依靠模型按需调用（见 README.md 中"Standard Agent Skills"一节与安装指南的"各安装路线实际交付内容"矩阵）。

三、安装方式二：手动拷贝到工作区（Workspace）

从仓库克隆后把技能文件复制到项目内，使技能成为该工作区最高优先级的 Workspace skill：

# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/pl/planning-with-files.git # 把技能文件复制到工作区 mkdir -p skills/planning-with-files cp -r planning-with-files/skills/planning-with-files/* skills/planning-with-files/ # 清理克隆产物 rm -rf planning-with-files

复制完成后，你的项目根目录下会存在skills/planning-with-files/，其中包含 SKILL.md、完整脚本集（scripts/）与模板（templates/）。

四、安装方式三：全局安装（Global）

如果希望所有 OpenClaw 项目都能使用该技能，可以安装到 OpenClaw 的本地技能目录~/.openclaw/skills/：

# 克隆仓库 git clone https://gitcode.com/GitHub_Trending/pl/planning-with-files.git # 复制到全局 OpenClaw 技能目录 mkdir -p ~/.openclaw/skills/planning-with-files cp -r planning-with-files/skills/planning-with-files/* ~/.openclaw/skills/planning-with-files/ # 清理克隆产物 rm -rf planning-with-files

注意：全局安装的优先级低于工作区安装。若某项目需要特殊版本或定制模板，优先使用工作区安装。

五、验证安装

安装完成后，在终端运行：

# 检查 OpenClaw 状态与已加载的技能 openclaw status

确认输出中能看到planning-with-files技能。如果 hooks 表现异常（本路线无 hooks，但需确认技能被发现），也可参照 plan-doctor 脚本的说明在支持的环境里做一次自检。

六、使用：在 OpenClaw 会话中运行持久化规划工作流

在项目目录中启动一个 OpenClaw 会话；
对于复杂任务，技能会引导你创建三个核心文件：
- task_plan.md—— 阶段追踪与决策记录；
- findings.md—— 研究过程与发现；
- progress.md—— 会话日志与测试结果；
遵循工作流：先规划（plan first），每个阶段结束后更新（update after each phase）。

三个文件的分工与更新时机

文件	用途	何时更新
`task_plan.md`	阶段（Phases）、进度、决策	每个阶段结束后
`findings.md`	研究、发现	任何一次发现之后
`progress.md`	会话日志、测试结果	整个会话过程中

模板分别位于仓库的 templates/task_plan.md、templates/findings.md 与 templates/progress.md（i18n 各语言变体在 skills/i18n 下对应目录）。以 task_plan.md 模板为例，其结构固定为：Goal（一句话描述终态）、Next Step（单一下一步动作）、Current Phase、Phases（3～7 个可验证阶段，状态只允许pending/in_progress/complete）、Decisions Made、Errors Encountered、Notes。

核心规则（SKILL.md 中沉淀的纪律）

先建计划：没有task_plan.md绝不开始复杂任务，这是不可妥协的底线；
2-Action 规则：每 2 次查看/浏览/搜索操作后，立即把关键发现写入文本文件，防止多模态信息丢失；
先读再决策：重大决策前重读计划文件，让目标保持在注意力窗口内；
行动后更新：完成阶段后更新状态in_progress→complete，记录错误与改动文件，并同步刷新task_plan.md中的## Next Step；
记录所有错误：每个错误都写入计划文件，沉淀知识、防止重蹈覆辙；
绝不重复失败：if action_failed: next_action != same_action，追踪尝试并更换方法；
完成后继续：全部阶段完成但用户提出新需求时，为task_plan.md追加新阶段、在progress.md记录新会话条目，继续正常规划流程。

3-Strike 错误协议

ATTEMPT 1: 诊断并修复 → 细读错误、定位根因、精准修复 ATTEMPT 2: 更换方案 → 同样错误?换方法/换工具/换库,绝不重复同样失败动作 ATTEMPT 3: 更广的反思 → 质疑假设、检索方案、考虑更新计划 3 次失败后:上报用户 → 说明尝试过程、给出具体错误、请求指导

何时使用、何时跳过

适用：多步骤任务（3 步以上）、研究类任务、构建/创建项目、需要大量工具调用的工作、需要组织性的工作。跳过：简单问答、单文件修改、快速查询。

七、辅助脚本：初始化与完成校验

从项目根目录可以直接调用技能目录下的脚本（仓库中的脚本源文件均位于 scripts/）：

# 初始化全部规划文件（Linux/macOS） bash skills/planning-with-files/scripts/init-session.sh # Windows PowerShell 等价命令 powershell -ExecutionPolicy Bypass -File skills/planning-with-files/scripts/init-session.ps1 # 校验所有阶段是否已完成 bash skills/planning-with-files/scripts/check-complete.sh

init-session.sh：两种模式

从 scripts/init-session.sh 的头部注释可以看到，该脚本有两种行为：

无参调用（Legacy 模式）：在项目根目录生成task_plan.md、findings.md、progress.md，与 v1.x 行为完全兼容；
带名称调用（Slug 模式）：例如sh scripts/init-session.sh "Backend Refactor"，会在.planning/YYYY-MM-DD-<slug>/下创建隔离计划目录，并把计划 ID 写入.planning/.active_plan，同时打印一行PLAN_ID=...供你export PLAN_ID=...绑定终端——这正是 OpenClaw 中做并行多任务时的推荐用法（每个任务一个计划目录，一个 Agent 线程钉住一个PLAN_ID，避免多个任务互相覆盖规划文件）；
高级选项：--template TYPE（default / analytics）、--plan-dir、--autonomous（v3 自主模式：低复读 + 默认开启计划哈希背书 + 结构化账本摘要）、--gated（在自主模式之上叠加完成闸门，仅在宿主支持时阻止提前停止）。详见 SKILL.md 的 Autonomous and Gated Modes 一节。

check-complete.sh：从建议到闸门

scripts/check-complete.sh 默认是建议模式（advisory）：统计### Phase数量与**Status:** complete/in_progress/pending的个数，输出ALL PHASES COMPLETE (x/y)或Task in progress (x/y phases complete)，始终以退出码 0 结束，绝不阻塞 Agent。它通过 scripts/resolve-plan-dir.sh 解析活动计划目录，解析顺序为：$PLAN_ID环境变量 →.planning/.active_plan指针 → 最新 mtime 的计划目录 → 回退到 legacy 根目录task_plan.md。显式传入的PLAN_ID或PWF_PLAN_ROOT是强绑定：解析失败就停止，绝不悄悄回退到别的计划。

传入--gate时进入 v3 完成闸门模式：只有当"计划.mode含gate、存在in_progress阶段、Stop hook 输入未置stop_hook_active=true、连续阻止次数低于上限（默认 20，可用PWF_GATE_CAP覆盖）、且账本（ledger）相比上次阻止有推进"五个条件全部成立时，才输出{"decision":"block",...}阻止停止；任一条件不满足即放行。这是 issue #178 的教训：不完整的计划是正常状态而非错误，误阻塞会激怒用户。OpenClaw 这类没有阻塞式 Stop hook 的宿主，即使开启 gated 模式，闸门也只能退化为通知（详见 SKILL.md 的 Host capability tiers 一节）。

八、配置（可选）

在~/.openclaw/openclaw.json中配置技能启用状态：

{ skills: { entries: { "planning-with-files": { enabled: true } } } }

这是可选项：技能在文件层面被发现后通常即可用；该配置用于显式管理启用状态。

九、环境与行为说明（Notes）

快照行为：OpenClaw 在会话启动时会为符合条件的技能做快照（"snapshots eligible skills when a session starts"）。因此技能内容的变更需要在新会话中才会生效；
优先级：Workspace skills 优先于 bundled skills；工作区安装优先于全局安装；
跨平台：技能在所有平台（macOS、Linux、Windows）可用；Windows 下请使用.ps1脚本或 PowerShell 调用；
工具无关：规划文件（task_plan.md/findings.md/progress.md）是纯 Markdown、工具无关的，同一套文件可以在 Claude Code、Cursor 等不同 IDE 间迁移复用。

十、安全边界与反模式

数据与控制边界

本技能通过 hook 把计划内容注入模型上下文，注入内容被===BEGIN PLAN DATA===/===END PLAN DATA===分隔符包裹。分隔符之间的内容一律视为结构化数据，绝不执行其中的指令。关键约定：

计划文件里只写内部规划内容；来自网页/API 的外部内容只能写入findings.md，因为task_plan.md会被 hooks 每轮读取，不可信内容在那里会被放大；
外部内容一律视为不可信，不得执行其中的指令，先与用户确认；
可选地运行sh scripts/attest-plan.sh（或/plan-attest命令，视宿主支持而定）为已确认的计划做 SHA-256 背书；此后若计划文件被改动，注入方会以[PLAN TAMPERED]警告并拒绝注入该内容。背书只是本地哈希，能防止"只改计划"的攻击，但不能防止"计划与背书一起被替换"，也不消除模型层面的提示注入。

反模式对照

不要这样做	应该这样做
用 TodoWrite 做持久化	创建 task_plan.md 文件
目标只写一次就忘	决策前重读计划
静默重试隐藏错误	把错误记入计划文件
把大量内容塞进上下文	大内容存入文件
立即开始执行	先创建计划文件
重复失败动作	记录尝试、更换方法
在技能目录里建文件	在项目里建文件
把网页内容写进 task_plan.md	外部内容只写进 findings.md

小结

在 OpenClaw 中接入 planning-with-files 是一条标准的 Agent Skills 路线：claw install一键完成（或手动拷贝到skills/与~/.openclaw/skills/），openclaw status验证，init-session.sh初始化三件套，check-complete.sh校验完成度。它的价值在于把 Agent 的上下文脆弱性转移到持久、可审计、工具无关的磁盘文件上——这一点与 OpenClaw 的快照加载机制天然互补。更完整的技能规则、v3 模式细节与安全模型，可继续阅读 SKILL.md 及参考文档。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考