gstack × OpenClaw 集成指南：用提示词协议把 gstack 规划纪律注入 Claude Code 会话

本文以 docs/OPENCLAW.md 为主体，讲清 gstack 与 OpenClaw 的集成方式：OpenClaw 作为编排器原生生成 Claude Code 会话，而 gstack 只以"方法论源"身份提供规划纪律，两者之间没有任何守护进程或 RPC，桥接物就是纯提示词文本。读完本文，你可以掌握 OpenClaw 的 5 级调度路由（Simple/Medium/Heavy/Full/Plan）、三份可注入的 CLAUDE.md 工件的完整内容、4 个原生方法论技能的安装方式，以及 OPENCLAW_SESSION 环境变量的自动检测机制，并能完整复现 bun run gen:skill-docs --host openclaw 的生成链路。

集成哲学：是方法论源，不是移植代码库

gstack 与 OpenClaw 的关系被明确定义为 methodology source（方法论源），而非 ported codebase（移植代码库）：

• OpenClaw 的 ACP runtime 负责原生生成（spawn）Claude Code 会话——会话调度能力完全由 OpenClaw 侧承担；
• gstack 提供的是"让那些会话变得更好"的规划纪律与方法论（planning discipline and methodology）；
• 整个集成是一条轻量协议，编码为提示词文本：没有守护进程（No daemon）、没有 JSON-RPC、没有兼容性矩阵。原文明确写道："The prompt is the bridge"（提示词就是桥）。

这个设计直接决定了仓库中不存在任何 OpenClaw 专用运行时——所有集成面只有两类产物：可粘贴到 AGENTS.md 的调度路由文本，以及可追加到 CLAUDE.md 的方法论文本。

整体架构

原文档给出的架构图如下，左边是 OpenClaw（编排器：消息、日历、记忆、EA），右边是 gstack 仓库（方法论与规划的事实源）：

  OpenClaw                               gstack repo
  ─────────────────────                    ──────────────
  Orchestrator: messaging,                 Source of truth for
  calendar, memory, EA                     methodology + planning
       │                                        │
       ├── Native skills (conversational)       ├── Generates native skills
       │   office-hours, ceo-review,            │   via gen-skill-docs pipeline
       │   investigate, retro                   │
       │                                        ├── Generates gstack-lite
       ├── sessions_spawn(runtime: "acp")       │   (planning discipline)
       │       │                                │
       │       └── Claude Code                  ├── Generates gstack-full
       │           └── gstack installed at      │   (complete pipeline)
       │               ~/.claude/skills/gstack  │
       │                                        └── docs/OPENCLAW.md (this file)
       └── Dispatch routing (AGENTS.md)

从架构图中可以读出三个关键点：

1. 技能安装位置：Claude Code 会话中，gstack 安装在 ~/.claude/skills/gstack；
2. 会话生成通道：OpenClaw 通过 sessions_spawn(runtime: "acp") 启动 Claude Code，而不是自研运行时；
3. 分发路由落点：调度决策规则写入 OpenClaw 侧的 AGENTS.md，会话启动时由编排器选择注入哪一层 gstack 支持。

调度路由：OpenClaw 在 spawn 时刻做分层决策

OpenClaw 在会话生成时（at spawn time）决定使用哪一层 gstack 支持。原文的完整分层表如下：

Tier	适用场景	注入的 Prompt 前缀
Simple	单文件修改、错别字、配置变更	不注入任何 gstack 上下文
Medium	多文件功能、重构	追加 gstack-lite CLAUDE.md
Heavy	需要指定某个 gstack 技能	"Load gstack. Run /X"
Full	完整功能、目标、项目	追加 gstack-full 流水线
Plan	"帮我规划一个 Claude Code 项目"	追加 gstack-plan 流水线

对应的决策启发式（decision heuristic）是五条可操作的判断规则：

• 能否在 <10 行代码内完成？→ Simple
• 涉及多个文件但方案显而易见？→ Medium
• 用户点名了具体技能（/cso、/review、/qa）？→ Heavy
• 是一个功能、项目或目标（而非一个任务）？→ Full
• 用户想为 Claude Code 规划某事、暂不实现？→ Plan

可直接粘贴的 AGENTS.md 路由段

完整的、可直接粘贴的路由段位于 openclaw/agents-gstack-section.md，原文档要求将其复制进你的 OpenClaw AGENTS.md。该文件在原文档五条启发式之外还补了一条："Upgrade gstack"、"update gstack" → Heavy 层，prompt 为 Run /gstack-upgrade。

文件开头还定义了三条不可协商（non-negotiable）的行为规则，并且要求这些规则写在调度分层之上：

1. Always spawn, never redirect（只生成，不转介）：用户要求使用任何 gstack 技能时，永远通过 sessions_spawn 生成一个 Claude Code 会话；绝不允许说"你需要自己打开 Claude Code"。
2. Resolve the repo（解析仓库）：用户点名了仓库就设置工作目录；不知道路径就反问是哪个仓库，而不是把用户推回 Claude Code。
3. Autoplan runs end-to-end（autoplan 端到端执行）：生成会话、让它跑完整个评审流水线（CEO → design → eng），结束后把规划结果在聊天中汇报回来，并把规划写入记忆。用户永远不需要离开 Telegram。

各层级的 spawn 调用形态在该文件中给出了具体示例：

• SIMPLE：sessions_spawn(runtime: "acp", prompt: "<just the task>")
• MEDIUM：sessions_spawn(runtime: "acp", prompt: "<gstack-lite content>\n\n<task>")
• HEAVY：sessions_spawn(runtime: "acp", prompt: "Load gstack. Run /qa https://...")，可用技能包括 /cso、/review、/qa、/ship、/investigate、/design-review、/benchmark、/gstack-upgrade
• FULL：注入 gstack-full 内容，Claude Code 依次执行 /autoplan → 实现 → /ship → 汇报
• PLAN：注入 gstack-plan 内容，Claude Code 执行 /office-hours → /autoplan → 保存规划文件 → 汇报；编排器把规划链接持久化到记忆/知识库，待用户准备实现时再生成一个指向该规划文件的 FULL 会话

CLAUDE.md 冲突处理

在已有 CLAUDE.md 的仓库中生成 Claude Code 时，规则是追加（APPEND）而非替换：把 gstack-lite/full 作为新的 section 追加到仓库现有说明之后，绝不覆盖仓库既有的指令。

三个注入工件：gstack-lite / gstack-full / gstack-plan

gstack 为 OpenClaw 生成的三份 CLAUDE.md 工件都位于 openclaw/ 目录，由 bun run gen:skill-docs --host openclaw 生成。下面给出每份工件的完整内容与定位。

gstack-lite（Medium 层）：约 15 行的规划纪律

gstack-lite-CLAUDE.md 是一份"注入到被生成的 Claude Code 会话、追加到现有 CLAUDE.md 末尾"的规划纪律清单，共 5 条：

1. 修改前先读每一个要改的文件，先理解既有模式；
2. 写码前陈述计划：what（做什么）、why（为什么）、which files（哪些文件）、test case（测试用例）、risk（风险）；
3. 歧义裁决原则：完整性优先于捷径、既有模式优先于新模式、可逆选择优先于不可逆选择、安全默认值优先于聪明做法；
4. 完成前自审：检查遗漏的文件、断掉的导入、未测试的路径、风格不一致；
5. 汇报格式：交付了什么、做了哪些决策、还有什么不确定。

原文档补充了一个 A/B 测试结论：启用该纪律后耗时约 2 倍（2x time），但输出质量显著提升（meaningfully better output）。注意模板文件 openclaw/templates/gstack-lite-CLAUDE.md 与其内容一致——templates/ 是生成源，根下文件是生成产物（见下文生成链路）。

gstack-full（Full 层）：串联既有技能完成整功能

gstack-full-CLAUDE.md 把已有的 gstack 技能串成一条完整流水线，共 5 步：

1. 读 CLAUDE.md，理解项目上下文；
2. 运行 /autoplan 评审方案（CEO + eng + design 评审流水线）；
3. 实现已批准的规划，遵循上文规划纪律；
4. 运行 /ship 创建带测试、changelog 和版本号的 PR；
5. 汇报：PR 链接、交付内容、做出的决策、不确定的地方。

并带有一条硬约束："Do not ask for human input until the PR is ready for review"（PR 达到可评审状态前不要请求人工输入）——这正契合 OpenClaw 场景下用户可能身处 Telegram 的异步工作流。

gstack-plan（Plan 层）：只规划、不实现

gstack-plan-CLAUDE.md 是一条"完整评审阵线（full review gauntlet），但不做任何实现"的规划流水线，共 5 步：

1. 读 CLAUDE.md 理解项目上下文；
2. 运行 /office-hours 产出设计文档（问题陈述、前提假设、替代方案）；
3. 运行 /autoplan 评审设计（CEO + eng + design + DX 评审 + codex 对抗式评审）；
4. 把评审后的最终规划保存到 plans/<project-slug>-plan-<date>.md，内容包括设计文档、所有评审决策、实现顺序；
5. 向编排器汇报：规划文件路径、一段话总结与关键决策、被接受的 scope 扩张（如有）、推荐的下一步（通常是用 gstack-full 生成新会话去实现）。

该文件的结尾明确写出两条边界："Do not implement anything. This is planning only." 以及"The orchestrator will persist the plan link to its own memory/knowledge store"——即由 OpenClaw 侧把规划链接持久化到自己的记忆存储（brain repo、知识库或 AGENTS.md 中配置的任意位置），等用户准备好构建时，再生成一个引用该规划文件的 FULL 会话。这形成了一条"规划 → 记忆持久化 → 实现"的跨会话闭环。

原生方法论技能：为 OpenClaw 会话式场景手工适配

除注入工件外，gstack 还为 OpenClaw 的会话式（conversational）上下文手工编写了 4 个原生技能，源码位于 openclaw/skills/ 目录，发布到 ClawHub 后用 clawhub install 安装：

技能	定位	源码位置
gstack-openclaw-office-hours	产品拷问（6 个强制性问题）	openclaw/skills/gstack-openclaw-office-hours/SKILL.md
gstack-openclaw-ceo-review	战略挑战（10 节评审、4 种模式）	openclaw/skills/gstack-openclaw-ceo-review/SKILL.md
gstack-openclaw-investigate	运维式排障（4 阶段方法论）	openclaw/skills/gstack-openclaw-investigate/SKILL.md
gstack-openclaw-retro	运维式回顾（周度工程复盘）	openclaw/skills/gstack-openclaw-retro/SKILL.md

从源码可以看到这些技能是 gstack 方法论的手工适配版本，刻意去掉了 gstack 基础设施——原文强调 "No gstack infrastructure (no browse, no telemetry, no preamble)"（没有 browse、没有 telemetry、没有 preamble）。例如 gstack-openclaw-office-hours/SKILL.md 以一个 HARD GATE 开篇："Do NOT invoke any implementation, write any code... Your only output is a design document"，先询问用户目标（创业/内部项目/hackathon/开源/学习/娱乐）再分 Startup mode 与 Builder mode 两条路径；gstack-openclaw-retro/SKILL.md 则支持 24h、14d、30d、compare 等时间窗口参数，并采用本地时区对齐午夜边界的 git log 查询窗口。这些技能不经过 gen-skill-docs 管道生成，是 hand-crafted 的（详见 docs/OPENCLAW_PUBLISHING.md 的说明）。

被生成会话的检测：OPENCLAW_SESSION 环境变量

当 Claude Code 运行在由 OpenClaw 生成的会话内部时，OPENCLAW_SESSION 环境变量应当被设置。gstack 检测到该变量后会调整行为：

• 跳过交互式提示（auto-chooses recommended options，自动选择推荐选项）；
• 跳过升级检查与 telemetry 提示；
• 聚焦任务完成与文字汇报（prose reporting）。

设置方式是在 sessions_spawn 时传入 env: { OPENCLAW_SESSION: "1" }。

从源码结构看，这个检测在仓库中是真实落地且贯穿各技能的：例如 bin/gstack-skill-start 中会执行 [ -n "${OPENCLAW_SESSION:-}" ] && echo "SPAWNED_SESSION: true" 来标记会话性质，bin/gstack-session-kind 依据该变量判定会话类型；而 office-hours、investigate、make-pdf 等大量技能的 SKILL.md 中也都内嵌了同样的检测片段。CHANGELOG.md 中还记录了这一特性的适用范围："Works for any orchestrator, not just OpenClaw"——即任何编排器只要设置该变量都能复用这套非交互行为，OpenClaw 只是第一个典型场景。

安装与工件生成链路

OpenClaw 用户侧安装

对 OpenClaw 用户，原文档给出的操作方式是对你的 OpenClaw agent 说 "install gstack for openclaw"。Agent 应当完成四步：

1. 把 gstack-lite CLAUDE.md 装入其编码会话模板；
2. 安装 4 个原生方法论技能；
3. 把调度路由段加入 AGENTS.md；
4. 用一次测试 spawn 验证。

gstack 开发者侧：生成命令与模板机制

对 gstack 开发者，./setup --host openclaw 会输出本文档对应的文档；实际工件由 bun run gen:skill-docs --host openclaw 生成。

从源码看生成机制：scripts/gen-skill-docs.ts 在处理 currentHost === 'openclaw' 时，会把 openclaw/templates/ 下的三个模板文件（gstack-lite/full/plan 的 CLAUDE.md）逐字节复制到 openclaw/ 根目录并打印 GENERATED: openclaw/<文件名>。这解释了仓库中同时存在 openclaw/templates/ 与 openclaw/ 根下同名文件的原因：前者是源（source of truth），后者是生成产物，二者内容保持一致。

另外，hosts/openclaw.ts 中定义了 OpenClaw 作为 gstack 文档生成 host 的配置，值得注意的三点：

• extraPathRewrites: [{ from: 'CLAUDE.md', to: 'AGENTS.md' }]——生成 OpenClaw 面向文档时，把对 CLAUDE.md 的引用重写为 AGENTS.md，与 OpenClaw 侧的编排器约定一致；
• suppressedResolvers 抑制了 CROSS_MODEL 与 GBRAIN 类 resolver，即裁掉不适用于 OpenClaw 的 Claude 专属 preamble 段落；
• coAuthorTrailer 被替换为 Co-Authored-By: OpenClaw Agent <[e-mail]>，保证 OpenClaw 场景下提交的署名正确。

技能发布（补充）

4 个原生技能发布到 ClawHub 的完整流程（clawhub publish 命令格式、clawhub login 认证、clawhub search gstack 验证）记录在 docs/OPENCLAW_PUBLISHING.md 中，关键点：发布命令是 clawhub publish 而非 clawhub skill publish，每次更新需递增 --version 并附 --changelog。

明确不做的事：集成的设计边界

原文档用一个 "What we don't do" 清单划定了这条集成协议的边界，这也是理解其轻量性的关键：

• 不做 dispatch daemon——会话生成由 ACP 负责，gstack 不另起调度守护进程；
• 不做 Clawvisor relay——认为不需要额外的安全中继层；
• 不做双向 learnings 桥——brain repo（知识库）本身就是知识存储，无需再建同步通道；
• 不做 JSON schema 或协议版本化——提示词即协议，不引入序列化契约；
• gstack 不提供 SOUL.md——OpenClaw 有自己的人格文件；
• 不做完整技能移植——编码类技能保持为 Claude Code 原生，OpenClaw 侧只有会话式方法论技能。

小结：一个"提示词即协议"的集成样本

gstack × OpenClaw 集成的全部实现可以归纳为三类纯文本产物：一份写入 AGENTS.md 的五层调度路由（openclaw/agents-gstack-section.md）、三份追加到 CLAUDE.md 的规划纪律/流水线/规划工件（openclaw/gstack-{lite,full,plan}-CLAUDE.md）、以及 4 个发布到 ClawHub 的手工方法论技能（openclaw/skills/）。没有守护进程、没有 RPC、没有 schema 版本协商——会话分层在 spawn 时刻由编排器根据五条启发式决定，OPENCLAW_SESSION 环境变量负责让 gstack 在被生成会话内自动切换为非交互模式。对于需要在消息类入口（如 Telegram）里异步驱动 Claude Code 完成"规划 → 实现 → /ship"闭环的团队，这套模式提供了一个几乎零基础设施成本的参考实现；而 gstack 的编码类技能本身仍保留在 Claude Code 原生侧，两者职责边界清晰。