openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-02 05:01:18 +00:00
parent 432ecb924e
commit 647aa74fa7
2 changed files with 114 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

169
docs/zh-CN/concepts/session-tool.md
View File

@ -1,39 +1,34 @@
---
read_when:
- 你想了解智能体有哪些会话工具
- 你想了解智能体拥有哪些会话工具
- 你想配置跨会话访问或子智能体生成
- 你想查看状态或控制已启动的子智能体
summary: 用于跨会话状态、召回、消息传递和子智能体编排的智能体工具
- 你想查看状态或控制已生成的子智能体
summary: 用于跨会话状态、记忆检索、消息传递和子智能体编排的智能体工具
title: 会话工具
x-i18n:
generated_at: "2026-04-28T19:38:59Z"
generated_at: "2026-05-02T05:00:30Z"
model: gpt-5.5
provider: openai
source_hash: 0464116d42e271da12cbe90529e06e9f51605981be85b54bb5850ee9b8fb7824
source_hash: e9343d42319492ac4531edd6e6c217eae13e9c5f7b8a3fc25a345395d9f57246
source_path: concepts/session-tool.md
workflow: 16
---
OpenClaw 为智能体提供工具，用于跨会话工作、检查 Status，并
编排子智能体。
OpenClaw 为智能体提供工具，用于跨会话协作、检查 Status，并编排子智能体。
## 可用工具
| 工具 | 作用 |
| 工具 | 作用 |
| ------------------ | --------------------------------------------------------------------------- |
| `sessions_list` | 列出会话，可选筛选条件包括类型、标签、智能体、最近活动、预览 |
| `sessions_history` | 读取特定会话的转录记录 |
| `sessions_send` | 向另一个会话发送消息，并可选择等待 |
| `sessions_spawn` | 生成一个隔离的子智能体会话用于后台工作 |
| `sessions_yield` | 结束当前轮次并等待后续子智能体结果 |
| `subagents` | 列出、引导或终止此会话生成的子智能体 |
| `session_status` | 显示类似 `/status` 的卡片，并可选择设置每会话模型覆盖项 |
| `sessions_list` | 使用可选过滤条件（类型、标签、智能体、最近活跃度、预览）列出会话 |
| `sessions_history` | 读取特定会话的转录 |
| `sessions_send` | 向另一个会话发送消息，并可选择等待 |
| `sessions_spawn` | 生成一个隔离的子智能体会话来执行后台工作 |
| `sessions_yield` | 结束当前轮次并等待后续子智能体结果 |
| `subagents` | 列出、引导或终止此会话生成的子智能体 |
| `session_status` | 显示类似 `/status` 的卡片，并可选择设置每个会话的模型覆盖 |
这些工具仍受当前工具 profile 和允许/拒绝策略约束。`tools.profile: "coding"` 包含完整的会话编排
工具集，包括 `sessions_spawn`、`sessions_yield` 和 `subagents`。
`tools.profile: "messaging"` 包含跨会话消息工具
（`sessions_list`、`sessions_history`、`sessions_send`、`session_status`），但
不包含子智能体生成。若要保留 messaging profile，同时仍允许原生委托，请添加：
这些工具仍然受当前工具配置档案以及允许/拒绝策略约束。`tools.profile: "coding"` 包含完整的会话编排工具集，包括 `sessions_spawn`、`sessions_yield` 和 `subagents`。`tools.profile: "messaging"` 包含跨会话消息工具（`sessions_list`、`sessions_history`、`sessions_send`、`session_status`），但不包含子智能体生成。若要保留消息配置档案并仍允许原生委派，请添加：
```json5
{
@ -44,128 +39,94 @@ OpenClaw 为智能体提供工具，用于跨会话工作、检查 Status，并
}
```
组、提供商、沙箱和每智能体策略仍可在 profile 阶段之后移除这些工具。
在受影响的会话中使用 `/tools` 检查实际生效的工具列表。
组、提供商、沙箱以及每个智能体的策略仍可在配置档案阶段之后移除这些工具。请在受影响的会话中使用 `/tools` 检查实际工具列表。
## 列出和读取会话
`sessions_list` 返回会话及其 key、agentId、类型、渠道、模型、
token 计数和时间戳。可按类型（`main`、`group`、`cron`、`hook`、
`node`）、精确 `label`、精确 `agentId`、搜索文本或最近活动
（`activeMinutes`）筛选。当你需要类似邮箱的分诊时，它还可以请求
可见性范围内派生的标题、最后一条消息预览片段，或每一行上有界的
近期消息。派生标题和预览只会为调用方在已配置的会话工具可见性策略下
已经可见的会话生成，因此无关会话会保持隐藏。
`sessions_list` 返回会话及其键、agentId、类型、渠道、模型、令牌计数和时间戳。可按类型（`main`、`group`、`cron`、`hook`、`node`）、精确 `label`、精确 `agentId`、搜索文本或最近活跃度（`activeMinutes`）过滤。当你需要类似邮箱的分诊时，它还可以为每一行请求基于可见性范围派生的标题、最后一条消息预览片段，或有界的近期消息。派生标题和预览只会为调用方在已配置会话工具可见性策略下已经可见的会话生成，因此无关会话会保持隐藏。
`sessions_history` 获取特定会话的对话转录记录。
默认情况下，工具结果会被排除——传入 `includeTools: true` 可查看它们。
返回视图是刻意有界且经过安全过滤的：
`sessions_history` 获取特定会话的对话转录。默认情况下会排除工具结果；传入 `includeTools: true` 可查看它们。返回视图会被刻意限制范围并进行安全过滤：
- 助手文本会在召回前标准化：
- thinking 标签会被移除
- `<relevant-memories>` / `<relevant_memories>` 脚手架块会被移除
- 纯文本工具调用 XML 载荷块，例如 `<tool_call>...</tool_call>`、
`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>` 和
`<function_calls>...</function_calls>` 会被移除，包括从未正常闭合的截断
载荷
- 降级的工具调用/结果脚手架，例如 `[Tool Call: ...]`、
`[Tool Result ...]` 和 `[Historical context ...]` 会被移除
- 泄漏的模型控制 token，例如 `<|assistant|>`、其他 ASCII
`<|...|>` token，以及全角 `<｜...｜>` 变体会被移除
- 格式异常的 MiniMax 工具调用 XML，例如 `<invoke ...>` /
`</minimax:tool_call>` 会被移除
- 类似凭证/token 的文本会在返回前被遮盖
- 智能体文本会在召回前规范化：
- 移除思考标签
- 移除 `<relevant-memories>` / `<relevant_memories>` 脚手架块
- 移除纯文本工具调用 XML 载荷块，例如 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>` 和 `<function_calls>...</function_calls>`，包括从未正常闭合的截断载荷
- 移除降级后的工具调用/结果脚手架，例如 `[Tool Call: ...]`、`[Tool Result ...]` 和 `[Historical context ...]`
- 移除泄漏的模型控制令牌，例如 `<|assistant|>`、其他 ASCII `<|...|>` 令牌，以及全角 `<｜...｜>` 变体
- 移除格式错误的 MiniMax 工具调用 XML，例如 `<invoke ...>` / `</minimax:tool_call>`
- 类似凭证/令牌的文本会在返回前被遮盖
- 长文本块会被截断
- 非常大的历史记录可能会丢弃较旧的行，或将超大的行替换为
`[sessions_history omitted: message too large]`
- 该工具会报告摘要标志，例如 `truncated`、`droppedMessages`、
`contentTruncated`、`contentRedacted` 和 `bytes`
- 非常大的历史记录可能会丢弃较旧行，或用 `[sessions_history omitted: message too large]` 替换过大的行
- 该工具会报告摘要标志，例如 `truncated`、`droppedMessages`、`contentTruncated`、`contentRedacted` 和 `bytes`
两个工具都接受 **会话 key**（如 `"main"`）或上一次列表调用中的 **会话 ID**。
两个工具都接受**会话键**（如 `"main"`）或来自先前列表调用的**会话 ID**。
如果你需要逐字节完全一致的转录记录，请检查磁盘上的转录文件，
而不是把 `sessions_history` 当作原始转储。
如果你需要逐字节完全一致的转录，请检查磁盘上的转录文件，而不要把 `sessions_history` 当作原始转储。
## 发送跨会话消息
`sessions_send` 会向另一个会话投递消息，并可选择等待响应：
`sessions_send` 将消息投递到另一个会话，并可选择等待响应：
- **发送后不等待：** 设置 `timeoutSeconds: 0`，入队后立即返回。
- **等待回复：** 设置超时时间，并以内联方式获取响应。
- **发送后不等待：** 将 `timeoutSeconds: 0` 设为入队后立即返回。
- **等待回复：** 设置超时并以内联方式获取响应。
消息和 A2A 后续回复会在接收方提示词中标记为会话间数据
（`[Inter-session message ... isUser=false]`），并记录在转录来源中。
接收智能体应将其视为由工具路由的数据，而不是最终用户直接撰写的指令。
线程范围的聊天会话，例如以 `:thread:<id>` 结尾的 Slack 或 Discord 键，不是有效的 `sessions_send` 目标。请使用父渠道会话键进行智能体间协调，使工具路由的消息不会出现在面向真人的活跃线程中。
目标响应后，OpenClaw 可以运行 **回复回传循环**，让智能体交替发送消息
（最多 5 轮）。目标智能体可以回复 `REPLY_SKIP` 以提前停止。
消息和 A2A 后续回复会在接收提示（`[Inter-session message ... isUser=false]`）和转录来源中标记为会话间数据。接收智能体应将其视为工具路由的数据，而不是由最终用户直接编写的指令。
## Status 与编排辅助工具
目标响应后，OpenClaw 可以运行**回传循环**，让智能体轮流发送消息（最多 5 轮）。目标智能体可以回复 `REPLY_SKIP` 来提前停止。
`session_status` 是当前会话或另一个可见会话的轻量级 `/status` 等效工具。
它会报告使用情况、时间、模型/运行时状态，以及存在时的关联后台任务上下文。
与 `/status` 一样，它可以从最新的转录用量条目回填稀疏的 token/cache 计数器，并且
`model=default` 会清除每会话覆盖项。调用方当前会话请使用
`sessionKey="current"`；可见客户端标签（如 `openclaw-tui`）不是会话 key。
## Status 和编排辅助工具
`sessions_yield` 会有意结束当前轮次，以便下一条消息可以是你正在等待的
后续事件。在生成子智能体后，如果你希望完成结果作为下一条消息到达，
而不是构建轮询循环，请使用它。
`session_status` 是当前会话或另一个可见会话的轻量级 `/status` 等效工具。它报告使用量、时间、模型/运行时状态，以及存在时的已关联后台任务上下文。与 `/status` 一样，它可以从最新的转录使用量条目回填稀疏的令牌/缓存计数，并且 `model=default` 会清除每个会话的覆盖。使用 `sessionKey="current"` 表示调用方当前会话；可见的客户端标签如 `openclaw-tui` 不是会话键。
`subagents` 是用于已生成 OpenClaw 子智能体的控制平面辅助工具。
它支持：
`sessions_yield` 会有意结束当前轮次，以便下一条消息可以是你正在等待的后续事件。在生成子智能体后，如果你希望完成结果作为下一条消息到达，而不是构建轮询循环，请使用它。
- `action: "list"` 用于检查活跃/近期运行
- `action: "steer"` 用于向正在运行的子会话发送后续指导
- `action: "kill"` 用于停止一个子会话或 `all`
`subagents` 是用于已生成 OpenClaw 子智能体的控制面辅助工具。它支持：
- `action: "list"` 检查活跃/近期运行
- `action: "steer"` 向正在运行的子项发送后续指导
- `action: "kill"` 停止一个子项或 `all`
## 生成子智能体
`sessions_spawn` 默认会为后台任务创建一个隔离会话。
它始终是非阻塞的——会立即返回 `runId` 和
`childSessionKey`。
`sessions_spawn` 默认会为后台任务创建一个隔离会话。它始终非阻塞，会立即返回 `runId` 和 `childSessionKey`。
关键选项：
- `runtime: "subagent"`（默认）或 `"acp"`，用于外部 harness 智能体。
- 子会话的 `model` 和 `thinking` 覆盖项。
- `thread: true`，将生成绑定到聊天线程（Discord、Slack 等）。
- `sandbox: "require"`，对子会话强制执行沙箱隔离。
- `context: "fork"`，用于在子会话需要当前请求方转录记录时的原生子智能体；
省略它或使用 `context: "isolated"` 可获得干净的子会话。
- 子会话的 `model` 和 `thinking` 覆盖。
- `thread: true` 将生成绑定到聊天线程（Discord、Slack 等）。
- `sandbox: "require"` 对子项强制沙箱隔离。
- 当子项需要当前请求方转录时，原生子智能体可使用 `context: "fork"`；省略它或使用 `context: "isolated"` 可获得干净的子项。
默认叶子子智能体不会获得会话工具。当
`maxSpawnDepth >= 2` 时，深度为 1 的编排型子智能体会额外获得
`sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，
以便它们管理自己的子会话。叶子运行仍不会获得递归编排工具。
默认叶子子智能体不会获得会话工具。当 `maxSpawnDepth >= 2` 时，深度为 1 的编排器子智能体还会收到 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便管理自己的子项。叶子运行仍然不会获得递归编排工具。
完成后，公告步骤会将结果发布到请求方的渠道。
完成交付会在可用时保留绑定的线程/主题路由，并且如果完成来源只标识了一个渠道，
OpenClaw 仍可以复用请求方会话存储的路由（`lastChannel` / `lastTo`）进行直接交付。
完成后，公告步骤会将结果发布到请求方的渠道。完成投递会在可用时保留绑定的线程/主题路由；如果完成来源只标识一个渠道，OpenClaw 仍可复用请求方会话已存储的路由（`lastChannel` / `lastTo`）进行直接投递。
关于 ACP 专属行为，请参阅 [ACP 智能体](/zh-CN/tools/acp-agents)。
有关 ACP 特定行为，请参阅 [ACP 智能体](/zh-CN/tools/acp-agents)。
## 可见性
会话工具会按范围限制智能体可见的内容：
会话工具会被限定范围，以限制智能体可以看到的内容：
| 级别 | 范围 |
| 级别 | 范围 |
| ------- | ---------------------------------------- |
| `self` | 仅当前会话 |
| `tree` | 当前会话 + 已生成的子智能体 |
| `agent` | 此智能体的所有会话 |
| `all` | 所有会话（如已配置，则跨智能体） |
| `self` | 仅当前会话 |
| `tree` | 当前会话 + 生成的子智能体 |
| `agent` | 此智能体的所有会话 |
| `all` | 所有会话（如果已配置，则跨智能体） |
默认值为 `tree`。无论配置如何，沙箱隔离的会话都会被限制为 `tree`。
默认值为 `tree`。沙箱隔离会话无论配置如何都会被限制为 `tree`。
## 延伸阅读
- [会话管理](/zh-CN/concepts/session)——路由、生命周期、维护
- [ACP 智能体](/zh-CN/tools/acp-agents)——外部 harness 生成
- [多智能体](/zh-CN/concepts/multi-agent)——多智能体架构
- [Gateway 网关配置](/zh-CN/gateway/configuration)——会话工具配置旋钮
- [会话管理](/zh-CN/concepts/session) -- 路由、生命周期、维护
- [ACP 智能体](/zh-CN/tools/acp-agents) -- 外部 harness 生成
- [多智能体](/zh-CN/concepts/multi-agent) -- 多智能体架构
- [Gateway 网关配置](/zh-CN/gateway/configuration) -- 会话工具配置旋钮
## 相关
## 相关内容
- [会话管理](/zh-CN/concepts/session)
- [会话剪枝](/zh-CN/concepts/session-pruning)
- [会话修剪](/zh-CN/concepts/session-pruning)

100
docs/zh-CN/install/installer.md
View File

@ -3,24 +3,24 @@ read_when:
- 你想了解 `openclaw.ai/install.sh`
- 你想自动化安装（CI / 无头环境）
- 你想从 GitHub 检出副本安装
summary: 安装脚本（install.sh、install-cli.sh、install.ps1）的工作方式、标志和自动化
summary: 安装脚本（install.sh、install-cli.sh、install.ps1）的工作原理、标志和自动化
title: 安装程序内部机制
x-i18n:
generated_at: "2026-04-28T11:56:46Z"
generated_at: "2026-05-02T05:00:28Z"
model: gpt-5.5
provider: openai
source_hash: 278e8d6a1a39651812b7f0955965c53c62afd3ad673b357484f8aecbcfbbdb1d
source_hash: 119d94edae8cae2460e1bce9fe6bb31dc3c91d23443090cd34bf10adde9e10f1
source_path: install/installer.md
workflow: 16
---
OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
OpenClaw 随附三个安装脚本，由 `openclaw.ai` 提供。
| 脚本 | 平台 | 作用 |
| ---------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------- |
| [`install.sh`](#installsh) | macOS / Linux / WSL | 按需安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并且可以运行新手引导。 |
| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL | 使用 npm 或 git checkout 模式，将 Node + OpenClaw 安装到本地前缀（`~/.openclaw`）。无需 root 权限。 |
| [`install.ps1`](#installps1) | Windows (PowerShell) | 按需安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并且可以运行新手引导。 |
| [`install.sh`](#installsh) | macOS / Linux / WSL | 按需安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行新手引导。 |
| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL | 将 Node + OpenClaw 安装到本地前缀（`~/.openclaw`），支持 npm 或 git checkout 模式。无需 root 权限。 |
| [`install.ps1`](#installps1) | Windows (PowerShell) | 按需安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行新手引导。 |
## 快速命令
@ -58,7 +58,7 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
</Tabs>
<Note>
如果安装成功，但在新终端中找不到 `openclaw`，请参阅 [Node.js 故障排除](/zh-CN/install/node#troubleshooting)。
如果安装成功但在新终端中找不到 `openclaw`，请参阅 [Node.js 故障排除](/zh-CN/install/node#troubleshooting)。
</Note>
---
@ -68,19 +68,19 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
## install.sh
<Tip>
推荐用于 macOS/Linux/WSL 上大多数交互式安装。
推荐用于 macOS/Linux/WSL 上的大多数交互式安装。
</Tip>
### 流程（install.sh）
<Steps>
<Step title="检测操作系统">
支持 macOS 和 Linux（包括 WSL）。如果检测到 macOS，则在缺少 Homebrew 时安装它。
支持 macOS 和 Linux（包括 WSL）。如果检测到 macOS，会在缺少 Homebrew 时安装它。
</Step>
<Step title="默认确保 Node.js 24">
检查 Node 版本，并在需要时安装 Node 24（macOS 上使用 Homebrew，Linux apt/dnf/yum 上使用 NodeSource 设置脚本）。为保持兼容性，OpenClaw 仍支持 Node 22 LTS，目前为 `22.14+`。
<Step title="默认确保 Node.js 24 可用">
检查 Node 版本，并在需要时安装 Node 24（macOS 上使用 Homebrew，Linux apt/dnf/yum 上使用 NodeSource 设置脚本）。为兼容性，OpenClaw 仍支持 Node 22 LTS，当前为 `22.14+`。
</Step>
<Step title="确保 Git">
<Step title="确保 Git 可用">
如果缺少 Git，则安装它。
</Step>
<Step title="安装 OpenClaw">
@ -90,8 +90,8 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
</Step>
<Step title="安装后任务">
- 尽力刷新已加载的 Gateway 网关服务（`openclaw gateway install --force`，然后重启）
- 在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力而为）
- 在适当情况下尝试新手引导（TTY 可用、未禁用新手引导，且 bootstrap/配置检查通过）
- 在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力执行）
- 在适当时尝试新手引导（TTY 可用、未禁用新手引导，并且 bootstrap/配置检查通过）
- 默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1`
</Step>
@ -99,14 +99,14 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
### 源码 checkout 检测
如果在 OpenClaw checkout（`package.json` + `pnpm-workspace.yaml`）内运行，脚本会提供：
如果在 OpenClaw checkout 内运行（`package.json` + `pnpm-workspace.yaml`），脚本会提供：
- 使用 checkout（`git`），或
- 使用全局安装（`npm`）
如果没有可用的 TTY 且未设置安装方法，则默认使用 `npm` 并发出警告。
如果没有可用 TTY 且未设置安装方法，它会默认使用 `npm` 并发出警告。
对于无效的方法选择或无效的 `--install-method` 值，脚本会以代码 `2` 退出。
如果方法选择无效或 `--install-method` 值无效，脚本会以代码 `2` 退出。
### 示例（install.sh）
@ -146,9 +146,9 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
| `--install-method npm\|git` | 选择安装方法（默认：`npm`）。别名：`--method` |
| `--npm` | npm 方法的快捷方式 |
| `--git` | git 方法的快捷方式。别名：`--github` |
| `--version <version\|dist-tag\|spec>` | npm 版本、dist-tag 或包 spec（默认：`latest`） |
| `--version <version\|dist-tag\|spec>` | npm 版本、dist-tag 或 package spec（默认：`latest`） |
| `--beta` | 如果可用则使用 beta dist-tag，否则回退到 `latest` |
| `--git-dir <path>` | Checkout 目录（默认：`~/openclaw`）。别名：`--dir` |
| `--git-dir <path>` | checkout 目录（默认：`~/openclaw`）。别名：`--dir` |
| `--no-git-update` | 对现有 checkout 跳过 `git pull` |
| `--no-prompt` | 禁用提示 |
| `--no-onboard` | 跳过新手引导 |
@ -164,9 +164,9 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
| 变量 | 描述 |
| ------------------------------------------------------- | --------------------------------------------- |
| `OPENCLAW_INSTALL_METHOD=git\|npm` | 安装方法 |
| `OPENCLAW_VERSION=latest\|next\|main\|<semver>\|<spec>` | npm 版本、dist-tag 或包 spec |
| `OPENCLAW_VERSION=latest\|next\|main\|<semver>\|<spec>` | npm 版本、dist-tag 或 package spec |
| `OPENCLAW_BETA=0\|1` | 如果可用则使用 beta |
| `OPENCLAW_GIT_DIR=<path>` | Checkout 目录 |
| `OPENCLAW_GIT_DIR=<path>` | checkout 目录 |
| `OPENCLAW_GIT_UPDATE=0\|1` | 切换 git 更新 |
| `OPENCLAW_NO_PROMPT=1` | 禁用提示 |
| `OPENCLAW_NO_ONBOARD=1` | 跳过新手引导 |
@ -185,9 +185,7 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
## install-cli.sh
<Info>
适用于希望所有内容都位于本地前缀
（默认 `~/.openclaw`）下且不依赖系统 Node 的环境。默认支持 npm 安装，
也支持在同一前缀流程下进行 git-checkout 安装。
专为希望所有内容都位于本地前缀下（默认 `~/.openclaw`）且不依赖系统 Node 的环境而设计。默认支持 npm 安装，也支持在同一前缀流程下进行 git-checkout 安装。
</Info>
### 流程（install-cli.sh）
@ -196,18 +194,18 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
<Step title="安装本地 Node 运行时">
将固定的受支持 Node LTS tarball（版本嵌入在脚本中，并独立更新）下载到 `<prefix>/tools/node-v<version>`，并验证 SHA-256。
</Step>
<Step title="确保 Git">
如果缺少 Git，则尝试通过 Linux 上的 apt/dnf/yum 或 macOS 上的 Homebrew 安装。
<Step title="确保 Git 可用">
如果缺少 Git，会尝试在 Linux 上通过 apt/dnf/yum 安装，或在 macOS 上通过 Homebrew 安装。
</Step>
<Step title="在前缀下安装 OpenClaw">
- `npm` 方法（默认）：使用 npm 安装到前缀下，然后将包装器写入 `<prefix>/bin/openclaw`
- `git` 方法：克隆/更新一个 checkout（默认 `~/openclaw`），并仍将包装器写入 `<prefix>/bin/openclaw`
- `npm` 方法（默认）：使用 npm 安装到该前缀下，然后将包装器写入 `<prefix>/bin/openclaw`
- `git` 方法：克隆/更新 checkout（默认 `~/openclaw`），并仍将包装器写入 `<prefix>/bin/openclaw`
</Step>
<Step title="刷新已加载的 Gateway 网关服务">
如果 Gateway 网关服务已经从同一前缀加载，脚本会运行
`openclaw gateway install --force`，然后运行 `openclaw gateway restart`，
并尽力探测 Gateway 网关健康状态。
如果已有 Gateway 网关服务从同一前缀加载，脚本会运行
`openclaw gateway install --force`，然后运行 `openclaw gateway restart`，并
尽力探测 Gateway 网关健康状态。
</Step>
</Steps>
@ -256,24 +254,24 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
| `--json` | 发出 NDJSON 事件 |
| `--onboard` | 安装后运行 `openclaw onboard` |
| `--no-onboard` | 跳过新手引导（默认） |
| `--set-npm-prefix` | 在 Linux 上，如果当前前缀不可写，则强制 npm 前缀为 `~/.npm-global` |
| `--set-npm-prefix` | 在 Linux 上，如果当前前缀不可写，则强制将 npm 前缀设为 `~/.npm-global` |
| `--help` | 显示用法（`-h`） |
</Accordion>
<Accordion title="环境变量参考">
| 变量 | 说明 |
| 变量 | 描述 |
| ------------------------------------------- | --------------------------------------------- |
| `OPENCLAW_PREFIX=<path>` | 安装前缀 |
| `OPENCLAW_INSTALL_METHOD=git\|npm` | 安装方式 |
| `OPENCLAW_VERSION=<ver>` | OpenClaw 版本或 dist-tag |
| `OPENCLAW_NODE_VERSION=<ver>` | Node 版本 |
| `OPENCLAW_GIT_DIR=<path>` | git 安装使用的 Git 检出目录 |
| `OPENCLAW_GIT_DIR=<path>` | git 安装的 Git 检出目录 |
| `OPENCLAW_GIT_UPDATE=0\|1` | 为现有检出切换 git 更新 |
| `OPENCLAW_NO_ONBOARD=1` | 跳过新手引导 |
| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm 日志级别 |
| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | 控制 sharp/libvips 行为（默认值：`1`） |
| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | 控制 sharp/libvips 行为（默认：`1`） |
</Accordion>
</AccordionGroup>
@ -294,18 +292,18 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
如果缺失，会尝试通过 winget 安装，然后是 Chocolatey，再然后是 Scoop。Node 22 LTS（当前为 `22.14+`）仍受支持以保持兼容性。
</Step>
<Step title="安装 OpenClaw">
- `npm` 方式（默认）：使用选定的 `-Tag` 进行全局 npm 安装
- `npm` 方式（默认）：使用选定的 `-Tag` 执行全局 npm 安装，并从可写的安装器临时目录启动，因此在 `C:\` 等受保护文件夹中打开的 shell 仍可正常工作
- `git` 方式：克隆/更新仓库，使用 pnpm 安装/构建，并在 `%USERPROFILE%\.local\bin\openclaw.cmd` 安装包装器
</Step>
<Step title="安装后任务">
- 在可能时将所需的 bin 目录添加到用户 PATH
- 尽可能将所需的 bin 目录添加到用户 PATH
- 尽力刷新已加载的 Gateway 网关服务（`openclaw gateway install --force`，然后重启）
- 在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力而为）
- 在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力执行）
</Step>
<Step title="处理失败">
`iwr ... | iex` 和脚本块安装会报告终止错误，但不会关闭当前 PowerShell 会话。直接使用 `powershell -File` / `pwsh -File` 安装时，仍会为自动化流程以非零状态退出。
`iwr ... | iex` 和 scriptblock 安装会报告终止错误，但不会关闭当前 PowerShell 会话。直接使用 `powershell -File` / `pwsh -File` 安装时，自动化场景仍会以非零状态退出。
</Step>
</Steps>
@ -350,11 +348,11 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
<AccordionGroup>
<Accordion title="标志参考">
| 标志 | 说明 |
| 标志 | 描述 |
| --------------------------- | ---------------------------------------------------------- |
| `-InstallMethod npm\|git` | 安装方式（默认值：`npm`） |
| `-Tag <tag\|version\|spec>` | npm dist-tag、版本或包 spec（默认值：`latest`） |
| `-GitDir <path>` | 检出目录（默认值：`%USERPROFILE%\openclaw`） |
| `-InstallMethod npm\|git` | 安装方式（默认：`npm`） |
| `-Tag <tag\|version\|spec>` | npm dist-tag、版本或包 spec（默认：`latest`） |
| `-GitDir <path>` | 检出目录（默认：`%USERPROFILE%\openclaw`） |
| `-NoOnboard` | 跳过新手引导 |
| `-NoGitUpdate` | 跳过 `git pull` |
| `-DryRun` | 仅打印操作 |
@ -363,7 +361,7 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
<Accordion title="环境变量参考">
| 变量 | 说明 |
| 变量 | 描述 |
| ---------------------------------- | ---------- |
| `OPENCLAW_INSTALL_METHOD=git\|npm` | 安装方式 |
| `OPENCLAW_GIT_DIR=<path>` | 检出目录 |
@ -375,7 +373,7 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
</AccordionGroup>
<Note>
如果使用 `-InstallMethod git` 且缺少 Git，脚本会退出并打印 Git for Windows 链接。
如果使用 `-InstallMethod git` 且缺少 Git，该脚本会退出并打印 Git for Windows 链接。
</Note>
---
@ -414,15 +412,15 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
<AccordionGroup>
<Accordion title="为什么需要 Git？">
`git` 安装方式需要 Git。对于 `npm` 安装，仍会检查/安装 Git，以避免依赖项使用 git URL 时发生 `spawn git ENOENT` 失败。
`git` 安装方式需要 Git。对于 `npm` 安装，仍会检查/安装 Git，以避免依赖项使用 git URL 时出现 `spawn git ENOENT` 失败。
</Accordion>
<Accordion title="为什么 npm 在 Linux 上遇到 EACCES？">
某些 Linux 设置会将 npm 全局前缀指向 root 拥有的路径。`install.sh` 可以将前缀切换到 `~/.npm-global`，并将 PATH 导出追加到 shell rc 文件中（当这些文件存在时）。
某些 Linux 设置会将 npm 全局前缀指向 root 拥有的路径。`install.sh` 可以将前缀切换到 `~/.npm-global`，并将 PATH 导出追加到 shell rc 文件（当这些文件存在时）。
</Accordion>
<Accordion title="sharp/libvips 问题">
脚本默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1`，以避免 sharp 针对系统 libvips 构建。要覆盖此设置：
脚本默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1`，以避免 sharp 基于系统 libvips 构建。要覆盖此设置：
```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
@ -439,7 +437,7 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
</Accordion>
<Accordion title="Windows：如何获取详细安装器输出">
`install.ps1` 当前未公开 `-Verbose` 开关。
`install.ps1` 目前不公开 `-Verbose` 开关。
使用 PowerShell 跟踪进行脚本级诊断：
```powershell
@ -451,7 +449,7 @@ OpenClaw 提供三个安装脚本，由 `openclaw.ai` 托管。
</Accordion>
<Accordion title="安装后找不到 openclaw">
通常是 PATH 问题。请参阅 [Node.js 故障排除](/zh-CN/install/node#troubleshooting)。
通常是 PATH 问题。参见 [Node.js 故障排除](/zh-CN/install/node#troubleshooting)。
</Accordion>
</AccordionGroup>