From 19fc3b17f1355a4f5e4df35f7a2d8a3c5946b64a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 23 Apr 2026 15:15:02 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/memory-qmd.md | 61 +++++++------- docs/zh-CN/concepts/system-prompt.md | 106 ++++++++++++------------- docs/zh-CN/reference/AGENTS.default.md | 94 +++++++++++----------- 3 files changed, 131 insertions(+), 130 deletions(-) diff --git a/docs/zh-CN/concepts/memory-qmd.md b/docs/zh-CN/concepts/memory-qmd.md index 1b762fd04..13203a25f 100644 --- a/docs/zh-CN/concepts/memory-qmd.md +++ b/docs/zh-CN/concepts/memory-qmd.md @@ -1,23 +1,23 @@ --- read_when: - 你想将 QMD 设置为你的记忆后端 - - 你想要高级记忆功能，例如重排序或额外的索引路径 + - 你希望使用高级记忆功能，例如重排序或额外的索引路径 summary: 本地优先的搜索 sidecar，支持 BM25、向量、重排序和查询扩展 -title: QMD Memory Engine +title: QMD 记忆引擎 x-i18n: - generated_at: "2026-04-12T17:53:41Z" + generated_at: "2026-04-23T15:14:07Z" model: gpt-5.4 provider: openai - source_hash: 27afc996b959d71caed964a3cae437e0e29721728b30ebe7f014db124c88da04 + source_hash: 406e271629c74a5e2c372d4227582802e235a390b7201af195de27ebb16866e7 source_path: concepts/memory-qmd.md workflow: 15 --- -# QMD Memory Engine +# QMD 记忆引擎 -[QMD](https://github.com/tobi/qmd) 是一个与 OpenClaw 一起运行的本地优先搜索 sidecar。它将 BM25、向量搜索和重排序整合到一个二进制文件中，并且可以为你的工作区记忆文件之外的内容建立索引。 +[QMD](https://github.com/tobi/qmd) 是一个本地优先的搜索 sidecar，与 OpenClaw 一起运行。它将 BM25、向量搜索和重排序整合到同一个二进制文件中，并且可以为你的工作区记忆文件之外的内容建立索引。 -## 相比内置功能增加了什么 +## 相比内置功能新增了什么 - **重排序和查询扩展**，以获得更好的召回效果。 - **为额外目录建立索引** —— 项目文档、团队笔记、磁盘上的任何内容。 @@ -30,9 +30,9 @@ x-i18n: ### 前提条件 - 安装 QMD：`npm install -g @tobilu/qmd` 或 `bun install -g @tobilu/qmd` -- 允许扩展的 SQLite 构建版本（在 macOS 上使用 `brew install sqlite`）。 -- QMD 必须位于 Gateway 网关的 `PATH` 上。 -- macOS 和 Linux 开箱即用。Windows 通过 WSL2 的支持最佳。 +- 支持扩展的 SQLite 构建版本（在 macOS 上可使用 `brew install sqlite`）。 +- QMD 必须在 Gateway 网关的 `PATH` 上。 +- macOS 和 Linux 可开箱即用。Windows 通过 WSL2 获得最佳支持。 ### 启用 @@ -44,23 +44,23 @@ x-i18n: } ``` -OpenClaw 会在 `~/.openclaw/agents//qmd/` 下创建一个自包含的 QMD 主目录，并自动管理 sidecar 生命周期 —— 集合、更新和嵌入运行都会为你处理。它会优先使用当前的 QMD 集合和 MCP 查询格式，但在需要时仍会回退到旧版 `--mask` 集合标志和较旧的 MCP 工具名称。 +OpenClaw 会在 `~/.openclaw/agents//qmd/` 下创建一个自包含的 QMD 主目录，并自动管理 sidecar 生命周期 —— 集合、更新和嵌入运行都由它为你处理。它会优先使用当前的 QMD collection 和 MCP query 形态，但在需要时仍会回退到旧版的 `--mask` collection 标志和更早的 MCP 工具名称。 ## sidecar 的工作方式 -- OpenClaw 会根据你的工作区记忆文件以及任何已配置的 `memory.qmd.paths` 创建集合，然后在启动时和定期执行 `qmd update` + `qmd embed`（默认每 5 分钟一次）。 -- 默认工作区集合会跟踪 `MEMORY.md` 以及 `memory/` 目录树。小写的 `memory.md` 仍然只是启动引导回退项，而不是单独的 QMD 集合。 -- 启动刷新会在后台运行，因此不会阻塞聊天启动。 -- 搜索会使用配置的 `searchMode`（默认：`search`；也支持 `vsearch` 和 `query`）。如果某种模式失败，OpenClaw 会使用 `qmd query` 重试。 -- 如果 QMD 完全失败，OpenClaw 会回退到内置 SQLite 引擎。 +- OpenClaw 会根据你的工作区记忆文件以及任何已配置的 `memory.qmd.paths` 创建集合，然后在启动时和周期性地运行 `qmd update` + `qmd embed`（默认每 5 分钟一次）。 +- 默认工作区集合会跟踪 `MEMORY.md` 以及 `memory/` 目录树。小写的 `memory.md` 不会作为根记忆文件建立索引。 +- 启动时刷新会在后台运行，因此不会阻塞聊天启动。 +- 搜索会使用已配置的 `searchMode`（默认：`search`；也支持 `vsearch` 和 `query`）。如果某种模式失败，OpenClaw 会使用 `qmd query` 重试。 +- 如果 QMD 完全失败，OpenClaw 会回退到内置的 SQLite 引擎。 -首次搜索可能会比较慢 —— QMD 会在第一次运行 `qmd query` 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。 +首次搜索可能会较慢 —— QMD 会在第一次运行 `qmd query` 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。 ## 模型覆盖 -QMD 模型环境变量会从 Gateway 网关进程原样透传，因此你可以全局调整 QMD，而无需新增 OpenClaw 配置： +QMD 模型环境变量会从 Gateway 网关进程原样透传，因此你可以在不添加新的 OpenClaw 配置的情况下全局调整 QMD： ```bash export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf" @@ -68,11 +68,11 @@ export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf" export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" ``` -更改嵌入模型后，请重新运行嵌入，以确保索引与新的向量空间匹配。 +更改嵌入模型后，请重新运行嵌入，以便索引与新的向量空间匹配。 ## 为额外路径建立索引 -将 QMD 指向附加目录，使其可被搜索： +将 QMD 指向附加目录以使其可搜索： ```json5 { @@ -85,7 +85,7 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" } ``` -来自额外路径的片段会在搜索结果中显示为 `qmd//`。`memory_get` 能识别此前缀，并从正确的集合根目录读取。 +来自额外路径的片段会在搜索结果中显示为 `qmd//`。`memory_get` 能识别这个前缀，并从正确的 collection 根目录读取内容。 ## 为会话转录建立索引 @@ -102,11 +102,11 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" } ``` -转录会以经过净化的用户/助手轮次形式导出到专用的 QMD 集合中，位置为 `~/.openclaw/agents//qmd/sessions/`。 +转录内容会作为已清理的用户 / 助手轮次导出到专用的 QMD collection 中，位于 `~/.openclaw/agents//qmd/sessions/`。 ## 搜索范围 -默认情况下，QMD 搜索结果会显示在私信和渠道会话中（不包括群组）。可通过配置 `memory.qmd.scope` 来更改： +默认情况下，QMD 搜索结果会出现在私信和渠道会话中（不包括群组）。可配置 `memory.qmd.scope` 来更改此行为： ```json5 { @@ -121,11 +121,11 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" } ``` -当范围阻止搜索时，OpenClaw 会记录一条警告日志，其中包含推导出的渠道和聊天类型，以便更容易调试空结果。 +当范围规则拒绝搜索时，OpenClaw 会记录一条警告日志，其中包含推导出的渠道和聊天类型，从而让空结果更容易调试。 ## 引用 -当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含 `Source: ` 页脚。将 `memory.citations = "off"` 可省略该页脚，同时仍会在内部将路径传递给智能体。 +当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含一个 `Source: ` 页脚。将 `memory.citations = "off"` 可省略该页脚，同时仍会在内部将路径传递给智能体。 ## 何时使用 @@ -136,22 +136,23 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf" - 回忆过去的会话对话。 - 完全本地的搜索，无需 API 密钥。 -对于更简单的设置，[内置引擎](/zh-CN/concepts/memory-builtin) 在无需额外依赖的情况下也能很好地工作。 +对于更简单的设置，[内置引擎](/zh-CN/concepts/memory-builtin) 在没有额外依赖的情况下也能很好地工作。 ## 故障排除 -**找不到 QMD？** 请确保该二进制文件位于 Gateway 网关的 `PATH` 上。如果 OpenClaw 作为服务运行，请创建符号链接： +**找不到 QMD？** 请确保该二进制文件位于 Gateway 网关的 `PATH` 上。如果 OpenClaw 作为服务运行，请创建一个符号链接： `sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`。 -**首次搜索非常慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录运行 `qmd query "test"` 进行预热。 +**首次搜索非常慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录运行 `qmd query "test"` 来预热。 **搜索超时？** 增加 `memory.qmd.limits.timeoutMs`（默认：4000ms）。对于较慢的硬件，可设置为 `120000`。 **群聊中结果为空？** 检查 `memory.qmd.scope` —— 默认仅允许私信和渠道会话。 **工作区可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？** -QMD 当前的遍历遵循底层 QMD 扫描器的行为，而不是 OpenClaw 内置的符号链接规则。在 QMD 提供循环安全遍历或显式排除控制之前，请将临时 monorepo 检出保存在 `.tmp/` 等隐藏目录下，或放在已建立索引的 QMD 根目录之外。 +QMD 当前的遍历遵循底层 QMD 扫描器的行为，而不是 OpenClaw 内置的符号链接规则。在 QMD 提供安全的循环遍历或显式排除控制之前，请将临时 monorepo 检出保存在诸如 `.tmp/` 之类的隐藏目录下，或放在已建立索引的 QMD 根目录之外。 ## 配置 -有关完整配置范围（`memory.qmd.*`）、搜索模式、更新间隔、范围规则以及所有其他可调项，请参阅[记忆配置参考](/zh-CN/reference/memory-config)。 +有关完整的配置范围（`memory.qmd.*`）、搜索模式、更新间隔、范围规则以及所有其他可调项，请参阅 +[记忆配置参考](/zh-CN/reference/memory-config)。 diff --git a/docs/zh-CN/concepts/system-prompt.md b/docs/zh-CN/concepts/system-prompt.md index 521aa4592..433258493 100644 --- a/docs/zh-CN/concepts/system-prompt.md +++ b/docs/zh-CN/concepts/system-prompt.md @@ -2,80 +2,80 @@ read_when: - 编辑系统提示词文本、工具列表或时间/心跳部分 - 更改工作区引导或 Skills 注入行为 -summary: OpenClaw 系统提示词包含什么内容，以及它是如何组装的 +summary: OpenClaw 系统提示词包含什么，以及它是如何组装的 title: 系统提示词 x-i18n: - generated_at: "2026-04-21T03:21:06Z" + generated_at: "2026-04-23T15:14:09Z" model: gpt-5.4 provider: openai - source_hash: bc7b887865830e29bcbfb7f88a12fe04f490eec64cb745fc4534051b63a862dc + source_hash: 489155f8916844b1926b2190196dd1926a6e24089b1f4b77e44d7cf27b45ce69 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` 提示词变更机制用于兼容性场景或真正的全局提示词更改，而不是常规提供商行为。 -OpenAI GPT-5 系列覆盖层会保持核心执行规则简洁，同时增加模型特定指引，涵盖角色锁定、简洁输出、工具使用纪律、并行查找、交付物覆盖、验证、缺失上下文以及终端工具使用规范。 +OpenAI GPT-5 系列覆盖层会保持核心执行规则简洁，并添加模型专属指引，用于角色锁定、简洁输出、工具纪律、并行查找、交付物覆盖、验证、缺失上下文和终端工具卫生。 ## 结构 -该提示词刻意保持紧凑，并使用固定部分： +该提示词有意保持紧凑，并使用固定部分： -- **工具**：结构化工具的权威来源提醒，以及运行时工具使用指引。 -- **执行倾向**：简洁的持续执行指引：对可执行请求在当前轮次直接行动，持续直到完成或被阻塞，从较弱的工具结果中恢复，实时检查可变状态，并在最终完成前进行验证。 -- **安全**：简短的护栏提醒，避免权力寻求行为或绕过监督。 -- **Skills**（可用时）：告诉模型如何按需加载 Skill 指令。 -- **OpenClaw 自我更新**：如何使用 `config.schema.lookup` 安全检查配置，使用 `config.patch` 修补配置，使用 `config.apply` 替换完整配置，以及仅在用户明确请求时运行 `update.run`。仅限所有者使用的 `gateway` 工具也会拒绝重写 `tools.exec.ask` / `tools.exec.security`，包括会规范化到这些受保护执行路径的旧版 `tools.bash.*` 别名。 -- **工作区**：工作目录（`agents.defaults.workspace`）。 -- **文档**：OpenClaw 文档的本地路径（仓库或 npm 包）以及何时阅读它们。 -- **工作区文件（已注入）**：表示下方包含引导文件。 -- **沙箱**（启用时）：表示当前为沙箱隔离运行时、沙箱路径，以及是否可用提权执行。 -- **当前日期与时间**：用户本地时间、时区和时间格式。 -- **回复标签**：受支持提供商的可选回复标签语法。 -- **心跳**：启用默认智能体心跳时的心跳提示与确认行为。 -- **运行时**：主机、操作系统、Node、模型、仓库根目录（如检测到）、思考级别（一行）。 -- **推理**：当前可见性级别 + `/reasoning` 切换提示。 +- **Tooling**：结构化工具事实来源提醒，加上运行时工具使用指引。 +- **Execution Bias**：紧凑的贯彻执行指引：对可执行请求在当前轮次内采取行动，持续推进直到完成或受阻，从较弱的工具结果中恢复，实时检查可变状态，并在最终结束前进行验证。 +- **Safety**：简短的护栏提醒，避免寻求权力的行为或绕过监督。 +- **Skills**（可用时）：告诉模型如何按需加载 skill 指令。 +- **OpenClaw Self-Update**：如何使用 `config.schema.lookup` 安全检查配置，使用 `config.patch` 修补配置，使用 `config.apply` 替换完整配置，以及仅在用户明确请求时运行 `update.run`。仅限所有者使用的 `gateway` 工具也会拒绝重写 `tools.exec.ask` / `tools.exec.security`，包括会标准化到这些受保护 exec 路径的旧版 `tools.bash.*` 别名。 +- **Workspace**：工作目录（`agents.defaults.workspace`）。 +- **Documentation**：OpenClaw 文档的本地路径（仓库或 npm 包）以及应在何时阅读它们。 +- **Workspace Files (injected)**：表示下方已包含引导文件。 +- **Sandbox**（启用时）：表示当前为沙箱隔离运行时、沙箱路径，以及是否可使用提权 exec。 +- **Current Date & Time**：用户本地时间、时区和时间格式。 +- **Reply Tags**：受支持提供商的可选回复标签语法。 +- **Heartbeats**：心跳提示词与确认行为，在为默认智能体启用心跳时显示。 +- **Runtime**：主机、操作系统、node、模型、仓库根目录（若已检测到）、思考级别（一行）。 +- **Reasoning**：当前可见性级别 + `/reasoning` 切换提示。 -“工具”部分还包含针对长时间运行任务的运行时指引： +Tooling 部分还包含针对长时间运行工作的运行时指引： -- 对于未来的后续跟进（`check back later`、提醒、周期性工作），使用 `cron`，而不是 `exec` 睡眠循环、`yieldMs` 延迟技巧或重复 `process` 轮询 -- 仅对“现在启动并在后台持续运行”的命令使用 `exec` / `process` -- 启用自动完成唤醒时，只启动命令一次，并在其产生输出或失败时依赖基于推送的唤醒路径 +- 对未来跟进（`check back later`、提醒、重复性工作）使用 `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` 工具时，Tooling 还会告诉模型：仅将其用于非平凡的多步骤工作，始终保持恰好一个 `in_progress` 步骤，并避免在每次更新后重复整个计划。 -系统提示词中的安全护栏属于建议性内容。它们用于引导模型行为，但不强制执行策略。若要进行硬性约束，请使用工具策略、执行审批、沙箱隔离和渠道允许列表；从设计上讲，运营者可以禁用这些机制。 +系统提示词中的安全护栏属于建议性质。它们会引导模型行为，但不会强制执行策略。对于硬性约束，请使用工具策略、exec 审批、沙箱隔离和渠道 allowlist；出于设计目的，操作员可以禁用这些机制。 -在具有原生审批卡片/按钮的渠道中，运行时提示词现在会告诉智能体优先依赖该原生审批 UI。只有当工具结果表明聊天审批不可用，或者手动审批是唯一途径时，它才应包含手动 `/approve` 命令。 +在具有原生审批卡片/按钮的渠道上，运行时提示词现在会告诉智能体优先依赖该原生审批 UI。只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，它才应包含手动 `/approve` 命令。 ## 提示词模式 OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为每次运行设置一个 `promptMode`（不是面向用户的配置）： - `full`（默认）：包含上述所有部分。 -- `minimal`：用于子智能体；省略 **Skills**、**Memory Recall**、**OpenClaw 自我更新**、**模型别名**、**用户身份**、**回复标签**、**消息传递**、**静默回复** 和 **心跳**。工具、**安全**、工作区、沙箱、当前日期与时间（如已知）、运行时以及注入的上下文仍然可用。 -- `none`：只返回基础身份行。 +- `minimal`：用于子智能体；省略 **Skills**、**Memory Recall**、**OpenClaw Self-Update**、**Model Aliases**、**User Identity**、**Reply Tags**、**Messaging**、**Silent Replies** 和 **Heartbeats**。Tooling、**Safety**、Workspace、Sandbox、Current Date & Time（已知时）、Runtime 和注入的上下文仍然可用。 +- `none`：仅返回基础身份行。 -当 `promptMode=minimal` 时，额外注入的提示词会标记为 **子智能体上下文**，而不是 **群聊上下文**。 +当 `promptMode=minimal` 时，额外注入的提示词会标记为 **Subagent Context**，而不是 **Group Chat Context**。 ## 工作区引导注入 -引导文件会被裁剪后追加到 **项目上下文** 下，这样模型无需显式读取就能看到身份和配置文件上下文： +引导文件会被裁剪，并附加在 **Project Context** 下，这样模型无需显式读取就能看到身份和配置文件上下文： - `AGENTS.md` - `SOUL.md` @@ -84,40 +84,40 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为 - `USER.md` - `HEARTBEAT.md` - `BOOTSTRAP.md`（仅在全新工作区中） -- 存在时使用 `MEMORY.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` 每日文件**不属于**常规引导“项目上下文”的一部分。在普通轮次中，它们通过 `memory_search` 和 `memory_get` 工具按需访问，因此除非模型显式读取，否则不会占用上下文窗口。纯 `/new` 和 `/reset` 轮次是例外：运行时可以为第一次轮次预置最近的每日记忆，作为一次性启动上下文块。 +> **注意：** `memory/*.md` 每日文件**不是**常规引导 Project Context 的一部分。在普通轮次中，它们通过 `memory_search` 和 `memory_get` 工具按需访问，因此除非模型显式读取，否则不会计入上下文窗口。纯 `/new` 和 `/reset` 轮次是例外：运行时可以为第一轮在前面附加最近的每日记忆，作为一次性启动上下文块。 -大文件会使用标记进行截断。每个文件的最大大小由 `agents.defaults.bootstrapMaxChars` 控制（默认：12000）。跨文件注入的引导内容总量上限由 `agents.defaults.bootstrapTotalMaxChars` 控制（默认：60000）。缺失文件会注入一个简短的缺失文件标记。发生截断时，OpenClaw 可以在项目上下文中注入警告块；可通过 `agents.defaults.bootstrapPromptTruncationWarning` 控制（`off`、`once`、`always`；默认：`once`）。 +大文件会使用标记进行截断。每个文件的最大大小由 `agents.defaults.bootstrapMaxChars` 控制（默认：12000）。跨文件注入的引导内容总量上限由 `agents.defaults.bootstrapTotalMaxChars` 控制（默认：60000）。缺失文件会注入一个简短的缺失文件标记。当发生截断时，OpenClaw 可以在 Project Context 中注入警告块；通过 `agents.defaults.bootstrapPromptTruncationWarning` 控制（`off`、`once`、`always`；默认：`once`）。 -子智能体会话只注入 `AGENTS.md` 和 `TOOLS.md`（其他引导文件会被过滤掉，以保持子智能体上下文较小）。 +子智能体会话只注入 `AGENTS.md` 和 `TOOLS.md`（其他引导文件会被过滤掉，以保持子智能体上下文精简）。 -内部钩子可以通过 `agent:bootstrap` 拦截此步骤，以变更或替换注入的引导文件（例如将 `SOUL.md` 替换为另一种角色设定）。 +内部钩子可以通过 `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`。参见 [上下文](/zh-CN/concepts/context)。 +若要检查每个注入文件贡献了多少内容（原始内容与注入内容、截断情况，以及工具 schema 开销），请使用 `/context list` 或 `/context detail`。参见 [Context](/zh-CN/concepts/context)。 ## 时间处理 -当已知用户时区时，系统提示词会包含专门的**当前日期与时间**部分。为了保持提示词缓存稳定，它现在只包含**时区**（不包含动态时钟或时间格式）。 +当已知用户时区时，系统提示词会包含专门的 **Current Date & Time** 部分。为保持提示词缓存稳定，它现在只包含**时区**（不包含动态时钟或时间格式）。 -当智能体需要当前时间时，请使用 `session_status`；状态卡片中包含时间戳行。该工具也可以选择设置每个会话的模型覆盖（`model=default` 会清除覆盖）。 +当智能体需要当前时间时，请使用 `session_status`；状态卡包含时间戳行。同一个工具还可以选择设置每会话模型覆盖（`model=default` 会清除它）。 可通过以下配置： - `agents.defaults.userTimezone` - `agents.defaults.timeFormat`（`auto` | `12` | `24`） -完整行为细节请参见 [日期与时间](/zh-CN/date-time)。 +完整行为细节请参见 [Date & Time](/zh-CN/date-time)。 ## Skills -当存在符合条件的 Skills 时，OpenClaw 会注入一个紧凑的**可用 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 allowlist。 ``` @@ -129,9 +129,9 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为 ``` -这样可以让基础提示词保持简短，同时仍然支持有针对性的 Skill 使用。 +这样既能保持基础提示词精简，又能启用有针对性的 skill 使用。 -Skills 列表的预算由 Skills 子系统负责： +skills 列表预算由 skills 子系统管理： - 全局默认值：`skills.limits.maxSkillsPromptChars` - 每智能体覆盖：`agents.list[].skillsLimits.maxSkillsPromptChars` @@ -141,8 +141,8 @@ Skills 列表的预算由 Skills 子系统负责： - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -这种拆分让 Skills 大小控制与运行时读取/注入大小控制分离，例如 `memory_get`、实时工具结果，以及压缩后对 `AGENTS.md` 的刷新。 +这种拆分使 skills 大小控制与运行时读取/注入大小控制相互独立，例如 `memory_get`、实时工具结果，以及压缩后 AGENTS.md 刷新等场景。 -## 文档 +## Documentation -可用时，系统提示词会包含一个**文档**部分，指向 OpenClaw 文档目录的本地路径（仓库工作区中的 `docs/` 或 npm 包内置文档），并同时说明公开镜像、源代码仓库、社区 Discord 以及用于发现 Skills 的 ClawHub（[https://clawhub.ai](https://clawhub.ai)）。提示词会指示模型在处理 OpenClaw 行为、命令、配置或架构时优先查阅本地文档，并在可能时自行运行 `openclaw status`（只有在无法访问时才询问用户）。 +可用时，系统提示词会包含一个 **Documentation** 部分，指向本地 OpenClaw 文档目录（仓库工作区中的 `docs/` 或 npm 包内置文档），同时还会注明公共镜像、源代码仓库、社区 Discord，以及用于发现 skills 的 ClawHub（[https://clawhub.ai](https://clawhub.ai)）。提示词会指示模型在涉及 OpenClaw 行为、命令、配置或架构时优先查阅本地文档，并在可能时自行运行 `openclaw status`（仅在无权访问时才询问用户）。 diff --git a/docs/zh-CN/reference/AGENTS.default.md b/docs/zh-CN/reference/AGENTS.default.md index 1f5fefe6a..7cefde6de 100644 --- a/docs/zh-CN/reference/AGENTS.default.md +++ b/docs/zh-CN/reference/AGENTS.default.md @@ -2,13 +2,13 @@ read_when: - 开始新的 OpenClaw 智能体会话 - 启用或审查默认 Skills -summary: 个人助理设置的默认 OpenClaw 智能体说明和 Skills 名册 +summary: 个人助理设置的默认 OpenClaw 智能体说明和 Skills 名录 title: 默认 AGENTS.md x-i18n: - generated_at: "2026-04-05T10:07:37Z" + generated_at: "2026-04-23T15:14:07Z" model: gpt-5.4 provider: openai - source_hash: 45990bc4e6fa2e3d80e76207e62ec312c64134bee3bc832a5cae32ca2eda3b61 + source_hash: f34b2e332028029af015e4c6a25cb1399b4d70c5520529f415477a592a97c79c source_path: reference/AGENTS.default.md workflow: 15 --- @@ -17,7 +17,7 @@ x-i18n: ## 首次运行（推荐） -OpenClaw 为智能体使用专用工作区目录。默认值：`~/.openclaw/workspace`（可通过 `agents.defaults.workspace` 配置）。 +OpenClaw 会为智能体使用一个专用工作区目录。默认值：`~/.openclaw/workspace`（可通过 `agents.defaults.workspace` 配置）。 1. 创建工作区（如果尚不存在）： @@ -33,7 +33,7 @@ cp docs/reference/templates/SOUL.md ~/.openclaw/workspace/SOUL.md cp docs/reference/templates/TOOLS.md ~/.openclaw/workspace/TOOLS.md ``` -3. 可选：如果你想使用个人助理 Skills 名册，请用此文件替换 AGENTS.md： +3. 可选：如果你想使用个人助理 Skills 名录，请用此文件替换 AGENTS.md： ```bash cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md @@ -47,46 +47,46 @@ cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md } ``` -## 默认安全规则 +## 默认安全设置 - 不要将目录内容或密钥转储到聊天中。 -- 除非被明确要求，否则不要运行破坏性命令。 -- 不要向外部消息表面发送部分/流式回复（只发送最终回复）。 +- 除非得到明确要求，否则不要运行破坏性命令。 +- 不要向外部消息传递界面发送部分回复或流式回复（只发送最终回复）。 -## 会话开始（必需） +## 会话启动（必需） -- 阅读 `SOUL.md`、`USER.md` 以及 `memory/` 中今天和昨天的内容。 -- 存在 `MEMORY.md` 时读取它；仅当 `MEMORY.md` 不存在时才回退到小写的 `memory.md`。 +- 读取 `SOUL.md`、`USER.md`，以及 `memory/` 中今天和昨天的内容。 +- 如果存在，也读取 `MEMORY.md`。 - 在回复之前完成这些操作。 ## Soul（必需） -- `SOUL.md` 定义身份、语气和边界。请保持其为最新状态。 -- 如果你更改了 `SOUL.md`，请告诉用户。 -- 你在每个会话中都是一个全新的实例；连续性保存在这些文件中。 +- `SOUL.md` 定义身份、语气和边界。请保持其最新。 +- 如果你修改了 `SOUL.md`，告诉用户。 +- 每个会话中你都是一个全新的实例；连续性保存在这些文件中。 ## 共享空间（推荐） -- 你不是用户的“代言人”；在群聊或公共渠道中要谨慎。 -- 不要分享私人数据、联系信息或内部笔记。 +- 你不是用户的代言人；在群聊或公共渠道中要谨慎。 +- 不要分享私人数据、联系信息或内部备注。 ## Memory 系统（推荐） -- 每日日志：`memory/YYYY-MM-DD.md`（如有需要请创建 `memory/`）。 -- 长期记忆：`MEMORY.md`，用于保存持久事实、偏好和决策。 -- 小写 `memory.md` 仅作旧版回退使用；不要故意同时保留这两个根文件。 -- 在会话开始时，读取今天 + 昨天 + `MEMORY.md`（如存在），否则读取 `memory.md`。 -- 记录：决策、偏好、约束、未完成事项。 -- 除非被明确要求，否则避免记录密钥。 +- 每日日志：`memory/YYYY-MM-DD.md`（如果需要，请创建 `memory/`）。 +- 长期记忆：`MEMORY.md`，用于保存持久事实、偏好和决定。 +- 小写的 `memory.md` 仅作为旧版修复输入；不要有意同时保留这两个根文件。 +- 在会话开始时，读取今天、昨天和 `MEMORY.md`（如果存在）。 +- 记录：决定、偏好、约束条件、未完成事项。 +- 除非明确要求，否则避免记录密钥。 -## 工具与 Skills +## 工具和 Skills -- 工具位于 Skills 中；当你需要它们时，请遵循各个 skill 的 `SKILL.md`。 -- 将特定于环境的说明保存在 `TOOLS.md` 中（Notes for Skills）。 +- 工具存在于 Skills 中；当你需要使用某个 skill 时，请遵循其 `SKILL.md`。 +- 将特定环境的说明保存在 `TOOLS.md` 中（Skills 说明）。 ## 备份提示（推荐） -如果你将此工作区视为 Clawd 的“记忆”，请把它设为 git 仓库（最好是私有仓库），这样 `AGENTS.md` 和你的 memory 文件就能得到备份。 +如果你将此工作区视为 Clawd 的“记忆”，请把它设为一个 git 仓库（最好是私有仓库），这样 `AGENTS.md` 和你的记忆文件就能得到备份。 ```bash cd ~/.openclaw/workspace @@ -98,36 +98,36 @@ git commit -m "Add Clawd workspace" ## OpenClaw 的作用 -- 运行 WhatsApp Gateway 网关 + Pi coding agent，使助理能够通过宿主 Mac 读写聊天、获取上下文并运行 Skills。 -- macOS 应用管理权限（屏幕录制、通知、麦克风），并通过其内置二进制文件公开 `openclaw` CLI。 -- 默认情况下，私聊会折叠到智能体的 `main` 会话中；群组会保持隔离，格式为 `agent:::group:`（房间/频道：`agent:::channel:`）；心跳会保持后台任务存活。 +- 运行 WhatsApp Gateway 网关和 Pi 编码智能体，使助理能够读写聊天、获取上下文，并通过主机 Mac 运行 Skills。 +- macOS 应用负责管理权限（屏幕录制、通知、麦克风），并通过其捆绑的二进制文件提供 `openclaw` CLI。 +- 默认情况下，私聊会合并到智能体的 `main` 会话中；群组则保持隔离，格式为 `agent:::group:`（房间/渠道：`agent:::channel:`）；心跳机制会让后台任务保持活跃。 -## 核心 Skills（在“设置 → Skills”中启用） +## 核心 Skills（在“设置”→“Skills”中启用） -- **mcporter** — 用于管理外部 skill 后端的工具服务器运行时/CLI。 -- **Peekaboo** — 快速进行 macOS 截图，可选 AI 视觉分析。 +- **mcporter** — 用于管理外部 skill 后端的工具服务器运行时 / CLI。 +- **Peekaboo** — 快速进行 macOS 截图，并可选择使用 AI 进行视觉分析。 - **camsnap** — 从 RTSP/ONVIF 安防摄像头捕获帧、片段或运动警报。 -- **oracle** — 面向 OpenAI 的智能体 CLI，支持会话重放和浏览器控制。 -- **eightctl** — 从终端控制你的睡眠。 -- **imsg** — 发送、读取、流式处理 iMessage 和 SMS。 +- **oracle** — 面向 OpenAI 的智能体 CLI，支持会话回放和浏览器控制。 +- **eightctl** — 通过终端控制你的睡眠。 +- **imsg** — 发送、读取和流式处理 iMessage 与 SMS。 - **wacli** — WhatsApp CLI：同步、搜索、发送。 - **discord** — Discord 操作：反应、贴纸、投票。使用 `user:` 或 `channel:` 目标（裸数字 id 有歧义）。 -- **gog** — Google Suite CLI：Gmail、Calendar、Drive、Contacts。 -- **spotify-player** — 终端 Spotify 客户端，用于搜索/排队/控制播放。 -- **sag** — 具有 mac 风格 say 体验的 ElevenLabs 语音；默认流式输出到扬声器。 -- **Sonos CLI** — 从脚本中控制 Sonos 音箱（发现/状态/播放/音量/分组）。 -- **blucli** — 从脚本中播放、分组和自动化 BluOS 播放器。 +- **gog** — Google Suite CLI：Gmail、日历、Drive、联系人。 +- **spotify-player** — 终端版 Spotify 客户端，用于搜索、加入队列和控制播放。 +- **sag** — 采用 mac 风格 `say` 交互体验的 ElevenLabs 语音；默认流式输出到扬声器。 +- **Sonos CLI** — 通过脚本控制 Sonos 扬声器（发现 / 状态 / 播放 / 音量 / 分组）。 +- **blucli** — 通过脚本播放、分组和自动化 BluOS 播放器。 - **OpenHue CLI** — 用于场景和自动化的 Philips Hue 灯光控制。 -- **OpenAI Whisper** — 用于快速听写和语音信箱转写的本地语音转文本。 +- **OpenAI Whisper** — 本地语音转文本，用于快速听写和语音信箱转录。 - **Gemini CLI** — 在终端中使用 Google Gemini 模型进行快速问答。 - **agent-tools** — 用于自动化和辅助脚本的实用工具包。 ## 使用说明 - 脚本编写优先使用 `openclaw` CLI；mac 应用负责处理权限。 -- 从 Skills 标签页运行安装；如果二进制文件已存在，它会隐藏按钮。 -- 保持启用心跳，这样助理才能安排提醒、监控收件箱并触发摄像头抓拍。 -- Canvas UI 以全屏方式运行，并带有原生叠加层。避免将关键控件放在左上角/右上角/底部边缘；在布局中添加明确的边距，不要依赖安全区域内边距。 -- 对于浏览器驱动的验证，使用 `openclaw browser`（tabs/status/screenshot）以及 OpenClaw 管理的 Chrome 配置文件。 -- 对于 DOM 检查，使用 `openclaw browser eval|query|dom|snapshot`（在需要机器可读输出时使用 `--json`/`--out`）。 -- 对于交互，使用 `openclaw browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run`（click/type 需要 snapshot 引用；对 CSS 选择器请使用 `evaluate`）。 +- 从 Skills 标签页运行安装；如果某个二进制文件已存在，按钮会被隐藏。 +- 保持启用心跳，这样助理才能安排提醒、监控收件箱并触发摄像头捕获。 +- Canvas UI 以全屏模式运行，并带有原生覆盖层。避免将关键控件放在左上角 / 右上角 / 底部边缘；请在布局中添加明确的边距，不要依赖安全区域边距。 +- 进行浏览器驱动的验证时，使用 `openclaw browser`（tabs/status/screenshot）以及 OpenClaw 管理的 Chrome 配置文件。 +- 进行 DOM 检查时，使用 `openclaw browser eval|query|dom|snapshot`（当你需要机器可读输出时，可使用 `--json` / `--out`）。 +- 进行交互时，使用 `openclaw browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run`（click/type 需要 snapshot 引用；CSS 选择器请使用 `evaluate`）。