OpenClaw 为每个 agent 运行构建自定义 System Prompt，不使用 pi-coding-agent 默认提示。Prompt 通过三层组装（buildAgentSystemPrompt、resolveAgentSystemPromptConfig、运行时适配器），Provider 插件可替换核心区块（interaction_style、tool_call_style、execution_bias）或在缓存边界上下注入前缀/后缀。Bootstrap 文件（AGENTS.md、SOUL.md、TOOLS.md 等）注入到上下文窗口，使用 bootstrapMaxChars（默认 12000）和 bootstrapTotalMaxChars（默认 60000）控制大小；子代理仅注入 AGENTS.md 和 TOOLS.md。使用 /context list 可查看实际注入内容。

OpenClaw System Prompt 结构：组装、注入与调试配置

OpenClaw 为每次 agent 运行构建自定义 System Prompt，不使用 pi-coding-agent 默认 Prompt。Prompt 完全由 OpenClaw 组装注入到 agent 运行中。

Prompt 组装分三层：

• buildAgentSystemPrompt：从显式输入渲染 Prompt，保持纯渲染器角色，不应直接读取全局配置。
• resolveAgentSystemPromptConfig：解析配置支持的 Prompt 旋钮，如 owner 显示、TTS 提示、模型别名、记忆引用模式和子代理委托模式。
• 运行时适配器（嵌入式、CLI、命令/导出预览、压缩）：收集实时事实（工具、沙箱状态、渠道能力、上下文文件、Provider 贡献提示），然后调用配置的 Prompt facade。

这样保证导出/调试 Prompt 表面与实际运行保持一致，而无需将所有运行时细节塞进一个单一大构建器。

Provider 插件可以贡献感知缓存的 Prompt 引导，而无需替换整个 Prompt。Provider 运行时可以：

• 替换少量命名的核心区块（interaction_style、tool_call_style、execution_bias）
• 在 Prompt 缓存边界上方注入稳定前缀（stable prefix）
• 在 Prompt 缓存边界下方注入动态后缀（dynamic suffix）

使用 Provider 拥有的贡献进行模型族特定调优。保留 before_prompt_build 的传统 Prompt 变异用于兼容性或真正全局的 Prompt 更改，不应用作普通 Provider 行为。

OpenAI GPT-5 系列叠加层保持核心执行规则简洁，并增加模型特定指导：persona 锁定、简洁输出、工具纪律、并行查询、交付覆盖、验证、缺失上下文和终端工具卫生。

Prompt 结构（固定区块）

Prompt 刻意保持紧凑，使用以下固定区块：

• Tooling：结构化工具真理源提醒 + 运行时工具使用指引。
• Execution Bias：紧凑跟进指引：对可操作的请求按顺序行动，直到完成或受阻，从弱工具结果恢复，实时检查可变状态，最终确认前验证。
• Safety：短防护提醒，避免寻求权力或绕过监督。
• Skills（可用时）：告知模型如何按需加载 Skill 指令。
• OpenClaw Control：告知模型优先使用 gateway 工具进行配置/重启工作，避免编造 CLI 命令。
• OpenClaw 自更新：如何使用 config.schema.lookup 安全检视配置、用 config.patch 打补丁、用 config.apply 替换完整配置、仅在用户明确请求时运行 update.run。agent 可用的 gateway 工具也拒绝重写 tools.exec.ask / tools.exec.security，包括旧版 tools.bash.* 别名（这些会归约到受保护的 exec 路径）。
• Workspace：工作目录（agents.defaults.workspace）。
• Documentation：本地 OpenClaw 文档路径（Git 检出 docs/ 或 npm 包文档），以及何时阅读。
• Workspace Files（注入）：标记 Bootstrap 文件将在下方注入。
• Sandbox（启用时）：指示沙箱运行环境、沙箱路径以及提权 exec 是否可用。
• 当前日期时间：仅包含时区（缓存稳定；实时时钟来自 session_status）。
• Assistant Output Directives：紧凑的附件、语音笔记和回复标签语法。
• Heartbeats：Heartbeat Prompt 和 ack 行为（当默认 agent 启用心跳时）。
• Runtime：主机、OS、Node、模型、仓库根目录（检测到时）、thinking 级别（一行）。
• Reasoning：当前可见性级别 + /reasoning 切换提示。

OpenClaw 将较大的稳定内容（包括 Project Context）保持在内部 Prompt 缓存边界之上。易变的渠道/会话区块（如 Control UI 嵌入指导、Messaging、Voice、Group Chat Context、Reactions、Heartbeats、Runtime）追加到该边界下方，以便带前缀缓存的本地后端可以跨渠道回合复用稳定的工作区前缀。工具描述同样应避免嵌入当前渠道名称（当接受的 schema 已携带该运行时细节时）。

Tooling 区块还包含长时运行工作的运行时指引：

• 使用 cron 处理未来跟进（"稍后检查"、提醒、周期任务），不要使用 exec sleep 循环、yieldMs 延迟技巧或重复 process 轮询。
• 仅在命令需要立即启动并继续在后台运行时才使用 exec / process。
• 启用自动完成唤醒时，启动一次命令，依赖基于推送的唤醒路径（当命令产生输出或失败时）。
• 使用 process 检查日志、状态、输入或干预，当需要检查正在运行的命令时。
• 如果任务较大，优先使用 sessions_spawn；子代理完成基于推送，自动回报给请求者。
• 不要循环轮询 subagents list / sessions_list 来等待完成。

agents.defaults.subagents.delegationMode 可以强化此指引。默认 suggest 模式保留基线提示。prefer 模式增加专门的 Sub-Agent Delegation 区块，告诉主 agent 充当响应式协调器，将任何比直接回复更复杂的任务推送给 sessions_spawn。这是 Prompt 层面的指令；工具策略仍然控制 sessions_spawn 是否可用。

当实验性 update_plan 工具启用时，Tooling 还告诉模型仅在非平凡的多步工作中使用它，保持恰好一个 in_progress 步骤，避免每次更新后重复完整计划。

系统 Prompt 中的 Safety 防护是建议性的，引导模型行为但不强制执行策略。使用工具策略、exec 审批、沙箱和渠道白名单做硬性约束；操作者可按设计禁用这些。

在带有原生审批卡片/按钮的渠道上，运行时 Prompt 现在告诉 agent 优先使用该原生审批 UI。它应仅在工具结果说聊天审批不可用或手动审批是唯一路径时包含手动 /approve 命令。

Prompt 模式

OpenClaw 可为子代理渲染更小的 System Prompt。运行时为每次运行设置 promptMode（非用户可见配置）：

• full（默认）：包含上述所有区块。
• minimal：用于子代理；省略 Memory Recall、OpenClaw 自更新、Model Aliases、User Identity、Assistant Output Directives、Messaging、Silent Replies 和 Heartbeats。保留 Tooling、Safety、Skills（当提供时）、Workspace、Sandbox、当前日期时间（当已知时）、Runtime 和注入的上下文。
• none：仅返回基本身份行。

当 promptMode=minimal 时，额外注入的 Prompt 标记为 Subagent Context 而非 Group Chat Context。

对于渠道自动回复运行，当直接消息、群组或仅消息工具上下文拥有可见回复契约时，OpenClaw 会省略通用的 Silent Replies 区块。只有旧的自动群组/渠道模式应显示 NO_REPLY；直接聊天和仅消息工具回复不会收到静默令牌指导。

Prompt 快照

OpenClaw 为 Codex 运行时 happy path 保留了已提交的 Prompt 快照，位于 test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/。它们渲染选定的应用服务器线程/回合参数，以及重建的模型绑定 Prompt 层堆栈，包括 Telegram 直接、Discord 群组和心跳回合。该堆栈包括一个固定的 Codex gpt-5.5 模型 Prompt fixture（从 Codex 模型目录/缓存形状生成）、Codex happy-path 权限开发者文本、OpenClaw 开发者指令、回合范围协作模式指令（当 OpenClaw 提供时）、用户回合输入以及对动态工具规约的引用。

刷新固定的 Codex 模型 Prompt fixture 使用命令：

pnpm prompt:snapshots:sync-codex-model

默认情况下，脚本在 $CODEX_HOME/models_cache.json 中查找 Codex 运行时缓存，然后是 ~/.codex/models_cache.json，最后回退到维护者 Codex 检出约定 ~/code/codex/codex-rs/models-manager/models.json。如果这些源都不存在，命令退出而不更改已提交的 fixture。传递 --catalog <path> 从特定的 models_cache.json 或 models.json 文件刷新。

这些快照仍然不是字节对字节的原始 OpenAI 请求捕获。Codex 可以在 OpenClaw 发送线程和回合参数之后，在 Codex 运行时内添加运行时拥有的工作区上下文，如 AGENTS.md、环境上下文、记忆、应用/插件指令和内置的默认协作模式指令。

使用以下命令重新生成：

pnpm prompt:snapshots:gen

使用以下命令检查差异：

pnpm prompt:snapshots:check

CI 在额外的边界分片中运行差异检查，以便 Prompt 更改和快照更新保持在同一 PR 中。

Workspace Bootstrap 文件注入规则

Bootstrap 文件从活动工作区解析，然后路由到匹配其生命周期的 Prompt 表面：

• AGENTS.md
• SOUL.md
• TOOLS.md
• IDENTITY.md
• USER.md
• HEARTBEAT.md
• BOOTSTRAP.md（仅在新工作区）
• MEMORY.md（当存在时）

在原生 Codex harness 上，OpenClaw 避免在每个用户回合重复注入稳定工作区文件。Codex 通过自身项目文档发现加载 AGENTS.md。SOUL.md、IDENTITY.md、TOOLS.md 和 USER.md 作为 Codex 开发者指令转发。HEARTBEAT.md 内容不注入；心跳回合获得协作模式注释，指向该文件（当文件存在且非空时）。MEMORY.md 和活跃的 BOOTSTRAP.md 内容暂时保持正常的回合上下文角色。

在非 Codex harness 上，Bootstrap 文件继续按照其现有门控组合到 OpenClaw Prompt 中。当默认 agent 禁用心跳或 agents.defaults.heartbeat.includeSystemPromptSection 为 false 时，普通运行中会省略 HEARTBEAT.md。

保持注入文件简洁，尤其是 MEMORY.md。MEMORY.md 旨在保持为精炼的长期摘要；详细的每日笔记属于 memory/*.md，可通过 memory_search 和 memory_get 按需检索。过大的 MEMORY.md 文件会增加 Prompt 用量，并可能因以下 Bootstrap 文件限制而被部分注入。

注意：memory/*.md 每日文件不属于正常 Bootstrap Project Context。在普通回合中，它们通过 memory_search 和 memory_get 工具按需访问，因此不占用上下文窗口，除非模型显式读取它们。裸 /new 和 /reset 回合是例外：运行时可以将最近的每日记忆作为一次性启动上下文块前置到第一个回合。

大文件会以标记截断。单文件最大由 agents.defaults.bootstrapMaxChars（默认 12000）控制。所有文件总注入内容上限由 agents.defaults.bootstrapTotalMaxChars（默认 60000）控制。缺失的文件注入短缺失文件标记。当发生截断时，OpenClaw 可以注入简洁的 Prompt 警告通知；通过 agents.defaults.bootstrapPromptTruncationWarning（可选值 off、once、always；默认 always）控制。详细的原始/注入计数保留在诊断中，如 /context、/status、doctor 和日志。

对于记忆文件，截断不意味着数据丢失：文件在磁盘上保持完整，但模型只看到缩短的注入副本，直到直接读取或搜索记忆。如果 MEMORY.md 反复被截断，请将其提炼为更短的持久摘要，并将详细历史移动到 memory/*.md，或者有意提高 Bootstrap 上限。

子代理会话仅注入 AGENTS.md 和 TOOLS.md（其他 Bootstrap 文件被过滤以保持子代理上下文精简）。

内部钩子可以通过 agent:bootstrap 拦截此步骤以变异或替换注入的 Bootstrap 文件（例如，将 SOUL.md 切换为替代角色）。

如果想让 agent 不那么泛化，建议从 SOUL.md Personality Guide 开始。

要检查每个注入文件贡献了多少（原始 vs 注入、截断、工具 schema 开销），使用 /context list 或 /context detail。参见 Context。

时间处理与时区配置

System Prompt 包含一个专用的 Current Date & Time 区块，仅当用户时区已知时。为了保持 Prompt 缓存稳定，现在只包含时区（无动态时钟或时间格式）。

agent 需要当前时间时使用 session_status；状态卡片包含时间戳行。同一工具可选择设置每会话模型覆盖（model=default 清除覆盖）。

配置项：

• agents.defaults.userTimezone
• agents.defaults.timeFormat（auto | 12 | 24）

参见 Date & Time 获取完整行为。

Skills 注入

当存在符合条件的 Skill 时，OpenClaw 注入紧凑的可用 Skill 列表（formatSkillsForPrompt），包含每个 Skill 的文件路径。Prompt 指示模型使用 read 按需加载指定位置的 SKILL.md（工作区、托管或捆绑）。如果没有符合资格的 Skill，则省略 Skills 区块。

符合条件包括 Skill 元数据门控、运行时环境/配置检查，以及当 agents.defaults.skills 或 agents.list[].skills 配置时生效的 agent Skill 允许列表。

插件捆绑的 Skill 仅当其所属插件启用时符合条件。这使工具插件可以暴露更深入的操作指南，而无需将所有这些指导嵌入每个工具描述中。

<available_skills>
  <skill>
    <name>...</name>
    <description>...</description>
    <location>...</location>
  </skill>
</available_skills>

这保持基础 Prompt 小巧，同时支持按需 Skill 调用。

Skill 列表预算由 Skills 子系统拥有：

• 全局默认：skills.limits.maxSkillsPromptChars
• 每个 agent 覆盖：agents.list[].skillsLimits.maxSkillsPromptChars

通用有界运行时摘录使用不同的表面：

• agents.defaults.contextLimits.*
• agents.list[].contextLimits.*

这种分离使得 Skills 大小与运行时读取/注入大小（如 memory_get、实时工具结果和压缩后 AGENTS.md 刷新）保持独立。

文档引用

System Prompt 包含 Documentation 区块。当本地文档可用时，指向本地 OpenClaw 文档目录（Git 检出 docs/ 或 npm 包中的文档）。如果本地文档不可用，回退到 https://docs.openclaw.ai。

同一区块还包含 OpenClaw 源码位置。Git 检出让 agent 可以直接检查本地源码根目录。包安装包括 GitHub 源码 URL，并告知 agent 在文档不完整或过时时在此处查看源码。Prompt 还会提到公开文档镜像、社区 Discord 和 ClawHub（https://clawhub.ai）用于技能发现。它告诉模型首先查阅 OpenClaw 行为、命令、配置或架构的文档，并在可能时自行运行 openclaw status（仅在缺少访问权限时询问用户）。对于配置，它指向 agent 使用 gateway 工具动作 config.schema.lookup 获取精确字段级文档和约束，然后使用 docs/gateway/configuration.md 和 docs/gateway/configuration-reference.md 获取更广泛的指导。

常见问题

怎么查看我的 agent 实际收到的 system prompt 是什么？

在聊天中使用 /context list 查看各区块内容、每个注入文件的 token 占用以及注入详情。使用 /context detail 可查看更细粒度信息。

如何让 agent 的个性更鲜明？

编辑工作区中的 SOUL.md 文件——详细指导请参阅 SOUL.md 个性指南。修改后无需重启，下次对话即生效。

Bootstrap 文件注入后模型怎么使用？MEMORY.md 太大怎么办？

MEMORY.md 中的内容在每次回合都被注入，过大时会消耗较多 token 并可能被截断（默认单文件上限 12000 字符）。建议将 MEMORY.md 保持为精炼的长期摘要，每日详细笔记移入 memory/*.md 文件，这些文件通过 memory_search / memory_get 工具按需读取，不占用回合上下文窗口。

安全提示真的能约束模型行为吗？

不能。系统 Prompt 中的 Safety 区块是建议性的，引导模型但不强制执行。实际的安全保障来自工具策略、exec 审批、沙箱和渠道白名单。如需更严格的安全控制，请配置这些硬性约束。