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

docs: regenerate zh-CN onboarding references

Browse Source
This commit is contained in:
Peter Steinberger 2026-03-16 07:02:46 +00:00
parent edab939f4d
commit 00ef214d59
59 changed files with 10929 additions and 6227 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

539
docs/zh-CN/automation/hooks.md
View File

File diff suppressed because it is too large Load Diff

237
docs/zh-CN/channels/bluebubbles.md
View File

@ -6,34 +6,35 @@ read_when:
summary: 通过 BlueBubbles macOS 服务器使用 iMessage（REST 发送/接收、输入状态、回应、配对、高级操作）。
title: BlueBubbles
x-i18n:
generated_at: "2026-02-03T10:04:52Z"
model: claude-opus-4-5
provider: pi
source_hash: 3aae277a8bec479800a7f6268bfbca912c65a4aadc6e513694057fb873597b69
generated_at: "2026-03-16T06:21:08Z"
model: gpt-5.4
provider: openai
source_hash: 877592bf7b9b06abdddd7567d56e756eff229d6ffa5056ef33fa3356086aa580
source_path: channels/bluebubbles.md
workflow: 15
---
# BlueBubbles（macOS REST）
状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。由于其更丰富的 API 和更简便的设置，**推荐用于 iMessage 集成**，优于旧版 imsg 渠道。
状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。由于其 API 更丰富且设置比旧版 imsg 渠道更简单，**推荐用于 iMessage 集成**。
## 概述
## 概览
- 通过 BlueBubbles 辅助应用在 macOS 上运行（[bluebubbles.app](https://bluebubbles.app)）。
- 推荐/已测试版本：macOS Sequoia (15)。macOS Tahoe (26) 可用；但在 Tahoe 上编辑功能目前不可用，群组图标更新可能显示成功但实际未同步。
- OpenClaw 通过其 REST API 与之通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。
- 传入消息通过 webhook 到达；发出的回复、输入指示器、已读回执和 tapback 均为 REST 调用。
- 附件和贴纸作为入站媒体被接收（并在可能时呈现给智能体）。
- 配对/白名单的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
- 回应作为系统事件呈现，与 Slack/Telegram 类似，智能体可以在回复前"提及"它们。
- 推荐/已测试：macOS Sequoia（15）。macOS Tahoe（26）可用；目前编辑功能在 Tahoe 上已损坏，群组图标更新可能会报告成功但不会同步。
- OpenClaw 通过其 REST API 与其通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。
- 传入消息通过 webhook 到达；传出回复、输入状态指示、已读回执和 tapback 都通过 REST 调用完成。
- 附件和贴纸会作为入站媒体接收（并在可能时展示给智能体）。
- 配对/allowlist 的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
- 回应会像 Slack/Telegram 一样作为系统事件呈现，因此智能体可以在回复前“提及”它们。
- 高级功能：编辑、撤回、回复线程、消息效果、群组管理。
## 快速开始
1. 在你的 Mac 上安装 BlueBubbles 服务器（按照 [bluebubbles.app/install](https://bluebubbles.app/install) 的说明操作）。
2. 在 BlueBubbles 配置中，启用 web API 并设置密码。
1. 在你的 Mac 上安装 BlueBubbles 服务器（按照 [bluebubbles.app/install](https://bluebubbles.app/install) 上的说明操作）。
2. 在 BlueBubbles 配置中启用 Web API 并设置密码。
3. 运行 `openclaw onboard` 并选择 BlueBubbles，或手动配置：
```json5
{
channels: {
@ -46,8 +47,89 @@ x-i18n:
},
}
```
4. 将 BlueBubbles webhook 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）。
5. 启动 Gateway 网关；它将注册 webhook 处理程序并开始配对。
5. 启动 Gateway 网关；它会注册 webhook 处理器并开始配对。
安全说明：
- 始终设置 webhook 密码。
- 始终要求进行 webhook 身份验证。无论 loopback/代理拓扑如何，除非 BlueBubbles webhook 请求包含与 `channels.bluebubbles.password` 匹配的 password/guid（例如 `?password=<password>` 或 `x-password`），否则 OpenClaw 会拒绝该请求。
- 在读取/解析完整 webhook 请求体之前就会检查密码身份验证。
## 保持 Messages.app 处于活动状态（VM / 无头设置）
某些 macOS VM / 常开设置可能会导致 Messages.app 进入“空闲”状态（传入事件会停止，直到应用被打开/切到前台）。一个简单的解决方法是使用 AppleScript + LaunchAgent **每 5 分钟“触碰”一次 Messages**。
### 1）保存 AppleScript
将以下内容保存为：
- `~/Scripts/poke-messages.scpt`
示例脚本（非交互式；不会抢占焦点）：
```applescript
try
tell application "Messages"
if not running then
launch
end if
-- Touch the scripting interface to keep the process responsive.
set _chatCount to (count of chats)
end tell
on error
-- Ignore transient failures (first-run prompts, locked session, etc).
end try
```
### 2）安装 LaunchAgent
将以下内容保存为：
- `~/Library/LaunchAgents/com.user.poke-messages.plist`
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.user.poke-messages</string>
<key>ProgramArguments</key>
<array>
<string>/bin/bash</string>
<string>-lc</string>
<string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StartInterval</key>
<integer>300</integer>
<key>StandardOutPath</key>
<string>/tmp/poke-messages.log</string>
<key>StandardErrorPath</key>
<string>/tmp/poke-messages.err</string>
</dict>
</plist>
```
说明：
- 这会**每 300 秒**运行一次，并且**在登录时**运行。
- 首次运行可能会触发 macOS 的**自动化**权限提示（`osascript` → Messages）。请在运行该 LaunchAgent 的同一用户会话中批准这些提示。
加载它：
```bash
launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
```
## 新手引导
@ -60,10 +142,10 @@ openclaw onboard
向导会提示输入：
- **服务器 URL**（必填）：BlueBubbles 服务器地址（例如 `http://192.168.1.100:1234`）
- **密码**（必填）：来自 BlueBubbles 服务器设置的 API 密码
- **密码**（必填）：来自 BlueBubbles Server 设置的 API 密码
- **Webhook 路径**（可选）：默认为 `/bluebubbles-webhook`
- **私信策略**：配对、白名单、开放或禁用
- **白名单**：电话号码、电子邮件或聊天目标
- **私信策略**：pairing、allowlist、open 或 disabled
- **允许列表**：电话号码、电子邮件或聊天目标
你也可以通过 CLI 添加 BlueBubbles：
@ -75,12 +157,12 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
私信：
- 默认：`channels.bluebubbles.dmPolicy = "pairing"`。
- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。
- 批准方式：
- 默认值：`channels.bluebubbles.dmPolicy = "pairing"`。
- 未知发送者会收到一个配对码；在获得批准前，消息会被忽略（代码 1 小时后过期）。
- 通过以下方式批准：
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- 配对是默认的令牌交换方式。详情：[配对](/channels/pairing)
- 配对是默认的令牌交换方式。详情见：[配对](/channels/pairing)
群组：
@ -89,13 +171,13 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
### 提及门控（群组）
BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
BlueBubbles 支持群聊中的提及门控，与 iMessage/WhatsApp 的行为一致：
- 使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）检测提及。
- 当群组启用 `requireMention` 时，智能体仅在被提及时响应。
- 当某个群组启用 `requireMention` 时，智能体只有在被提及时才会响应。
- 来自授权发送者的控制命令会绕过提及门控。
单群组配置：
每群组配置：
```json5
{
@ -104,8 +186,8 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
groupPolicy: "allowlist",
groupAllowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true }, // 所有群组的默认设置
"iMessage;-;chat123": { requireMention: false }, // 特定群组的覆盖设置
"*": { requireMention: true }, // 所有群组的默认值
"iMessage;-;chat123": { requireMention: false }, // 对特定群组覆盖
},
},
},
@ -115,14 +197,14 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
### 命令门控
- 控制命令（例如 `/config`、`/model`）需要授权。
- 使用 `allowFrom` 和 `groupAllowFrom` 确定命令授权。
- 授权发送者即使在群组中未被提及也可以运行控制命令。
- 使用 `allowFrom` 和 `groupAllowFrom` 来判断命令授权。
- 授权发送者即使在群组中未提及，也可以运行控制命令。
## 输入状态 + 已读回执
- **输入指示器**：在响应生成前和生成期间自动发送。
- **输入状态指示**：会在生成响应之前和期间自动发送。
- **已读回执**：由 `channels.bluebubbles.sendReadReceipts` 控制（默认：`true`）。
- **输入指示器**：OpenClaw 发送输入开始事件；BlueBubbles 在发送或超时时自动清除输入状态（通过 DELETE 手动停止不可靠）。
- **输入状态指示**：OpenClaw 会发送输入开始事件；BlueBubbles 会在发送后或超时后自动清除输入状态（通过 DELETE 手动停止并不可靠）。
```json5
{
@ -136,7 +218,7 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致：
## 高级操作
BlueBubbles 在配置中启用时支持高级消息操作：
在配置中启用后，BlueBubbles 支持高级消息操作：
```json5
{
@ -144,15 +226,15 @@ BlueBubbles 在配置中启用时支持高级消息操作：
bluebubbles: {
actions: {
reactions: true, // tapback（默认：true）
edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上不可用）
edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上已损坏）
unsend: true, // 撤回消息（macOS 13+）
reply: true, // 通过消息 GUID 进行回复线程
reply: true, // 按消息 GUID 回复线程
sendWithEffect: true, // 消息效果（slam、loud 等）
renameGroup: true, // 重命名群聊
setGroupIcon: true, // 设置群聊图标/照片（在 macOS 26 Tahoe 上不稳定）
addParticipant: true, // 将参与者添加到群组
addParticipant: true, // 向群组添加参与者
removeParticipant: true, // 从群组移除参与者
leaveGroup: true, // 离开群聊
leaveGroup: true, // 退出群聊
sendAttachment: true, // 发送附件/媒体
},
},
@ -163,37 +245,37 @@ BlueBubbles 在配置中启用时支持高级消息操作：
可用操作：
- **react**：添加/移除 tapback 回应（`messageId`、`emoji`、`remove`）
- **edit**：编辑已发送的消息（`messageId`、`text`）
- **edit**：编辑已发送消息（`messageId`、`text`）
- **unsend**：撤回消息（`messageId`）
- **reply**：回复特定消息（`messageId`、`text`、`to`）
- **sendWithEffect**：带 iMessage 效果发送（`text`、`to`、`effectId`）
- **renameGroup**：重命名群聊（`chatGuid`、`displayName`）
- **setGroupIcon**：设置群聊图标/照片（`chatGuid`、`media`）— 在 macOS 26 Tahoe 上不稳定（API 可能返回成功但图标未同步）。
- **addParticipant**：将某人添加到群组（`chatGuid`、`address`）
- **removeParticipant**：将某人从群组移除（`chatGuid`、`address`）
- **leaveGroup**：离开群聊（`chatGuid`）
- **setGroupIcon**：设置群聊图标/照片（`chatGuid`、`media`）——在 macOS 26 Tahoe 上不稳定（API 可能返回成功，但图标不会同步）。
- **addParticipant**：向群组添加某人（`chatGuid`、`address`）
- **removeParticipant**：从群组移除某人（`chatGuid`、`address`）
- **leaveGroup**：退出群聊（`chatGuid`）
- **sendAttachment**：发送媒体/文件（`to`、`buffer`、`filename`、`asVoice`）
- 语音备忘录：将 `asVoice: true` 与 **MP3** 或 **CAF** 音频一起设置，以 iMessage 语音消息形式发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。
- 语音备忘录：将 `asVoice: true` 与 **MP3** 或 **CAF** 音频一起设置，即可作为 iMessage 语音消息发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。
### 消息 ID（短格式 vs 完整格式）
### 消息 ID（短 ID 与完整 ID）
OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
- `MessageSid` / `ReplyToId` 可以是短 ID。
- `MessageSidFull` / `ReplyToIdFull` 包含提供商的完整 ID。
- 短 ID 存储在内存中；它们可能在重启或缓存清除后过期。
- 操作接受短或完整的 `messageId`，但如果短 ID 不再可用将会报错。
- 短 ID 存在于内存中；它们可能会在重启或缓存清除后失效。
- 操作接受短或完整 `messageId`，但如果短 ID 不再可用，就会报错。
对于持久化自动化和存储，请使用完整 ID：
- 模板：`{{MessageSidFull}}`、`{{ReplyToIdFull}}`
- 上下文：入站负载中的 `MessageSidFull` / `ReplyToIdFull`
参见[配置](/gateway/configuration)了解模板变量。
模板变量请参见[配置](/gateway/configuration)。
## 分块流式传输
控制响应是作为单条消息发送还是分块流式传输：
控制响应是作为单条消息发送，还是按块流式发送：
```json5
{
@ -208,8 +290,8 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
## 媒体 + 限制
- 入站附件会被下载并存储在媒体缓存中。
- 媒体上限通过 `channels.bluebubbles.mediaMaxMb` 设置（默认：8 MB）。
- 出站文本按 `channels.bluebubbles.textChunkLimit` 分块（默认：4000 字符）。
- 通过 `channels.bluebubbles.mediaMaxMb` 控制入站和出站媒体大小上限（默认：8 MB）。
- 出站文本会按 `channels.bluebubbles.textChunkLimit` 分块（默认：4000 个字符）。
## 配置参考
@ -217,22 +299,23 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
提供商选项：
- `channels.bluebubbles.enabled`：启用/禁用渠道。
- `channels.bluebubbles.enabled`：启用/禁用该渠道。
- `channels.bluebubbles.serverUrl`：BlueBubbles REST API 基础 URL。
- `channels.bluebubbles.password`：API 密码。
- `channels.bluebubbles.webhookPath`：Webhook 端点路径（默认：`/bluebubbles-webhook`）。
- `channels.bluebubbles.dmPolicy`：`pairing | allowlist | open | disabled`（默认：`pairing`）。
- `channels.bluebubbles.allowFrom`：私信白名单（句柄、电子邮件、E.164 号码、`chat_id:*`、`chat_guid:*`）。
- `channels.bluebubbles.allowFrom`：私信 allowlist（handle、电子邮件、E.164 号码、`chat_id:*`、`chat_guid:*`）。
- `channels.bluebubbles.groupPolicy`：`open | allowlist | disabled`（默认：`allowlist`）。
- `channels.bluebubbles.groupAllowFrom`：群组发送者白名单。
- `channels.bluebubbles.groups`：单群组配置（`requireMention` 等）。
- `channels.bluebubbles.groupAllowFrom`：群组发送者 allowlist。
- `channels.bluebubbles.groups`：每群组配置（`requireMention` 等）。
- `channels.bluebubbles.sendReadReceipts`：发送已读回执（默认：`true`）。
- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`false`；流式回复必需）。
- `channels.bluebubbles.textChunkLimit`：出站分块大小（字符）（默认：4000）。
- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在长度分块前先按空行（段落边界）分割。
- `channels.bluebubbles.mediaMaxMb`：入站媒体上限（MB）（默认：8）。
- `channels.bluebubbles.historyLimit`：上下文的最大群组消息数（0 表示禁用）。
- `channels.bluebubbles.dmHistoryLimit`：私信历史限制。
- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`false`；流式回复所必需）。
- `channels.bluebubbles.textChunkLimit`：出站分块大小（按字符计，默认：4000）。
- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时拆分；`newline` 会先按空行（段落边界）拆分，再按长度分块。
- `channels.bluebubbles.mediaMaxMb`：入站/出站媒体大小上限（MB，默认：8）。
- `channels.bluebubbles.mediaLocalRoots`：允许用于出站本地媒体路径的绝对本地目录显式 allowlist。默认情况下，本地路径发送会被拒绝，除非配置了此项。每账户覆盖：`channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`。
- `channels.bluebubbles.historyLimit`：用于上下文的最大群组消息数（0 表示禁用）。
- `channels.bluebubbles.dmHistoryLimit`：私信历史记录上限。
- `channels.bluebubbles.actions`：启用/禁用特定操作。
- `channels.bluebubbles.accounts`：多账户配置。
@ -241,31 +324,31 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
- `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）。
- `messages.responsePrefix`。
## 地址 / 投递目标
## 寻址 / 送达目标
优先使用 `chat_guid` 以获得稳定的路由：
优先使用 `chat_guid` 以获得稳定路由：
- `chat_guid:iMessage;-;+15555550123`（群组推荐）
- `chat_guid:iMessage;-;+15555550123`（群组首选）
- `chat_id:123`
- `chat_identifier:...`
- 直接句柄：`+15555550123`、`user@example.com`
- 如果直接句柄没有现有的私信聊天，OpenClaw 将通过 `POST /api/v1/chat/new` 创建一个。这需要启用 BlueBubbles Private API。
- 直接 handle：`+15555550123`、`user@example.com`
- 如果某个直接 handle 没有现有私信聊天，OpenClaw 会通过 `POST /api/v1/chat/new` 创建一个。这要求启用 BlueBubbles Private API。
## 安全性
## 安全
- Webhook 请求通过比较 `guid`/`password` 查询参数或头部与 `channels.bluebubbles.password` 进行身份验证。来自 `localhost` 的请求也会被接受。
- 保持 API 密码和 webhook 端点的机密性（将它们视为凭证）。
- localhost 信任意味着同主机的反向代理可能无意中绕过密码验证。如果你使用代理 Gateway 网关，请在代理处要求身份验证并配置 `gateway.trustedProxies`。参见 [Gateway 网关安全性](/gateway/security#reverse-proxy-configuration)。
- 如果将 BlueBubbles 服务器暴露在局域网之外，请启用 HTTPS + 防火墙规则。
- 通过将查询参数或请求头中的 `guid`/`password` 与 `channels.bluebubbles.password` 进行比较来验证 webhook 请求。来自 `localhost` 的请求也会被接受。
- 请妥善保管 API 密码和 webhook 端点（将它们视为凭证）。
- 对 localhost 的信任意味着同主机上的反向代理可能会无意中绕过密码。如果你对 Gateway 网关进行了代理，请在代理层要求身份验证，并配置 `gateway.trustedProxies`。请参见 [Gateway 网关安全](/gateway/security#reverse-proxy-configuration)。
- 如果要在局域网外暴露 BlueBubbles 服务器，请启用 HTTPS + 防火墙规则。
## 故障排除
- 如果输入/已读事件停止工作，请检查 BlueBubbles webhook 日志并验证 Gateway 网关路径是否与 `channels.bluebubbles.webhookPath` 匹配。
- 配对码在一小时后过期；使用 `openclaw pairing list bluebubbles` 和 `openclaw pairing approve bluebubbles <code>`。
- 回应需要 BlueBubbles private API（`POST /api/v1/message/react`）；确保服务器版本支持它。
- 编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑功能目前不可用。
- 在 macOS 26（Tahoe）上群组图标更新可能不稳定：API 可能返回成功但新图标未同步。
- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果在 macOS 26（Tahoe）上编辑仍然显示，请使用 `channels.bluebubbles.actions.edit=false` 手动禁用。
- 查看状态/健康信息：`openclaw status --all` 或 `openclaw status --deep`。
- 如果输入状态/已读事件停止工作，请检查 BlueBubbles webhook 日志，并验证 Gateway 网关路径与 `channels.bluebubbles.webhookPath` 一致。
- 配对码会在一小时后过期；使用 `openclaw pairing list bluebubbles` 和 `openclaw pairing approve bluebubbles <code>`。
- 回应需要 BlueBubbles private API（`POST /api/v1/message/react`）；请确保服务器版本提供该接口。
- 编辑/撤回需要 macOS 13+ 以及兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑功能目前已损坏。
- 群组图标更新在 macOS 26（Tahoe）上可能不稳定：API 可能返回成功，但新图标不会同步。
- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知损坏的操作。如果在 macOS 26（Tahoe）上仍显示编辑操作，请手动使用 `channels.bluebubbles.actions.edit=false` 禁用它。
- 状态/健康信息请使用：`openclaw status --all` 或 `openclaw status --deep`。
有关通用渠道工作流参考，请参阅[渠道](/channels)和[插件](/tools/plugin)指南。
有关通用渠道工作流程参考，请参见 [Channels](/channels) 和 [Plugins](/tools/plugin) 指南。

565
docs/zh-CN/channels/feishu.md
View File

@ -1,22 +1,29 @@
---
summary: "飞书机器人支持状态、功能和配置"
read_when:
- 您想要连接飞书机器人
- 您正在配置飞书渠道
- 你想连接一个飞书/Lark 机器人
- 你正在配置飞书渠道
summary: 飞书机器人概览、功能和配置
title: 飞书
x-i18n:
generated_at: "2026-03-16T06:21:11Z"
model: gpt-5.4
provider: openai
source_hash: 951e78c5c7264471382f863fa896a15ddeaf0717ef782da20d0f1b3eb23396ba
source_path: channels/feishu.md
workflow: 15
---
# 飞书机器人
状态：生产就绪，支持机器人私聊和群组。使用 WebSocket 长连接模式接收消息。
飞书（Lark）是企业用于消息沟通与协作的团队聊天平台。此插件通过平台的 WebSocket 事件订阅将 OpenClaw 连接到飞书/Lark 机器人，因此无需暴露公共 webhook URL 即可接收消息。
---
## 内置插件
## 捆绑插件
当前版本的 OpenClaw 已内置 Feishu 插件，因此通常不需要单独安装。
飞书随当前的 OpenClaw 版本一同捆绑提供，因此无需单独安装插件。
如果你使用的是较旧版本，或是没有内置 Feishu 的自定义安装，可手动安装：
如果你使用的是较旧版本，或使用了不包含捆绑飞书的自定义安装，请手动安装：
```bash
openclaw plugins install @openclaw/feishu
@ -26,75 +33,75 @@ openclaw plugins install @openclaw/feishu
## 快速开始
添加飞书渠道有两种方式：
有两种方式可添加飞书渠道：
### 方式一：通过安装向导添加（推荐）
### 方法 1：设置向导（推荐）
如果您刚安装完 OpenClaw，可以直接运行向导，根据提示添加飞书：
如果你刚安装 OpenClaw，请运行设置向导：
```bash
openclaw onboard
```
向导会引导您完成：
向导会引导你完成以下步骤：
1. 创建飞书应用并获取凭证
2. 配置应用凭证
3. 启动网关
1. 创建飞书应用并收集凭证
2. 在 OpenClaw 中配置应用凭证
3. 启动 Gateway 网关
✅ **完成配置后**，您可以使用以下命令检查网关状态：
✅ **配置完成后**，检查 Gateway 网关状态：
- `openclaw gateway status` - 查看网关运行状态
- `openclaw logs --follow` - 查看实时日志
- `openclaw gateway status`
- `openclaw logs --follow`
### 方式二：通过命令行添加
### 方法 2：CLI 设置
如果您已经完成了初始安装，可以用以下命令添加飞书渠道：
如果你已经完成初始安装，可通过 CLI 添加该渠道：
```bash
openclaw channels add
```
然后根据交互式提示选择 Feishu，输入 App ID 和 App Secret 即可。
选择 **Feishu**，然后输入 App ID 和 App Secret。
✅ **完成配置后**，您可以使用以下命令管理网关：
✅ **配置完成后**，管理 Gateway 网关：
- `openclaw gateway status` - 查看网关运行状态
- `openclaw gateway restart` - 重启网关以应用新配置
- `openclaw logs --follow` - 查看实时日志
- `openclaw gateway status`
- `openclaw gateway restart`
- `openclaw logs --follow`
---
## 第一步：创建飞书应用
## 第 1 步：创建飞书应用
### 1. 打开飞书开放平台
访问 [飞书开放平台](https://open.feishu.cn/app)，使用飞书账号登录。
访问 [Feishu Open Platform](https://open.feishu.cn/app) 并登录。
Lark（国际版）请使用 https://open.larksuite.com/app，并在配置中设置 `domain: "lark"`。
Lark（国际版）租户应使用 [https://open.larksuite.com/app](https://open.larksuite.com/app)，并在飞书配置中设置 `domain: "lark"`。
### 2. 创建应用
1. 点击 **创建企业自建应用**
1. 点击 **Create enterprise app**
2. 填写应用名称和描述
3. 选择应用图标
![创建企业自建应用](/images/feishu-step2-create-app.png)
![Create enterprise app](../images/feishu-step2-create-app.png)
### 3. 获取应用凭证
### 3. 复制凭证
在应用的 **凭证与基础信息** 页面，复制：
在 **Credentials & Basic Info** 中，复制：
- **App ID**（格式如 `cli_xxx`）
- **App ID**（格式：`cli_xxx`）
- **App Secret**
❗ **重要**：请妥善保管 App Secret，不要分享给他人。
❗ **重要：**请将 App Secret 妥善保密。
![获取应用凭证](/images/feishu-step3-credentials.png)
![Get credentials](../images/feishu-step3-credentials.png)
### 4. 配置应用权限
### 4. 配置权限
在 **权限管理** 页面，点击 **批量导入** 按钮，粘贴以下 JSON 配置一键导入所需权限：
在 **Permissions** 中，点击 **Batch import** 并粘贴：
```json
{
@ -105,81 +112,71 @@ Lark（国际版）请使用 https://open.larksuite.com/app，并在配置中设
"application:application.app_message_stats.overview:readonly",
"application:application:self_manage",
"application:bot.menu:write",
"cardkit:card:read",
"cardkit:card:write",
"contact:user.employee_id:readonly",
"corehr:file:download",
"docs:document.content:read",
"event:ip_list",
"im:chat",
"im:chat.access_event.bot_p2p_chat:read",
"im:chat.members:bot_access",
"im:message",
"im:message.group_at_msg:readonly",
"im:message.group_msg",
"im:message.p2p_msg:readonly",
"im:message:readonly",
"im:message:send_as_bot",
"im:resource",
"sheets:spreadsheet",
"wiki:wiki:readonly"
"im:resource"
],
"user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
}
}
```
![配置应用权限](/images/feishu-step4-permissions.png)
![Configure permissions](../images/feishu-step4-permissions.png)
### 5. 启用机器人能力
在 **应用能力** > **机器人** 页面：
在 **App Capability** > **Bot** 中：
1. 开启机器人能力
2. 配置机器人名称
1. 启用机器人能力
2. 设置机器人名称
![启用机器人能力](/images/feishu-step5-bot-capability.png)
![Enable bot capability](../images/feishu-step5-bot-capability.png)
### 6. 配置事件订阅
⚠️ **重要提醒**：在配置事件订阅前，请务必确保已完成以下步骤：
⚠️ **重要：**在设置事件订阅前，请确保：
1. 运行 `openclaw channels add` 添加了 Feishu 渠道
2. 网关处于启动状态（可通过 `openclaw gateway status` 检查状态）
1. 你已经为飞书运行过 `openclaw channels add`
2. Gateway 网关正在运行（`openclaw gateway status`）
在 **事件订阅** 页面：
在 **Event Subscription** 中：
1. 选择 **使用长连接接收事件**（WebSocket 模式）
2. 添加事件：
- `im.message.receive_v1`
- `im.message.reaction.created_v1`
- `im.message.reaction.deleted_v1`
- `application.bot.menu_v6`
1. 选择 **Use long connection to receive events**（WebSocket）
2. 添加事件：`im.message.receive_v1`
⚠️ **注意**：如果网关未启动或渠道未添加，长连接设置将保存失败。
⚠️ 如果 Gateway 网关未运行，长连接设置可能无法保存。
![配置事件订阅](/images/feishu-step6-event-subscription.png)
![Configure event subscription](../images/feishu-step6-event-subscription.png)
### 7. 发布应用
1. 在 **版本管理与发布** 页面创建版本
1. 在 **Version Management & Release** 中创建版本
2. 提交审核并发布
3. 等待管理员审批（企业自建应用通常自动通过）
3. 等待管理员批准（企业应用通常会自动批准）
---
## 第二步：配置 OpenClaw
## 第 2 步：配置 OpenClaw
### 通过向导配置（推荐）
运行以下命令，根据提示粘贴 App ID 和 App Secret：
### 使用向导配置（推荐）
```bash
openclaw channels add
```
选择 **Feishu**，然后输入您在第一步获取的凭证即可。
选择 **Feishu**，然后粘贴你的 App ID 和 App Secret。
### 通过配置文件配置
### 通过配置文件进行配置
编辑 `~/.openclaw/openclaw.json`：
@ -193,7 +190,7 @@ openclaw channels add
main: {
appId: "cli_xxx",
appSecret: "xxx",
botName: "我的AI助手",
botName: "My AI assistant",
},
},
},
@ -201,18 +198,20 @@ openclaw channels add
}
```
若使用 `connectionMode: "webhook"`，需设置 `verificationToken`。飞书 Webhook 服务默认绑定 `127.0.0.1`；仅在需要不同监听地址时设置 `webhookHost`。
如果你使用 `connectionMode: "webhook"`，请同时设置 `verificationToken` 和 `encryptKey`。飞书 webhook 服务器默认绑定到 `127.0.0.1`；只有在你明确需要不同绑定地址时，才设置 `webhookHost`。
#### 获取 Verification Token（仅 Webhook 模式）
#### Verification Token 和 Encrypt Key（webhook 模式）
使用 Webhook 模式时，需在配置中设置 `channels.feishu.verificationToken`。获取方式：
使用 webhook 模式时，请在配置中同时设置 `channels.feishu.verificationToken` 和 `channels.feishu.encryptKey`。获取这些值的方法如下：
1. 在飞书开放平台打开您的应用
2. 进入 **开发配置** → **事件与回调**
3. 打开 **加密策略** 选项卡
4. 复制 **Verification Token**（校验令牌）
1. 在飞书开放平台中，打开你的应用
2. 前往 **Development** → **Events & Callbacks**（开发配置 → 事件与回调）
3. 打开 **Encryption** 标签页（加密策略）
4. 复制 **Verification Token** 和 **Encrypt Key**
![Verification Token 位置](/images/feishu-verification-token.png)
下图展示了 **Verification Token** 的位置。**Encrypt Key** 位于同一个 **Encryption** 区域中。
![Verification Token location](../images/feishu-verification-token.png)
### 通过环境变量配置
@ -223,7 +222,7 @@ export FEISHU_APP_SECRET="xxx"
### Lark（国际版）域名
如果您的租户在 Lark（国际版），请设置域名为 `lark`（或完整域名），可配置 `channels.feishu.domain` 或 `channels.feishu.accounts.<id>.domain`：
如果你的租户位于 Lark（国际版），请将域名设置为 `lark`（或完整域名字串）。你可以在 `channels.feishu.domain` 设置，也可以按账户设置（`channels.feishu.accounts.<id>.domain`）。
```json5
{
@ -241,14 +240,14 @@ export FEISHU_APP_SECRET="xxx"
}
```
### 配额优化
### 配额优化标志
可通过以下可选配置减少飞书 API 调用：
你可以使用两个可选标志来减少飞书 API 使用量：
- `typingIndicator`（默认 `true`）：设为 `false` 时不发送“正在输入”状态。
- `resolveSenderNames`（默认 `true`）：设为 `false` 时不拉取发送者资料。
- `typingIndicator`（默认 `true`）：设为 `false` 时，跳过“正在输入”反应调用。
- `resolveSenderNames`（默认 `true`）：设为 `false` 时，跳过发送者资料查询调用。
可在渠道级或账号级配置：
你可以在顶层或按账户进行设置：
```json5
{
@ -271,9 +270,9 @@ export FEISHU_APP_SECRET="xxx"
---
## 第三步：启动并测试
## 第 3 步：启动并测试
### 1. 启动网关
### 1. 启动 Gateway 网关
```bash
openclaw gateway
@ -281,74 +280,74 @@ openclaw gateway
### 2. 发送测试消息
在飞书中找到您创建的机器人，发送一条消息。
在飞书中找到你的机器人并发送一条消息。
### 3. 配对授权
### 3. 批准配对
默认情况下，机器人会回复一个 **配对码**。您需要批准此代码：
默认情况下，机器人会回复一个配对码。批准它：
```bash
openclaw pairing approve feishu <配对码>
openclaw pairing approve feishu <CODE>
```
批准后即可正常对话。
批准后，你就可以正常聊天了。
---
## 介绍
## 概览
- **飞书机器人渠道**：由网关管理的飞书机器人
- **确定性路由**：回复始终返回飞书，模型不会选择渠道
- **会话隔离**：私聊共享主会话；群组独立隔离
- **WebSocket 连接**：使用飞书 SDK 的长连接模式，无需公网 URL
- **飞书机器人渠道**：由 Gateway 网关管理的飞书机器人
- **确定性路由**：回复始终返回到飞书
- **会话隔离**：私信共享主会话；群组彼此隔离
- **WebSocket 连接**：通过飞书 SDK 建立长连接，无需公共 URL
---
## 访问控制
### 私聊访问
### 私信
- **默认**：`dmPolicy: "pairing"`，陌生用户会收到配对码
- **默认**：`dmPolicy: "pairing"`（未知用户会收到配对码）
- **批准配对**：
```bash
openclaw pairing list feishu # 查看待审批列表
openclaw pairing approve feishu <CODE> # 批准
```
- **白名单模式**：通过 `channels.feishu.allowFrom` 配置允许的用户 Open ID
### 群组访问
```bash
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>
```
- **Allowlist 模式**：设置 `channels.feishu.allowFrom`，填入允许的 Open ID
### 群聊
**1. 群组策略**（`channels.feishu.groupPolicy`）：
- `"open"` = 允许群组中所有人（默认）
- `"allowlist"` = 仅允许 `groupAllowFrom` 中的群组
- `"disabled"` = 禁用群组消息
- `"open"` = 允许群组中的所有人（默认）
- `"allowlist"` = 仅允许 `groupAllowFrom`
- `"disabled"` = 禁用群消息
**2. @提及要求**（`channels.feishu.groups.<chat_id>.requireMention`）：
**2. 提及要求**（`channels.feishu.groups.<chat_id>.requireMention`）：
- `true` = 需要 @机器人才响应（默认）
- `false` = 无需 @也响应
- `true` = 需要 @ 提及（默认）
- `false` = 无需提及也会回复
---
## 群组配置示例
### 允许所有群组，需要 @提及（默认行为）
### 允许所有群组，要求 @ 提及（默认）
```json5
{
channels: {
feishu: {
groupPolicy: "open",
// 默认 requireMention: true
// Default requireMention: true
},
},
}
```
### 允许所有群组，无需 @提及
需要为特定群组配置：
### 允许所有群组，无需 @ 提及
```json5
{
@ -369,16 +368,16 @@ openclaw pairing approve feishu <配对码>
channels: {
feishu: {
groupPolicy: "allowlist",
// 群组 ID 格式为 oc_xxx
// Feishu group IDs (chat_id) look like: oc_xxx
groupAllowFrom: ["oc_xxx", "oc_yyy"],
},
},
}
```
### 仅允许特定成员在群组中发信（发送者白名单）
### 限制哪些发送者可以在群组中发消息（发送者 allowlist）
除群组白名单外，该群组内**所有消息**均按发送者 open_id 校验：仅 `groups.<chat_id>.allowFrom` 中列出的用户消息会被处理，其他成员的消息会被忽略（此为发送者级白名单，不仅针对 /reset、/new 等控制命令）。
除了允许群组本身外，该群组中的**所有消息**还会按发送者 `open_id` 进行限制：只有列在 `groups.<chat_id>.allowFrom` 中的用户，其消息才会被处理；其他成员发送的消息会被忽略（这是完整的发送者级限制，而不只是对 `/reset` 或 `/new` 等控制命令生效）。
```json5
{
@ -388,7 +387,7 @@ openclaw pairing approve feishu <配对码>
groupAllowFrom: ["oc_xxx"],
groups: {
oc_xxx: {
// 用户 open_id 格式为 ou_xxx
// Feishu user IDs (open_id) look like: ou_xxx
allowFrom: ["ou_user1", "ou_user2"],
},
},
@ -401,29 +400,31 @@ openclaw pairing approve feishu <配对码>
## 获取群组/用户 ID
### 获取群组 ID（chat_id）
### 群组 ID（`chat_id`）
群组 ID 格式为 `oc_xxx`，可以通过以下方式获取：
群组 ID 看起来像 `oc_xxx`。
**方法一**（推荐）：
**方法 1（推荐）**
1. 启动网关并在群组中 @机器人发消息
2. 运行 `openclaw logs --follow` 查看日志中的 `chat_id`
1. 启动 Gateway 网关并在群里 @ 提及机器人
2. 运行 `openclaw logs --follow` 并查找 `chat_id`
**方法二**：
使用飞书 API 调试工具获取机器人所在群组列表。
**方法 2**
### 获取用户 ID（open_id）
使用飞书 API 调试器列出群聊。
用户 ID 格式为 `ou_xxx`，可以通过以下方式获取：
### 用户 ID（`open_id`）
**方法一**（推荐）：
用户 ID 看起来像 `ou_xxx`。
1. 启动网关并给机器人发消息
2. 运行 `openclaw logs --follow` 查看日志中的 `open_id`
**方法 1（推荐）**
**方法二**：
查看配对请求列表，其中包含用户的 Open ID：
1. 启动 Gateway 网关并向机器人发送私信
2. 运行 `openclaw logs --follow` 并查找 `open_id`
**方法 2**
检查配对请求中的用户 Open ID：
```bash
openclaw pairing list feishu
@ -433,65 +434,61 @@ openclaw pairing list feishu
## 常用命令
| 命令 | 说明 |
| Command | Description |
| --------- | -------------- |
| `/status` | 查看机器人状态 |
| `/reset` | 重置对话会话 |
| `/model` | 查看/切换模型 |
| `/status` | 显示机器人状态 |
| `/reset` | 重置会话 |
| `/model` | 显示/切换模型 |
飞书机器人菜单建议直接在飞书开放平台的机器人能力页面配置。OpenClaw 当前支持接收 `application.bot.menu_v6` 事件，并把点击事件转换成普通文本命令（例如 `/menu <eventKey>`）继续走现有消息路由，但不通过渠道配置自动创建或同步菜单。
> 注意：飞书暂不支持原生命令菜单，因此命令必须以文本形式发送。
## 网关管理命令
## Gateway 网关管理命令
在配置和使用飞书渠道时，您可能需要使用以下网关管理命令：
| 命令 | 说明 |
| -------------------------- | ----------------- |
| `openclaw gateway status` | 查看网关运行状态 |
| `openclaw gateway install` | 安装/启动网关服务 |
| `openclaw gateway stop` | 停止网关服务 |
| `openclaw gateway restart` | 重启网关服务 |
| `openclaw logs --follow` | 实时查看日志输出 |
| Command | Description |
| -------------------------- | -------------------------- |
| `openclaw gateway status` | 显示 Gateway 网关状态 |
| `openclaw gateway install` | 安装/启动 Gateway 网关服务 |
| `openclaw gateway stop` | 停止 Gateway 网关服务 |
| `openclaw gateway restart` | 重启 Gateway 网关服务 |
| `openclaw logs --follow` | 跟踪 Gateway 网关日志 |
---
## 故障排除
### 机器人在群组中不响应
### 机器人在群聊中没有响应
1. 检查机器人是否已添加到群组
2. 检查是否 @了机器人（默认需要 @提及）
3. 检查 `groupPolicy` 是否为 `"disabled"`
4. 查看日志：`openclaw logs --follow`
1. 确保机器人已加入群组
2. 确保你 @ 提及了机器人（默认行为）
3. 检查 `groupPolicy` 未设置为 `"disabled"`
4. 检查日志：`openclaw logs --follow`
### 机器人收不到消息
### 机器人未接收到消息
1. 检查应用是否已发布并审批通过
2. 检查事件订阅是否配置正确（`im.message.receive_v1`）
3. 检查是否选择了 **长连接** 模式
4. 检查应用权限是否完整
5. 检查网关是否正在运行：`openclaw gateway status`
6. 查看实时日志：`openclaw logs --follow`
1. 确保应用已发布并获批准
2. 确保事件订阅包含 `im.message.receive_v1`
3. 确保已启用**长连接**
4. 确保应用权限完整
5. 确保 Gateway 网关正在运行：`openclaw gateway status`
6. 检查日志：`openclaw logs --follow`
### App Secret 泄露怎么办
### App Secret 泄露
1. 在飞书开放平台重置 App Secret
2. 更新配置文件中的 App Secret
3. 重启网关
1. 在飞书开放平台中重置 App Secret
2. 在你的配置中更新 App Secret
3. 重启 Gateway 网关
### 发送消息失败
### 消息发送失败
1. 检查应用是否有 `im:message:send_as_bot` 权限
2. 检查应用是否已发布
3. 查看日志获取详细错误信息
1. 确保应用具有 `im:message:send_as_bot` 权限
2. 确保应用已发布
3. 查看日志以获取详细错误信息
---
## 高级配置
### 多账号配置
如果需要管理多个飞书机器人，可配置 `defaultAccount` 指定出站未显式指定 `accountId` 时使用的账号：
### 多账户
```json5
{
@ -502,13 +499,13 @@ openclaw pairing list feishu
main: {
appId: "cli_xxx",
appSecret: "xxx",
botName: "主机器人",
botName: "Primary bot",
},
backup: {
appId: "cli_yyy",
appSecret: "yyy",
botName: "备用机器人",
enabled: false, // 暂时禁用
botName: "Backup bot",
enabled: false,
},
},
},
@ -516,104 +513,102 @@ openclaw pairing list feishu
}
```
`defaultAccount` 用于控制当出站 API 未显式指定 `accountId` 时，使用哪个飞书账户。
### 消息限制
- `textChunkLimit`：出站文本分块大小（默认 2000 字符）
- `mediaMaxMb`：媒体上传/下载限制（默认 30MB）
- `textChunkLimit`：出站文本分块大小（默认：2000 个字符）
- `mediaMaxMb`：媒体上传/下载限制（默认：30 MB）
### 流式输出
### 流式传输
飞书支持通过交互式卡片实现流式输出，机器人会实时更新卡片内容显示生成进度。默认配置：
飞书通过交互式卡片支持流式回复。启用后，机器人会在生成文本时更新卡片。
```json5
{
channels: {
feishu: {
streaming: true, // 启用流式卡片输出（默认 true）
blockStreamingCoalesce: {
enabled: true,
minDelayMs: 50,
maxDelayMs: 250,
},
blockStreaming: true, // 启用分块流式传输（默认 true）
},
},
}
```
如需禁用流式输出（等待完整回复后一次性发送），可设置 `streaming: false`。
将 `streaming: false` 设为等待完整回复生成后再发送。
### 交互式卡片
### ACP 会话
OpenClaw 默认会在需要时发送 Markdown 卡片；如果你需要完整的 Feishu 原生交互式卡片，也可以显式发送原始 `card` payload。
飞书支持以下 ACP 场景：
- 默认路径：文本自动渲染或 Markdown 卡片
- 显式卡片：通过消息动作的 `card` 参数发送原始交互卡片
- 更新卡片：同一消息支持后续 patch/update
- 私信
- 群组话题会话
卡片按钮回调当前走文本回退路径：
飞书 ACP 由文本命令驱动。没有原生斜杠命令菜单，因此请直接在会话中使用 `/acp ...` 消息。
- 若 `action.value.text` 存在，则作为入站文本继续处理
- 若 `action.value.command` 存在，则作为命令文本继续处理
- 其他对象值会序列化为 JSON 文本
#### 持久化 ACP 绑定
这样可以保持与现有消息/命令路由兼容，而不要求下游先理解 Feishu 专有的交互 payload。
### 表情反应
飞书渠道现已完整支持表情反应生命周期：
- 接收 `reaction created`
- 接收 `reaction deleted`
- 主动添加反应
- 主动删除自身反应
- 查询消息上的反应列表
是否把入站反应转成内部消息，可通过 `reactionNotifications` 控制：
| 值 | 行为 |
| ----- | ---------------------------- |
| `off` | 不生成反应通知 |
| `own` | 仅当反应发生在机器人消息上时 |
| `all` | 所有可验证的反应都生成通知 |
### 消息引用
在群聊中，机器人的回复可以引用用户发送的原始消息，让对话上下文更加清晰。
配置选项：
使用顶层类型化 ACP 绑定，将飞书私信或话题会话固定到持久化 ACP 会话。
```json5
{
channels: {
feishu: {
// 账户级别配置（默认 "all"）
replyToMode: "all",
groups: {
oc_xxx: {
// 特定群组可以覆盖
replyToMode: "first",
agents: {
list: [
{
id: "codex",
runtime: {
type: "acp",
acp: {
agent: "codex",
backend: "acpx",
mode: "persistent",
cwd: "/workspace/openclaw",
},
},
},
},
],
},
bindings: [
{
type: "acp",
agentId: "codex",
match: {
channel: "feishu",
accountId: "default",
peer: { kind: "direct", id: "ou_1234567890" },
},
},
{
type: "acp",
agentId: "codex",
match: {
channel: "feishu",
accountId: "default",
peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
},
acp: { label: "codex-feishu-topic" },
},
],
}
```
`replyToMode` 值说明：
#### 从聊天中按线程绑定 ACP 生成
| 值 | 行为 |
| --------- | ---------------------------------- |
| `"off"` | 不引用原消息（私聊默认值） |
| `"first"` | 仅在第一条回复时引用原消息 |
| `"all"` | 所有回复都引用原消息（群聊默认值） |
在飞书私信或话题会话中，你可以就地生成并绑定一个 ACP 会话：
> 注意：消息引用功能与流式卡片输出（`streaming: true`）不能同时使用。当启用流式输出时，回复会以卡片形式呈现，不会显示引用。
```text
/acp spawn codex --thread here
```
### 多 Agent 路由
说明：
通过 `bindings` 配置，您可以用一个飞书机器人对接多个不同功能或性格的 Agent。系统会根据用户 ID 或群组 ID 自动将对话分发到对应的 Agent。
- `--thread here` 适用于私信和飞书话题。
- 绑定后的私信/话题中的后续消息会直接路由到该 ACP 会话。
- v1 不支持针对通用的非话题群聊。
配置示例：
### 多智能体路由
使用 `bindings` 将飞书私信或群组路由到不同的智能体。
```json5
{
@ -634,91 +629,81 @@ OpenClaw 默认会在需要时发送 Markdown 卡片；如果你需要完整的
},
bindings: [
{
// 用户 A 的私聊 → main agent
agentId: "main",
match: {
channel: "feishu",
peer: { kind: "dm", id: "ou_28b31a88..." },
peer: { kind: "direct", id: "ou_xxx" },
},
},
{
// 用户 B 的私聊 → clawd-fan agent
agentId: "clawd-fan",
match: {
channel: "feishu",
peer: { kind: "dm", id: "ou_0fe6b1c9..." },
peer: { kind: "direct", id: "ou_yyy" },
},
},
{
// 某个群组 → clawd-xi agent
agentId: "clawd-xi",
match: {
channel: "feishu",
peer: { kind: "group", id: "oc_xxx..." },
peer: { kind: "group", id: "oc_zzz" },
},
},
],
}
```
匹配规则说明：
路由字段：
| 字段 | 说明 |
| ----------------- | --------------------------------------------- |
| `agentId` | 目标 Agent 的 ID，需要在 `agents.list` 中定义 |
| `match.channel` | 渠道类型，这里固定为 `"feishu"` |
| `match.peer.kind` | 对话类型：`"dm"`（私聊）或 `"group"`（群组） |
| `match.peer.id` | 用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`） |
- `match.channel`：`"feishu"`
- `match.peer.kind`：`"direct"` 或 `"group"`
- `match.peer.id`：用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`）
> 获取 ID 的方法：参见上文 [获取群组/用户 ID](#获取群组用户-id) 章节。
查找提示请参见 [获取群组/用户 ID](#get-groupuser-ids)。
---
## 配置参考
完整配置请参考：[网关配置](/gateway/configuration)
完整配置：[Gateway 网关配置](/gateway/configuration)
主要选项：
关键选项：
| 配置项 | 说明 | 默认值 |
| ------------------------------------------------- | --------------------------------- | ---------------- |
| `channels.feishu.enabled` | 启用/禁用渠道 | `true` |
| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` |
| `channels.feishu.connectionMode` | 事件传输模式（websocket/webhook） | `websocket` |
| `channels.feishu.defaultAccount` | 出站路由默认账号 ID | `default` |
| `channels.feishu.verificationToken` | Webhook 模式必填 | - |
| `channels.feishu.webhookPath` | Webhook 路由路径 | `/feishu/events` |
| `channels.feishu.webhookHost` | Webhook 监听地址 | `127.0.0.1` |
| `channels.feishu.webhookPort` | Webhook 监听端口 | `3000` |
| `channels.feishu.accounts.<id>.appId` | 应用 App ID | - |
| `channels.feishu.accounts.<id>.appSecret` | 应用 App Secret | - |
| `channels.feishu.accounts.<id>.domain` | 单账号 API 域名覆盖 | `feishu` |
| `channels.feishu.dmPolicy` | 私聊策略 | `pairing` |
| `channels.feishu.allowFrom` | 私聊白名单（open_id 列表） | - |
| `channels.feishu.groupPolicy` | 群组策略 | `allowlist` |
| `channels.feishu.groupAllowFrom` | 群组白名单 | - |
| `channels.feishu.groups.<chat_id>.requireMention` | 是否需要 @提及 | `true` |
| `channels.feishu.groups.<chat_id>.enabled` | 是否启用该群组 | `true` |
| `channels.feishu.replyInThread` | 群聊回复是否进入飞书话题线程 | `disabled` |
| `channels.feishu.groupSessionScope` | 群聊会话隔离粒度 | `group` |
| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` |
| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` |
| `channels.feishu.streaming` | 启用流式卡片输出 | `true` |
| `channels.feishu.blockStreamingCoalesce.enabled` | 启用块级流式合并 | `true` |
| `channels.feishu.typingIndicator` | 发送“正在输入”状态 | `true` |
| `channels.feishu.resolveSenderNames` | 拉取发送者名称 | `true` |
| `channels.feishu.reactionNotifications` | 入站反应通知策略 | `own` |
| Setting | Description | Default |
| ------------------------------------------------- | -------------------------------- | ---------------- |
| `channels.feishu.enabled` | 启用/禁用渠道 | `true` |
| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` |
| `channels.feishu.connectionMode` | 事件传输模式 | `websocket` |
| `channels.feishu.defaultAccount` | 出站路由的默认账户 ID | `default` |
| `channels.feishu.verificationToken` | webhook 模式必填 | - |
| `channels.feishu.encryptKey` | webhook 模式必填 | - |
| `channels.feishu.webhookPath` | webhook 路由路径 | `/feishu/events` |
| `channels.feishu.webhookHost` | webhook 绑定主机 | `127.0.0.1` |
| `channels.feishu.webhookPort` | webhook 绑定端口 | `3000` |
| `channels.feishu.accounts.<id>.appId` | App ID | - |
| `channels.feishu.accounts.<id>.appSecret` | App Secret | - |
| `channels.feishu.accounts.<id>.domain` | 按账户覆盖 API 域名 | `feishu` |
| `channels.feishu.dmPolicy` | 私信策略 | `pairing` |
| `channels.feishu.allowFrom` | 私信 allowlist（`open_id` 列表） | - |
| `channels.feishu.groupPolicy` | 群组策略 | `open` |
| `channels.feishu.groupAllowFrom` | 群组 allowlist | - |
| `channels.feishu.groups.<chat_id>.requireMention` | 要求 @ 提及 | `true` |
| `channels.feishu.groups.<chat_id>.enabled` | 启用群组 | `true` |
| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` |
| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` |
| `channels.feishu.streaming` | 启用流式卡片输出 | `true` |
| `channels.feishu.blockStreaming` | 启用分块流式传输 | `true` |
---
## dmPolicy 策略说明
## dmPolicy 参考
| 值 | 行为 |
| ------------- | -------------------------------------------------- |
| `"pairing"` | **默认**。未知用户收到配对码，管理员批准后才能对话 |
| `"allowlist"` | 仅 `allowFrom` 列表中的用户可对话，其他静默忽略 |
| `"open"` | 允许所有人对话（需在 allowFrom 中加 `"*"`） |
| `"disabled"` | 完全禁止私聊 |
| Value | Behavior |
| ------------- | ---------------------------------------------------- |
| `"pairing"` | **默认。**未知用户会收到配对码；必须获批准后才能使用 |
| `"allowlist"` | 只有 `allowFrom` 中的用户可以聊天 |
| `"open"` | 允许所有用户（要求 `allowFrom` 中有 `"*"`） |
| `"disabled"` | 禁用私信 |
---
@ -726,17 +711,17 @@ OpenClaw 默认会在需要时发送 Markdown 卡片；如果你需要完整的
### 接收
- ✅ 文本消息
- ✅ 富文本（帖子）
- ✅ 文本
- ✅ 富文本（post）
- ✅ 图片
- ✅ 文件
- ✅ 音频
- ✅ 视频
- ✅ 表情包
- ✅ 贴纸
### 发送
- ✅ 文本消息
- ✅ 文本
- ✅ 图片
- ✅ 文件
- ✅ 音频

119
docs/zh-CN/channels/nostr.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 你希望 OpenClaw 通过 Nostr 接收私信
- 你正在设置去中心化消息
summary: 通过 NIP-04 加密消息的 Nostr 私信渠道
- 你想让 OpenClaw 通过 Nostr 接收私信
- 你正在设置去中心化消息传递
summary: 通过 NIP-04 加密消息实现的 Nostr 私信渠道
title: Nostr
x-i18n:
generated_at: "2026-02-03T07:44:13Z"
model: claude-opus-4-5
provider: pi
source_hash: 6b9fe4c74bf5e7c0f59bbaa129ec5270fd29a248551a8a9a7dde6cff8fb46111
generated_at: "2026-03-16T06:20:37Z"
model: gpt-5.4
provider: openai
source_hash: fcce57da49256971420c4bb099aebb7944f8c7e8619b17b163da685add225001
source_path: channels/nostr.md
workflow: 15
---
@ -17,21 +17,21 @@ x-i18n:
**状态：** 可选插件（默认禁用）。
Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信（DMs）。
Nostr 是一种用于社交网络的去中心化协议。此渠道使 OpenClaw 能够通过 NIP-04 接收并回复加密私信。
## 安装（按需）
### 新手引导（推荐）
- 新手引导向导（`openclaw onboard`）和 `openclaw channels add` 会列出可选的渠道插件。
- 选择 Nostr 会提示你按需安装插件。
- 设置向导（`openclaw onboard`）和 `openclaw channels add` 会列出可选渠道插件。
- 选择 Nostr 时，系统会提示你按需安装该插件。
安装默认值：
安装默认行为：
- **Dev 渠道 + git checkout 可用：** 使用本地插件路径。
- **Stable/Beta：** 从 npm 下载。
- **Dev 渠道 + 可用的 git 检出：** 使用本地插件路径。
- **稳定版 / Beta：** 从 npm 下载。
你可以随时在提示中覆盖选择。
你始终可以在提示中覆盖该选择。
### 手动安装
@ -39,24 +39,33 @@ Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够
openclaw plugins install @openclaw/nostr
```
使用本地 checkout（开发工作流）：
使用本地检出（dev 工作流）：
```bash
openclaw plugins install --link <path-to-openclaw>/extensions/nostr
```
安装或启用插件后重启 Gateway 网关。
安装或启用插件后，重启 Gateway 网关。
### 非交互式设置
```bash
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net"
```
使用 `--use-env` 可将 `NOSTR_PRIVATE_KEY` 保留在环境中，而不是将密钥存储在配置里。
## 快速设置
1. 生成 Nostr 密钥对（如需要）：
1. 生成一个 Nostr 密钥对（如有需要）：
```bash
# 使用 nak
# Using nak
nak key generate
```
2. 添加到配置：
2. 添加到配置中：
```json
{
@ -78,19 +87,19 @@ export NOSTR_PRIVATE_KEY="nsec1..."
## 配置参考
| 键 | 类型 | 默认值 | 描述 |
| 键 | 类型 | 默认值 | 说明 |
| ------------ | -------- | ------------------------------------------- | --------------------------- |
| `privateKey` | string | 必填 | `nsec` 或十六进制格式的私钥 |
| `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | 中继 URL（WebSocket） |
| `dmPolicy` | string | `pairing` | 私信访问策略 |
| `allowFrom` | string[] | `[]` | 允许的发送者公钥 |
| `enabled` | boolean | `true` | 启用/禁用渠道 |
| `allowFrom` | string[] | `[]` | 允许的发送方公钥 |
| `enabled` | boolean | `true` | 启用 / 禁用渠道 |
| `name` | string | - | 显示名称 |
| `profile` | object | - | NIP-01 个人资料元数据 |
| `profile` | object | - | NIP-01 资料元数据 |
## 个人资料元数据
## 资料元数据
个人资料数据作为 NIP-01 `kind:0` 事件发布。你可以从控制界面（Channels -> Nostr -> Profile）管理它，或直接在配置中设置。
资料数据会作为 NIP-01 `kind:0` 事件发布。你可以在控制 UI 中管理它（Channels -> Nostr -> Profile），也可以直接在配置中设置。
示例：
@ -114,19 +123,19 @@ export NOSTR_PRIVATE_KEY="nsec1..."
}
```
注意事项：
注意：
- 个人资料 URL 必须使用 `https://`。
- 从中继导入会合并字段并保留本地覆盖。
- 资料 URL 必须使用 `https://`。
- 从中继导入时会合并字段，并保留本地覆盖项。
## 访问控制
### 私信策略
- **pairing**（默认）：未知发送者会收到配对码。
- **pairing**（默认）：未知发送方会收到一个配对码。
- **allowlist**：只有 `allowFrom` 中的公钥可以发送私信。
- **open**：公开接收私信（需要 `allowFrom: ["*"]`）。
- **disabled**：忽略接收的私信。
- **open**：公开接收入站私信（要求 `allowFrom: ["*"]`）。
- **disabled**：忽略入站私信。
### 允许列表示例
@ -166,26 +175,26 @@ export NOSTR_PRIVATE_KEY="nsec1..."
提示：
- 使用 2-3 个中继以实现冗余。
- 使用 2 到 3 个中继以实现冗余。
- 避免使用过多中继（延迟、重复）。
- 付费中继可以提高可靠性。
- 本地中继适合测试（`ws://localhost:7777`）。
- 本地中继也适合测试（`ws://localhost:7777`）。
## 协议支持
| NIP | 状态 | 描述 |
| ------ | ------ | ----------------------------- |
| NIP-01 | 已支持 | 基本事件格式 + 个人资料元数据 |
| NIP-04 | 已支持 | 加密私信（`kind:4`） |
| NIP-17 | 计划中 | 礼物包装私信 |
| NIP-44 | 计划中 | 版本化加密 |
| NIP | 状态 | 说明 |
| ------ | ------ | ------------------------- |
| NIP-01 | 已支持 | 基础事件格式 + 资料元数据 |
| NIP-04 | 已支持 | 加密私信（`kind:4`） |
| NIP-17 | 计划中 | Gift-wrapped 私信 |
| NIP-44 | 计划中 | 版本化加密 |
## 测试
### 本地中继
```bash
# 启动 strfry
# Start strfry
docker run -p 7777:7777 ghcr.io/hoytech/strfry
```
@ -203,38 +212,38 @@ docker run -p 7777:7777 ghcr.io/hoytech/strfry
### 手动测试
1. 从日志中记下机器人公钥（npub）。
2. 打开 Nostr 客户端（Damus、Amethyst 等）。
3. 向机器人公钥发送私信。
4. 验证响应。
2. 打开一个 Nostr 客户端（Damus、Amethyst 等）。
3. 向该机器人公钥发送私信。
4. 验证回复。
## 故障排除
### 未收到消息
### 未接收到消息
- 验证私钥是否有效。
- 确保中继 URL 可访问并使用 `wss://`（本地使用 `ws://`）。
- 验证私钥有效。
- 确保中继 URL 可访问，并使用 `wss://`（本地则使用 `ws://`）。
- 确认 `enabled` 不是 `false`。
- 检查 Gateway 网关日志中的中继连接错误。
### 未发送响应
### 未发送回复
- 检查中继是否接受写入。
- 验证出站连接。
- 验证出站连接性。
- 注意中继速率限制。
### 重复响应
### 重复回复
- 使用多个中继时属于正常现象。
- 消息按事件 ID 去重；只有首次投递会触发响应。
- 使用多个中继时这是预期行为。
- 消息会按事件 ID 去重；只有首次投递会触发回复。
## 安全
## 安全性
- 切勿提交私钥。
- 使用环境变量存储密钥。
- 生产环境机器人考虑使用 `allowlist`。
- 对密钥使用环境变量。
- 对生产机器人考虑使用 `allowlist`。
## 限制（MVP）
- 仅支持私信（不支持群聊）。
- 不支持媒体附件。
- 仅支持 NIP-04（计划支持 NIP-17 礼物包装）。
- 仅支持 NIP-04（计划支持 NIP-17 gift-wrap）。

138
docs/zh-CN/channels/synology-chat.md Normal file
View File

@ -0,0 +1,138 @@
---
read_when:
- 设置 OpenClaw 与 Synology Chat
- 调试 Synology Chat webhook 路由
summary: Synology Chat webhook 设置与 OpenClaw 配置
title: Synology Chat
x-i18n:
generated_at: "2026-03-16T06:20:51Z"
model: gpt-5.4
provider: openai
source_hash: 7d77598ea759f89873a1edf0a3a7e7fedc1e4a7067709aaca6b999056a89eb1a
source_path: channels/synology-chat.md
workflow: 15
---
# Synology Chat（插件）
状态：通过插件支持，作为使用 Synology Chat webhook 的私信渠道。
该插件接受来自 Synology Chat 出站 webhook 的入站消息，并通过 Synology Chat 入站 webhook 发送回复。
## 需要插件
Synology Chat 基于插件，不属于默认的核心渠道安装内容。
从本地检出安装：
```bash
openclaw plugins install ./extensions/synology-chat
```
详情：[插件](/tools/plugin)
## 快速设置
1. 安装并启用 Synology Chat 插件。
- `openclaw onboard` 现在会在与 `openclaw channels add` 相同的渠道设置列表中显示 Synology Chat。
- 非交互式设置：`openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
2. 在 Synology Chat 集成中：
- 创建一个入站 webhook 并复制其 URL。
- 使用你的 secret token 创建一个出站 webhook。
3. 将出站 webhook URL 指向你的 OpenClaw Gateway 网关：
- 默认是 `https://gateway-host/webhook/synology`。
- 或者使用你自定义的 `channels.synology-chat.webhookPath`。
4. 在 OpenClaw 中完成设置。
- 引导式：`openclaw onboard`
- 直接设置：`openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
5. 重启 Gateway 网关，并向 Synology Chat 机器人发送一条私信。
最小配置：
```json5
{
channels: {
"synology-chat": {
enabled: true,
token: "synology-outgoing-token",
incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...",
webhookPath: "/webhook/synology",
dmPolicy: "allowlist",
allowedUserIds: ["123456"],
rateLimitPerMinute: 30,
allowInsecureSsl: false,
},
},
}
```
## 环境变量
对于默认账户，你可以使用环境变量：
- `SYNOLOGY_CHAT_TOKEN`
- `SYNOLOGY_CHAT_INCOMING_URL`
- `SYNOLOGY_NAS_HOST`
- `SYNOLOGY_ALLOWED_USER_IDS`（逗号分隔）
- `SYNOLOGY_RATE_LIMIT`
- `OPENCLAW_BOT_NAME`
配置值会覆盖环境变量。
## 私信策略与访问控制
- 推荐的默认值是 `dmPolicy: "allowlist"`。
- `allowedUserIds` 接受 Synology 用户 ID 列表（或逗号分隔字符串）。
- 在 `allowlist` 模式下，空的 `allowedUserIds` 列表会被视为配置错误，webhook 路由将不会启动（如需允许所有人，请使用 `dmPolicy: "open"`）。
- `dmPolicy: "open"` 允许任何发送方。
- `dmPolicy: "disabled"` 会阻止私信。
- 配对批准可配合以下命令使用：
- `openclaw pairing list synology-chat`
- `openclaw pairing approve synology-chat <CODE>`
## 出站投递
使用数字形式的 Synology Chat 用户 ID 作为目标。
示例：
```bash
openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw"
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
```
支持通过基于 URL 的文件投递发送媒体。
## 多账户
支持在 `channels.synology-chat.accounts` 下配置多个 Synology Chat 账户。
每个账户都可以覆盖 token、入站 URL、webhook 路径、私信策略和限制。
```json5
{
channels: {
"synology-chat": {
enabled: true,
accounts: {
default: {
token: "token-a",
incomingUrl: "https://nas-a.example.com/...token=...",
},
alerts: {
token: "token-b",
incomingUrl: "https://nas-b.example.com/...token=...",
webhookPath: "/webhook/synology-alerts",
dmPolicy: "allowlist",
allowedUserIds: ["987654"],
},
},
},
},
}
```
## 安全说明
- 妥善保管 `token`，如果泄露请轮换。
- 除非你明确可信任本地 NAS 的自签名证书，否则请保持 `allowInsecureSsl: false`。
- 入站 webhook 请求会按 token 验证，并按发送方进行速率限制。
- 生产环境优先使用 `dmPolicy: "allowlist"`。

417
docs/zh-CN/cli/index.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 添加或修改 CLI 命令或选项
- 为新命令界面编写文档
summary: OpenClaw `openclaw` 命令、子命令和选项的 CLI 参考
- 添加或修改 CLI 命令或选项时
- 为新的命令界面编写文档时
summary: "`openclaw` 命令、子命令和选项的 OpenClaw CLI 参考"
title: CLI 参考
x-i18n:
generated_at: "2026-02-03T07:47:54Z"
model: claude-opus-4-5
provider: pi
source_hash: a73923763d7b89d4b183f569d543927ffbfd1f3e02f9e66639913f6daf226850
generated_at: "2026-03-16T06:22:35Z"
model: gpt-5.4
provider: openai
source_hash: a2bca34fca64558a8d91fc640ad3880e79677e81d0f605083edc6cbe86bfba53
source_path: cli/index.md
workflow: 15
---
@ -23,8 +23,10 @@ x-i18n:
- [`onboard`](/cli/onboard)
- [`configure`](/cli/configure)
- [`config`](/cli/config)
- [`completion`](/cli/completion)
- [`doctor`](/cli/doctor)
- [`dashboard`](/cli/dashboard)
- [`backup`](/cli/backup)
- [`reset`](/cli/reset)
- [`uninstall`](/cli/uninstall)
- [`update`](/cli/update)
@ -40,6 +42,7 @@ x-i18n:
- [`system`](/cli/system)
- [`models`](/cli/models)
- [`memory`](/cli/memory)
- [`directory`](/cli/directory)
- [`nodes`](/cli/nodes)
- [`devices`](/cli/devices)
- [`node`](/cli/node)
@ -53,42 +56,46 @@ x-i18n:
- [`hooks`](/cli/hooks)
- [`webhooks`](/cli/webhooks)
- [`pairing`](/cli/pairing)
- [`qr`](/cli/qr)
- [`plugins`](/cli/plugins)（插件命令）
- [`channels`](/cli/channels)
- [`security`](/cli/security)
- [`secrets`](/cli/secrets)
- [`skills`](/cli/skills)
- [`daemon`](/cli/daemon)（Gateway 网关服务命令的旧别名）
- [`clawbot`](/cli/clawbot)（旧别名命名空间）
- [`voicecall`](/cli/voicecall)（插件；如已安装）
## 全局标志
- `--dev`：将状态隔离到 `~/.openclaw-dev` 下并调整默认端口。
- `--dev`：将状态隔离到 `~/.openclaw-dev` 下，并变更默认端口。
- `--profile <name>`：将状态隔离到 `~/.openclaw-<name>` 下。
- `--no-color`：禁用 ANSI 颜色。
- `--update`：`openclaw update` 的简写（仅限源码安装）。
- `-V`、`--version`、`-v`：打印版本并退出。
- `--update`：`openclaw update` 的简写（仅适用于源码安装）。
- `-V`, `--version`, `-v`：打印版本并退出。
## 输出样式
- ANSI 颜色和进度指示器仅在 TTY 会话中渲染。
- OSC-8 超链接在支持的终端中渲染为可点击链接；否则回退到纯 URL。
- `--json`（以及支持的地方使用 `--plain`）禁用样式以获得干净输出。
- `--no-color` 禁用 ANSI 样式；也支持 `NO_COLOR=1`。
- 长时间运行的命令显示进度指示器（支持时使用 OSC 9;4）。
- OSC-8 超链接会在受支持的终端中显示为可点击链接；否则会回退为纯 URL。
- `--json`（以及在支持处的 `--plain`）会禁用样式，以获得干净输出。
- `--no-color` 会禁用 ANSI 样式；同时也支持 `NO_COLOR=1`。
- 长时间运行的命令会显示进度指示器（支持时使用 OSC 9;4）。
## 颜色调色板
## 调色板
OpenClaw 在 CLI 输出中使用龙虾调色板。
OpenClaw 在 CLI 输出中使用龙虾色调调色板。
- `accent`（#FF5A2D）：标题、标签、主要高亮。
- `accentBright`（#FF7A3D）：命令名称、强调。
- `accentDim`（#D14A22）：次要高亮文本。
- `info`（#FF8A5B）：信息性值。
- `success`（#2FBF71）：成功状态。
- `warn`（#FFB020）：警告、回退、注意。
- `error`（#E23D2D）：错误、失败。
- `muted`（#8B7F77）：弱化、元数据。
- `accent` (#FF5A2D)：标题、标签、主要高亮。
- `accentBright` (#FF7A3D)：命令名称、强调。
- `accentDim` (#D14A22)：次级高亮文本。
- `info` (#FF8A5B)：信息性值。
- `success` (#2FBF71)：成功状态。
- `warn` (#FFB020)：警告、回退、注意事项。
- `error` (#E23D2D)：错误、失败。
- `muted` (#8B7F77)：弱化显示、元数据。
调色板权威来源：`src/terminal/palette.ts`（又名"lobster seam"）。
调色板唯一来源：`src/terminal/palette.ts`（也称为 “lobster seam”）。
## 命令树
@ -101,9 +108,17 @@ openclaw [--dev] [--profile <name>] <command>
get
set
unset
completion
doctor
dashboard
backup
create
verify
security
audit
secrets
reload
migrate
reset
uninstall
update
@ -115,6 +130,7 @@ openclaw [--dev] [--profile <name>] <command>
remove
login
logout
directory
skills
list
info
@ -152,6 +168,13 @@ openclaw [--dev] [--profile <name>] <command>
stop
restart
run
daemon
status
install
uninstall
start
stop
restart
logs
system
event
@ -238,49 +261,59 @@ openclaw [--dev] [--profile <name>] <command>
pairing
list
approve
qr
clawbot
qr
docs
dns
setup
tui
```
注意：插件可以添加额外的顶级命令（例如 `openclaw voicecall`）。
注意：插件可以添加额外的顶层命令（例如 `openclaw voicecall`）。
## 安全
- `openclaw security audit` — 审计配置 + 本地状态中常见的安全隐患。
- `openclaw security audit` — 审计配置 + 本地状态中常见的安全陷阱。
- `openclaw security audit --deep` — 尽力进行实时 Gateway 网关探测。
- `openclaw security audit --fix` — 收紧安全默认值并 chmod 状态/配置。
- `openclaw security audit --fix` — 收紧安全默认值并对状态 / 配置执行 chmod。
## 密钥
- `openclaw secrets reload` — 重新解析引用，并以原子方式替换运行时快照。
- `openclaw secrets audit` — 扫描明文残留、未解析引用和优先级漂移。
- `openclaw secrets configure` — 用于提供商设置 + SecretRef 映射 + 预检 / 应用的交互式助手。
- `openclaw secrets apply --from <plan.json>` — 应用先前生成的计划（支持 `--dry-run`）。
## 插件
管理扩展及其配置：
- `openclaw plugins list` — 发现插件（使用 `--json` 获取机器可读输出）。
- `openclaw plugins list` — 发现插件（机器输出请使用 `--json`）。
- `openclaw plugins info <id>` — 显示插件详情。
- `openclaw plugins install <path|.tgz|npm-spec>` — 安装插件（或将插件路径添加到 `plugins.load.paths`）。
- `openclaw plugins enable <id>` / `disable <id>` — 切换 `plugins.entries.<id>.enabled`。
- `openclaw plugins doctor` — 报告插件加载错误。
大多数插件更改需要重启 Gateway 网关。参见 [/plugin](/tools/plugin)。
大多数插件更改都需要重启 gateway。参见 [/plugin](/tools/plugin)。
## 记忆
## 内存
对 `MEMORY.md` + `memory/*.md` 进行向量搜索：
对 `MEMORY.md` + `memory/*.md` 执行向量搜索：
- `openclaw memory status` — 显示索引统计。
- `openclaw memory index` — 重新索引记忆文件。
- `openclaw memory search "<query>"` — 对记忆进行语义搜索。
- `openclaw memory status` — 显示索引统计信息。
- `openclaw memory index` — 重新索引内存文件。
- `openclaw memory search "<query>"`（或 `--query "<query>"`）— 对内存执行语义搜索。
## 聊天斜杠命令
聊天消息支持 `/...` 命令（文本和原生）。参见 [/tools/slash-commands](/tools/slash-commands)。
亮点：
重点：
- `/status` 用于快速诊断。
- `/config` 用于持久化配置更改。
- `/debug` 用于仅运行时的配置覆盖（内存中，不写入磁盘；需要 `commands.debug: true`）。
- `/debug` 用于仅运行时的配置覆盖（内存中，不写磁盘；要求 `commands.debug: true`）。
## 设置 + 新手引导
@ -291,32 +324,35 @@ openclaw [--dev] [--profile <name>] <command>
选项：
- `--workspace <dir>`：智能体工作区路径（默认 `~/.openclaw/workspace`）。
- `--wizard`：运行新手引导向导。
- `--wizard`：运行设置向导。
- `--non-interactive`：无提示运行向导。
- `--mode <local|remote>`：向导模式。
- `--remote-url <url>`：远程 Gateway 网关 URL。
- `--remote-token <token>`：远程 Gateway 网关令牌。
- `--remote-token <token>`：远程 Gateway 网关 token。
当存在任何向导标志（`--non-interactive`、`--mode`、`--remote-url`、`--remote-token`）时，向导自动运行。
只要存在任意向导标志（`--non-interactive`, `--mode`, `--remote-url`, `--remote-token`），就会自动运行向导。
### `onboard`
交互式向导，用于设置 Gateway 网关、工作区和 Skills。
用于设置 gateway、工作区和 Skills 的交互式向导。
选项：
- `--workspace <dir>`
- `--reset`（在向导之前重置配置 + 凭证 + 会话 + 工作区）
- `--reset`（在运行向导前重置配置 + 凭据 + 会话）
- `--reset-scope <config|config+creds+sessions|full>`（默认 `config+creds+sessions`；使用 `full` 还会删除工作区）
- `--non-interactive`
- `--mode <local|remote>`
- `--flow <quickstart|advanced|manual>`（manual 是 advanced 的别名）
- `--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip>`
- `--token-provider <id>`（非交互式；与 `--auth-choice token` 配合使用）
- `--token <token>`（非交互式；与 `--auth-choice token` 配合使用）
- `--flow <quickstart|advanced|manual>`（`manual` 是 `advanced` 的别名）
- `--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ollama|ai-gateway-api-key|moonshot-api-key|moonshot-api-key-cn|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|mistral-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|opencode-go|custom-api-key|skip>`
- `--token-provider <id>`（非交互式；与 `--auth-choice token` 一起使用）
- `--token <token>`（非交互式；与 `--auth-choice token` 一起使用）
- `--token-profile-id <id>`（非交互式；默认：`<provider>:manual`）
- `--token-expires-in <duration>`（非交互式；例如 `365d`、`12h`）
- `--secret-input-mode <plaintext|ref>`（默认 `plaintext`；使用 `ref` 可存储提供商默认环境引用，而非明文密钥）
- `--anthropic-api-key <key>`
- `--openai-api-key <key>`
- `--mistral-api-key <key>`
- `--openrouter-api-key <key>`
- `--ai-gateway-api-key <key>`
- `--moonshot-api-key <key>`
@ -325,10 +361,17 @@ openclaw [--dev] [--profile <name>] <command>
- `--zai-api-key <key>`
- `--minimax-api-key <key>`
- `--opencode-zen-api-key <key>`
- `--opencode-go-api-key <key>`
- `--custom-base-url <url>`（非交互式；与 `--auth-choice custom-api-key` 或 `--auth-choice ollama` 一起使用）
- `--custom-model-id <id>`（非交互式；与 `--auth-choice custom-api-key` 或 `--auth-choice ollama` 一起使用）
- `--custom-api-key <key>`（非交互式；可选；与 `--auth-choice custom-api-key` 一起使用；省略时回退到 `CUSTOM_API_KEY`）
- `--custom-provider-id <id>`（非交互式；可选自定义提供商 id）
- `--custom-compatibility <openai|anthropic>`（非交互式；可选；默认 `openai`）
- `--gateway-port <port>`
- `--gateway-bind <loopback|lan|tailnet|auto|custom>`
- `--gateway-auth <token|password>`
- `--gateway-token <token>`
- `--gateway-token-ref-env <name>`（非交互式；将 `gateway.auth.token` 存储为环境 SecretRef；要求该环境变量已设置；不能与 `--gateway-token` 一起使用）
- `--gateway-password <password>`
- `--remote-url <url>`
- `--remote-token <token>`
@ -341,35 +384,39 @@ openclaw [--dev] [--profile <name>] <command>
- `--skip-skills`
- `--skip-health`
- `--skip-ui`
- `--node-manager <npm|pnpm|bun>`（推荐 pnpm；不建议将 bun 用于 Gateway 网关运行时）
- `--node-manager <npm|pnpm|bun>`（推荐 pnpm；不推荐将 bun 用作 Gateway 网关运行时）
- `--json`
### `configure`
交互式配置向导（模型、渠道、Skills、Gateway 网关）。
交互式配置向导（模型、渠道、Skills、gateway）。
### `config`
非交互式配置辅助工具（get/set/unset）。不带子命令运行 `openclaw config` 会启动向导。
非交互式配置助手（get/set/unset/file/validate）。直接运行 `openclaw config` 而不带
子命令会启动向导。
子命令：
- `config get <path>`：打印配置值（点/括号路径）。
- `config set <path> <value>`：设置值（JSON5 或原始字符串）。
- `config unset <path>`：删除值。
- `config get <path>`：打印一个配置值（点 / 方括号路径）。
- `config set <path> <value>`：设置一个值（JSON5 或原始字符串）。
- `config unset <path>`：移除一个值。
- `config file`：打印当前活动配置文件路径。
- `config validate`：根据 schema 验证当前配置，而不启动 gateway。
- `config validate --json`：输出机器可读的 JSON。
### `doctor`
健康检查 + 快速修复（配置 + Gateway 网关 + 旧版服务）。
健康检查 + 快速修复（配置 + gateway + 旧版服务）。
选项：
- `--no-workspace-suggestions`：禁用工作区记忆提示。
- `--yes`：无提示接受默认值（无头模式）。
- `--no-workspace-suggestions`：禁用工作区内存提示。
- `--yes`：接受默认值而不提示（无头）。
- `--non-interactive`：跳过提示；仅应用安全迁移。
- `--deep`：扫描系统服务以查找额外的 Gateway 网关安装。
- `--deep`：扫描系统服务以查找额外的 gateway 安装。
## 渠道辅助工具
## 渠道助手
### `channels`
@ -378,19 +425,21 @@ openclaw [--dev] [--profile <name>] <command>
子命令：
- `channels list`：显示已配置的渠道和认证配置文件。
- `channels status`：检查 Gateway 网关可达性和渠道健康状况（`--probe` 运行额外检查；使用 `openclaw health` 或 `openclaw status --deep` 进行 Gateway 网关健康探测）。
- 提示：`channels status` 在检测到常见配置错误时会打印带有建议修复的警告（然后指向 `openclaw doctor`）。
- `channels logs`：显示 Gateway 网关日志文件中最近的渠道日志。
- `channels add`：不传标志时使用向导式设置；标志切换到非交互模式。
- `channels remove`：默认禁用；传 `--delete` 可无提示删除配置条目。
- `channels login`：交互式渠道登录（仅限 WhatsApp Web）。
- `channels logout`：登出渠道会话（如支持）。
- `channels status`：检查 gateway 可达性和渠道健康状态（`--probe` 会运行额外检查；gateway 健康探测请使用 `openclaw health` 或 `openclaw status --deep`）。
- 提示：如果能够检测到常见配置错误，`channels status` 会打印带建议修复方式的警告（随后指向 `openclaw doctor`）。
- `channels logs`：显示 gateway 日志文件中的最近渠道日志。
- `channels add`：未传入任何标志时为向导式设置；传入标志后切换为非交互模式。
- 当向仍使用单账户顶层配置的渠道添加非默认账户时，OpenClaw 会先将账户作用域值移动到 `channels.<channel>.accounts.default`，再写入新账户。
- 非交互式 `channels add` 不会自动创建 / 升级绑定；仅渠道绑定会继续匹配默认账户。
- `channels remove`：默认执行禁用；传入 `--delete` 可在无提示下删除配置项。
- `channels login`：交互式渠道登录（仅 WhatsApp Web）。
- `channels logout`：登出某个渠道会话（如支持）。
通用选项：
- `--channel <name>`：`whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams`
- `--account <id>`：渠道账户 id（默认 `default`）
- `--name <label>`：账户的显示名称
- `--name <label>`：账户显示名称
`channels login` 选项：
@ -405,8 +454,8 @@ openclaw [--dev] [--profile <name>] <command>
`channels list` 选项：
- `--no-usage`：跳过模型提供商用量/配额快照（仅限 OAuth/API 支持的）。
- `--json`：输出 JSON（除非设置 `--no-usage`，否则包含用量）。
- `--no-usage`：跳过模型提供商用量 / 配额快照（仅 OAuth / API 支持）。
- `--json`：输出 JSON（除非设置了 `--no-usage`，否则包含用量）。
`channels logs` 选项：
@ -414,7 +463,7 @@ openclaw [--dev] [--profile <name>] <command>
- `--lines <n>`（默认 `200`）
- `--json`
更多详情：[/concepts/oauth](/concepts/oauth)
更多细节：[/concepts/oauth](/concepts/oauth)
示例：
@ -428,19 +477,19 @@ openclaw status --deep
### `skills`
列出和检查可用的 Skills 及就绪信息。
列出并检查可用 Skills，以及就绪信息。
子命令：
- `skills list`：列出 Skills（无子命令时的默认行为）。
- `skills list`：列出 Skills（未指定子命令时的默认行为）。
- `skills info <name>`：显示单个 Skill 的详情。
- `skills check`：就绪与缺失需求的摘要。
- `skills check`：汇总已就绪与缺失的要求。
选项：
- `--eligible`：仅显示就绪的 Skills。
- `--eligible`：仅显示已就绪的 Skills。
- `--json`：输出 JSON（无样式）。
- `-v`、`--verbose`：包含缺失需求详情。
- `-v`, `--verbose`：包含缺失要求的详细信息。
提示：使用 `npx clawhub` 搜索、安装和同步 Skills。
@ -450,31 +499,46 @@ openclaw status --deep
子命令：
- `pairing list <channel> [--json]`
- `pairing approve <channel> <code> [--notify]`
- `pairing list [channel] [--channel <channel>] [--account <id>] [--json]`
- `pairing approve <channel> <code> [--account <id>] [--notify]`
- `pairing approve --channel <channel> [--account <id>] <code> [--notify]`
### `webhooks gmail`
### `devices`
Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/automation/gmail-pubsub)。
管理 gateway 设备配对条目和按角色划分的设备 token。
子命令：
- `webhooks gmail setup`（需要 `--account <email>`；支持 `--project`、`--topic`、`--subscription`、`--label`、`--hook-url`、`--hook-token`、`--push-token`、`--bind`、`--port`、`--path`、`--include-body`、`--max-bytes`、`--renew-minutes`、`--tailscale`、`--tailscale-path`、`--tailscale-target`、`--push-endpoint`、`--json`）
- `webhooks gmail run`（相同标志的运行时覆盖）
- `devices list [--json]`
- `devices approve [requestId] [--latest]`
- `devices reject <requestId>`
- `devices remove <deviceId>`
- `devices clear --yes [--pending]`
- `devices rotate --device <id> --role <role> [--scope <scope...>]`
- `devices revoke --device <id> --role <role>`
### `webhooks gmail`
Gmail Pub/Sub hook 设置 + 运行器。参见 [/automation/gmail-pubsub](/automation/gmail-pubsub)。
子命令：
- `webhooks gmail setup`（要求 `--account <email>`；支持 `--project`, `--topic`, `--subscription`, `--label`, `--hook-url`, `--hook-token`, `--push-token`, `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes`, `--tailscale`, `--tailscale-path`, `--tailscale-target`, `--push-endpoint`, `--json`）
- `webhooks gmail run`（对相同标志进行运行时覆盖）
### `dns setup`
广域发现 DNS 辅助工具（CoreDNS + Tailscale）。参见 [/gateway/discovery](/gateway/discovery)。
广域设备发现 DNS 助手（CoreDNS + Tailscale）。参见 [/gateway/discovery](/gateway/discovery)。
选项：
- `--apply`：安装/更新 CoreDNS 配置（需要 sudo；仅限 macOS）。
- `--apply`：安装 / 更新 CoreDNS 配置（需要 sudo；仅 macOS）。
## 消息 + 智能体
### `message`
统一的出站消息 + 渠道操作。
统一的出站消息发送 + 渠道操作。
参见：[/cli/message](/cli/message)
@ -497,17 +561,17 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
### `agent`
通过 Gateway 网关运行一个智能体回合（或使用 `--local` 嵌入式运行）。
通过 Gateway 网关（或 `--local` 嵌入模式）运行一次智能体轮次。
必需：
必需项：
- `--message <text>`
选项：
- `--to <dest>`（用于会话键和可选发送）
- `--to <dest>`（用于会话键以及可选投递）
- `--session-id <id>`
- `--thinking <off|minimal|low|medium|high|xhigh>`（仅限 GPT-5.2 + Codex 模型）
- `--thinking <off|minimal|low|medium|high|xhigh>`（仅适用于 GPT-5.2 + Codex 模型）
- `--verbose <on|full|off>`
- `--channel <whatsapp|telegram|discord|slack|mattermost|signal|imessage|msteams>`
- `--local`
@ -530,7 +594,7 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
#### `agents add [name]`
添加新的隔离智能体。除非传入标志（或 `--non-interactive`），否则运行引导向导；非交互模式下 `--workspace` 是必需的。
添加一个新的隔离智能体。除非传入标志（或 `--non-interactive`），否则会运行引导式向导；在非交互模式下必须提供 `--workspace`。
选项：
@ -541,11 +605,41 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
- `--non-interactive`
- `--json`
绑定规范使用 `channel[:accountId]`。对于 WhatsApp，省略 `accountId` 时使用默认账户 id。
绑定规范使用 `channel[:accountId]`。省略 `accountId` 时，OpenClaw 可能通过渠道默认值 / 插件 hook 解析账户作用域；否则这就是不带显式账户作用域的渠道绑定。
#### `agents bindings`
列出路由绑定。
选项：
- `--agent <id>`
- `--json`
#### `agents bind`
为智能体添加路由绑定。
选项：
- `--agent <id>`
- `--bind <channel[:accountId]>`（可重复）
- `--json`
#### `agents unbind`
移除智能体的路由绑定。
选项：
- `--agent <id>`
- `--bind <channel[:accountId]>`（可重复）
- `--all`
- `--json`
#### `agents delete <id>`
删除智能体并清理其工作区 + 状态。
删除一个智能体并清理其工作区 + 状态。
选项：
@ -554,44 +648,44 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
### `acp`
运行连接 IDE 到 Gateway 网关的 ACP 桥接。
运行将 IDE 连接到 Gateway 网关的 ACP 桥接器。
完整选项和示例参见 [`acp`](/cli/acp)。
完整选项和示例请参见 [`acp`](/cli/acp)。
### `status`
显示关联会话健康状况和最近的收件人。
显示已链接会话的健康状态和最近收件人。
选项：
- `--json`
- `--all`（完整诊断；只读，可粘贴）
- `--all`（完整诊断；只读、可粘贴）
- `--deep`（探测渠道）
- `--usage`（显示模型提供商用量/配额）
- `--usage`（显示模型提供商用量 / 配额）
- `--timeout <ms>`
- `--verbose`
- `--debug`（`--verbose` 的别名）
说明：
- 概览包含 Gateway 网关 + 节点主机服务状态（如可用）。
- 概览中会在可用时包含 Gateway 网关 + node host 服务状态。
### 用量跟踪
当 OAuth/API 凭证可用时，OpenClaw 可以显示提供商用量/配额。
在 OAuth / API 凭据可用时，OpenClaw 可以显示提供商用量 / 配额。
显示位置：
展示位置：
- `/status`（可用时添加简短的提供商用量行）
- `/status`（可用时添加一行简短的提供商用量信息）
- `openclaw status --usage`（打印完整的提供商明细）
- macOS 菜单栏（上下文下的用量部分）
- macOS 菜单栏（Context 下的 Usage 部分）
说明：
- 数据直接来自提供商用量端点（非估算）。
- 提供商：Anthropic、GitHub Copilot、OpenAI Codex OAuth，以及通过捆绑 `google` 插件提供的 Gemini CLI 和已配置的 Antigravity。
- 如果没有匹配的凭证，用量会被隐藏。
- 详情：参见[用量跟踪](/concepts/usage-tracking)。
- 数据直接来自提供商用量端点（不是估算值）。
- 提供商：Anthropic、GitHub Copilot、OpenAI Codex OAuth，以及打包的 `google` 插件所提供的 Gemini CLI 和在已配置情况下的 Antigravity。
- 如果不存在匹配的凭据，则不会显示用量。
- 详情：参见 [用量跟踪](/concepts/usage-tracking)。
### `health`
@ -605,7 +699,7 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
### `sessions`
列出存储的对话会话。
列出已存储的对话会话。
选项：
@ -614,11 +708,11 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
- `--store <path>`
- `--active <minutes>`
## 重置/卸载
## 重置 / 卸载
### `reset`
重置本地配置/状态（保留 CLI 安装）。
重置本地配置 / 状态（保留已安装的 CLI）。
选项：
@ -629,11 +723,11 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
说明：
- `--non-interactive` 需要 `--scope` 和 `--yes`。
- `--non-interactive` 要求同时提供 `--scope` 和 `--yes`。
### `uninstall`
卸载 Gateway 网关服务 + 本地数据（CLI 保留）。
卸载 gateway 服务 + 本地数据（CLI 保留）。
选项：
@ -648,7 +742,7 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
说明：
- `--non-interactive` 需要 `--yes` 和明确的范围（或 `--all`）。
- `--non-interactive` 要求 `--yes` 和显式作用域（或 `--all`）。
## Gateway 网关
@ -663,12 +757,13 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
- `--token <token>`
- `--auth <token|password>`
- `--password <password>`
- `--password-file <path>`
- `--tailscale <off|serve|funnel>`
- `--tailscale-reset-on-exit`
- `--allow-unconfigured`
- `--dev`
- `--reset`（重置 dev 配置 + 凭证 + 会话 + 工作区）
- `--force`（终止端口上的现有监听器）
- `--reset`（重置 dev 配置 + 凭据 + 会话 + 工作区）
- `--force`（杀掉端口上的现有监听器）
- `--verbose`
- `--claude-cli-logs`
- `--ws-log <auto|full|compact>`
@ -683,7 +778,7 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
子命令：
- `gateway status`（默认探测 Gateway 网关 RPC）
- `gateway install`（服务安装）
- `gateway install`（安装服务）
- `gateway uninstall`
- `gateway start`
- `gateway stop`
@ -691,12 +786,14 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
说明：
- `gateway status` 默认使用服务解析的端口/配置探测 Gateway 网关 RPC（使用 `--url/--token/--password` 覆盖）。
- `gateway status` 支持 `--no-probe`、`--deep` 和 `--json` 用于脚本化。
- `gateway status` 在检测到旧版或额外的 Gateway 网关服务时也会显示（`--deep` 添加系统级扫描）。配置文件命名的 OpenClaw 服务被视为一等公民，不会被标记为"额外"。
- `gateway status` 打印 CLI 使用的配置路径与服务可能使用的配置（服务环境），以及解析的探测目标 URL。
- `gateway install|uninstall|start|stop|restart` 支持 `--json` 用于脚本化（默认输出保持人类友好）。
- `gateway install` 默认使用 Node 运行时；**不建议**使用 bun（WhatsApp/Telegram bug）。
- `gateway status` 默认使用服务解析出的端口 / 配置来探测 Gateway 网关 RPC（可用 `--url/--token/--password` 覆盖）。
- `gateway status` 支持 `--no-probe`、`--deep`、`--require-rpc` 和 `--json`，便于脚本化。
- `gateway status` 还能在检测到时显示旧版或额外的 gateway 服务（`--deep` 会增加系统级扫描）。带 profile 名称的 OpenClaw 服务会被视为一等公民，不会标记为“额外”。
- `gateway status` 会打印 CLI 使用的是哪个配置路径、服务可能使用的是哪个配置（服务环境），以及解析出的探测目标 URL。
- 如果 gateway 认证 SecretRef 在当前命令路径中未解析，`gateway status --json` 仅会在探测连接 / 认证失败时报告 `rpc.authWarning`（探测成功时会抑制警告）。
- 在 Linux systemd 安装中，状态 token 漂移检查同时包括 `Environment=` 和 `EnvironmentFile=` 单元来源。
- `gateway install|uninstall|start|stop|restart` 支持 `--json`，便于脚本化（默认输出仍然更适合人类阅读）。
- `gateway install` 默认使用 Node 运行时；**不推荐** bun（存在 WhatsApp / Telegram bug）。
- `gateway install` 选项：`--port`、`--runtime`、`--token`、`--force`、`--json`。
### `logs`
@ -705,8 +802,8 @@ Gmail Pub/Sub 钩子设置 + 运行器。参见 [/automation/gmail-pubsub](/auto
说明：
- TTY 会话渲染彩色、结构化视图；非 TTY 回退到纯文本。
- `--json` 输出行分隔的 JSON（每行一个日志事件）。
- TTY 会话会渲染彩色的结构化视图；非 TTY 会回退为纯文本。
- `--json` 会输出逐行 JSON（每行一个日志事件）。
示例：
@ -720,7 +817,9 @@ openclaw logs --no-color
### `gateway <subcommand>`
Gateway 网关 CLI 辅助工具（RPC 子命令使用 `--url`、`--token`、`--password`、`--timeout`、`--expect-final`）。
Gateway 网关 CLI 助手（RPC 子命令可使用 `--url`、`--token`、`--password`、`--timeout`、`--expect-final`）。
当你传入 `--url` 时，CLI 不会自动应用配置或环境凭据。
请显式包含 `--token` 或 `--password`。缺少显式凭据会报错。
子命令：
@ -738,13 +837,14 @@ Gateway 网关 CLI 辅助工具（RPC 子命令使用 `--url`、`--token`、`--p
- `config.patch`（合并部分更新 + 重启 + 唤醒）
- `update.run`（运行更新 + 重启 + 唤醒）
提示：直接调用 `config.set`/`config.apply`/`config.patch` 时，如果配置已存在，请传入来自 `config.get` 的 `baseHash`。
提示：直接调用 `config.set`/`config.apply`/`config.patch` 时，如果配置已存在，请从
`config.get` 传入 `baseHash`。
## 模型
回退行为和扫描策略参见 [/concepts/models](/concepts/models)。
关于回退行为和扫描策略，请参见 [/concepts/models](/concepts/models)。
首选 Anthropic 认证（setup-token）：
Anthropic setup-token（已支持）：
```bash
claude setup-token
@ -752,6 +852,10 @@ openclaw models auth setup-token --provider anthropic
openclaw models status
```
策略说明：这是技术兼容性。Anthropic 过去曾阻止某些
Claude Code 之外的订阅使用；在生产环境依赖 setup-token 之前，请确认当前的 Anthropic
条款。
### `models`（根命令）
`openclaw models` 是 `models status` 的别名。
@ -777,15 +881,16 @@ openclaw models status
- `--json`
- `--plain`
- `--check`（退出码 1=过期/缺失，2=即将过期）
- `--check`（退出码 1=已过期 / 缺失，2=即将过期）
- `--probe`（对已配置认证配置文件进行实时探测）
- `--probe-provider <name>`
- `--probe-profile <id>`（重复或逗号分隔）
- `--probe-profile <id>`（可重复或逗号分隔）
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
始终包含认证概览和认证存储中配置文件的 OAuth 过期状态。`--probe` 运行实时请求（可能消耗令牌并触发速率限制）。
始终包含认证总览以及认证存储中配置文件的 OAuth 过期状态。
`--probe` 会发起实时请求（可能消耗 token 并触发速率限制）。
### `models set <model>`
@ -842,7 +947,7 @@ openclaw models status
选项：
- `add`：交互式认证辅助工具
- `add`：交互式认证助手
- `setup-token`：`--provider <name>`（默认 `anthropic`）、`--yes`
- `paste-token`：`--provider <name>`、`--profile-id <id>`、`--expires-in <duration>`
@ -858,9 +963,9 @@ openclaw models status
### `system event`
将系统事件加入队列并可选触发心跳（Gateway 网关 RPC）。
将一个系统事件加入队列，并可选择触发一次 heartbeat（Gateway 网关 RPC）。
必需：
必需项：
- `--text <text>`
@ -868,47 +973,48 @@ openclaw models status
- `--mode <now|next-heartbeat>`
- `--json`
- `--url`、`--token`、`--timeout`、`--expect-final`
- `--url`, `--token`, `--timeout`, `--expect-final`
### `system heartbeat last|enable|disable`
心跳控制（Gateway 网关 RPC）。
heartbeat 控制（Gateway 网关 RPC）。
选项：
- `--json`
- `--url`、`--token`、`--timeout`、`--expect-final`
- `--url`, `--token`, `--timeout`, `--expect-final`
### `system presence`
列出系统存在条目（Gateway 网关 RPC）。
列出系统 presence 条目（Gateway 网关 RPC）。
选项：
- `--json`
- `--url`、`--token`、`--timeout`、`--expect-final`
- `--url`, `--token`, `--timeout`, `--expect-final`
## 定时任务
## Cron
管理计划任务（Gateway 网关 RPC）。参见 [/automation/cron-jobs](/automation/cron-jobs)。
子命令：
- `cron status [--json]`
- `cron list [--all] [--json]`（默认表格输出；使用 `--json` 获取原始数据）
- `cron add`（别名：`create`；需要 `--name` 和 `--at` | `--every` | `--cron` 三选一，以及 `--system-event` | `--message` 负载二选一）
- `cron edit <id>`（补丁字段）
- `cron rm <id>`（别名：`remove`、`delete`）
- `cron list [--all] [--json]`（默认输出表格；原始输出请使用 `--json`）
- `cron add`（别名：`create`；要求 `--name`，并且必须且只能提供 `--at` | `--every` | `--cron` 之一，以及 `--system-event` | `--message` 之一作为负载）
- `cron edit <id>`（修补字段）
- `cron rm <id>`（别名：`remove`, `delete`）
- `cron enable <id>`
- `cron disable <id>`
- `cron runs --id <id> [--limit <n>]`
- `cron run <id> [--force]`
所有 `cron` 命令接受 `--url`、`--token`、`--timeout`、`--expect-final`。
所有 `cron` 命令都接受 `--url`、`--token`、`--timeout`、`--expect-final`。
## 节点主机
## Node 主机
`node` 运行**无头节点主机**或将其作为后台服务管理。参见 [`openclaw node`](/cli/node)。
`node` 运行一个**无头 node host**，或将其作为后台服务进行管理。参见
[`openclaw node`](/cli/node)。
子命令：
@ -919,13 +1025,18 @@ openclaw models status
- `node stop`
- `node restart`
## 节点
认证说明：
`nodes` 与 Gateway 网关通信并针对已配对的节点。参见 [/nodes](/nodes)。
- `node` 从环境 / 配置解析 gateway 认证（不支持 `--token`/`--password` 标志）：`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`，然后是 `gateway.auth.*`。在本地模式下，node host 会有意忽略 `gateway.remote.*`；在 `gateway.mode=remote` 时，`gateway.remote.*` 会根据远程优先级规则参与解析。
- 旧版 `CLAWDBOT_GATEWAY_*` 环境变量会被有意忽略，不用于 node-host 认证解析。
## Nodes
`nodes` 与 Gateway 网关通信，并以已配对节点为目标。参见 [/nodes](/nodes)。
通用选项：
- `--url`、`--token`、`--timeout`、`--json`
- `--url`, `--token`, `--timeout`, `--json`
子命令：
@ -937,8 +1048,8 @@ openclaw models status
- `nodes reject <requestId>`
- `nodes rename --node <id|name|ip> --name <displayName>`
- `nodes invoke --node <id|name|ip> --command <command> [--params <json>] [--invoke-timeout <ms>] [--idempotency-key <key>]`
- `nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>`（mac 节点或无头节点主机）
- `nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>]`（仅限 mac）
- `nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>`（mac 节点或无头 node host）
- `nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>]`（仅 mac）
相机：
@ -946,7 +1057,7 @@ openclaw models status
- `nodes camera snap --node <id|name|ip> [--facing front|back|both] [--device-id <id>] [--max-width <px>] [--quality <0-1>] [--delay-ms <ms>] [--invoke-timeout <ms>]`
- `nodes camera clip --node <id|name|ip> [--facing front|back] [--device-id <id>] [--duration <ms|10s|1m>] [--no-audio] [--invoke-timeout <ms>]`
画布 + 屏幕：
Canvas + 屏幕：
- `nodes canvas snapshot --node <id|name|ip> [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--invoke-timeout <ms>]`
- `nodes canvas present --node <id|name|ip> [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>] [--invoke-timeout <ms>]`
@ -963,11 +1074,11 @@ openclaw models status
## 浏览器
浏览器控制 CLI（专用 Chrome/Brave/Edge/Chromium）。参见 [`openclaw browser`](/cli/browser) 和[浏览器工具](/tools/browser)。
浏览器控制 CLI（专用 Chrome/Brave/Edge/Chromium）。参见 [`openclaw browser`](/cli/browser) 和 [Browser 工具](/tools/browser)。
通用选项：
- `--url`、`--token`、`--timeout`、`--json`
- `--url`, `--token`, `--timeout`, `--json`
- `--browser-profile <name>`
管理：
@ -1011,7 +1122,7 @@ openclaw models status
### `docs [query...]`
搜索在线文档索引。
搜索实时文档索引。
## TUI
@ -1028,5 +1139,5 @@ openclaw models status
- `--deliver`
- `--thinking <level>`
- `--message <text>`
- `--timeout-ms <ms>`（默认为 `agents.defaults.timeoutSeconds`）
- `--timeout-ms <ms>`（默认值为 `agents.defaults.timeoutSeconds`）
- `--history-limit <n>`

152
docs/zh-CN/cli/onboard.md
View File

@ -1,24 +1,28 @@
---
read_when:
- 你想要 Gateway 网关、工作区、认证、渠道和 Skills 的引导式设置
summary: "`openclaw onboard` 的 CLI 参考（交互式新手引导向导）"
- 你想通过引导式设置来配置 Gateway 网关、工作区、身份验证、渠道和 Skills
summary: "`openclaw onboard` 的 CLI 参考（交互式设置向导）"
title: onboard
x-i18n:
generated_at: "2026-02-03T07:45:00Z"
model: claude-opus-4-5
provider: pi
source_hash: a661049a6983233986a880a68440a3bcc6869ee2c4c6f5e9f3ab8ff973e22f60
generated_at: "2026-03-16T06:21:32Z"
model: gpt-5.4
provider: openai
source_hash: 04d7747342c582abcfcafff28847b4297f65ada665157d9cfbe3dbb258ee31d9
source_path: cli/onboard.md
workflow: 15
---
# `openclaw onboard`
交互式新手引导向导（本地或远程 Gateway 网关设置）。
交互式设置向导（本地或远程 Gateway 网关设置）。
相关内容：
## 相关指南
- 向导指南：[新手引导](/start/onboarding)
- CLI 新手引导中心：[设置向导（CLI）](/start/wizard)
- 新手引导概览：[新手引导概览](/start/onboarding-overview)
- CLI 新手引导参考：[CLI 设置参考](/start/wizard-cli-reference)
- CLI 自动化：[CLI 自动化](/start/wizard-cli-automation)
- macOS 新手引导：[新手引导（macOS 应用）](/start/onboarding)
## 示例
@ -26,11 +30,135 @@ x-i18n:
openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url ws://gateway-host:18789
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```
对于明文私有网络 `ws://` 目标（仅限受信任网络），请在新手引导进程环境中设置
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`。
非交互式自定义提供商：
```bash
openclaw onboard --non-interactive \
--auth-choice custom-api-key \
--custom-base-url "https://llm.example.com/v1" \
--custom-model-id "foo-large" \
--custom-api-key "$CUSTOM_API_KEY" \
--secret-input-mode plaintext \
--custom-compatibility openai
```
在非交互式模式下，`--custom-api-key` 是可选的。如果省略，新手引导会检查 `CUSTOM_API_KEY`。
非交互式 Ollama：
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
`--custom-base-url` 默认为 `http://127.0.0.1:11434`。`--custom-model-id` 是可选的；如果省略，新手引导会使用 Ollama 建议的默认值。像 `kimi-k2.5:cloud` 这样的云端模型 ID 在这里也可用。
将提供商密钥存储为引用而不是明文：
```bash
openclaw onboard --non-interactive \
--auth-choice openai-api-key \
--secret-input-mode ref \
--accept-risk
```
使用 `--secret-input-mode ref` 时，新手引导会写入由环境变量支持的引用，而不是明文密钥值。
对于由 auth-profile 支持的提供商，这会写入 `keyRef` 条目；对于自定义提供商，这会将 `models.providers.<id>.apiKey` 写为环境变量引用（例如 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`）。
非交互式 `ref` 模式约定：
- 在新手引导进程环境中设置提供商环境变量（例如 `OPENAI_API_KEY`）。
- 不要传递内联密钥标志（例如 `--openai-api-key`），除非该环境变量也已设置。
- 如果传递了内联密钥标志但未设置所需环境变量，新手引导会快速失败并提供指引。
非交互式模式中的 Gateway 网关令牌选项：
- `--gateway-auth token --gateway-token <token>` 存储明文令牌。
- `--gateway-auth token --gateway-token-ref-env <name>` 将 `gateway.auth.token` 存储为环境变量 SecretRef。
- `--gateway-token` 和 `--gateway-token-ref-env` 互斥。
- `--gateway-token-ref-env` 要求在新手引导进程环境中存在一个非空环境变量。
- 使用 `--install-daemon` 时，当令牌身份验证需要令牌时，由 SecretRef 管理的 Gateway 网关令牌会被验证，但不会以已解析的明文形式持久化到 supervisor 服务环境元数据中。
- 使用 `--install-daemon` 时，如果令牌模式需要令牌，而配置的令牌 SecretRef 未解析，新手引导会以封闭失败方式终止，并提供修复指引。
- 使用 `--install-daemon` 时，如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，新手引导会阻止安装，直到显式设置 mode。
示例：
```bash
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
--mode local \
--auth-choice skip \
--gateway-auth token \
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
--accept-risk
```
非交互式本地 Gateway 网关健康检查：
- 除非你传递 `--skip-health`，否则新手引导会等待本地 Gateway 网关可访问后才成功退出。
- `--install-daemon` 会先启动受管 Gateway 网关安装路径。不使用它时，你必须已经有一个正在运行的本地 Gateway 网关，例如 `openclaw gateway run`。
- 如果你只想在自动化中写入配置/工作区/bootstrap，请使用 `--skip-health`。
- 在原生 Windows 上，`--install-daemon` 会先尝试 Scheduled Tasks；如果任务创建被拒绝，则回退到每用户 Startup 文件夹登录项。
带引用模式的交互式新手引导行为：
- 出现提示时，选择**使用密钥引用**。
- 然后选择以下之一：
- 环境变量
- 已配置的密钥提供商（`file` 或 `exec`）
- 新手引导会在保存引用前执行快速预检验证。
- 如果验证失败，新手引导会显示错误并让你重试。
非交互式 Z.AI 端点选择：
注意：`--auth-choice zai-api-key` 现在会为你的密钥自动检测最佳 Z.AI 端点（优先使用通用 API 搭配 `zai/glm-5`）。
如果你明确想使用 GLM Coding Plan 端点，请选择 `zai-coding-global` 或 `zai-coding-cn`。
```bash
# 无提示端点选择
openclaw onboard --non-interactive \
--auth-choice zai-coding-global \
--zai-api-key "$ZAI_API_KEY"
# 其他 Z.AI 端点选择：
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn
```
非交互式 Mistral 示例：
```bash
openclaw onboard --non-interactive \
--auth-choice mistral-api-key \
--mistral-api-key "$MISTRAL_API_KEY"
```
流程说明：
- `quickstart`：最少提示，自动生成 Gateway 网关令牌。
- `manual`：完整的端口/绑定/认证提示（`advanced` 的别名）。
- 最快开始聊天：`openclaw dashboard`（控制 UI，无需渠道设置）。
- `manual`：提供端口/绑定/身份验证的完整提示（`advanced` 的别名）。
- 本地新手引导私信范围行为：[CLI 设置参考](/start/wizard-cli-reference#outputs-and-internals)。
- 最快开始第一次聊天：`openclaw dashboard`（控制 UI，无需设置渠道）。
- 自定义提供商：连接任何兼容 OpenAI 或 Anthropic 的端点，
包括未列出的托管提供商。使用 Unknown 进行自动检测。
## 常见后续命令
```bash
openclaw configure
openclaw agents add <name>
```
<Note>
`--json` 不代表非交互式模式。脚本请使用 `--non-interactive`。
</Note>

14
docs/zh-CN/cli/setup.md
View File

@ -1,16 +1,16 @@
---
read_when:
- 你在不使用完整新手引导向导的情况下进行首次设置
- 你正在进行首次运行设置，但不使用完整的设置向导
- 你想设置默认工作区路径
summary: "`openclaw setup` 的 CLI 参考（初始化配置 + 工作区）"
title: setup
x-i18n:
generated_at: "2026-02-01T20:21:26Z"
model: claude-opus-4-5
provider: pi
source_hash: 7f3fc8b246924edf48501785be2c0d356bd31bfbb133e75a139a5ee41dbf57f4
generated_at: "2026-03-16T06:21:20Z"
model: gpt-5.4
provider: openai
source_hash: b6d6fef6642a4fdf9880ea4f752981b5ed0404289274ee3429ee31702873e3ea
source_path: cli/setup.md
workflow: 14
workflow: 15
---
# `openclaw setup`
@ -19,7 +19,7 @@ x-i18n:
相关内容：
- 快速开始：[快速开始](/start/getting-started)
- 入门指南：[入门指南](/start/getting-started)
- 向导：[新手引导](/start/onboarding)
## 示例

142
docs/zh-CN/concepts/agent-workspace.md
View File

@ -5,28 +5,26 @@ read_when:
summary: 智能体工作区：位置、布局和备份策略
title: 智能体工作区
x-i18n:
generated_at: "2026-02-03T07:45:49Z"
model: claude-opus-4-5
provider: pi
source_hash: 84c550fd89b5f2474aeae586795485fd29d36effbb462f13342b31540fc18b82
generated_at: "2026-03-16T06:21:45Z"
model: gpt-5.4
provider: openai
source_hash: 6854ddbebe2d21da08c4e1773da6a44f02c815070677821996dab4c91cfb9cd4
source_path: concepts/agent-workspace.md
workflow: 15
---
# 智能体工作区
工作区是智能体的家。它是文件工具和工作区上下文使用的唯一工作目录。请保持其私密性并将其视为记忆。
工作区是智能体的“家”。它是文件工具和工作区上下文所使用的唯一工作目录。请将其保持为私有，并将其视为记忆。
这与 `~/.openclaw/` 是分开的，后者存储配置、凭证和会话。
这与存储配置、凭证和会话的 `~/.openclaw/` 是分开的。
**重要：** 工作区是**默认 cwd**，而不是硬性沙箱。工具会根据工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱隔离。如果你需要隔离，请使用
[`agents.defaults.sandbox`](/gateway/sandboxing)（和/或每智能体沙箱配置）。
当启用沙箱隔离且 `workspaceAccess` 不是 `"rw"` 时，工具在 `~/.openclaw/sandboxes` 下的沙箱工作区内操作，而不是你的主机工作区。
**重要：**工作区是**默认 cwd**，而不是硬性沙箱。工具会相对于工作区解析相对路径，但除非启用沙箱隔离，否则绝对路径仍然可以访问主机上的其他位置。如果你需要隔离，请使用 [`agents.defaults.sandbox`](/gateway/sandboxing)（和/或按智能体配置的沙箱）。启用沙箱隔离后，如果 `workspaceAccess` 不是 `"rw"`，工具会在 `~/.openclaw/sandboxes` 下的沙箱工作区中运行，而不是在你的主机工作区中运行。
## 默认位置
- 默认：`~/.openclaw/workspace`
- 如果设置了 `OPENCLAW_PROFILE` 且不是 `"default"`，默认值变为
- 默认值：`~/.openclaw/workspace`
- 如果设置了 `OPENCLAW_PROFILE` 且其值不是 `"default"`，默认值将变为
`~/.openclaw/workspace-<profile>`。
- 在 `~/.openclaw/openclaw.json` 中覆盖：
@ -38,9 +36,10 @@ x-i18n:
}
```
`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 将创建工作区并在缺失时填充引导文件。
`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 会在工作区缺失时创建工作区并植入引导文件。
沙箱种子复制仅接受工作区内的常规文件；解析到源工作区外部的符号链接/硬链接别名会被忽略。
如果你已经自己管理工作区文件，可以禁用引导文件创建：
如果你已经自行管理工作区文件，可以禁用引导文件创建：
```json5
{ agent: { skipBootstrap: true } }
@ -48,91 +47,92 @@ x-i18n:
## 额外的工作区文件夹
旧版安装可能创建了 `~/openclaw`。保留多个工作区目录可能会导致混乱的认证或状态漂移，因为同一时间只有一个工作区是活动的。
较旧的安装可能创建过 `~/openclaw`。保留多个工作区目录可能会导致令人困惑的凭证或状态漂移，因为同一时间只有一个工作区处于活动状态。
**建议：** 保持单个活动工作区。如果你不再使用额外的文件夹，请归档或移至废纸篓（例如 `trash ~/openclaw`）。
如果你有意保留多个工作区，请确保 `agents.defaults.workspace` 指向活动的那个。
**建议：**只保留一个活动工作区。如果你不再使用额外的文件夹，请将其归档或移到废纸篓（例如 `trash ~/openclaw`）。
如果你有意保留多个工作区，请确保
`agents.defaults.workspace` 指向当前活动的那个。
`openclaw doctor` 在检测到额外工作区目录时会发出警告。
当 `openclaw doctor` 检测到额外的工作区目录时，会发出警告。
## 工作区文件映射（每个文件的含义）
这些是 OpenClaw 在工作区内期望的标准文件：
以下是 OpenClaw 在工作区内预期的标准文件：
- `AGENTS.md`
- 智能体的操作指南以及它应该如何使用记忆。
- 在每个会话开始时加载。
- 适合放置规则、优先级和"如何行为"的详细信息。
- 智能体的操作说明，以及它应如何使用记忆。
- 每次会话开始时加载。
- 很适合放置规则、优先级和“如何表现”之类的细节。
- `SOUL.md`
- 人设、语气和边界。
- 每个会话加载。
- 每次会话都会加载。
- `USER.md`
- 用户是谁以及如何称呼他们。
- 每个会话加载。
- 用户是谁，以及应如何称呼他们。
- 每次会话都会加载。
- `IDENTITY.md`
- 智能体的名称、风格和表情符号。
- 智能体的名称、风格和 emoji。
- 在引导仪式期间创建/更新。
- `TOOLS.md`
- 关于你本地工具和惯例的注释。
- 不控制工具可用性；仅作为指导。
- 关于你的本地工具和约定的说明。
- 它不控制工具可用性；仅提供指导。
- `HEARTBEAT.md`
- 可选的心跳运行小型检查清单。
- 保持简短以避免 token 消耗。
- 可选的心跳运行微型检查清单。
- 保持简短以避免消耗过多 token。
- `BOOT.md`
- 当启用内部 hooks 时，在 Gateway 网关重启时执行的可选启动检查清单。
- 保持简短；使用 message 工具进行出站发送。
- 可选的启动检查清单；当启用内部 hooks 时，会在 Gateway 网关重启时执行。
- 保持简短；出站发送请使用消息工具。
- `BOOTSTRAP.md`
- 一次性首次运行仪式。
- 仅为全新工作区创建。
- 仪式完成后删除它。
- 一次性的首次运行仪式。
- 仅为全新的工作区创建。
- 仪式完成后请将其删除。
- `memory/YYYY-MM-DD.md`
- 每日记忆日志（每天一个文件）。
- 建议在会话开始时读取今天 + 昨天的内容。
- 建议在会话开始时阅读今天和昨天的内容。
- `MEMORY.md`（可选）
- 精选的长期记忆。
- 仅在主私密会话中加载（不在共享/群组上下文中）。
- 仅在主私有会话中加载（不在共享/群组上下文中加载）。
参见 [记忆](/concepts/memory) 了解工作流程和自动记忆刷新。
有关工作流和自动记忆刷新，请参见[记忆](/concepts/memory)。
- `skills/`（可选）
- 工作区特定的 Skills。
- 当名称冲突时覆盖托管/捆绑的 Skills。
- 工作区专用技能。
- 名称冲突时会覆盖托管/捆绑的 Skills。
- `canvas/`（可选）
- 用于节点显示的 Canvas UI 文件（例如 `canvas/index.html`）。
如果任何引导文件缺失，OpenClaw 会在会话中注入"缺失文件"标记并继续。大型引导文件在注入时会被截断；使用 `agents.defaults.bootstrapMaxChars` 调整限制（默认：20000）。
`openclaw setup` 可以重新创建缺失的默认值而不覆盖现有文件。
如果任何引导文件缺失，OpenClaw 会在会话中注入一个“缺失文件”标记并继续执行。注入时，大型引导文件会被截断；可使用 `agents.defaults.bootstrapMaxChars`（默认：20000）和 `agents.defaults.bootstrapTotalMaxChars`（默认：150000）调整限制。
`openclaw setup` 可以重新创建缺失的默认文件，而不会覆盖现有文件。
## 工作区中不包含的内容
## 不在工作区中的内容
这些位于 `~/.openclaw/` 下，不应提交到工作区仓库：
这些内容位于 `~/.openclaw/` 下，**不应**提交到工作区仓库：
- `~/.openclaw/openclaw.json`（配置）
- `~/.openclaw/credentials/`（OAuth token、API 密钥）
- `~/.openclaw/agents/<agentId>/sessions/`（会话记录 + 元数据）
- `~/.openclaw/skills/`（托管的 Skills）
- `~/.openclaw/credentials/`（OAuth 令牌、API 密钥）
- `~/.openclaw/agents/<agentId>/sessions/`（会话记录和元数据）
- `~/.openclaw/skills/`（托管 Skills）
如果你需要迁移会话或配置，请单独复制它们并将它们排除在版本控制之外。
如果你需要迁移会话或配置，请单独复制它们，并确保不要将其纳入版本控制。
## Git 备份（推荐，私有）
将工作区视为私密记忆。将其放入**私有** git 仓库以便备份和恢复。
将工作区视为私有记忆。把它放进一个**私有** git 仓库，以便备份并可恢复。
在运行 Gateway 网关的机器上执行这些步骤（工作区就在那里）。
请在 Gateway 网关运行的机器上执行这些步骤（工作区就位于那里）。
### 1）初始化仓库
如果安装了 git，全新工作区会自动初始化。如果此工作区还不是仓库，请运行：
如果已安装 git，全新工作区会自动初始化。如果这个工作区还不是仓库，请运行：
```bash
cd ~/.openclaw/workspace
@ -141,14 +141,14 @@ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"
```
### 2）添加私有远程（适合初学者的选项）
### 2）添加私有远程仓库（适合新手的选项）
选项 A：GitHub 网页界面
选项 A：GitHub Web UI
1. 在 GitHub 上创建新的**私有**仓库。
2. 不要用 README 初始化（避免合并冲突）。
1. 在 GitHub 上创建一个新的**私有**仓库。
2. 不要使用 README 初始化（以避免合并冲突）。
3. 复制 HTTPS 远程 URL。
4. 添加远程并推送：
4. 添加远程仓库并推送：
```bash
git branch -M main
@ -163,12 +163,12 @@ gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push
```
选项 C：GitLab 网页界面
选项 C：GitLab Web UI
1. 在 GitLab 上创建新的**私有**仓库。
2. 不要用 README 初始化（避免合并冲突）。
1. 在 GitLab 上创建一个新的**私有**仓库。
2. 不要使用 README 初始化（以避免合并冲突）。
3. 复制 HTTPS 远程 URL。
4. 添加远程并推送：
4. 添加远程仓库并推送：
```bash
git branch -M main
@ -187,15 +187,15 @@ git push
## 不要提交密钥
即使在私有仓库中，也要避免在工作区中存储密钥：
即使在私有仓库中，也应避免在工作区中存储密钥：
- API 密钥、OAuth token、密码或私有凭证。
- API 密钥、OAuth 令牌、密码或私有凭证。
- `~/.openclaw/` 下的任何内容。
- 聊天的原始转储或敏感附件。
- 聊天原始转储或敏感附件。
如果你必须存储敏感引用，请使用占位符并将真正的密钥保存在其他地方（密码管理器、环境变量或 `~/.openclaw/`）。
如果你必须存储敏感引用，请使用占位符，并将真实密钥保存在其他地方（密码管理器、环境变量或 `~/.openclaw/`）。
建议的 `.gitignore` 起始配置：
建议的 `.gitignore` 起始内容：
```gitignore
.DS_Store
@ -207,13 +207,13 @@ git push
## 将工作区迁移到新机器
1. 将仓库克隆到所需路径（默认 `~/.openclaw/workspace`）。
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` 下使用每会话沙箱工作区。
- 多智能体路由可以为不同智能体使用不同的工作区。有关路由配置，请参见
[渠道路由](/channels/channel-routing)。
- 如果启用了 `agents.defaults.sandbox`，非主会话可以在 `agents.defaults.sandbox.workspaceRoot` 下使用按会话划分的沙箱工作区。

501
docs/zh-CN/concepts/model-providers.md
View File

@ -1,107 +1,155 @@
---
read_when:
- 你需要一份逐提供商的模型设置参考
- 你需要模型提供商的示例配置或 CLI 新手引导命令
summary: 模型提供商概览，包含示例配置和 CLI 流程
- 你需要按提供商划分的模型设置参考
- 你想要模型提供商的示例配置或 CLI 新手引导命令
summary: 模型提供商概览，包含示例配置 + CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-03-16T02:12:40Z"
model: claude-opus-4-6
provider: pi
source_hash: 978798c80c5809c162f9807072ab48fdf99bfe0db39b2b3c245ce8b4e5451603
generated_at: "2026-03-16T06:22:52Z"
model: gpt-5.4
provider: openai
source_hash: 1b84eea0103a59e77571f82c800c9c0ad9fc554e8c9b2c1fd15c2cc121e7f6b4
source_path: concepts/model-providers.md
workflow: 15
---
# 模型提供商
本页涵盖 **LLM/模型提供商** （不是 WhatsApp/Telegram 等聊天渠道）。
有关模型选择规则，请参阅 [/concepts/models](/concepts/models)。
本页介绍的是 **LLM/模型提供商**（而不是像 WhatsApp/Telegram 这样的聊天渠道）。
有关模型选择规则，请参见 [/concepts/models](/concepts/models)。
## 快速规则
- 模型引用使用 `provider/model` （例如： `opencode/claude-opus-4-6`）。
- 如果你设置了 `agents.defaults.models`，它将成为允许列表。
- CLI 辅助命令： `openclaw onboard`， `openclaw models list`， `openclaw models set <provider/model>`。
- 提供商插件可以通过以下方式注入模型目录 `registerProvider({ catalog })`；
OpenClaw 将该输出合并到 `models.providers` 之后再写入
`models.json`。
- 提供商插件还可以通过以下方式控制提供商的运行时行为
`resolveDynamicModel`， `prepareDynamicModel`， `normalizeResolvedModel`，
`capabilities`， `prepareExtraParams`， `wrapStreamFn`，
`isCacheTtlEligible`， `prepareRuntimeAuth`， `resolveUsageAuth`，以及
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
- 如果你设置了 `agents.defaults.models`，它就会成为 allowlist。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；
OpenClaw 会在写入
`models.json` 之前将该输出合并到 `models.providers` 中。
- 提供商清单可以声明 `providerAuthEnvVars`，这样基于通用环境变量的
身份验证探测就不需要加载插件运行时。其余的核心环境变量映射
现在只用于非插件/核心提供商，以及少数通用优先级场景，
例如 Anthropic 以 API 密钥优先的新手引导。
- 提供商插件还可以通过以下机制接管提供商运行时行为：
`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、
`capabilities`、`prepareExtraParams`、`wrapStreamFn`、`formatApiKey`、
`refreshOAuth`、`buildAuthDoctorHint`、
`isCacheTtlEligible`、`buildMissingAuthMessage`、
`suppressBuiltInModel`、`augmentModelCatalog`、`isBinaryThinking`、
`supportsXHighThinking`、`resolveDefaultThinkingLevel`、
`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`，以及
`fetchUsageSnapshot`。
## 插件管理的提供商行为
## 插件接管的提供商行为
提供商插件现在可以管理大部分提供商特定逻辑，而 OpenClaw 负责维护通用推理循环。
提供商插件现在可以接管大多数提供商特定逻辑，而 OpenClaw 保留
通用推理循环。
典型分工：
典型划分：
- `catalog`：提供商出现在 `models.providers`
- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 ID
- `prepareDynamicModel`：提供商在重试动态解析之前需要刷新元数据
- `normalizeResolvedModel`：提供商需要传输层或基础 URL 重写
- `capabilities`：提供商发布会话记录/工具/提供商系列的特殊行为
- `prepareExtraParams`：提供商默认或规范化每个模型的请求参数
- `wrapStreamFn`：提供商应用请求头/请求体/模型兼容性封装
- `auth[].run` / `auth[].runNonInteractive`：提供商接管 `openclaw onboard`、`openclaw models auth` 和无头设置的
新手引导/登录流程
- `wizard.onboarding` / `wizard.modelPicker`：提供商接管新手引导/模型选择器中的身份验证选项标签、
提示和设置条目
- `catalog`：提供商出现在 `models.providers` 中
- `resolveDynamicModel`：提供商接受尚未出现在本地静态
目录中的模型 ID
- `prepareDynamicModel`：提供商在重试
动态解析之前需要刷新元数据
- `normalizeResolvedModel`：提供商需要重写传输或基础 URL
- `capabilities`：提供商发布 transcript/工具/提供商家族的特殊行为
- `prepareExtraParams`：提供商为每个模型请求参数提供默认值或进行标准化
- `wrapStreamFn`：提供商应用请求头/请求体/模型兼容包装器
- `formatApiKey`：提供商将存储的 auth profile 格式化为
传输层预期的运行时 `apiKey` 字符串
- `refreshOAuth`：当共享的 `pi-ai`
刷新器不足时，由提供商接管 OAuth 刷新
- `buildAuthDoctorHint`：当 OAuth 刷新
失败时，提供商附加修复指引
- `isCacheTtlEligible`：提供商决定哪些上游模型 ID 支持 prompt-cache TTL
- `prepareRuntimeAuth`：提供商将配置的凭证转换为短期运行时令牌
- `resolveUsageAuth`：提供商为以下用途解析使用量/配额凭证 `/usage`
以及相关的状态/报告界面
- `fetchUsageSnapshot`：提供商负责使用量端点的获取/解析，而核心仍负责摘要外壳和格式化
- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示
替换通用 auth-store 错误
- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以在直接解析失败时返回
供应商自有错误
- `augmentModelCatalog`：提供商在
发现和配置合并后追加合成/最终目录条目
- `isBinaryThinking`：提供商接管二元开/关 thinking UX
- `supportsXHighThinking`：提供商让选定模型支持 `xhigh`
- `resolveDefaultThinkingLevel`：提供商接管某个
模型家族默认 `/think` 策略
- `isModernModelRef`：提供商接管 live/smoke 首选模型匹配
- `prepareRuntimeAuth`：提供商将已配置凭证转换为短期
运行时令牌
- `resolveUsageAuth`：提供商为 `/usage`
以及相关状态/报告界面解析使用量/配额凭证
- `fetchUsageSnapshot`：提供商接管使用量端点的获取/解析，而核心仍负责摘要外壳和格式化
当前内置示例：
- `anthropic`：Claude 4.6 向前兼容回退、使用量端点获取，以及 cache-TTL/提供商系列元数据
- `openrouter`：直通模型 ID、请求封装、提供商能力提示，以及 cache-TTL 策略
- `github-copilot`：向前兼容模型回退、Claude-thinking 会话记录提示、运行时令牌交换，以及使用量端点获取
- `openai`：GPT-5.4 向前兼容回退、直接 OpenAI 传输规范化，以及提供商系列元数据
- `openai-codex`：向前兼容模型回退、传输规范化，以及默认传输参数和使用量端点获取
- `google-gemini-cli`：Gemini 3.1 向前兼容回退，以及使用量界面的 usage-token 解析和配额端点获取
- `moonshot`：共享传输、插件管理的 thinking 负载规范化
- `kilocode`：共享传输、插件管理的请求头、推理负载规范化、Gemini 会话记录提示，以及 cache-TTL 策略
- `zai`：GLM-5 向前兼容回退， `tool_stream` 默认值、cache-TTL 策略，以及使用量认证和配额获取
- `mistral`， `opencode`，以及`opencode-go`：插件管理的能力元数据
- `byteplus`， `cloudflare-ai-gateway`， `huggingface`， `kimi-coding`，
`minimax-portal`， `modelstudio`， `nvidia`， `qianfan`， `qwen-portal`，
`synthetic`， `together`， `venice`， `vercel-ai-gateway`，以及`volcengine`：仅限插件管理的目录
- `minimax` 和 `xiaomi`：插件管理的目录以及使用量认证/快照逻辑
- `anthropic`：Claude 4.6 前向兼容回退、身份验证修复提示、使用量
端点获取，以及 cache-TTL/提供商家族元数据
- `openrouter`：直通模型 ID、请求包装器、提供商能力
提示，以及 cache-TTL 策略
- `github-copilot`：新手引导/设备登录、前向兼容模型回退、
Claude-thinking transcript 提示、运行时令牌交换，以及使用量端点
获取
- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输
标准化、Codex 感知的缺失身份验证提示、Spark 抑制、合成
OpenAI/Codex 目录条目、thinking/live-model 策略，以及
提供商家族元数据
- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退和
现代模型匹配；Gemini CLI OAuth 还接管 auth-profile 令牌
格式化、usage-token 解析，以及面向使用量界面的配额端点获取
- `moonshot`：共享传输、插件接管的 thinking 负载标准化
- `kilocode`：共享传输、插件接管的请求头、reasoning 负载
标准化、Gemini transcript 提示，以及 cache-TTL 策略
- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、cache-TTL
策略、二元 thinking/live-model 策略，以及使用量身份验证 + 配额获取
- `mistral`、`opencode` 和 `opencode-go`：插件接管的能力元数据
- `byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi-coding`、
`modelstudio`、`nvidia`、`qianfan`、`synthetic`、`together`、`venice`、
`vercel-ai-gateway` 和 `volcengine`：仅插件接管的目录
- `qwen-portal`：插件接管的目录、OAuth 登录和 OAuth 刷新
- `minimax` 和 `xiaomi`：插件接管的目录，以及使用量身份验证/快照逻辑
以上涵盖了仍然适用于 OpenClaw 常规传输层的提供商。如果某个提供商需要完全自定义的请求执行器，则属于一个独立的、更深层的扩展层面。
内置的 `openai` 插件现在接管两个提供商 ID：`openai` 和
`openai-codex`。
以上涵盖了仍适合 OpenClaw 常规传输的提供商。若某个提供商
需要完全自定义的请求执行器，那就是另一个更深层的扩展接口。
## API 密钥轮换
- 支持对选定提供商的通用提供商轮换。
- 支持为选定提供商进行通用提供商轮换。
- 通过以下方式配置多个密钥：
- `OPENCLAW_LIVE_<PROVIDER>_KEY` （单个实时覆盖，最高优先级）
- `<PROVIDER>_API_KEYS` （逗号或分号分隔的列表）
- `<PROVIDER>_API_KEY` （主密钥）
- `<PROVIDER>_API_KEY_*` （编号列表，例如 `<PROVIDER>_API_KEY_1`）
- 对于 Google 提供商， `GOOGLE_API_KEY` 也作为备选项包含在内。
- 密钥选择顺序按优先级排列并去除重复值。
- 仅在速率限制响应时使用下一个密钥重试请求（例如 `429`， `rate_limit`， `quota`， `resource exhausted`）。
- 非速率限制的失败会立即报错；不会尝试密钥轮换。
- 当所有候选密钥均失败时，返回最后一次尝试的错误。
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个 live 覆盖，最高优先级）
- `<PROVIDER>_API_KEYS`（逗号或分号分隔列表）
- `<PROVIDER>_API_KEY`（主密钥）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
- 对于 Google 提供商，还会包含 `GOOGLE_API_KEY` 作为回退。
- 密钥选择顺序会保留优先级并对值去重。
- 仅在速率限制响应时才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`）。
- 非速率限制失败会立即失败；不会尝试密钥轮换。
- 当所有候选密钥都失败时，将返回最后一次尝试的最终错误。
## 内置提供商（pi-ai 目录）
OpenClaw 附带 pi-ai 目录。这些提供商需要 **无需**
`models.providers` 配置；只需设置认证并选择一个模型。
OpenClaw 附带 pi‑ai 目录。这些提供商**不需要**
`models.providers` 配置；只需设置身份验证 + 选择一个模型。
### OpenAI
- 提供商： `openai`
- 认证： `OPENAI_API_KEY`
- 可选轮换： `OPENAI_API_KEYS`， `OPENAI_API_KEY_1`， `OPENAI_API_KEY_2`，加上 `OPENCLAW_LIVE_OPENAI_KEY` （单个覆盖）
- 示例模型： `openai/gpt-5.4`， `openai/gpt-5.4-pro`
- CLI： `openclaw onboard --auth-choice openai-api-key`
- 默认传输为 `auto` （WebSocket 优先，SSE 备选）
- 通过以下方式覆盖每个模型 `agents.defaults.models["openai/<model>"].params.transport` （`"sse"`， `"websocket"`，或 `"auto"`）
- OpenAI Responses WebSocket 预热默认通过以下方式启用 `params.openaiWsWarmup` （`true`/`false`）
- OpenAI 优先处理可以通过以下方式启用 `agents.defaults.models["openai/<model>"].params.serviceTier`
- OpenAI 快速模式可以通过以下方式为每个模型启用 `agents.defaults.models["<provider>/<model>"].params.fastMode`
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为 OpenAI 实时 API 会拒绝它；Spark 被视为仅限 Codex 使用
- 提供商：`openai`
- 身份验证：`OPENAI_API_KEY`
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
- 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-pro`
- CLI：`openclaw onboard --auth-choice openai-api-key`
- 默认传输为 `auto`（优先 WebSocket，SSE 回退）
- 通过 `agents.defaults.models["openai/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`）
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先处理
- 可通过 `agents.defaults.models["<provider>/<model>"].params.fastMode` 为每个模型启用 OpenAI 快速模式
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex
```json5
{
@ -111,14 +159,14 @@ OpenClaw 附带 pi-ai 目录。这些提供商需要 **无需**
### Anthropic
- 提供商： `anthropic`
- 认证： `ANTHROPIC_API_KEY` 或 `claude setup-token`
- 可选轮换： `ANTHROPIC_API_KEYS`， `ANTHROPIC_API_KEY_1`， `ANTHROPIC_API_KEY_2`，加上 `OPENCLAW_LIVE_ANTHROPIC_KEY` （单个覆盖）
- 示例模型： `anthropic/claude-opus-4-6`
- CLI： `openclaw onboard --auth-choice token` （粘贴 setup-token）或 `openclaw models auth paste-token --provider anthropic`
- 直接 API 密钥模型支持共享的 `/fast` 切换和 `params.fastMode`；OpenClaw 将其映射到 Anthropic 的 `service_tier` （`auto` 与 `standard_only`）
- 策略说明：setup-token 支持属于技术兼容性；Anthropic 过去曾阻止部分订阅在 Claude Code 之外的使用。请核实当前 Anthropic 条款，并根据你的风险承受能力做出决定。
- 建议：Anthropic API 密钥认证是比订阅 setup-token 认证更安全的推荐方式。
- 提供商：`anthropic`
- 身份验证：`ANTHROPIC_API_KEY` 或 `claude setup-token`
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖）
- 示例模型：`anthropic/claude-opus-4-6`
- CLI：`openclaw onboard --auth-choice token`（粘贴 setup-token）或 `openclaw models auth paste-token --provider anthropic`
- 直接 API 密钥模型支持共享的 `/fast` 开关和 `params.fastMode`；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- 策略说明：setup-token 支持属于技术兼容性；Anthropic 过去曾阻止某些在 Claude Code 之外的订阅用法。请核实当前 Anthropic 条款，并根据你的风险承受能力做出决定。
- 建议：相比订阅 setup-token 身份验证，Anthropic API 密钥身份验证是更安全、也更推荐的路径。
```json5
{
@ -126,17 +174,17 @@ OpenClaw 附带 pi-ai 目录。这些提供商需要 **无需**
}
```
### OpenAI Code (Codex)
### OpenAI Code（Codex）
- 提供商： `openai-codex`
- 认证：OAuth (ChatGPT)
- 示例模型： `openai-codex/gpt-5.4`
- CLI： `openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
- 默认传输为 `auto` （WebSocket 优先，SSE 备选）
- 通过以下方式覆盖每个模型 `agents.defaults.models["openai-codex/<model>"].params.transport` （`"sse"`， `"websocket"`，或 `"auto"`）
- 与相同的 `/fast` 切换和 `params.fastMode` 配置共享，如同直接的 `openai/*`
- `openai-codex/gpt-5.3-codex-spark` 当 Codex OAuth 目录公开时仍然可用；取决于授权资格
- 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 等外部工具/工作流。
- 提供商：`openai-codex`
- 身份验证：OAuth（ChatGPT）
- 示例模型：`openai-codex/gpt-5.4`
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
- 默认传输为 `auto`（优先 WebSocket，SSE 回退）
- 通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置
- 当 Codex OAuth 目录暴露它时，`openai-codex/gpt-5.3-codex-spark` 仍然可用；取决于 entitlement
- 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 这样的外部工具/工作流。
```json5
{
@ -146,11 +194,11 @@ OpenClaw 附带 pi-ai 目录。这些提供商需要 **无需**
### OpenCode
- 认证： `OPENCODE_API_KEY` （或 `OPENCODE_ZEN_API_KEY`）
- Zen 运行时提供商： `opencode`
- Go 运行时提供商： `opencode-go`
- 示例模型： `opencode/claude-opus-4-6`， `opencode-go/kimi-k2.5`
- CLI： `openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`
- 身份验证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
- Zen 运行时提供商：`opencode`
- Go 运行时提供商：`opencode-go`
- 示例模型：`opencode/claude-opus-4-6`、`opencode-go/kimi-k2.5`
- CLI：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`
```json5
{
@ -160,94 +208,97 @@ OpenClaw 附带 pi-ai 目录。这些提供商需要 **无需**
### Google Gemini（API 密钥）
- 提供商： `google`
- 认证： `GEMINI_API_KEY`
- 可选轮换： `GEMINI_API_KEYS`， `GEMINI_API_KEY_1`， `GEMINI_API_KEY_2`， `GOOGLE_API_KEY` 备选，以及 `OPENCLAW_LIVE_GEMINI_KEY` （单个覆盖）
- 示例模型： `google/gemini-3.1-pro-preview`， `google/gemini-3-flash-preview`
- 兼容性：使用旧版 OpenClaw 配置的 `google/gemini-3.1-flash-preview` 会被规范化为 `google/gemini-3-flash-preview`
- CLI： `openclaw onboard --auth-choice gemini-api-key`
- 提供商：`google`
- 身份验证：`GEMINI_API_KEY`
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被标准化为 `google/gemini-3-flash-preview`
- CLI：`openclaw onboard --auth-choice gemini-api-key`
### Google Vertex 和 Gemini CLI
- 提供商： `google-vertex`， `google-gemini-cli`
- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。部分用户报告称在使用第三方客户端后 Google 账户受到限制。请查阅 Google 条款，如果你选择继续，建议使用非关键账户。
- Gemini CLI OAuth 作为内置的 `google` 插件的一部分提供。
- 启用： `openclaw plugins enable google`
- 登录： `openclaw models auth login --provider google-gemini-cli --set-default`
- 注意：你确实 **不** 需要将 client ID 或 secret 粘贴到 `openclaw.json`中。CLI 登录流程将令牌存储在 Gateway 网关主机的认证配置文件中。
- 提供商：`google-vertex`、`google-gemini-cli`
- 身份验证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告在使用第三方客户端后遭遇 Google 账号限制。请查看 Google 条款，如果你决定继续，建议使用非关键账号。
- Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
- 启用：`openclaw plugins enable google`
- 登录：`openclaw models auth login --provider google-gemini-cli --set-default`
- 注意：你**不需要**将客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会将
令牌存储在 Gateway 网关主机上的 auth profile 中。
### Z.AI (GLM)
### Z.AI（GLM）
- 提供商： `zai`
- 认证： `ZAI_API_KEY`
- 示例模型： `zai/glm-5`
- CLI： `openclaw onboard --auth-choice zai-api-key`
- 别名： `z.ai/*` 和 `z-ai/*` 规范化为 `zai/*`
- 提供商：`zai`
- 身份验证：`ZAI_API_KEY`
- 示例模型：`zai/glm-5`
- CLI：`openclaw onboard --auth-choice zai-api-key`
- 别名：`z.ai/*` 和 `z-ai/*` 会标准化为 `zai/*`
### Vercel AI Gateway
- 提供商： `vercel-ai-gateway`
- 认证： `AI_GATEWAY_API_KEY`
- 示例模型： `vercel-ai-gateway/anthropic/claude-opus-4.6`
- CLI： `openclaw onboard --auth-choice ai-gateway-api-key`
- 提供商：`vercel-ai-gateway`
- 身份验证：`AI_GATEWAY_API_KEY`
- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6`
- CLI：`openclaw onboard --auth-choice ai-gateway-api-key`
### Kilo Gateway
- 提供商： `kilocode`
- 认证： `KILOCODE_API_KEY`
- 示例模型： `kilocode/anthropic/claude-opus-4.6`
- CLI： `openclaw onboard --kilocode-api-key <key>`
- 基础 URL： `https://api.kilo.ai/api/gateway/`
- 扩展的内置目录包括 GLM-5 Free、MiniMax M2.5 Free、GPT-5.2、Gemini 3 Pro Preview、Gemini 3 Flash Preview、Grok Code Fast 1 和 Kimi K2.5。
- 提供商：`kilocode`
- 身份验证：`KILOCODE_API_KEY`
- 示例模型：`kilocode/anthropic/claude-opus-4.6`
- CLI：`openclaw onboard --kilocode-api-key <key>`
- 基础 URL：`https://api.kilo.ai/api/gateway/`
- 扩展后的内置目录包括 GLM-5 Free、MiniMax M2.5 Free、GPT-5.2、Gemini 3 Pro Preview、Gemini 3 Flash Preview、Grok Code Fast 1 和 Kimi K2.5。
参阅 [/providers/kilocode](/providers/kilocode) 了解详情。
设置详情请参见 [/providers/kilocode](/providers/kilocode)。
### 其他内置提供商插件
- OpenRouter： `openrouter` （`OPENROUTER_API_KEY`）
- 示例模型： `openrouter/anthropic/claude-sonnet-4-5`
- Kilo Gateway： `kilocode` （`KILOCODE_API_KEY`）
- 示例模型： `kilocode/anthropic/claude-opus-4.6`
- MiniMax： `minimax` （`MINIMAX_API_KEY`）
- Moonshot： `moonshot` （`MOONSHOT_API_KEY`）
- Kimi Coding： `kimi-coding` （`KIMI_API_KEY` 或 `KIMICODE_API_KEY`）
- Qianfan： `qianfan` （`QIANFAN_API_KEY`）
- Model Studio： `modelstudio` （`MODELSTUDIO_API_KEY`）
- NVIDIA： `nvidia` （`NVIDIA_API_KEY`）
- Together： `together` （`TOGETHER_API_KEY`）
- Venice： `venice` （`VENICE_API_KEY`）
- Xiaomi： `xiaomi` （`XIAOMI_API_KEY`）
- Vercel AI Gateway： `vercel-ai-gateway` （`AI_GATEWAY_API_KEY`）
- Hugging Face Inference： `huggingface` （`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`）
- Cloudflare AI Gateway： `cloudflare-ai-gateway` （`CLOUDFLARE_AI_GATEWAY_API_KEY`）
- Volcengine： `volcengine` （`VOLCANO_ENGINE_API_KEY`）
- BytePlus： `byteplus` （`BYTEPLUS_API_KEY`）
- xAI： `xai` （`XAI_API_KEY`）
- Mistral： `mistral` （`MISTRAL_API_KEY`）
- 示例模型： `mistral/mistral-large-latest`
- CLI： `openclaw onboard --auth-choice mistral-api-key`
- Groq： `groq` （`GROQ_API_KEY`）
- Cerebras： `cerebras` （`CEREBRAS_API_KEY`）
- OpenRouter：`openrouter`（`OPENROUTER_API_KEY`）
- 示例模型：`openrouter/anthropic/claude-sonnet-4-5`
- Kilo Gateway：`kilocode`（`KILOCODE_API_KEY`）
- 示例模型：`kilocode/anthropic/claude-opus-4.6`
- MiniMax：`minimax`（`MINIMAX_API_KEY`）
- Moonshot：`moonshot`（`MOONSHOT_API_KEY`）
- Kimi Coding：`kimi-coding`（`KIMI_API_KEY` 或 `KIMICODE_API_KEY`）
- Qianfan：`qianfan`（`QIANFAN_API_KEY`）
- Model Studio：`modelstudio`（`MODELSTUDIO_API_KEY`）
- NVIDIA：`nvidia`（`NVIDIA_API_KEY`）
- Together：`together`（`TOGETHER_API_KEY`）
- Venice：`venice`（`VENICE_API_KEY`）
- Xiaomi：`xiaomi`（`XIAOMI_API_KEY`）
- Vercel AI Gateway：`vercel-ai-gateway`（`AI_GATEWAY_API_KEY`）
- Hugging Face Inference：`huggingface`（`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`）
- Cloudflare AI Gateway：`cloudflare-ai-gateway`（`CLOUDFLARE_AI_GATEWAY_API_KEY`）
- Volcengine：`volcengine`（`VOLCANO_ENGINE_API_KEY`）
- BytePlus：`byteplus`（`BYTEPLUS_API_KEY`）
- xAI：`xai`（`XAI_API_KEY`）
- Mistral：`mistral`（`MISTRAL_API_KEY`）
- 示例模型：`mistral/mistral-large-latest`
- CLI：`openclaw onboard --auth-choice mistral-api-key`
- Groq：`groq`（`GROQ_API_KEY`）
- Cerebras：`cerebras`（`CEREBRAS_API_KEY`）
- Cerebras 上的 GLM 模型使用 ID `zai-glm-4.7` 和 `zai-glm-4.6`。
- 兼容 OpenAI 的基础 URL： `https://api.cerebras.ai/v1`。
- GitHub Copilot： `github-copilot` （`COPILOT_GITHUB_TOKEN`/`GH_TOKEN`/`GITHUB_TOKEN`）
- Hugging Face Inference 示例模型： `huggingface/deepseek-ai/DeepSeek-R1`；CLI： `openclaw onboard --auth-choice huggingface-api-key`。参阅 [Hugging Face (Inference)](/providers/huggingface)。
- OpenAI 兼容基础 URL：`https://api.cerebras.ai/v1`。
- GitHub Copilot：`github-copilot`（`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`）
- Hugging Face Inference 示例模型：`huggingface/deepseek-ai/DeepSeek-R1`；CLI：`openclaw onboard --auth-choice huggingface-api-key`。请参见 [Hugging Face（Inference）](/providers/huggingface)。
## 通过以下方式提供的提供商 `models.providers` （自定义/基础 URL）
## 通过 `models.providers` 配置的提供商（自定义/基础 URL）
使用 `models.providers` （或 `models.json`）来添加 **自定义** 提供商或 OpenAI/Anthropic 兼容代理。
使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或
兼容 OpenAI/Anthropic 的代理。
下方许多内置提供商插件已经发布了默认目录。
使用显式的 `models.providers.<id>` 条目仅在你需要覆盖默认基础 URL、请求头或模型列表时使用。
下面许多内置提供商插件已经发布了默认目录。
只有在你希望覆盖默认
基础 URL、请求头或模型列表时，才使用显式 `models.providers.<id>` 条目。
### Moonshot AI (Kimi)
### Moonshot AI（Kimi）
Moonshot 使用兼容 OpenAI 的端点，因此将其配置为自定义提供商：
- 提供商： `moonshot`
- 认证： `MOONSHOT_API_KEY`
- 示例模型： `moonshot/kimi-k2.5`
- 提供商：`moonshot`
- 身份验证：`MOONSHOT_API_KEY`
- 示例模型：`moonshot/kimi-k2.5`
Kimi K2 模型 ID：
@ -284,9 +335,9 @@ Kimi K2 模型 ID：
Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
- 提供商： `kimi-coding`
- 认证： `KIMI_API_KEY`
- 示例模型： `kimi-coding/k2p5`
- 提供商：`kimi-coding`
- 身份验证：`KIMI_API_KEY`
- 示例模型：`kimi-coding/k2p5`
```json5
{
@ -297,10 +348,10 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
}
```
### Qwen OAuth（免费套餐）
### Qwen OAuth（免费层）
Qwen 通过设备码流程提供对 Qwen Coder + Vision 的 OAuth 访问。
内置提供商插件默认启用，只需登录：
Qwen 通过设备代码流程提供对 Qwen Coder + Vision 的 OAuth 访问。
内置提供商插件默认启用，因此只需登录：
```bash
openclaw models auth login --provider qwen-portal --set-default
@ -311,16 +362,16 @@ openclaw models auth login --provider qwen-portal --set-default
- `qwen-portal/coder-model`
- `qwen-portal/vision-model`
参阅 [/providers/qwen](/providers/qwen) 了解详情和注意事项。
设置详情和说明请参见 [/providers/qwen](/providers/qwen)。
### 火山引擎（豆包）
### Volcano Engine（Doubao）
火山引擎提供对豆包及中国其他模型的访问。
Volcano Engine（火山引擎）为中国用户提供对 Doubao 和其他模型的访问。
- 提供商： `volcengine` （编码： `volcengine-plan`）
- 认证： `VOLCANO_ENGINE_API_KEY`
- 示例模型： `volcengine/doubao-seed-1-8-251228`
- CLI： `openclaw onboard --auth-choice volcengine-api-key`
- 提供商：`volcengine`（编码：`volcengine-plan`）
- 身份验证：`VOLCANO_ENGINE_API_KEY`
- 示例模型：`volcengine/doubao-seed-1-8-251228`
- CLI：`openclaw onboard --auth-choice volcengine-api-key`
```json5
{
@ -332,11 +383,11 @@ openclaw models auth login --provider qwen-portal --set-default
可用模型：
- `volcengine/doubao-seed-1-8-251228` （豆包 Seed 1.8）
- `volcengine/doubao-seed-1-8-251228`（Doubao Seed 1.8）
- `volcengine/doubao-seed-code-preview-251028`
- `volcengine/kimi-k2-5-260127` （Kimi K2.5）
- `volcengine/glm-4-7-251222` （GLM 4.7）
- `volcengine/deepseek-v3-2-251201` （DeepSeek V3.2 128K）
- `volcengine/kimi-k2-5-260127`（Kimi K2.5）
- `volcengine/glm-4-7-251222`（GLM 4.7）
- `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K）
编码模型（`volcengine-plan`）：
@ -348,12 +399,12 @@ openclaw models auth login --provider qwen-portal --set-default
### BytePlus（国际版）
BytePlus ARK 为国际用户提供与火山引擎相同的模型访问。
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。
- 提供商： `byteplus` （编码： `byteplus-plan`）
- 认证： `BYTEPLUS_API_KEY`
- 示例模型： `byteplus/seed-1-8-251228`
- CLI： `openclaw onboard --auth-choice byteplus-api-key`
- 提供商：`byteplus`（编码：`byteplus-plan`）
- 身份验证：`BYTEPLUS_API_KEY`
- 示例模型：`byteplus/seed-1-8-251228`
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
```json5
{
@ -365,9 +416,9 @@ BytePlus ARK 为国际用户提供与火山引擎相同的模型访问。
可用模型：
- `byteplus/seed-1-8-251228` （Seed 1.8）
- `byteplus/kimi-k2-5-260127` （Kimi K2.5）
- `byteplus/glm-4-7-251222` （GLM 4.7）
- `byteplus/seed-1-8-251228`（Seed 1.8）
- `byteplus/kimi-k2-5-260127`（Kimi K2.5）
- `byteplus/glm-4-7-251222`（GLM 4.7）
编码模型（`byteplus-plan`）：
@ -379,12 +430,12 @@ BytePlus ARK 为国际用户提供与火山引擎相同的模型访问。
### Synthetic
Synthetic 提供 Anthropic 兼容模型，位于 `synthetic` 提供商背后：
Synthetic 通过 `synthetic` 提供商提供兼容 Anthropic 的模型：
- 提供商： `synthetic`
- 认证： `SYNTHETIC_API_KEY`
- 示例模型： `synthetic/hf:MiniMaxAI/MiniMax-M2.5`
- CLI： `openclaw onboard --auth-choice synthetic-api-key`
- 提供商：`synthetic`
- 身份验证：`SYNTHETIC_API_KEY`
- 示例模型：`synthetic/hf:MiniMaxAI/MiniMax-M2.5`
- CLI：`openclaw onboard --auth-choice synthetic-api-key`
```json5
{
@ -407,24 +458,24 @@ Synthetic 提供 Anthropic 兼容模型，位于 `synthetic` 提供商背后：
### MiniMax
MiniMax 通过以下方式配置 `models.providers` ，因为它使用自定义端点：
MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax（Anthropic 兼容）： `--auth-choice minimax-api`
- 认证： `MINIMAX_API_KEY`
- MiniMax（兼容 Anthropic）：`--auth-choice minimax-api`
- 身份验证：`MINIMAX_API_KEY`
参阅 [/providers/minimax](/providers/minimax) 了解详情、模型选项和配置代码片段。
设置详情、模型选项和配置片段请参见 [/providers/minimax](/providers/minimax)。
### Ollama
Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API：
- 提供商： `ollama`
- 认证：无需（本地服务器）
- 示例模型： `ollama/llama3.3`
- 安装： [https://ollama.com/download](https://ollama.com/download)
- 提供商：`ollama`
- 身份验证：无需（本地服务器）
- 示例模型：`ollama/llama3.3`
- 安装：[https://ollama.com/download](https://ollama.com/download)
```bash
# Install Ollama, then pull a model:
# 安装 Ollama，然后拉取一个模型：
ollama pull llama3.3
```
@ -436,26 +487,26 @@ ollama pull llama3.3
}
```
Ollama 在本地通过以下地址检测 `http://127.0.0.1:11434` 当你通过以下方式选择启用时
`OLLAMA_API_KEY`，内置提供商插件会将 Ollama 直接添加到
`openclaw onboard` 和模型选择器中。参阅 [/providers/ollama](/providers/ollama)
了解新手引导、云端/本地模式和自定义配置。
当你通过
`OLLAMA_API_KEY` 选择加入时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到，内置提供商插件会将 Ollama 直接添加到
`openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/providers/ollama)。
### vLLM
vLLM 作为内置提供商插件提供，用于本地/自托管的兼容 OpenAI 服务器：
vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容
服务器：
- 提供商： `vllm`
- 认证：可选（取决于你的服务器）
- 默认基础 URL： `http://127.0.0.1:8000/v1`
- 提供商：`vllm`
- 身份验证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:8000/v1`
要在本地选择启用自动发现（如果你的服务器不强制认证，任何值均可）：
要选择加入本地自动发现（如果你的服务器不强制身份验证，则任意值均可）：
```bash
export VLLM_API_KEY="vllm-local"
```
然后设置一个模型（替换为由 `/v1/models`）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -465,23 +516,25 @@ export VLLM_API_KEY="vllm-local"
}
```
参阅 [/providers/vllm](/providers/vllm) 了解详情。
详情请参见 [/providers/vllm](/providers/vllm)。
### SGLang
SGLang 作为内置提供商插件提供，用于快速自托管的兼容 OpenAI 服务器：
SGLang 作为内置提供商插件提供，用于高速自托管
OpenAI 兼容服务器：
- 提供商： `sglang`
- 认证：可选（取决于你的服务器）
- 默认基础 URL： `http://127.0.0.1:30000/v1`
- 提供商：`sglang`
- 身份验证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:30000/v1`
要在本地选择启用自动发现（如果你的服务器不强制认证，任何值均可）：
要选择加入本地自动发现（如果你的服务器不
强制身份验证，则任意值均可）：
```bash
export SGLANG_API_KEY="sglang-local"
```
然后设置一个模型（替换为由 `/v1/models`）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -491,7 +544,7 @@ export SGLANG_API_KEY="sglang-local"
}
```
参阅 [/providers/sglang](/providers/sglang) 了解详情。
详情请参见 [/providers/sglang](/providers/sglang)。
### 本地代理（LM Studio、vLLM、LiteLLM 等）
@ -528,19 +581,19 @@ export SGLANG_API_KEY="sglang-local"
}
```
注意事项：
说明：
- 对于自定义提供商， `reasoning`， `input`， `cost`， `contextWindow`，以及`maxTokens` 是可选的。
省略时，OpenClaw 默认为：
- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 是可选的。
如果省略，OpenClaw 默认使用：
- `reasoning: false`
- `input: ["text"]`
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`
- 建议：设置与你的代理/模型限制相匹配的显式值。
- 对于 `api: "openai-completions"` 在非原生端点上（任何非空的 `baseUrl` 且主机不是 `api.openai.com`），OpenClaw 强制使用 `compat.supportsDeveloperRole: false` 以避免提供商对不支持的 `developer` 角色返回 400 错误。
- 如果 `baseUrl` 为空/省略，OpenClaw 保持默认的 OpenAI 行为（解析为 `api.openai.com`）。
- 为安全起见，显式的 `compat.supportsDeveloperRole: true` 在非原生 `openai-completions` 端点上仍会被覆盖。
- 建议：设置与你的代理/模型限制匹配的显式值。
- 对于非原生端点上的 `api: "openai-completions"`（任何主机不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（即解析为 `api.openai.com`）。
- 出于安全考虑，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。
## CLI 示例
@ -550,4 +603,4 @@ openclaw models set opencode/claude-opus-4-6
openclaw models list
```
另请参阅： [/gateway/configuration](/gateway/configuration) 查看完整配置示例。
另请参见：[/gateway/configuration](/gateway/configuration) 了解完整配置示例。

151
docs/zh-CN/concepts/models.md
View File

@ -1,79 +1,85 @@
---
read_when:
- 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks）
- 更改模型回退行为或选择用户体验
- 更新模型扫描探测（工具/图像）
summary: 模型 CLI：列表、设置、别名、回退、扫描、状态
title: 模型 CLI
- 添加或修改 models CLI（models list/set/scan/aliases/fallbacks）
- 更改模型回退行为或选择 UX
- 更新模型扫描探测（tools/images）
summary: Models CLI：列出、设置、别名、回退、扫描、状态
title: Models CLI
x-i18n:
generated_at: "2026-02-03T10:05:42Z"
model: claude-opus-4-5
provider: pi
source_hash: e8b54bb370b4f63a9b917594fb0f6ff48192e168196d30c713b8bbe72b78fef6
generated_at: "2026-03-16T06:22:01Z"
model: gpt-5.4
provider: openai
source_hash: 26150aef638bc3375866dec736b98eac32384466a8ef2b0a471fb7ff7729b13c
source_path: concepts/models.md
workflow: 15
---
# 模型 CLI
# Models CLI
参见 [/concepts/model-failover](/concepts/model-failover) 了解认证配置文件轮换、冷却时间及其与回退的交互。
快速提供商概述 + 示例：[/concepts/model-providers](/concepts/model-providers)。
关于凭证配置轮换、冷却时间以及它们如何与回退交互，请参阅 [/concepts/model-failover](/concepts/model-failover)。
快速提供商概览 + 示例：[/concepts/model-providers](/concepts/model-providers)。
## 模型选择工作原理
## 模型选择的工作方式
OpenClaw 按以下顺序选择模型：
1. **主要**模型（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
2. `agents.defaults.model.fallbacks` 中的**回退**（按顺序）。
3. **提供商认证故障转移**在移动到下一个模型之前在提供商内部发生。
1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
2. `agents.defaults.model.fallbacks` 中的 **回退模型**（按顺序）。
3. **提供商凭证故障切换** 会在单个提供商内部发生，然后才会移动到下一个模型。
相关：
相关内容：
- `agents.defaults.models` 是 OpenClaw 可使用的模型白名单/目录（加上别名）。
- `agents.defaults.imageModel` **仅在**主要模型无法接受图像时使用。
- 每个智能体的默认值可以通过 `agents.list[].model` 加绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/concepts/multi-agent)）。
- `agents.defaults.models` 是 OpenClaw 可使用的模型允许列表/目录（以及别名）。
- `agents.defaults.imageModel` **仅在** 主模型无法接受图像时使用。
- 每个智能体的默认值可以通过 `agents.list[].model` 加上绑定来覆盖 `agents.defaults.model`（见 [/concepts/multi-agent](/concepts/multi-agent)）。
## 快速模型推荐（经验之谈）
## 快速模型策略
- **GLM**：在编程/工具调用方面稍好。
- **MiniMax**：在写作和氛围方面更好。
- 将你的主模型设置为你可用的、最新一代中最强的模型。
- 对于对成本/延迟敏感的任务和风险较低的聊天，使用回退模型。
- 对于启用了工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。
## 设置向导（推荐）
如果你不想手动编辑配置，请运行新手引导向导：
如果你不想手动编辑配置，请运行设置向导：
```bash
openclaw onboard
```
它可以为常见提供商设置模型 + 认证，包括 **OpenAI Code（Codex）订阅**（OAuth）和 **Anthropic**（推荐使用 API 密钥；也支持 `claude setup-token`）。
它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code (Codex)**
订阅（OAuth）和 **Anthropic**（API key 或 `claude setup-token`）。
## 配置键（概述）
## 配置键（概览）
- `agents.defaults.model.primary` 和 `agents.defaults.model.fallbacks`
- `agents.defaults.imageModel.primary` 和 `agents.defaults.imageModel.fallbacks`
- `agents.defaults.models`（白名单 + 别名 + 提供商参数）
- `agents.defaults.models`（允许列表 + 别名 + 提供商参数）
- `models.providers`（写入 `models.json` 的自定义提供商）
模型引用会规范化为小写。提供商别名如 `z.ai/*` 会规范化为 `zai/*`。
模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会被规范化
为 `zai/*`。
提供商配置示例（包括 OpenCode Zen）在 [/gateway/configuration](/gateway/configuration#opencode-zen-multi-model-proxy)。
提供商配置示例（包括 OpenCode）位于
[/gateway/configuration](/gateway/configuration#opencode)。
## "Model is not allowed"（以及为什么回复停止）
## “Model is not allowed”（以及为什么回复会停止）
如果设置了 `agents.defaults.models`，它将成为 `/model` 和会话覆盖的**白名单**。当用户选择不在该白名单中的模型时，OpenClaw 返回：
如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的 **允许列表**。当用户选择了不在该允许列表中的模型时，
OpenClaw 会返回：
```
Model "provider/model" is not allowed. Use /model to list available models.
```
这发生在正常回复生成**之前**，所以消息可能感觉像"没有响应"。修复方法是：
这会在生成正常回复 **之前** 发生，因此消息可能会让人觉得
它“没有响应”。修复方法是：
- 将模型添加到 `agents.defaults.models`，或
- 清除白名单（删除 `agents.defaults.models`），或
- 将该模型添加到 `agents.defaults.models`，或者
- 清除允许列表（移除 `agents.defaults.models`），或者
- 从 `/model list` 中选择一个模型。
白名单配置示例：
允许列表示例配置：
```json5
{
@ -81,7 +87,7 @@ Model "provider/model" is not allowed. Use /model to list available models.
model: { primary: "anthropic/claude-sonnet-4-5" },
models: {
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
"anthropic/claude-opus-4-5": { alias: "Opus" },
"anthropic/claude-opus-4-6": { alias: "Opus" },
},
},
}
@ -89,7 +95,7 @@ Model "provider/model" is not allowed. Use /model to list available models.
## 在聊天中切换模型（`/model`）
你可以在不重启的情况下切换当前会话的模型：
你可以在不重启的情况下为当前会话切换模型：
```
/model
@ -99,16 +105,17 @@ Model "provider/model" is not allowed. Use /model to list available models.
/model status
```
注意事项：
说明：
- `/model`（和 `/model list`）是紧凑的编号选择器（模型系列 + 可用提供商）。
- `/model <#>` 从该选择器中选择。
- `/model status` 是详细视图（认证候选项，以及配置时的提供商端点 `baseUrl` + `api` 模式）。
- 模型引用通过在**第一个** `/` 处分割来解析。输入 `/model <ref>` 时使用 `provider/model`。
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。
- 如果省略提供商，OpenClaw 将输入视为别名或**默认提供商**的模型（仅在模型 ID 中没有 `/` 时有效）。
- `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个 Submit 步骤。
- `/model <#>` 会从该选择器中进行选择。
- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` + `api` 模式）。
- 模型引用是通过按 **第一个** `/` 进行分割来解析的。输入 `/model <ref>` 时请使用 `provider/model`。
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。
- 如果你省略提供商，OpenClaw 会将输入视为别名或 **默认提供商** 的模型（仅在模型 ID 中没有 `/` 时有效）。
完整命令行为/配置：[斜杠命令](/tools/slash-commands)。
完整命令行为/配置： [Slash commands](/tools/slash-commands)。
## CLI 命令
@ -137,7 +144,7 @@ openclaw models image-fallbacks clear
### `models list`
默认显示已配置的模型。有用的标志：
默认显示已配置的模型。常用标志：
- `--all`：完整目录
- `--local`：仅本地提供商
@ -147,12 +154,18 @@ openclaw models image-fallbacks clear
### `models status`
显示已解析的主要模型、回退、图像模型，以及已配置提供商的认证概述。它还显示认证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内警告）。`--plain` 仅打印已解析的主要模型。
OAuth 状态始终显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印 **Missing auth** 部分。
JSON 包括 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效认证）。
使用 `--check` 进行自动化（缺失/过期时退出 `1`，即将过期时退出 `2`）。
显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示凭证存储中找到的配置文件的 OAuth 过期状态
（默认会在 24 小时内到期时警告）。`--plain` 仅打印已解析的
主模型。
OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置的
提供商没有凭证，`models status` 会打印一个 **Missing auth** 部分。
JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`
（每个提供商的有效凭证）。
自动化场景请使用 `--check`（缺失/已过期时退出码为 `1`，即将过期时为 `2`）。
首选的 Anthropic 认证是 Claude Code CLI setup-token（在任何地方运行；如需要在 Gateway 网关主机上粘贴）：
凭证选择取决于提供商/账号。对于始终在线的 Gateway 网关主机，API key 通常最可预测；也支持订阅 token 流程。
示例（Anthropic setup-token）：
```bash
claude setup-token
@ -161,21 +174,23 @@ openclaw models status
## 扫描（OpenRouter 免费模型）
`openclaw models scan` 检查 OpenRouter 的**免费模型目录**，并可选择性地探测模型的工具和图像支持。
`openclaw models scan` 会检查 OpenRouter 的 **免费模型目录**，并且可以
选择性地探测模型对工具和图像的支持。
关键标志：
- `--no-probe`：跳过实时探测（仅元数据）
- `--min-params <b>`：最小参数量（十亿）
- `--max-age-days <days>`：跳过较旧的模型
- `--min-params <b>`：最小参数规模（十亿）
- `--max-age-days <days>`：跳过较旧模型
- `--provider <name>`：提供商前缀筛选
- `--max-candidates <n>`：回退列表大小
- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择
- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择
- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择项
- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择项
探测需要 OpenRouter API 密钥（来自认证配置文件或 `OPENROUTER_API_KEY`）。没有密钥时，使用 `--no-probe` 仅列出候选项。
探测需要 OpenRouter API key（来自凭证配置文件或
`OPENROUTER_API_KEY`）。如果没有 key，请使用 `--no-probe` 仅列出候选项。
扫描结果按以下顺序排名：
扫描结果按以下顺序排序：
1. 图像支持
2. 工具延迟
@ -185,12 +200,26 @@ openclaw models status
输入
- OpenRouter `/models` 列表（筛选 `:free`）
- 需要来自认证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/help/environment)）
- 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API key（见 [/environment](/help/environment)）
- 可选筛选器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
- 探测控制：`--timeout`、`--concurrency`
在 TTY 中运行时，你可以交互式选择回退。在非交互模式下，传递 `--yes` 接受默认值。
在 TTY 中运行时，你可以交互式选择回退模型。在非交互
模式下，传入 `--yes` 以接受默认值。
## 模型注册表（`models.json`）
`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认 `~/.openclaw/agents/<agentId>/models.json`）。除非 `models.mode` 设置为 `replace`，否则此文件默认会被合并。
`models.providers` 中的自定义提供商会写入
智能体目录下的 `models.json`（默认是 `~/.openclaw/agents/<agentId>/agent/models.json`）。默认会合并此文件，除非将 `models.mode` 设置为 `replace`。
匹配提供商 ID 时的合并模式优先级：
- 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。
- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中不是 SecretRef 管理时才优先。
- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）刷新，而不是持久化已解析的 secret。
- 由 SecretRef 管理的提供商 header 值会从源标记（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）刷新。
- 智能体中为空或缺失的 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
- 其他提供商字段会从配置和规范化后的目录数据中刷新。
标记持久化以源为准：OpenClaw 会根据活动源配置快照（预解析）写入标记，而不是根据运行时已解析的 secret 值写入。
这适用于 OpenClaw 重新生成 `models.json` 的所有情况，包括像 `openclaw agent` 这样的命令驱动路径。

115
docs/zh-CN/concepts/oauth.md
View File

@ -1,69 +1,80 @@
---
read_when:
- 你想全面了解 OpenClaw 的 OAuth 流程
- 你想端到端了解 OpenClaw OAuth
- 你遇到了令牌失效/登出问题
- 你想了解 setup-token 或 OAuth 认证流程
- 你想使用多账户或配置文件路由
- 你想使用 setup-token 或 OAuth 认证流程
- 你想使用多个账户或配置文件路由
summary: OpenClaw 中的 OAuth：令牌交换、存储和多账户模式
title: OAuth
x-i18n:
generated_at: "2026-02-01T20:23:29Z"
model: claude-opus-4-5
provider: pi
source_hash: af714bdadc4a89295a18da1eba5f5b857c8d533ebabe9b0758b722fe60c36124
generated_at: "2026-03-16T06:22:05Z"
model: gpt-5.4
provider: openai
source_hash: 976668c3e02ee50500fcaaa585a89af718398dc41988318ec3a583c2d5449df3
source_path: concepts/oauth.md
workflow: 14
workflow: 15
---
# OAuth
OpenClaw 支持通过 OAuth 进行"订阅认证"，适用于提供此功能的提供商（特别是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic 订阅，请使用 **setup-token** 流程。本页说明：
OpenClaw 通过 OAuth 支持提供商提供的“订阅认证”，适用于支持此方式的提供商（尤其是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic 订阅，请使用 **setup-token** 流程。过去有些用户在 Claude Code 之外使用 Anthropic 订阅时曾受限，因此这应视为用户自行选择承担的风险，你应自行核实 Anthropic 当前的政策。OpenAI Codex OAuth 明确支持在 OpenClaw 这样的外部工具中使用。本页说明：
- OAuth **令牌交换**的工作原理（PKCE）
- 令牌**存储**在哪里（以及原因）
- 如何处理**多账户**（配置文件 + 按会话覆盖）
对于生产环境中的 Anthropic，相比订阅 setup-token 认证，API 密钥认证是更安全、也更推荐的路径。
OpenClaw 还支持**提供商插件**，它们自带 OAuth 或 API 密钥流程。通过以下命令运行：
- OAuth **令牌交换** 如何工作（PKCE）
- 令牌**存储**在哪里（以及为什么）
- 如何处理**多个账户**（配置文件 + 按会话覆盖）
OpenClaw 也支持自带 OAuth 或 API 密钥流程的**提供商插件**。运行方式如下：
```bash
openclaw models auth login --provider <id>
```
## 令牌汇聚点（为什么需要它）
## 令牌汇点（为什么需要它）
OAuth 提供商通常在登录/刷新流程中发放**新的刷新令牌**。某些提供商（或 OAuth 客户端）在为同一用户/应用发放新令牌时，可能会使旧的刷新令牌失效。
OAuth 提供商通常会在登录/刷新流程中签发一个**新的刷新令牌**。某些提供商（或 OAuth 客户端）会在为同一用户/应用签发新令牌时使旧的刷新令牌失效。
实际症状：
- 你通过 OpenClaw _和_ Claude Code / Codex CLI 登录 → 其中一个稍后会随机"登出"
- 你同时通过 OpenClaw _和_ Claude Code / Codex CLI 登录 → 之后其中一个会随机“被登出”
为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为**令牌汇聚点**：
为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为一个**令牌汇点**：
- 运行时从**同一个位置**读取凭据
- 我们可以保留多个配置文件并确定性地路由它们
- 运行时从**同一个地方**读取凭证
- 我们可以保留多个配置文件，并进行确定性路由
## 存储（令牌存放位置）
密钥按**智能体**存储：
密钥按**每个智能体**存储：
- 认证配置文件（OAuth + API 密钥）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- 运行时缓存（自动管理；请勿编辑）：`~/.openclaw/agents/<agentId>/agent/auth.json`
- 认证配置文件（OAuth + API 密钥 + 可选的值级引用）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- 旧版兼容文件：`~/.openclaw/agents/<agentId>/agent/auth.json`
（发现静态 `api_key` 条目时会进行清理）
仅用于导入的旧版文件（仍然支持，但不是主存储）：
仅用于旧版导入的文件（仍受支持，但不是主存储）：
- `~/.openclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`）
- `~/.openclaw/credentials/oauth.json`（首次使用时会导入到 `auth-profiles.json`）
以上所有路径也遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys)
以上所有位置也都遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys)
有关静态密钥引用和运行时快照激活行为，请参见 [Secrets Management](/gateway/secrets)。
## Anthropic setup-token（订阅认证）
<Warning>
Anthropic setup-token 支持是技术兼容性，并非策略保证。
Anthropic 过去曾阻止过某些在 Claude Code 之外的订阅使用。
是否使用订阅认证由你自行决定，并请核实 Anthropic 当前的条款。
</Warning>
在任意机器上运行 `claude setup-token`，然后将其粘贴到 OpenClaw 中：
```bash
openclaw models auth setup-token --provider anthropic
```
如果你在其他地方生成了令牌，可以手动粘贴：
如果你是在其他地方生成的令牌，可手动粘贴：
```bash
openclaw models auth paste-token --provider anthropic
@ -75,77 +86,79 @@ openclaw models auth paste-token --provider anthropic
openclaw models status
```
## OAuth 交换（登录工作原理）
## OAuth 交换（登录如何工作）
OpenClaw 的交互式登录流程在 `@mariozechner/pi-ai` 中实现，并集成到向导/命令中。
OpenClaw 的交互式登录流程在 `@mariozechner/pi-ai` 中实现，并接入到各类向导/命令中。
### Anthropic（Claude Pro/Max）setup-token
### Anthropic setup-token
流程概要：
流程形态：
1. 运行 `claude setup-token`
2. 将令牌粘贴到 OpenClaw
3. 作为令牌认证配置文件存储（无刷新）
3. 存储为令牌认证配置文件（不刷新）
向导路径为 `openclaw onboard` → 认证选择 `setup-token`（Anthropic）。
### OpenAI Codex（ChatGPT OAuth）
流程概要（PKCE）：
OpenAI Codex OAuth 明确支持在 Codex CLI 之外使用，包括 OpenClaw 工作流。
1. 生成 PKCE 验证器/质询 + 随机 `state`
流程形态（PKCE）：
1. 生成 PKCE verifier/challenge 和随机 `state`
2. 打开 `https://auth.openai.com/oauth/authorize?...`
3. 尝试在 `http://127.0.0.1:1455/auth/callback` 捕获回调
4. 如果回调无法绑定（或你在远程/无头环境中），手动粘贴重定向 URL/代码
5. 在 `https://auth.openai.com/oauth/token` 进行交换
4. 如果回调无法绑定（或你是在远程/无头环境中），则粘贴重定向 URL/code
5. 在 `https://auth.openai.com/oauth/token` 交换令牌
6. 从访问令牌中提取 `accountId` 并存储 `{ access, refresh, expires, accountId }`
向导路径为 `openclaw onboard` → 认证选择 `openai-codex`。
## 刷新 + 过期
## 刷新和过期
配置文件存储 `expires` 时间戳。
配置文件会存储一个 `expires` 时间戳。
运行时：
在运行时：
- 如果 `expires` 在未来 → 使用已存储的访问令牌
- 如果已过期 → 刷新（在文件锁下）并覆盖已存储的凭据
- 如果 `expires` 尚未到期 → 使用已存储的访问令牌
- 如果已过期 → 在文件锁下刷新，并覆盖已存储的凭证
刷新流程是自动的；你通常不需要手动管理令牌。
刷新流程是自动的；通常你不需要手动管理令牌。
## 多账户（配置文件）+ 路由
## 多个账户（配置文件）+ 路由
两种模式：
有两种模式：
### 1）推荐：独立智能体
### 1）推荐：分离的智能体
如果你希望"个人"和"工作"永远不交叉，请使用隔离的智能体（独立的会话 + 凭据 + 工作区）：
如果你希望“个人”和“工作”永不交叉，请使用隔离的智能体（独立的会话 + 凭证 + 工作区）：
```bash
openclaw agents add work
openclaw agents add personal
```
然后按智能体配置认证（向导），并将聊天路由到正确的智能体。
然后按智能体配置认证（使用向导），并将聊天路由到正确的智能体。
### 2）高级：单个智能体中的多个配置文件
`auth-profiles.json` 支持同一提供商的多个配置文件 ID。
`auth-profiles.json` 支持同一提供商下的多个配置文件 ID。
选择使用哪个配置文件：
- 通过配置顺序全局设置（`auth.order`）
- 通过 `/model ...@<profileId>` 按会话设置
- 通过配置排序全局选择（`auth.order`）
- 通过 `/model ...@<profileId>` 按会话选择
示例（会话覆盖）：
- `/model Opus@anthropic:work`
如何查看存在哪些配置文件 ID：
查看现有配置文件 ID 的方法：
- `openclaw channels list --json`（显示 `auth[]`）
相关文档：
- [/concepts/model-failover](/concepts/model-failover)（轮换 + 冷却规则）
- [/tools/slash-commands](/tools/slash-commands)（命令界面）
- [/tools/slash-commands](/tools/slash-commands)（命令入口）

112
docs/zh-CN/gateway/authentication.md
View File

@ -1,41 +1,50 @@
---
read_when:
- 调试模型认证或 OAuth 过期
- 记录认证或凭证存储
summary: 模型认证：OAuth、API 密钥和 setup-token
- 编写有关认证或凭证存储的文档
summary: 模型认证：OAuth、API key 和 setup-token
title: 认证
x-i18n:
generated_at: "2026-02-03T07:47:32Z"
model: claude-opus-4-5
provider: pi
source_hash: 66fa2c64ff374c9cfcdb4e7a951b0d164d512295e65513eb682f12191b75e557
generated_at: "2026-03-16T06:22:17Z"
model: gpt-5.4
provider: openai
source_hash: 219ac1acd7d192a5a12779e204cca65dae77a852fdc668271c45c01e0c69b7c9
source_path: gateway/authentication.md
workflow: 15
---
# 认证
OpenClaw 支持模型提供商的 OAuth 和 API 密钥。对于 Anthropic 账户，我们推荐使用 **API 密钥**。对于 Claude 订阅访问，使用 `claude setup-token` 创建的长期令牌。
OpenClaw 支持模型提供商使用 OAuth 和 API key。对于始终在线的 Gateway 网关
主机，API key 通常是最可预测的选项。当它们与你的提供商账号模型匹配时，
也支持订阅/OAuth 流程。
参阅 [/concepts/oauth](/concepts/oauth) 了解完整的 OAuth 流程和存储布局。
完整的 OAuth 流程和存储布局，请参阅 [/concepts/oauth](/concepts/oauth)。
关于基于 SecretRef 的认证（`env`/`file`/`exec` 提供商），请参阅 [Secrets Management](/gateway/secrets)。
关于 `models status --probe` 使用的凭证资格/原因码规则，请参阅
[Auth Credential Semantics](/auth-credential-semantics)。
## 推荐的 Anthropic 设置（API 密钥）
## 推荐设置（API key，任意提供商）
如果你直接使用 Anthropic，请使用 API 密钥。
如果你正在运行长期存活的 Gateway 网关，请先为你选择的
提供商配置一个 API key。
对于 Anthropic，API key 认证是更稳妥的方式，推荐优先于
订阅 setup-token 认证。
1. 在 Anthropic 控制台创建 API 密钥。
2. 将其放在 **Gateway 网关主机**（运行 `openclaw gateway` 的机器）上。
1. 在你的提供商控制台中创建一个 API key。
2. 将它放在 **Gateway 网关主机** 上（运行 `openclaw gateway` 的机器）。
```bash
export ANTHROPIC_API_KEY="..."
export <PROVIDER>_API_KEY="..."
openclaw models status
```
3. 如果 Gateway 网关在 systemd/launchd 下运行，最好将密钥放在 `~/.openclaw/.env` 中以便守护进程可以读取：
3. 如果 Gateway 通过 systemd/launchd 运行，建议将 key 放入
`~/.openclaw/.env`，这样守护进程就可以读取它：
```bash
cat >> ~/.openclaw/.env <<'EOF'
ANTHROPIC_API_KEY=...
<PROVIDER>_API_KEY=...
EOF
```
@ -46,25 +55,28 @@ openclaw models status
openclaw doctor
```
如果你不想自己管理环境变量，新手引导向导可以为守护进程使用存储 API 密钥：`openclaw onboard`。
如果你不想自己管理环境变量，设置向导可以为守护进程使用场景存储
API key：`openclaw onboard`。
参阅[帮助](/help)了解环境变量继承的详情（`env.shellEnv`、`~/.openclaw/.env`、systemd/launchd）。
有关环境继承（`env.shellEnv`、
`~/.openclaw/.env`、systemd/launchd）的详细信息，请参阅 [Help](/help)。
## Anthropic：setup-token（订阅认证）
对于 Anthropic，推荐的路径是 **API 密钥**。如果你使用 Claude 订阅，也支持 setup-token 流程。在 **Gateway 网关主机**上运行：
如果你使用的是 Claude 订阅，则支持 setup-token 流程。请在
**Gateway 网关主机** 上运行：
```bash
claude setup-token
```
然后将其粘贴到 OpenClaw：
然后将它粘贴到 OpenClaw 中：
```bash
openclaw models auth setup-token --provider anthropic
```
如果令牌是在另一台机器上创建的，手动粘贴：
如果 token 是在另一台机器上创建的，请手动粘贴：
```bash
openclaw models auth paste-token --provider anthropic
@ -76,22 +88,34 @@ openclaw models auth paste-token --provider anthropic
This credential is only authorized for use with Claude Code and cannot be used for other API requests.
```
…请改用 Anthropic API 密钥。
……请改用 Anthropic API key。
手动令牌输入（任何提供商；写入 `auth-profiles.json` + 更新配置）：
<Warning>
Anthropic setup-token 支持仅是技术兼容性。Anthropic 过去曾阻止
Claude Code 之外的某些订阅用法。只有在你认为相关策略风险可接受时才使用它，
并请你自行核实 Anthropic 当前的条款。
</Warning>
手动输入 token（任意提供商；会写入 `auth-profiles.json` + 更新配置）：
```bash
openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openrouter
```
自动化友好检查（过期/缺失时退出 `1`，即将过期时退出 `2`）：
静态凭证也支持凭证配置文件引用：
- `api_key` 凭证可以使用 `keyRef: { source, provider, id }`
- `token` 凭证可以使用 `tokenRef: { source, provider, id }`
适合自动化的检查（已过期/缺失时退出码为 `1`，即将过期时为 `2`）：
```bash
openclaw models status --check
```
可选的运维脚本（systemd/Termux）在此处记录：[/automation/auth-monitoring](/automation/auth-monitoring)
可选的运维脚本（systemd/Termux）记录在这里：
[/automation/auth-monitoring](/automation/auth-monitoring)
> `claude setup-token` 需要交互式 TTY。
@ -102,17 +126,33 @@ openclaw models status
openclaw doctor
```
## API key 轮换行为（Gateway 网关）
某些提供商支持在 API 调用触发提供商限流时，使用替代 key 重试请求。
- 优先级顺序：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个覆盖值）
- `<PROVIDER>_API_KEYS`
- `<PROVIDER>_API_KEY`
- `<PROVIDER>_API_KEY_*`
- Google 提供商还将 `GOOGLE_API_KEY` 作为额外回退项。
- 使用前会对同一组 key 列表去重。
- 仅当出现限流错误时，OpenClaw 才会使用下一个 key 重试（例如
`429`、`rate_limit`、`quota`、`resource exhausted`）。
- 非限流错误不会使用替代 key 重试。
- 如果所有 key 都失败，则返回最后一次尝试的最终错误。
## 控制使用哪个凭证
### 每会话（聊天命令）
### 每个会话（聊天命令）
使用 `/model <alias-or-id>@<profileId>` 为当前会话固定特定的提供商凭证（示例配置文件 ID：`anthropic:default`、`anthropic:work`）。
使用 `/model <alias-or-id>@<profileId>` 为当前会话固定使用特定的提供商凭证（示例配置文件 id：`anthropic:default`、`anthropic:work`）。
使用 `/model`（或 `/model list`）获取紧凑的选择器；使用 `/model status` 获取完整视图（候选项 + 下一个认证配置文件，以及配置时的提供商端点详情）。
使用 `/model`（或 `/model list`）查看紧凑选择器；使用 `/model status` 查看完整视图（候选项 + 下一个凭证配置文件，以及在已配置时显示提供商端点详情）。
### 每智能体（CLI 覆盖）
### 每个智能体（CLI 覆盖）
为智能体设置显式的认证配置文件顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）：
为智能体设置显式的凭证配置文件顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）：
```bash
openclaw models auth order get --provider anthropic
@ -120,23 +160,25 @@ openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic
```
使用 `--agent <id>` 指定特定智能体；省略它则使用配置的默认智能体。
使用 `--agent <id>` 指定特定智能体；省略它则使用已配置的默认智能体。
## 故障排除
### "No credentials found"
### “No credentials found”
如果 Anthropic 令牌配置文件缺失，在 **Gateway 网关主机**上运行 `claude setup-token`，然后重新检查：
如果缺少 Anthropic token 配置文件，请在
**Gateway 网关主机** 上运行 `claude setup-token`，然后重新检查：
```bash
openclaw models status
```
### 令牌即将过期/已过期
### Token 即将过期/已过期
运行 `openclaw models status` 确认哪个配置文件即将过期。如果配置文件缺失，重新运行 `claude setup-token` 并再次粘贴令牌。
运行 `openclaw models status` 以确认哪个配置文件即将过期。如果该配置文件
缺失，请重新运行 `claude setup-token` 并再次粘贴 token。
## 要求
- Claude Max 或 Pro 订阅（用于 `claude setup-token`）
- Anthropic 订阅账号（用于 `claude setup-token`）
- 已安装 Claude Code CLI（`claude` 命令可用）

3103
docs/zh-CN/gateway/configuration-reference.md Normal file
View File

File diff suppressed because it is too large Load Diff

3770
docs/zh-CN/gateway/configuration.md
View File

File diff suppressed because it is too large Load Diff

78
docs/zh-CN/gateway/local-models.md
View File

@ -1,35 +1,37 @@
---
read_when:
- 你想从自己的 GPU 机器提供模型服务
- 你正在配置 LM Studio 或 OpenAI 兼容代理
- 你想从自己的 GPU 主机提供模型服务
- 你正在接入 LM Studio 或兼容 OpenAI 的代理
- 你需要最安全的本地模型指南
summary: 在本地 LLM 上运行 OpenClaw（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点）
title: 本地模型
x-i18n:
generated_at: "2026-02-03T07:48:15Z"
model: claude-opus-4-5
provider: pi
source_hash: f72b424c3d8986319868dc4c552596bcd599cc79fab5a57c14bf4f0695c39690
generated_at: "2026-03-16T06:22:54Z"
model: gpt-5.4
provider: openai
source_hash: 43ad6b91216e12be4d0c9395c981e0b5d8bd16ba4952efd02b7261052304a4ce
source_path: gateway/local-models.md
workflow: 15
---
# 本地模型
本地运行是可行的，但 OpenClaw 期望大上下文 + 强大的提示注入防御。小显存会截断上下文并泄露安全性。目标要高：**≥2 台满配 Mac Studio 或同等 GPU 配置（约 $30k+）**。单张 **24 GB** GPU 仅适用于较轻的提示，且延迟更高。使用**你能运行的最大/完整尺寸模型变体**；激进量化或"小型"检查点会增加提示注入风险（参见[安全](/gateway/security)）。
本地部署是可行的，但 OpenClaw 需要大上下文和对提示注入的强防御能力。小显卡会截断上下文并削弱安全性。目标要高：**至少 2 台满配 Mac Studio 或同等 GPU 设备（约 3 万美元以上）**。单张 **24 GB** GPU 仅适用于较轻的提示，且延迟更高。请使用**你能运行的最大 / 完整尺寸模型变体**；激进量化或“small”检查点会提高提示注入风险（见 [安全](/gateway/security)）。
## 推荐：LM Studio + MiniMax M2.1（Responses API，完整尺寸）
如果你想要摩擦最小的本地设置，请从 [Ollama](/providers/ollama) 和 `openclaw onboard` 开始。本页是面向更高端本地栈和自定义兼容 OpenAI 的本地服务器的偏好型指南。
当前最佳本地堆栈。在 LM Studio 中加载 MiniMax M2.1，启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 将推理与最终文本分开。
## 推荐：LM Studio + MiniMax M2.5（Responses API，完整尺寸）
当前最佳的本地栈。先在 LM Studio 中加载 MiniMax M2.5，启用本地服务器（默认 `http://127.0.0.1:1234`），然后使用 Responses API 将推理与最终文本分离。
```json5
{
agents: {
defaults: {
model: { primary: "lmstudio/minimax-m2.1-gs32" },
model: { primary: "lmstudio/minimax-m2.5-gs32" },
models: {
"anthropic/claude-opus-4-5": { alias: "Opus" },
"lmstudio/minimax-m2.1-gs32": { alias: "Minimax" },
"anthropic/claude-opus-4-6": { alias: "Opus" },
"lmstudio/minimax-m2.5-gs32": { alias: "Minimax" },
},
},
},
@ -42,8 +44,8 @@ x-i18n:
api: "openai-responses",
models: [
{
id: "minimax-m2.1-gs32",
name: "MiniMax M2.1 GS32",
id: "minimax-m2.5-gs32",
name: "MiniMax M2.5 GS32",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
@ -59,15 +61,15 @@ x-i18n:
**设置清单**
- 安装 LM Studio：https://lmstudio.ai
- 在 LM Studio 中，下载**可用的最大 MiniMax M2.1 构建**（避免"小型"/重度量化变体），启动服务器，确认 `http://127.0.0.1:1234/v1/models` 列出了它。
- 保持模型加载；冷加载会增加启动延迟。
- 如果你的 LM Studio 构建不同，调整 `contextWindow`/`maxTokens`。
- 对于 WhatsApp，坚持使用 Responses API，这样只发送最终文本。
- 安装 LM Studio：[https://lmstudio.ai](https://lmstudio.ai)
- 在 LM Studio 中，下载**可用的最大 MiniMax M2.5 构建版本**（避免 “small” / 重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 中列出了它。
- 保持模型处于已加载状态；冷加载会增加启动延迟。
- 如果你的 LM Studio 构建不同，请调整 `contextWindow` / `maxTokens`。
- 对于 WhatsApp，请坚持使用 Responses API，这样只会发送最终文本。
即使运行本地模型也要保持托管模型的配置；使用 `models.mode: "merge"` 以便备用方案保持可用。
即使在本地运行时，也要保留托管模型配置；使用 `models.mode: "merge"`，以便回退模型始终可用。
### 混合配置：托管为主，本地备用
### 混合配置：托管主模型，本地回退
```json5
{
@ -75,12 +77,12 @@ x-i18n:
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: ["lmstudio/minimax-m2.1-gs32", "anthropic/claude-opus-4-5"],
fallbacks: ["lmstudio/minimax-m2.5-gs32", "anthropic/claude-opus-4-6"],
},
models: {
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
"lmstudio/minimax-m2.1-gs32": { alias: "MiniMax Local" },
"anthropic/claude-opus-4-5": { alias: "Opus" },
"lmstudio/minimax-m2.5-gs32": { alias: "MiniMax Local" },
"anthropic/claude-opus-4-6": { alias: "Opus" },
},
},
},
@ -93,8 +95,8 @@ x-i18n:
api: "openai-responses",
models: [
{
id: "minimax-m2.1-gs32",
name: "MiniMax M2.1 GS32",
id: "minimax-m2.5-gs32",
name: "MiniMax M2.5 GS32",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
@ -108,18 +110,18 @@ x-i18n:
}
```
### 本地优先，托管作为安全网
### 本地优先，并保留托管安全网
交换主要和备用的顺序；保持相同的 providers 块和 `models.mode: "merge"`，这样当本地机器宕机时可以回退到 Sonnet 或 Opus。
交换主模型与回退模型的顺序；保留相同的 providers 块和 `models.mode: "merge"`，这样当本地主机不可用时，你仍然可以回退到 Sonnet 或 Opus。
### 区域托管/数据路由
### 区域托管 / 数据路由
- 托管的 MiniMax/Kimi/GLM 变体也存在于 OpenRouter 上，带有区域固定端点（例如，美国托管）。在那里选择区域变体以将流量保持在你选择的管辖区内，同时仍使用 `models.mode: "merge"` 作为 Anthropic/OpenAI 备用。
- 纯本地仍然是最强的隐私路径；当你需要提供商功能但又想控制数据流时，托管区域路由是折中方案。
- OpenRouter 上也提供托管版 MiniMax / Kimi / GLM 变体，并带有区域固定端点（例如托管在美国）。可以在那里选择区域变体，将流量保留在你选定的司法辖区内，同时继续使用 `models.mode: "merge"` 作为 Anthropic / OpenAI 回退。
- 纯本地仍然是最强的隐私方案；当你需要提供商功能但又想控制数据流向时，托管区域路由是折中方案。
## 其他 OpenAI 兼容本地代理
## 其他兼容 OpenAI 的本地代理
vLLM、LiteLLM、OAI-proxy 或自定义网关都可以工作，只要它们暴露 OpenAI 风格的 `/v1` 端点。用你的端点和模型 ID 替换上面的 provider 块：
只要暴露兼容 OpenAI 风格的 `/v1` 端点，vLLM、LiteLLM、OAI-proxy 或自定义网关都可以工作。将上面的 provider 块替换为你的端点和模型 ID：
```json5
{
@ -147,11 +149,11 @@ vLLM、LiteLLM、OAI-proxy 或自定义网关都可以工作，只要它们暴
}
```
保持 `models.mode: "merge"` 以便托管模型作为备用保持可用。
保留 `models.mode: "merge"`，这样托管模型仍可作为回退使用。
## 故障排除
- Gateway 网关能访问代理吗？`curl http://127.0.0.1:1234/v1/models`。
- LM Studio 模型卸载了？重新加载；冷启动是常见的"卡住"原因。
- 上下文错误？降低 `contextWindow` 或提高服务器限制。
- 安全：本地模型跳过提供商端过滤器；保持智能体范围窄并开启压缩以限制提示注入的影响范围。
- Gateway 网关能连接到代理吗？`curl http://127.0.0.1:1234/v1/models`
- LM Studio 模型已卸载？重新加载；冷启动是常见的“卡住”原因。
- 上下文错误？降低 `contextWindow` 或提高你的服务器限制。
- 安全性：本地模型会跳过提供商侧过滤；请保持智能体职责范围狭窄，并开启压缩，以限制提示注入的影响范围。

78
docs/zh-CN/gateway/multiple-gateways.md
View File

@ -1,35 +1,35 @@
---
read_when:
- 在同一台机器上运行多个 Gateway 网关
- 你需要每个 Gateway 网关有隔离的配置/状态/端口
summary: 在同一主机上运行多个 OpenClaw Gateway 网关（隔离、端口和配置文件）
title: 多 Gateway 网关
- 你需要为每个 Gateway 网关隔离配置/状态/端口
summary: 在一台主机上运行多个 OpenClaw Gateway 网关（隔离、端口和配置档案）
title: 多个 Gateway 网关
x-i18n:
generated_at: "2026-02-03T07:48:13Z"
model: claude-opus-4-5
provider: pi
source_hash: 09b5035d4e5fb97c8d4596f7e23dea67224dad3b6d9e2c37ecb99840f28bd77d
generated_at: "2026-03-16T06:23:07Z"
model: gpt-5.4
provider: openai
source_hash: 98c14bed7b7447481325d60ac379846ae379326400c4b0ed7f8d320ad8c50080
source_path: gateway/multiple-gateways.md
workflow: 15
---
# 多 Gateway 网关（同一主机）
# 多个 Gateway 网关（同一主机）
大多数设置应该使用单个 Gateway 网关，因为一个 Gateway 网关可以处理多个消息连接和智能体。如果你需要更强的隔离或冗余（例如，救援机器人），请使用隔离的配置文件/端口运行多个 Gateway 网关。
大多数设置应使用一个 Gateway 网关，因为单个 Gateway 网关可以处理多个消息连接和智能体。如果你需要更强的隔离或冗余（例如救援机器人），请运行使用隔离配置档案/端口的独立 Gateway 网关。
## 隔离检查清单（必需）
- `OPENCLAW_CONFIG_PATH` — 每个实例的配置文件
- `OPENCLAW_STATE_DIR` — 每个实例的会话、凭证、缓存
- `agents.defaults.workspace` — 每个实例的工作区根目录
- `OPENCLAW_CONFIG_PATH` — 每个实例单独的配置文件
- `OPENCLAW_STATE_DIR` — 每个实例单独的会话、凭证、缓存
- `agents.defaults.workspace` — 每个实例单独的工作区根目录
- `gateway.port`（或 `--port`）— 每个实例唯一
- 派生端口（浏览器/画布）不得重叠
- 派生端口（browser/canvas）不得重叠
如果这些是共享的，你将遇到配置竞争和端口冲突。
如果这些被共享，你会遇到配置竞争和端口冲突。
## 推荐：配置文件（`--profile`）
## 推荐：配置档案（`--profile`）
配置文件自动限定 `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH` 范围并为服务名称添加后缀。
配置档案会自动限定 `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH`，并为服务名称添加后缀。
```bash
# main
@ -41,7 +41,7 @@ openclaw --profile rescue setup
openclaw --profile rescue gateway --port 19001
```
按配置文件的服务：
每个配置档案的服务：
```bash
openclaw --profile main gateway install
@ -50,34 +50,34 @@ openclaw --profile rescue gateway install
## 救援机器人指南
在同一主机上运行第二个 Gateway 网关，使用独立的：
在同一主机上运行第二个 Gateway 网关，并为它单独设置：
- 配置文件/配置
- 配置档案/配置
- 状态目录
- 工作区
- 基础端口（加上派生端口）
- 基础端口（以及派生端口）
这使救援机器人与主机器人隔离，以便在主机器人宕机时可以调试或应用配置更改。
这样可以将救援机器人与主机器人隔离，因此当主机器人宕机时，它仍可用于调试或应用配置更改。
端口间距：在基础端口之间至少留出 20 个端口，这样派生的浏览器/画布/CDP 端口永远不会冲突。
端口间距：基础端口之间至少保留 20 个端口，以确保派生的 browser/canvas/CDP 端口永不冲突。
### 如何安装（救援机器人）
```bash
# 主机器人（现有或新建，不带 --profile 参数）
# Main bot（现有或全新，不带 --profile 参数）
# 运行在端口 18789 + Chrome CDC/Canvas/... 端口
openclaw onboard
openclaw gateway install
# 救援机器人（隔离的配置文件 + 端口）
# Rescue bot（隔离的配置档案 + 端口）
openclaw --profile rescue onboard
# 注意：
# - 工作区名称默认会添加 -rescue 后缀
# - 端口应至少为 18789 + 20 个端口，
# 最好选择完全不同的基础端口，如 19789，
# - 其余的新手引导与正常相同
# 说明：
# - 工作区名称默认会追加 -rescue 后缀
# - 端口至少应为 18789 + 20 个端口，
# 最好选择完全不同的基础端口，例如 19789，
# - 其余新手引导与正常情况相同
# 安装服务（如果在新手引导期间没有自动完成）
# 安装服务（如果设置期间未自动完成）
openclaw --profile rescue gateway install
```
@ -85,18 +85,18 @@ openclaw --profile rescue gateway install
基础端口 = `gateway.port`（或 `OPENCLAW_GATEWAY_PORT` / `--port`）。
- 浏览器控制服务端口 = 基础 + 2（仅 loopback）
- `canvasHost.port = 基础 + 4`
- 浏览器配置文件 CDP 端口从 `browser.controlPort + 9 .. + 108` 自动分配
- browser 控制服务端口 = 基础端口 + 2（仅 loopback）
- canvas host 由 Gateway 网关 HTTP 服务器提供（与 `gateway.port` 使用相同端口）
- Browser profile CDP 端口会从 `browser.controlPort + 9 .. + 108` 自动分配
如果你在配置或环境变量中覆盖了这些，必须确保每个实例都唯一。
如果你在配置或环境变量中覆盖了其中任何一个，必须确保它们在每个实例之间保持唯一。
## 浏览器/CDP 注意事项（常见陷阱）
## Browser/CDP 说明（常见陷阱）
- **不要**在多个实例上将 `browser.cdpUrl` 固定为相同的值。
- 每个实例需要自己的浏览器控制端口和 CDP 范围（从其 Gateway 网关端口派生）。
- 如果你需要显式的 CDP 端口，请为每个实例设置 `browser.profiles.<name>.cdpPort`。
- 远程 Chrome：使用 `browser.profiles.<name>.cdpUrl`（每个配置文件，每个实例）。
- **不要**在多个实例上将 `browser.cdpUrl` 固定为相同值。
- 每个实例都需要自己的 browser 控制端口和 CDP 范围（从其 Gateway 网关端口派生）。
- 如果你需要显式 CDP 端口，请为每个实例设置 `browser.profiles.<name>.cdpPort`。
- 远程 Chrome：使用 `browser.profiles.<name>.cdpUrl`（按配置档案、按实例设置）。
## 手动环境变量示例

4
docs/zh-CN/help/faq.md
View File

@ -2,10 +2,10 @@
summary: 关于 OpenClaw 安装、配置和使用的常见问题
title: 常见问题
x-i18n:
generated_at: "2026-03-16T01:39:16Z"
generated_at: "2026-03-16T06:52:18Z"
model: claude-opus-4-5
provider: pi
source_hash: 6e6a4a63fb73dca24dbe77928b51c6b2e5d51ec883fb36c64e2e40ef027050e9
source_hash: 94f7c6ea1024d5606379ce80d65a006b3acc12a963d57ca2333fcee3e5a31872
source_path: help/faq.md
workflow: 15
---

68
docs/zh-CN/install/exe-dev.md
View File

@ -1,50 +1,51 @@
---
read_when:
- 你想要一个便宜的常驻 Linux 主机来运行 Gateway 网关
- 你想要远程控制 UI 访问而无需运行自己的 VPS
- 你想为 Gateway 网关使用一台便宜且始终在线的 Linux 主机
- 你想在不自行运行 VPS 的情况下远程访问控制 UI
summary: 在 exe.dev 上运行 OpenClaw Gateway 网关（VM + HTTPS 代理）以实现远程访问
title: exe.dev
x-i18n:
generated_at: "2026-02-03T07:51:36Z"
model: claude-opus-4-5
provider: pi
source_hash: 8d57ee7dd6029f0b778465c147092b824a0f1b0680af13032aaf116ff3d4d671
source_path: platforms/exe-dev.md
generated_at: "2026-03-16T06:23:23Z"
model: gpt-5.4
provider: openai
source_hash: 3c90f57e37145333429328477a3e12306586aa53283127daec75e065dbb85e39
source_path: install/exe-dev.md
workflow: 15
---
# exe.dev
目标：OpenClaw Gateway 网关运行在 exe.dev VM 上，可从你的笔记本电脑通过以下地址访问：`https://<vm-name>.exe.xyz`
目标：让 OpenClaw Gateway 网关运行在 exe.dev VM 上，并且可通过你的笔记本电脑访问：`https://<vm-name>.exe.xyz`
本页假设使用 exe.dev 的默认 **exeuntu** 镜像。如果你选择了不同的发行版，请相应地映射软件包。
本页假设你使用的是 exe.dev 默认的 **exeuntu** 镜像。如果你选择了不同的发行版，请相应调整软件包。
## 新手快速路径
## 面向初学者的快速路径
1. [https://exe.new/openclaw](https://exe.new/openclaw)
2. 根据需要填写你的认证密钥/令牌
3. 点击 VM 旁边的"Agent"，然后等待...
2. 根据需要填写你的身份验证密钥/令牌
3. 点击你的 VM 旁边的 “Agent”，然后等待……
4. ???
5. 完成
5. 成功
## 你需要什么
## 你需要准备的内容
- exe.dev 账户
- `ssh exe.dev` 访问 [exe.dev](https://exe.dev) 虚拟机（可选）
- 对 [exe.dev](https://exe.dev) 虚拟机的 `ssh exe.dev` 访问权限（可选）
## 使用 Shelley 自动安装
Shelley，[exe.dev](https://exe.dev) 的智能体，可以使用我们的提示立即安装 OpenClaw。使用的提示如下：
Shelley 是 [exe.dev](https://exe.dev) 的智能体，可以使用我们的提示词立即安装 OpenClaw。
使用的提示词如下：
```
Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-interactive and accept-risk flags for openclaw onboarding. Add the supplied auth or token as needed. Configure nginx to forward from the default port 18789 to the root location on the default enabled site config, making sure to enable Websocket support. Pairing is done by "openclaw devices list" and "openclaw device approve <request id>". Make sure the dashboard shows that OpenClaw's health is OK. exe.dev handles forwarding from port 8000 to port 80/443 and HTTPS for us, so the final "reachable" should be <vm-name>.exe.xyz, without port specification.
Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-interactive and accept-risk flags for openclaw onboarding. Add the supplied auth or token as needed. Configure nginx to forward from the default port 18789 to the root location on the default enabled site config, making sure to enable Websocket support. Pairing is done by "openclaw devices list" and "openclaw devices approve <request id>". Make sure the dashboard shows that OpenClaw's health is OK. exe.dev handles forwarding from port 8000 to port 80/443 and HTTPS for us, so the final "reachable" should be <vm-name>.exe.xyz, without port specification.
```
## 手动安装
## 1) 创建 VM
## 1）创建 VM
从你的设备：
在你的设备上运行：
```bash
ssh exe.dev new
@ -56,16 +57,16 @@ ssh exe.dev new
ssh <vm-name>.exe.xyz
```
提示：保持此 VM **有状态**。OpenClaw 在 `~/.openclaw/` 和 `~/.openclaw/workspace/` 下存储状态。
提示：请让这个 VM 保持**有状态**。OpenClaw 会将状态存储在 `~/.openclaw/` 和 `~/.openclaw/workspace/` 下。
## 2) 安装先决条件（在 VM 上）
## 2）安装前置依赖（在 VM 上）
```bash
sudo apt-get update
sudo apt-get install -y git curl jq ca-certificates openssl
```
## 3) 安装 OpenClaw
## 3）安装 OpenClaw
运行 OpenClaw 安装脚本：
@ -73,9 +74,9 @@ sudo apt-get install -y git curl jq ca-certificates openssl
curl -fsSL https://openclaw.ai/install.sh | bash
```
## 4) 设置 nginx 将 OpenClaw 代理到端口 8000
## 4）设置 nginx，将 OpenClaw 代理到端口 8000
编辑 `/etc/nginx/sites-enabled/default`：
编辑 `/etc/nginx/sites-enabled/default`，内容如下：
```
server {
@ -90,30 +91,35 @@ server {
proxy_pass http://127.0.0.1:18789;
proxy_http_version 1.1;
# WebSocket 支持
# WebSocket support
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 标准代理头
# Standard proxy headers
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 长连接超时设置
# Timeout settings for long-lived connections
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
}
}
```
## 5) 访问 OpenClaw 并授予权限
## 5）访问 OpenClaw 并授予权限
访问 `https://<vm-name>.exe.xyz/?token=YOUR-TOKEN-FROM-TERMINAL`（参阅新手引导中的控制 UI 输出）。使用 `openclaw devices list` 和 `openclaw devices approve <requestId>` 批准设备。如有疑问，从浏览器使用 Shelley！
访问 `https://<vm-name>.exe.xyz/`（请查看新手引导输出中的控制 UI）。如果提示进行身份验证，请粘贴 VM 上的
`gateway.auth.token` 中的令牌（可通过 `openclaw config get gateway.auth.token` 获取，或使用
`openclaw doctor --generate-gateway-token` 生成）。使用 `openclaw devices list` 和
`openclaw devices approve <requestId>` 批准设备。如果拿不准，请在浏览器中使用 Shelley！
## 远程访问
远程访问由 [exe.dev](https://exe.dev) 的认证处理。默认情况下，来自端口 8000 的 HTTP 流量通过电子邮件认证转发到 `https://<vm-name>.exe.xyz`。
远程访问由 [exe.dev](https://exe.dev) 的身份验证处理。默认情况下，
来自端口 8000 的 HTTP 流量会被转发到 `https://<vm-name>.exe.xyz`，
并使用电子邮件身份验证。
## 更新
@ -124,4 +130,4 @@ openclaw gateway restart
openclaw health
```
指南：[更新](/install/updating)
指南：[Updating](/install/updating)

296
docs/zh-CN/install/index.md
View File

@ -1,170 +1,204 @@
---
read_when:
- 安装 OpenClaw
- 你想从 GitHub 安装
summary: 安装 OpenClaw（推荐安装器、全局安装或从源代码安装）
- 你需要一种不同于“入门指南”快速开始的安装方式
- 你想部署到云平台
- 你需要更新、迁移或卸载
summary: 安装 OpenClaw —— 安装脚本、npm/pnpm、从源码、Docker 等
title: 安装
x-i18n:
generated_at: "2026-02-03T10:07:43Z"
model: claude-opus-4-5
provider: pi
source_hash: b26f48c116c26c163ee0090fb4c3e29622951bd427ecaeccba7641d97cfdf17a
generated_at: "2026-03-16T06:23:36Z"
model: gpt-5.4
provider: openai
source_hash: 14b80b6176b2a4ff5c60aad2db88460d8d980bd416faaa3103b38d90521496af
source_path: install/index.md
workflow: 15
---
# 安装
除非有特殊原因，否则请使用安装器。它会设置 CLI 并运行新手引导。
## 快速安装（推荐）
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
Windows（PowerShell）：
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
下一步（如果你跳过了新手引导）：
```bash
openclaw onboard --install-daemon
```
已经按照 [入门指南](/start/getting-started) 操作过了吗？那你已经准备好了 —— 本页适用于其他安装方法、特定平台说明以及维护操作。
## 系统要求
- **Node >=22**
- macOS、Linux 或通过 WSL2 的 Windows
- `pnpm` 仅在从源代码构建时需要
- **[Node 24（推荐）](/install/node)**（出于兼容性考虑，仍支持 Node 22 LTS，目前为 `22.16+`；如果缺失，[安装脚本](#install-methods) 会安装 Node 24）
- macOS、Linux 或 Windows
- 仅当你从源码构建时需要 `pnpm`
## 选择安装路径
<Note>
在 Windows 上，我们强烈建议你在 [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) 下运行 OpenClaw。
</Note>
### 1）安装器脚本（推荐）
## 安装方法
通过 npm 全局安装 `openclaw` 并运行新手引导。
<Tip>
**安装脚本** 是安装 OpenClaw 的推荐方式。它会一步完成 Node 检测、安装和新手引导。
</Tip>
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
<Warning>
对于 VPS/云主机，尽量避免使用第三方“一键式”市场镜像。优先选择干净的基础 OS 镜像（例如 Ubuntu LTS），然后使用安装脚本自行安装 OpenClaw。
</Warning>
安装器标志：
<AccordionGroup>
<Accordion title="安装脚本" icon="rocket" defaultOpen>
下载 CLI，通过 npm 全局安装，并启动设置向导。
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
```
<Tabs>
<Tab title="macOS / Linux / WSL2">
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
</Tab>
<Tab title="Windows (PowerShell)">
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
</Tab>
</Tabs>
详情：[安装器内部原理](/install/installer)。
就这样 —— 脚本会处理 Node 检测、安装和新手引导。
非交互式（跳过新手引导）：
如果要跳过新手引导，只安装二进制文件：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
```
<Tabs>
<Tab title="macOS / Linux / WSL2">
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
```
</Tab>
<Tab title="Windows (PowerShell)">
```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
```
</Tab>
</Tabs>
### 2）全局安装（手动）
所有标志、环境变量以及 CI/自动化选项，请参阅 [Installer internals](/install/installer)。
如果你已经有 Node：
</Accordion>
```bash
npm install -g openclaw@latest
```
<Accordion title="npm / pnpm" icon="package">
如果你已经自行管理 Node，我们推荐使用 Node 24。出于兼容性考虑，OpenClaw 仍支持 Node 22 LTS，目前为 `22.16+`：
如果你全局安装了 libvips（macOS 上通过 Homebrew 安装很常见）且 `sharp` 安装失败，请强制使用预构建二进制文件：
<Tabs>
<Tab title="npm">
```bash
npm install -g openclaw@latest
openclaw onboard --install-daemon
```
```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
```
<Accordion title="sharp 构建错误？">
如果你全局安装了 libvips（在 macOS 上通过 Homebrew 很常见），并且 `sharp` 失败，请强制使用预构建二进制文件：
如果你看到 `sharp: Please add node-gyp to your dependencies`，要么安装构建工具（macOS：Xcode CLT + `npm install -g node-gyp`），要么使用上面的 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 变通方法来跳过原生构建。
```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
```
或使用 pnpm：
如果你看到 `sharp: Please add node-gyp to your dependencies`，请安装构建工具链（macOS：Xcode CLT + `npm install -g node-gyp`），或者使用上面的环境变量。
</Accordion>
</Tab>
<Tab title="pnpm">
```bash
pnpm add -g openclaw@latest
pnpm approve-builds -g # 批准 openclaw、node-llama-cpp、sharp 等
openclaw onboard --install-daemon
```
```bash
pnpm add -g openclaw@latest
pnpm approve-builds -g # 批准 openclaw、node-llama-cpp、sharp 等
pnpm add -g openclaw@latest # 重新运行以执行 postinstall 脚本
```
<Note>
`pnpm` 要求对带有构建脚本的包进行显式批准。首次安装出现 “Ignored build scripts” 警告后，运行 `pnpm approve-builds -g` 并选择列出的包。
</Note>
</Tab>
</Tabs>
pnpm 需要显式批准带有构建脚本的包。在首次安装显示"Ignored build scripts"警告后，运行 `pnpm approve-builds -g` 并选择列出的包，然后重新运行安装以执行 postinstall 脚本。
想通过包管理器安装当前 GitHub `main` 分支最新版本？
然后：
```bash
npm install -g github:openclaw/openclaw#main
```
```bash
openclaw onboard --install-daemon
```
```bash
pnpm add -g github:openclaw/openclaw#main
```
### 3）从源代码（贡献者/开发）
</Accordion>
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
openclaw onboard --install-daemon
```
<Accordion title="从源码" icon="github">
适用于贡献者或任何想从本地检出运行的人。
提示：如果你还没有全局安装，请通过 `pnpm openclaw ...` 运行仓库命令。
<Steps>
<Step title="克隆并构建">
克隆 [OpenClaw 仓库](https://github.com/openclaw/openclaw) 并构建：
### 4）其他安装选项
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
```
</Step>
<Step title="链接 CLI">
让 `openclaw` 命令在全局可用：
- Docker：[Docker](/install/docker)
- Nix：[Nix](/install/nix)
- Ansible：[Ansible](/install/ansible)
- Bun（仅 CLI）：[Bun](/install/bun)
```bash
pnpm link --global
```
或者，你也可以跳过链接，直接在仓库内通过 `pnpm openclaw ...` 运行命令。
</Step>
<Step title="运行新手引导">
```bash
openclaw onboard --install-daemon
```
</Step>
</Steps>
更深入的开发工作流请参阅 [Setup](/start/setup)。
</Accordion>
</AccordionGroup>
## 其他安装方法
<CardGroup cols={2}>
<Card title="Docker" href="/install/docker" icon="container">
容器化或无头部署。
</Card>
<Card title="Podman" href="/install/podman" icon="container">
无 root 容器：先运行一次 `setup-podman.sh`，然后运行启动脚本。
</Card>
<Card title="Nix" href="/install/nix" icon="snowflake">
通过 Nix 进行声明式安装。
</Card>
<Card title="Ansible" href="/install/ansible" icon="server">
自动化批量配置。
</Card>
<Card title="Bun" href="/install/bun" icon="zap">
通过 Bun 运行时进行仅 CLI 使用。
</Card>
</CardGroup>
## 安装后
- 运行新手引导：`openclaw onboard --install-daemon`
- 快速检查：`openclaw doctor`
- 检查 Gateway 网关健康状态：`openclaw status` + `openclaw health`
- 打开仪表板：`openclaw dashboard`
## 安装方式：npm vs git（安装器）
安装器支持两种方式：
- `npm`（默认）：`npm install -g openclaw@latest`
- `git`：从 GitHub 克隆/构建并从源代码 checkout 运行
### CLI 标志
验证一切是否正常工作：
```bash
# 显式 npm
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
# 从 GitHub 安装（源代码 checkout）
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
openclaw doctor # 检查配置问题
openclaw status # Gateway 网关状态
openclaw dashboard # 打开浏览器 UI
```
常用标志：
如果你需要自定义运行时路径，请使用：
- `--install-method npm|git`
- `--git-dir <path>`（默认：`~/openclaw`）
- `--no-git-update`（使用现有 checkout 时跳过 `git pull`）
- `--no-prompt`（禁用提示；CI/自动化中必需）
- `--dry-run`（打印将要执行的操作；不做任何更改）
- `--no-onboard`（跳过新手引导）
- `OPENCLAW_HOME` 用于基于主目录的内部路径
- `OPENCLAW_STATE_DIR` 用于可变状态位置
- `OPENCLAW_CONFIG_PATH` 用于配置文件位置
### 环境变量
有关优先级和完整细节，请参阅 [Environment vars](/help/environment)。
等效的环境变量（对自动化有用）：
## 故障排除：找不到 `openclaw`
- `OPENCLAW_INSTALL_METHOD=git|npm`
- `OPENCLAW_GIT_DIR=...`
- `OPENCLAW_GIT_UPDATE=0|1`
- `OPENCLAW_NO_PROMPT=1`
- `OPENCLAW_DRY_RUN=1`
- `OPENCLAW_NO_ONBOARD=1`
- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1`（默认：`1`；避免 `sharp` 针对系统 libvips 构建）
## 故障排除：找不到 `openclaw`（PATH）
快速诊断：
<Accordion title="PATH 诊断与修复">
快速诊断：
```bash
node -v
@ -173,21 +207,29 @@ npm prefix -g
echo "$PATH"
```
如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不**在 `echo "$PATH"` 的输出中，你的 shell 无法找到全局 npm 二进制文件（包括 `openclaw`）。
如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不在**你的 `$PATH` 中，那么你的 shell 就找不到全局 npm 二进制文件（包括 `openclaw`）。
修复：将其添加到你的 shell 启动文件（zsh：`~/.zshrc`，bash：`~/.bashrc`）：
修复方法 —— 将其添加到你的 shell 启动文件（`~/.zshrc` 或 `~/.bashrc`）中：
```bash
# macOS / Linux
export PATH="$(npm prefix -g)/bin:$PATH"
```
在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH。
在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH 中。
然后打开新终端（或在 zsh 中执行 `rehash` / 在 bash 中执行 `hash -r`）。
然后打开一个新的终端（或者在 zsh 中运行 `rehash`，在 bash 中运行 `hash -r`）。
</Accordion>
## 更新/卸载
## 更新 / 卸载
- 更新：[更新](/install/updating)
- 迁移到新机器：[迁移](/install/migrating)
- 卸载：[卸载](/install/uninstall)
<CardGroup cols={3}>
<Card title="更新" href="/install/updating" icon="refresh-cw">
让 OpenClaw 保持最新。
</Card>
<Card title="迁移" href="/install/migrating" icon="arrow-right">
迁移到新机器。
</Card>
<Card title="卸载" href="/install/uninstall" icon="trash-2">
完全移除 OpenClaw。
</Card>
</CardGroup>

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

@ -1,128 +1,422 @@
---
read_when:
- 你想了解 `openclaw.ai/install.sh` 的工作机制
- 你想自动化安装（CI / 无头环境）
- 你想了解 `openclaw.ai/install.sh`
- 你想自动化安装（CI / 无头）
- 你想从 GitHub 检出安装
summary: 安装器脚本的工作原理（install.sh + install-cli.sh）、参数和自动化
summary: 安装脚本的工作原理（install.sh、install-cli.sh、install.ps1）、标志和自动化
title: 安装器内部机制
x-i18n:
generated_at: "2026-02-01T21:07:55Z"
model: claude-opus-4-5
provider: pi
source_hash: 9e0a19ecb5da0a395030e1ccf0d4bedf16b83946b3432c5399d448fe5d298391
generated_at: "2026-03-16T06:24:11Z"
model: gpt-5.4
provider: openai
source_hash: e389fa04140ecc98b7e83330d0d467165b23bd22e31807bbd36963c87394ddc4
source_path: install/installer.md
workflow: 14
workflow: 15
---
# 安装器内部机制
OpenClaw 提供两个安装器脚本（托管在 `openclaw.ai`）：
OpenClaw 提供三个安装脚本，由 `openclaw.ai` 提供。
- `https://openclaw.ai/install.sh` — "推荐"安装器（默认全局 npm 安装；也可从 GitHub 检出安装）
- `https://openclaw.ai/install-cli.sh` — 无需 root 权限的 CLI 安装器（安装到带有独立 Node 的前缀目录）
- `https://openclaw.ai/install.ps1` — Windows PowerShell 安装器（默认 npm；可选 git 安装）
| 脚本 | 平台 | 功能 |
| ---------------------------------- | --------------------- | ----------------------------------------------------------------------------- |
| [`install.sh`](#installsh) | macOS / Linux / WSL | 如有需要则安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行新手引导。 |
| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL | 将 Node + OpenClaw 安装到本地前缀（`~/.openclaw`）中。无需 root。 |
| [`install.ps1`](#installps1) | Windows（PowerShell） | 如有需要则安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行新手引导。 |
查看当前参数/行为，运行：
## 快速命令
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
```
<Tabs>
<Tab title="install.sh">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
```
Windows (PowerShell) 帮助：
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help
```
```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -?
```
</Tab>
<Tab title="install-cli.sh">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
```
如果安装器完成但在新终端中找不到 `openclaw`，通常是 Node/npm PATH 问题。参见：[安装](/install#nodejs--npm-path-sanity)。
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help
```
## install.sh（推荐）
</Tab>
<Tab title="install.ps1">
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
功能概述：
```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
```
- 检测操作系统（macOS / Linux / WSL）。
- 确保 Node.js **22+**（macOS 通过 Homebrew；Linux 通过 NodeSource）。
- 选择安装方式：
- `npm`（默认）：`npm install -g openclaw@latest`
- `git`：克隆/构建源码检出并安装包装脚本
- 在 Linux 上：必要时将 npm 前缀切换到 `~/.npm-global`，以避免全局 npm 权限错误。
- 如果是升级现有安装：运行 `openclaw doctor --non-interactive`（尽力执行）。
- 对于 git 安装：安装/更新后运行 `openclaw doctor --non-interactive`（尽力执行）。
- 通过默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 来缓解 `sharp` 原生安装问题（避免使用系统 libvips 编译）。
</Tab>
</Tabs>
如果你*希望* `sharp` 链接到全局安装的 libvips（或你正在调试），请设置：
<Note>
如果安装成功但在新终端中找不到 `openclaw`，请参见 [Node.js 故障排除](/install/node#troubleshooting)。
</Note>
```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash
```
---
### 可发现性 / "git 安装"提示
## install.sh
如果你在**已有的 OpenClaw 源码检出目录中**运行安装器（通过 `package.json` + `pnpm-workspace.yaml` 检测），它会提示：
<Tip>
推荐用于大多数 macOS/Linux/WSL 上的交互式安装。
</Tip>
- 更新并使用此检出（`git`）
- 或迁移到全局 npm 安装（`npm`）
### 流程（install.sh）
在非交互式上下文中（无 TTY / `--no-prompt`），你必须传入 `--install-method git|npm`（或设置 `OPENCLAW_INSTALL_METHOD`），否则脚本将以退出码 `2` 退出。
<Steps>
<Step title="检测操作系统">
支持 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.16+`。
</Step>
<Step title="确保安装 Git">
如果缺少 Git，则安装它。
</Step>
<Step title="安装 OpenClaw">
- `npm` 方法（默认）：全局 npm 安装
- `git` 方法：克隆/更新仓库，使用 pnpm 安装依赖，构建，然后将包装器安装到 `~/.local/bin/openclaw`
</Step>
<Step title="安装后任务">
- 在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力而为）
- 在适当情况下尝试运行新手引导（有 TTY、未禁用新手引导，并且 bootstrap/配置检查通过）
- 默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1`
</Step>
</Steps>
### 为什么需要 Git
### 源码检出检测
`--install-method git` 路径（克隆 / 拉取）需要 Git。
如果在 OpenClaw 检出目录中运行（`package.json` + `pnpm-workspace.yaml`），脚本会提供：
对于 `npm` 安装，Git *通常*不是必需的，但某些环境仍然需要它（例如通过 git URL 获取软件包或依赖时）。安装器目前会确保 Git 存在，以避免在全新发行版上出现 `spawn git ENOENT` 错误。
- 使用检出目录（`git`），或
- 使用全局安装（`npm`）
### 为什么在全新 Linux 上 npm 会报 `EACCES`
如果没有可用 TTY 且未设置安装方法，它将默认使用 `npm` 并发出警告。
在某些 Linux 设置中（尤其是通过系统包管理器或 NodeSource 安装 Node 后），npm 的全局前缀指向 root 拥有的位置。此时 `npm install -g ...` 会报 `EACCES` / `mkdir` 权限错误。
对于无效的方法选择或无效的 `--install-method` 值，脚本会以退出码 `2` 退出。
`install.sh` 通过将前缀切换到以下位置来缓解此问题：
### 示例（install.sh）
- `~/.npm-global`（并在存在时将其添加到 `~/.bashrc` / `~/.zshrc` 的 `PATH` 中）
<Tabs>
<Tab title="默认">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
```
</Tab>
<Tab title="跳过新手引导">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard
```
</Tab>
<Tab title="Git 安装">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
```
</Tab>
<Tab title="通过 npm 安装 GitHub main">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --version main
```
</Tab>
<Tab title="试运行">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run
```
</Tab>
</Tabs>
## install-cli.sh（无需 root 权限的 CLI 安装器）
<AccordionGroup>
<Accordion title="标志参考">
此脚本将 `openclaw` 安装到前缀目录（默认：`~/.openclaw`），同时在该前缀下安装专用的 Node 运行时，因此可以在不想改动系统 Node/npm 的机器上使用。
| 标志 | 说明 |
| ------------------------------------- | ------------------------------------------------- |
| `--install-method npm\|git` | 选择安装方法（默认：`npm`）。别名：`--method` |
| `--npm` | npm 方法快捷方式 |
| `--git` | git 方法快捷方式。别名：`--github` |
| `--version <version\|dist-tag\|spec>` | npm 版本、dist-tag 或包规范（默认：`latest`） |
| `--beta` | 如有可用则使用 beta dist-tag，否则回退到 `latest` |
| `--git-dir <path>` | 检出目录（默认：`~/openclaw`）。别名：`--dir` |
| `--no-git-update` | 对现有检出跳过 `git pull` |
| `--no-prompt` | 禁用提示 |
| `--no-onboard` | 跳过新手引导 |
| `--onboard` | 启用新手引导 |
| `--dry-run` | 打印操作但不应用更改 |
| `--verbose` | 启用调试输出（`set -x`、npm notice 级别日志） |
| `--help` | 显示用法（`-h`） |
帮助：
</Accordion>
```bash
curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help
```
<Accordion title="环境变量参考">
## install.ps1（Windows PowerShell）
| 变量 | 说明 |
| ------------------------------------------------------- | ------------------------------------ |
| `OPENCLAW_INSTALL_METHOD=git\|npm` | 安装方法 |
| `OPENCLAW_VERSION=latest\|next\|main\|<semver>\|<spec>` | npm 版本、dist-tag 或包规范 |
| `OPENCLAW_BETA=0\|1` | 如有可用则使用 beta |
| `OPENCLAW_GIT_DIR=<path>` | 检出目录 |
| `OPENCLAW_GIT_UPDATE=0\|1` | 切换 git 更新 |
| `OPENCLAW_NO_PROMPT=1` | 禁用提示 |
| `OPENCLAW_NO_ONBOARD=1` | 跳过新手引导 |
| `OPENCLAW_DRY_RUN=1` | 试运行模式 |
| `OPENCLAW_VERBOSE=1` | 调试模式 |
| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm 日志级别 |
| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | 控制 sharp/libvips 行为（默认：`1`） |
功能概述：
</Accordion>
</AccordionGroup>
- 确保 Node.js **22+**（winget/Chocolatey/Scoop 或手动安装）。
- 选择安装方式：
- `npm`（默认）：`npm install -g openclaw@latest`
- `git`：克隆/构建源码检出并安装包装脚本
- 在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力执行）。
---
示例：
## install-cli.sh
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
<Info>
适用于你希望所有内容都放在本地前缀（默认 `~/.openclaw`）下，并且不依赖系统 Node 的环境。
</Info>
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git
```
### 流程（install-cli.sh）
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw"
```
<Steps>
<Step title="安装本地 Node 运行时">
将固定的受支持 Node tarball（当前默认 `22.22.0`）下载到 `<prefix>/tools/node-v<version>`，并验证 SHA-256。
</Step>
<Step title="确保安装 Git">
如果缺少 Git，则尝试在 Linux 上通过 apt/dnf/yum 安装，或在 macOS 上通过 Homebrew 安装。
</Step>
<Step title="在前缀下安装 OpenClaw">
使用 `--prefix <prefix>` 通过 npm 安装，然后将包装器写入 `<prefix>/bin/openclaw`。
</Step>
</Steps>
环境变量：
### 示例（install-cli.sh）
- `OPENCLAW_INSTALL_METHOD=git|npm`
- `OPENCLAW_GIT_DIR=...`
<Tabs>
<Tab title="默认">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
```
</Tab>
<Tab title="自定义前缀 + 版本">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest
```
</Tab>
<Tab title="自动化 JSON 输出">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
```
</Tab>
<Tab title="运行新手引导">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard
```
</Tab>
</Tabs>
Git 要求：
<AccordionGroup>
<Accordion title="标志参考">
如果你选择 `-InstallMethod git` 但未安装 Git，安装器会打印 Git for Windows 的链接（`https://git-scm.com/download/win`）并退出。
| 标志 | 说明 |
| ---------------------- | ---------------------------------------------------------------------- |
| `--prefix <path>` | 安装前缀（默认：`~/.openclaw`） |
| `--version <ver>` | OpenClaw 版本或 dist-tag（默认：`latest`） |
| `--node-version <ver>` | Node 版本（默认：`22.22.0`） |
| `--json` | 输出 NDJSON 事件 |
| `--onboard` | 安装后运行 `openclaw onboard` |
| `--no-onboard` | 跳过新手引导（默认） |
| `--set-npm-prefix` | 在 Linux 上，如果当前前缀不可写，则强制将 npm 前缀设为 `~/.npm-global` |
| `--help` | 显示用法（`-h`） |
常见 Windows 问题：
</Accordion>
- **npm error spawn git / ENOENT**：安装 Git for Windows 并重新打开 PowerShell，然后重新运行安装器。
- **"openclaw" 不是可识别的命令**：你的 npm 全局 bin 文件夹不在 PATH 中。大多数系统使用 `%AppData%\\npm`。你也可以运行 `npm config get prefix` 并将 `\\bin` 添加到 PATH，然后重新打开 PowerShell。
<Accordion title="环境变量参考">
| 变量 | 说明 |
| ------------------------------------------- | ------------------------------------------------------ |
| `OPENCLAW_PREFIX=<path>` | 安装前缀 |
| `OPENCLAW_VERSION=<ver>` | OpenClaw 版本或 dist-tag |
| `OPENCLAW_NODE_VERSION=<ver>` | Node 版本 |
| `OPENCLAW_NO_ONBOARD=1` | 跳过新手引导 |
| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm 日志级别 |
| `OPENCLAW_GIT_DIR=<path>` | 旧版清理查找路径（用于删除旧的 `Peekaboo` 子模块检出） |
| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | 控制 sharp/libvips 行为（默认：`1`） |
</Accordion>
</AccordionGroup>
---
## install.ps1
### 流程（install.ps1）
<Steps>
<Step title="确保 PowerShell + Windows 环境">
需要 PowerShell 5+。
</Step>
<Step title="默认确保使用 Node.js 24">
如果缺少，则依次尝试通过 winget、Chocolatey、Scoop 安装。为了兼容性，Node 22 LTS（当前为 `22.16+`）仍然受支持。
</Step>
<Step title="安装 OpenClaw">
- `npm` 方法（默认）：使用所选 `-Tag` 进行全局 npm 安装
- `git` 方法：克隆/更新仓库，使用 pnpm 安装/构建，并将包装器安装到 `%USERPROFILE%\.local\bin\openclaw.cmd`
</Step>
<Step title="安装后任务">
在可能情况下将所需 bin 目录添加到用户 PATH，然后在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力而为）。
</Step>
</Steps>
### 示例（install.ps1）
<Tabs>
<Tab title="默认">
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
</Tab>
<Tab title="Git 安装">
```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git
```
</Tab>
<Tab title="通过 npm 安装 GitHub main">
```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag main
```
</Tab>
<Tab title="自定义 git 目录">
```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"
```
</Tab>
<Tab title="试运行">
```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun
```
</Tab>
<Tab title="调试跟踪">
```powershell
# install.ps1 目前还没有专门的 -Verbose 标志。
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
```
</Tab>
</Tabs>
<AccordionGroup>
<Accordion title="标志参考">
| 标志 | 说明 |
| --------------------------- | -------------------------------------------- |
| `-InstallMethod npm\|git` | 安装方法（默认：`npm`） |
| `-Tag <tag\|version\|spec>` | npm dist-tag、版本或包规范（默认：`latest`） |
| `-GitDir <path>` | 检出目录（默认：`%USERPROFILE%\openclaw`） |
| `-NoOnboard` | 跳过新手引导 |
| `-NoGitUpdate` | 跳过 `git pull` |
| `-DryRun` | 仅打印操作 |
</Accordion>
<Accordion title="环境变量参考">
| 变量 | 说明 |
| ---------------------------------- | ------------- |
| `OPENCLAW_INSTALL_METHOD=git\|npm` | 安装方法 |
| `OPENCLAW_GIT_DIR=<path>` | 检出目录 |
| `OPENCLAW_NO_ONBOARD=1` | 跳过新手引导 |
| `OPENCLAW_GIT_UPDATE=0` | 禁用 git pull |
| `OPENCLAW_DRY_RUN=1` | 试运行模式 |
</Accordion>
</AccordionGroup>
<Note>
如果使用 `-InstallMethod git` 且缺少 Git，脚本会退出并打印 Git for Windows 链接。
</Note>
---
## CI 和自动化
使用非交互式标志/环境变量以实现可预测的运行。
<Tabs>
<Tab title="install.sh（非交互式 npm）">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard
```
</Tab>
<Tab title="install.sh（非交互式 git）">
```bash
OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
```
</Tab>
<Tab title="install-cli.sh（JSON）">
```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
```
</Tab>
<Tab title="install.ps1（跳过新手引导）">
```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
```
</Tab>
</Tabs>
---
## 故障排除
<AccordionGroup>
<Accordion title="为什么需要 Git？">
`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 文件中（如果这些文件存在）。
</Accordion>
<Accordion title="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
```
</Accordion>
<Accordion title='Windows：“npm error spawn git / ENOENT”'>
安装 Git for Windows，重新打开 PowerShell，然后重新运行安装器。
</Accordion>
<Accordion title='Windows：“openclaw is not recognized”'>
运行 `npm config get prefix`，并将该目录添加到你的用户 PATH（Windows 上不需要 `\bin` 后缀），然后重新打开 PowerShell。
</Accordion>
<Accordion title="Windows：如何获取详细安装器输出">
`install.ps1` 目前没有提供 `-Verbose` 开关。
对于脚本级诊断，请使用 PowerShell 跟踪：
```powershell
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
```
</Accordion>
<Accordion title="安装后找不到 openclaw">
通常是 PATH 问题。请参见 [Node.js 故障排除](/install/node#troubleshooting)。
</Accordion>
</AccordionGroup>

158
docs/zh-CN/install/macos-vm.md
View File

@ -1,75 +1,75 @@
---
read_when:
- 你想让 OpenClaw 与你的主 macOS 环境隔离
- 你想在沙箱中集成 iMessage（BlueBubbles）
- 你想要一个可重置、可克隆的 macOS 环境
- 你想比较本地与托管 macOS VM 选项
summary: 在沙箱隔离的 macOS VM（本地或托管）中运行 OpenClaw，当你需要隔离或 iMessage 时
title: macOS 虚拟机
- 你希望 OpenClaw 与你的主 macOS 环境隔离
- 你希望在沙箱中集成 iMessage（BlueBubbles）
- 你希望拥有一个可重置且可克隆的 macOS 环境
- 你希望比较本地与托管 macOS VM 选项
summary: 在沙箱化的 macOS VM（本地或托管）中运行 OpenClaw，适用于你需要隔离或 iMessage 的场景
title: macOS VM
x-i18n:
generated_at: "2026-02-03T07:53:09Z"
model: claude-opus-4-5
provider: pi
generated_at: "2026-03-16T06:23:59Z"
model: gpt-5.4
provider: openai
source_hash: 4d1c85a5e4945f9f0796038cd5960edecb71ec4dffb6f9686be50adb75180716
source_path: platforms/macos-vm.md
source_path: install/macos-vm.md
workflow: 15
---
# 在 macOS 虚拟机上运行 OpenClaw（沙箱隔离）
# 在 macOS VM 上运行 OpenClaw（沙箱隔离）
## 推荐默认方案（大多数用户）
## 推荐默认方案（适用于大多数用户）
- **小型 Linux VPS** 用于永久在线的 Gateway 网关，成本低。参见 [VPS 托管](/vps)。
- **专用硬件**（Mac mini 或 Linux 机器）如果你想要完全控制和**住宅 IP** 用于浏览器自动化。许多网站会屏蔽数据中心 IP，所以本地浏览通常效果更好。
- **混合方案：** 将 Gateway 网关保持在廉价 VPS 上，当你需要浏览器/UI 自动化时，将你的 Mac 作为**节点**连接。参见[节点](/nodes)和 [Gateway 网关远程](/gateway/remote)。
- **小型 Linux VPS**：适合始终在线的 Gateway 网关，且成本较低。参见 [VPS hosting](/vps)。
- **专用硬件**（Mac mini 或 Linux 主机）：如果你希望完全控制，并为浏览器自动化获得一个**住宅 IP**。许多网站会屏蔽数据中心 IP，因此本地浏览通常效果更好。
- **混合方案：** 将 Gateway 网关放在便宜的 VPS 上，当你需要浏览器/UI 自动化时，再将你的 Mac 作为一个 **node** 连接进来。参见 [Nodes](/nodes) 和 [Gateway remote](/gateway/remote)。
当你特别需要 macOS 独有功能（iMessage/BlueBubbles）或想要与日常 Mac 严格隔离时，使用 macOS VM。
当你明确需要 macOS 独有能力（iMessage/BlueBubbles），或希望与你的日常 Mac 严格隔离时，再使用 macOS VM。
## macOS VM 选项
### 在你的 Apple Silicon Mac 上运行本地 VM（Lume）
使用 [Lume](https://cua.ai/docs/lume) 在你现有的 Apple Silicon Mac 上的沙箱 macOS VM 中运行 OpenClaw。
使用 [Lume](https://cua.ai/docs/lume) 在你现有的 Apple Silicon Mac 上的沙箱化 macOS VM 中运行 OpenClaw。
这为你提供：
这样你将获得：
- 隔离的完整 macOS 环境（你的主机保持干净）
- 通过 BlueBubbles 支持 iMessage（在 Linux/Windows 上不可能）
- 通过克隆 VM 即时重置
- 完全隔离的 macOS 环境（你的宿主机保持干净）
- 通过 BlueBubbles 获得 iMessage 支持（在 Linux/Windows 上无法实现）
- 通过克隆 VM 实现即时重置
- 无需额外硬件或云成本
### 托管 Mac 提供商（云）
### 托管 Mac 提供商（云端）
如果你想要云端的 macOS，托管 Mac 提供商也可以：
如果你希望在云中使用 macOS，托管 Mac 提供商同样可行：
- [MacStadium](https://www.macstadium.com/)（托管 Mac）
- 其他托管 Mac 供应商也可以；按照他们的 VM + SSH 文档操作
- 其他托管 Mac 供应商也可以；请遵循它们的 VM + SSH 文档
一旦你有了 macOS VM 的 SSH 访问权限，继续下面的步骤 6。
一旦你获得了对 macOS VM 的 SSH 访问权限，就继续执行下面的第 6 步。
---
## 快速路径（Lume，有经验的用户）
## 快速路径（Lume，适合有经验的用户）
1. 安装 Lume
2. `lume create openclaw --os macos --ipsw latest`
3. 完成设置助手，启用远程登录（SSH）
3. 完成设置助理，启用远程登录（SSH）
4. `lume run openclaw --no-display`
5. SSH 进入，安装 OpenClaw，配置渠道
5. SSH 登录，安装 OpenClaw，配置渠道
6. 完成
---
## 你需要什么（Lume）
## 你需要准备的内容（Lume）
- Apple Silicon Mac（M1/M2/M3/M4）
- 主机上安装 macOS Sequoia 或更高版本
- 每个 VM 约 60 GB 可用磁盘空间
- 宿主机运行 macOS Sequoia 或更高版本
- 每个 VM 大约 60 GB 可用磁盘空间
- 约 20 分钟
---
## 1) 安装 Lume
## 1）安装 Lume
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
@ -87,11 +87,11 @@ echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
lume --version
```
文档：[Lume 安装](https://cua.ai/docs/lume/guide/getting-started/installation)
文档： [Lume Installation](https://cua.ai/docs/lume/guide/getting-started/installation)
---
## 2) 创建 macOS VM
## 2）创建 macOS VM
```bash
lume create openclaw --os macos --ipsw latest
@ -99,47 +99,47 @@ lume create openclaw --os macos --ipsw latest
这会下载 macOS 并创建 VM。VNC 窗口会自动打开。
注意：下载可能需要一段时间，取决于你的网络连接。
注意：下载可能需要一些时间，具体取决于你的网络连接。
---
## 3) 完成设置助手
## 3）完成设置助理
在 VNC 窗口中：
1. 选择语言和地区
2. 跳过 Apple ID（或者如果你以后想要 iMessage 就登录）
3. 创建用户账户（记住用户名和密码）
2. 跳过 Apple ID（或者如果你之后想使用 iMessage，也可以登录）
3. 创建一个用户账号（记住用户名和密码）
4. 跳过所有可选功能
设置完成后，启用 SSH：
1. 打开系统设置 → 通用 → 共享
2. 启用"远程登录"
1. 打开“系统设置”→“通用”→“共享”
2. 启用“远程登录”
---
## 4) 获取 VM 的 IP 地址
## 4）获取 VM 的 IP 地址
```bash
lume get openclaw
```
查找 IP 地址（通常是 `192.168.64.x`）。
查找 IP 地址（通常为 `192.168.64.x`）。
---
## 5) SSH 进入 VM
## 5）通过 SSH 连接到 VM
```bash
ssh youruser@192.168.64.X
```
将 `youruser` 替换为你创建的账户，IP 替换为你 VM 的 IP。
将 `youruser` 替换为你创建的账号，并将 IP 替换为你的 VM IP。
---
## 6) 安装 OpenClaw
## 6）安装 OpenClaw
在 VM 内：
@ -152,7 +152,7 @@ openclaw onboard --install-daemon
---
## 7) 配置渠道
## 7）配置渠道
编辑配置文件：
@ -176,7 +176,7 @@ nano ~/.openclaw/openclaw.json
}
```
然后登录 WhatsApp（扫描二维码）：
然后登录 WhatsApp（扫描 QR 码）：
```bash
openclaw channels login
@ -184,16 +184,16 @@ openclaw channels login
---
## 8) 无头运行 VM
## 8）以无界面方式运行 VM
停止 VM 并在无显示器模式下重启：
停止 VM，然后在无显示模式下重启：
```bash
lume stop openclaw
lume run openclaw --no-display
```
VM 在后台运行。OpenClaw 的守护进程保持 Gateway 网关运行。
VM 会在后台运行。OpenClaw 的守护进程会保持 Gateway 网关持续运行。
检查状态：
@ -203,18 +203,18 @@ ssh youruser@192.168.64.X "openclaw status"
---
## 额外：iMessage 集成
## 加分项：iMessage 集成
这是在 macOS 上运行的杀手级功能。使用 [BlueBubbles](https://bluebubbles.app) 将 iMessage 添加到 OpenClaw。
这是在 macOS 上运行的杀手级特性。使用 [BlueBubbles](https://bluebubbles.app) 将 iMessage 添加到 OpenClaw。
在 VM 内：
1. 从 bluebubbles.app 下载 BlueBubbles
2. 用你的 Apple ID 登录
3. 启用 Web API 并设置密码
4. 将 BlueBubbles webhooks 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）
2. 使用你的 Apple ID 登录
3. 启用 Web API 并设置一个密码
4. 将 BlueBubbles webhook 指向你的 gateway（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）
添加到你的 OpenClaw 配置：
添加到你的 OpenClaw 配置中：
```json
{
@ -228,15 +228,15 @@ ssh youruser@192.168.64.X "openclaw status"
}
```
重启 Gateway 网关。现在你的智能体可以发送和接收 iMessage 了。
重启 Gateway 网关。现在你的智能体就可以发送和接收 iMessage 了。
完整设置详情：[BlueBubbles 渠道](/channels/bluebubbles)
完整设置细节： [BlueBubbles channel](/channels/bluebubbles)
---
## 保存黄金镜像
在进一步自定义之前，快照你的干净状态：
在进一步自定义之前，为你的干净状态创建快照：
```bash
lume stop openclaw
@ -253,36 +253,36 @@ lume run openclaw --no-display
---
## 24/7 运行
## 7×24 运行
通过以下方式保持 VM 运行：
通过以下方式保持 VM 持续运行：
- 保持你的 Mac 插电
- 在系统设置 → 节能中禁用睡眠
- 如需要使用 `caffeinate`
- 让你的 Mac 保持通电
- 在“系统设置”→“节能”中禁用睡眠
- 如有需要，使用 `caffeinate`
对于真正的永久在线，考虑专用 Mac mini 或小型 VPS。参见 [VPS 托管](/vps)。
如果你需要真正始终在线，请考虑使用专用 Mac mini 或小型 VPS。参见 [VPS hosting](/vps)。
---
## 故障排除
| 问题 | 解决方案 |
| ----------------------- | ---------------------------------------------------------------- |
| 无法 SSH 进入 VM | 检查 VM 的系统设置中是否启用了"远程登录" |
| VM IP 未显示 | 等待 VM 完全启动，再次运行 `lume get openclaw` |
| 找不到 Lume 命令 | 将 `~/.local/bin` 添加到你的 PATH |
| WhatsApp 二维码扫描失败 | 确保运行 `openclaw channels login` 时你是登录到 VM（而不是主机） |
| 问题 | 解决方案 |
| ----------------------- | ----------------------------------------------------------------- |
| 无法通过 SSH 连接到 VM | 检查 VM 的“系统设置”中是否已启用“远程登录” |
| 未显示 VM IP | 等待 VM 完全启动后，再次运行 `lume get openclaw` |
| 找不到 `lume` 命令 | 将 `~/.local/bin` 添加到你的 PATH |
| 无法扫描 WhatsApp QR 码 | 运行 `openclaw channels login` 时，确保你登录的是 VM 而不是宿主机 |
---
## 相关文档
- [VPS 托管](/vps)
- [节点](/nodes)
- [Gateway 网关远程](/gateway/remote)
- [BlueBubbles 渠道](/channels/bluebubbles)
- [Lume 快速入门](https://cua.ai/docs/lume/guide/getting-started/quickstart)
- [Lume CLI 参考](https://cua.ai/docs/lume/reference/cli-reference)
- [无人值守 VM 设置](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup)（高级）
- [Docker 沙箱隔离](/install/docker)（替代隔离方案）
- [VPS hosting](/vps)
- [Nodes](/nodes)
- [Gateway remote](/gateway/remote)
- [BlueBubbles channel](/channels/bluebubbles)
- [Lume Quickstart](https://cua.ai/docs/lume/guide/getting-started/quickstart)
- [Lume CLI Reference](https://cua.ai/docs/lume/reference/cli-reference)
- [Unattended VM Setup](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup)（高级）
- [Docker Sandboxing](/install/docker)（另一种隔离方案）

160
docs/zh-CN/platforms/digitalocean.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 在 DigitalOcean 上设置 OpenClaw
- 寻找便宜的 VPS 托管来运行 OpenClaw
- 寻找适合 OpenClaw 的低价 VPS 托管
summary: 在 DigitalOcean 上运行 OpenClaw（简单的付费 VPS 选项）
title: DigitalOcean
x-i18n:
generated_at: "2026-02-03T07:51:55Z"
model: claude-opus-4-5
provider: pi
source_hash: d60559b8751da37413e5364e83c88254b476b2283386a0b07b2ca6b4e16157fc
generated_at: "2026-03-16T06:24:23Z"
model: gpt-5.4
provider: openai
source_hash: f7cbbee2bdc2df08d2c255ee55fdf822c27924b41c4f4717cafb7e6e015d0966
source_path: platforms/digitalocean.md
workflow: 15
---
@ -17,137 +17,141 @@ x-i18n:
## 目标
以 **$6/月**（或使用预留定价 $4/月）在 DigitalOcean 上运行持久的 OpenClaw Gateway 网关。
在 DigitalOcean 上以 **每月 6 美元**（或预留定价时每月 4 美元）运行一个持久化的 OpenClaw Gateway 网关。
如果你想要 $0/月的选项且不介意 ARM + 特定提供商的设置，请参阅 [Oracle Cloud 指南](/platforms/oracle)。
如果你想要每月 0 美元的方案，并且不介意 ARM + 提供商特定设置，请参阅 [Oracle Cloud 指南](/platforms/oracle)。
## 成本比较（2026）
## 成本对比（2026）
| 提供商 | 方案 | 配置 | 价格/月 | 备注 |
| ------------ | --------------- | --------------------- | ----------- | ------------------------ |
| Oracle Cloud | Always Free ARM | 最高 4 OCPU、24GB RAM | $0 | ARM，容量有限 / 注册有坑 |
| Hetzner | CX22 | 2 vCPU、4GB RAM | €3.79 (~$4) | 最便宜的付费选项 |
| DigitalOcean | Basic | 1 vCPU、1GB RAM | $6 | 界面简单，文档完善 |
| Vultr | Cloud Compute | 1 vCPU、1GB RAM | $6 | 多地区可选 |
| Linode | Nanode | 1 vCPU、1GB RAM | $5 | 现为 Akamai 旗下 |
| 提供商 | 套餐 | 规格 | 每月价格 | 说明 |
| ------------ | --------------- | ---------------------- | -------------- | -------------------------------- |
| Oracle Cloud | Always Free ARM | 最多 4 OCPU，24 GB RAM | $0 | ARM，容量有限 / 注册流程有些麻烦 |
| Hetzner | CX22 | 2 vCPU，4 GB RAM | €3.79（约 $4） | 最便宜的付费选项 |
| DigitalOcean | Basic | 1 vCPU，1 GB RAM | $6 | UI 简单，文档完善 |
| Vultr | Cloud Compute | 1 vCPU，1 GB RAM | $6 | 机房位置多 |
| Linode | Nanode | 1 vCPU，1 GB RAM | $5 | 现已并入 Akamai |
**选择提供商：**
**如何选择提供商：**
- DigitalOcean：最简单的用户体验 + 可预测的设置（本指南）
- Hetzner：性价比高（参见 [Hetzner 指南](/install/hetzner)）
- Oracle Cloud：可以 $0/月，但更麻烦且仅限 ARM（参见 [Oracle 指南](/platforms/oracle)）
- DigitalOcean：最简单的 UX + 可预测的设置（本指南）
- Hetzner：性价比不错（见 [Hetzner guide](/install/hetzner)）
- Oracle Cloud：可能做到每月 0 美元，但更挑环境且仅支持 ARM（见 [Oracle guide](/platforms/oracle)）
---
## 前提条件
- DigitalOcean 账户（[注册可获 $200 免费额度](https://m.do.co/c/signup)）
- DigitalOcean 账号（[注册可获 200 美元免费额度](https://m.do.co/c/signup)）
- SSH 密钥对（或愿意使用密码认证）
- 约 20 分钟
## 1) 创建 Droplet
## 1）创建 Droplet
<Warning>
请使用干净的基础镜像（Ubuntu 24.04 LTS）。除非你已经检查过其启动脚本和防火墙默认设置，否则请避免使用第三方 Marketplace 一键镜像。
</Warning>
1. 登录 [DigitalOcean](https://cloud.digitalocean.com/)
2. 点击 **Create → Droplets**
3. 选择：
- **Region：** 离你（或你的用户）最近的地区
- **Region：** 离你（或你的用户）最近
- **Image：** Ubuntu 24.04 LTS
- **Size：** Basic → Regular → **$6/mo**（1 vCPU、1GB RAM、25GB SSD）
- **Authentication：** SSH 密钥（推荐）或密码
- **Size：** Basic → Regular → **$6/mo**（1 vCPU、1 GB RAM、25 GB SSD）
- **Authentication：** SSH key（推荐）或密码
4. 点击 **Create Droplet**
5. 记下 IP 地址
## 2) 通过 SSH 连接
## 2）通过 SSH 连接
```bash
ssh root@YOUR_DROPLET_IP
```
## 3) 安装 OpenClaw
## 3）安装 OpenClaw
```bash
# Update system
# 更新系统
apt update && apt upgrade -y
# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
# 安装 Node.js 24
curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
apt install -y nodejs
# Install OpenClaw
# 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash
# Verify
# 验证
openclaw --version
```
## 4) 运行新手引导
## 4）运行新手引导
```bash
openclaw onboard --install-daemon
```
向导将引导你完成：
向导会带你完成以下设置：
- 模型认证（API 密钥或 OAuth）
- 模型认证（API key 或 OAuth）
- 渠道设置（Telegram、WhatsApp、Discord 等）
- Gateway 网关令牌（自动生成）
- Gateway 网关 token（自动生成）
- 守护进程安装（systemd）
## 5) 验证 Gateway 网关
## 5）验证 Gateway 网关
```bash
# Check status
# 检查状态
openclaw status
# Check service
# 检查服务
systemctl --user status openclaw-gateway.service
# View logs
# 查看日志
journalctl --user -u openclaw-gateway.service -f
```
## 6) 访问控制面板
## 6）访问 Dashboard
Gateway 网关默认绑定到 loopback。要访问控制界面：
Gateway 网关默认绑定到 loopback。要访问 Control UI：
**选项 A：SSH 隧道（推荐）**
```bash
# From your local machine
# 在你的本地机器上
ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP
# Then open: http://localhost:18789
# 然后打开：http://localhost:18789
```
**选项 B：Tailscale Serve（HTTPS，仅 loopback）**
```bash
# On the droplet
# 在 droplet 上
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up
# Configure Gateway to use Tailscale Serve
# 将 Gateway 网关配置为使用 Tailscale Serve
openclaw config set gateway.tailscale.mode serve
openclaw gateway restart
```
打开：`https://<magicdns>/`
注意事项：
说明：
- Serve 保持 Gateway 网关仅 loopback 并通过 Tailscale 身份头进行认证。
- 要改为需要令牌/密码，请设置 `gateway.auth.allowTailscale: false` 或使用 `gateway.auth.mode: "password"`。
- Serve 会让 Gateway 网关保持仅 loopback，并通过 Tailscale 身份头对 Control UI/WebSocket 流量进行认证（无 token 认证假定 Gateway 网关主机可信；HTTP API 仍然需要 token/password）。
- 如果你想强制要求 token/password，请设置 `gateway.auth.allowTailscale: false` 或使用 `gateway.auth.mode: "password"`。
**选项 C：Tailnet 绑定（不使用 Serve）**
**选项 C：绑定到 tailnet（不使用 Serve）**
```bash
openclaw config set gateway.bind tailnet
openclaw gateway restart
```
打开：`http://<tailscale-ip>:18789`（需要令牌）。
打开：`http://<tailscale-ip>:18789`（需要 token）。
## 7) 连接你的渠道
## 7）连接你的渠道
### Telegram
@ -160,16 +164,16 @@ openclaw pairing approve telegram <CODE>
```bash
openclaw channels login whatsapp
# Scan QR code
# 扫描 QR 码
```
参见[渠道](/channels)了解其他提供商。
其他提供商请参阅 [Channels](/channels)。
---
## 1GB RAM 的优化
## 针对 1 GB RAM 的优化
$6 的 droplet 只有 1GB RAM。为了保持运行流畅：
6 美元的 droplet 只有 1 GB RAM。为了保持运行顺畅：
### 添加 swap（推荐）
@ -183,9 +187,9 @@ echo '/swapfile none swap sw 0 0' >> /etc/fstab
### 使用更轻量的模型
如果遇到 OOM，考虑：
如果你遇到 OOM，可以考虑：
- 使用基于 API 的模型（Claude、GPT）而不是本地模型
- 使用基于 API 的模型（Claude、GPT），而不是本地模型
- 将 `agents.defaults.model.primary` 设置为更小的模型
### 监控内存
@ -199,12 +203,12 @@ htop
## 持久化
所有状态存储在：
所有状态都存储在：
- `~/.openclaw/` — 配置、凭证、会话数据
- `~/.openclaw/workspace/` — 工作区（SOUL.md、记忆等）
- `~/.openclaw/workspace/` — 工作区（`SOUL.md`、memory 等）
这些在重启后保留。定期备份：
这些内容在重启后仍会保留。请定期备份：
```bash
tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace
@ -214,21 +218,21 @@ tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace
## Oracle Cloud 免费替代方案
Oracle Cloud 提供 **Always Free** ARM 实例，比这里任何付费选项都强大得多 — 每月 $0。
Oracle Cloud 提供 **Always Free** ARM 实例，性能显著强于这里列出的任何付费选项 —— 且每月 0 美元。
| 你将获得 | 配置 |
| -------------- | ---------------- |
| **4 OCPUs** | ARM Ampere A1 |
| **24GB RAM** | 绰绰有余 |
| **200GB 存储** | 块存储卷 |
| **永久免费** | 不收取信用卡费用 |
| 你将获得 | 规格 |
| --------------- | ------------------ |
| **4 OCPU** | ARM Ampere A1 |
| **24 GB RAM** | 完全足够 |
| **200 GB 存储** | 块存储卷 |
| **永久免费** | 不会产生信用卡费用 |
**注意事项：**
- 注册可能有点麻烦（失败了就重试）
- ARM 架构 — 大多数东西都能工作，但有些二进制文件需要 ARM 构建
- 注册过程可能比较挑剔（如果失败请重试）
- ARM 架构 —— 大多数东西都能运行，但某些二进制文件需要 ARM 构建版本
完整设置指南请参阅 [Oracle Cloud](/platforms/oracle)。关于注册技巧和注册流程故障排除，请参阅此[社区指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)。
完整设置指南请参阅 [Oracle Cloud](/platforms/oracle)。关于注册技巧和注册流程故障排除，请参阅这篇[社区指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)。
---
@ -242,7 +246,7 @@ openclaw doctor --non-interactive
journalctl -u openclaw --no-pager -n 50
```
### 端口已被使用
### 端口已被占用
```bash
lsof -i :18789
@ -252,18 +256,18 @@ kill <PID>
### 内存不足
```bash
# Check memory
# 检查内存
free -h
# Add more swap
# Or upgrade to $12/mo droplet (2GB RAM)
# 添加更多 swap
# 或升级到每月 12 美元的 droplet（2 GB RAM）
```
---
## 另请参阅
- [Hetzner 指南](/install/hetzner) — 更便宜、更强大
- [Docker 安装](/install/docker) — 容器化设置
- [Tailscale](/gateway/tailscale) — 安全远程访问
- [配置](/gateway/configuration) — 完整配置参考
- [Hetzner guide](/install/hetzner) — 更便宜、性能更强
- [Docker install](/install/docker) — 容器化设置
- [Tailscale](/gateway/tailscale) — 安全的远程访问
- [Configuration](/gateway/configuration) — 完整配置参考

32
docs/zh-CN/platforms/index.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 查找操作系统支持或安装路径时
- 决定在哪里运行 Gateway 网关时
summary: 平台支持概述（Gateway 网关 + 配套应用）
- 查找操作系统支持或安装路径
- 决定在哪里运行 Gateway 网关
summary: 平台支持概览（Gateway 网关 + 配套应用）
title: 平台
x-i18n:
generated_at: "2026-02-03T07:52:07Z"
model: claude-opus-4-5
provider: pi
source_hash: 254852a5ed1996982a52eed4a72659477609e08d340c625d24ef6d99c21eece6
generated_at: "2026-03-16T06:24:20Z"
model: gpt-5.4
provider: openai
source_hash: 653f395598b9558cb15b58ab42ed931dba47c70780be1c803d33dd795bad6503
source_path: platforms/index.md
workflow: 15
---
@ -16,11 +16,11 @@ x-i18n:
# 平台
OpenClaw 核心使用 TypeScript 编写。**Node 是推荐的运行时**。
不推荐 Bun 用于 Gateway 网关（WhatsApp/Telegram 存在 bug）。
不建议将 Bun 用于 Gateway 网关（存在 WhatsApp/Telegram bug）。
配套应用适用于 macOS（菜单栏应用）和移动节点（iOS/Android）。Windows 和
Linux 配套应用已在计划中，但 Gateway 网关目前已完全支持。
Windows 原生配套应用也在计划中；推荐通过 WSL2 使用 Gateway 网关。
已提供适用于 macOS（菜单栏应用）和移动节点（iOS/Android）的配套应用。Windows 和
Linux 配套应用已在规划中，但 Gateway 网关目前已得到完全支持。
适用于 Windows 的原生配套应用也在规划中；推荐通过 WSL2 运行 Gateway 网关。
## 选择你的操作系统
@ -30,7 +30,7 @@ Windows 原生配套应用也在计划中；推荐通过 WSL2 使用 Gateway 网
- Windows：[Windows](/platforms/windows)
- Linux：[Linux](/platforms/linux)
## VPS 和托管
## VPS 与托管
- VPS 中心：[VPS 托管](/vps)
- Fly.io：[Fly.io](/install/fly)
@ -47,14 +47,14 @@ Windows 原生配套应用也在计划中；推荐通过 WSL2 使用 Gateway 网
## Gateway 网关服务安装（CLI）
使用以下任一方式（均支持）：
使用以下任一方式（均受支持）：
- 向导（推荐）：`openclaw onboard --install-daemon`
- 直接安装：`openclaw gateway install`
- 配置流程：`openclaw configure` → 选择 **Gateway service**
- 修复/迁移：`openclaw doctor`（提供安装或修复服务）
- 配置流程：`openclaw configure` → 选择 **Gateway 服务**
- 修复/迁移：`openclaw doctor`（会提供安装或修复服务的选项）
服务目标取决于操作系统：
- macOS：LaunchAgent（`bot.molt.gateway` 或 `bot.molt.<profile>`；旧版 `com.openclaw.*`）
- macOS：LaunchAgent（`ai.openclaw.gateway` 或 `ai.openclaw.<profile>`；旧版为 `com.openclaw.*`）
- Linux/WSL2：systemd 用户服务（`openclaw-gateway[-<profile>].service`）

35
docs/zh-CN/platforms/linux.md
View File

@ -1,31 +1,31 @@
---
read_when:
- 查找 Linux 配套应用状态时
- 规划平台覆盖或贡献时
- 查找 Linux 配套应用状态
- 规划平台覆盖范围或贡献
summary: Linux 支持 + 配套应用状态
title: Linux 应用
x-i18n:
generated_at: "2026-02-03T07:52:18Z"
model: claude-opus-4-5
provider: pi
source_hash: a9bbbcecf2fd522a2f5ac8f3b9068febbc43658465bfb9276bff6c3e946789d2
generated_at: "2026-03-16T06:24:30Z"
model: gpt-5.4
provider: openai
source_hash: 12f2a28ec8fc17769210bda97af11fda332355956d41bba69ac51cc523be6178
source_path: platforms/linux.md
workflow: 15
---
# Linux 应用
Gateway 网关在 Linux 上完全支持。**Node 是推荐的运行时**。
不推荐 Bun 用于 Gateway 网关（WhatsApp/Telegram 存在 bug）。
Gateway 网关在 Linux 上得到完全支持。**Node 是推荐的运行时**。
不建议将 Bun 用于 Gateway 网关（存在 WhatsApp/Telegram bug）。
原生 Linux 配套应用已在计划中。如果你想帮助构建，欢迎贡献。
原生 Linux 配套应用已在规划中。如果你想帮助构建一个，欢迎贡献。
## 新手快速路径（VPS）
## 面向初学者的快速路径（VPS）
1. 安装 Node 22+
1. 安装 Node 24（推荐；Node 22 LTS，目前 `22.16+`，为了兼容性仍然可用）
2. `npm i -g openclaw@latest`
3. `openclaw onboard --install-daemon`
4. 从你的笔记本电脑：`ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
4. 在你的笔记本电脑上运行：`ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
5. 打开 `http://127.0.0.1:18789/` 并粘贴你的令牌
分步 VPS 指南：[exe.dev](/install/exe-dev)
@ -49,19 +49,19 @@ Gateway 网关在 Linux 上完全支持。**Node 是推荐的运行时**。
openclaw onboard --install-daemon
```
或：
或者：
```
openclaw gateway install
```
或：
或者：
```
openclaw configure
```
出现提示时选择 **Gateway service**。
出现提示时，选择 **Gateway 服务**。
修复/迁移：
@ -71,9 +71,8 @@ openclaw doctor
## 系统控制（systemd 用户单元）
OpenClaw 默认安装 systemd **用户**服务。对于共享或常驻服务器使用**系统**
服务。完整的单元示例和指南
在 [Gateway 网关运行手册](/gateway) 中。
OpenClaw 默认安装 systemd **用户**服务。对于共享或始终在线的服务器，请使用 **系统** 服务。完整的单元示例和指导
请参见 [Gateway 网关运行手册](/gateway)。
最小设置：

267
docs/zh-CN/platforms/raspberry-pi.md
View File

@ -1,15 +1,15 @@
---
read_when:
- 在 Raspberry Pi 上设置 OpenClaw 时
- 在 ARM 设备上运行 OpenClaw 时
- 构建低成本常驻个人 AI 时
summary: 在 Raspberry Pi 上运行 OpenClaw（低成本自托管设置）
- 在 Raspberry Pi 上设置 OpenClaw
- 在 ARM 设备上运行 OpenClaw
- 构建一个低成本、始终在线的个人 AI
summary: 在 Raspberry Pi 上运行 OpenClaw（低预算自托管方案）
title: Raspberry Pi
x-i18n:
generated_at: "2026-02-03T07:53:30Z"
model: claude-opus-4-5
provider: pi
source_hash: 6741eaf0115a4fa0efd6599a99e0526a20ceb30eda1d9b04cba9dd5dec84bee2
generated_at: "2026-03-16T06:24:58Z"
model: gpt-5.4
provider: openai
source_hash: 3106dea63b5a548622b82e3090e7fdb7f748b96bf0e23893496f1b60c095334a
source_path: platforms/raspberry-pi.md
workflow: 15
---
@ -18,51 +18,51 @@ x-i18n:
## 目标
在 Raspberry Pi 上运行持久、常驻的 OpenClaw Gateway 网关，**一次性成本约 $35-80**（无月费）。
在 Raspberry Pi 上以 **约 35–80 美元**的一次性成本（无月费）运行一个持久化、始终在线的 OpenClaw Gateway 网关。
适用于：
非常适合：
- 24/7 个人 AI 助手
- 家庭自动化中心
- 低功耗、随时可用的 Telegram/WhatsApp 机器人
- 7×24 个人 AI 助手
- 家庭自动化中枢
- 低功耗、始终可用的 Telegram/WhatsApp bot
## 硬件要求
| Pi 型号 | 内存 | 是否可用？ | 说明 |
| --------------- | ------- | ---------- | -------------------------- |
| **Pi 5** | 4GB/8GB | ✅ 最佳 | 最快，推荐 |
| **Pi 4** | 4GB | ✅ 良好 | 大多数用户的最佳选择 |
| **Pi 4** | 2GB | ✅ 可以 | 可用，添加交换空间 |
| **Pi 4** | 1GB | ⚠️ 紧张 | 使用交换空间可行，最小配置 |
| **Pi 3B+** | 1GB | ⚠️ 慢 | 可用但较慢 |
| **Pi Zero 2 W** | 512MB | ❌ | 不推荐 |
| Pi 型号 | RAM | 可用？ | 说明 |
| --------------- | ------- | ------- | -------------------------- |
| **Pi 5** | 4GB/8GB | ✅ 最佳 | 最快，推荐 |
| **Pi 4** | 4GB | ✅ 良好 | 适合大多数用户的最佳平衡点 |
| **Pi 4** | 2GB | ✅ 可以 | 可用，建议加 swap |
| **Pi 4** | 1GB | ⚠️ 紧张 | 配合 swap 和最小化配置可行 |
| **Pi 3B+** | 1GB | ⚠️ 较慢 | 可用，但反应迟缓 |
| **Pi Zero 2 W** | 512MB | ❌ | 不推荐 |
**最低配置：** 1GB 内存，1 核，500MB 磁盘
**推荐：** 2GB+ 内存，64 位系统，16GB+ SD 卡（或 USB SSD）
**最低规格：** 1 GB RAM、1 核、500 MB 磁盘
**推荐规格：** 2 GB 以上 RAM、64 位 OS、16 GB 以上 SD 卡（或 USB SSD）
## 你需要准备
## 你需要准备的内容
- Raspberry Pi 4 或 5（推荐 2GB+）
- MicroSD 卡（16GB+）或 USB SSD（性能更好）
- 电源（推荐官方 Pi 电源）
- 网络连接（以太网或 WiFi）
- Raspberry Pi 4 或 5（推荐 2 GB 以上）
- MicroSD 卡（16 GB 以上）或 USB SSD（性能更好）
- 电源（推荐使用官方 Pi 电源）
- 网络连接（以太网或 Wi‑Fi）
- 约 30 分钟
## 1) 刷写系统
## 1）刷写 OS
使用 **Raspberry Pi OS Lite (64-bit)** — 无头服务器不需要桌面。
使用 **Raspberry Pi OS Lite（64 位）** —— 对于无头服务器，不需要桌面环境。
1. 下载 [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
2. 选择系统：**Raspberry Pi OS Lite (64-bit)**
3. 点击齿轮图标（⚙️）预配置：
2. 选择 OS：**Raspberry Pi OS Lite（64 位）**
3. 点击齿轮图标（⚙️）进行预配置：
- 设置主机名：`gateway-host`
- 启用 SSH
- 设置用户名/密码
- 配置 WiFi（如果不使用以太网）
4. 刷写到你的 SD 卡 / USB 驱动器
- 配置 Wi‑Fi（如果不使用以太网）
4. 将系统写入你的 SD 卡 / USB 驱动器
5. 插入并启动 Pi
## 2) 通过 SSH 连接
## 2）通过 SSH 连接
```bash
ssh user@gateway-host
@ -70,37 +70,37 @@ ssh user@gateway-host
ssh user@192.168.x.x
```
## 3) 系统设置
## 3）系统设置
```bash
# 更新系统
sudo apt update && sudo apt upgrade -y
# 安装必要软件包
# 安装基础软件包
sudo apt install -y git curl build-essential
# 设置时区（对 cron/提醒很重要）
sudo timedatectl set-timezone America/Chicago # 改成你的时区
```
## 4) 安装 Node.js 22（ARM64）
## 4）安装 Node.js 24（ARM64）
```bash
# 通过 NodeSource 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
# 验证
node --version # 应显示 v22.x.x
node --version # 应显示 v24.x.x
npm --version
```
## 5) 添加交换空间（2GB 或更少内存时很重要）
## 5）添加 swap（对于 2 GB 或更低内存很重要）
交换空间可防止内存不足崩溃：
swap 可以防止内存不足崩溃：
```bash
# 创建 2GB 交换文件
# 创建 2 GB swap 文件
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
@ -109,12 +109,12 @@ sudo swapon /swapfile
# 永久生效
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
# 优化低内存（降低 swappiness）
# 针对低内存优化（降低 swappiness）
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```
## 6) 安装 OpenClaw
## 6）安装 OpenClaw
### 选项 A：标准安装（推荐）
@ -122,7 +122,7 @@ sudo sysctl -p
curl -fsSL https://openclaw.ai/install.sh | bash
```
### 选项 B：可修改安装（用于调试）
### 选项 B：可修改安装（适合折腾）
```bash
git clone https://github.com/openclaw/openclaw.git
@ -132,22 +132,22 @@ npm run build
npm link
```
可修改安装让你可以直接访问日志和代码 — 对调试 ARM 特定问题很有用。
可修改安装会让你直接访问日志和代码 —— 这对于调试 ARM 特定问题很有帮助。
## 7) 运行新手引导
## 7）运行新手引导
```bash
openclaw onboard --install-daemon
```
按照向导操作：
按向导完成设置：
1. **Gateway 网关模式：** Local
2. **认证：** 推荐 API 密钥（OAuth 在无头 Pi 上可能不稳定）
3. **渠道：** Telegram 最容易上手
2. **认证：** 推荐 API key（在无头 Pi 上 OAuth 可能比较挑环境）
3. **渠道：** 最容易上手的是 Telegram
4. **守护进程：** 是（systemd）
## 8) 验证安装
## 8）验证安装
```bash
# 检查状态
@ -160,52 +160,103 @@ sudo systemctl status openclaw
journalctl -u openclaw -f
```
## 9) 访问仪表板
## 9）访问 OpenClaw Dashboard
由于 Pi 是无头的，使用 SSH 隧道：
将 `user@gateway-host` 替换为你的 Pi 用户名，以及主机名或 IP 地址。
在你的电脑上，让 Pi 打印一个新的 Dashboard URL：
```bash
# 从你的笔记本电脑/台式机
ssh -L 18789:localhost:18789 user@gateway-host
# 然后在浏览器中打开
open http://localhost:18789
ssh user@gateway-host 'openclaw dashboard --no-open'
```
或使用 Tailscale 实现常驻访问：
该命令会打印 `Dashboard URL:`。根据 `gateway.auth.token`
的配置方式，URL 可能是普通的 `http://127.0.0.1:18789/` 链接，也可能是包含 `#token=...` 的链接。
在你电脑上的另一个终端中，创建 SSH 隧道：
```bash
# 在 Pi 上
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# 更新配置
openclaw config set gateway.bind tailnet
sudo systemctl restart openclaw
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
```
然后在本地浏览器中打开打印出的 Dashboard URL。
如果 UI 要求认证，请将 `gateway.auth.token`
（或 `OPENCLAW_GATEWAY_TOKEN`）中的 token 粘贴到 Control UI 设置中。
如需始终在线的远程访问，请参阅 [Tailscale](/gateway/tailscale)。
---
## 性能优化
### 使用 USB SSD（巨大改进）
### 使用 USB SSD（显著提升）
SD 卡速度慢且会磨损。USB SSD 可大幅提升性能：
SD 卡速度慢且易磨损。USB SSD 会显著提升性能：
```bash
# 检查是否从 USB 启动
lsblk
```
设置请参见 [Pi USB 启动指南](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot)。
设置方法请参阅 [Pi USB boot guide](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot)。
### 减少内存使用
### 加快 CLI 启动速度（模块编译缓存）
在性能较弱的 Pi 主机上，启用 Node 的模块编译缓存可以加快重复 CLI 运行速度：
```bash
# 禁用 GPU 内存分配（无头模式）
grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1
EOF
source ~/.bashrc
```
说明：
- `NODE_COMPILE_CACHE` 会加快后续运行（`status`、`health`、`--help`）。
- `/var/tmp` 比 `/tmp` 更能在重启后保留内容。
- `OPENCLAW_NO_RESPAWN=1` 可避免 CLI 自重启带来的额外启动开销。
- 第一次运行会预热缓存；之后的运行收益最大。
### systemd 启动调优（可选）
如果这台 Pi 主要运行 OpenClaw，可以添加一个服务 drop-in，以减少重启抖动并保持稳定的启动环境：
```bash
sudo systemctl edit openclaw
```
```ini
[Service]
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Restart=always
RestartSec=2
TimeoutStartSec=90
```
然后应用：
```bash
sudo systemctl daemon-reload
sudo systemctl restart openclaw
```
如果可能，请将 OpenClaw 状态/缓存放在 SSD 支持的存储上，以避免冷启动期间 SD 卡随机 I/O 成为瓶颈。
关于 `Restart=` 策略如何帮助自动恢复：
[systemd can automate service recovery](https://www.redhat.com/en/blog/systemd-automate-recovery)。
### 减少内存占用
```bash
# 禁用 GPU 内存分配（无头）
echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
# 如不需要则禁用蓝牙
# 如果不需要，禁用蓝牙
sudo systemctl disable bluetooth
```
@ -228,32 +279,32 @@ htop
### 二进制兼容性
大多数 OpenClaw 功能在 ARM64 上可用，但某些外部二进制文件可能需要 ARM 构建：
OpenClaw 的大多数功能都可在 ARM64 上运行，但某些外部二进制文件可能需要 ARM 构建版本：
| 工具 | ARM64 状态 | 说明 |
| ------------------ | ---------- | ----------------------------------- |
| Node.js | ✅ | 运行良好 |
| WhatsApp (Baileys) | ✅ | 纯 JS，无问题 |
| Telegram | ✅ | 纯 JS，无问题 |
| gog (Gmail CLI) | ⚠️ | 检查是否有 ARM 版本 |
| gog (Gmail CLI) | ⚠️ | 请检查是否有 ARM 发布版本 |
| Chromium (browser) | ✅ | `sudo apt install chromium-browser` |
如果某个 skill 失败，检查其二进制文件是否有 ARM 构建。许多 Go/Rust 工具有；有些没有。
如果某个 skill 失败，请检查其二进制文件是否有 ARM 构建版本。许多 Go/Rust 工具都有；有些则没有。
### 32 位 vs 64 位
### 32 位与 64 位
**始终使用 64 位系统。** Node.js 和许多现代工具需要它。使用以下命令检查：
**务必使用 64 位 OS。** Node.js 和许多现代工具都要求如此。使用以下命令检查：
```bash
uname -m
# 应显示：aarch64（64 位）而不是 armv7l（32 位）
# 应显示：aarch64（64 位），而不是 armv7l（32 位）
```
---
## 推荐的模型设置
由于 Pi 只是 Gateway 网关（模型在云端运行），使用基于 API 的模型：
由于 Pi 只是 Gateway 网关（模型在云中运行），请使用基于 API 的模型：
```json
{
@ -268,19 +319,19 @@ uname -m
}
```
**不要尝试在 Pi 上运行本地 LLM** — 即使是小模型也太慢了。让 Claude/GPT 来做繁重的工作。
**不要尝试在 Pi 上运行本地 LLM** —— 即使是小模型也太慢了。让 Claude/GPT 负责主要计算工作。
---
## 开机自启
## 开机自动启动
新手引导向导会设置这个，但要验证：
设置向导会帮你配置这个，但你也可以这样验证：
```bash
# 检查服务是否已启用
sudo systemctl is-enabled openclaw
# 如果没有则启用
# 如果没有，则启用
sudo systemctl enable openclaw
# 开机启动
@ -297,15 +348,15 @@ sudo systemctl start openclaw
# 检查内存
free -h
# 添加更多交换空间（见步骤 5）
# 添加更多 swap（见第 5 步）
# 或减少 Pi 上运行的服务
```
### 性能慢
### 性能缓慢
- 使用 USB SSD 代替 SD 卡
- 使用 USB SSD 替代 SD 卡
- 禁用未使用的服务：`sudo systemctl disable cups bluetooth avahi-daemon`
- 检查 CPU 降频：`vcgencmd get_throttled`（应返回 `0x0`）
- 检查 CPU 限频：`vcgencmd get_throttled`（应返回 `0x0`）
### 服务无法启动
@ -314,25 +365,25 @@ free -h
journalctl -u openclaw --no-pager -n 100
# 常见修复：重新构建
cd ~/openclaw # 如果使用可修改安装
cd ~/openclaw # 如果使用的是可修改安装
npm run build
sudo systemctl restart openclaw
```
### ARM 二进制问题
如果某个 skill 失败并显示"exec format error"：
如果某个 skill 因 “exec format error” 失败：
1. 检查该二进制文件是否有 ARM64 构建
2. 尝试从源代码构建
1. 检查该二进制文件是否有 ARM64 构建版本
2. 尝试从源码构建
3. 或使用支持 ARM 的 Docker 容器
### WiFi 断开
### Wi‑Fi 掉线
对于使用 WiFi 的无头 Pi：
对于通过 Wi‑Fi 运行的无头 Pi：
```bash
# 禁用 WiFi 电源管理
# 禁用 Wi‑Fi 省电
sudo iwconfig wlan0 power off
# 永久生效
@ -343,23 +394,23 @@ echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
## 成本对比
| 设置 | 一次性成本 | 月费 | 说明 |
| -------------- | ---------- | -------- | ------------------ |
| **Pi 4 (2GB)** | ~$45 | $0 | + 电费（约 $5/年） |
| **Pi 4 (4GB)** | ~$55 | $0 | 推荐 |
| **Pi 5 (4GB)** | ~$60 | $0 | 最佳性能 |
| **Pi 5 (8GB)** | ~$80 | $0 | 过剩但面向未来 |
| DigitalOcean | $0 | $6/月 | $72/年 |
| Hetzner | $0 | €3.79/月 | 约 $50/年 |
| 方案 | 一次性成本 | 月成本 | 说明 |
| --------------- | ---------- | -------- | ------------------------ |
| **Pi 4（2GB）** | ~$45 | $0 | + 电费（约 $5/年） |
| **Pi 4（4GB）** | ~$55 | $0 | 推荐 |
| **Pi 5（4GB）** | ~$60 | $0 | 最佳性能 |
| **Pi 5（8GB）** | ~$80 | $0 | 有些超配，但更有未来余量 |
| DigitalOcean | $0 | $6/月 | $72/年 |
| Hetzner | $0 | €3.79/月 | 约 $50/年 |
**回本期：** 与云 VPS 相比，Pi 约 6-12 个月内回本。
**回本周期：** 与云 VPS 相比，一台 Pi 大约 6–12 个月即可回本。
---
## 另请参阅
- [Linux 指南](/platforms/linux) — 通用 Linux 设置
- [DigitalOcean 指南](/platforms/digitalocean) — 云替代方案
- [Hetzner 指南](/install/hetzner) — Docker 设置
- [Linux guide](/platforms/linux) — 通用 Linux 设置
- [DigitalOcean guide](/platforms/digitalocean) — 云端替代方案
- [Hetzner guide](/install/hetzner) — Docker 设置
- [Tailscale](/gateway/tailscale) — 远程访问
- [节点](/nodes) — 将你的笔记本电脑/手机与 Pi Gateway 网关配对
- [Nodes](/nodes) — 将你的笔记本电脑/手机与 Pi Gateway 网关配对

155
docs/zh-CN/platforms/windows.md
View File

@ -3,31 +3,72 @@ read_when:
- 在 Windows 上安装 OpenClaw
- 查找 Windows 配套应用状态
summary: Windows（WSL2）支持 + 配套应用状态
title: Windows (WSL2)
title: Windows（WSL2）
x-i18n:
generated_at: "2026-02-03T07:53:19Z"
model: claude-opus-4-5
provider: pi
source_hash: c93d2263b4e5b60cb6fbe9adcb1a0ca95b70cd6feb6e63cfc4459cb18b229da0
generated_at: "2026-03-16T06:24:52Z"
model: gpt-5.4
provider: openai
source_hash: 2e905b129f34ac31e30d5767504233411b306b5985252f1a285e09f1ece19962
source_path: platforms/windows.md
workflow: 15
---
# Windows (WSL2)
# Windows（WSL2）
Windows 上的 OpenClaw 推荐**通过 WSL2**（推荐 Ubuntu）。CLI + Gateway 网关在 Linux 内运行，这保持了运行时的一致性并使工具兼容性大大提高（Node/Bun/pnpm、Linux 二进制文件、Skills）。原生 Windows 可能更棘手。WSL2 给你完整的 Linux 体验——一条命令安装：`wsl --install`。
推荐在 Windows 上**通过 WSL2** 运行 OpenClaw（推荐 Ubuntu）。CLI + Gateway 网关在 Linux 内运行，这能保持运行时一致，并使
工具链兼容性高得多（Node/Bun/pnpm、Linux 二进制文件、Skills）。原生
Windows 可能会更棘手。WSL2 可提供完整的 Linux 体验 —— 只需一条命令
即可安装：`wsl --install`。
原生 Windows 配套应用已在计划中。
原生 Windows 配套应用已在规划中。
## 安装（WSL2）
- [入门指南](/start/getting-started)（在 WSL 内使用）
- [安装和更新](/install/updating)
- 官方 WSL2 指南（Microsoft）：https://learn.microsoft.com/windows/wsl/install
- [入门指南](/start/getting-started)（请在 WSL 内使用）
- [安装与更新](/install/updating)
- 官方 WSL2 指南（Microsoft）：[https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
## 原生 Windows 状态
原生 Windows CLI 流程正在改进，但 WSL2 仍然是推荐路径。
当前在原生 Windows 上运行良好的内容：
- 通过 `install.ps1` 使用网站安装器
- 本地 CLI 用法，例如 `openclaw --version`、`openclaw doctor` 和 `openclaw plugins list --json`
- 嵌入式 local-agent/provider 冒烟测试，例如：
```powershell
openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."
```
当前注意事项：
- 除非你传递 `--skip-health`，否则 `openclaw onboard --non-interactive` 仍然要求本地 Gateway 网关可访问
- `openclaw onboard --non-interactive --install-daemon` 和 `openclaw gateway install` 会优先尝试 Windows Scheduled Tasks
- 如果拒绝创建 Scheduled Task，OpenClaw 会回退到每用户 Startup 文件夹登录项，并立即启动 Gateway 网关
- 如果 `schtasks` 本身卡住或停止响应，OpenClaw 现在会快速中止该路径并回退，而不是无限挂起
- 在可用时仍优先使用 Scheduled Tasks，因为它们能提供更好的 supervisor 状态
如果你只想使用原生 CLI，而不安装 Gateway 网关服务，可使用以下任一方式：
```powershell
openclaw onboard --non-interactive --skip-health
openclaw gateway run
```
如果你确实想在原生 Windows 上使用受管启动：
```powershell
openclaw gateway install
openclaw gateway status --json
```
如果无法创建 Scheduled Task，回退服务模式仍会通过当前用户的 Startup 文件夹在登录后自动启动。
## Gateway 网关
- [Gateway 网关操作手册](/gateway)
- [Gateway 网关运行手册](/gateway)
- [配置](/gateway/configuration)
## Gateway 网关服务安装（CLI）
@ -38,19 +79,19 @@ Windows 上的 OpenClaw 推荐**通过 WSL2**（推荐 Ubuntu）。CLI + Gateway
openclaw onboard --install-daemon
```
或：
或者：
```
openclaw gateway install
```
或：
或者：
```
openclaw configure
```
出现提示时选择 **Gateway service**。
出现提示时，选择 **Gateway 服务**。
修复/迁移：
@ -58,11 +99,58 @@ openclaw configure
openclaw doctor
```
## 高级：通过 LAN 暴露 WSL 服务（portproxy）
## 在 Windows 登录前自动启动 Gateway 网关
WSL 有自己的虚拟网络。如果另一台机器需要访问**在 WSL 内**运行的服务（SSH、本地 TTS 服务器或 Gateway 网关），你必须将 Windows 端口转发到当前的 WSL IP。WSL IP 在重启后会改变，因此你可能需要刷新转发规则。
对于无头设置，请确保完整的启动链即使在无人登录
Windows 时也能运行。
示例（以**管理员身份**运行 PowerShell）：
### 1）在未登录时保持用户服务运行
在 WSL 内：
```bash
sudo loginctl enable-linger "$(whoami)"
```
### 2）安装 OpenClaw Gateway 网关用户服务
在 WSL 内：
```bash
openclaw gateway install
```
### 3）在 Windows 启动时自动启动 WSL
以管理员身份打开 PowerShell：
```powershell
schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM
```
将 `Ubuntu` 替换为以下命令输出中的发行版名称：
```powershell
wsl --list --verbose
```
### 验证启动链
重启后（在 Windows 登录前），在 WSL 中检查：
```bash
systemctl --user is-enabled openclaw-gateway
systemctl --user status openclaw-gateway --no-pager
```
## 高级：通过局域网暴露 WSL 服务（portproxy）
WSL 有自己的虚拟网络。如果另一台机器需要访问
**在 WSL 内运行**的服务（SSH、本地 TTS 服务器或 Gateway 网关），你必须
将 Windows 端口转发到当前的 WSL IP。WSL IP 会在重启后变化，
因此你可能需要刷新转发规则。
示例（**以管理员身份**打开 PowerShell）：
```powershell
$Distro = "Ubuntu-24.04"
@ -76,7 +164,7 @@ netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPor
connectaddress=$WslIp connectport=$TargetPort
```
允许端口通过 Windows 防火墙（一次性）：
允许该端口通过 Windows 防火墙（一次性）：
```powershell
New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
@ -91,14 +179,16 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.
connectaddress=$WslIp connectport=$TargetPort | Out-Null
```
注意事项：
说明：
- 从另一台机器 SSH 目标是 **Windows 主机 IP**（示例：`ssh user@windows-host -p 2222`）。
- 远程节点必须指向**可访问的** Gateway 网关 URL（不是 `127.0.0.1`）；使用 `openclaw status --all` 确认。
- 使用 `listenaddress=0.0.0.0` 进行 LAN 访问；`127.0.0.1` 仅保持本地访问。
- 如果你想自动化，注册一个计划任务在登录时运行刷新步骤。
- 来自另一台机器的 SSH 应指向**Windows 主机 IP**（例如：`ssh user@windows-host -p 2222`）。
- 远程节点必须指向**可访问的** Gateway 网关 URL（而不是 `127.0.0.1`）；请使用
`openclaw status --all` 进行确认。
- 使用 `listenaddress=0.0.0.0` 可供局域网访问；`127.0.0.1` 则仅限本地。
- 如果你希望自动执行此操作，请注册一个 Scheduled Task，在登录时运行刷新
步骤。
## WSL2 分步安装
## 分步 WSL2 安装
### 1）安装 WSL2 + Ubuntu
@ -106,14 +196,14 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.
```powershell
wsl --install
# Or pick a distro explicitly:
# 或显式选择一个发行版：
wsl --list --online
wsl --install -d Ubuntu-24.04
```
如果 Windows 要求则重启。
如果 Windows 提示，请重启。
### 2）启用 systemd（Gateway 网关安装所需）
### 2）启用 systemd（Gateway 网关安装所必需）
在你的 WSL 终端中：
@ -124,7 +214,7 @@ systemd=true
EOF
```
然后从 PowerShell：
然后在 PowerShell 中运行：
```powershell
wsl --shutdown
@ -138,13 +228,13 @@ systemctl --user status
### 3）安装 OpenClaw（在 WSL 内）
在 WSL 内按照 Linux 入门指南流程：
在 WSL 内按照 Linux 入门指南流程操作：
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm ui:build # 首次运行时会自动安装 UI 依赖
pnpm build
openclaw onboard
```
@ -153,4 +243,5 @@ openclaw onboard
## Windows 配套应用
我们还没有 Windows 配套应用。如果你想让它实现，欢迎贡献。
我们还没有 Windows 配套应用。如果你想推动这件事发生，欢迎
贡献。

200
docs/zh-CN/providers/anthropic.md
View File

@ -5,31 +5,31 @@ read_when:
summary: 在 OpenClaw 中通过 API 密钥或 setup-token 使用 Anthropic Claude
title: Anthropic
x-i18n:
generated_at: "2026-02-03T10:08:33Z"
model: claude-opus-4-5
provider: pi
source_hash: a78ccd855810a93e71d7138af4d3fc7d66e877349815c4a3207cf2214b0150b3
generated_at: "2026-03-16T06:25:19Z"
model: gpt-5.4
provider: openai
source_hash: b18eff35b652d8dc4b6d55e9051d35682511909b3168be868fa172038294d20b
source_path: providers/anthropic.md
workflow: 15
---
# Anthropic（Claude）
Anthropic 构建了 **Claude** 模型系列，并通过 API 提供访问。
在 OpenClaw 中，你可以使用 API 密钥或 **setup-token** 进行认证。
Anthropic 构建了 **Claude** 模型家族，并通过 API 提供访问。
在 OpenClaw 中，你可以使用 API 密钥或 **setup-token** 进行身份验证。
## 选项 A：Anthropic API 密钥
**适用于：** 标准 API 访问和按用量计费。
在 Anthropic Console 中创建你的 API 密钥。
**最适合：** 标准 API 访问和按使用量计费。
请在 Anthropic Console 中创建你的 API 密钥。
### CLI 设置
```bash
openclaw onboard
# 选择：Anthropic API key
# choose: Anthropic API key
# 或非交互式
# or non-interactive
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
```
@ -38,22 +38,59 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
```json5
{
env: { ANTHROPIC_API_KEY: "sk-ant-..." },
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}
```
## 提示缓存（Anthropic API）
## Thinking 默认值（Claude 4.6）
OpenClaw 支持 Anthropic 的提示缓存功能。这是**仅限 API**；订阅认证不支持缓存设置。
- 当未设置显式 thinking 级别时，Anthropic Claude 4.6 模型在 OpenClaw 中默认使用 `adaptive` thinking。
- 你可以按消息覆盖（`/think:<level>`），或在模型参数中覆盖：
`agents.defaults.models["anthropic/<model>"].params.thinking`。
- 相关 Anthropic 文档：
- [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking)
- [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
## 快速模式（Anthropic API）
OpenClaw 的共享 `/fast` 开关也支持直接 Anthropic API 密钥流量。
- `/fast on` 映射到 `service_tier: "auto"`
- `/fast off` 映射到 `service_tier: "standard_only"`
- 配置默认值：
```json5
{
agents: {
defaults: {
models: {
"anthropic/claude-sonnet-4-5": {
params: { fastMode: true },
},
},
},
},
}
```
重要限制：
- 这**仅适用于 API 密钥**。Anthropic setup-token / OAuth 身份验证不会遵循 OpenClaw 的快速模式层级注入。
- OpenClaw 仅对直接发往 `api.anthropic.com` 的请求注入 Anthropic 服务层级。如果你通过代理或网关路由 `anthropic/*`，`/fast` 不会修改 `service_tier`。
- Anthropic 会在响应中的 `usage.service_tier` 下报告实际生效的层级。对于没有 Priority Tier 容量的账户，`service_tier: "auto"` 仍可能解析为 `standard`。
## Prompt 缓存（Anthropic API）
OpenClaw 支持 Anthropic 的 prompt 缓存功能。这**仅适用于 API**；订阅身份验证不会遵循缓存设置。
### 配置
在模型配置中使用 `cacheRetention` 参数：
在你的模型配置中使用 `cacheRetention` 参数：
| 值 | 缓存时长 | 描述 |
| 值 | 缓存时长 | 说明 |
| ------- | -------- | -------------------------- |
| `none` | 无缓存 | 禁用提示缓存 |
| `short` | 5 分钟 | API 密钥认证的默认值 |
| `none` | 不缓存 | 禁用 prompt 缓存 |
| `short` | 5 分钟 | API 密钥身份验证的默认值 |
| `long` | 1 小时 | 扩展缓存（需要 beta 标志） |
```json5
@ -61,7 +98,7 @@ OpenClaw 支持 Anthropic 的提示缓存功能。这是**仅限 API**；订阅
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-5": {
"anthropic/claude-opus-4-6": {
params: { cacheRetention: "long" },
},
},
@ -72,88 +109,157 @@ OpenClaw 支持 Anthropic 的提示缓存功能。这是**仅限 API**；订阅
### 默认值
使用 Anthropic API 密钥认证时，OpenClaw 会自动为所有 Anthropic 模型应用 `cacheRetention: "short"`（5 分钟缓存）。你可以通过在配置中显式设置 `cacheRetention` 来覆盖此设置。
当使用 Anthropic API 密钥身份验证时，OpenClaw 会自动对所有 Anthropic 模型应用 `cacheRetention: "short"`（5 分钟缓存）。你可以通过在配置中显式设置 `cacheRetention` 来覆盖此行为。
### 每个智能体的 cacheRetention 覆盖
将模型级参数用作基线，然后通过 `agents.list[].params` 覆盖特定智能体。
```json5
{
agents: {
defaults: {
model: { primary: "anthropic/claude-opus-4-6" },
models: {
"anthropic/claude-opus-4-6": {
params: { cacheRetention: "long" }, // 大多数智能体的基线
},
},
},
list: [
{ id: "research", default: true },
{ id: "alerts", params: { cacheRetention: "none" } }, // 仅对该智能体覆盖
],
},
}
```
与缓存相关参数的配置合并顺序：
1. `agents.defaults.models["provider/model"].params`
2. `agents.list[].params`（匹配 `id`，按键覆盖）
这使得一个智能体可以保留长生命周期缓存，而同一模型上的另一个智能体可以禁用缓存，以避免在突发/低复用流量上产生写入成本。
### Bedrock Claude 说明
- 当已配置时，Bedrock 上的 Anthropic Claude 模型（`amazon-bedrock/*anthropic.claude*`）接受透传的 `cacheRetention`。
- 非 Anthropic 的 Bedrock 模型会在运行时被强制设置为 `cacheRetention: "none"`。
- 当未设置显式值时，Anthropic API 密钥的智能默认值也会为 Bedrock 上的 Claude 模型引用填入 `cacheRetention: "short"`。
### 旧版参数
为了向后兼容，仍支持旧版 `cacheControlTtl` 参数：
旧的 `cacheControlTtl` 参数仍受支持，以保持向后兼容：
- `"5m"` 映射到 `short`
- `"1h"` 映射到 `long`
- `"5m"` 映射为 `short`
- `"1h"` 映射为 `long`
我们建议迁移到新的 `cacheRetention` 参数。
OpenClaw 在 Anthropic API 请求中包含 `extended-cache-ttl-2025-04-11` beta 标志；
如果你覆盖提供商头信息，请保留它（参见 [/gateway/configuration](/gateway/configuration)）。
OpenClaw 会在 Anthropic API 请求中包含 `extended-cache-ttl-2025-04-11` beta 标志；
如果你覆盖了提供商请求头，请保留它（参见 [/gateway/configuration](/gateway/configuration)）。
## 1M 上下文窗口（Anthropic beta）
Anthropic 的 1M 上下文窗口受 beta 门控。在 OpenClaw 中，可通过为受支持的 Opus/Sonnet 模型
设置 `params.context1m: true` 按模型启用。
```json5
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": {
params: { context1m: true },
},
},
},
},
}
```
OpenClaw 会将其映射为 Anthropic 请求上的 `anthropic-beta: context-1m-2025-08-07`。
仅当该模型的 `params.context1m` 被显式设置为 `true` 时，
此功能才会激活。
要求：Anthropic 必须允许该凭证使用长上下文
（通常是 API 密钥计费，或启用了 Extra Usage 的订阅账户）。
否则 Anthropic 会返回：
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。
注意：Anthropic 当前在使用
OAuth/订阅令牌（`sk-ant-oat-*`）时会拒绝 `context-1m-*` beta 请求。OpenClaw 会自动跳过
OAuth 身份验证的 `context1m` beta 请求头，并保留所需的 OAuth beta 标志。
## 选项 B：Claude setup-token
**适用于：** 使用你的 Claude 订阅。
**最适合：** 使用你的 Claude 订阅。
### 在哪里获取 setup-token
### 如何获取 setup-token
setup-token 由 **Claude Code CLI** 创建，而不是 Anthropic Console。你可以在**任何机器**上运行：
setup-token 由 **Claude Code CLI** 创建，而不是在 Anthropic Console 中创建。你可以在**任何机器**上运行：
```bash
claude setup-token
```
将令牌粘贴到 OpenClaw（向导：**Anthropic token (paste setup-token)**），或在 Gateway 网关主机上运行：
将该令牌粘贴到 OpenClaw 中（向导：**Anthropic token（粘贴 setup-token）**），或在 Gateway 网关主机上运行：
```bash
openclaw models auth setup-token --provider anthropic
```
如果你在不同的机器上生成了令牌，请粘贴它：
如果你是在另一台机器上生成该令牌，请粘贴它：
```bash
openclaw models auth paste-token --provider anthropic
```
### CLI 设置
### CLI 设置（setup-token）
```bash
# 在新手引导期间粘贴 setup-token
# Paste a setup-token during setup
openclaw onboard --auth-choice setup-token
```
### 配置片段
### 配置片段（setup-token）
```json5
{
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}
```
## 注意事项
## 说明
- 使用 `claude setup-token` 生成 setup-token 并粘贴，或在 Gateway 网关主机上运行 `openclaw models auth setup-token`。
- 如果你在 Claude 订阅上看到"OAuth token refresh failed …"，请使用 setup-token 重新认证。参见 [/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription](/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription)。
- 认证详情 + 重用规则在 [/concepts/oauth](/concepts/oauth)。
- 使用 `claude setup-token` 生成 setup-token 并粘贴它，或者在 Gateway 网关主机上运行 `openclaw models auth setup-token`。
- 如果你在 Claude 订阅上看到 “OAuth token refresh failed …”，请使用 setup-token 重新进行身份验证。请参见 [/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription](/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription)。
- 身份验证详情和复用规则见 [/concepts/oauth](/concepts/oauth)。
## 故障排除
**401 错误/令牌突然失效**
**401 错误 / 令牌突然无效**
- Claude 订阅认证可能过期或被撤销。重新运行 `claude setup-token`
并将其粘贴到 **Gateway 网关主机**。
- 如果 Claude CLI 登录在不同的机器上，在 Gateway 网关主机上使用
- Claude 订阅身份验证可能会过期或被撤销。请重新运行 `claude setup-token`，
并将其粘贴到 **Gateway 网关主机** 上。
- 如果 Claude CLI 登录位于另一台机器上，请在 Gateway 网关主机上使用
`openclaw models auth paste-token --provider anthropic`。
**No API key found for provider "anthropic"**
- 认证是**按智能体**的。新智能体不会继承主智能体的密钥。
- 为该智能体重新运行新手引导，或在 Gateway 网关主机上粘贴 setup-token / API 密钥，
然后使用 `openclaw models status` 验证。
- 身份验证是**按智能体**区分的。新智能体不会继承主智能体的密钥。
- 请为该智能体重新运行新手引导，或在
Gateway 网关主机上粘贴 setup-token / API 密钥，然后使用 `openclaw models status` 验证。
**No credentials found for profile `anthropic:default`**
- 运行 `openclaw models status` 查看哪个认证配置文件处于活动状态。
- 重新运行新手引导，或为该配置文件粘贴 setup-token / API 密钥。
- 运行 `openclaw models status` 查看当前活动的 auth profile。
- 重新运行新手引导，或为该配置档案粘贴 setup-token / API 密钥。
**No available auth profile (all in cooldown/unavailable)**
- 检查 `openclaw models status --json` 中的 `auth.unusableProfiles`。
- 添加另一个 Anthropic 配置文件或等待冷却期结束。
- 添加另一个 Anthropic 配置档案，或等待冷却结束。
更多信息：[/gateway/troubleshooting](/gateway/troubleshooting) 和 [/help/faq](/help/faq)。

78
docs/zh-CN/providers/cloudflare-ai-gateway.md Normal file
View File

@ -0,0 +1,78 @@
---
read_when:
- 你想将 Cloudflare AI Gateway 与 OpenClaw 一起使用
- 你需要 account ID、gateway ID 或 API key 环境变量
summary: Cloudflare AI Gateway 设置（认证 + 模型选择）
title: Cloudflare AI Gateway
x-i18n:
generated_at: "2026-03-16T06:25:05Z"
model: gpt-5.4
provider: openai
source_hash: db77652c37652ca20f7c50f32382dbaeaeb50ea5bdeaf1d4fd17dc394e58950c
source_path: providers/cloudflare-ai-gateway.md
workflow: 15
---
# Cloudflare AI Gateway
Cloudflare AI Gateway 位于提供商 API 前方，让你能够添加分析、缓存和控制功能。对于 Anthropic，OpenClaw 会通过你的 Gateway 端点使用 Anthropic Messages API。
- 提供商：`cloudflare-ai-gateway`
- Base URL：`https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic`
- 默认模型：`cloudflare-ai-gateway/claude-sonnet-4-5`
- API key：`CLOUDFLARE_AI_GATEWAY_API_KEY`（你用于通过 Gateway 发起请求的提供商 API key）
对于 Anthropic 模型，请使用你的 Anthropic API key。
## 快速开始
1. 设置提供商 API key 和 Gateway 详细信息：
```bash
openclaw onboard --auth-choice cloudflare-ai-gateway-api-key
```
2. 设置默认模型：
```json5
{
agents: {
defaults: {
model: { primary: "cloudflare-ai-gateway/claude-sonnet-4-5" },
},
},
}
```
## 非交互式示例
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice cloudflare-ai-gateway-api-key \
--cloudflare-ai-gateway-account-id "your-account-id" \
--cloudflare-ai-gateway-gateway-id "your-gateway-id" \
--cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY"
```
## 已认证的 Gateway
如果你在 Cloudflare 中启用了 Gateway 认证，请添加 `cf-aig-authorization` header（这是在你的提供商 API key 之外额外添加的）。
```json5
{
models: {
providers: {
"cloudflare-ai-gateway": {
headers: {
"cf-aig-authorization": "Bearer <cloudflare-ai-gateway-token>",
},
},
},
},
}
```
## 环境说明
如果 Gateway 作为守护进程运行（launchd/systemd），请确保 `CLOUDFLARE_AI_GATEWAY_API_KEY` 对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。

39
docs/zh-CN/providers/glm.md
View File

@ -1,26 +1,37 @@
---
read_when:
- 你想在 OpenClaw 中使用 GLM 模型
- 你需要了解模型命名规范和设置方法
summary: GLM 模型系列概述 + 如何在 OpenClaw 中使用
title: GLM 模型
- 你需要了解模型命名约定和设置方法
summary: GLM 模型家族概览 + 如何在 OpenClaw 中使用
title: GLM Models
x-i18n:
generated_at: "2026-02-01T21:34:53Z"
model: claude-opus-4-5
provider: pi
source_hash: 2d7b457f033f26f28c230a9cd2310151f825fc52c3ee4fb814d08fd2d022d041
generated_at: "2026-03-16T06:25:10Z"
model: gpt-5.4
provider: openai
source_hash: 061254ebeedec7285d9c0c6e88145f89184ad4ab8d8d6132f1d692c7d3ca03a2
source_path: providers/glm.md
workflow: 15
---
# GLM 模型
GLM 是一个**模型系列**（而非公司），通过 Z.AI 平台提供。在 OpenClaw 中，GLM 模型通过 `zai` 提供商访问，模型 ID 格式如 `zai/glm-4.7`。
GLM 是一个**模型家族**（不是公司），可通过 Z.AI 平台使用。在 OpenClaw 中，GLM
模型通过 `zai` 提供商访问，模型 ID 形式如 `zai/glm-5`。
## CLI 设置
```bash
openclaw onboard --auth-choice zai-api-key
# Coding Plan Global，推荐给 Coding Plan 用户
openclaw onboard --auth-choice zai-coding-global
# Coding Plan CN（中国区域），推荐给 Coding Plan 用户
openclaw onboard --auth-choice zai-coding-cn
# 通用 API
openclaw onboard --auth-choice zai-global
# 通用 API CN（中国区域）
openclaw onboard --auth-choice zai-cn
```
## 配置片段
@ -28,12 +39,12 @@ openclaw onboard --auth-choice zai-api-key
```json5
{
env: { ZAI_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "zai/glm-4.7" } } },
agents: { defaults: { model: { primary: "zai/glm-5" } } },
}
```
## 注意事项
## 说明
- GLM 版本和可用性可能会变化；请查阅 Z.AI 的文档获取最新信息。
- 示例模型 ID 包括 `glm-4.7` 和 `glm-4.6`。
- 有关提供商的详细信息，请参阅 [/providers/zai](/providers/zai)。
- GLM 版本和可用性可能会变化；请查看 Z.AI 的文档以获取最新信息。
- 示例模型 ID 包括 `glm-5`、`glm-4.7` 和 `glm-4.6`。
- 关于提供商详情，请参阅 [/providers/zai](/providers/zai)。

216
docs/zh-CN/providers/huggingface.md Normal file
View File

@ -0,0 +1,216 @@
---
read_when:
- 你想将 Hugging Face Inference 与 OpenClaw 一起使用
- 你需要 HF token 环境变量或 CLI 认证选项
summary: Hugging Face Inference 设置（认证 + 模型选择）
title: Hugging Face（Inference）
x-i18n:
generated_at: "2026-03-16T06:25:40Z"
model: gpt-5.4
provider: openai
source_hash: e62b74915c9a26ab21954abcd9c03442cdd2133fba3371ddb9bcfc3a3458a002
source_path: providers/huggingface.md
workflow: 15
---
# Hugging Face（Inference）
[Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers) 通过单一路由器 API 提供与 OpenAI 兼容的 chat completions。你只需一个 token，即可访问许多模型（DeepSeek、Llama 等）。OpenClaw 使用 **OpenAI 兼容端点**（仅 chat completions）；如果要使用 text-to-image、embeddings 或 speech，请直接使用 [HF inference clients](https://huggingface.co/docs/api-inference/quicktour)。
- 提供商：`huggingface`
- 认证：`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`（带有 **Make calls to Inference Providers** 权限的细粒度 token）
- API：OpenAI 兼容（`https://router.huggingface.co/v1`）
- 计费：单个 HF token；[定价](https://huggingface.co/docs/inference-providers/pricing) 按提供商费率执行，并带有免费层。
## 快速开始
1. 在 [Hugging Face → Settings → Tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained) 创建一个细粒度 token，并授予 **Make calls to Inference Providers** 权限。
2. 运行新手引导，并在提供商下拉菜单中选择 **Hugging Face**，然后在提示时输入你的 API key：
```bash
openclaw onboard --auth-choice huggingface-api-key
```
3. 在 **Default Hugging Face model** 下拉菜单中，选择你想使用的模型（当你有有效 token 时，列表会从 Inference API 加载；否则会显示内置列表）。你的选择会保存为默认模型。
4. 你也可以稍后在配置中设置或更改默认模型：
```json5
{
agents: {
defaults: {
model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
},
},
}
```
## 非交互式示例
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice huggingface-api-key \
--huggingface-api-key "$HF_TOKEN"
```
这会将 `huggingface/deepseek-ai/DeepSeek-R1` 设置为默认模型。
## 环境说明
如果 Gateway 网关作为守护进程运行（launchd/systemd），请确保 `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`
对此进程可用（例如放在 `~/.openclaw/.env` 中，或通过
`env.shellEnv` 提供）。
## 模型发现和新手引导下拉菜单
OpenClaw 通过直接调用 **Inference 端点** 来发现模型：
```bash
GET https://router.huggingface.co/v1/models
```
（可选：发送 `Authorization: Bearer $HUGGINGFACE_HUB_TOKEN` 或 `$HF_TOKEN` 以获取完整列表；某些端点在未认证时只返回子集。）响应采用 OpenAI 风格：`{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }`。
当你配置 Hugging Face API key 时（通过新手引导、`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`），OpenClaw 会使用这个 GET 请求来发现可用的 chat-completion 模型。在**交互式设置**期间，你输入 token 后会看到一个 **Default Hugging Face model** 下拉菜单，其内容来自该列表（如果请求失败，则使用内置目录）。在运行时（例如 Gateway 网关启动时），只要存在 key，OpenClaw 就会再次调用 **GET** `https://router.huggingface.co/v1/models` 来刷新目录。该列表会与内置目录合并（以补充上下文窗口和成本等元数据）。如果请求失败或未设置 key，则只使用内置目录。
## 模型名称和可编辑选项
- **来自 API 的名称：** 当 API 返回 `name`、`title` 或 `display_name` 时，模型显示名称会从 **GET /v1/models** 中补全；否则会从模型 id 推导（例如 `deepseek-ai/DeepSeek-R1` → “DeepSeek R1”）。
- **覆盖显示名称：** 你可以在配置中为每个模型设置自定义标签，使其在 CLI 和 UI 中按你希望的方式显示：
```json5
{
agents: {
defaults: {
models: {
"huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
"huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
},
},
},
}
```
- **提供商 / 策略选择：** 在**模型 id** 后附加后缀，以选择路由器如何挑选后端：
- **`:fastest`** — 最高吞吐量（由路由器选择；提供商选择会被**锁定** —— 不会显示交互式后端选择器）。
- **`:cheapest`** — 每输出 token 成本最低（由路由器选择；提供商选择会被**锁定**）。
- **`:provider`** — 强制使用特定后端（例如 `:sambanova`、`:together`）。
当你选择 **:cheapest** 或 **:fastest** 时（例如在新手引导的模型下拉菜单中），提供商会被锁定：路由器会按成本或速度决定，不会显示可选的“偏好特定后端”步骤。你可以将这些作为单独条目添加到 `models.providers.huggingface.models` 中，或为 `model.primary` 设置带后缀的值。你也可以在 [Inference Provider settings](https://hf.co/settings/inference-providers) 中设置默认顺序（无后缀 = 使用该顺序）。
- **配置合并：** 当配置被合并时，`models.providers.huggingface.models` 中已有的条目（例如在 `models.json` 中）会被保留。因此，你在其中设置的任何自定义 `name`、`alias` 或模型选项都会保留。
## 模型 ID 和配置示例
模型引用使用 `huggingface/<org>/<model>` 形式（Hub 风格 ID）。下面的列表来自 **GET** `https://router.huggingface.co/v1/models`；你的目录中可能包含更多内容。
**示例 ID（来自 inference 端点）：**
| 模型 | 引用（加上 `huggingface/` 前缀） |
| ---------------------- | ----------------------------------- |
| DeepSeek R1 | `deepseek-ai/DeepSeek-R1` |
| DeepSeek V3.2 | `deepseek-ai/DeepSeek-V3.2` |
| Qwen3 8B | `Qwen/Qwen3-8B` |
| Qwen2.5 7B Instruct | `Qwen/Qwen2.5-7B-Instruct` |
| Qwen3 32B | `Qwen/Qwen3-32B` |
| Llama 3.3 70B Instruct | `meta-llama/Llama-3.3-70B-Instruct` |
| Llama 3.1 8B Instruct | `meta-llama/Llama-3.1-8B-Instruct` |
| GPT-OSS 120B | `openai/gpt-oss-120b` |
| GLM 4.7 | `zai-org/GLM-4.7` |
| Kimi K2.5 | `moonshotai/Kimi-K2.5` |
你可以在模型 id 后附加 `:fastest`、`:cheapest` 或 `:provider`（例如 `:together`、`:sambanova`）。请在 [Inference Provider settings](https://hf.co/settings/inference-providers) 中设置默认顺序；完整列表请参阅 [Inference Providers](https://huggingface.co/docs/inference-providers) 和 **GET** `https://router.huggingface.co/v1/models`。
### 完整配置示例
**以 DeepSeek R1 为主模型，Qwen 作为回退：**
```json5
{
agents: {
defaults: {
model: {
primary: "huggingface/deepseek-ai/DeepSeek-R1",
fallbacks: ["huggingface/Qwen/Qwen3-8B"],
},
models: {
"huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
"huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
},
},
},
}
```
**以 Qwen 为默认模型，并包含 `:cheapest` 和 `:fastest` 变体：**
```json5
{
agents: {
defaults: {
model: { primary: "huggingface/Qwen/Qwen3-8B" },
models: {
"huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
"huggingface/Qwen/Qwen3-8B:cheapest": { alias: "Qwen3 8B（最便宜）" },
"huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B（最快）" },
},
},
},
}
```
**带有别名的 DeepSeek + Llama + GPT-OSS：**
```json5
{
agents: {
defaults: {
model: {
primary: "huggingface/deepseek-ai/DeepSeek-V3.2",
fallbacks: [
"huggingface/meta-llama/Llama-3.3-70B-Instruct",
"huggingface/openai/gpt-oss-120b",
],
},
models: {
"huggingface/deepseek-ai/DeepSeek-V3.2": { alias: "DeepSeek V3.2" },
"huggingface/meta-llama/Llama-3.3-70B-Instruct": { alias: "Llama 3.3 70B" },
"huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
},
},
},
}
```
**使用 `:provider` 强制指定特定后端：**
```json5
{
agents: {
defaults: {
model: { primary: "huggingface/deepseek-ai/DeepSeek-R1:together" },
models: {
"huggingface/deepseek-ai/DeepSeek-R1:together": { alias: "DeepSeek R1 (Together)" },
},
},
},
}
```
**多个 Qwen 和 DeepSeek 模型，带策略后缀：**
```json5
{
agents: {
defaults: {
model: { primary: "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest" },
models: {
"huggingface/Qwen/Qwen2.5-7B-Instruct": { alias: "Qwen2.5 7B" },
"huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest": { alias: "Qwen2.5 7B（便宜）" },
"huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1（快速）" },
"huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
},
},
},
}
```

46
docs/zh-CN/providers/index.md
View File

@ -1,41 +1,33 @@
---
read_when:
- 你想选择一个模型提供商
- 你需要快速了解支持的 LLM 后端
- 你需要支持的 LLM 后端的快速概览
summary: OpenClaw 支持的模型提供商（LLM）
title: 模型提供商
x-i18n:
generated_at: "2026-02-03T07:53:32Z"
model: claude-opus-4-5
provider: pi
source_hash: eb4a97438adcf610499253afcf8b2af6624f4be098df389a6c3746f14c4a901b
generated_at: "2026-03-16T06:25:28Z"
model: gpt-5.4
provider: openai
source_hash: 1d7ba79fd152a978e6eb3b8f8d5dfc44cebba77d2c74dc3892aae917d32ad2ee
source_path: providers/index.md
workflow: 15
---
# 模型提供商
OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，进行认证，然后将默认模型设置为 `provider/model`。
OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份验证，然后将
默认模型设置为 `provider/model`。
正在寻找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）等）？参见[渠道](/channels)。
## 亮点：Venice（Venice AI）
Venice 是我们推荐的 Venice AI 设置，用于隐私优先的推理，并可选择使用 Opus 处理困难任务。
- 默认：`venice/llama-3.3-70b`
- 最佳综合：`venice/claude-opus-45`（Opus 仍然是最强的）
参见 [Venice AI](/providers/venice)。
在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/等）？请参见 [Channels](/channels)。
## 快速开始
1. 与提供商进行认证（通常通过 `openclaw onboard`）。
1. 使用该提供商进行身份验证（通常通过 `openclaw onboard`）。
2. 设置默认模型：
```json5
{
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}
```
@ -43,15 +35,25 @@ Venice 是我们推荐的 Venice AI 设置，用于隐私优先的推理，并
- [Amazon Bedrock](/providers/bedrock)
- [Anthropic（API + Claude Code CLI）](/providers/anthropic)
- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
- [GLM 模型](/providers/glm)
- [Hugging Face（Inference）](/providers/huggingface)
- [Kilocode](/providers/kilocode)
- [LiteLLM（统一网关）](/providers/litellm)
- [MiniMax](/providers/minimax)
- [Mistral](/providers/mistral)
- [Moonshot AI（Kimi + Kimi Coding）](/providers/moonshot)
- [Ollama（本地模型）](/providers/ollama)
- [NVIDIA](/providers/nvidia)
- [Ollama（云端 + 本地模型）](/providers/ollama)
- [OpenAI（API + Codex）](/providers/openai)
- [OpenCode Zen](/providers/opencode)
- [OpenCode（Zen + Go）](/providers/opencode)
- [OpenRouter](/providers/openrouter)
- [Qianfan](/providers/qianfan)
- [Qwen（OAuth）](/providers/qwen)
- [Together AI](/providers/together)
- [Vercel AI Gateway](/providers/vercel-ai-gateway)
- [Venice（Venice AI，注重隐私）](/providers/venice)
- [vLLM（本地模型）](/providers/vllm)
- [Xiaomi](/providers/xiaomi)
- [Z.AI](/providers/zai)
@ -61,7 +63,7 @@ Venice 是我们推荐的 Venice AI 设置，用于隐私优先的推理，并
## 社区工具
- [Claude Max API Proxy](/providers/claude-max-api-proxy) - 将 Claude Max/Pro 订阅作为 OpenAI 兼容的 API 端点使用
- [Claude Max API Proxy](/providers/claude-max-api-proxy) - 面向 Claude 订阅凭证的社区代理（使用前请核实 Anthropic 政策/条款）
有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，
参见[模型提供商](/concepts/model-providers)。
请参见 [模型提供商](/concepts/model-providers)。

80
docs/zh-CN/providers/kilocode.md Normal file
View File

@ -0,0 +1,80 @@
---
read_when:
- 你想用一个 API 密钥访问多种 LLM
- 你想在 OpenClaw 中通过 Kilo Gateway 运行模型
summary: 使用 Kilo Gateway 的统一 API 在 OpenClaw 中访问多种模型
x-i18n:
generated_at: "2026-03-16T06:25:35Z"
model: gpt-5.4
provider: openai
source_hash: acd4c29496abc1ef8d4da6c48575763dfe3b4c1319874f900532223ac3775257
source_path: providers/kilocode.md
workflow: 15
---
# Kilo Gateway
Kilo Gateway 提供一个**统一 API**，可通过单一
端点和 API 密钥将请求路由到多种模型。它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换基础 URL 即可使用。
## 获取 API 密钥
1. 前往 [app.kilo.ai](https://app.kilo.ai)
2. 登录或创建账户
3. 进入 API Keys 并生成一个新密钥
## CLI 设置
```bash
openclaw onboard --kilocode-api-key <key>
```
或者设置环境变量：
```bash
export KILOCODE_API_KEY="<your-kilocode-api-key>" # pragma: allowlist secret
```
## 配置片段
```json5
{
env: { KILOCODE_API_KEY: "<your-kilocode-api-key>" }, // pragma: allowlist secret
agents: {
defaults: {
model: { primary: "kilocode/kilo/auto" },
},
},
}
```
## 默认模型
默认模型是 `kilocode/kilo/auto`，这是一个智能路由模型，会根据任务自动选择
最佳的底层模型：
- 规划、调试和编排任务会路由到 Claude Opus
- 代码编写和探索任务会路由到 Claude Sonnet
## 可用模型
OpenClaw 会在启动时从 Kilo Gateway 动态发现可用模型。使用
`/models kilocode` 查看你的账户可用的完整模型列表。
Gateway 网关上任何可用的模型都可以使用 `kilocode/` 前缀：
```
kilocode/kilo/auto (default - smart routing)
kilocode/anthropic/claude-sonnet-4
kilocode/openai/gpt-5.2
kilocode/google/gemini-3-pro-preview
...and many more
```
## 说明
- 模型引用格式为 `kilocode/<model-id>`（例如 `kilocode/anthropic/claude-sonnet-4`）。
- 默认模型：`kilocode/kilo/auto`
- 基础 URL：`https://api.kilo.ai/api/gateway/`
- 更多模型/提供商选项，请参见 [/concepts/model-providers](/concepts/model-providers)。
- Kilo Gateway 在底层使用带有你的 API 密钥的 Bearer token。

160
docs/zh-CN/providers/litellm.md Normal file
View File

@ -0,0 +1,160 @@
---
read_when:
- 你想通过 LiteLLM 代理路由 OpenClaw
- 你需要通过 LiteLLM 进行成本跟踪、日志记录或模型路由
summary: 通过 LiteLLM Proxy 运行 OpenClaw，以实现统一模型访问和成本跟踪
x-i18n:
generated_at: "2026-03-16T06:25:50Z"
model: gpt-5.4
provider: openai
source_hash: 269529671c60864972441606c730b5ca327546a45d3b264dbd03204c4401936f
source_path: providers/litellm.md
workflow: 15
---
# LiteLLM
[LiteLLM](https://litellm.ai) 是一个开源 LLM 网关，可为 100+ 模型提供商提供统一 API。通过 LiteLLM 路由 OpenClaw，你可以获得集中式成本跟踪、日志记录，以及在不更改 OpenClaw 配置的情况下切换后端的灵活性。
## 为什么要将 LiteLLM 与 OpenClaw 搭配使用？
- **成本跟踪** —— 精确查看 OpenClaw 在所有模型上的花费
- **模型路由** —— 无需更改配置，即可在 Claude、GPT-4、Gemini、Bedrock 之间切换
- **虚拟密钥** —— 为 OpenClaw 创建带有支出限制的密钥
- **日志记录** —— 提供完整的请求/响应日志，便于调试
- **回退** —— 如果你的主要提供商宕机，可自动故障切换
## 快速开始
### 通过新手引导
```bash
openclaw onboard --auth-choice litellm-api-key
```
### 手动设置
1. 启动 LiteLLM Proxy：
```bash
pip install 'litellm[proxy]'
litellm --model claude-opus-4-6
```
2. 将 OpenClaw 指向 LiteLLM：
```bash
export LITELLM_API_KEY="your-litellm-key"
openclaw
```
就是这样。OpenClaw 现在会通过 LiteLLM 进行路由。
## 配置
### 环境变量
```bash
export LITELLM_API_KEY="sk-litellm-key"
```
### 配置文件
```json5
{
models: {
providers: {
litellm: {
baseUrl: "http://localhost:4000",
apiKey: "${LITELLM_API_KEY}",
api: "openai-completions",
models: [
{
id: "claude-opus-4-6",
name: "Claude Opus 4.6",
reasoning: true,
input: ["text", "image"],
contextWindow: 200000,
maxTokens: 64000,
},
{
id: "gpt-4o",
name: "GPT-4o",
reasoning: false,
input: ["text", "image"],
contextWindow: 128000,
maxTokens: 8192,
},
],
},
},
},
agents: {
defaults: {
model: { primary: "litellm/claude-opus-4-6" },
},
},
}
```
## 虚拟密钥
为 OpenClaw 创建一个带支出限制的专用密钥：
```bash
curl -X POST "http://localhost:4000/key/generate" \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"key_alias": "openclaw",
"max_budget": 50.00,
"budget_duration": "monthly"
}'
```
将生成的密钥用作 `LITELLM_API_KEY`。
## 模型路由
LiteLLM 可以将模型请求路由到不同后端。在你的 LiteLLM `config.yaml` 中进行配置：
```yaml
model_list:
- model_name: claude-opus-4-6
litellm_params:
model: claude-opus-4-6
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: gpt-4o
litellm_params:
model: gpt-4o
api_key: os.environ/OPENAI_API_KEY
```
OpenClaw 会继续请求 `claude-opus-4-6` —— 路由由 LiteLLM 处理。
## 查看使用情况
检查 LiteLLM 的仪表板或 API：
```bash
# 密钥信息
curl "http://localhost:4000/key/info" \
-H "Authorization: Bearer sk-litellm-key"
# 支出日志
curl "http://localhost:4000/spend/logs" \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"
```
## 说明
- LiteLLM 默认运行在 `http://localhost:4000`
- OpenClaw 通过兼容 OpenAI 的 `/v1/chat/completions` 端点连接
- 所有 OpenClaw 功能都可通过 LiteLLM 使用 —— 没有限制
## 另请参见
- [LiteLLM 文档](https://docs.litellm.ai)
- [模型提供商](/concepts/model-providers)

156
docs/zh-CN/providers/minimax.md
View File

@ -2,75 +2,78 @@
read_when:
- 你想在 OpenClaw 中使用 MiniMax 模型
- 你需要 MiniMax 设置指南
summary: 在 OpenClaw 中使用 MiniMax M2.1
summary: 在 OpenClaw 中使用 MiniMax M2.5
title: MiniMax
x-i18n:
generated_at: "2026-02-03T10:08:52Z"
model: claude-opus-4-5
provider: pi
source_hash: 861e1ddc3c24be88f716bfb72d6015d62875a9087f8e89ea4ba3a35f548c7fae
generated_at: "2026-03-16T06:26:04Z"
model: gpt-5.4
provider: openai
source_hash: ffed28de9ecc5a1d2ad9f18adc08dd9cf39df40674b14c7ef078b16c92faacf2
source_path: providers/minimax.md
workflow: 15
---
# MiniMax
MiniMax 是一家构建 **M2/M2.1** 模型系列的 AI 公司。当前面向编程的版本是 **MiniMax M2.1**（2025 年 12 月 23 日），专为现实世界的复杂任务而构建。
MiniMax 是一家 AI 公司，构建了 **M2/M2.5** 模型家族。当前
面向编码的版本是 **MiniMax M2.5**（2025 年 12 月 23 日），专为
现实世界中的复杂任务打造。
来源：[MiniMax M2.1 发布说明](https://www.minimax.io/news/minimax-m21)
来源：[MiniMax M2.5 发布说明](https://www.minimax.io/news/minimax-m25)
## 模型概述（M2.1）
## 模型概览（M2.5）
MiniMax 强调 M2.1 的以下改进：
MiniMax 在 M2.5 中重点强调了以下改进：
- 更强的**多语言编程**能力（Rust、Java、Go、C++、Kotlin、Objective-C、TS/JS）。
- 更好的 **Web/应用开发**和美观输出质量（包括原生移动端）。
- 改进的**复合指令**处理，适用于办公风格的工作流程，基于交错思考和集成约束执行。
- **更简洁的响应**，更低的 token 使用量和更快的迭代循环。
- 更强的**工具/智能体框架**兼容性和上下文管理（Claude Code、Droid/Factory AI、Cline、Kilo Code、Roo Code、BlackBox）。
- 更强的**多语言编码**能力（Rust、Java、Go、C++、Kotlin、Objective-C、TS/JS）。
- 更好的**Web/应用开发**和美学输出质量（包括原生移动端）。
- 在交错思考和集成约束执行的基础上，改进了面向办公类工作流的**复合指令**处理。
- **更简洁的响应**，token 使用量更低，迭代循环更快。
- 更强的**工具/智能体框架**兼容性和上下文管理能力（Claude Code、
Droid/Factory AI、Cline、Kilo Code、Roo Code、BlackBox）。
- 更高质量的**对话和技术写作**输出。
## MiniMax M2.1 vs MiniMax M2.1 Lightning
## MiniMax M2.5 与 MiniMax M2.5 Highspeed
- **速度：** Lightning 是 MiniMax 定价文档中的"快速"变体。
- **成本：** 定价显示相同的输入成本，但 Lightning 的输出成本更高。
- **编程计划路由：** Lightning 后端在 MiniMax 编程计划中不能直接使用。MiniMax 自动将大多数请求路由到 Lightning，但在流量高峰期会回退到常规 M2.1 后端。
- **速度：** `MiniMax-M2.5-highspeed` 是 MiniMax 文档中的官方高速层级。
- **成本：** MiniMax 定价显示，高速版的输入成本相同，而输出成本更高。
- **当前模型 ID：** 使用 `MiniMax-M2.5` 或 `MiniMax-M2.5-highspeed`。
## 选择设置方式
## 选择一种设置方式
### MiniMax OAuth（编程计划）— 推荐
### MiniMax OAuth（Coding Plan）—— 推荐
**适用于：** 通过 OAuth 快速设置 MiniMax 编程计划，无需 API 密钥。
**最适合：** 通过 OAuth 使用 MiniMax Coding Plan 快速设置，无需 API key。
启用内置 OAuth 插件并进行认证：
启用内置 OAuth 插件并完成认证：
```bash
openclaw plugins enable minimax-portal-auth # 如果已加载则跳过
openclaw gateway restart # 如果 Gateway 网关已在运行则重启
openclaw plugins enable minimax # 如果已加载则跳过。
openclaw gateway restart # 如果 gateway 已在运行，则重启
openclaw onboard --auth-choice minimax-portal
```
系统会提示你选择端点：
系统会提示你选择一个端点：
- **Global** - 国际用户（`api.minimax.io`）
- **CN** - 中国用户（`api.minimaxi.com`）
详情参见 [MiniMax OAuth 插件 README](https://github.com/openclaw/openclaw/tree/main/extensions/minimax-portal-auth)。
详情请参阅 [MiniMax plugin README](https://github.com/openclaw/openclaw/tree/main/extensions/minimax)。
### MiniMax M2.1（API 密钥）
### MiniMax M2.5（API key）
**适用于：** 使用 Anthropic 兼容 API 的托管 MiniMax。
**最适合：** 使用与 Anthropic 兼容 API 的托管 MiniMax。
通过 CLI 配置：
- 运行 `openclaw configure`
- 选择 **Model/auth**
- 选择 **MiniMax M2.1**
- 选择 **MiniMax M2.5**
```json5
{
env: { MINIMAX_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "minimax/MiniMax-M2.1" } } },
agents: { defaults: { model: { primary: "minimax/MiniMax-M2.5" } } },
models: {
mode: "merge",
providers: {
@ -80,11 +83,20 @@ openclaw onboard --auth-choice minimax-portal
api: "anthropic-messages",
models: [
{
id: "MiniMax-M2.1",
name: "MiniMax M2.1",
reasoning: false,
id: "MiniMax-M2.5",
name: "MiniMax M2.5",
reasoning: true,
input: ["text"],
cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.12 },
contextWindow: 200000,
maxTokens: 8192,
},
{
id: "MiniMax-M2.5-highspeed",
name: "MiniMax M2.5 Highspeed",
reasoning: true,
input: ["text"],
cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.12 },
contextWindow: 200000,
maxTokens: 8192,
},
@ -95,9 +107,10 @@ openclaw onboard --auth-choice minimax-portal
}
```
### MiniMax M2.1 作为备用（Opus 为主）
### 将 MiniMax M2.5 作为回退模型（示例）
**适用于：** 保持 Opus 4.5 为主模型，故障时切换到 MiniMax M2.1。
**最适合：** 保持你最强的最新一代模型作为主模型，并在失败时回退到 MiniMax M2.5。
下面的示例使用 Opus 作为具体主模型；你可以替换成自己偏好的最新一代主模型。
```json5
{
@ -105,12 +118,12 @@ openclaw onboard --auth-choice minimax-portal
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-5": { alias: "opus" },
"minimax/MiniMax-M2.1": { alias: "minimax" },
"anthropic/claude-opus-4-6": { alias: "primary" },
"minimax/MiniMax-M2.5": { alias: "minimax" },
},
model: {
primary: "anthropic/claude-opus-4-5",
fallbacks: ["minimax/MiniMax-M2.1"],
primary: "anthropic/claude-opus-4-6",
fallbacks: ["minimax/MiniMax-M2.5"],
},
},
},
@ -119,8 +132,8 @@ openclaw onboard --auth-choice minimax-portal
### 可选：通过 LM Studio 本地运行（手动）
**适用于：** 使用 LM Studio 进行本地推理。
我们在强大硬件（例如台式机/服务器）上使用 LM Studio 的本地服务器运行 MiniMax M2.1 时看到了出色的效果。
**最适合：** 通过 LM Studio 进行本地推理。
我们已经看到，在强力硬件上（例如台式机/服务器）使用 LM Studio 的本地服务器运行 MiniMax M2.5 时，效果非常强。
通过 `openclaw.json` 手动配置：
@ -128,8 +141,8 @@ openclaw onboard --auth-choice minimax-portal
{
agents: {
defaults: {
model: { primary: "lmstudio/minimax-m2.1-gs32" },
models: { "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" } },
model: { primary: "lmstudio/minimax-m2.5-gs32" },
models: { "lmstudio/minimax-m2.5-gs32": { alias: "Minimax" } },
},
},
models: {
@ -141,9 +154,9 @@ openclaw onboard --auth-choice minimax-portal
api: "openai-responses",
models: [
{
id: "minimax-m2.1-gs32",
name: "MiniMax M2.1 GS32",
reasoning: false,
id: "minimax-m2.5-gs32",
name: "MiniMax M2.5 GS32",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 196608,
@ -158,48 +171,51 @@ openclaw onboard --auth-choice minimax-portal
## 通过 `openclaw configure` 配置
使用交互式配置向导设置 MiniMax，无需编辑 JSON：
使用交互式配置向导设置 MiniMax，而无需编辑 JSON：
1. 运行 `openclaw configure`。
2. 选择 **Model/auth**。
3. 选择 **MiniMax M2.1**。
3. 选择 **MiniMax M2.5**。
4. 在提示时选择你的默认模型。
## 配置选项
- `models.providers.minimax.baseUrl`：推荐使用 `https://api.minimax.io/anthropic`（Anthropic 兼容）；`https://api.minimax.io/v1` 可选用于 OpenAI 兼容的负载。
- `models.providers.minimax.api`：推荐使用 `anthropic-messages`；`openai-completions` 可选用于 OpenAI 兼容的负载。
- `models.providers.minimax.apiKey`：MiniMax API 密钥（`MINIMAX_API_KEY`）。
- `models.providers.minimax.baseUrl`：优先使用 `https://api.minimax.io/anthropic`（与 Anthropic 兼容）；`https://api.minimax.io/v1` 可选，用于与 OpenAI 兼容的负载。
- `models.providers.minimax.api`：优先使用 `anthropic-messages`；`openai-completions` 可选，用于与 OpenAI 兼容的负载。
- `models.providers.minimax.apiKey`：MiniMax API key（`MINIMAX_API_KEY`）。
- `models.providers.minimax.models`：定义 `id`、`name`、`reasoning`、`contextWindow`、`maxTokens`、`cost`。
- `agents.defaults.models`：为你想要在允许列表中的模型设置别名。
- `models.mode`：如果你想将 MiniMax 与内置模型一起添加，保持 `merge`。
- `agents.defaults.models`：为你希望放入允许列表的模型设置别名。
- `models.mode`：如果你希望在内置模型之外添加 MiniMax，请保持为 `merge`。
## 注意事项
## 说明
- 模型引用格式为 `minimax/<model>`。
- 编程计划使用量 API：`https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains`（需要编程计划密钥）。
- 如果需要精确的成本跟踪，请更新 `models.json` 中的定价值。
- MiniMax 编程计划推荐链接（9 折优惠）：https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link
- 参见 [/concepts/model-providers](/concepts/model-providers) 了解提供商规则。
- 使用 `openclaw models list` 和 `openclaw models set minimax/MiniMax-M2.1` 切换模型。
- 推荐模型 ID：`MiniMax-M2.5` 和 `MiniMax-M2.5-highspeed`。
- Coding Plan 用量 API：`https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains`（需要 coding plan key）。
- 如果你需要精确成本跟踪，请更新 `models.json` 中的定价值。
- MiniMax Coding Plan 推荐链接（九折）：[https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
- 关于提供商规则，请参阅 [/concepts/model-providers](/concepts/model-providers)。
- 使用 `openclaw models list` 和 `openclaw models set minimax/MiniMax-M2.5` 进行切换。
## 故障排除
### "Unknown model: minimax/MiniMax-M2.1"
### “Unknown model: minimax/MiniMax-M2.5”
这通常意味着 **MiniMax 提供商未配置**（没有提供商条目，也没有找到 MiniMax 认证配置文件/环境变量密钥）。此检测的修复在 **2026.1.12** 中（撰写本文时尚未发布）。修复方法：
这通常意味着 **MiniMax 提供商未配置**（没有提供商条目，
并且也未找到 MiniMax 凭证配置文件/环境变量 key）。对此检测问题的修复已包含在
**2026.1.12** 中（在撰写本文时尚未发布）。修复方法：
- 升级到 **2026.1.12**（或从源码 `main` 分支运行），然后重启 Gateway 网关。
- 运行 `openclaw configure` 并选择 **MiniMax M2.1**，或
- 手动添加 `models.providers.minimax` 块，或
- 设置 `MINIMAX_API_KEY`（或 MiniMax 认证配置文件）以便注入提供商。
- 升级到 **2026.1.12**（或从源码运行 `main`），然后重启 gateway。
- 运行 `openclaw configure` 并选择 **MiniMax M2.5**，或者
- 手动添加 `models.providers.minimax` 配置块，或者
- 设置 `MINIMAX_API_KEY`（或 MiniMax 凭证配置文件），以便注入该提供商。
确保模型 id **区分大小写**：
请确保模型 id **区分大小写**：
- `minimax/MiniMax-M2.1`
- `minimax/MiniMax-M2.1-lightning`
- `minimax/MiniMax-M2.5`
- `minimax/MiniMax-M2.5-highspeed`
然后重新检查：
然后使用以下命令重新检查：
```bash
openclaw models list

61
docs/zh-CN/providers/mistral.md Normal file
View File

@ -0,0 +1,61 @@
---
read_when:
- 你想在 OpenClaw 中使用 Mistral 模型
- 你需要 Mistral API 密钥新手引导和模型引用
summary: 在 OpenClaw 中使用 Mistral 模型和 Voxtral 转录
title: Mistral
x-i18n:
generated_at: "2026-03-16T06:25:57Z"
model: gpt-5.4
provider: openai
source_hash: 4f3efe060cbaeb14e20439ade040e57d27e7d98fb9dd06e657f6a69ae808f24f
source_path: providers/mistral.md
workflow: 15
---
# Mistral
OpenClaw 支持 Mistral，用于文本/图像模型路由（`mistral/...`）以及
通过媒体理解中的 Voxtral 进行音频转录。
Mistral 还可用于记忆嵌入（`memorySearch.provider = "mistral"`）。
## CLI 设置
```bash
openclaw onboard --auth-choice mistral-api-key
# or non-interactive
openclaw onboard --mistral-api-key "$MISTRAL_API_KEY"
```
## 配置片段（LLM 提供商）
```json5
{
env: { MISTRAL_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "mistral/mistral-large-latest" } } },
}
```
## 配置片段（使用 Voxtral 进行音频转录）
```json5
{
tools: {
media: {
audio: {
enabled: true,
models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
},
},
},
}
```
## 说明
- Mistral 身份验证使用 `MISTRAL_API_KEY`。
- 提供商基础 URL 默认为 `https://api.mistral.ai/v1`。
- 新手引导默认模型为 `mistral/mistral-large-latest`。
- Mistral 的媒体理解默认音频模型为 `voxtral-mini-latest`。
- 媒体转录路径使用 `/v1/audio/transcriptions`。
- 记忆嵌入路径使用 `/v1/embeddings`（默认模型：`mistral-embed`）。

40
docs/zh-CN/providers/models.md
View File

@ -1,55 +1,51 @@
---
read_when:
- 你想选择一个模型提供商
- 你想要 LLM 认证 + 模型选择的快速设置示例
- 你想要 LLM 身份验证 + 模型选择的快速设置示例
summary: OpenClaw 支持的模型提供商（LLM）
title: 模型提供商快速入门
title: 模型提供商快速开始
x-i18n:
generated_at: "2026-02-03T07:53:35Z"
model: claude-opus-4-5
provider: pi
source_hash: 2f5b99207dc7860e0a7b541b61e984791f5d7ab1953b3e917365a248a09b025b
generated_at: "2026-03-16T06:26:02Z"
model: gpt-5.4
provider: openai
source_hash: 7a868ba56e93e6332f0e9dd3d3e2c79a08f369dbc96c400dfba141f347d40e8f
source_path: providers/models.md
workflow: 15
---
# 模型提供商
OpenClaw 可以使用许多 LLM 提供商。选择一个，进行认证，然后将默认模型设置为 `provider/model`。
OpenClaw 可以使用许多 LLM 提供商。选择一个，完成身份验证，然后将默认
模型设置为 `provider/model`。
## 推荐：Venice（Venice AI）
## 快速开始（两步）
Venice 是我们推荐的 Venice AI 设置，用于隐私优先的推理，并可选择使用 Opus 处理最困难的任务。
- 默认：`venice/llama-3.3-70b`
- 最佳综合：`venice/claude-opus-45`（Opus 仍然是最强的）
参见 [Venice AI](/providers/venice)。
## 快速开始（两个步骤）
1. 与提供商认证（通常通过 `openclaw onboard`）。
1. 使用该提供商进行身份验证（通常通过 `openclaw onboard`）。
2. 设置默认模型：
```json5
{
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}
```
## 支持的提供商（入门集）
## 支持的提供商（入门集合）
- [OpenAI（API + Codex）](/providers/openai)
- [Anthropic（API + Claude Code CLI）](/providers/anthropic)
- [OpenRouter](/providers/openrouter)
- [Vercel AI Gateway](/providers/vercel-ai-gateway)
- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
- [Moonshot AI（Kimi + Kimi Coding）](/providers/moonshot)
- [Mistral](/providers/mistral)
- [Synthetic](/providers/synthetic)
- [OpenCode Zen](/providers/opencode)
- [OpenCode（Zen + Go）](/providers/opencode)
- [Z.AI](/providers/zai)
- [GLM 模型](/providers/glm)
- [MiniMax](/providers/minimax)
- [Venice（Venice AI）](/providers/venice)
- [Amazon Bedrock](/providers/bedrock)
- [Qianfan](/providers/qianfan)
有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅[模型提供商](/concepts/model-providers)。
有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，
请参见 [模型提供商](/concepts/model-providers)。

69
docs/zh-CN/providers/moonshot.md
View File

@ -1,32 +1,36 @@
---
read_when:
- 你想了解 Moonshot K2（Moonshot 开放平台）与 Kimi Coding 的配置
- 你需要了解独立的端点、密钥和模型引用
- 你想获取任一提供商的可复制粘贴配置
summary: 配置 Moonshot K2 与 Kimi Coding（独立提供商和密钥）
- 你想了解 Moonshot K2（Moonshot Open Platform）与 Kimi Coding 的设置方式
- 你需要理解独立的端点、密钥和模型引用
- 你想要任一提供商的可直接复制粘贴配置
summary: 配置 Moonshot K2 与 Kimi Coding（独立提供商 + 密钥）
title: Moonshot AI
x-i18n:
generated_at: "2026-02-01T21:35:13Z"
model: claude-opus-4-5
provider: pi
source_hash: 2de81b1a37a0e6e61e0e142fcd36760ecd00834e107dc9b5e38bbf971b27e18e
generated_at: "2026-03-16T06:26:20Z"
model: gpt-5.4
provider: openai
source_hash: f95e6ffa9397e0c2bdbc247e6fb6f2892ca6a34b276ca9b773e6b875233539e3
source_path: providers/moonshot.md
workflow: 15
---
# Moonshot AI (Kimi)
# Moonshot AI（Kimi）
Moonshot 提供兼容 OpenAI 端点的 Kimi API。配置提供商并将默认模型设置为 `moonshot/kimi-k2.5`，或使用 Kimi Coding 的 `kimi-coding/k2p5`。
Moonshot 提供带有 OpenAI 兼容端点的 Kimi API。配置该
提供商，并将默认模型设置为 `moonshot/kimi-k2.5`，或者使用
`kimi-coding/k2p5` 作为 Kimi Coding。
当前 Kimi K2 模型 ID：
{/_ moonshot-kimi-k2-ids:start _/}
[//]: # "moonshot-kimi-k2-ids:start"
- `kimi-k2.5`
- `kimi-k2-0905-preview`
- `kimi-k2-turbo-preview`
- `kimi-k2-thinking`
- `kimi-k2-thinking-turbo`
{/_ moonshot-kimi-k2-ids:end _/}
[//]: # "moonshot-kimi-k2-ids:end"
```bash
openclaw onboard --auth-choice moonshot-api-key
@ -38,7 +42,7 @@ Kimi Coding：
openclaw onboard --auth-choice kimi-code-api-key
```
注意：Moonshot 和 Kimi Coding 是独立的提供商。密钥不可互换，端点不同，模型引用也不同（Moonshot 使用 `moonshot/...`，Kimi Coding 使用 `kimi-coding/...`）。
注意：Moonshot 和 Kimi Coding 是独立提供商。密钥不可互换，端点不同，模型引用也不同（Moonshot 使用 `moonshot/...`，Kimi Coding 使用 `kimi-coding/...`）。
## 配置片段（Moonshot API）
@ -137,9 +141,42 @@ openclaw onboard --auth-choice kimi-code-api-key
}
```
## 注意事项
## 说明
- Moonshot 模型引用使用 `moonshot/<modelId>`。Kimi Coding 模型引用使用 `kimi-coding/<modelId>`。
- 如有需要，可在 `models.providers` 中覆盖定价和上下文元数据。
- 如果 Moonshot 发布了某个模型的不同上下文限制，请相应调整 `contextWindow`。
- 如需使用中国端点，请使用 `https://api.moonshot.cn/v1`。
- 如果 Moonshot 为某个模型发布了不同的上下文限制，请相应调整
`contextWindow`。
- 国际端点使用 `https://api.moonshot.ai/v1`，中国端点使用 `https://api.moonshot.cn/v1`。
## 原生 thinking 模式（Moonshot）
Moonshot Kimi 支持二元原生 thinking：
- `thinking: { type: "enabled" }`
- `thinking: { type: "disabled" }`
通过 `agents.defaults.models.<provider/model>.params` 为每个模型进行配置：
```json5
{
agents: {
defaults: {
models: {
"moonshot/kimi-k2.5": {
params: {
thinking: { type: "disabled" },
},
},
},
},
},
}
```
OpenClaw 还会为 Moonshot 映射运行时 `/think` 级别：
- `/think off` -> `thinking.type=disabled`
- 任何非 off 的 thinking 级别 -> `thinking.type=enabled`
当启用 Moonshot thinking 时，`tool_choice` 必须为 `auto` 或 `none`。为保持兼容性，OpenClaw 会将不兼容的 `tool_choice` 值标准化为 `auto`。

62
docs/zh-CN/providers/nvidia.md Normal file
View File

@ -0,0 +1,62 @@
---
read_when:
- 你想在 OpenClaw 中使用 NVIDIA 模型
- 你需要设置 `NVIDIA_API_KEY`
summary: 在 OpenClaw 中使用 NVIDIA 的 OpenAI 兼容 API
title: NVIDIA
x-i18n:
generated_at: "2026-03-16T06:26:11Z"
model: gpt-5.4
provider: openai
source_hash: 81e7a1b6cd6821b68db9c71b864d36023b1ccfad1641bf88e2bc2957782edf8b
source_path: providers/nvidia.md
workflow: 15
---
# NVIDIA
NVIDIA 在 `https://integrate.api.nvidia.com/v1` 提供一个与 OpenAI 兼容的 API，用于 Nemotron 和 NeMo 模型。请使用来自 [NVIDIA NGC](https://catalog.ngc.nvidia.com/) 的 API key 进行认证。
## CLI 设置
先导出 key，然后运行新手引导并设置一个 NVIDIA 模型：
```bash
export NVIDIA_API_KEY="nvapi-..."
openclaw onboard --auth-choice skip
openclaw models set nvidia/nvidia/llama-3.1-nemotron-70b-instruct
```
如果你仍然使用 `--token`，请记住它会出现在 shell 历史记录和 `ps` 输出中；如果可能，优先使用环境变量。
## 配置片段
```json5
{
env: { NVIDIA_API_KEY: "nvapi-..." },
models: {
providers: {
nvidia: {
baseUrl: "https://integrate.api.nvidia.com/v1",
api: "openai-completions",
},
},
},
agents: {
defaults: {
model: { primary: "nvidia/nvidia/llama-3.1-nemotron-70b-instruct" },
},
},
}
```
## 模型 ID
- `nvidia/llama-3.1-nemotron-70b-instruct`（默认）
- `meta/llama-3.3-70b-instruct`
- `nvidia/mistral-nemo-minitron-8b-8k-instruct`
## 说明
- 使用与 OpenAI 兼容的 `/v1` 端点；请使用来自 NVIDIA NGC 的 API key。
- 当设置了 `NVIDIA_API_KEY` 时，提供商会自动启用；使用静态默认值（131,072-token 上下文窗口，4,096 最大 tokens）。

251
docs/zh-CN/providers/ollama.md
View File

@ -1,37 +1,98 @@
---
read_when:
- 你想通过 Ollama 使用本地模型运行 OpenClaw
- 你需要 Ollama 的安装和配置指导
summary: 通过 Ollama（本地 LLM 运行时）运行 OpenClaw
- 你想通过 Ollama 在 OpenClaw 中运行云端或本地模型
- 你需要 Ollama 设置和配置指南
summary: 通过 Ollama 运行 OpenClaw（云端和本地模型）
title: Ollama
x-i18n:
generated_at: "2026-02-01T21:35:22Z"
model: claude-opus-4-5
provider: pi
source_hash: 157080ad90f449f622260a5f5bd293f79c15800527d36b15596e8ca232e3c957
generated_at: "2026-03-16T06:26:42Z"
model: gpt-5.4
provider: openai
source_hash: 226b71bfd59614552f0b9cf1c9b1d18d82121a5fb05f6c71b11cc3cf4c23fd4e
source_path: providers/ollama.md
workflow: 15
---
# Ollama
Ollama 是一个本地 LLM 运行时，可以轻松在你的机器上运行开源模型。OpenClaw 通过 Ollama 的 OpenAI 兼容 API 进行集成，并且当你通过 `OLLAMA_API_KEY`（或认证配置）启用且未定义显式的 `models.providers.ollama` 条目时，可以**自动发现支持工具调用的模型**。
Ollama 是一个本地 LLM 运行时，可以让你轻松在自己的机器上运行开源模型。OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），支持流式传输和工具调用，并且在你选择使用 `OLLAMA_API_KEY`（或凭证配置文件）且未定义显式 `models.providers.ollama` 条目时，可以自动发现本地 Ollama 模型。
<Warning>
**远程 Ollama 用户：** 不要在 OpenClaw 中使用 `/v1` 的 OpenAI 兼容 URL（`http://host:11434/v1`）。这会破坏工具调用，而且模型可能会把原始工具 JSON 当作纯文本输出。请改用原生 Ollama API URL：`baseUrl: "http://host:11434"`（不要加 `/v1`）。
</Warning>
## 快速开始
1. 安装 Ollama：https://ollama.ai
### 新手引导向导（推荐）
2. 拉取模型：
通过设置向导配置 Ollama 是最快的方法：
```bash
ollama pull llama3.3
# 或
ollama pull qwen2.5-coder:32b
# 或
ollama pull deepseek-r1:32b
openclaw onboard
```
3. 为 OpenClaw 启用 Ollama（任意值即可；Ollama 不需要真实密钥）：
从提供商列表中选择 **Ollama**。向导将会：
1. 询问你的 Ollama base URL，也就是可以访问你的实例的地址（默认 `http://127.0.0.1:11434`）。
2. 让你选择 **Cloud + Local**（云端模型和本地模型）或 **Local**（仅本地模型）。
3. 如果你选择 **Cloud + Local** 且尚未登录 ollama.com，则打开浏览器登录流程。
4. 发现可用模型并建议默认值。
5. 如果所选模型本地不可用，则自动拉取它。
也支持非交互模式：
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--accept-risk
```
也可以选择指定自定义 base URL 或模型：
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
### 手动设置
1. 安装 Ollama：[https://ollama.com/download](https://ollama.com/download)
2. 如果你想进行本地推理，先拉取一个本地模型：
```bash
ollama pull glm-4.7-flash
# 或
ollama pull gpt-oss:20b
# 或
ollama pull llama3.3
```
3. 如果你也想使用云端模型，请先登录：
```bash
ollama signin
```
4. 运行新手引导并选择 `Ollama`：
```bash
openclaw onboard
```
- `Local`：仅本地模型
- `Cloud + Local`：本地模型加云端模型
- 云端模型如 `kimi-k2.5:cloud`、`minimax-m2.5:cloud` 和 `glm-5:cloud` **不需要** 本地执行 `ollama pull`
OpenClaw 当前建议：
- 本地默认：`glm-4.7-flash`
- 云端默认：`kimi-k2.5:cloud`、`minimax-m2.5:cloud`、`glm-5:cloud`
5. 如果你更喜欢手动设置，也可以直接为 OpenClaw 启用 Ollama（任意值都可以；Ollama 不需要真实 key）：
```bash
# 设置环境变量
@ -41,13 +102,20 @@ export OLLAMA_API_KEY="ollama-local"
openclaw config set models.providers.ollama.apiKey "ollama-local"
```
4. 使用 Ollama 模型：
6. 查看或切换模型：
```bash
openclaw models list
openclaw models set ollama/glm-4.7-flash
```
7. 或者在配置中设置默认值：
```json5
{
agents: {
defaults: {
model: { primary: "ollama/llama3.3" },
model: { primary: "ollama/glm-4.7-flash" },
},
},
}
@ -55,39 +123,38 @@ openclaw config set models.providers.ollama.apiKey "ollama-local"
## 模型发现（隐式提供商）
当你设置了 `OLLAMA_API_KEY`（或认证配置）且**未**定义 `models.providers.ollama` 时，OpenClaw 会从本地 Ollama 实例 `http://127.0.0.1:11434` 发现模型：
当你设置 `OLLAMA_API_KEY`（或凭证配置文件），并且**未**定义 `models.providers.ollama` 时，OpenClaw 会从 `http://127.0.0.1:11434` 上的本地 Ollama 实例发现模型：
- 查询 `/api/tags` 和 `/api/show`
- 仅保留报告了 `tools` 能力的模型
- 当模型报告 `thinking` 时标记为 `reasoning`
- 在可用时从 `model_info["<arch>.context_length"]` 读取 `contextWindow`
- 将 `maxTokens` 设置为上下文窗口的 10 倍
- 所有费用设置为 `0`
- 查询 `/api/tags`
- 在可用时，尽力通过 `/api/show` 查找 `contextWindow`
- 通过模型名称启发式规则标记 `reasoning`（`r1`、`reasoning`、`think`）
- 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限
- 将所有成本设置为 `0`
这样无需手动配置模型条目，同时保持目录与 Ollama 的能力对齐。
这样无需手动维护模型条目，同时又能让目录与本地 Ollama 实例保持一致。
查看可用模型：
查看有哪些可用模型：
```bash
ollama list
openclaw models list
```
要添加新模型，只需通过 Ollama 拉取：
添加新模型时，只需通过 Ollama 拉取它：
```bash
ollama pull mistral
```
新模型将被自动发现并可供使用。
新模型会被自动发现，并可立即使用。
如果你显式设置了 `models.providers.ollama`，自动发现将被跳过，你必须手动定义模型（见下文）。
如果你显式设置了 `models.providers.ollama`，则会跳过自动发现，你必须手动定义模型（见下文）。
## 配置
### 基本设置（隐式发现）
启用 Ollama 最简单的方式是通过环境变量：
启用 Ollama 的最简单方式是通过环境变量：
```bash
export OLLAMA_API_KEY="ollama-local"
@ -95,25 +162,24 @@ export OLLAMA_API_KEY="ollama-local"
### 显式设置（手动模型）
在以下情况使用显式配置：
以下情况适合使用显式配置：
- Ollama 运行在其他主机/端口上。
- 你想强制指定上下文窗口或模型列表。
- 你想包含未报告工具支持的模型。
- 你想强制指定特定的上下文窗口或模型列表。
- 你希望完全手动定义模型。
```json5
{
models: {
providers: {
ollama: {
// 使用包含 /v1 的主机地址以兼容 OpenAI API
baseUrl: "http://ollama-host:11434/v1",
baseUrl: "http://ollama-host:11434",
apiKey: "ollama-local",
api: "openai-completions",
api: "ollama",
models: [
{
id: "llama3.3",
name: "Llama 3.3",
id: "gpt-oss:20b",
name: "GPT-OSS 20B",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
@ -127,11 +193,11 @@ export OLLAMA_API_KEY="ollama-local"
}
```
如果设置了 `OLLAMA_API_KEY`，你可以在提供商条目中省略 `apiKey`，OpenClaw 会自动填充以进行可用性检查。
如果设置了 `OLLAMA_API_KEY`，你可以在提供商条目中省略 `apiKey`，OpenClaw 会在可用性检查时自动填充它。
### 自定义基础 URL（显式配置）
### 自定义 base URL（显式配置）
如果 Ollama 运行在不同的主机或端口上（显式配置会禁用自动发现，因此需要手动定义模型）：
如果 Ollama 运行在不同的主机或端口上（显式配置会禁用自动发现，因此你需要手动定义模型）：
```json5
{
@ -139,59 +205,120 @@ export OLLAMA_API_KEY="ollama-local"
providers: {
ollama: {
apiKey: "ollama-local",
baseUrl: "http://ollama-host:11434/v1",
baseUrl: "http://ollama-host:11434", // 不要加 /v1 - 使用原生 Ollama API URL
api: "ollama", // 显式设置，以确保原生工具调用行为
},
},
},
}
```
<Warning>
不要在 URL 中添加 `/v1`。`/v1` 路径会启用 OpenAI 兼容模式，而在该模式下工具调用并不可靠。请使用不带路径后缀的基础 Ollama URL。
</Warning>
### 模型选择
配置完成后，所有 Ollama 模型即可使用：
配置完成后，你的所有 Ollama 模型都可用：
```json5
{
agents: {
defaults: {
model: {
primary: "ollama/llama3.3",
fallbacks: ["ollama/qwen2.5-coder:32b"],
primary: "ollama/gpt-oss:20b",
fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
},
},
},
}
```
## 云端模型
云端模型让你可以将云托管模型（例如 `kimi-k2.5:cloud`、`minimax-m2.5:cloud`、`glm-5:cloud`）与本地模型一起使用。
要使用云端模型，请在设置期间选择 **Cloud + Local** 模式。向导会检查你是否已登录，并在需要时打开浏览器登录流程。如果无法验证认证状态，向导会回退到本地模型默认值。
你也可以直接在 [ollama.com/signin](https://ollama.com/signin) 登录。
## 高级用法
### 推理模型
当 Ollama 在 `/api/show` 中报告 `thinking` 时，OpenClaw 会将模型标记为具有推理能力：
OpenClaw 默认会将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为支持推理的模型：
```bash
ollama pull deepseek-r1:32b
```
### 模型费用
### 模型成本
Ollama 免费且在本地运行，因此所有模型费用均设置为 $0。
Ollama 是免费的，并且在本地运行，因此所有模型成本都设置为 $0。
### 流式传输配置
OpenClaw 的 Ollama 集成默认使用 **原生 Ollama API**（`/api/chat`），它完全支持同时进行流式传输和工具调用。无需任何特殊配置。
#### 旧版 OpenAI 兼容模式
<Warning>
**在 OpenAI 兼容模式下，工具调用并不可靠。** 只有当你需要为代理使用 OpenAI 格式，并且不依赖原生工具调用行为时，才使用这种模式。
</Warning>
如果你确实需要改用 OpenAI 兼容端点（例如，在只支持 OpenAI 格式的代理之后），请显式设置 `api: "openai-completions"`：
```json5
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434/v1",
api: "openai-completions",
injectNumCtxForOpenAICompat: true, // 默认：true
apiKey: "ollama-local",
models: [...]
}
}
}
}
```
这种模式可能不支持同时进行流式传输 + 工具调用。你可能需要在模型配置中通过 `params: { streaming: false }` 禁用流式传输。
当 Ollama 使用 `api: "openai-completions"` 时，OpenClaw 默认会注入 `options.num_ctx`，这样 Ollama 就不会静默回退到 4096 上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段，请禁用此行为：
```json5
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434/v1",
api: "openai-completions",
injectNumCtxForOpenAICompat: false,
apiKey: "ollama-local",
models: [...]
}
}
}
}
```
### 上下文窗口
对于自动发现的模型，OpenClaw 会使用 Ollama 报告的上下文窗口（如果可用），否则默认为 `8192`。你可以在显式提供商配置中覆盖 `contextWindow` 和 `maxTokens`。
对于自动发现的模型，OpenClaw 会在 Ollama 提供时使用其报告的上下文窗口，否则回退到 OpenClaw 使用的默认 Ollama 上下文窗口。你可以在显式提供商配置中覆盖 `contextWindow` 和 `maxTokens`。
## 故障排除
### Ollama 未被检测到
### 未检测到 Ollama
确保 Ollama 正在运行，且你已设置 `OLLAMA_API_KEY`（或认证配置），并且**未**定义显式的 `models.providers.ollama` 条目：
请确认 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或凭证配置文件），而且**没有**定义显式的 `models.providers.ollama` 条目：
```bash
ollama serve
```
同时确认 API 可访问：
并确认 API 可访问：
```bash
curl http://localhost:11434/api/tags
@ -199,24 +326,26 @@ curl http://localhost:11434/api/tags
### 没有可用模型
OpenClaw 仅自动发现报告了工具支持的模型。如果你的模型未列出，可以：
如果没有列出你的模型，可以：
- 拉取一个支持工具调用的模型，或
- 在本地拉取该模型，或者
- 在 `models.providers.ollama` 中显式定义该模型。
添加模型：
```bash
ollama list # 查看已安装的模型
ollama pull llama3.3 # 拉取模型
ollama pull glm-4.7-flash
ollama pull gpt-oss:20b
ollama pull llama3.3 # 或其他模型
```
### 连接被拒绝
检查 Ollama 是否在正确的端口上运行：
检查 Ollama 是否正在正确的端口上运行：
```bash
# 检查 Ollama 是否在运行
# 检查 Ollama 是否正在运行
ps aux | grep ollama
# 或重启 Ollama
@ -225,6 +354,6 @@ ollama serve
## 另请参阅
- [模型提供商](/concepts/model-providers) - 所有提供商概览
- [模型选择](/concepts/models) - 如何选择模型
- [配置](/gateway/configuration) - 完整配置参考
- [Model Providers](/concepts/model-providers) - 所有提供商的概览
- [Model Selection](/concepts/models) - 如何选择模型
- [Configuration](/gateway/configuration) - 完整配置参考

282
docs/zh-CN/providers/openai.md
View File

@ -1,32 +1,34 @@
---
read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 订阅认证而非 API 密钥
- 你想使用 Codex 订阅身份验证而不是 API 密钥
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
title: OpenAI
x-i18n:
generated_at: "2026-02-01T21:35:10Z"
model: claude-opus-4-5
provider: pi
source_hash: f15365d5d616258f6035b986d80fe6acd1be5836a07e5bb68236688ef2952ef7
generated_at: "2026-03-16T06:26:45Z"
model: gpt-5.4
provider: openai
source_hash: a348d8fca7b809f84c6b90bf6a799e0a070a6e7b98a78b2cd2d747bb3d2b2212
source_path: providers/openai.md
workflow: 15
---
# OpenAI
OpenAI 提供 GPT 模型的开发者 API。Codex 支持**ChatGPT 登录**进行订阅访问，或**API 密钥**登录进行按量计费访问。Codex 云端需要 ChatGPT 登录。
OpenAI 为 GPT 模型提供开发者 API。Codex 支持**ChatGPT 登录**以进行订阅
访问，也支持**API 密钥**登录以进行按使用量计费的访问。Codex cloud 需要 ChatGPT 登录。
OpenAI 明确支持在 OpenClaw 这样的外部工具/工作流中使用订阅 OAuth。
## 方式 A：OpenAI API 密钥（OpenAI Platform）
## 选项 A：OpenAI API 密钥（OpenAI Platform）
**适用于：**直接 API 访问和按量计费。
**最适合：** 直接 API 访问和按使用量计费。
从 OpenAI 控制台获取你的 API 密钥。
### CLI 设置
```bash
openclaw onboard --auth-choice openai-api-key
# 或非交互式
# or non-interactive
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
```
@ -35,34 +37,272 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY"
```json5
{
env: { OPENAI_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "openai/gpt-5.2" } } },
agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}
```
## 方式 B：OpenAI Code（Codex）订阅
OpenAI 当前的 API 模型文档将 `gpt-5.4` 和 `gpt-5.4-pro` 列为直接
OpenAI API 用法的模型。OpenClaw 会通过 `openai/*` Responses 路径转发这两者。
OpenClaw 会有意隐藏过时的 `openai/gpt-5.3-codex-spark` 条目，
因为直接 OpenAI API 调用会在实际流量中拒绝它。
**适用于：**使用 ChatGPT/Codex 订阅访问而非 API 密钥。
Codex 云端需要 ChatGPT 登录，而 Codex CLI 支持 ChatGPT 或 API 密钥登录。
OpenClaw **不会**在直接 OpenAI
API 路径上暴露 `openai/gpt-5.3-codex-spark`。`pi-ai` 仍然为该模型提供内置条目，但当前实际 OpenAI API
请求会拒绝它。在 OpenClaw 中，Spark 被视为仅限 Codex。
### CLI 设置
## 选项 B：OpenAI Code（Codex）订阅
**最适合：** 使用 ChatGPT/Codex 订阅访问，而不是 API 密钥。
Codex cloud 需要 ChatGPT 登录，而 Codex CLI 支持 ChatGPT 或 API 密钥登录。
### CLI 设置（Codex OAuth）
```bash
# 在向导中运行 Codex OAuth
# Run Codex OAuth in the wizard
openclaw onboard --auth-choice openai-codex
# 或直接运行 OAuth
# Or run OAuth directly
openclaw models auth login --provider openai-codex
```
### 配置片段
### 配置片段（Codex 订阅）
```json5
{
agents: { defaults: { model: { primary: "openai-codex/gpt-5.2" } } },
agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}
```
## 注意事项
OpenAI 当前的 Codex 文档将 `gpt-5.4` 列为当前 Codex 模型。OpenClaw
会将其映射为 `openai-codex/gpt-5.4`，用于 ChatGPT/Codex OAuth。
- 模型引用始终使用 `provider/model` 格式（参见 [/concepts/models](/concepts/models)）。
- 认证详情和复用规则请参阅 [/concepts/oauth](/concepts/oauth)。
如果你的 Codex 账户有权使用 Codex Spark，OpenClaw 也支持：
- `openai-codex/gpt-5.3-codex-spark`
OpenClaw 将 Codex Spark 视为仅限 Codex。它不会暴露直接的
`openai/gpt-5.3-codex-spark` API 密钥路径。
当 `pi-ai`
发现 `openai-codex/gpt-5.3-codex-spark` 时，OpenClaw 也会保留它。请将其视为依赖 entitlement 且处于实验阶段：Codex Spark 与 GPT-5.4 `/fast` 分开，是否可用取决于已登录的 Codex /
ChatGPT 账户。
### 默认传输
OpenClaw 使用 `pi-ai` 进行模型流式传输。对于 `openai/*` 和
`openai-codex/*`，默认传输都是 `"auto"`（优先 WebSocket，然后回退到 SSE）。
你可以设置 `agents.defaults.models.<provider/model>.params.transport`：
- `"sse"`：强制使用 SSE
- `"websocket"`：强制使用 WebSocket
- `"auto"`：尝试 WebSocket，然后回退到 SSE
对于 `openai/*`（Responses API），当使用 WebSocket 传输时，
OpenClaw 还会默认启用 WebSocket 预热
（`openaiWsWarmup: true`）。
相关 OpenAI 文档：
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
```json5
{
agents: {
defaults: {
model: { primary: "openai-codex/gpt-5.4" },
models: {
"openai-codex/gpt-5.4": {
params: {
transport: "auto",
},
},
},
},
},
}
```
### OpenAI WebSocket 预热
OpenAI 文档将预热描述为可选。OpenClaw 对
`openai/*` 默认启用它，以在使用 WebSocket 传输时减少首次响应延迟。
### 禁用预热
```json5
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: {
openaiWsWarmup: false,
},
},
},
},
},
}
```
### 显式启用预热
```json5
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: {
openaiWsWarmup: true,
},
},
},
},
},
}
```
### OpenAI 优先处理
OpenAI 的 API 通过 `service_tier=priority` 暴露优先处理。在
OpenClaw 中，设置 `agents.defaults.models["openai/<model>"].params.serviceTier`，即可
在直接 `openai/*` Responses 请求中透传该字段。
```json5
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: {
serviceTier: "priority",
},
},
},
},
},
}
```
支持的值为 `auto`、`default`、`flex` 和 `priority`。
### OpenAI 快速模式
OpenClaw 为 `openai/*` 和
`openai-codex/*` 会话公开了共享快速模式开关：
- 聊天/UI：`/fast status|on|off`
- 配置：`agents.defaults.models["<provider>/<model>"].params.fastMode`
启用快速模式后，OpenClaw 会应用低延迟 OpenAI 配置：
- 当负载未明确指定 reasoning 时，设置 `reasoning.effort = "low"`
- 当负载未明确指定 verbosity 时，设置 `text.verbosity = "low"`
- 对直接发往 `api.openai.com` 的 `openai/*` Responses 调用设置 `service_tier = "priority"`
示例：
```json5
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: {
fastMode: true,
},
},
"openai-codex/gpt-5.4": {
params: {
fastMode: true,
},
},
},
},
},
}
```
会话覆盖优先于配置。在会话 UI 中清除会话覆盖后，
该会话会恢复为配置的默认值。
### OpenAI Responses 服务端压缩
对于直接 OpenAI Responses 模型（使用 `api: "openai-responses"` 的 `openai/*`，
且 `baseUrl` 指向 `api.openai.com`），OpenClaw 现在会自动启用 OpenAI 服务端
压缩负载提示：
- 强制设置 `store: true`（除非模型兼容性设置 `supportsStore: false`）
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
默认情况下，`compact_threshold` 为模型 `contextWindow` 的 `70%`（或在不可用时为 `80000`）。
### 显式启用服务端压缩
当你想在兼容的
Responses 模型上强制注入 `context_management` 时使用此设置（例如 Azure OpenAI Responses）：
```json5
{
agents: {
defaults: {
models: {
"azure-openai-responses/gpt-5.4": {
params: {
responsesServerCompaction: true,
},
},
},
},
},
}
```
### 使用自定义阈值启用
```json5
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: {
responsesServerCompaction: true,
responsesCompactThreshold: 120000,
},
},
},
},
},
}
```
### 禁用服务端压缩
```json5
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: {
responsesServerCompaction: false,
},
},
},
},
},
}
```
`responsesServerCompaction` 仅控制 `context_management` 注入。
直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置
了 `supportsStore: false`。
## 说明
- 模型引用始终使用 `provider/model`（参见 [/concepts/models](/concepts/models)）。
- 身份验证详情和复用规则见 [/concepts/oauth](/concepts/oauth)。

52
docs/zh-CN/providers/opencode-go.md Normal file
View File

@ -0,0 +1,52 @@
---
read_when:
- 你想使用 OpenCode Go 目录
- 你需要了解 Go 托管模型的运行时模型引用
summary: 使用共享的 OpenCode 设置来使用 OpenCode Go 目录
title: OpenCode Go
x-i18n:
generated_at: "2026-03-16T06:26:48Z"
model: gpt-5.4
provider: openai
source_hash: 8650af7c64220c14bab8c22472fff8bebd7abde253e972b6a11784ad833d321c
source_path: providers/opencode-go.md
workflow: 15
---
# OpenCode Go
OpenCode Go 是 [OpenCode](/providers/opencode) 中的 Go 目录。
它使用与 Zen 目录相同的 `OPENCODE_API_KEY`，但保留运行时
提供商 id `opencode-go`，以便上游按模型路由保持正确。
## 支持的模型
- `opencode-go/kimi-k2.5`
- `opencode-go/glm-5`
- `opencode-go/minimax-m2.5`
## CLI 设置
```bash
openclaw onboard --auth-choice opencode-go
# 或非交互式
openclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
```
## 配置片段
```json5
{
env: { OPENCODE_API_KEY: "YOUR_API_KEY_HERE" }, // pragma: allowlist secret
agents: { defaults: { model: { primary: "opencode-go/kimi-k2.5" } } },
}
```
## 路由行为
当模型引用使用 `opencode-go/...` 时，OpenClaw 会自动处理按模型路由。
## 说明
- 共享的新手引导和目录概览请使用 [OpenCode](/providers/opencode)。
- 运行时引用保持显式：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`。

60
docs/zh-CN/providers/opencode.md
View File

@ -1,41 +1,71 @@
---
read_when:
- 你想通过 OpenCode Zen 访问模型
- 你想要一个适合编程的精选模型列表
summary: 在 OpenClaw 中使用 OpenCode Zen（精选模型）
title: OpenCode Zen
- 你想使用 OpenCode 托管的模型访问
- 你想在 Zen 和 Go 目录之间进行选择
summary: 在 OpenClaw 中使用 OpenCode Zen 和 Go 目录
title: OpenCode
x-i18n:
generated_at: "2026-02-01T21:35:16Z"
model: claude-opus-4-5
provider: pi
source_hash: 1390f9803a3cac48cb40694dd69267e3ddccd203a4ce8babda3198b926b5f6a3
generated_at: "2026-03-16T06:26:52Z"
model: gpt-5.4
provider: openai
source_hash: 9ffe65d152d1835163f9f5ae4cc966e29bd01a9dbb88187c24d149c960c8225d
source_path: providers/opencode.md
workflow: 15
---
# OpenCode Zen
# OpenCode
OpenCode Zen 是由 OpenCode 团队推荐的一组**精选模型列表**，适用于编程智能体。它是一个可选的托管模型访问路径，使用 API 密钥和 `opencode` 提供商。Zen 目前处于测试阶段。
OpenCode 在 OpenClaw 中提供两个托管目录：
- `opencode/...` 用于 **Zen** 目录
- `opencode-go/...` 用于 **Go** 目录
两个目录都使用相同的 OpenCode API 密钥。OpenClaw 会将运行时提供商 ID
保持拆分，以便上游按模型路由保持正确，但新手引导和文档将它们视为
同一个 OpenCode 设置。
## CLI 设置
### Zen 目录
```bash
openclaw onboard --auth-choice opencode-zen
# 或非交互式
openclaw onboard --opencode-zen-api-key "$OPENCODE_API_KEY"
```
### Go 目录
```bash
openclaw onboard --auth-choice opencode-go
openclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
```
## 配置片段
```json5
{
env: { OPENCODE_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "opencode/claude-opus-4-5" } } },
agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
}
```
## 注意事项
## 目录
### Zen
- 运行时提供商：`opencode`
- 示例模型：`opencode/claude-opus-4-6`、`opencode/gpt-5.2`、`opencode/gemini-3-pro`
- 适合你想使用精选的 OpenCode 多模型代理时
### Go
- 运行时提供商：`opencode-go`
- 示例模型：`opencode-go/kimi-k2.5`、`opencode-go/glm-5`、`opencode-go/minimax-m2.5`
- 适合你想使用 OpenCode 托管的 Kimi/GLM/MiniMax 产品线时
## 说明
- 也支持 `OPENCODE_ZEN_API_KEY`。
- 你需要登录 Zen，添加账单信息，然后复制你的 API 密钥。
- OpenCode Zen 按请求计费；详情请查看 OpenCode 控制台。
- 在设置期间输入一个 OpenCode 密钥，会为两个运行时提供商都存储凭证。
- 你需要登录 OpenCode、添加计费信息，然后复制你的 API 密钥。
- 计费和目录可用性由 OpenCode 仪表板管理。

21
docs/zh-CN/providers/openrouter.md
View File

@ -1,13 +1,13 @@
---
read_when:
- 你想用一个 API 密钥访问多种 LLM
- 你想在 OpenClaw 中通过 OpenRouter 运行模型
summary: 使用 OpenRouter 的统一 API 在 OpenClaw 中访问多种模型
- 你想用一个 API key 访问许多 LLM
- 你想通过 OpenRouter 在 OpenClaw 中运行模型
summary: 使用 OpenRouter 的统一 API 在 OpenClaw 中访问许多模型
title: OpenRouter
x-i18n:
generated_at: "2026-02-01T21:35:19Z"
model: claude-opus-4-5
provider: pi
generated_at: "2026-03-16T06:26:52Z"
model: gpt-5.4
provider: openai
source_hash: b7e29fc9c456c64d567dd909a85166e6dea8388ebd22155a31e69c970e081586
source_path: providers/openrouter.md
workflow: 15
@ -15,7 +15,8 @@ x-i18n:
# OpenRouter
OpenRouter 提供了一个**统一 API**，通过单一端点和 API 密钥将请求路由到多种模型。它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。
OpenRouter 提供一个**统一 API**，可通过单个
端点和 API key 将请求路由到许多模型。它与 OpenAI 兼容，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。
## CLI 设置
@ -36,8 +37,8 @@ openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPEN
}
```
## 注意事项
## 说明
- 模型引用格式为 `openrouter/<provider>/<model>`。
- 更多模型/提供商选项，请参阅[模型提供商](/concepts/model-providers)。
- OpenRouter 底层使用 Bearer 令牌和你的 API 密钥进行认证。
- 关于更多模型/提供商选项，请参阅 [/concepts/model-providers](/concepts/model-providers)。
- OpenRouter 在底层使用带有你的 API key 的 Bearer token。

45
docs/zh-CN/providers/qianfan.md
View File

@ -1,8 +1,45 @@
---
summary: 使用千帆统一 API 在 OpenClaw 中接入多种模型
title: 千帆（Qianfan）
read_when:
- 你想用一个 API key 访问许多 LLM
- 你需要 Baidu Qianfan 设置指南
summary: 使用 Qianfan 的统一 API 在 OpenClaw 中访问许多模型
title: Qianfan
x-i18n:
generated_at: "2026-03-16T06:26:58Z"
model: gpt-5.4
provider: openai
source_hash: 2ca710b422f190b65d23db51a3219f0abd67074fb385251efeca6eae095d02e0
source_path: providers/qianfan.md
workflow: 15
---
# 千帆（Qianfan）
# Qianfan 提供商指南
该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Qianfan](/providers/qianfan)。
Qianfan 是 Baidu 的 MaaS 平台，提供一个**统一 API**，可通过单个
端点和 API key 将请求路由到许多模型。它与 OpenAI 兼容，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。
## 前提条件
1. 一个已开通 Qianfan API 访问权限的 Baidu Cloud 账号
2. 一个来自 Qianfan 控制台的 API key
3. 已在你的系统上安装 OpenClaw
## 获取 API key
1. 访问 [Qianfan Console](https://console.bce.baidu.com/qianfan/ais/console/apiKey)
2. 创建一个新应用，或选择一个现有应用
3. 生成一个 API key（格式：`bce-v3/ALTAK-...`）
4. 复制该 API key 以在 OpenClaw 中使用
## CLI 设置
```bash
openclaw onboard --auth-choice qianfan-api-key
```
## 相关文档
- [OpenClaw Configuration](/gateway/configuration)
- [Model Providers](/concepts/model-providers)
- [Agent Setup](/concepts/agent)
- [Qianfan API Documentation](https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb)

111
docs/zh-CN/providers/sglang.md Normal file
View File

@ -0,0 +1,111 @@
---
read_when:
- 你想让 OpenClaw 连接本地 SGLang 服务器运行
- 你想通过自己的模型使用兼容 OpenAI 的 `/v1` 端点
summary: 让 OpenClaw 与 SGLang 一起运行（兼容 OpenAI 的自托管服务器）
title: SGLang
x-i18n:
generated_at: "2026-03-16T06:27:01Z"
model: gpt-5.4
provider: openai
source_hash: 26ba858c46bc2b82088274c62270500ffc243e5fb505b8aaaffc096d835187b0
source_path: providers/sglang.md
workflow: 15
---
# SGLang
SGLang 可以通过**兼容 OpenAI** 的 HTTP API 提供开源模型服务。
OpenClaw 可以使用 `openai-completions` API 连接到 SGLang。
当你通过 `SGLANG_API_KEY` 选择加入时，OpenClaw 还可以**自动发现**
SGLang 提供的可用模型（如果你的服务器不强制身份验证，任意值都可）
并且你没有定义显式的 `models.providers.sglang` 条目。
## 快速开始
1. 使用兼容 OpenAI 的服务器启动 SGLang。
你的基础 URL 应暴露 `/v1` 端点（例如 `/v1/models`、
`/v1/chat/completions`）。SGLang 通常运行在：
- `http://127.0.0.1:30000/v1`
2. 选择加入（如果未配置身份验证，任意值都可）：
```bash
export SGLANG_API_KEY="sglang-local"
```
3. 运行新手引导并选择 `SGLang`，或直接设置模型：
```bash
openclaw onboard
```
```json5
{
agents: {
defaults: {
model: { primary: "sglang/your-model-id" },
},
},
}
```
## 模型发现（隐式提供商）
当设置了 `SGLANG_API_KEY`（或存在 auth profile），并且你**没有**
定义 `models.providers.sglang` 时，OpenClaw 将查询：
- `GET http://127.0.0.1:30000/v1/models`
并将返回的 ID 转换为模型条目。
如果你显式设置了 `models.providers.sglang`，则会跳过自动发现，
你必须手动定义模型。
## 显式配置（手动模型）
在以下情况下使用显式配置：
- SGLang 运行在不同的主机/端口上。
- 你想固定 `contextWindow`/`maxTokens` 值。
- 你的服务器需要真实 API 密钥（或者你想控制请求头）。
```json5
{
models: {
providers: {
sglang: {
baseUrl: "http://127.0.0.1:30000/v1",
apiKey: "${SGLANG_API_KEY}",
api: "openai-completions",
models: [
{
id: "your-model-id",
name: "本地 SGLang 模型",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 128000,
maxTokens: 8192,
},
],
},
},
},
}
```
## 故障排除
- 检查服务器是否可访问：
```bash
curl http://127.0.0.1:30000/v1/models
```
- 如果请求因身份验证错误而失败，请设置与
你的服务器配置匹配的真实 `SGLANG_API_KEY`，或者在
`models.providers.sglang` 下显式配置该提供商。

86
docs/zh-CN/providers/synthetic.md
View File

@ -1,35 +1,36 @@
---
read_when:
- 你想使用 Synthetic 作为模型提供商
- 你需要配置 Synthetic API 密钥或 base URL
- 你想将 Synthetic 用作模型提供商
- 你需要 Synthetic API key 或 base URL 设置
summary: 在 OpenClaw 中使用 Synthetic 的 Anthropic 兼容 API
title: Synthetic
x-i18n:
generated_at: "2026-02-01T21:35:34Z"
model: claude-opus-4-5
provider: pi
source_hash: f3f6e3eb864661754cbe2276783c5bc96ae01cb85ee4a19c92bed7863a35a4f7
generated_at: "2026-03-16T06:27:11Z"
model: gpt-5.4
provider: openai
source_hash: 3a2adb0b831babe3e88b027772167748764d85ee72d402ff759571420a91757f
source_path: providers/synthetic.md
workflow: 15
---
# Synthetic
Synthetic 提供兼容 Anthropic 的端点。OpenClaw 将其注册为 `synthetic` 提供商，并使用 Anthropic Messages API。
Synthetic 提供与 Anthropic 兼容的端点。OpenClaw 将其注册为
`synthetic` 提供商，并使用 Anthropic Messages API。
## 快速设置
1. 设置 `SYNTHETIC_API_KEY`（或运行以下向导）。
1. 设置 `SYNTHETIC_API_KEY`（或运行下面的向导）。
2. 运行新手引导：
```bash
openclaw onboard --auth-choice synthetic-api-key
```
默认模型设置为：
默认模型会设置为：
```
synthetic/hf:MiniMaxAI/MiniMax-M2.1
synthetic/hf:MiniMaxAI/MiniMax-M2.5
```
## 配置示例
@ -39,8 +40,8 @@ synthetic/hf:MiniMaxAI/MiniMax-M2.1
env: { SYNTHETIC_API_KEY: "sk-..." },
agents: {
defaults: {
model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.1" },
models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.1": { alias: "MiniMax M2.1" } },
model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
},
},
models: {
@ -52,8 +53,8 @@ synthetic/hf:MiniMaxAI/MiniMax-M2.1
api: "anthropic-messages",
models: [
{
id: "hf:MiniMaxAI/MiniMax-M2.1",
name: "MiniMax M2.1",
id: "hf:MiniMaxAI/MiniMax-M2.5",
name: "MiniMax M2.5",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
@ -67,36 +68,39 @@ synthetic/hf:MiniMaxAI/MiniMax-M2.1
}
```
注意：OpenClaw 的 Anthropic 客户端会自动在 base URL 后追加 `/v1`，因此请使用 `https://api.synthetic.new/anthropic`（而非 `/anthropic/v1`）。如果 Synthetic 更改了其 base URL，请覆盖 `models.providers.synthetic.baseUrl`。
注意：OpenClaw 的 Anthropic 客户端会将 `/v1` 追加到 base URL 后面，因此请使用
`https://api.synthetic.new/anthropic`（而不是 `/anthropic/v1`）。如果 Synthetic 更改了
其 base URL，请覆盖 `models.providers.synthetic.baseUrl`。
## 模型目录
以下所有模型的费用均为 `0`（输入/输出/缓存）。
下面所有模型的成本都为 `0`（输入/输出/缓存）。
| 模型 ID | 上下文窗口 | 最大令牌数 | 推理 | 输入 |
| ------------------------------------------------------ | ---------- | ---------- | ----- | ------------ |
| `hf:MiniMaxAI/MiniMax-M2.1` | 192000 | 65536 | false | text |
| `hf:moonshotai/Kimi-K2-Thinking` | 256000 | 8192 | true | text |
| `hf:zai-org/GLM-4.7` | 198000 | 128000 | false | text |
| `hf:deepseek-ai/DeepSeek-R1-0528` | 128000 | 8192 | false | text |
| `hf:deepseek-ai/DeepSeek-V3-0324` | 128000 | 8192 | false | text |
| `hf:deepseek-ai/DeepSeek-V3.1` | 128000 | 8192 | false | text |
| `hf:deepseek-ai/DeepSeek-V3.1-Terminus` | 128000 | 8192 | false | text |
| `hf:deepseek-ai/DeepSeek-V3.2` | 159000 | 8192 | false | text |
| `hf:meta-llama/Llama-3.3-70B-Instruct` | 128000 | 8192 | false | text |
| `hf:meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 524000 | 8192 | false | text |
| `hf:moonshotai/Kimi-K2-Instruct-0905` | 256000 | 8192 | false | text |
| `hf:openai/gpt-oss-120b` | 128000 | 8192 | false | text |
| `hf:Qwen/Qwen3-235B-A22B-Instruct-2507` | 256000 | 8192 | false | text |
| `hf:Qwen/Qwen3-Coder-480B-A35B-Instruct` | 256000 | 8192 | false | text |
| `hf:Qwen/Qwen3-VL-235B-A22B-Instruct` | 250000 | 8192 | false | text + image |
| `hf:zai-org/GLM-4.5` | 128000 | 128000 | false | text |
| `hf:zai-org/GLM-4.6` | 198000 | 128000 | false | text |
| `hf:deepseek-ai/DeepSeek-V3` | 128000 | 8192 | false | text |
| `hf:Qwen/Qwen3-235B-A22B-Thinking-2507` | 256000 | 8192 | true | text |
| 模型 ID | 上下文窗口 | 最大 tokens | 推理 | 输入 |
| ------------------------------------------------------ | ---------- | ----------- | ----- | ------------ |
| `hf:MiniMaxAI/MiniMax-M2.5` | 192000 | 65536 | false | text |
| `hf:moonshotai/Kimi-K2-Thinking` | 256000 | 8192 | true | text |
| `hf:zai-org/GLM-4.7` | 198000 | 128000 | false | text |
| `hf:deepseek-ai/DeepSeek-R1-0528` | 128000 | 8192 | false | text |
| `hf:deepseek-ai/DeepSeek-V3-0324` | 128000 | 8192 | false | text |
| `hf:deepseek-ai/DeepSeek-V3.1` | 128000 | 8192 | false | text |
| `hf:deepseek-ai/DeepSeek-V3.1-Terminus` | 128000 | 8192 | false | text |
| `hf:deepseek-ai/DeepSeek-V3.2` | 159000 | 8192 | false | text |
| `hf:meta-llama/Llama-3.3-70B-Instruct` | 128000 | 8192 | false | text |
| `hf:meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 524000 | 8192 | false | text |
| `hf:moonshotai/Kimi-K2-Instruct-0905` | 256000 | 8192 | false | text |
| `hf:openai/gpt-oss-120b` | 128000 | 8192 | false | text |
| `hf:Qwen/Qwen3-235B-A22B-Instruct-2507` | 256000 | 8192 | false | text |
| `hf:Qwen/Qwen3-Coder-480B-A35B-Instruct` | 256000 | 8192 | false | text |
| `hf:Qwen/Qwen3-VL-235B-A22B-Instruct` | 250000 | 8192 | false | text + image |
| `hf:zai-org/GLM-4.5` | 128000 | 128000 | false | text |
| `hf:zai-org/GLM-4.6` | 198000 | 128000 | false | text |
| `hf:deepseek-ai/DeepSeek-V3` | 128000 | 8192 | false | text |
| `hf:Qwen/Qwen3-235B-A22B-Thinking-2507` | 256000 | 8192 | true | text |
## 注意事项
## 说明
- 模型引用格式为 `synthetic/<modelId>`。
- 如果启用了模型允许列表（`agents.defaults.models`），请添加你计划使用的所有模型。
- 参阅[模型提供商](/concepts/model-providers)了解提供商规则。
- 模型引用使用 `synthetic/<modelId>`。
- 如果你启用了模型允许列表（`agents.defaults.models`），请添加你
计划使用的每个模型。
- 有关提供商规则，请参阅 [Model providers](/concepts/model-providers)。

72
docs/zh-CN/providers/together.md Normal file
View File

@ -0,0 +1,72 @@
---
read_when:
- 你想在 OpenClaw 中使用 Together AI
- 你需要 API 密钥环境变量或 CLI 身份验证选项
summary: Together AI 设置（身份验证 + 模型选择）
x-i18n:
generated_at: "2026-03-16T06:27:08Z"
model: gpt-5.4
provider: openai
source_hash: 4f2ba5a12b03d0140feba4f54e0540bb57237cd131c8f1d826bc3629fde2d111
source_path: providers/together.md
workflow: 15
---
# Together AI
[Together AI](https://together.ai) 通过统一 API 提供对领先开源模型的访问，包括 Llama、DeepSeek、Kimi 等。
- 提供商：`together`
- 身份验证：`TOGETHER_API_KEY`
- API：兼容 OpenAI
## 快速开始
1. 设置 API 密钥（推荐：为 Gateway 网关存储它）：
```bash
openclaw onboard --auth-choice together-api-key
```
2. 设置默认模型：
```json5
{
agents: {
defaults: {
model: { primary: "together/moonshotai/Kimi-K2.5" },
},
},
}
```
## 非交互式示例
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice together-api-key \
--together-api-key "$TOGETHER_API_KEY"
```
这会将 `together/moonshotai/Kimi-K2.5` 设置为默认模型。
## 环境说明
如果 Gateway 网关作为守护进程运行（launchd/systemd），请确保 `TOGETHER_API_KEY`
对该进程可用（例如在 `~/.openclaw/.env` 中，或通过
`env.shellEnv`）。
## 可用模型
Together AI 提供对许多热门开源模型的访问：
- **GLM 4.7 Fp8** - 具有 200K 上下文窗口的默认模型
- **Llama 3.3 70B Instruct Turbo** - 快速、高效的指令跟随模型
- **Llama 4 Scout** - 具备图像理解能力的视觉模型
- **Llama 4 Maverick** - 高级视觉和推理模型
- **DeepSeek V3.1** - 强大的编码和推理模型
- **DeepSeek R1** - 高级推理模型
- **Kimi K2 Instruct** - 具有 262K 上下文窗口的高性能模型
所有模型都支持标准聊天补全，并兼容 OpenAI API。

255
docs/zh-CN/providers/venice.md
View File

@ -1,50 +1,50 @@
---
read_when:
- 你想在 OpenClaw 中使用注重隐私的推理服务
- 你需要 Venice AI 设置指导
- 你想在 OpenClaw 中使用注重隐私的推理
- 你想获得 Venice AI 设置指引
summary: 在 OpenClaw 中使用 Venice AI 注重隐私的模型
title: Venice AI
x-i18n:
generated_at: "2026-02-01T21:36:03Z"
model: claude-opus-4-5
provider: pi
source_hash: 2453a6ec3a715c24c460f902dec1755edcad40328de2ef895e35a614a25624cf
generated_at: "2026-03-16T06:27:49Z"
model: gpt-5.4
provider: openai
source_hash: e72c7ad24b045e9695530bee80ab7213986742354b7553b72bb230b75edf76e8
source_path: providers/venice.md
workflow: 15
---
# Venice AI（Venice 精选）
# Venice AI（Venice 亮点）
**Venice** 是我们精选的 Venice 隐私优先推理配置，支持可选的匿名化访问专有模型。
**Venice** 是我们重点推荐的 Venice 设置，适用于隐私优先的推理，并可选择通过匿名访问专有模型。
Venice AI 提供注重隐私的 AI 推理服务，支持无审查模型，并可通过其匿名代理访问主流专有模型。所有推理默认私密——不会用你的数据训练，不会记录日志。
Venice AI 提供注重隐私的 AI 推理，支持未审查模型，并可通过其匿名代理访问主要专有模型。所有推理默认都是私密的——不会使用你的数据进行训练，也不会记录日志。
## 为什么在 OpenClaw 中使用 Venice
- **私密推理**，适用于开源模型（无日志记录）。
- 需要时可使用**无审查模型**。
- 在质量重要时，可**匿名访问**专有模型（Opus/GPT/Gemini）。
- **私密推理**，适用于开源模型（不记录日志）。
- 当你需要时可使用**未审查模型**。
- 当质量更重要时，可**匿名访问**专有模型（Opus/GPT/Gemini）。
- 兼容 OpenAI 的 `/v1` 端点。
## 隐私模式
Venice 提供两种隐私级别——理解这一点是选择模型的关键：
Venice 提供两个隐私级别 —— 理解这一点对于选择你的模型至关重要：
| 模式 | 描述 | 模型 |
| ---------- | ------------------------------------------------------------------------------------- | ------------------------------------------- |
| **私密** | 完全私密。提示词/回复**从不存储或记录**。临时性处理。 | Llama、Qwen、DeepSeek、Venice Uncensored 等 |
| **匿名化** | 通过 Venice 代理转发并剥离元数据。底层提供商（OpenAI、Anthropic）收到的是匿名化请求。 | Claude、GPT、Gemini、Grok、Kimi、MiniMax |
| 模式 | 说明 | 模型 |
| -------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **私密** | 完全私密。提示词/响应**绝不会被存储或记录**。临时性。 | Llama、Qwen、DeepSeek、Kimi、MiniMax、Venice Uncensored 等。 |
| **匿名** | 通过 Venice 代理并剥离元数据。底层提供商（OpenAI、Anthropic、Google、xAI）看到的是匿名请求。 | Claude、GPT、Gemini、Grok |
## 功能特性
## 功能
- **注重隐私**：可选择"私密"（完全私密）和"匿名化"（代理转发）模式
- **无审查模型**：访问无内容限制的模型
- **主流模型访问**：通过 Venice 匿名代理使用 Claude、GPT-5.2、Gemini、Grok
- **兼容 OpenAI API**：标准 `/v1` 端点，易于集成
- **流式输出**：✅ 所有模型均支持
- **函数调用**：✅ 部分模型支持（请检查模型能力）
- **视觉**：✅ 具有视觉能力的模型支持
- **无硬性速率限制**：极端使用情况下可能触发公平使用限流
- **注重隐私**：可在 “private”（完全私密）和 “anonymized”（代理）模式之间选择
- **未审查模型**：访问不受内容限制的模型
- **主流模型访问**：通过 Venice 的匿名代理使用 Claude、GPT、Gemini 和 Grok
- **兼容 OpenAI 的 API**：标准 `/v1` 端点，易于集成
- **流式传输**：✅ 所有模型都支持
- **函数调用**：✅ 选定模型支持（请检查模型能力）
- **视觉**：✅ 具备视觉能力的模型支持
- **无硬性速率限制**：极端使用情况下可能会应用公平使用节流
## 设置
@ -56,26 +56,26 @@ Venice 提供两种隐私级别——理解这一点是选择模型的关键：
### 2. 配置 OpenClaw
**方案 A：环境变量**
**选项 A：环境变量**
```bash
export VENICE_API_KEY="vapi_xxxxxxxxxxxx"
```
**方案 B：交互式设置（推荐）**
**选项 B：交互式设置（推荐）**
```bash
openclaw onboard --auth-choice venice-api-key
```
这将：
这将会：
1. 提示输入你的 API 密钥（或使用已有的 `VENICE_API_KEY`）
1. 提示输入你的 API 密钥（或使用现有的 `VENICE_API_KEY`）
2. 显示所有可用的 Venice 模型
3. 让你选择默认模型
4. 自动配置提供商
4. 自动配置该提供商
**方案 C：非交互式**
**选项 C：非交互式**
```bash
openclaw onboard --non-interactive \
@ -86,23 +86,23 @@ openclaw onboard --non-interactive \
### 3. 验证设置
```bash
openclaw chat --model venice/llama-3.3-70b "Hello, are you working?"
openclaw agent --model venice/kimi-k2-5 --message "Hello, are you working?"
```
## 模型选择
设置完成后，OpenClaw 会显示所有可用的 Venice 模型。根据你的需求选择：
设置完成后，OpenClaw 会显示所有可用的 Venice 模型。请根据你的需要进行选择：
- **默认（我们的推荐）**：`venice/llama-3.3-70b`，私密且性能均衡。
- **最佳整体质量**：`venice/claude-opus-45`，适合复杂任务（Opus 仍然是最强的）。
- **隐私**：选择"私密"模型以获得完全私密的推理。
- **能力**：选择"匿名化"模型以通过 Venice 代理访问 Claude、GPT、Gemini。
- **默认模型**：`venice/kimi-k2-5`，适合强大的私密推理 + 视觉。
- **高能力选项**：`venice/claude-opus-4-6`，适合最强的匿名 Venice 路径。
- **隐私**：选择 “private” 模型以获得完全私密的推理。
- **能力**：选择 “anonymized” 模型，以通过 Venice 的代理访问 Claude、GPT、Gemini。
随时更改默认模型：
你可以随时更改默认模型：
```bash
openclaw models set venice/claude-opus-45
openclaw models set venice/llama-3.3-70b
openclaw models set venice/kimi-k2-5
openclaw models set venice/claude-opus-4-6
```
列出所有可用模型：
@ -117,104 +117,119 @@ openclaw models list | grep venice
2. 选择 **Model/auth**
3. 选择 **Venice AI**
## 应该使用哪个模型？
## 我应该使用哪个模型？
| 使用场景 | 推荐模型 | 原因 |
| ---------------------- | -------------------------------- | ---------------------------- |
| **通用对话** | `llama-3.3-70b` | 综合表现好，完全私密 |
| **最佳整体质量** | `claude-opus-45` | Opus 在复杂任务上仍然最强 |
| **隐私 + Claude 品质** | `claude-opus-45` | 通过匿名代理获得最佳推理能力 |
| **编程** | `qwen3-coder-480b-a35b-instruct` | 代码优化，262k 上下文 |
| **视觉任务** | `qwen3-vl-235b-a22b` | 最佳私密视觉模型 |
| **无审查** | `venice-uncensored` | 无内容限制 |
| **快速 + 低成本** | `qwen3-4b` | 轻量级，仍有不错能力 |
| **复杂推理** | `deepseek-v3.2` | 推理能力强，私密 |
| 使用场景 | 推荐模型 | 原因 |
| -------------------- | -------------------------------- | -------------------------------- |
| **通用聊天（默认）** | `kimi-k2-5` | 强大的私密推理 + 视觉 |
| **整体最佳质量** | `claude-opus-4-6` | 最强的匿名 Venice 选项 |
| **隐私 + 编码** | `qwen3-coder-480b-a35b-instruct` | 具有大上下文的私密编码模型 |
| **私密视觉** | `kimi-k2-5` | 无需离开私密模式即可支持视觉 |
| **快速 + 便宜** | `qwen3-4b` | 轻量级推理模型 |
| **复杂私密任务** | `deepseek-v3.2` | 推理能力强，但不支持 Venice 工具 |
| **未审查** | `venice-uncensored` | 无内容限制 |
## 可用模型（共 25 个）
## 可用模型（共 41 个）
### 私密模型（15 个）— 完全私密，无日志记录
### 私密模型（26 个）—— 完全私密，不记录日志
| 模型 ID | 名称 | 上下文（token） | 特性 |
| -------------------------------- | ----------------------- | --------------- | ------------ |
| `llama-3.3-70b` | Llama 3.3 70B | 131k | 通用 |
| `llama-3.2-3b` | Llama 3.2 3B | 131k | 快速，轻量 |
| `hermes-3-llama-3.1-405b` | Hermes 3 Llama 3.1 405B | 131k | 复杂任务 |
| `qwen3-235b-a22b-thinking-2507` | Qwen3 235B Thinking | 131k | 推理 |
| `qwen3-235b-a22b-instruct-2507` | Qwen3 235B Instruct | 131k | 通用 |
| `qwen3-coder-480b-a35b-instruct` | Qwen3 Coder 480B | 262k | 编程 |
| `qwen3-next-80b` | Qwen3 Next 80B | 262k | 通用 |
| `qwen3-vl-235b-a22b` | Qwen3 VL 235B | 262k | 视觉 |
| `qwen3-4b` | Venice Small (Qwen3 4B) | 32k | 快速，推理 |
| `deepseek-v3.2` | DeepSeek V3.2 | 163k | 推理 |
| `venice-uncensored` | Venice Uncensored | 32k | 无审查 |
| `mistral-31-24b` | Venice Medium (Mistral) | 131k | 视觉 |
| `google-gemma-3-27b-it` | Gemma 3 27B Instruct | 202k | 视觉 |
| `openai-gpt-oss-120b` | OpenAI GPT OSS 120B | 131k | 通用 |
| `zai-org-glm-4.7` | GLM 4.7 | 202k | 推理，多语言 |
| 模型 ID | 名称 | 上下文 | 功能 |
| -------------------------------------- | ------------------------------------ | ------ | ------------------ |
| `kimi-k2-5` | Kimi K2.5 | 256k | 默认、推理、视觉 |
| `kimi-k2-thinking` | Kimi K2 Thinking | 256k | 推理 |
| `llama-3.3-70b` | Llama 3.3 70B | 128k | 通用 |
| `llama-3.2-3b` | Llama 3.2 3B | 128k | 通用 |
| `hermes-3-llama-3.1-405b` | Hermes 3 Llama 3.1 405B | 128k | 通用，工具已禁用 |
| `qwen3-235b-a22b-thinking-2507` | Qwen3 235B Thinking | 128k | 推理 |
| `qwen3-235b-a22b-instruct-2507` | Qwen3 235B Instruct | 128k | 通用 |
| `qwen3-coder-480b-a35b-instruct` | Qwen3 Coder 480B | 256k | 编码 |
| `qwen3-coder-480b-a35b-instruct-turbo` | Qwen3 Coder 480B Turbo | 256k | 编码 |
| `qwen3-5-35b-a3b` | Qwen3.5 35B A3B | 256k | 推理、视觉 |
| `qwen3-next-80b` | Qwen3 Next 80B | 256k | 通用 |
| `qwen3-vl-235b-a22b` | Qwen3 VL 235B（视觉） | 256k | 视觉 |
| `qwen3-4b` | Venice Small（Qwen3 4B） | 32k | 快速、推理 |
| `deepseek-v3.2` | DeepSeek V3.2 | 160k | 推理，工具已禁用 |
| `venice-uncensored` | Venice Uncensored（Dolphin-Mistral） | 32k | 未审查，工具已禁用 |
| `mistral-31-24b` | Venice Medium（Mistral） | 128k | 视觉 |
| `google-gemma-3-27b-it` | Google Gemma 3 27B Instruct | 198k | 视觉 |
| `openai-gpt-oss-120b` | OpenAI GPT OSS 120B | 128k | 通用 |
| `nvidia-nemotron-3-nano-30b-a3b` | NVIDIA Nemotron 3 Nano 30B | 128k | 通用 |
| `olafangensan-glm-4.7-flash-heretic` | GLM 4.7 Flash Heretic | 128k | 推理 |
| `zai-org-glm-4.6` | GLM 4.6 | 198k | 通用 |
| `zai-org-glm-4.7` | GLM 4.7 | 198k | 推理 |
| `zai-org-glm-4.7-flash` | GLM 4.7 Flash | 128k | 推理 |
| `zai-org-glm-5` | GLM 5 | 198k | 推理 |
| `minimax-m21` | MiniMax M2.1 | 198k | 推理 |
| `minimax-m25` | MiniMax M2.5 | 198k | 推理 |
### 匿名化模型（10 个）— 通过 Venice 代理
### 匿名模型（15 个）—— 通过 Venice 代理
| 模型 ID | 原始模型 | 上下文（token） | 特性 |
| ------------------------ | ----------------- | --------------- | ---------- |
| `claude-opus-45` | Claude Opus 4.5 | 202k | 推理，视觉 |
| `claude-sonnet-45` | Claude Sonnet 4.5 | 202k | 推理，视觉 |
| `openai-gpt-52` | GPT-5.2 | 262k | 推理 |
| `openai-gpt-52-codex` | GPT-5.2 Codex | 262k | 推理，视觉 |
| `gemini-3-pro-preview` | Gemini 3 Pro | 202k | 推理，视觉 |
| `gemini-3-flash-preview` | Gemini 3 Flash | 262k | 推理，视觉 |
| `grok-41-fast` | Grok 4.1 Fast | 262k | 推理，视觉 |
| `grok-code-fast-1` | Grok Code Fast 1 | 262k | 推理，编程 |
| `kimi-k2-thinking` | Kimi K2 Thinking | 262k | 推理 |
| `minimax-m21` | MiniMax M2.1 | 202k | 推理 |
| 模型 ID | 名称 | 上下文 | 功能 |
| ------------------------------- | -------------------------------- | ------ | ---------------- |
| `claude-opus-4-6` | Claude Opus 4.6（通过 Venice） | 1M | 推理、视觉 |
| `claude-opus-4-5` | Claude Opus 4.5（通过 Venice） | 198k | 推理、视觉 |
| `claude-sonnet-4-6` | Claude Sonnet 4.6（通过 Venice） | 1M | 推理、视觉 |
| `claude-sonnet-4-5` | Claude Sonnet 4.5（通过 Venice） | 198k | 推理、视觉 |
| `openai-gpt-54` | GPT-5.4（通过 Venice） | 1M | 推理、视觉 |
| `openai-gpt-53-codex` | GPT-5.3 Codex（通过 Venice） | 400k | 推理、视觉、编码 |
| `openai-gpt-52` | GPT-5.2（通过 Venice） | 256k | 推理 |
| `openai-gpt-52-codex` | GPT-5.2 Codex（通过 Venice） | 256k | 推理、视觉、编码 |
| `openai-gpt-4o-2024-11-20` | GPT-4o（通过 Venice） | 128k | 视觉 |
| `openai-gpt-4o-mini-2024-07-18` | GPT-4o Mini（通过 Venice） | 128k | 视觉 |
| `gemini-3-1-pro-preview` | Gemini 3.1 Pro（通过 Venice） | 1M | 推理、视觉 |
| `gemini-3-pro-preview` | Gemini 3 Pro（通过 Venice） | 198k | 推理、视觉 |
| `gemini-3-flash-preview` | Gemini 3 Flash（通过 Venice） | 256k | 推理、视觉 |
| `grok-41-fast` | Grok 4.1 Fast（通过 Venice） | 1M | 推理、视觉 |
| `grok-code-fast-1` | Grok Code Fast 1（通过 Venice） | 256k | 推理、编码 |
## 模型发现
当设置了 `VENICE_API_KEY` 时，OpenClaw 会自动从 Venice API 发现模型。如果 API 不可达，则回退到静态目录。
当设置了 `VENICE_API_KEY` 时，OpenClaw 会自动从 Venice API 发现模型。如果 API 不可访问，则会回退到静态目录。
`/models` 端点是公开的（列出模型无需认证），但推理需要有效的 API 密钥。
`/models` 端点是公开的（列出模型无需身份验证），但推理需要有效的 API 密钥。
## 流式输出与工具支持
## 流式传输与工具支持
| 功能 | 支持情况 |
| ------------- | ---------------------------------------------------------- |
| **流式输出** | ✅ 所有模型 |
| **流式传输** | ✅ 所有模型 |
| **函数调用** | ✅ 大多数模型（请检查 API 中的 `supportsFunctionCalling`） |
| **视觉/图像** | ✅ 标记为"视觉"特性的模型 |
| **视觉/图像** | ✅ 标有 “Vision” 功能的模型 |
| **JSON 模式** | ✅ 通过 `response_format` 支持 |
## 定价
Venice 使用积分制。请查看 [venice.ai/pricing](https://venice.ai/pricing) 了解当前费率：
Venice 使用基于积分的系统。当前费率请查看 [venice.ai/pricing](https://venice.ai/pricing)：
- **私密模型**：通常成本较低
- **匿名化模型**：与直接 API 定价相近 + 少量 Venice 费用
- **私密模型**：通常成本更低
- **匿名模型**：与直接 API 定价相近，外加少量 Venice 费用
## 对比：Venice 与直接 API
| 方面 | Venice（匿名化） | 直接 API |
| -------- | ------------------ | ------------ |
| **隐私** | 剥离元数据，匿名化 | 关联你的账户 |
| **延迟** | +10-50ms（代理） | 直连 |
| **功能** | 支持大部分功能 | 完整功能 |
| **计费** | Venice 积分 | 提供商计费 |
| 方面 | Venice（匿名） | 直接 API |
| -------- | -------------------- | -------------- |
| **隐私** | 元数据被剥离，匿名化 | 关联到你的账户 |
| **延迟** | +10-50ms（代理） | 直接 |
| **功能** | 支持大多数功能 | 完整功能 |
| **计费** | Venice 积分 | 提供商计费 |
## 使用示例
```bash
# 使用默认私密模型
openclaw chat --model venice/llama-3.3-70b
openclaw agent --model venice/kimi-k2-5 --message "Quick health check"
# 通过 Venice 使用 Claude（匿名化）
openclaw chat --model venice/claude-opus-45
# 通过 Venice 使用 Claude Opus（匿名）
openclaw agent --model venice/claude-opus-4-6 --message "Summarize this task"
# 使用无审查模型
openclaw chat --model venice/venice-uncensored
# 使用未审查模型
openclaw agent --model venice/venice-uncensored --message "Draft options"
# 使用视觉模型处理图像
openclaw chat --model venice/qwen3-vl-235b-a22b
# 使用带图像的视觉模型
openclaw agent --model venice/qwen3-vl-235b-a22b --message "Review attached image"
# 使用编程模型
openclaw chat --model venice/qwen3-coder-480b-a35b-instruct
# 使用编码模型
openclaw agent --model venice/qwen3-coder-480b-a35b-instruct --message "Refactor this function"
```
## 故障排除
@ -226,22 +241,22 @@ echo $VENICE_API_KEY
openclaw models list | grep venice
```
确保密钥以 `vapi_` 开头。
请确保该密钥以 `vapi_` 开头。
### 模型不可用
Venice 模型目录会动态更新。运行 `openclaw models list` 查看当前可用的模型。部分模型可能暂时离线。
Venice 模型目录会动态更新。运行 `openclaw models list` 以查看当前可用的模型。某些模型可能暂时离线。
### 连接问题
Venice API 地址为 `https://api.venice.ai/api/v1`。确保你的网络允许 HTTPS 连接。
Venice API 地址为 `https://api.venice.ai/api/v1`。请确保你的网络允许 HTTPS 连接。
## 配置文件示例
```json5
{
env: { VENICE_API_KEY: "vapi_..." },
agents: { defaults: { model: { primary: "venice/llama-3.3-70b" } } },
agents: { defaults: { model: { primary: "venice/kimi-k2-5" } } },
models: {
mode: "merge",
providers: {
@ -251,13 +266,13 @@ Venice API 地址为 `https://api.venice.ai/api/v1`。确保你的网络允许 H
api: "openai-completions",
models: [
{
id: "llama-3.3-70b",
name: "Llama 3.3 70B",
reasoning: false,
input: ["text"],
id: "kimi-k2-5",
name: "Kimi K2.5",
reasoning: true,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 131072,
maxTokens: 8192,
contextWindow: 256000,
maxTokens: 65536,
},
],
},
@ -269,6 +284,6 @@ Venice API 地址为 `https://api.venice.ai/api/v1`。确保你的网络允许 H
## 链接
- [Venice AI](https://venice.ai)
- [API 文档](https://docs.venice.ai)
- [定价](https://venice.ai/pricing)
- [状态页](https://status.venice.ai)
- [API Documentation](https://docs.venice.ai)
- [Pricing](https://venice.ai/pricing)
- [Status](https://status.venice.ai)

35
docs/zh-CN/providers/vercel-ai-gateway.md
View File

@ -1,29 +1,31 @@
---
read_when:
- 你想将 Vercel AI Gateway 与 OpenClaw 配合使用
- 你需要 API 密钥环境变量或 CLI 认证选择
- 你想将 Vercel AI Gateway 与 OpenClaw 一起使用
- 你需要 API key 环境变量或 CLI 认证选项
summary: Vercel AI Gateway 设置（认证 + 模型选择）
title: Vercel AI Gateway
x-i18n:
generated_at: "2026-02-03T07:53:39Z"
model: claude-opus-4-5
provider: pi
source_hash: c6482f047a31b09c7a691d40babbd1f9fb3aa2042b61cc42956ad9b791da8285
generated_at: "2026-03-16T06:27:18Z"
model: gpt-5.4
provider: openai
source_hash: f30768dc3db49708b25042d317906f7ad9a2c72b0fa03263bc04f5eefbf7a507
source_path: providers/vercel-ai-gateway.md
workflow: 15
---
# Vercel AI Gateway
[Vercel AI Gateway](https://vercel.com/ai-gateway) 提供了一个统一的 API，通过单一端点访问数百个模型。
[Vercel AI Gateway](https://vercel.com/ai-gateway) 提供统一 API，可通过单个端点访问数百个模型。
- 提供商：`vercel-ai-gateway`
- 认证：`AI_GATEWAY_API_KEY`
- API：兼容 Anthropic Messages
- OpenClaw 会自动发现 Gateway 的 `/v1/models` 目录，因此 `/models vercel-ai-gateway`
会包含当前模型引用，例如 `vercel-ai-gateway/openai/gpt-5.4`。
## 快速开始
1. 设置 API 密钥（推荐：为 Gateway 网关存储它）：
1. 设置 API key（推荐：为 Gateway 网关持久保存它）：
```bash
openclaw onboard --auth-choice ai-gateway-api-key
@ -35,7 +37,7 @@ openclaw onboard --auth-choice ai-gateway-api-key
{
agents: {
defaults: {
model: { primary: "vercel-ai-gateway/anthropic/claude-opus-4.5" },
model: { primary: "vercel-ai-gateway/anthropic/claude-opus-4.6" },
},
},
}
@ -50,8 +52,15 @@ openclaw onboard --non-interactive \
--ai-gateway-api-key "$AI_GATEWAY_API_KEY"
```
## 环境变量说明
## 环境说明
如果 Gateway 网关作为守护进程运行（launchd/systemd），请确保 `AI_GATEWAY_API_KEY`
对该进程可用（例如，在 `~/.openclaw/.env` 中或通过
`env.shellEnv`）。
如果 Gateway 作为守护进程运行（launchd/systemd），请确保 `AI_GATEWAY_API_KEY`
对此进程可用（例如放在 `~/.openclaw/.env` 中，或通过
`env.shellEnv` 提供）。
## 模型 ID 简写
OpenClaw 接受 Vercel Claude 简写模型引用，并会在运行时将其规范化：
- `vercel-ai-gateway/claude-opus-4.6` -> `vercel-ai-gateway/anthropic/claude-opus-4.6`
- `vercel-ai-gateway/opus-4.6` -> `vercel-ai-gateway/anthropic/claude-opus-4-6`

25
docs/zh-CN/providers/xiaomi.md
View File

@ -1,13 +1,13 @@
---
read_when:
- 你想在 OpenClaw 中使用 Xiaomi MiMo 模型
- 你需要设置 XIAOMI_API_KEY
summary: 在 OpenClaw 中使用 Xiaomi MiMo (mimo-v2-flash)
- 你需要设置 `XIAOMI_API_KEY`
summary: 在 OpenClaw 中使用 Xiaomi MiMo（`mimo-v2-flash`）
title: Xiaomi MiMo
x-i18n:
generated_at: "2026-02-01T21:36:15Z"
model: claude-opus-4-5
provider: pi
generated_at: "2026-03-16T06:27:26Z"
model: gpt-5.4
provider: openai
source_hash: 366fd2297b2caf8c5ad944d7f1b6d233b248fe43aedd22a28352ae7f370d2435
source_path: providers/xiaomi.md
workflow: 15
@ -15,13 +15,16 @@ x-i18n:
# Xiaomi MiMo
Xiaomi MiMo 是 **MiMo** 模型的 API 平台。它提供与 OpenAI 和 Anthropic 格式兼容的 REST API，并使用 API 密钥进行身份验证。请在 [Xiaomi MiMo 控制台](https://platform.xiaomimimo.com/#/console/api-keys) 中创建你的 API 密钥。OpenClaw 使用 `xiaomi` 提供商配合 Xiaomi MiMo API 密钥。
Xiaomi MiMo 是 **MiMo** 模型的 API 平台。它提供与
OpenAI 和 Anthropic 格式兼容的 REST API，并使用 API key 进行认证。请在
[Xiaomi MiMo console](https://platform.xiaomimimo.com/#/console/api-keys) 中创建你的 API key。OpenClaw 使用
`xiaomi` 提供商配合 Xiaomi MiMo API key。
## 模型概览
- **mimo-v2-flash**：262144 token 上下文窗口，兼容 Anthropic Messages API。
- 基础 URL：`https://api.xiaomimimo.com/anthropic`
- 授权方式：`Bearer $XIAOMI_API_KEY`
- **mimo-v2-flash**：262144-token 上下文窗口，兼容 Anthropic Messages API。
- Base URL：`https://api.xiaomimimo.com/anthropic`
- 认证方式：`Bearer $XIAOMI_API_KEY`
## CLI 设置
@ -61,8 +64,8 @@ openclaw onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY"
}
```
## 备注
## 说明
- 模型引用：`xiaomi/mimo-v2-flash`。
- 当设置了 `XIAOMI_API_KEY`（或存在身份验证配置文件）时，该提供商会自动注入。
- 当设置了 `XIAOMI_API_KEY`（或存在凭证配置文件）时，提供商会自动注入。
- 有关提供商规则，请参阅 [/concepts/model-providers](/concepts/model-providers)。

42
docs/zh-CN/providers/zai.md
View File

@ -1,28 +1,38 @@
---
read_when:
- 你想在 OpenClaw 中使用 Z.AI / GLM 模型
- 你需要简单的 ZAI_API_KEY 配置
summary: 在 OpenClaw 中使用智谱 AI（GLM 模型）
- 你需要简单的 `ZAI_API_KEY` 设置
summary: 在 OpenClaw 中使用 Z.AI（GLM 模型）
title: Z.AI
x-i18n:
generated_at: "2026-02-01T21:36:13Z"
model: claude-opus-4-5
provider: pi
source_hash: 2c24bbad86cf86c38675a58e22f9e1b494f78a18fdc3051c1be80d2d9a800711
generated_at: "2026-03-16T06:27:34Z"
model: gpt-5.4
provider: openai
source_hash: 79ea8f3d6c286b5fef090e54257eb7c60c82b29630cee3f54e96161e55349bf5
source_path: providers/zai.md
workflow: 15
---
# Z.AI
Z.AI 是 **GLM** 模型的 API 平台。它为 GLM 提供 REST API，并使用 API 密钥进行身份验证。请在 Z.AI 控制台中创建你的 API 密钥。OpenClaw 通过 `zai` 提供商配合 Z.AI API 密钥使用。
Z.AI 是 **GLM** 模型的 API 平台。它为 GLM 提供 REST API，并使用 API key
进行认证。请在 Z.AI 控制台中创建你的 API key。OpenClaw 使用 `zai` 提供商
配合 Z.AI API key。
## CLI 设置
```bash
openclaw onboard --auth-choice zai-api-key
# 或非交互式
openclaw onboard --zai-api-key "$ZAI_API_KEY"
# Coding Plan Global，推荐给 Coding Plan 用户
openclaw onboard --auth-choice zai-coding-global
# Coding Plan CN（中国区域），推荐给 Coding Plan 用户
openclaw onboard --auth-choice zai-coding-cn
# 通用 API
openclaw onboard --auth-choice zai-global
# 通用 API CN（中国区域）
openclaw onboard --auth-choice zai-cn
```
## 配置片段
@ -30,12 +40,14 @@ openclaw onboard --zai-api-key "$ZAI_API_KEY"
```json5
{
env: { ZAI_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "zai/glm-4.7" } } },
agents: { defaults: { model: { primary: "zai/glm-5" } } },
}
```
## 注意事项
## 说明
- GLM 模型以 `zai/<model>` 的形式提供（例如：`zai/glm-4.7`）。
- 参阅 [/providers/glm](/providers/glm) 了解模型系列概览。
- Z.AI 使用 Bearer 认证方式配合你的 API 密钥。
- GLM 模型可用作 `zai/<model>`（例如：`zai/glm-5`）。
- `tool_stream` 默认启用，用于 Z.AI 工具调用流式传输。若要禁用，请设置
`agents.defaults.models["zai/<model>"].params.tool_stream` 为 `false`。
- 关于模型家族概览，请参阅 [/providers/glm](/providers/glm)。
- Z.AI 使用带有你的 API key 的 Bearer 认证。

243
docs/zh-CN/reference/wizard.md
View File

@ -1,9 +1,242 @@
---
summary: Onboarding 向导参考：完整步骤、参数与配置字段
title: 向导参考
sidebarTitle: 向导参考
read_when:
- 查找特定的向导步骤或标志
- 使用非交互模式自动执行新手引导
- 调试向导行为
sidebarTitle: Wizard Reference
summary: CLI 设置向导的完整参考：每个步骤、标志和配置字段
title: 设置向导参考
x-i18n:
generated_at: "2026-03-16T06:28:28Z"
model: gpt-5.4
provider: openai
source_hash: f6560ef9921e58e4fe7f9b23872c0f8bbf3a0a3c4449d686752fc5b5b50bb216
source_path: reference/wizard.md
workflow: 15
---
# 向导参考
# 设置向导参考
该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Onboarding Wizard Reference](/reference/wizard)。
这是 `openclaw onboard` CLI 向导的完整参考。
有关高层概览，请参阅 [设置向导](/start/wizard)。
## 流程详情（本地模式）
<Steps>
<Step title="现有配置检测">
- 如果 `~/.openclaw/openclaw.json` 存在，请选择 **Keep / Modify / Reset**。
- 重新运行向导**不会**清除任何内容，除非你明确选择 **Reset**
（或传入 `--reset`）。
- CLI `--reset` 默认值为 `config+creds+sessions`；使用 `--reset-scope full`
可额外移除工作区。
- 如果配置无效或包含旧版键，向导会停止，并要求
你先运行 `openclaw doctor` 再继续。
- 重置会使用 `trash`（绝不使用 `rm`），并提供以下范围：
- 仅配置
- 配置 + 凭证 + 会话
- 完整重置（也会移除工作区）
</Step>
<Step title="模型/认证">
- **Anthropic API key**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示输入 key，然后保存以供守护进程使用。
- **Anthropic OAuth（Claude Code CLI）**：在 macOS 上，向导会检查钥匙串项目 “Claude Code-credentials”（请选择 “Always Allow”，这样 launchd 启动时就不会被阻塞）；在 Linux/Windows 上，如果存在，则会重用 `~/.claude/.credentials.json`。
- **Anthropic token（粘贴 setup-token）**：在任意机器上运行 `claude setup-token`，然后粘贴该 token（你可以为其命名；留空 = default）。
- **OpenAI Code (Codex) 订阅（Codex CLI）**：如果 `~/.codex/auth.json` 存在，向导可以重用它。
- **OpenAI Code (Codex) 订阅（OAuth）**：浏览器流程；粘贴 `code#state`。
- 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.2`。
- **OpenAI API key**：如果存在则使用 `OPENAI_API_KEY`，否则提示输入 key，然后将其存储到凭证配置文件中。
- **xAI（Grok）API key**：提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。
- **OpenCode**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，可从 https://opencode.ai/auth 获取），并让你选择 Zen 或 Go 目录。
- **Ollama**：提示输入 Ollama base URL，提供 **Cloud + Local** 或 **Local** 模式，发现可用模型，并在需要时自动拉取所选本地模型。
- 更多细节： [Ollama](/providers/ollama)
- **API key**：为你存储该 key。
- **Vercel AI Gateway（多模型代理）**：提示输入 `AI_GATEWAY_API_KEY`。
- 更多细节： [Vercel AI Gateway](/providers/vercel-ai-gateway)
- **Cloudflare AI Gateway**：提示输入 Account ID、Gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。
- 更多细节： [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
- **MiniMax M2.5**：自动写入配置。
- 更多细节： [MiniMax](/providers/minimax)
- **Synthetic（Anthropic 兼容）**：提示输入 `SYNTHETIC_API_KEY`。
- 更多细节： [Synthetic](/providers/synthetic)
- **Moonshot（Kimi K2）**：自动写入配置。
- **Kimi Coding**：自动写入配置。
- 更多细节： [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
- **Skip**：暂不配置认证。
- 从已检测到的选项中选择默认模型（或手动输入 `provider/model`）。为了获得最佳质量并降低 prompt injection 风险，请选择你在提供商栈中可用的最强最新一代模型。
- 向导会运行模型检查，并在所配置模型未知或缺少认证时发出警告。
- API key 存储模式默认为明文 auth-profile 值。使用 `--secret-input-mode ref` 可改为存储基于环境变量的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。
- OAuth 凭证保存在 `~/.openclaw/credentials/oauth.json`；auth-profile 保存在 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（API key + OAuth）。
- 更多细节： [/concepts/oauth](/concepts/oauth)
<Note>
无头/服务器提示：在有浏览器的机器上完成 OAuth，然后将
`~/.openclaw/credentials/oauth.json`（或 `$OPENCLAW_STATE_DIR/credentials/oauth.json`）复制到
Gateway 网关主机上。
</Note>
</Step>
<Step title="工作区">
- 默认为 `~/.openclaw/workspace`（可配置）。
- 为工作区植入智能体引导仪式所需的文件。
- 完整工作区布局 + 备份指南： [智能体工作区](/concepts/agent-workspace)
</Step>
<Step title="Gateway 网关">
- Port、bind、auth mode、tailscale 暴露方式。
- 认证建议：即使是 loopback，也保留 **Token**，这样本地 WS 客户端也必须进行认证。
- 在 token 模式下，交互式设置提供：
- **生成/存储明文 token**（默认）
- **使用 SecretRef**（可选启用）
- 快速开始会在新手引导探测/dashboard 引导期间，跨 `env`、`file` 和 `exec` 提供商重用现有的 `gateway.auth.token` SecretRef。
- 如果该 SecretRef 已配置但无法解析，则新手引导会提前失败，并给出明确修复信息，而不是静默降级运行时认证。
- 在 password 模式下，交互式设置也支持明文或 SecretRef 存储。
- 非交互式 token SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
- 要求新手引导进程环境中存在非空环境变量。
- 不能与 `--gateway-token` 组合使用。
- 仅当你完全信任每个本地进程时，才禁用认证。
- 非 loopback 绑定仍然需要认证。
</Step>
<Step title="渠道">
- [WhatsApp](/channels/whatsapp)：可选 QR 登录。
- [Telegram](/channels/telegram)：bot token。
- [Discord](/channels/discord)：bot token。
- [Google Chat](/channels/googlechat)：服务账号 JSON + webhook audience。
- [Mattermost](/channels/mattermost)（插件）：bot token + base URL。
- [Signal](/channels/signal)：可选安装 `signal-cli` + 账号配置。
- [BlueBubbles](/channels/bluebubbles)：**iMessage 推荐方案**；server URL + password + webhook。
- [iMessage](/channels/imessage)：旧版 `imsg` CLI 路径 + 数据库访问。
- 私信安全：默认为 pairing。首次私信会发送一个代码；通过 `openclaw pairing approve <channel> <code>` 批准，或使用允许列表。
</Step>
<Step title="Web 搜索">
- 选择一个提供商：Perplexity、Brave、Gemini、Grok 或 Kimi（也可跳过）。
- 粘贴你的 API key（QuickStart 会自动从环境变量或现有配置中检测 key）。
- 使用 `--skip-search` 跳过。
- 之后再配置：`openclaw configure --section web`。
</Step>
<Step title="守护进程安装">
- macOS：LaunchAgent
- 需要已登录的用户会话；无头场景请使用自定义 LaunchDaemon（未随产品提供）。
- Linux（以及通过 WSL2 的 Windows）：systemd 用户单元
- 向导会尝试启用 lingering：`loginctl enable-linger <user>`，以便 Gateway 网关在注销后仍保持运行。
- 可能会提示输入 sudo（会写入 `/var/lib/systemd/linger`）；它会先尝试不使用 sudo。
- **运行时选择：** Node（推荐；WhatsApp/Telegram 必需）。**不推荐** Bun。
- 如果 token 认证需要 token，并且 `gateway.auth.token` 由 SecretRef 管理，则守护进程安装会验证它，但不会将解析出的明文 token 值持久化到 supervisor 服务环境元数据中。
- 如果 token 认证需要 token，但配置的 token SecretRef 尚未解析，则会阻止守护进程安装，并给出可执行指导。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，则会阻止守护进程安装，直到显式设置 mode。
</Step>
<Step title="健康检查">
- 启动 Gateway 网关（如果需要）并运行 `openclaw health`。
- 提示：`openclaw status --deep` 会在状态输出中添加 Gateway 网关健康探测（需要能访问到 Gateway 网关）。
</Step>
<Step title="Skills（推荐）">
- 读取可用的 Skills 并检查要求。
- 让你选择一个 node manager：**npm / pnpm**（不推荐 bun）。
- 安装可选依赖（某些在 macOS 上使用 Homebrew）。
</Step>
<Step title="完成">
- 摘要 + 后续步骤，包括可提供额外功能的 iOS/Android/macOS 应用。
</Step>
</Steps>
<Note>
如果未检测到 GUI，向导会打印用于访问 Control UI 的 SSH 端口转发说明，而不是打开浏览器。
如果缺少 Control UI 资源，向导会尝试构建它们；回退方式是 `pnpm ui:build`（会自动安装 UI 依赖）。
</Note>
## 非交互模式
使用 `--non-interactive` 自动化或脚本化新手引导：
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice apiKey \
--anthropic-api-key "$ANTHROPIC_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback \
--install-daemon \
--daemon-runtime node \
--skip-skills
```
添加 `--json` 可获得机器可读摘要。
在非交互模式中使用 Gateway token SecretRef：
```bash
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
--mode local \
--auth-choice skip \
--gateway-auth token \
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN
```
`--gateway-token` 和 `--gateway-token-ref-env` 互斥。
<Note>
`--json` **并不**意味着非交互模式。脚本中请使用 `--non-interactive`（以及 `--workspace`）。
</Note>
特定提供商的命令示例位于 [CLI Automation](/start/wizard-cli-automation#provider-specific-examples)。
本参考页用于说明标志语义和步骤顺序。
### 添加智能体（非交互）
```bash
openclaw agents add work \
--workspace ~/.openclaw/workspace-work \
--model openai/gpt-5.2 \
--bind whatsapp:biz \
--non-interactive \
--json
```
## Gateway 网关向导 RPC
Gateway 网关通过 RPC 暴露向导流程（`wizard.start`、`wizard.next`、`wizard.cancel`、`wizard.status`）。
客户端（macOS 应用、Control UI）可以渲染这些步骤，而无需重新实现新手引导逻辑。
## Signal 设置（signal-cli）
向导可以从 GitHub releases 安装 `signal-cli`：
- 下载适合的发布资源。
- 将其存储到 `~/.openclaw/tools/signal-cli/<version>/` 下。
- 将 `channels.signal.cliPath` 写入你的配置。
说明：
- JVM 构建需要 **Java 21**。
- 在可用时会使用原生构建。
- Windows 使用 WSL2；`signal-cli` 安装会在 WSL 中遵循 Linux 流程。
## 向导会写入的内容
`~/.openclaw/openclaw.json` 中的典型字段：
- `agents.defaults.workspace`
- `agents.defaults.model` / `models.providers`（如果选择了 Minimax）
- `tools.profile`（本地新手引导在未设置时默认为 `"coding"`；已有的显式值会被保留）
- `gateway.*`（mode、bind、auth、tailscale）
- `session.dmScope`（行为细节： [CLI 设置参考](/start/wizard-cli-reference#outputs-and-internals)）
- `channels.telegram.botToken`、`channels.discord.token`、`channels.signal.*`、`channels.imessage.*`
- 当你在提示中选择启用时，渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）（名称会在可能时解析为 ID）。
- `skills.install.nodeManager`
- `wizard.lastRunAt`
- `wizard.lastRunVersion`
- `wizard.lastRunCommit`
- `wizard.lastRunCommand`
- `wizard.lastRunMode`
`openclaw agents add` 会写入 `agents.list[]` 和可选的 `bindings`。
WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp/<accountId>/` 下。
会话存储在 `~/.openclaw/agents/<agentId>/sessions/` 下。
某些渠道以插件形式提供。当你在设置期间选择其中一个时，向导
会提示先安装它（npm 或本地路径），然后才能配置。
## 相关文档
- 向导概览： [设置向导](/start/wizard)
- macOS 应用新手引导： [新手引导](/start/onboarding)
- 配置参考： [Gateway 配置](/gateway/configuration)
- 提供商： [WhatsApp](/channels/whatsapp)、[Telegram](/channels/telegram)、[Discord](/channels/discord)、[Google Chat](/channels/googlechat)、[Signal](/channels/signal)、[BlueBubbles](/channels/bluebubbles)（iMessage）、[iMessage](/channels/imessage)（旧版）
- Skills： [Skills](/tools/skills)、[Skills 配置](/tools/skills-config)

271
docs/zh-CN/start/getting-started.md
View File

@ -1,206 +1,143 @@
---
read_when:
- 从零开始首次设置
- 你想要从安装 → 新手引导 → 第一条消息的最快路径
summary: 新手指南：从零到第一条消息（向导、认证、渠道、配对）
- 从零开始进行首次设置
- 你想用最快的路径开始可用聊天
summary: 在几分钟内安装 OpenClaw 并开始你的第一次聊天。
title: 入门指南
x-i18n:
generated_at: "2026-02-03T07:54:14Z"
model: claude-opus-4-5
provider: pi
source_hash: 78cfa02eb2e4ea1a83e18edd99d142dbae707ec063e8d74c9a54f94581aa067f
generated_at: "2026-03-16T06:27:55Z"
model: gpt-5.4
provider: openai
source_hash: 47583047c1a603c1254d2540846452ad321d12bc7fc3f24e5def9282ee96f415
source_path: start/getting-started.md
workflow: 15
---
# 入门指南
目标：尽快从**零**到**第一个可用聊天**（使用合理的默认值）。
目标：以最少的设置，从零开始到完成第一次可用聊天。
最快聊天：打开 Control UI（无需渠道设置）。运行 `openclaw dashboard` 并在浏览器中聊天，或在 Gateway 网关主机上打开 `http://127.0.0.1:18789/`。文档：[Dashboard](/web/dashboard) 和 [Control UI](/web/control-ui)。
<Info>
最快的聊天方式：打开 Control UI（无需设置渠道）。运行 `openclaw dashboard`
并在浏览器中聊天，或在
<Tooltip headline="Gateway host" tip="运行 OpenClaw Gateway 网关服务的机器。">网关主机</Tooltip>
上打开 `http://127.0.0.1:18789/`。
文档：[Dashboard](/web/dashboard) 和 [Control UI](/web/control-ui)。
</Info>
推荐路径：使用 **CLI 新手引导向导**（`openclaw onboard`）。它设置：
## 前置条件
- 模型/认证（推荐 OAuth）
- Gateway 网关设置
- 渠道（WhatsApp/Telegram/Discord/Mattermost（插件）/...）
- 配对默认值（安全私信）
- 工作区引导 + Skills
- 可选的后台服务
- 推荐使用 Node 24（Node 22 LTS，目前为 `22.16+`，仍因兼容性而受支持）
如果你想要更深入的参考页面，跳转到：[向导](/start/wizard)、[设置](/start/setup)、[配对](/channels/pairing)、[安全](/gateway/security)。
<Tip>
如果你不确定，请使用 `node --version` 检查你的 Node 版本。
</Tip>
沙箱注意事项：`agents.defaults.sandbox.mode: "non-main"` 使用 `session.mainKey`（默认 `"main"`），因此群组/渠道会话会被沙箱隔离。如果你想要主智能体始终在主机上运行，设置显式的每智能体覆盖：
## 快速设置（CLI）
```json
{
"routing": {
"agents": {
"main": {
"workspace": "~/.openclaw/workspace",
"sandbox": { "mode": "off" }
}
}
}
}
```
<Steps>
<Step title="安装 OpenClaw（推荐）">
<Tabs>
<Tab title="macOS/Linux">
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
<img
src="/assets/install-script.svg"
alt="安装脚本流程"
className="rounded-lg"
/>
</Tab>
<Tab title="Windows（PowerShell）">
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
</Tab>
</Tabs>
## 0) 前置条件
<Note>
其他安装方式和要求： [Install](/install)。
</Note>
- Node `>=22`
- `pnpm`（可选；如果从源代码构建则推荐）
- **推荐：**Brave Search API 密钥用于网页搜索。最简单的方式：`openclaw configure --section web`（存储 `tools.web.search.apiKey`）。参见 [Web 工具](/tools/web)。
</Step>
<Step title="运行设置向导">
```bash
openclaw onboard --install-daemon
```
macOS：如果你计划构建应用，安装 Xcode / CLT。仅用于 CLI + Gateway 网关的话，Node 就足够了。
Windows：使用 **WSL2**（推荐 Ubuntu）。强烈推荐 WSL2；原生 Windows 未经测试，问题更多，工具兼容性更差。先安装 WSL2，然后在 WSL 内运行 Linux 步骤。参见 [Windows (WSL2)](/platforms/windows)。
向导会配置认证、Gateway 网关设置和可选渠道。
详情请参见 [Setup Wizard](/start/wizard)。
## 1) 安装 CLI（推荐）
</Step>
<Step title="检查 Gateway 网关">
如果你已安装服务，它应该已经在运行：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
```bash
openclaw gateway status
```
安装程序选项（安装方法、非交互式、从 GitHub）：[安装](/install)。
</Step>
<Step title="打开 Control UI">
```bash
openclaw dashboard
```
</Step>
</Steps>
Windows (PowerShell)：
<Check>
如果 Control UI 能加载，你的 Gateway 网关就已准备就绪，可以使用。
</Check>
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
## 可选检查和附加内容
替代方案（全局安装）：
<AccordionGroup>
<Accordion title="在前台运行 Gateway 网关">
适合快速测试或故障排除。
```bash
npm install -g openclaw@latest
```
```bash
openclaw gateway --port 18789
```
```bash
pnpm add -g openclaw@latest
```
</Accordion>
<Accordion title="发送一条测试消息">
需要已配置的渠道。
## 2) 运行新手引导向导（并安装服务）
```bash
openclaw message send --target +15555550123 --message "Hello from OpenClaw"
```
```bash
openclaw onboard --install-daemon
```
</Accordion>
</AccordionGroup>
你将选择：
## 常用环境变量
- **本地 vs 远程** Gateway 网关
- **认证**：OpenAI Code (Codex) 订阅（OAuth）或 API 密钥。对于 Anthropic 我们推荐 API 密钥；也支持 `claude setup-token`。
- **提供商**：WhatsApp QR 登录、Telegram/Discord 机器人令牌、Mattermost 插件令牌等。
- **守护进程**：后台安装（launchd/systemd；WSL2 使用 systemd）
- **运行时**：Node（推荐；WhatsApp/Telegram 必需）。**不推荐** Bun。
- **Gateway 网关令牌**：向导默认生成一个（即使在 loopback 上）并存储在 `gateway.auth.token`。
如果你将 OpenClaw 作为服务账户运行，或想使用自定义配置/状态位置：
向导文档：[向导](/start/wizard)
- `OPENCLAW_HOME` 设置用于内部路径解析的主目录。
- `OPENCLAW_STATE_DIR` 覆盖状态目录。
- `OPENCLAW_CONFIG_PATH` 覆盖配置文件路径。
### 凭证：存储位置（重要）
完整的环境变量参考： [环境变量](/help/environment)。
- **推荐的 Anthropic 路径：**设置 API 密钥（向导可以为服务使用存储它）。如果你想复用 Claude Code 凭证，也支持 `claude setup-token`。
## 深入了解
- OAuth 凭证（旧版导入）：`~/.openclaw/credentials/oauth.json`
- 认证配置文件（OAuth + API 密钥）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
<Columns>
<Card title="设置向导（详情）" href="/start/wizard">
完整的 CLI 向导参考和高级选项。
</Card>
<Card title="macOS 应用新手引导" href="/start/onboarding">
macOS 应用的首次运行流程。
</Card>
</Columns>
无头/服务器提示：先在普通机器上完成 OAuth，然后将 `oauth.json` 复制到 Gateway 网关主机。
## 你将获得什么
## 3) 启动 Gateway 网关
- 一个正在运行的 Gateway 网关
- 已配置好的认证
- Control UI 访问权限或一个已连接的渠道
如果你在新手引导期间安装了服务，Gateway 网关应该已经在运行：
## 后续步骤
```bash
openclaw gateway status
```
手动运行（前台）：
```bash
openclaw gateway --port 18789 --verbose
```
Dashboard（local loopback）：`http://127.0.0.1:18789/`
如果配置了令牌，将其粘贴到 Control UI 设置中（存储为 `connect.params.auth.token`）。
⚠️ **Bun 警告（WhatsApp + Telegram）：**Bun 与这些渠道存在已知问题。如果你使用 WhatsApp 或 Telegram，请使用 **Node** 运行 Gateway 网关。
## 3.5) 快速验证（2 分钟）
```bash
openclaw status
openclaw health
openclaw security audit --deep
```
## 4) 配对 + 连接你的第一个聊天界面
### WhatsApp（QR 登录）
```bash
openclaw channels login
```
通过 WhatsApp → 设置 → 链接设备扫描。
WhatsApp 文档：[WhatsApp](/channels/whatsapp)
### Telegram / Discord / 其他
向导可以为你写入令牌/配置。如果你更喜欢手动配置，从这里开始：
- Telegram：[Telegram](/channels/telegram)
- Discord：[Discord](/channels/discord)
- Mattermost（插件）：[Mattermost](/channels/mattermost)
**Telegram 私信提示：**你的第一条私信会返回配对码。批准它（见下一步），否则机器人不会响应。
## 5) 私信安全（配对审批）
默认姿态：未知私信会获得一个短代码，消息在批准之前不会被处理。如果你的第一条私信没有收到回复，批准配对：
```bash
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>
```
配对文档：[配对](/channels/pairing)
## 从源代码（开发）
如果你正在开发 OpenClaw 本身，从源代码运行：
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
openclaw onboard --install-daemon
```
如果你还没有全局安装，从仓库通过 `pnpm openclaw ...` 运行新手引导步骤。`pnpm build` 也会打包 A2UI 资源；如果你只需要运行那个步骤，使用 `pnpm canvas:a2ui:bundle`。
Gateway 网关（从此仓库）：
```bash
node openclaw.mjs gateway --port 18789 --verbose
```
## 7) 验证端到端
在新终端中，发送测试消息：
```bash
openclaw message send --target +15555550123 --message "Hello from OpenClaw"
```
如果 `openclaw health` 显示"未配置认证"，回到向导设置 OAuth/密钥认证——没有它智能体将无法响应。
提示：`openclaw status --all` 是最佳的可粘贴、只读调试报告。
健康探测：`openclaw health`（或 `openclaw status --deep`）向运行中的 Gateway 网关请求健康快照。
## 下一步（可选，但很棒）
- macOS 菜单栏应用 + 语音唤醒：[macOS 应用](/platforms/macos)
- iOS/Android 节点（Canvas/相机/语音）：[节点](/nodes)
- 远程访问（SSH 隧道 / Tailscale Serve）：[远程访问](/gateway/remote) 和 [Tailscale](/gateway/tailscale)
- 常开 / VPN 设置：[远程访问](/gateway/remote)、[exe.dev](/install/exe-dev)、[Hetzner](/install/hetzner)、[macOS 远程](/platforms/mac/remote)
- 私信安全和批准：[Pairing](/channels/pairing)
- 连接更多渠道：[Channels](/channels)
- 高级工作流和源码安装：[Setup](/start/setup)

58
docs/zh-CN/start/onboarding-overview.md Normal file
View File

@ -0,0 +1,58 @@
---
read_when:
- 选择一种新手引导路径
- 设置新环境
sidebarTitle: Onboarding Overview
summary: OpenClaw 新手引导选项与流程概览
title: 新手引导概览
x-i18n:
generated_at: "2026-03-16T06:27:56Z"
model: gpt-5.4
provider: openai
source_hash: 8a22945f0780515be7ec1b94b5ff486828cf9b8f060ab598a31eb17ee0a5c60b
source_path: start/onboarding-overview.md
workflow: 15
---
# 新手引导概览
OpenClaw 支持多种新手引导路径，具体取决于 Gateway 网关运行的位置
以及你偏好的提供商配置方式。
## 选择你的新手引导路径
- 适用于 macOS、Linux 和 Windows（通过 WSL2）的 **CLI 向导**。
- 适用于 Apple silicon 或 Intel Mac 的 **macOS 应用**，提供引导式首次运行体验。
## CLI 设置向导
在终端中运行向导：
```bash
openclaw onboard
```
当你希望完全控制 Gateway 网关、工作区、
渠道和 Skills 时，请使用 CLI 向导。文档：
- [设置向导（CLI）](/start/wizard)
- [`openclaw onboard` 命令](/cli/onboard)
## macOS 应用新手引导
如果你希望在 macOS 上使用完全引导式设置，请使用 OpenClaw 应用。文档：
- [新手引导（macOS 应用）](/start/onboarding)
## 自定义提供商
如果你需要一个未列出的端点，包括那些
公开标准 OpenAI 或 Anthropic API 的托管提供商，请在
CLI 向导中选择 **Custom Provider**。系统会要求你：
- 选择兼容 OpenAI、兼容 Anthropic，或 **Unknown**（自动检测）。
- 输入基础 URL 和 API 密钥（如果提供商需要）。
- 提供模型 ID 和可选别名。
- 选择一个 Endpoint ID，以便多个自定义端点可以共存。
如需详细步骤，请按照上面的 CLI 新手引导文档操作。

222
docs/zh-CN/start/wizard-cli-automation.md Normal file
View File

@ -0,0 +1,222 @@
---
read_when:
- 你正在脚本或 CI 中自动化新手引导
- 你需要特定提供商的非交互式示例
sidebarTitle: CLI automation
summary: 用于 OpenClaw CLI 的脚本化新手引导和智能体设置
title: CLI 自动化
x-i18n:
generated_at: "2026-03-16T06:28:19Z"
model: gpt-5.4
provider: openai
source_hash: 2a82c491616e8c1c2aa6ef5e19bde80b8cccd1e5f7684838b9ce704c33e41b0e
source_path: start/wizard-cli-automation.md
workflow: 15
---
# CLI 自动化
使用 `--non-interactive` 自动化 `openclaw onboard`。
<Note>
`--json` 并不意味着非交互模式。对于脚本，请使用 `--non-interactive`（以及 `--workspace`）。
</Note>
## 基础非交互式示例
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice apiKey \
--anthropic-api-key "$ANTHROPIC_API_KEY" \
--secret-input-mode plaintext \
--gateway-port 18789 \
--gateway-bind loopback \
--install-daemon \
--daemon-runtime node \
--skip-skills
```
添加 `--json` 可获得机器可读的摘要。
使用 `--secret-input-mode ref` 可在认证配置文件中存储基于环境变量的引用，而不是明文值。
在设置向导流程中，支持在环境变量引用与已配置的提供商引用（`file` 或 `exec`）之间进行交互式选择。
在非交互式 `ref` 模式下，必须在进程环境中设置提供商环境变量。
如果传入了内联密钥标志，但缺少匹配的环境变量，现在会快速失败。
示例：
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice openai-api-key \
--secret-input-mode ref \
--accept-risk
```
## 提供商专用示例
<AccordionGroup>
<Accordion title="Gemini 示例">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice gemini-api-key \
--gemini-api-key "$GEMINI_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
</Accordion>
<Accordion title="Z.AI 示例">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice zai-api-key \
--zai-api-key "$ZAI_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
</Accordion>
<Accordion title="Vercel AI Gateway 示例">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice ai-gateway-api-key \
--ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
</Accordion>
<Accordion title="Cloudflare AI Gateway 示例">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice cloudflare-ai-gateway-api-key \
--cloudflare-ai-gateway-account-id "your-account-id" \
--cloudflare-ai-gateway-gateway-id "your-gateway-id" \
--cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
</Accordion>
<Accordion title="Moonshot 示例">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice moonshot-api-key \
--moonshot-api-key "$MOONSHOT_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
</Accordion>
<Accordion title="Mistral 示例">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice mistral-api-key \
--mistral-api-key "$MISTRAL_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
</Accordion>
<Accordion title="Synthetic 示例">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice synthetic-api-key \
--synthetic-api-key "$SYNTHETIC_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
</Accordion>
<Accordion title="OpenCode 示例">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice opencode-zen \
--opencode-zen-api-key "$OPENCODE_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
对 Go 目录，可改用 `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"`。
</Accordion>
<Accordion title="Ollama 示例">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice ollama \
--custom-model-id "qwen3.5:27b" \
--accept-risk \
--gateway-port 18789 \
--gateway-bind loopback
```
</Accordion>
<Accordion title="自定义提供商示例">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice custom-api-key \
--custom-base-url "https://llm.example.com/v1" \
--custom-model-id "foo-large" \
--custom-api-key "$CUSTOM_API_KEY" \
--custom-provider-id "my-custom" \
--custom-compatibility anthropic \
--gateway-port 18789 \
--gateway-bind loopback
```
`--custom-api-key` 是可选的。如果省略，新手引导会检查 `CUSTOM_API_KEY`。
`ref` 模式变体：
```bash
export CUSTOM_API_KEY="your-key"
openclaw onboard --non-interactive \
--mode local \
--auth-choice custom-api-key \
--custom-base-url "https://llm.example.com/v1" \
--custom-model-id "foo-large" \
--secret-input-mode ref \
--custom-provider-id "my-custom" \
--custom-compatibility anthropic \
--gateway-port 18789 \
--gateway-bind loopback
```
在此模式下，新手引导会将 `apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。
</Accordion>
</AccordionGroup>
## 添加另一个智能体
使用 `openclaw agents add <name>` 创建一个单独的智能体，它拥有自己的工作区、
会话和认证配置文件。不带 `--workspace` 运行会启动向导。
```bash
openclaw agents add work \
--workspace ~/.openclaw/workspace-work \
--model openai/gpt-5.2 \
--bind whatsapp:biz \
--non-interactive \
--json
```
它会设置：
- `agents.list[].name`
- `agents.list[].workspace`
- `agents.list[].agentDir`
说明：
- 默认工作区遵循 `~/.openclaw/workspace-<agentId>`。
- 添加 `bindings` 以路由入站消息（向导可以完成这项操作）。
- 非交互式标志：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。
## 相关文档
- 新手引导中心：[设置向导（CLI）](/start/wizard)
- 完整参考：[CLI 设置参考](/start/wizard-cli-reference)
- 命令参考：[`openclaw onboard`](/cli/onboard)

306
docs/zh-CN/start/wizard-cli-reference.md Normal file
View File

@ -0,0 +1,306 @@
---
read_when:
- 你需要了解 `openclaw onboard` 的详细行为
- 你正在调试新手引导结果或集成新手引导客户端
sidebarTitle: CLI reference
summary: CLI 设置流程、身份验证/模型设置、输出和内部机制的完整参考
title: CLI 设置参考
x-i18n:
generated_at: "2026-03-16T06:28:34Z"
model: gpt-5.4
provider: openai
source_hash: 6b9460013b6a0fbd59f639ade6b255c8d7f7412238495e78b942859ade695e86
source_path: start/wizard-cli-reference.md
workflow: 15
---
# CLI 设置参考
本页是 `openclaw onboard` 的完整参考。
简短指南请参见 [设置向导（CLI）](/start/wizard)。
## 向导会执行什么
本地模式（默认）会引导你完成以下内容：
- 模型和身份验证设置（OpenAI Code 订阅 OAuth、Anthropic API 密钥或 setup token，以及 MiniMax、GLM、Ollama、Moonshot 和 AI Gateway 选项）
- 工作区位置和 bootstrap 文件
- Gateway 网关设置（端口、绑定、身份验证、tailscale）
- 渠道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost 插件、Signal）
- 守护进程安装（LaunchAgent 或 systemd 用户单元）
- 健康检查
- Skills 设置
远程模式会将此机器配置为连接到其他位置的网关。
它不会在远程主机上安装或修改任何内容。
## 本地流程详情
<Steps>
<Step title="现有配置检测">
- 如果 `~/.openclaw/openclaw.json` 存在，可选择 Keep、Modify 或 Reset。
- 重新运行向导不会清除任何内容，除非你明确选择 Reset（或传递 `--reset`）。
- CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full` 还会删除工作区。
- 如果配置无效或包含旧版键，向导会停止，并要求你先运行 `openclaw doctor` 再继续。
- Reset 使用 `trash`，并提供以下范围：
- 仅配置
- 配置 + 凭证 + 会话
- 完全重置（也会删除工作区）
</Step>
<Step title="模型和身份验证">
- 完整选项矩阵见 [身份验证和模型选项](#auth-and-model-options)。
</Step>
<Step title="工作区">
- 默认值为 `~/.openclaw/workspace`（可配置）。
- 会植入首次运行 bootstrap 仪式所需的工作区文件。
- 工作区布局：[智能体工作区](/concepts/agent-workspace)。
</Step>
<Step title="Gateway 网关">
- 会提示你输入端口、绑定、身份验证模式和 tailscale 暴露设置。
- 建议：即使仅用于 loopback，也保持启用令牌身份验证，这样本地 WS 客户端也必须进行身份验证。
- 在令牌模式下，交互式设置提供：
- **生成/存储明文令牌**（默认）
- **使用 SecretRef**（可选）
- 在密码模式下，交互式设置也支持明文或 SecretRef 存储。
- 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
- 要求在新手引导进程环境中存在一个非空环境变量。
- 不能与 `--gateway-token` 组合使用。
- 仅当你完全信任每个本地进程时才禁用身份验证。
- 非 loopback 绑定仍然需要身份验证。
</Step>
<Step title="渠道">
- [WhatsApp](/channels/whatsapp)：可选 QR 登录
- [Telegram](/channels/telegram)：bot 令牌
- [Discord](/channels/discord)：bot 令牌
- [Google Chat](/channels/googlechat)：服务账号 JSON + webhook audience
- [Mattermost](/channels/mattermost) 插件：bot 令牌 + 基础 URL
- [Signal](/channels/signal)：可选 `signal-cli` 安装 + 账户配置
- [BlueBubbles](/channels/bluebubbles)：推荐用于 iMessage；服务器 URL + 密码 + webhook
- [iMessage](/channels/imessage)：旧版 `imsg` CLI 路径 + 数据库访问
- 私信安全：默认是配对。首次私信会发送一个代码；通过
`openclaw pairing approve <channel> <code>` 批准，或使用 allowlist。
</Step>
<Step title="守护进程安装">
- macOS：LaunchAgent
- 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随附）。
- Linux 和通过 WSL2 的 Windows：systemd 用户单元
- 向导会尝试执行 `loginctl enable-linger <user>`，使网关在注销后仍保持运行。
- 可能会提示输入 sudo（写入 `/var/lib/systemd/linger`）；会先尝试不使用 sudo。
- 运行时选择：Node（推荐；WhatsApp 和 Telegram 必需）。不建议使用 Bun。
</Step>
<Step title="健康检查">
- 启动 Gateway 网关（如有需要），并运行 `openclaw health`。
- `openclaw status --deep` 会在状态输出中添加 Gateway 网关健康探测。
</Step>
<Step title="Skills">
- 读取可用的 Skills 并检查要求。
- 让你选择 node 管理器：npm 或 pnpm（不建议使用 bun）。
- 安装可选依赖（部分依赖在 macOS 上使用 Homebrew）。
</Step>
<Step title="完成">
- 显示摘要和后续步骤，包括 iOS、Android 和 macOS 应用选项。
</Step>
</Steps>
<Note>
如果未检测到 GUI，向导会打印用于控制 UI 的 SSH 端口转发说明，而不是打开浏览器。
如果缺少控制 UI 资源，向导会尝试构建它们；回退命令为 `pnpm ui:build`（首次运行会自动安装 UI 依赖）。
</Note>
## 远程模式详情
远程模式会将此机器配置为连接到其他位置的网关。
<Info>
远程模式不会在远程主机上安装或修改任何内容。
</Info>
你需要设置的内容：
- 远程 Gateway 网关 URL（`ws://...`）
- 如果远程 Gateway 网关需要身份验证，则设置令牌（推荐）
<Note>
- 如果网关仅绑定到 loopback，请使用 SSH 隧道或 tailnet。
- 发现提示：
- macOS：Bonjour（`dns-sd`）
- Linux：Avahi（`avahi-browse`）
</Note>
## 身份验证和模型选项
<AccordionGroup>
<Accordion title="Anthropic API 密钥">
如果存在 `ANTHROPIC_API_KEY` 则使用它，否则提示输入密钥，然后保存以供守护进程使用。
</Accordion>
<Accordion title="Anthropic OAuth（Claude Code CLI）">
- macOS：检查 Keychain 条目 “Claude Code-credentials”
- Linux 和 Windows：如果存在，则复用 `~/.claude/.credentials.json`
在 macOS 上，请选择 “Always Allow”，以免 launchd 启动被阻塞。
</Accordion>
<Accordion title="Anthropic token（粘贴 setup token）">
在任意机器上运行 `claude setup-token`，然后粘贴该令牌。
你可以为其命名；留空则使用默认值。
</Accordion>
<Accordion title="OpenAI Code 订阅（复用 Codex CLI）">
如果存在 `~/.codex/auth.json`，向导可以复用它。
</Accordion>
<Accordion title="OpenAI Code 订阅（OAuth）">
浏览器流程；粘贴 `code#state`。
当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。
</Accordion>
<Accordion title="OpenAI API 密钥">
如果存在 `OPENAI_API_KEY` 则使用它，否则提示输入密钥，然后将该凭证存储在 auth profile 中。
当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.1-codex`。
</Accordion>
<Accordion title="xAI（Grok）API 密钥">
提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。
</Accordion>
<Accordion title="OpenCode">
提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`），并让你选择 Zen 或 Go 目录。
设置 URL：[opencode.ai/auth](https://opencode.ai/auth)。
</Accordion>
<Accordion title="API 密钥（通用）">
会为你存储该密钥。
</Accordion>
<Accordion title="Vercel AI Gateway">
提示输入 `AI_GATEWAY_API_KEY`。
更多详情：[Vercel AI Gateway](/providers/vercel-ai-gateway)。
</Accordion>
<Accordion title="Cloudflare AI Gateway">
提示输入账户 ID、Gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。
更多详情：[Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)。
</Accordion>
<Accordion title="MiniMax M2.5">
配置会自动写入。
更多详情：[MiniMax](/providers/minimax)。
</Accordion>
<Accordion title="Synthetic（兼容 Anthropic）">
提示输入 `SYNTHETIC_API_KEY`。
更多详情：[Synthetic](/providers/synthetic)。
</Accordion>
<Accordion title="Ollama（Cloud 和本地开放模型）">
提示输入基础 URL（默认 `http://127.0.0.1:11434`），然后提供 Cloud + Local 或 Local 模式。
会发现可用模型并建议默认值。
更多详情：[Ollama](/providers/ollama)。
</Accordion>
<Accordion title="Moonshot 和 Kimi Coding">
Moonshot（Kimi K2）和 Kimi Coding 配置会自动写入。
更多详情：[Moonshot AI（Kimi + Kimi Coding）](/providers/moonshot)。
</Accordion>
<Accordion title="自定义提供商">
适用于兼容 OpenAI 和兼容 Anthropic 的端点。
交互式新手引导支持与其他提供商 API 密钥流程相同的 API 密钥存储选项：
- **现在粘贴 API 密钥**（明文）
- **使用密钥引用**（环境变量引用或已配置提供商引用，并带有预检验证）
非交互式标志：
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key`（可选；回退到 `CUSTOM_API_KEY`）
- `--custom-provider-id`（可选）
- `--custom-compatibility <openai|anthropic>`（可选；默认 `openai`）
</Accordion>
<Accordion title="跳过">
保持身份验证未配置。
</Accordion>
</AccordionGroup>
模型行为：
- 从检测到的选项中选择默认模型，或手动输入提供商和模型。
- 向导会执行模型检查，并在配置的模型未知或缺少身份验证时发出警告。
凭证和配置档案路径：
- OAuth 凭证：`~/.openclaw/credentials/oauth.json`
- Auth profile（API 密钥 + OAuth）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
凭证存储模式：
- 默认新手引导行为会将 API 密钥作为明文值持久化到 auth profile 中。
- `--secret-input-mode ref` 会启用引用模式，而不是明文密钥存储。
在交互式设置中，你可以选择：
- 环境变量引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）
- 已配置提供商引用（`file` 或 `exec`），带提供商别名 + id
- 交互式引用模式会在保存前运行快速预检验证。
- 环境变量引用：验证变量名 + 当前新手引导环境中的非空值。
- 提供商引用：验证提供商配置并解析所请求的 id。
- 如果预检失败，新手引导会显示错误并让你重试。
- 在非交互式模式下，`--secret-input-mode ref` 仅支持由环境变量支持的引用。
- 在新手引导进程环境中设置提供商环境变量。
- 内联密钥标志（例如 `--openai-api-key`）要求设置该环境变量；否则新手引导会快速失败。
- 对于自定义提供商，非交互式 `ref` 模式会将 `models.providers.<id>.apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。
- 在这种自定义提供商场景下，`--custom-api-key` 要求设置 `CUSTOM_API_KEY`；否则新手引导会快速失败。
- Gateway 网关身份验证凭证在交互式设置中支持明文和 SecretRef 选项：
- 令牌模式：**生成/存储明文令牌**（默认）或 **使用 SecretRef**。
- 密码模式：明文或 SecretRef。
- 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
- 现有的明文设置会继续保持不变并正常工作。
<Note>
无头和服务器提示：在有浏览器的机器上完成 OAuth，然后复制
`~/.openclaw/credentials/oauth.json`（或 `$OPENCLAW_STATE_DIR/credentials/oauth.json`）
到 Gateway 网关主机。
</Note>
## 输出和内部机制
`~/.openclaw/openclaw.json` 中的典型字段：
- `agents.defaults.workspace`
- `agents.defaults.model` / `models.providers`（如果选择了 Minimax）
- `tools.profile`（本地新手引导在未设置时默认设为 `"coding"`；现有显式值会保留）
- `gateway.*`（模式、绑定、身份验证、tailscale）
- `session.dmScope`（本地新手引导在未设置时默认设为 `per-channel-peer`；现有显式值会保留）
- `channels.telegram.botToken`、`channels.discord.token`、`channels.signal.*`、`channels.imessage.*`
- 当你在提示中选择加入时的渠道 allowlist（Slack、Discord、Matrix、Microsoft Teams）（如果可能，名称会解析为 ID）
- `skills.install.nodeManager`
- `wizard.lastRunAt`
- `wizard.lastRunVersion`
- `wizard.lastRunCommit`
- `wizard.lastRunCommand`
- `wizard.lastRunMode`
`openclaw agents add` 会写入 `agents.list[]` 和可选的 `bindings`。
WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp/<accountId>/`。
会话存储在 `~/.openclaw/agents/<agentId>/sessions/` 下。
<Note>
某些渠道以插件形式交付。在设置期间选择这些渠道时，向导
会先提示安装插件（npm 或本地路径），然后再进行渠道配置。
</Note>
Gateway 网关向导 RPC：
- `wizard.start`
- `wizard.next`
- `wizard.cancel`
- `wizard.status`
客户端（macOS 应用和控制 UI）可以在不重新实现新手引导逻辑的情况下渲染步骤。
Signal 设置行为：
- 下载适当的发布资源
- 将其存储在 `~/.openclaw/tools/signal-cli/<version>/`
- 在配置中写入 `channels.signal.cliPath`
- JVM 构建需要 Java 21
- 在可用时使用原生构建
- Windows 使用 WSL2，并在 WSL 内遵循 Linux 的 signal-cli 流程
## 相关文档
- 新手引导中心：[设置向导（CLI）](/start/wizard)
- 自动化和脚本：[CLI 自动化](/start/wizard-cli-automation)
- 命令参考：[`openclaw onboard`](/cli/onboard)

371
docs/zh-CN/start/wizard.md
View File

@ -1,331 +1,132 @@
---
read_when:
- 运行或配置新手引导向导
- 设置新机器
summary: CLI 新手引导向导：引导式配置 Gateway 网关、工作区、渠道和 Skills
title: 新手引导向导
- 运行或配置设置向导
- 设置一台新机器
sidebarTitle: "Onboarding: CLI"
summary: CLI 设置向导：用于 Gateway 网关、工作区、渠道和 Skills 的引导式设置
title: 设置向导（CLI）
x-i18n:
generated_at: "2026-02-03T09:20:27Z"
model: claude-opus-4-5
provider: pi
source_hash: 45e10d31048d927ee6546e35b050914f0e6e21a4dee298b3b277eebe7c133732
generated_at: "2026-03-16T06:28:38Z"
model: gpt-5.4
provider: openai
source_hash: 99fd87dddd78798eb0087ad9433e5a32de2af110b6e65ee351b1a194a11c7df3
source_path: start/wizard.md
workflow: 15
---
# 新手引导向导（CLI）
# 设置向导（CLI）
新手引导向导是在 macOS、Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的**推荐**方式。
它可以在一个引导式流程中配置本地 Gateway 网关或远程 Gateway 网关连接，以及渠道、Skills 和工作区默认值。
主要入口：
设置向导是在 macOS、
Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的**推荐**方式。
它可在一次引导式流程中配置本地 Gateway 网关或远程 Gateway 网关连接，以及渠道、Skills
和工作区默认值。
```bash
openclaw onboard
```
最快开始聊天的方式：打开控制界面（无需设置渠道）。运行 `openclaw dashboard` 并在浏览器中聊天。文档：[控制面板](/web/dashboard)。
<Info>
最快的首次聊天方式：打开 Control UI（无需设置渠道）。运行
`openclaw dashboard` 并在浏览器中聊天。文档：[Dashboard](/web/dashboard)。
</Info>
后续重新配置：
若要稍后重新配置：
```bash
openclaw configure
```
推荐：设置 Brave Search API 密钥，以便智能体可以使用 `web_search`（`web_fetch` 无需密钥即可使用）。最简单的方式：`openclaw configure --section web`，它会存储 `tools.web.search.apiKey`。文档：[Web 工具](/tools/web)。
## 快速开始 vs 高级
向导从**快速开始**（默认值）vs **高级**（完全控制）开始。
**快速开始**保持默认值：
- 本地 Gateway 网关（loopback）
- 默认工作区（或现有工作区）
- Gateway 网关端口 **18789**
- Gateway 网关认证 **Token**（自动生成，即使在 loopback 上）
- Tailscale 暴露 **关闭**
- Telegram + WhatsApp 私信默认使用**允许列表**（系统会提示你输入电话号码）
**高级**暴露每个步骤（模式、工作区、Gateway 网关、渠道、守护进程、Skills）。
## 向导做了什么
**本地模式（默认）**引导你完成：
- 模型/认证（OpenAI Code (Codex) 订阅 OAuth、Anthropic API 密钥（推荐）或 setup-token（粘贴），以及 MiniMax/GLM/Moonshot/AI Gateway 选项）
- 工作区位置 + 引导文件
- Gateway 网关设置（端口/绑定/认证/tailscale）
- 提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost（插件）、Signal）
- 守护进程安装（LaunchAgent / systemd 用户单元）
- 健康检查
- Skills（推荐）
**远程模式**仅配置本地客户端连接到其他位置的 Gateway 网关。
它**不会**在远程主机上安装或更改任何内容。
要添加更多隔离的智能体（独立的工作区 + 会话 + 认证），使用：
```bash
openclaw agents add <name>
```
提示：`--json` **不**意味着非交互模式。脚本中请使用 `--non-interactive`（和 `--workspace`）。
<Note>
`--json` 并不意味着非交互模式。对于脚本，请使用 `--non-interactive`。
</Note>
## 流程详情（本地）
<Tip>
设置向导包含一个 web search 步骤，你可以选择一个提供商
（Perplexity、Brave、Gemini、Grok 或 Kimi），并粘贴你的 API 密钥，以便智能体
可以使用 `web_search`。你也可以稍后通过
`openclaw configure --section web` 进行配置。文档：[Web 工具](/tools/web)。
</Tip>
1. **现有配置检测**
- 如果 `~/.openclaw/openclaw.json` 存在，选择**保留 / 修改 / 重置**。
- 重新运行向导**不会**清除任何内容，除非你明确选择**重置**（或传递 `--reset`）。
- 如果配置无效或包含遗留键名，向导会停止并要求你在继续之前运行 `openclaw doctor`。
- 重置使用 `trash`（永不使用 `rm`）并提供范围选项：
- 仅配置
- 配置 + 凭证 + 会话
- 完全重置（同时删除工作区）
## 快速开始与高级模式
2. **模型/认证**
- **Anthropic API 密钥（推荐）**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示输入密钥，然后保存供守护进程使用。
- **Anthropic OAuth（Claude Code CLI）**：在 macOS 上，向导检查钥匙串项目"Claude Code-credentials"（选择"始终允许"以便 launchd 启动不会阻塞）；在 Linux/Windows 上，如果存在则复用 `~/.claude/.credentials.json`。
- **Anthropic 令牌（粘贴 setup-token）**：在任何机器上运行 `claude setup-token`，然后粘贴令牌（你可以命名它；空白 = 默认）。
- **OpenAI Code (Codex) 订阅（Codex CLI）**：如果 `~/.codex/auth.json` 存在，向导可以复用它。
- **OpenAI Code (Codex) 订阅（OAuth）**：浏览器流程；粘贴 `code#state`。
- 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.2`。
- **OpenAI API 密钥**：如果存在则使用 `OPENAI_API_KEY`，否则提示输入密钥，然后保存到 `~/.openclaw/.env` 以便 launchd 可以读取。
- **OpenCode Zen（多模型代理）**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，在 https://opencode.ai/auth 获取）。
- **API 密钥**：为你存储密钥。
- **Vercel AI Gateway（多模型代理）**：提示输入 `AI_GATEWAY_API_KEY`。
- 更多详情：[Vercel AI Gateway](/providers/vercel-ai-gateway)
- **MiniMax M2.1**：自动写入配置。
- 更多详情：[MiniMax](/providers/minimax)
- **Synthetic（Anthropic 兼容）**：提示输入 `SYNTHETIC_API_KEY`。
- 更多详情：[Synthetic](/providers/synthetic)
- **Moonshot（Kimi K2）**：自动写入配置。
- **Kimi Coding**：自动写入配置。
- 更多详情：[Moonshot AI（Kimi + Kimi Coding）](/providers/moonshot)
- **跳过**：尚未配置认证。
- 从检测到的选项中选择默认模型（或手动输入提供商/模型）。
- 向导运行模型检查，如果配置的模型未知或缺少认证则发出警告。
向导开始时会让你选择**快速开始**（默认值）或**高级模式**（完全控制）。
- OAuth 凭证存储在 `~/.openclaw/credentials/oauth.json`；认证配置文件存储在 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（API 密钥 + OAuth）。
- 更多详情：[/concepts/oauth](/concepts/oauth)
<Tabs>
<Tab title="快速开始（默认值）">
- 本地网关（loopback）
- 默认工作区（或现有工作区）
- Gateway 网关端口 **18789**
- Gateway 网关认证 **Token**（即使在 loopback 上也会自动生成）
- 新本地设置的默认工具策略：`tools.profile: "coding"`（会保留现有显式配置文件）
- 私信隔离默认值：本地新手引导会在未设置时写入 `session.dmScope: "per-channel-peer"`。详情见：[CLI 设置参考](/start/wizard-cli-reference#outputs-and-internals)
- Tailscale 暴露 **关闭**
- Telegram + WhatsApp 私信默认使用 **allowlist**（系统会提示你输入电话号码）
</Tab>
<Tab title="高级模式（完全控制）">
- 暴露每一个步骤（模式、工作区、Gateway 网关、渠道、守护进程、Skills）。
</Tab>
</Tabs>
3. **工作区**
- 默认 `~/.openclaw/workspace`（可配置）。
- 为智能体引导仪式播种所需的工作区文件。
- 完整的工作区布局 + 备份指南：[智能体工作区](/concepts/agent-workspace)
## 向导会配置什么
4. **Gateway 网关**
- 端口、绑定、认证模式、tailscale 暴露。
- 认证建议：即使对于 loopback 也保持 **Token**，以便本地 WS 客户端必须进行认证。
- 仅当你完全信任每个本地进程时才禁用认证。
- 非 loopback 绑定仍需要认证。
**本地模式（默认）**会引导你完成以下步骤：
5. **渠道**
- [WhatsApp](/channels/whatsapp)：可选的二维码登录。
- [Telegram](/channels/telegram)：机器人令牌。
- [Discord](/channels/discord)：机器人令牌。
- [Google Chat](/channels/googlechat)：服务账户 JSON + webhook 受众。
- [Mattermost](/channels/mattermost)（插件）：机器人令牌 + 基础 URL。
- [Signal](/channels/signal)：可选的 `signal-cli` 安装 + 账户配置。
- [iMessage](/channels/imessage)：本地 `imsg` CLI 路径 + 数据库访问。
- 私信安全：默认为配对。第一条私信发送验证码；通过 `openclaw pairing approve <channel> <code>` 批准或使用允许列表。
1. **模型/认证** —— 选择任意受支持的提供商/认证流程（API 密钥、OAuth 或 setup-token），包括自定义提供商
（兼容 OpenAI、兼容 Anthropic，或未知自动检测）。选择一个默认模型。
安全说明：如果这个智能体将运行工具或处理 webhook/hooks 内容，请优先选择当前可用的最强最新一代模型，并保持严格的工具策略。较弱/较旧的层级更容易被 prompt 注入。
对于非交互式运行，`--secret-input-mode ref` 会在认证配置文件中存储基于环境变量的引用，而不是明文 API 密钥值。
在非交互式 `ref` 模式下，必须设置提供商环境变量；如果传入内联密钥标志但缺少该环境变量，则会快速失败。
在交互式运行中，选择 secret reference 模式后，你可以指向环境变量或已配置的 provider ref（`file` 或 `exec`），并在保存前进行快速预检校验。
2. **工作区** —— 智能体文件的位置（默认 `~/.openclaw/workspace`）。会植入引导文件。
3. **Gateway 网关** —— 端口、绑定地址、认证模式、Tailscale 暴露。
在交互式 token 模式中，你可以选择默认的明文 token 存储，或选择启用 SecretRef。
非交互式 token SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
4. **渠道** —— WhatsApp、Telegram、Discord、Google Chat、Mattermost、Signal、BlueBubbles 或 iMessage。
5. **守护进程** —— 安装 LaunchAgent（macOS）或 systemd 用户单元（Linux/WSL2）。
如果 token 认证需要 token，且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将已解析的 token 持久化到监督服务的环境元数据中。
如果 token 认证需要 token，而已配置的 token SecretRef 无法解析，守护进程安装会被阻止，并提供可执行的指导。
如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，而 `gateway.auth.mode` 未设置，守护进程安装会被阻止，直到显式设置 mode。
6. **健康检查** —— 启动 Gateway 网关并验证其正在运行。
7. **Skills** —— 安装推荐的 Skills 和可选依赖项。
6. **守护进程安装**
- macOS：LaunchAgent
- 需要已登录的用户会话；对于无头环境，使用自定义 LaunchDaemon（未提供）。
- Linux（和通过 WSL2 的 Windows）：systemd 用户单元
- 向导尝试通过 `loginctl enable-linger <user>` 启用 lingering，以便 Gateway 网关在注销后保持运行。
- 可能提示 sudo（写入 `/var/lib/systemd/linger`）；它首先尝试不使用 sudo。
- **运行时选择：**Node（推荐；WhatsApp/Telegram 需要）。**不推荐** Bun。
<Note>
重新运行向导**不会**清除任何内容，除非你显式选择 **Reset**（或传入 `--reset`）。
CLI `--reset` 默认会重置配置、凭证和会话；如需包含工作区，请使用 `--reset-scope full`。
如果配置无效或包含旧版键，向导会先要求你运行 `openclaw doctor`。
</Note>
7. **健康检查**
- 启动 Gateway 网关（如果需要）并运行 `openclaw health`。
- 提示：`openclaw status --deep` 在状态输出中添加 Gateway 网关健康探测（需要可达的 Gateway 网关）。
8. **Skills（推荐）**
- 读取可用的 Skills 并检查要求。
- 让你选择节点管理器：**npm / pnpm**（不推荐 bun）。
- 安装可选依赖项（某些在 macOS 上使用 Homebrew）。
9. **完成**
- 总结 + 后续步骤，包括用于额外功能的 iOS/Android/macOS 应用。
- 如果未检测到 GUI，向导会打印控制界面的 SSH 端口转发说明，而不是打开浏览器。
- 如果控制界面资源缺失，向导会尝试构建它们；回退方案是 `pnpm ui:build`（自动安装 UI 依赖）。
## 远程模式
远程模式配置本地客户端连接到其他位置的 Gateway 网关。
你将设置的内容：
- 远程 Gateway 网关 URL（`ws://...`）
- 如果远程 Gateway 网关需要认证则需要令牌（推荐）
注意事项：
- 不执行远程安装或守护进程更改。
- 如果 Gateway 网关仅限 loopback，使用 SSH 隧道或 tailnet。
- 发现提示：
- macOS：Bonjour（`dns-sd`）
- Linux：Avahi（`avahi-browse`）
**远程模式**只会配置本地客户端以连接到其他地方的 Gateway 网关。
它**不会**在远程主机上安装或更改任何内容。
## 添加另一个智能体
使用 `openclaw agents add <name>` 创建一个具有独立工作区、会话和认证配置文件的单独智能体。不带 `--workspace` 运行会启动向导。
使用 `openclaw agents add <name>` 创建一个单独的智能体，它拥有自己的工作区、
会话和认证配置文件。不带 `--workspace` 运行会启动向导。
它设置的内容：
它会设置：
- `agents.list[].name`
- `agents.list[].workspace`
- `agents.list[].agentDir`
注意事项：
说明：
- 默认工作区遵循 `~/.openclaw/workspace-<agentId>`。
- 添加 `bindings` 以路由入站消息（向导可以执行此操作）。
- 非交互标志：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。
- 添加 `bindings` 以路由入站消息（向导可以完成这项操作）。
- 非交互式标志：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。
## 非交互模式
## 完整参考
使用 `--non-interactive` 自动化或脚本化新手引导：
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice apiKey \
--anthropic-api-key "$ANTHROPIC_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback \
--install-daemon \
--daemon-runtime node \
--skip-skills
```
添加 `--json` 以获取机器可读的摘要。
Gemini 示例：
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice gemini-api-key \
--gemini-api-key "$GEMINI_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
Z.AI 示例：
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice zai-api-key \
--zai-api-key "$ZAI_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
Vercel AI Gateway 示例：
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice ai-gateway-api-key \
--ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
Moonshot 示例：
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice moonshot-api-key \
--moonshot-api-key "$MOONSHOT_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
Synthetic 示例：
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice synthetic-api-key \
--synthetic-api-key "$SYNTHETIC_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
OpenCode Zen 示例：
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice opencode-zen \
--opencode-zen-api-key "$OPENCODE_API_KEY" \
--gateway-port 18789 \
--gateway-bind loopback
```
添加智能体（非交互）示例：
```bash
openclaw agents add work \
--workspace ~/.openclaw/workspace-work \
--model openai/gpt-5.2 \
--bind whatsapp:biz \
--non-interactive \
--json
```
## Gateway 网关向导 RPC
Gateway 网关通过 RPC 暴露向导流程（`wizard.start`、`wizard.next`、`wizard.cancel`、`wizard.status`）。
客户端（macOS 应用、控制界面）可以渲染步骤而无需重新实现新手引导逻辑。
## Signal 设置（signal-cli）
向导可以从 GitHub releases 安装 `signal-cli`：
- 下载适当的发布资源。
- 存储在 `~/.openclaw/tools/signal-cli/<version>/` 下。
- 将 `channels.signal.cliPath` 写入你的配置。
注意事项：
- JVM 构建需要 **Java 21**。
- 可用时使用原生构建。
- Windows 使用 WSL2；signal-cli 安装在 WSL 内遵循 Linux 流程。
## 向导写入的内容
`~/.openclaw/openclaw.json` 中的典型字段：
- `agents.defaults.workspace`
- `agents.defaults.model` / `models.providers`（如果选择了 Minimax）
- `gateway.*`（模式、绑定、认证、tailscale）
- `channels.telegram.botToken`、`channels.discord.token`、`channels.signal.*`、`channels.imessage.*`
- 当你在提示中选择加入时的渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）（名称在可能时解析为 ID）。
- `skills.install.nodeManager`
- `wizard.lastRunAt`
- `wizard.lastRunVersion`
- `wizard.lastRunCommit`
- `wizard.lastRunCommand`
- `wizard.lastRunMode`
`openclaw agents add` 写入 `agents.list[]` 和可选的 `bindings`。
WhatsApp 凭证存储在 `~/.openclaw/credentials/whatsapp/<accountId>/` 下。
会话存储在 `~/.openclaw/agents/<agentId>/sessions/` 下。
某些渠道以插件形式提供。当你在新手引导期间选择一个时，向导会在配置之前提示安装它（npm 或本地路径）。
有关详细的分步骤拆解和配置输出，请参见
[CLI 设置参考](/start/wizard-cli-reference)。
有关非交互式示例，请参见 [CLI 自动化](/start/wizard-cli-automation)。
有关更深入的技术参考（包括 RPC 细节），请参见
[向导参考](/reference/wizard)。
## 相关文档
- CLI 命令参考：[`openclaw onboard`](/cli/onboard)
- 新手引导概览：[Onboarding Overview](/start/onboarding-overview)
- macOS 应用新手引导：[新手引导](/start/onboarding)
- 配置参考：[Gateway 网关配置](/gateway/configuration)
- 提供商：[WhatsApp](/channels/whatsapp)、[Telegram](/channels/telegram)、[Discord](/channels/discord)、[Google Chat](/channels/googlechat)、[Signal](/channels/signal)、[iMessage](/channels/imessage)
- Skills：[Skills](/tools/skills)、[Skills 配置](/tools/skills-config)
- 智能体首次运行仪式：[智能体引导](/start/bootstrapping)

1283
docs/zh-CN/tools/plugin.md
View File

File diff suppressed because it is too large Load Diff