系统提示词

OpenClaw 会为每次代理运行构建自己的系统 Prompt；没有运行时默认 Prompt。

组装分为三层：

• buildAgentSystemPrompt 从显式输入渲染 Prompt。它保持为纯渲染器，不直接读取全局配置。
• buildConfiguredAgentSystemPrompt 在渲染前为特定代理应用基于配置的 Prompt 配置项（所有者显示、TTS 提示、模型别名、记忆引用模式、子代理委派模式）。
• 运行时适配器（嵌入式、CLI、命令/导出预览、压缩）收集实时事实（工具、沙箱状态、通道能力、上下文文件、提供商 Prompt 贡献）并调用已配置的 Prompt 门面。

这使导出/调试 Prompt 展示面与实时运行保持一致，而不会将每个运行时细节变成一个单体构建器。

提供商插件可以贡献缓存感知指导，而不会替换 OpenClaw 拥有的 Prompt。提供商运行时可以：

• 替换三个命名核心部分之一：interaction_style、tool_call_style、execution_bias
• 在 Prompt 缓存边界上方注入稳定前缀
• 在 Prompt 缓存边界下方注入动态后缀

使用提供商拥有的贡献进行模型系列特定调优；自 v2026.4.5 以来，它们一直是推荐路径。保留仍受支持的 before_prompt_build 钩子，用于兼容性或真正全局的 Prompt 更改。

内置 GPT-5 系列 Prompt 贡献（resolveGpt5SystemPromptContribution）使用此机制：一个 stablePrefix 行为契约（执行策略、工具纪律、输出契约、完成契约）加上可选的 interaction_style 覆盖以获得更友好的语气。对于 OpenAI 系列路由，plugins.entries.openai.config.personality 控制该风格层："friendly" 是默认值，"on" 是 "friendly" 的别名，"off" 仅移除 friendly 覆盖；稳定行为契约保持不变。

结构¶

Prompt 紧凑，包含固定部分：

• 工具：结构化工具权威来源提醒，加上运行时工具使用指导。当 progress_card 启用（tools.updatePlan，默认开启）时，其自身描述说明如何维护一个持久计划和状态备注，最多保持一个步骤为 in_progress，并跳过不会改变整体情况的例行更新。
• 执行倾向：在本轮内对可执行请求采取行动，持续进行直到完成或被阻塞，从较弱的工具结果中恢复，实时检查可变状态，并在最终确定前验证。对于有可用工具的请求操作，视为已授权：工具策略、沙箱和 exec 审批在运行时控制风险，因此 Prompt 不要求模型预先拒绝、警告或寻求额外许可。
• 承诺的工作：承诺未来、后台、委派或持续工作会产生跟进所有权：在结束本轮前安排可用的完成或监视路径，主动返回结果或具体阻塞项，并绝不将进度（如 running）视为完成。
• 谨慎：编辑现有配置或调度器文件前先检查并合并，按用户要求使用或存储用户共享的凭据，在群组中私密投递短期登录码，以及当没有控制工具可用时提供终端设置路径。
• 运行时上下文：面向所有提供商的稳定指导，位于谨慎之后、缓存边界上方。由 <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> 和 <<<END_OPENCLAW_INTERNAL_CONTEXT>>> 分隔的消息承载其后续用户请求的运行时上下文，而不是用户编写的文本。这包括关于活动 exec 会话、活动子代理和媒体生成进度的紧凑事实，以及当 exec 可用时在 Windows 上的建议性已批准可执行文件提示。每个可用能力都会发出当前快照，空时包括 none，并取代旧快照。使用它时无需回复或描述它，保持其内部细节私密，并继续而不等待另一条消息。载体本身只保存分隔的主体，因此该指令不会每轮重复。
• 技能（可用时）：告诉模型如何按需加载技能说明。
• OpenClaw 控制：使用 gateway（config.get / config.schema.lookup）检查配置；当 openclaw 可用时，通过它请求重启、配置、通道、插件、代理以及模型/提供商更改。委派更改遵循有效权限。对于承载此会话的 Gateway，所有者请求的更新仅在用户明确请求时使用 gateway 操作 update.run，并自动重启以及发送完成或失败通知。如果没有 gateway，引导用户联系 OpenClaw 所有者、在终端中运行 openclaw update，或使用 Control UI 更新该 Gateway。绝不通过 exec 或分离任务修改该 Gateway 的安装或控制其服务；不要编造 CLI 命令。当 exec 可用时，Prompt 还会说明：“对于用户请求的其他主机更新，先验证它不是此 Gateway，然后使用 exec/SSH 运行 openclaw update --yes；正常 exec 审批仍然适用。”参见自动化和 SSH。
• 消息：对已连接通道的回复和操作使用 OpenClaw 路由，而不是 shell 或 HTTP 变通方案。这并不禁止用户授权的用于其他服务的 CLI 或 API 操作，例如发送邮件；正常工具权限和审批仍然适用。
• 工作区：工作目录（agents.defaults.workspace）。
• 文档：本地文档/源码路径以及何时阅读它们。
• 工作区文件（注入）：说明引导文件包含在下方。
• 沙箱（启用时）：沙箱运行时、沙箱路径、提权 exec 可用性。
• 时间上下文：缓存边界下方的本地日期和时区；精确时间来自 session_status（当可用时）。
• 助手输出指令：紧凑的附件、语音留言和回复标签语法。
• UI 展示（展示工具可用时）：紧凑的 widget、仪表板和门户路由；验证实际交付的表面。
• 可折叠详情（受支持时）：教导模型将可选深度保留在 <details> 披露中，同时保持主要答案和必需操作可见。
• 运行时：主机、操作系统、node、模型、仓库根目录（当检测到时）和会话身份（一行）。Git 共同作者尾注仅当共享会话有可署名的人时出现在这里。活动 exec 会话通过运行时上下文载体传递。推理强度通过提供商控制传递；其 Ultra 编排指导保持在缓存边界下方。使用 /status 检查所选强度。
• 推理：当前可见性级别以及 /reasoning 切换提示。

大型稳定内容（包括 项目上下文 和静态 记忆召回 指令）保持在内部提示缓存边界上方。易变的每轮部分（UI 呈现、Control UI 嵌入指导、消息、可折叠详情、语音、群聊上下文、表情回应、运行时、项目记忆 事实、特定频道的 ACP 提示、委派/编排模式，以及当前提升级别）附加在该边界下方，以便具有前缀缓存的本地后端能够跨频道轮次复用稳定的工作区前缀。Exec、子代理和媒体事实使用后面的运行时上下文载体，以同样保留对话历史前缀；它们基于能力的指令仍保留在系统提示中。该边界是内部传输元数据：每个部分对 CLI 后端而言仍是系统提示指导。当已接受的 schema 已经携带该运行时细节时，工具描述应避免嵌入当前频道名称。

媒体任务事实仅包含已启用的媒体工具和属于当前请求者的任务。没有记录请求者的恢复任务使用配置的会话所有者；已完成任务会被省略。

工具还承载长时间运行工作的指导：

• 使用 cron 进行未来跟进（check back later、提醒、周期性工作），而不是 exec 睡眠循环、yieldMs 延迟技巧或重复的 process 轮询
• 仅对现在启动并在后台继续的命令使用 exec / process
• 当启用自动完成唤醒时，只启动一次命令，并依赖基于推送的唤醒路径
• 使用 process 查看运行中命令的日志、状态、输入或进行干预
• 对于较大任务，优先使用 sessions_spawn，并遵循其已接受的完成模式：宣告型子代理返回完成事件；收集器需要显式结果收集
• 将子代理完成视为该次运行的结束，而不是被委派用户目标已完成的证明；当范围内仍有工作时，继续持久会话
• 不要循环轮询 subagents list / sessions_list 仅为了等待完成

agents.defaults.subagents.delegationMode 可以强化这一点。如果没有显式设置，OpenClaw 会在每个代理的主会话中使用 "prefer"，在其他地方使用 "suggest"；显式默认值或按代理覆盖始终优先。"prefer" 会添加一个专门的 委派 部分，告知代理保持响应，使用隐藏子代理处理内部杂务，并使用可见侧边栏会话处理用户会跟进或返回的工作。这仅是提示层面；工具策略仍控制 sessions_spawn 是否可用。

在 ultra 思考级别，当 sessions_spawn 可用时，还会添加一个 主动子代理编排 部分：它告知模型通过子代理并行化独立的调查、实现和验证，将简单或紧耦合的工作保留在本地，为每个子代理设定有界目标，并在回复前综合结果。

secrets 工具描述教导元数据优先发现、任务所需的掩码请求，以及为受支持的配置字段返回存储的 SecretRefs。设置工具描述将凭据收集路由到掩码流程。Care 部分告知代理按用户要求使用或存储用户共享的凭据，完成任务，并在最终回复中简要确认所提供的凭据是如何使用或存储的，而不重复其值。该确认保持事实性且不令人担忧。它还指示将用户请求的登录或配对代码以及验证 URL 从群聊中私下发送给请求用户，随后在群聊中确认，但不包含代码或 URL。当 openclaw 和 gateway 都不可用时，它将频道、提供商和凭据设置引导到终端中的 openclaw channels add <channel> 或 openclaw configure，其中提示会掩码密钥。该凭据指导也出现在 Codex 和 Copilot 提示中，基于其可调用的控制工具。参见 Secrets。

UI 呈现指导与原生 Codex 开发者指令共享。它仅包含当前可调用的工具，包括延迟工具和 Code Mode 工具；最小提示会省略它。工具资格遵循客户端和频道呈现器能力，而不是硬编码的频道列表。widget 可以内联渲染或使用频道呈现器；其返回的呈现是权威的。

紧凑指南区分 widget 与 dashboard 布局、portals 和浏览器标签页。缺少创作是会话限制，而不是平台限制。Portals 通过 Control UI → Portals 打开，而不是裸 publicUrl；携带令牌的 URL 保持私有。代理必须验证已交付的交互，或说明其未经验证。工具描述和链接文档拥有详细的沙箱、权限和服务器设置指令。

风险在运行时强制执行，而不是在提示文本中。工具策略、exec 审批、沙箱和频道允许列表决定什么可以运行或需要确认；提示告知代理执行请求的工作，并让那些门控决定。

Gateway 拥有的提示组装将上下文来源与消息文本分开携带。上下文生产者区分运行时指令与对话数据和心跳结果。在新会话中，模型投影会转义入站文本中的内部上下文分隔符提及，并引用上下文数据，而不更改存储的用户转录。匹配文本永远不会将消息提升为运行时上下文。这是提示加固，而不是授权边界或针对提示注入的保证。

转录头选择此投影：新会话使用版本 4；现有版本 3 会话在重启后保留其先前投影。分支和恢复的历史保留源版本，现有转录内的重置边界和压缩也是如此。采用保留的历史不变；Doctor 使用版本 3 修复无头的遗留历史。未知投影版本在模型提交前被拒绝。提供商消息角色保持不变，以保留保留思考前缀兼容性。Cloud-worker 提示组装使用单独的启动契约，并且仍需要此加固；参见 cloud-worker 后续。

恢复的房间 CLI 轮次会保留新的线程笔记、系统事件和 MCP 应用上下文。

在具有原生审批卡片/按钮的频道中，提示词会告知代理优先依赖该 UI，并且仅在工具结果表示聊天审批不可用或手动审批是唯一路径时，才包含手动 /approve 命令。

提示词模式¶

OpenClaw 会为子代理渲染更小的系统提示词。运行时按每次运行设置 promptMode（不是面向用户的配置）：

• full（默认）：以上所有部分。
• minimal：用于子代理；省略记忆提示词部分（打包为记忆召回）、模型别名、用户身份、助手输出指令、消息、可折叠详情和静默回复。工具、关怀、技能（如提供）、工作区、沙箱、当前日期和时间（如已知）、运行时以及注入上下文仍可用。
• none：仅返回基础身份行。

在 promptMode=minimal 下，额外注入的提示词会被标记为子代理上下文，而不是群聊上下文。

对于频道自动回复运行，当直接、群组或仅消息工具上下文已经拥有可见回复契约时，OpenClaw 会省略通用的静默回复部分。自动群组/频道上下文仅在操作者明确允许群组静默时显示 NO_REPLY 指导；直接聊天和仅消息工具回复会跳过静默令牌指导。

提示词快照¶

OpenClaw 在 test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/ 下为 Codex 运行时正常路径保留已提交的提示词快照。它们渲染选定的 app-server 线程/轮次参数，以及针对 Telegram 直接、Discord 群组和心跳轮次重建的模型绑定提示词层栈：固定的 Codex gpt-5.5 模型提示词夹具、Codex 正常路径权限开发者文本、父级本地请求指令、OpenClaw 开发者指令、原生协作模式指令、用户轮次输入，以及对动态工具规范的引用。

使用 pnpm prompt:snapshots:sync-codex-model 刷新固定的 Codex 模型提示词夹具。默认情况下，它会查找 $CODEX_HOME/models_cache.json，然后是 ~/.codex/models_cache.json，再然后是维护者检出约定 ~/code/codex/codex-rs/models-manager/models.json；如果都不存在，它会退出且不更改已提交的夹具。传入 --catalog <path> 可从特定的 models_cache.json 或 models.json 文件刷新。

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

使用 pnpm prompt:snapshots:gen 重新生成；使用 pnpm prompt:snapshots:check 验证漂移。CI 会连同附加边界分片一起运行漂移检查，因此提示词更改和快照更新会落在同一个 PR 中。

工作区引导注入¶

代理身份、指令和记忆从已配置的代理工作区解析，并路由到与其生命周期匹配的提示词表面。当会话从另一个文件夹或受管 worktree 运行时，该文件夹仍然是执行工作区。其 AGENTS.md 会作为项目上下文追加在已配置工作区文件之后；OpenClaw 不会从执行文件夹加载 SOUL.md、IDENTITY.md、USER.md、MEMORY.md 或 BOOTSTRAP.md。

轮次启动时，仅在已配置的代理工作区中初始化缺失的引导模板，绝不在单独的执行文件夹中初始化。这也适用于生成的子会话和与会话绑定的 cron 轮次。

• AGENTS.md
• SOUL.md
• IDENTITY.md
• USER.md
• BOOTSTRAP.md（仅在全新工作区中）
• MEMORY.md（如存在）

在原生 Codex 框架上，OpenClaw 避免在每个用户轮次中重复稳定的工作区文件。Codex 通过原生项目文档发现加载执行文件夹的 AGENTS.md，包括其 ## Tools 部分，因此 OpenClaw 不会再次注入该文件。当执行使用另一个文件夹时，OpenClaw 会将已配置代理工作区的有界 AGENTS.md 快照添加到线程级开发者指令中，以便原生 Codex 子代理继承它。在受管捆绑 stdio app-server 上，SOUL.md、IDENTITY.md 和 USER.md 会被追加到仅限父级的模型请求指令中，而不是原生历史中，因此新交付的人格不会自动流向原生子代理。外部和 Desktop 连接保留旧版协作载体，并带有明确的可用性警告；旧历史会被保留。MEMORY.md 内容也不会粘贴到每个原生 Codex 轮次中：当代理工作区可用记忆工具时，Codex 轮次会获得一条小型工作区记忆说明，指示模型使用 memory_search 或 memory_get。如果工具被禁用或记忆搜索不可用，MEMORY.md 会回退到正常的有界轮次上下文路径。BOOTSTRAP.md 保持正常的轮次上下文角色。

心跳监控临时内容不是引导文件。心跳运行器仅将其追加到计划的心跳用户消息中；正常轮次不会收到它，并且系统提示词不包含心跳特定部分。

在非 Codex 框架上，其余引导文件会根据其现有门控组合到 OpenClaw 提示词中。保持注入文件简洁，尤其是非 Codex MEMORY.md：它应保持为精选的长期摘要，详细每日笔记放在 memory/*.md 中，可通过 memory_search / memory_get 按需检索。过大的非 Codex MEMORY.md 文件会增加提示词用量，并可能在下述引导文件限制下被部分注入。

大文件会被截断，并带有标记：

发生截断时，OpenClaw 总是向系统提示词注入一条简洁通知，说明某些 bootstrap 文件已被截断，并建议直接读取受影响文件；该通知是内置的且不可配置，并且有意省略每个文件的详细信息。缺失文件会注入一个简短的缺失文件标记。文件名和原始/注入计数保留在诊断信息中，例如 /context、/status、doctor 和日志。

对于记忆文件，截断不是数据丢失：文件在磁盘上保持完整。在原生 Codex 上，MEMORY.md 在可用时通过记忆工具按需读取，否则使用有界的提示词回退。在其他运行框架上，模型只能看到缩短后的注入副本，直到它直接读取或搜索记忆。如果 MEMORY.md 被反复截断，请将其提炼为更短的持久摘要，将详细历史移入 memory/*.md，或有意提高 bootstrap 限制。

子代理会话仅注入 AGENTS.md（其他 bootstrap 文件会被过滤掉，以保持子代理上下文较小）。

内部钩子可通过 agent:bootstrap 事件拦截此步骤，以修改或替换注入的 bootstrap 文件（例如将 SOUL.md 替换为另一种人格）。

为了让语气不那么通用，请从 SOUL.md 人格指南 开始。

要检查每个注入文件的贡献量（原始与注入、截断、工具 schema 开销），请使用 /context list 或 /context detail。参见 上下文。

时间处理¶

时间上下文 部分包含用户本地日历日期和时区。它位于缓存边界下方，因此日期变更或时区变化不会使稳定前缀失效。

当代理需要精确当前时间且该工具可用时，使用 session_status；其状态卡片包含一行时间戳。同一工具还可以可选地设置按会话的模型覆盖（model=default 会清除它）。

通过以下配置：

• agents.defaults.userTimezone

参见 时区 和 日期与时间 了解完整行为细节。

技能¶

当存在符合条件的技能时，OpenClaw 会注入一个紧凑的 <available_skills> 列表（formatSkillsForPrompt），并为每个技能提供文件路径。提示词指示模型使用 read 加载所列位置（工作区、托管或内置）的 SKILL.md。如果没有符合条件的技能，则省略技能部分。

受管理的原生 Codex 轮次通过父级本地模型请求指令接收此列表，而不是通过每轮用户输入；但保留精确定时提示词的轻量 cron 轮次除外。没有该中继的连接使用线程开发者指令，以确保模型拥有的协作指令无法替换技能目录。其他运行框架保留正常的提示词部分。

位置可以指向嵌套技能，例如 skills/personal/foo/SKILL.md。嵌套仅用于组织；提示词使用 SKILL.md frontmatter 中的扁平技能名称。

资格判定包括技能元数据门控、运行时环境/配置检查，以及在配置了 agents.defaults.skills 或 agents.entries.*.skills 时生效的代理技能允许列表。插件内置技能仅在其所属插件启用时才符合条件，这使得工具插件能够暴露更深入的运行指南，而无需将所有这些指导嵌入每个工具描述中。

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

这使基础提示词保持较小，同时仍支持针对性技能使用。大小由技能子系统负责，独立于通用运行时读取/注入大小：

运行时摘录预算涵盖 memory_get、实时工具结果以及压缩后的 AGENTS.md 刷新。

文档¶

文档 部分在可用时指向本地文档（Git 检出中的 docs/ 或捆绑的 npm 包文档），否则回退到 https://docs.openclaw.ai。它还列出 OpenClaw 源代码位置：Git 检出示出本地源代码根目录，包安装获得 GitHub 源代码 URL，并指示在文档不完整或过时时到那里审查源代码。

提示词将文档定位为 OpenClaw 自我认知的权威来源，先于模型理解 OpenClaw 如何工作（记忆/每日笔记、会话、工具、Gateway、配置、命令、项目上下文），并告知模型将 AGENTS.md、项目上下文、工作区/个人资料/记忆笔记以及 memory_search 视为指令上下文或用户记忆，而不是 OpenClaw 设计/实现知识。如果文档未提及或过时，模型应说明并检查源代码。它还告知模型在可能时自行运行 openclaw status，仅在无法访问时才询问用户。

对于配置，它会引导代理使用 gateway 工具操作 config.schema.lookup 获取精确的字段级文档和约束，然后参考 docs/gateway/configuration.md 和 docs/gateway/configuration-reference.md 获取更广泛的指导。

相关¶

• 代理循环
• 代理运行时
• 代理工作区
• 上下文引擎