跳转至

系统提示词

OpenClaw 为每次代理运行构建自己的系统提示词;不存在运行时默认提示词。

组装分为三层:

  • buildAgentSystemPrompt 根据显式输入渲染提示词。它保持为纯渲染器,不直接读取全局配置。
  • buildConfiguredAgentSystemPrompt 在渲染前为特定代理应用由配置支持的提示词调节项(所有者显示、TTS 提示、模型别名、记忆引用模式、子代理委派模式)。
  • 运行时适配器(嵌入式、CLI、命令/导出预览、压缩)收集实时事实(工具、沙箱状态、频道能力、上下文文件、提供方提示词贡献)并调用配置好的提示词外观。

这样可以保持导出/调试提示词表面与实时运行一致,而无需将每个运行时细节都塞进一个单体构建器中。

由节点托管的 OpenClaw 会话使用与 Gateway 本地会话相同的提示词和 bootstrap 准备。Gateway 在会话现有的隐私与工具策略下选择代理指令、人格文件、技能、记忆指导和对话上下文。节点提供自己的工作区路径、主机、操作系统、shell 和活动进程事实。将执行移动到节点不会将代理切换到通用编码提示词,也不会使未选中的节点本地 bootstrap 文件成为其上下文的一部分。

上下文引擎选择、历史准备和回合结算仍由 Gateway 负责。直接的回合后钩子会在节点的工作区结果被接受之后、其放置声明被释放之前运行。

提供方插件可以贡献具备缓存感知的指导,而无需替换 OpenClaw 拥有的提示词。提供方运行时可以:

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

使用提供方自有的贡献进行模型家族特定的调优;自 v2026.4.5 起,它们就是推荐路径。before_prompt_build 钩子仍受支持,请将其保留用于兼容性或真正全局性的提示词变更。

内置的 GPT-5 系列提示词贡献(resolveGpt5SystemPromptContribution)使用这一机制:一个 stablePrefix 行为契约(执行策略、工具纪律、输出契约、完成契约),外加一个可选的 interaction_style 覆盖,以获得更友好的语气。对于 OpenAI 系列路由,plugins.entries.openai.config.personality 控制该风格层:"friendly" 是默认值,"on" 是 "friendly" 的别名,"off" 仅移除友好的覆盖;稳定的行为契约仍然保留。

结构

提示词紧凑,包含固定部分:

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

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

在受支持的直接 Anthropic API 密钥路由和原生 OpenAI Responses 路由上,嵌入式会话固定该边界的两侧。刷新后的部分作为指令消息附加在当前用户轮次之后,保留之前的 Prompt 和历史字节。路由或所选个人配置文件更改、重置和压缩开启新系列;技能和记忆刷新契约继续提供更新指导。Prompt 缓存诊断使用有界名称集合识别已更改的部分,而不记录其内容。

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

工具还携带长时间运行工作的指导:

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

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

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

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

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

紧凑指南将小部件与 仪表盘 布局、门户 和浏览器选项卡区分开来。缺少创作能力是会话限制,而不是平台限制。门户通过 Control UI → Portals 打开,而不是裸 publicUrl;携带 token 的 URL 保持私有。代理必须验证已交付的交互,或说明它未经验证。工具描述和链接文档负责详细的沙箱、权限和服务器设置指令。

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

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

转录头部选择此投影:新会话使用版本 4;现有版本 3 会话在重启后保留其先前投影。分支和恢复的历史保持源版本,现有转录中的重置边界和压缩也是如此。采用不会改动保留的历史;Doctor 使用版本 3 修复遗留的无头部历史。未知投影版本会在提交给模型之前被拒绝。提供商消息角色保持不变,以保留 retained-thinking 前缀兼容性。云工作器回合在启动前使用相同的 Gateway 拥有的提示词投影,并将可信运行时上下文单独传递给工作器,工作器会添加其执行主机事实。

恢复的房间 CLI 回合会保留新的线程笔记、系统事件和 MCP App 上下文。

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

提示词模式

OpenClaw 为子代理渲染更小的系统提示词。运行时为每次运行设置 promptMode(非面向用户的配置):

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

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

静默回复 部分仅适用于连接到外部消息频道的会话。子代理、Control UI 和其他内部会话永远不会收到静默令牌指导:它们必须返回结果或继续未完成的工作。对于频道自动回复运行,当直接、群组或仅消息工具上下文已经拥有可见回复契约时,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 中。

工作区引导注入

代理身份、指令和记忆从已配置的代理工作区解析,并路由到与其生命周期匹配的提示词表面。当会话从另一个文件夹或受管工作树运行时,该文件夹仍然是执行工作区。其 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 连接)通过可刷新的线程开发者指令传递共享人设,原生子级可以继承这些指令。在这些连接上,所选的个人 users/<profile-id>/USER.md 覆盖会被省略,因为它们缺少仅限父级的载体;当选择其中一个时,OpenClaw 会记录警告。旧历史会被保留。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 文件会增加提示词用量,并可能在下述引导文件限制下被部分注入。

Note

memory/*.md 每日文件不属于正常引导项目上下文。在普通轮次中,它们通过 memory_search / memory_get 按需访问,因此除非模型明确读取它们,否则不会占用上下文窗口。裸 /new 和 /reset 轮次是例外:运行时可以为该首轮在其前面添加近期每日记忆,作为一次性启动上下文块。

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

限制 配置键 默认值
单文件最大字符数 agents.defaults.bootstrapMaxChars 20000
所有文件总计 agents.defaults.bootstrapTotalMaxChars 60000

发生截断时,OpenClaw 始终会向系统提示词注入一条简洁通知,说明某些引导文件已被截断,并建议直接读取受影响文件;该通知是内置的且不可配置,并刻意省略逐文件细节。缺失文件会注入一个简短的缺失文件标记。文件名以及原始/注入计数保留在 /context、/status、doctor 和日志等诊断信息中。

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

子代理会话仅注入 AGENTS.md(其他引导文件会被过滤掉,以保持子代理上下文较小)。

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

为了听起来不那么通用,请从 SOUL.md 人格指南 开始。

要检查每个注入文件贡献了多少(原始与注入、截断、工具模式开销),请使用 /context list 或 /context detail。参见 上下文。

时间处理

时间上下文 部分在当前轮次的运行时上下文中携带用户本地日历日期和时区,位于系统提示词之外。它每轮刷新,而不会重写较早消息。因此,跨天不会改变完整系统提示词和先前对话字节,从而在本地和托管提供商上保留前缀缓存复用。原始模型探测会省略 OpenClaw 运行时上下文。

Chat Completions 和原生 Ollama 默认保留这些隐藏的每轮消息,因此下一个请求会扩展前一个请求的前缀。提供商重放策略可以明确选择退出。保留的运行时事实包括用于清除先前活动状态的空白快照,并计入正常历史和压缩预算;临时路由仍会省略空生产者快照。

当代理需要精确当前时间且工具可用时,请使用 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>

这使基础提示词保持较小,同时仍支持有针对性的技能使用。大小由技能子系统负责,与通用运行时读取/注入大小分开:

范围 技能提示词预算 运行时摘录预算
全局 skills.limits.maxSkillsPromptChars agents.defaults.contextLimits.*
范围 技能提示词预算 运行时摘录预算
每个代理 agents.entries.*.skillsLimits.maxSkillsPromptChars agents.entries.*.contextLimits.*

运行时摘录预算涵盖 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 获取更广泛的指导。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw