chore(i18n): refresh zh-CN translations

This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-18 03:43:31 +00:00
parent 1c55acad4c
commit 8c267c5704
4 changed files with 920 additions and 943 deletions

View File

@ -1,36 +1,30 @@
---
read_when:
- 你需要解释智能体工作区或其文件布局
- 你想备份或迁移智能体工作区
- 你想备份或迁移智能体工作区
summary: 智能体工作区:位置、布局和备份策略
title: 智能体工作区
x-i18n:
generated_at: "2026-04-05T08:20:53Z"
generated_at: "2026-04-18T03:32:01Z"
model: gpt-5.4
provider: openai
source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a
source_hash: dd2e74614d8d45df04b1bbda48e2224e778b621803d774d38e4b544195eb234e
source_path: concepts/agent-workspace.md
workflow: 15
---
# 智能体工作区
工作区是智能体的“家”。它是
文件工具和工作区上下文使用的唯一工作目录。请保持其私密,并将其视为记忆。
工作区是智能体的“家”。它是文件工具和工作区上下文唯一使用的工作目录。请将其保持私密,并把它视为记忆。
这与 `~/.openclaw/` 分开,后者存储配置、凭证和
会话。
这与 `~/.openclaw/` 分开,后者用于存储配置、凭证和会话。
**重要:** 工作区是**默认 cwd**,而不是硬性沙箱。工具
会基于工作区解析相对路径,但绝对路径仍然可以访问主机上的其他位置,除非启用了沙箱隔离。如果你需要隔离,请使用
[`agents.defaults.sandbox`](/gateway/sandboxing)(和/或按智能体的沙箱配置)。
当启用沙箱隔离且 `workspaceAccess` 不为 `"rw"` 时,工具会在
`~/.openclaw/sandboxes` 下的沙箱工作区内运行,而不是在你的主机工作区中运行。
**重要:** 工作区是**默认 cwd**,而不是硬性沙箱。工具会基于工作区解析相对路径,但绝对路径仍然可以访问主机上的其他位置,除非启用了沙箱隔离。如果你需要隔离,请使用 [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing)(和/或按智能体设置的沙箱配置)。启用沙箱隔离后,如果 `workspaceAccess` 不是 `"rw"`,工具会在 `~/.openclaw/sandboxes` 下的沙箱工作区内运行,而不是在你的主机工作区内运行。
## 默认位置
- 默认值:`~/.openclaw/workspace`
- 如果设置了 `OPENCLAW_PROFILE`不为 `"default"`,默认值会变为
- 如果设置了 `OPENCLAW_PROFILE`其值不是 `"default"`,默认值会变为
`~/.openclaw/workspace-<profile>`
- 可在 `~/.openclaw/openclaw.json` 中覆盖:
@ -42,12 +36,10 @@ x-i18n:
}
```
`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 会在
工作区不存在时创建该工作区并填充 bootstrap 文件。
沙箱种子复制仅接受工作区内的常规文件;解析到源工作区外部的符号链接/硬链接别名会被忽略。
`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 会在工作区不存在时创建它,并填充引导文件。
沙箱种子复制仅接受工作区内的常规文件;解析后指向源工作区外部的符号链接 / 硬链接别名会被忽略。
如果你已经自行管理工作区文件,可以禁用 bootstrap
文件创建:
如果你已经自行管理工作区文件,可以禁用引导文件创建:
```json5
{ agent: { skipBootstrap: true } }
@ -55,106 +47,95 @@ x-i18n:
## 额外的工作区文件夹
较旧的安装可能创建过 `~/openclaw`。保留多个工作区
目录可能导致令人困惑的鉴权或状态漂移,因为同一时间只有一个
工作区处于活动状态。
较早版本的安装可能创建了 `~/openclaw`。保留多个工作区目录可能会导致令人困惑的凭证或状态漂移,因为同一时间只有一个工作区处于活动状态。
**建议:** 仅保留一个活动工作区。如果你不再使用这些
额外文件夹,请归档或移到废纸篓(例如 `trash ~/openclaw`)。
**建议:** 只保留一个活动工作区。如果你不再使用额外的文件夹,请将其归档或移到废纸篓(例如 `trash ~/openclaw`)。
如果你有意保留多个工作区,请确保
`agents.defaults.workspace` 指向当前活动的那个。
检测到额外工作区目录时,`openclaw doctor` 会发出警告。
`openclaw doctor` 检测到额外的工作区目录时,会发出警告。
## 工作区文件映射(每个文件的含义)
这些是 OpenClaw 在工作区中预期的标准文件:
以下是 OpenClaw 在工作区内预期的标准文件:
- `AGENTS.md`
- 智能体的操作说明,以及它应如何使用记忆。
- 每次会话开始时加载。
- 很适合放置规则、优先级以及“如何表现”的细节。
- 每次会话开始时都会加载。
- 适合放置规则、优先级和“应如何表现”的细节。
- `SOUL.md`
- 人设、语气和边界。
- 每会话都会加载。
- 指南:[SOUL.md Personality Guide](/concepts/soul)
- 每会话都会加载。
- 指南:[SOUL.md Personality Guide](/zh-CN/concepts/soul)
- `USER.md`
- 用户是谁,以及如何称呼用户。
- 每会话都会加载。
- 关于用户是谁,以及如何称呼用户。
- 每会话都会加载。
- `IDENTITY.md`
- 智能体的名称、风格和 emoji。
- 在 bootstrap 仪式期间创建/更新。
- 智能体的名称、氛围和 emoji。
- 在引导仪式期间创建 / 更新。
- `TOOLS.md`
- 关于你的本地工具和约定的说明。
- 它不控制工具可用性;仅作为指导。
- 它不控制工具可用性;仅作为指导。
- `HEARTBEAT.md`
- 可选的小型检查清单,用于 heartbeat 运行。
- 保持简短,以避免 token 消耗
- 可选的超短清单,用于心跳运行。
- 保持简短,以避免消耗过多 token。
- `BOOT.md`
- 可选的启动检查清单;当启用内部 hooks 时,会在 Gateway 网关重启时执行。
- 保持简短;使用消息工具进行出站发送
- 可选的启动清单;当启用内部 hooks 时,会在 Gateway 网关重启时执行。
- 保持简短;对外发送请使用 message 工具
- `BOOTSTRAP.md`
- 一次性的首次运行仪式。
- 仅为全新工作区创建。
- 仪式完成后请删除它
- 仅为全新工作区创建。
- 仪式完成后将其删除
- `memory/YYYY-MM-DD.md`
- 每日记忆日志(每天一个文件)。
- 建议在会话开始时阅读今天和昨天的内容
- 建议在会话开始时读取今天和昨天的文件
- `MEMORY.md`(可选)
- 整理后的长期记忆。
- 仅在主私有会话中加载(不在共享/群组上下文中加载)。
- 仅在主私有会话中加载(不在共享 / 群组上下文中加载)。
有关工作流和自动记忆刷新,请参见[记忆](/concepts/memory)。
有关工作流和自动记忆刷新,请参见 [Memory](/zh-CN/concepts/memory)。
- `skills/`(可选)
- 工作区专的 Skills。
- 工作区专的 Skills。
- 该工作区中优先级最高的 Skills 位置。
- 当名称冲突时,会覆盖项目智能体 Skills、个人智能体 Skills、托管 Skills、内置 Skills 以及 `skills.load.extraDirs`
- 当名称冲突时,会覆盖项目智能体 Skills、个人智能体 Skills、托管 Skills、内置 Skills以及 `skills.load.extraDirs`
- `canvas/`(可选)
- 用于节点显示的 Canvas UI 文件(例如 `canvas/index.html`)。
如果任何 bootstrap 文件缺失OpenClaw 会向
会话中注入一个“缺失文件”标记并继续。大型 bootstrap 文件在注入时会被截断;
可通过 `agents.defaults.bootstrapMaxChars`默认20000
`agents.defaults.bootstrapTotalMaxChars`默认150000调整限制。
`openclaw setup` 可以重新创建缺失的默认文件,而不会覆盖现有
文件。
如果任何引导文件缺失OpenClaw 会在会话中注入“缺失文件”标记并继续运行。注入时,大型引导文件会被截断;可通过 `agents.defaults.bootstrapMaxChars`默认12000`agents.defaults.bootstrapTotalMaxChars`默认60000调整限制。
`openclaw setup` 可以重新创建缺失的默认文件,而不会覆盖现有文件。
## 哪些内容**不**在工作区中
这些内容位于 `~/.openclaw/` 下,**不应**提交到工作区仓库:
以下内容位于 `~/.openclaw/` 下,**不应**提交到工作区仓库:
- `~/.openclaw/openclaw.json`(配置)
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`(模型鉴权配置OAuth + API 密钥)
- `~/.openclaw/credentials/`(渠道/提供商状态以及旧版 OAuth 导入数据)
- `~/.openclaw/agents/<agentId>/sessions/`(会话转录 + 元数据)
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`(模型凭证配置文件OAuth + API 密钥)
- `~/.openclaw/credentials/`(渠道 / 提供商状态以及旧版 OAuth 导入数据)
- `~/.openclaw/agents/<agentId>/sessions/`(会话转录内容 + 元数据)
- `~/.openclaw/skills/`(托管 Skills
如果你需要迁移会话或配置,请单独复制它们,并确保将其
排除在版本控制之外。
如果你需要迁移会话或配置,请单独复制它们,并确保不要将它们纳入版本控制。
## Git 备份(推荐,私有)
请将工作区视为私有记忆。把它放到一个**私有** git 仓库中,以便
进行备份和恢复。
请将工作区视为私密记忆。把它放入一个**私有** git 仓库中,以便备份和恢复。
请在运行 Gateway 网关的机器上执行以下步骤(工作区就在
那里)。
请在运行 Gateway 网关 的机器上执行这些步骤(工作区就位于那里)。
### 1初始化仓库
如果已安装 git全新的工作区会自动初始化。如果该
工作区尚不是仓库,请运行:
如果已安装 git全新工作区会自动初始化。如果这个工作区还不是仓库请运行
```bash
cd ~/.openclaw/workspace
@ -165,11 +146,11 @@ git commit -m "Add agent workspace"
### 2添加私有远程仓库适合初学者的选项
选项 AGitHub Web UI
选项 AGitHub 网页 UI
1. 在 GitHub 上创建一个新的**私有**仓库。
2. 不要使用 README 初始化(可避免合并冲突)。
3. 复制 HTTPS 远程 URL。
3. 复制 HTTPS 远程仓库 URL。
4. 添加远程仓库并推送:
```bash
@ -178,18 +159,18 @@ git remote add origin <https-url>
git push -u origin main
```
选项 BGitHub CLI`gh`
选项 BGitHub CLI (`gh`)
```bash
gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push
```
选项 CGitLab Web UI
选项 CGitLab 网页 UI
1. 在 GitLab 上创建一个新的**私有**仓库。
2. 不要使用 README 初始化(可避免合并冲突)。
3. 复制 HTTPS 远程 URL。
3. 复制 HTTPS 远程仓库 URL。
4. 添加远程仓库并推送:
```bash
@ -207,16 +188,15 @@ git commit -m "Update memory"
git push
```
## 不要提交密钥
## 不要提交机密信息
即使在私有仓库中,也应避免在工作区存储密钥
即使是在私有仓库中,也要避免在工作区中存储机密
- API 密钥、OAuth 令牌、密码或私凭证。
- API 密钥、OAuth 令牌、密码或私凭证。
- `~/.openclaw/` 下的任何内容。
- 聊天记录原始转储或敏感附件。
- 聊天记录原始导出或敏感附件。
如果你必须存储敏感引用,请使用占位符,并将真实
密钥保存在其他地方(密码管理器、环境变量或 `~/.openclaw/`)。
如果你必须存储敏感引用,请使用占位符,并将真实机密保存在其他位置(密码管理器、环境变量或 `~/.openclaw/`)。
建议的 `.gitignore` 起始内容:
@ -232,20 +212,18 @@ git push
1. 将仓库克隆到目标路径(默认 `~/.openclaw/workspace`)。
2. 在 `~/.openclaw/openclaw.json` 中将 `agents.defaults.workspace` 设置为该路径。
3. 运行 `openclaw setup --workspace <path>` 以填充缺失文件。
4. 如果你还需要会话,请将 `~/.openclaw/agents/<agentId>/sessions/`
旧机器单独复制过来。
3. 运行 `openclaw setup --workspace <path>` 以填充任何缺失的文件。
4. 如果你需要会话,请单独从旧机器复制 `~/.openclaw/agents/<agentId>/sessions/`
## 高级说明
- 多智能体路由可以为不同智能体使用不同工作区。参见
[渠道路由](/channels/channel-routing) 了解路由配置。
- 如果启用了 `agents.defaults.sandbox`,非主会话可以在 `agents.defaults.sandbox.workspaceRoot`
使用按会话划分的沙箱工作区。
- 多智能体路由可以为不同智能体使用不同的工作区。请参见
[Channel routing](/zh-CN/channels/channel-routing) 了解路由配置。
- 如果启用了 `agents.defaults.sandbox`,非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用按会话划分的沙箱工作区。
## 相关内容
- [Standing Orders](/automation/standing-orders) — 工作区文件中的持久指令
- [Heartbeat](/gateway/heartbeat) — HEARTBEAT.md 工作区文件
- [会话](/concepts/session) — 会话存储路径
- [沙箱隔离](/gateway/sandboxing) — 沙箱环境中的工作区访问
- [Standing Orders](/zh-CN/automation/standing-orders) — 工作区文件中的持久指令
- [Heartbeat](/zh-CN/gateway/heartbeat) — `HEARTBEAT.md` 工作区文件
- [Session](/zh-CN/concepts/session) — 会话存储路径
- [Sandboxing](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的工作区访问

View File

@ -1,86 +1,86 @@
---
read_when:
- 你想了解 “context” 在 OpenClaw 中的含义
- 你想了解 “上下文” 在 OpenClaw 中是什么意思
- 你正在调试为什么模型“知道”某些内容(或为什么它忘记了这些内容)
- 你想减少上下文开销(`/context`、`/status`、`/compact`
summary: 上下文:模型会看到什么、它是如何构建的,以及如何检查它
- 你想降低上下文开销(`/context`、`/status`、`/compact`
summary: 上下文:模型所见内容、其构建方式,以及如何检查它
title: 上下文
x-i18n:
generated_at: "2026-04-12T18:22:04Z"
generated_at: "2026-04-18T03:31:58Z"
model: gpt-5.4
provider: openai
source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d
source_hash: 477ccb1d9654968d0e904b6846b32b8c14db6b6c0d3d2ec2b7409639175629f9
source_path: concepts/context.md
workflow: 15
---
# 上下文
“上下文”是 **OpenClaw 在一次运行中发送给模型的全部内容**。它受模型的 **上下文窗口**token 限制)约束。
“上下文” **OpenClaw 在一次运行中发送给模型的全部内容**。它受模型的 **上下文窗口**token 限制)约束。
适合初学者的理解方式
适合初学者的理解模型
- **系统提示词**(由 OpenClaw 构建规则、工具、Skills 列表、时间/运行时信息,以及注入的工作区文件。
- **系统提示词**(由 OpenClaw 构建规则、工具、Skills 列表、时间/运行时,以及注入的工作区文件。
- **对话历史**:你在此会话中的消息 + 助手的消息。
- **工具调用/结果 + 附件**:命令输出、文件读取、图片/音频等。
上下文 _不等同于_memory”memory 可以存储到磁盘并在之后重新加载;上下文则是模型当前窗口中的内容。
上下文 _不等同于_记忆”:记忆可以存储在磁盘上并在之后重新加载;上下文则是模型当前窗口中的内容。
## 快速开始(检查上下文)
- `/status` → 快速查看“我的窗口用了多少?”以及会话设置。
- `/context list` → 查看注入了什么内容 + 大致大小(每个文件 + 总计)。
- `/context detail` → 更深入的明细:按文件、按工具 schema 大小、按 Skills 条目大小,以及系统提示词大小。
- `/usage tokens` → 在普通回复后加每次回复的用量页脚。
- `/compact` → 将较早的历史总结为一条紧凑条目,以释放窗口空间。
- `/context list` → 查看注入了什么 + 大致大小(每个文件 + 总计)。
- `/context detail` → 更深入的拆分:每个文件、每个工具 schema 的大小、每个 skill 条目的大小,以及系统提示词大小。
- `/usage tokens` → 在普通回复后加每次回复的用量页脚。
- `/compact` → 将较早的历史总结为一条精简条目,以释放窗口空间。
另请参阅:[Slash commands](/zh-CN/tools/slash-commands)、[Token use & costs](/zh-CN/reference/token-use)、[Compaction](/zh-CN/concepts/compaction)。
## 示例输出
数值会因模型、提供商、工具策略以及你的工作区内容而有所不同
具体数值会因模型、提供商、工具策略以及你的工作区内容而
### `/context list`
```
🧠 Context breakdown
Workspace: <workspaceDir>
Bootstrap max/file: 20,000 chars
Sandbox: mode=non-main sandboxed=false
System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
🧠 上下文拆分
工作区:<workspaceDir>
Bootstrap 每文件上限12,000 个字符
沙箱:mode=non-main sandboxed=false
系统提示词运行时38,412 个字符(约 9,603 tokProject Context 23,901 个字符(约 5,976 tok
Injected workspace files:
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
- HEARTBEAT.md: MISSING | raw 0 | injected 0
- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)
注入的工作区文件:
- AGENTS.md:正常 | 原始 1,742 个字符(约 436 tok| 注入 1,742 个字符(约 436 tok
- SOUL.md:正常 | 原始 912 个字符(约 228 tok| 注入 912 个字符(约 228 tok
- TOOLS.md:已截断 | 原始 54,210 个字符(约 13,553 tok| 注入 20,962 个字符(约 5,241 tok
- IDENTITY.md:正常 | 原始 211 个字符(约 53 tok| 注入 211 个字符(约 53 tok
- USER.md:正常 | 原始 388 个字符(约 97 tok| 注入 388 个字符(约 97 tok
- HEARTBEAT.md:缺失 | 原始 0 | 注入 0
- BOOTSTRAP.md:正常 | 原始 0 个字符(约 0 tok| 注入 0 个字符(约 0 tok
Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
Tools: read, edit, write, exec, process, browser, message, sessions_send,
Tool list (system prompt text): 1,032 chars (~258 tok)
Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
Tools: (same as above)
Skills 列表系统提示词文本2,184 个字符(约 546 tok12 个 skill
工具read、edit、write、exec、process、browser、message、sessions_send、
工具列表系统提示词文本1,032 个字符(约 258 tok
工具 schemasJSON31,988 个字符(约 7,997 tok计入上下文不显示为文本
工具:(同上)
Session tokens (cached): 14,250 total / ctx=32,000
会话 tokens已缓存总计 14,250 / ctx=32,000
```
### `/context detail`
```
🧠 Context breakdown (detailed)
🧠 上下文拆分(详细)
Top skills (prompt entry size):
- frontend-design: 412 chars (~103 tok)
- oracle: 401 chars (~101 tok)
(+10 more skills)
最大的 skills提示词条目大小
- frontend-design412 个字符(约 103 tok
- oracle401 个字符(约 101 tok
(另有 10 个)
Top tools (schema size):
- browser: 9,812 chars (~2,453 tok)
- exec: 6,240 chars (~1,560 tok)
(+N more tools)
最大的工具schema 大小):
- browser9,812 个字符(约 2,453 tok
- exec6,240 个字符(约 1,560 tok
(另有 N 个)
```
## 哪些内容会计入上下文窗口
@ -90,22 +90,22 @@ Top tools (schema size):
- 系统提示词(所有部分)。
- 对话历史。
- 工具调用 + 工具结果。
- 附件/转录内容(图/音频/文件)。
- 压缩摘要和剪产物。
- 提供商的“包装层”或隐藏头信息(你看不到,但依然计入)。
- 附件/转录内容(图/音频/文件)。
- 压缩摘要和剪产物。
- 提供商“包装层”或隐藏头部(你看不到,但仍会计数)。
## OpenClaw 如何构建系统提示词
系统提示词 **OpenClaw 持有**,并在每次运行时重新构建。它包括:
系统提示词 **OpenClaw 持有**,并且会在每次运行时重新构建。它包括:
- 工具列表 + 简短描述
- 工具列表 + 简短说明
- Skills 列表(仅元数据;见下文)。
- 工作区位置。
- 时间UTC + 如已配置则包含转换后的用户时间)。
- 运行时元数据(主机/OS/模型/thinking)。
- **Project Context**注入工作区 bootstrap 文件。
- 时间UTC + 如已配置则转换后的用户时间)。
- 运行时元数据(主机/操作系统/模型/思考)。
- **Project Context** 下注入工作区 bootstrap 文件。
完整细分说明请参阅[System Prompt](/zh-CN/concepts/system-prompt)。
完整拆分参见[System Prompt](/zh-CN/concepts/system-prompt)。
## 注入的工作区文件Project Context
@ -119,55 +119,56 @@ Top tools (schema size):
- `HEARTBEAT.md`
- `BOOTSTRAP.md`(仅首次运行)
大文件会按单文件通过 `agents.defaults.bootstrapMaxChars`(默认 `20000` 字符进行截断。OpenClaw 还会对跨文件的 bootstrap 注入总量施加总上限 `agents.defaults.bootstrapTotalMaxChars`(默认 `150000` 字符)。`/context` 会显示 **原始大小与注入大小**,以及是否发生了截断。
大文件会根据 `agents.defaults.bootstrapMaxChars`(默认 `12000` 个字符按文件截断。OpenClaw 还会通过 `agents.defaults.bootstrapTotalMaxChars`(默认 `60000` 个字符)对所有文件的 bootstrap 注入总量设置上限。`/context` 会显示 **原始大小与注入大小**,以及是否发生了截断。
发生截断时,运行时可以在 Project Context 下方注入一个提示词内警告块。可通过 `agents.defaults.bootstrapPromptTruncationWarning` 配置此行为(`off`、`once`、`always`;默认 `once`)。
## Skills默认注入与按需加载
## Skills注入与按需加载
系统提示词会包含一个紧凑的 **Skills 列表**(名称 + 描述 + 位置)。这个列表本身就有实际开销。
系统提示词中包含一个精简的 **Skills 列表**(名称 + 描述 + 位置)。这个列表本身会带来真实的开销。
Skill 说明 _默认不会_ 被包含。模型应当只在需要时才使用 `read` 去读取该 Skill 的 `SKILL.md`
默认情况下不会包含 skill 指令本身。模型应当只在需要时 `read` 该 skill 的 `SKILL.md`
## Tools有两成本
## Tools有两成本
Tools 会通过两种方式影响上下文:
工具会以两种方式影响上下文:
1. 系统提示词中的 **工具列表文本**也就是你看到的 “Tooling”
2. **工具 schema**JSON。这些内容会发送给模型以便它可以调用工具。即使你看不到其纯文本形式它们依然会计入上下文。
1. 系统提示词中的 **工具列表文本**(你看到的 “Tooling”
2. **工具 schemas**JSON。这些会发送给模型以便它调用工具。尽管你不会将它们视为普通文本看到但它们仍计入上下文。
`/context detail` 会拆分显示最大的工具 schema这样你就能看出主要开销来自哪里。
`/context detail` 会拆分最大的工具 schema让你看到主要开销来自哪里。
## 命令、指令和“内联快捷方式”
Slash commands 由 Gateway 网关处理。这里有几种不同的行为:
Slash 命令由 Gateway 网关处理。这里有几种不同的行为:
- **独立命令**:如果一条消息只有 `/...`它会作为命令运行。
- **指令**`/think`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/model`、`/queue` 会在模型看到消息前被剥离。
- 只有指令的消息会持久化会话设置。
- **独立命令**:如果一条消息只有 `/...`则会作为命令执行。
- **指令**`/think`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/model`、`/queue` 会在模型看到消息前被剥离。
- 仅含指令的消息会持久化会话设置。
- 普通消息中的内联指令会作为单条消息级别的提示。
- **内联快捷方式**(仅限 allowlist 发送者):普通消息中的某些 `/...` token 可以立即执行例如“hey /status”并会在模型看到剩余文本前被剥离。
- **内联快捷方式**(仅允许列表中的发送者):普通消息中的某些 `/...` token 可以立即执行例如“hey /status”并会在模型看到剩余文本前被剥离。
详情请参阅[Slash commands](/zh-CN/tools/slash-commands)。
详情参见[Slash commands](/zh-CN/tools/slash-commands)。
## 会话、压缩与裁剪(哪些内容会持久化)
## 会话、压缩与修剪(哪些会持久化)
跨消息持久化哪些内容,取决于具体机制:
跨消息持久化的内容取决于具体机制:
- **普通历史**持久保存在会话转录中,直到按策略被压缩/裁剪。
- **压缩**把摘要持久化到转录中,并保留最近的消息
- **裁剪** 会从某次运行的 _内存中_ 提示词里移除较旧的工具结果,但不会改写转录。
- **普通历史**保存在会话转录中,直到被策略压缩/修剪。
- **压缩**将摘要持久化进转录中,并保留最近的消息不变
- **修剪** 会从某次运行的 _内存中_ 提示词里移除旧的工具结果,但不会重写转录。
文档: [Session](/zh-CN/concepts/session)、[Compaction](/zh-CN/concepts/compaction)、[Session pruning](/zh-CN/concepts/session-pruning)。
文档参见[Session](/zh-CN/concepts/session)、[Compaction](/zh-CN/concepts/compaction)、[Session pruning](/zh-CN/concepts/session-pruning)。
默认情况下OpenClaw 使用内置的 `legacy` 上下文引擎来进行组装和压缩。如果你安装了一个提供 `kind: "context-engine"` 的插件,并通过 `plugins.slots.contextEngine` 选择它OpenClaw 就会把上下文组装、`/compact` 以及相关的 subagent 上下文生命周期 hook 委托给该引擎。`ownsCompaction: false` 不会自动回退到 legacy 引擎;当前激活的引擎仍必须正确实现 `compact()`。完整的可插拔接口、生命周期 hook 和配置请参阅 [Context Engine](/zh-CN/concepts/context-engine)。
默认情况下OpenClaw 使用内置的 `legacy` 上下文引擎来进行组装和压缩。
如果你安装了一个提供 `kind: "context-engine"` 的插件,并通过 `plugins.slots.contextEngine` 选中它OpenClaw 会将上下文组装、`/compact` 以及相关的子智能体上下文生命周期 hook 委托给该引擎。`ownsCompaction: false` 不会自动回退到 legacy 引擎;当前激活的引擎仍必须正确实现 `compact()`。完整的可插拔接口、生命周期 hook 和配置请参见 [Context Engine](/zh-CN/concepts/context-engine)。
## `/context` 实际报告的是什么
在可用时,`/context` 会优先使用最新的 **运行时构建** 系统提示词报告:
在可用时,`/context` 会优先使用最新的 **运行时构建** 系统提示词报告:
- `System prompt (run)` = 从上一次嵌入式(支持工具)运行中捕获,并持久化在会话存储中
- `System prompt (estimate)` = 当不存在运行报告时动态计算得出(或者在使用不会生成该报告的 CLI 后端运行时)。
- `System prompt (run)` = 从上一次嵌入式(可调用工具)运行中捕获,并持久化到会话存储中的报告
- `System prompt (estimate)` = 在没有运行时报告时即时计算得出(或通过不生成该报告的 CLI 后端运行时)。
无论哪种方式,它都会报告大小和主要贡献项;它 **不会** 输出完整的系统提示词或工具 schema。
@ -175,5 +176,5 @@ Slash commands 由 Gateway 网关处理。这里有几种不同的行为:
- [Context Engine](/zh-CN/concepts/context-engine) — 通过插件进行自定义上下文注入
- [Compaction](/zh-CN/concepts/compaction) — 总结长对话
- [System Prompt](/zh-CN/concepts/system-prompt) — 系统提示词如何构建
- [Agent Loop](/zh-CN/concepts/agent-loop) — 完整的智能体执行循环
- [System Prompt](/zh-CN/concepts/system-prompt) — 系统提示词如何构建
- [Agent Loop](/zh-CN/concepts/agent-loop) — 完整的智能体执行周期

View File

@ -5,74 +5,74 @@ read_when:
summary: OpenClaw 系统提示词包含什么内容,以及它是如何组装的
title: 系统提示词
x-i18n:
generated_at: "2026-04-15T18:07:35Z"
generated_at: "2026-04-18T03:31:58Z"
model: gpt-5.4
provider: openai
source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4
source_hash: e60705994cebdd9768926168cb1c6d17ab717d7ff02353a5d5e7478ba8191cab
source_path: concepts/system-prompt.md
workflow: 15
---
# 系统提示词
OpenClaw 会为每次智能体运行构建一个自定义系统提示词。该提示词**由 OpenClaw 拥有**,不使用 `pi-coding-agent` 的默认提示词。
OpenClaw 会为每次智能体运行构建一个自定义系统提示词。该提示词**OpenClaw 自有**,不使用 pi-coding-agent 的默认提示词。
提示词由 OpenClaw 组装,并注入到每次智能体运行中。
提示词由 OpenClaw 组装,并注入到每次智能体运行中。
提供商插件可以贡献具备缓存感知能力的提示词指导,而无需替换完整的 OpenClaw 自有提示词。提供商运行时可以:
- 替换一小组具名核心部分(`interaction_style`、`tool_call_style`、`execution_bias`
- 在提示词缓存边界上注入一个**稳定前缀**
- 在提示词缓存边界下注入一个**动态后缀**
- 在提示词缓存边界上注入**稳定前缀**
- 在提示词缓存边界下注入**动态后缀**
将提供商自有贡献用于按模型家族进行特定调优。保留旧版的 `before_prompt_build` 提示词变更机制,用于兼容性需求或真正的全局提示词更改,而不是常规的提供商行为。
对于特定模型家族的调优,请使用提供商自有贡献。将旧版 `before_prompt_build` 提示词变更保留用于兼容性场景或真正的全局提示词更改,而不是普通的提供商行为。
## 结构
该提示词刻意保持紧凑,并使用固定部分:
- **工具**:结构化工具事实来源提醒,以及运行时工具使用指导。
- **工具使用**:结构化工具事实来源提醒,以及运行时工具使用指导。
- **安全**:简短的护栏提醒,用于避免追求权力的行为或绕过监督。
- **Skills**(可用时):告诉模型如何按需加载 Skills 指令。
- **OpenClaw 自更新**:如何使用 `config.schema.lookup` 安全检查配置,使用 `config.patch` 修补配置,使用 `config.apply` 替换完整配置,以及仅在用户明确请求时运行 `update.run`。仅限所有者使用`gateway` 工具也会拒绝重写 `tools.exec.ask` / `tools.exec.security`,包括会规范化到这些受保护执行路径的旧版 `tools.bash.*` 别名。
- **Skills**(可用时):告诉模型如何按需加载 Skill 指令。
- **OpenClaw 自更新**:如何安全地使用 `config.schema.lookup` 检查配置,使用 `config.patch` 修补配置,使用 `config.apply` 替换完整配置,以及仅在用户明确请求时运行 `update.run`。仅限所有者的 `gateway` 工具也会拒绝重写 `tools.exec.ask` / `tools.exec.security`,包括会规范化到这些受保护 exec 路径的旧版 `tools.bash.*` 别名。
- **工作区**:工作目录(`agents.defaults.workspace`)。
- **文档**OpenClaw 文档的本地路径(仓库或 npm 包)以及何时阅读它们。
- **工作区文件(已注入)**:表示引导文件已包含在下方
- **沙箱**(启用时):表示运行时处于沙箱隔离状态、沙箱路径以及是否可使用提权执行
- **文档**OpenClaw 文档的本地路径(仓库或 npm 包)以及何时阅读它们。
- **工作区文件(已注入)**:表示下方包含引导文件。
- **沙箱**(启用时):表示运行时处于沙箱隔离中、沙箱路径,以及是否可使用提权 exec
- **当前日期与时间**:用户本地时间、时区和时间格式。
- **回复标签**:受支持提供商的可选回复标签语法。
- **心跳**当默认智能体启用心跳时的心跳提示词和确认行为
- **运行时**:主机、操作系统、Node、模型、仓库根目录检测到时)、思考级别(一行)。
- **回复标签**适用于受支持提供商的可选回复标签语法。
- **心跳**心跳提示词和确认行为,以及默认智能体启用心跳时的相关说明
- **运行时**:主机、操作系统、node、模型、仓库根目录若检测到)、思考级别(一行)。
- **推理**:当前可见性级别 + `/reasoning` 切换提示。
“工具”部分还包含针对长时间运行任务的运行时指导:
“工具使用”部分还包含针对长时间运行工作的运行时指导:
- 对未来的后续跟进(“稍后再检查”、提醒、周期性工作)使用 `cron`,而不是使用 `exec` 睡眠循环、`yieldMs` 延迟技巧或反复轮询 `process`
- 仅`exec` / `process` 用于那些现在启动并将在后台持续运行的命令
- 启用自动完成唤醒时,只启动命令一次,并依赖其输出内容或失败时的基于推送的唤醒路径
- 对未来跟进(“稍后回来查看”、提醒、重复性工作)使用 cron而不是使用 `exec` 睡眠循环、`yieldMs` 延迟技巧或重复的 `process` 轮询
- 仅对“立即启动并继续在后台运行”的命令使用 `exec` / `process`
- 启用自动完成唤醒时,只启动一次命令,并在其输出内容或失败时依赖基于推送的唤醒路径
- 当你需要检查正在运行命令的日志、状态、输入或进行干预时,使用 `process`
- 如果任务更大,优先使用 `sessions_spawn`;子智能体完成采用基于推送的方式,并会自动向请求方回报
- 不要仅仅为了等待完成而循环轮询 `subagents list` / `sessions_list`
- 如果任务更大,优先使用 `sessions_spawn`;子智能体完成采用基于推送的方式,并会自动向请求方发回通知
- 不要循环轮询 `subagents list` / `sessions_list` 来单纯等待完成
当实验性的 `update_plan` 工具启用时,“工具”部分还会告诉模型:仅将其用于非平凡的多步骤工作,始终只保留一个 `in_progress` 步骤,并避免在每次更新后重复整个计划。
启用实验性 `update_plan` 工具时,“工具使用”还会告诉模型仅将其用于非平凡的多步骤工作,始终只保留一个 `in_progress` 步骤,并避免在每次更新后重复整个计划。
系统提示词中的安全护栏是建议性的。它们用于引导模型行为,但不强制执行策略。要实现硬性约束,请使用工具策略、执行审批、沙箱隔离和渠道允许列表;设计上也允许运维人员禁用这些机制。
系统提示词中的安全护栏属于建议性内容。它们用于引导模型行为但不强制执行策略。若要进行硬性约束请使用工具策略、exec 审批、沙箱隔离和渠道允许列表;运营者可以按设计禁用这些机制。
具有原生审批卡片 / 按钮的渠道上,运行时提示词现在会告诉智能体优先依赖该原生审批 UI。只有当工具结果表明聊天审批不可用或者手动审批是唯一途径时才应包含手动 `/approve` 命令。
带有原生审批卡片 / 按钮的渠道中,运行时提示词现在会告诉智能体优先依赖该原生审批 UI。只有当工具结果表明聊天审批不可用或者手动审批是唯一途径时才应包含手动 `/approve` 命令。
## 提示词模式
OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为每次运行设置一个 `promptMode`(不是面向用户的配置):
- `full`(默认):包含上所有部分。
- `minimal`:用于子智能体;省略**Skills**、**Memory Recall**、**OpenClaw 自更新**、**模型别名**、**用户身份**、**回复标签**、**消息传递**、**静默回复**和**心跳**。工具、**安全**、工作区、沙箱、当前日期与时间(已知)、运行时以及注入的上下文仍然可用。
- `none`返回基础身份行。
- `full`(默认):包含上面的所有部分。
- `minimal`:用于子智能体;省略 **Skills**、**记忆召回**、**OpenClaw 自更新**、**模型别名**、**用户身份**、**回复标签**、**消息传递**、**静默回复** **心跳**。工具使用、**安全**、工作区、沙箱、当前日期与时间(已知)、运行时以及注入的上下文仍然可用。
- `none`返回基础身份行。
`promptMode=minimal` 时,额外注入的提示词会标记为**子智能体上下文**,而不是**群聊上下文**。
`promptMode=minimal` 时,额外注入的提示词会标记为 **子智能体上下文**,而不是 **群聊上下文**
## 工作区引导注入
引导文件会被裁剪后追加在 **Project Context** 下,以便模型无需显式读取就能看到身份和配置文件上下文:
引导文件会被裁剪并追加到 **项目上下文** 下,这样模型无需显式读取也能看到身份和配置档上下文:
- `AGENTS.md`
- `SOUL.md`
@ -83,38 +83,38 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为
- `BOOTSTRAP.md`(仅在全新工作区中)
- 存在时使用 `MEMORY.md`,否则回退为小写的 `memory.md`
除非适用文件特定的门控规则,否则以上所有文件都会在每一轮中**注入到上下文窗口中**。当默认智能体禁用心跳,或 `agents.defaults.heartbeat.includeSystemPromptSection` 为 false 时,正常运行中会省略 `HEARTBEAT.md`。请保持注入文件简洁——尤其是 `MEMORY.md`,它会随着时间增长,并可能导致上下文使用量意外升高以及更频繁的压缩。
除非有特定文件的门控规则,否则所有这些文件都会在每一轮**注入到上下文窗口中**。在普通运行中,如果默认智能体禁用了心跳,或 `agents.defaults.heartbeat.includeSystemPromptSection` 为 false会省略 `HEARTBEAT.md`。请保持注入文件简洁——尤其是 `MEMORY.md`,它会随着时间增长,并可能导致意外偏高的上下文使用量以及更频繁的压缩。
> **注意:** `memory/*.md` 每日文件**不属于**常规引导的 Project Context。在普通轮次中它们会通过 `memory_search``memory_get` 工具按需访问,因此除非模型显式读取,否则不会计入上下文窗口。纯 `/new``/reset` 轮次是例外:运行时可以把最近的每日记忆作为一次性启动上下文块预置到第一轮
> **注意:** `memory/*.md` 每日文件**不属于**常规引导“项目上下文”的一部分。在普通轮次中,它们通过 `memory_search``memory_get` 工具按需访问,因此除非模型显式读取,否则不会计入上下文窗口。纯 `/new``/reset` 轮次是例外:运行时可以将最近的每日记忆作为一次性的启动上下文块预置到第一轮中
文件会以标记形式截断。每个文件的最大大小由 `agents.defaults.bootstrapMaxChars` 控制(默认20000。跨文件注入的引导内容总量上限由 `agents.defaults.bootstrapTotalMaxChars` 控制(默认150000。缺失文件会注入一个简短的缺失文件标记。发生截断时OpenClaw 可以在 Project Context 中注入一个警告块;使用 `agents.defaults.bootstrapPromptTruncationWarning` 控制(`off`、`once`、`always`;默认`once`)。
型文件会带有标记后被截断。每个文件的最大大小由 `agents.defaults.bootstrapMaxChars` 控制(默认:12000。跨文件注入的引导内容总量上限由 `agents.defaults.bootstrapTotalMaxChars` 控制(默认60000。缺失文件会注入一个简短的缺失文件标记。发生截断时OpenClaw 可以在“项目上下文”中注入一段警告块;可通过 `agents.defaults.bootstrapPromptTruncationWarning` 控制(`off`、`once`、`always`;默认:`once`)。
子智能体会话注入 `AGENTS.md``TOOLS.md`(其他引导文件会被过滤掉,以保持子智能体上下文较小)。
子智能体会话注入 `AGENTS.md``TOOLS.md`(其他引导文件会被过滤掉,以保持子智能体上下文较小)。
内部 hooks 可以通过 `agent:bootstrap` 拦截此步骤,以变更或替换注入的引导文件(例如将 `SOUL.md` 替换为其他 persona
内部 hooks 可以通过 `agent:bootstrap` 拦截这一步,以变更或替换注入的引导文件(例如将 `SOUL.md` 替换为其他 persona
如果你想让智能体听起来不那么通用,从 [SOUL.md Personality Guide](/zh-CN/concepts/soul) 开始。
如果你想让智能体听起来不那么通用,可以从 [SOUL.md Personality Guide](/zh-CN/concepts/soul) 开始。
要检查每个注入文件贡献了多少内容(原始内容与注入内容、截断情况,以及工具 schema 开销),请使用 `/context list``/context detail`。参见 [Context](/zh-CN/concepts/context)。
如果你想检查每个注入文件各自贡献了多少内容(原始内容 vs 注入内容、截断情况,以及工具 schema 开销),请使用 `/context list``/context detail`。参见 [上下文](/zh-CN/concepts/context)。
## 时间处理
当已知用户时区时,系统提示词会包含一个专门的**当前日期与时间**部分。为了保持提示词缓存稳定,它现在只包含**时区**(不包含动态时钟或时间格式)。
当已知用户时区时,系统提示词会包含专门的**当前日期与时间**部分。为了保持提示词缓存稳定,它现在只包含**时区**(不包含动态时钟或时间格式)。
当智能体需要当前时间时,请使用 `session_status`;状态卡中包含时间戳行。该工具还可以选择设置每个会话的模型覆盖(`model=default` 会清除它)。
当智能体需要当前时间时,请使用 `session_status`;状态卡中包含时间戳行。该工具还可以选择设置会话级模型覆盖(`model=default` 会清除它)。
配置方式如下
配置
- `agents.defaults.userTimezone`
- `agents.defaults.timeFormat``auto` | `12` | `24`
完整行为细节请参见 [Date & Time](/zh-CN/date-time)。
完整行为细节请参见 [日期与时间](/zh-CN/date-time)。
## Skills
当存在符合条件的 SkillsOpenClaw 会注入一个紧凑的**可用 Skills 列表**`formatSkillsForPrompt`),其中包含每个 skill 的**文件路径**。提示词会指示模型使用 `read` 加载所列位置(工作区、托管或内置)中的 `SKILL.md`。如果没有符合条件的 Skills,则省略 Skills 部分。
当存在符合条件的 Skill 时OpenClaw 会注入一个紧凑的**可用 Skills 列表**`formatSkillsForPrompt`),其中包含每个 Skill 的**文件路径**。提示词会指示模型使用 `read` 加载所列位置(工作区、托管或内置)中的 SKILL.md。如果没有符合条件的 Skill则省略 Skills 部分。
资格条件包括 skill 元数据门控、运行时环境 / 配置检查,以及配置了 `agents.defaults.skills``agents.list[].skills`的有效智能体 skill 允许列表。
资格条件包括 Skill 元数据门控、运行时环境 / 配置检查,以及配置了 `agents.defaults.skills``agents.list[].skills`生效的智能体 Skill 允许列表。
```
<available_skills>
@ -126,20 +126,20 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为
</available_skills>
```
这样可以保持基础提示词较小,同时仍能启用有针对性的 skill 使用。
这样可以在保持基础提示词较小的同时,仍支持有针对性的 Skill 使用。
Skills 列表预算由 Skills 子系统负责
Skills 列表预算由 Skills 子系统管理
- 全局默认值:`skills.limits.maxSkillsPromptChars`
- 每智能体覆盖:`agents.list[].skillsLimits.maxSkillsPromptChars`
- 每智能体覆盖`agents.list[].skillsLimits.maxSkillsPromptChars`
通用的有界运行时摘录使用不同的配置面:
- `agents.defaults.contextLimits.*`
- `agents.list[].contextLimits.*`
这种拆分使 Skills 大小控制与运行时读取 / 注入大小控制分离,例如 `memory_get`、实时工具结果以及压缩后的 `AGENTS.md` 刷新。
这种划分将 Skills 大小控制与运行时读取 / 注入大小控制分开,例如 `memory_get`、实时工具结果,以及压缩后对 `AGENTS.md`刷新。
## 文档
可用时,系统提示词会包含一个**文档**部分,指向本地 OpenClaw 文档目录(仓库工作区中的 `docs/` 或内置的 npm 包文档),并同时说明公共镜像、源代码仓库、社区 Discord以及用于发现 Skills 的 ClawHub[https://clawhub.ai](https://clawhub.ai))。提示词会指示模型优先查阅本地文档,以了解 OpenClaw 的行为、命令、配置或架构,并在可能时自行运行 `openclaw status`(仅在无权访问时才询问用户)。
可用时,系统提示词会包含一个**文档**部分,指向本地 OpenClaw 文档目录(仓库工作区中的 `docs/` 或内置的 npm 包文档),并且还会说明公开镜像、源代码仓库、社区 Discord以及用于发现 Skills 的 ClawHub[https://clawhub.ai](https://clawhub.ai))。提示词会指示模型在涉及 OpenClaw 行为、命令、配置或架构时优先查阅本地文档,并在可能的情况下自行运行 `openclaw status`(只有在无权访问时才询问用户)。

File diff suppressed because it is too large Load Diff