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

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-29 21:07:36 +00:00
parent aaac50e81c
commit 0316e2f85d
4 changed files with 669 additions and 510 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

490
docs/zh-CN/channels/discord.md
View File

File diff suppressed because it is too large Load Diff

387
docs/zh-CN/channels/slack.md
View File

@ -1,62 +1,70 @@
---
read_when:
- 设置 Slack 或调试 Slack socket/HTTP 模式
summary: Slack 设置和运行时行为（Socket 模式 + HTTP 请求 URL）
summary: Slack 设置和运行时行为（套接字模式 + HTTP 请求 URL）
title: Slack
x-i18n:
generated_at: "2026-04-29T15:39:31Z"
generated_at: "2026-04-29T21:05:41Z"
model: gpt-5.5
provider: openai
source_hash: e888211dc4729da87c2f2d269dca691aec280b5f09ceb3416f5ea16d7930cdd3
source_hash: f4a991fccb938c133303624c8151bd15094cd4254ee9c9bd71649f1430aaa57c
source_path: channels/slack.md
workflow: 16
---
Production-ready for DMs and channels via Slack app integrations. Default mode is Socket Mode; HTTP Request URLs are also supported.
可通过 Slack 应用集成用于生产环境中的私信和渠道。默认模式是 Socket Mode；也支持 HTTP Request URLs。
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/zh-CN/channels/pairing">
Slack DMs default to pairing mode.
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
Slack 私信默认使用配对模式。
</Card>
<Card title="Slash commands" icon="terminal" href="/zh-CN/tools/slash-commands">
Native command behavior and command catalog.
<Card title="Slash 命令" icon="terminal" href="/zh-CN/tools/slash-commands">
原生命令行为和命令目录。
</Card>
<Card title="Channel troubleshooting" icon="wrench" href="/zh-CN/channels/troubleshooting">
Cross-channel diagnostics and repair playbooks.
<Card title="渠道故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
跨渠道诊断和修复手册。
</Card>
</CardGroup>
## Quick setup
## 快速设置
<Tabs>
<Tab title="Socket Mode (default)">
<Tab title="Socket Mode（默认）">
<Steps>
<Step title="Create a new Slack app">
In Slack app settings press the **[Create New App](https://api.slack.com/apps/new)** button:
<Step title="创建新的 Slack 应用">
在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮：
- choose **from a manifest** and select a workspace for your app
- paste the [example manifest](#manifest-and-scope-checklist) from below and continue to create
- generate an **App-Level Token** (`xapp-...`) with `connections:write`
- install app and copy the **Bot Token** (`xoxb-...`) shown
- 选择 **from a manifest**，并为你的应用选择一个工作区
- 粘贴下面的[示例清单](#manifest-and-scope-checklist)，然后继续创建
- 生成一个具有 `connections:write` 的 **App-Level Token**（`xapp-...`）
- 安装应用，并复制显示的 **Bot Token**（`xoxb-...`）
</Step>
<Step title="Configure OpenClaw">
<Step title="配置 OpenClaw">
```json5
推荐的 SecretRef 设置：
```bash
export SLACK_APP_TOKEN=xapp-...
export SLACK_BOT_TOKEN=xoxb-...
cat > slack.socket.patch.json5 <<'JSON5'
{
channels: {
slack: {
enabled: true,
mode: "socket",
appToken: "xapp-...",
botToken: "xoxb-...",
appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
},
},
}
JSON5
openclaw config patch --file ./slack.socket.patch.json5 --dry-run
openclaw config patch --file ./slack.socket.patch.json5
```
Env fallback (default account only):
环境变量回退（仅默认账户）：
```bash
SLACK_APP_TOKEN=xapp-...
@ -65,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-...
</Step>
<Step title="Start gateway">
<Step title="启动 Gateway 网关">
```bash
openclaw gateway
@ -78,41 +86,49 @@ openclaw gateway
<Tab title="HTTP Request URLs">
<Steps>
<Step title="Create a new Slack app">
In Slack app settings press the **[Create New App](https://api.slack.com/apps/new)** button:
<Step title="创建新的 Slack 应用">
在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮：
- choose **from a manifest** and select a workspace for your app
- paste the [example manifest](#manifest-and-scope-checklist) and update the URLs before create
- save the **Signing Secret** for request verification
- install app and copy the **Bot Token** (`xoxb-...`) shown
- 选择 **from a manifest**，并为你的应用选择一个工作区
- 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL
- 保存用于请求验证的 **Signing Secret**
- 安装应用，并复制显示的 **Bot Token**（`xoxb-...`）
</Step>
<Step title="Configure OpenClaw">
<Step title="配置 OpenClaw">
```json5
推荐的 SecretRef 设置：
```bash
export SLACK_BOT_TOKEN=xoxb-...
export SLACK_SIGNING_SECRET=...
cat > slack.http.patch.json5 <<'JSON5'
{
channels: {
slack: {
enabled: true,
mode: "http",
botToken: "xoxb-...",
signingSecret: "your-signing-secret",
botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
signingSecret: { source: "env", provider: "default", id: "SLACK_SIGNING_SECRET" },
webhookPath: "/slack/events",
},
},
}
JSON5
openclaw config patch --file ./slack.http.patch.json5 --dry-run
openclaw config patch --file ./slack.http.patch.json5
```
<Note>
Use unique webhook paths for multi-account HTTP
为多账户 HTTP 使用唯一的 webhook 路径
Give each account a distinct `webhookPath` (default `/slack/events`) so registrations do not collide.
为每个账户提供不同的 `webhookPath`（默认 `/slack/events`），以免注册发生冲突。
</Note>
</Step>
<Step title="Start gateway">
<Step title="启动 Gateway 网关">
```bash
openclaw gateway
@ -124,9 +140,9 @@ openclaw gateway
</Tab>
</Tabs>
## Socket Mode transport tuning
## Socket Mode 传输调优
OpenClaw sets the Slack SDK client pong timeout to 15 seconds by default for Socket Mode. Override the transport settings only when you need workspace- or host-specific tuning:
OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 秒。仅当你需要针对工作区或主机进行特定调优时，才覆盖传输设置：
```json5
{
@ -143,13 +159,13 @@ OpenClaw sets the Slack SDK client pong timeout to 15 seconds by default for Soc
}
```
Use this only for Socket Mode workspaces that log Slack websocket pong/server-ping timeouts or run on hosts with known event-loop starvation. `clientPingTimeout` is the pong wait after the SDK sends a client ping; `serverPingTimeout` is the wait for Slack server pings. App messages and events remain application state, not transport liveness signals.
仅对记录 Slack websocket pong/服务器 ping 超时，或运行在已知存在事件循环饥饿问题的主机上的 Socket Mode 工作区使用此设置。`clientPingTimeout` 是 SDK 发送客户端 ping 后等待 pong 的时间；`serverPingTimeout` 是等待 Slack 服务器 ping 的时间。应用消息和事件仍然是应用状态，而不是传输活性信号。
## Manifest and scope checklist
## 清单和 scope 检查清单
The base Slack app manifest is the same for Socket Mode and HTTP Request URLs. Only the `settings` block (and the slash command `url`) differs.
基础 Slack 应用清单对于 Socket Mode 和 HTTP Request URLs 相同。只有 `settings` 块（以及 slash 命令的 `url`）不同。
Base manifest (Socket Mode default):
基础清单（Socket Mode 默认）：
```json
{
@ -221,7 +237,7 @@ Base manifest (Socket Mode default):
}
```
For **HTTP Request URLs mode**, replace `settings` with the HTTP variant and add `url` to each slash command. Public URL required:
对于 **HTTP Request URLs 模式**，将 `settings` 替换为 HTTP 变体，并为每个 slash 命令添加 `url`。需要公网 URL：
```json
{
@ -251,22 +267,22 @@ For **HTTP Request URLs mode**, replace `settings` with the HTTP variant and add
}
```
### Additional manifest settings
### 其他清单设置
Surface different features that extend the above defaults.
启用在上述默认设置之外的不同功能。
<AccordionGroup>
<Accordion title="Optional native slash commands">
<Accordion title="可选的原生 slash 命令">
Multiple [native slash commands](#commands-and-slash-behavior) can be used instead of a single configured command with nuance:
可以使用多个[原生 slash 命令](#commands-and-slash-behavior)，而不是单个已配置命令，并提供更细的差异化行为：
- Use `/agentstatus` instead of `/status` because the `/status` command is reserved.
- No more than 25 slash commands can be made available at once.
- 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已保留。
- 一次最多可以提供 25 个 slash 命令。
Replace your existing `features.slash_commands` section with a subset of [available commands](/zh-CN/tools/slash-commands#command-list):
将现有 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)的子集：
<Tabs>
<Tab title="Socket Mode (default)">
<Tab title="Socket Mode（默认）">
```json
"slash_commands": [
@ -383,7 +399,7 @@ Surface different features that extend the above defaults.
</Tab>
<Tab title="HTTP Request URLs">
Use the same `slash_commands` list as Socket Mode above, and add `"url": "https://gateway-host.example.com/slack/events"` to every entry. Example:
使用与上面 Socket Mode 相同的 `slash_commands` 列表，并为每一项添加 `"url": "https://gateway-host.example.com/slack/events"`。示例：
```json
"slash_commands": [
@ -406,14 +422,14 @@ Surface different features that extend the above defaults.
</Tabs>
</Accordion>
<Accordion title="Optional authorship scopes (write operations)">
Add the `chat:write.customize` bot scope if you want outgoing messages to use the active agent identity (custom username and icon) instead of the default Slack app identity.
<Accordion title="可选的作者身份 scope（写入操作）">
如果你希望传出消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。
If you use an emoji icon, Slack expects `:emoji_name:` syntax.
如果你使用 emoji 图标，Slack 需要 `:emoji_name:` 语法。
</Accordion>
<Accordion title="Optional user-token scopes (read operations)">
If you configure `channels.slack.userToken`, typical read scopes are:
<Accordion title="可选的用户 token scope（读取操作）">
如果你配置了 `channels.slack.userToken`，典型的读取 scope 包括：
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
@ -421,41 +437,41 @@ Surface different features that extend the above defaults.
- `reactions:read`
- `pins:read`
- `emoji:read`
- `search:read` (if you depend on Slack search reads)
- `search:read`（如果你依赖 Slack 搜索读取）
</Accordion>
</AccordionGroup>
## Token model
## Token 模型
- `botToken` + `appToken` are required for Socket Mode.
- HTTP mode requires `botToken` + `signingSecret`.
- `botToken`, `appToken`, `signingSecret`, and `userToken` accept plaintext
strings or SecretRef objects.
- Config tokens override env fallback.
- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env fallback applies only to the default account.
- `userToken` (`xoxp-...`) is config-only (no env fallback) and defaults to read-only behavior (`userTokenReadOnly: true`).
- Socket Mode 需要 `botToken` + `appToken`。
- HTTP 模式需要 `botToken` + `signingSecret`。
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文
字符串或 SecretRef 对象。
- 配置令牌会覆盖环境变量回退。
- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账号。
- `userToken`（`xoxp-...`）仅能通过配置提供（无环境变量回退），并默认采用只读行为（`userTokenReadOnly: true`）。
Status snapshot behavior:
Status 快照行为：
- Slack 账号检查会跟踪每个凭据的 `*Source` 和 `*Status`
- Slack 账号检查会按凭证跟踪 `*Source` 和 `*Status`
字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。
- Status 为 `available`、`configured_unavailable` 或 `missing`。
- `configured_unavailable` 表示账号通过 SecretRef
或其他非内联密钥来源配置，但当前命令/运行时路径
或其他非内联密钥来源进行了配置，但当前命令/运行时路径
无法解析实际值。
- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，
- 在 HTTP 模式下会包含 `signingSecretStatus`；在 Socket Mode 下，
必需的组合是 `botTokenStatus` + `appTokenStatus`。
<Tip>
对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍优先使用 bot 令牌；只有当 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。
对于操作/目录读取，配置了用户令牌时可以优先使用用户令牌。对于写入，仍优先使用机器人令牌；仅当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许用户令牌写入。
</Tip>
## 操作和门控
Slack 操作由 `channels.slack.actions.*` 控制。
当前 Slack 工具中的可用操作组：
当前 Slack 工具中可用的操作组：
| 组 | 默认值 |
| ---------- | ------- |
@ -465,7 +481,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。
| memberInfo | 已启用 |
| emojiList | 已启用 |
当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并为图片返回图片预览，或为其他文件类型返回本地文件元数据。
当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并对图片返回图片预览，或对其他文件类型返回本地文件元数据。
## 访问控制和路由
@ -483,16 +499,16 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- `dm.enabled`（默认 true）
- `channels.slack.allowFrom`
- `dm.allowFrom`（旧版）
- `dm.groupEnabled`（群组私信默认 false）
- `dm.groupEnabled`（群组私信默认为 false）
- `dm.groupChannels`（可选 MPIM 允许列表）
多账号优先级：
- `channels.slack.accounts.default.allowFrom` 仅适用于 `default` 账号。
- 命名账号在自身 `allowFrom` 未设置时继承 `channels.slack.allowFrom`。
- 命名账号不会继承 `channels.slack.accounts.default.allowFrom`。
- 具名账号在自身 `allowFrom` 未设置时继承 `channels.slack.allowFrom`。
- 具名账号不会继承 `channels.slack.accounts.default.allowFrom`。
旧版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的情况下，将它们迁移到 `dmPolicy` 和 `allowFrom`。
旧版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的情况下，尽可能将它们迁移到 `dmPolicy` 和 `allowFrom`。
私信中的配对使用 `openclaw pairing approve slack <code>`。
@ -505,28 +521,28 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- `allowlist`
- `disabled`
渠道允许列表位于 `channels.slack.channels` 下，并应使用稳定的渠道 ID。
渠道允许列表位于 `channels.slack.channels` 下，应使用稳定的渠道 ID。
运行时注意事项：如果 `channels.slack` 完全缺失（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使已设置 `channels.defaults.groupPolicy`）。
运行时注意事项：如果完全缺少 `channels.slack`（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录警告（即使设置了 `channels.defaults.groupPolicy`）。
名称/ID 解析：
- 当令牌访问允许时，渠道允许列表条目和私信允许列表条目会在启动时解析
- 未解析的渠道名称条目会按配置保留，但默认会在路由中忽略
- 入站授权和渠道路由默认以 ID 优先；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true`
- 入站授权和渠道路由默认优先使用 ID；直接用户名/短名匹配要求设置 `channels.slack.dangerouslyAllowNameMatching: true`
</Tab>
<Tab title="提及和渠道用户">
渠道消息默认受提及门控。
渠道消息默认受提及门控限制。
提及来源：
- 显式应用提及（`<@botId>`）
- 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`）
- 隐式回复 bot 线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用）
- 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`）
- 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用）
按渠道控制（`channels.slack.channels.<id>`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 使用）：
按渠道控制（`channels.slack.channels.<id>`；名称仅通过启动解析或 `dangerouslyAllowNameMatching`）：
- `requireMention`
- `users`（允许列表）
@ -545,10 +561,10 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。
- 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。
- 渠道会话：`agent:<agentId>:slack:channel:<channelId>`。
- 线程回复可在适用时创建线程会话后缀（`:thread:<threadTs>`）。
- `channels.slack.thread.historyScope` 默认值为 `thread`；`thread.inheritParent` 默认值为 `false`。
- 线程回复在适用时可以创建线程会话后缀（`:thread:<threadTs>`）。
- `channels.slack.thread.historyScope` 默认为 `thread`；`thread.inheritParent` 默认为 `false`。
- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时获取多少条现有线程消息（默认 `20`；设置为 `0` 可禁用）。
- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，会抑制隐式线程提及，因此 bot 只会响应线程内显式 `@bot` 提及，即使 bot 已经参与该线程。如果不这样设置，bot 参与过的线程中的回复会绕过 `requireMention` 门控。
- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，会抑制隐式线程提及，使机器人在线程内只响应显式 `@bot` 提及，即使机器人已经参与了该线程。否则，在机器人参与过的线程中，回复会绕过 `requireMention` 门控。
回复线程控制：
@ -562,10 +578,10 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- `[[reply_to:<id>]]`
<Note>
`replyToMode="off"` 会禁用 Slack 中的**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这不同于 Telegram，后者在 `"off"` 模式下仍会遵循显式标签。Slack 线程会从渠道中隐藏消息，而 Telegram 回复仍以内联方式可见。
`replyToMode="off"` 会在 Slack 中禁用**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这不同于 Telegram，后者在 `"off"` 模式下仍会遵循显式标签。Slack 线程会把消息从渠道中隐藏，而 Telegram 回复会继续以内联方式可见。
</Note>
## 确认响应表情
## 确认回应表情
`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。
@ -578,8 +594,8 @@ Slack 操作由 `channels.slack.actions.*` 控制。
注意事项：
- Slack 需要短代码（例如 `"eyes"`）。
- 使用 `""` 可为 Slack 账号或全局禁用该响应。
- Slack 期望短代码（例如 `"eyes"`）。
- 使用 `""` 可为 Slack 账号或全局禁用该回应。
## 文本流式传输
@ -589,18 +605,18 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- `partial`（默认）：用最新的部分输出替换预览文本。
- `block`：追加分块预览更新。
- `progress`：生成期间显示进度状态文本，然后发送最终文本。
- `streaming.preview.toolProgress`：草稿预览处于活动状态时，将工具/进度更新路由到同一条已编辑的预览消息中（默认：`true`）。设置为 `false` 可保留单独的工具/进度消息。
- `streaming.preview.toolProgress`：当草稿预览处于活动状态时，将工具/进度更新路由到同一条经过编辑的预览消息中（默认：`true`）。设置为 `false` 可保留单独的工具/进度消息。
当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。
- 必须有可用的回复线程，原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍遵循 `replyToMode`。
- 必须存在回复线程，原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍遵循 `replyToMode`。
- 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。
- 顶层 Slack 私信默认保持在线程外，因此不会显示线程样式预览；如果想在那里看到可见进度，请使用线程回复或 `typingReaction`。
- 顶层 Slack 私信默认不进入线程，因此不会显示线程样式预览；如果你希望在那里显示可见进度，请使用线程回复或 `typingReaction`。
- 媒体和非文本载荷会回退到普通投递。
- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息仅在能就地编辑预览时才会刷新。
- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息仅在可以就地编辑预览时刷新。
- 如果流式传输在回复中途失败，OpenClaw 会对剩余载荷回退到普通投递。
使用草稿预览，而不是 Slack 原生文本流式传输：
使用草稿预览而不是 Slack 原生文本流式传输：
```json5
{
@ -621,9 +637,9 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。
- 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。
## 输入响应回退
## 输入状态回应回退
`typingReaction` 会在 OpenClaw 处理回复时向入站 Slack 消息添加临时响应，并在运行完成时将其移除。这在线程回复之外最有用，因为线程回复使用默认的 "is typing..." 状态指示器。
`typingReaction` 会在 OpenClaw 处理回复时向入站 Slack 消息添加一个临时回应，并在运行结束时移除它。这在线程回复之外最有用，因为线程回复会使用默认的“正在输入...”状态指示器。
解析顺序：
@ -632,18 +648,18 @@ Slack 操作由 `channels.slack.actions.*` 控制。
注意事项：
- Slack 需要短代码（例如 `"hourglass_flowing_sand"`）。
- 该响应会尽力执行，并会在回复或失败路径完成后自动尝试清理。
- Slack 期望短代码（例如 `"hourglass_flowing_sand"`）。
- 该回应为尽力而为，并会在回复或失败路径完成后自动尝试清理。
## 媒体、分块和投递
<AccordionGroup>
<Accordion title="入站附件">
Slack 文件附件会从 Slack 托管的私有 URL 下载（使用令牌认证请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以使用 `download-file` 获取原始文件。
Slack 文件附件会从 Slack 托管的私有 URL 下载（经令牌认证的请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，以便智能体可以用 `download-file` 获取原始文件。
下载使用有界空闲超时和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息，并回退到文件占位符。
运行时入站大小上限默认为 `20MB`，除非由 `channels.slack.mediaMaxMb` 覆盖。
运行时入站大小上限默认为 `20MB`，除非通过 `channels.slack.mediaMaxMb` 覆盖。
</Accordion>
@ -651,7 +667,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- 文本分块使用 `channels.slack.textChunkLimit`（默认 4000）
- `channels.slack.chunkMode="newline"` 启用段落优先拆分
- 文件发送使用 Slack 上传 API，并可包含线程回复（`thread_ts`）
- 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则，渠道发送使用媒体管线中的 MIME 类型默认值
- 配置时，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则，渠道发送使用媒体流水线中的 MIME 类型默认值
</Accordion>
@ -661,7 +677,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。
- `user:<id>` 用于私信
- `channel:<id>` 用于渠道
发送到用户目标时，Slack 私信会通过 Slack conversation API 打开。
发送到用户目标时，Slack 私信会通过 Slack 会话 API 打开。
</Accordion>
</AccordionGroup>
@ -679,7 +695,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。
/openclaw /help
```
原生命令需要在你的 Slack 应用中配置[额外清单设置](#additional-manifest-settings)，并改为通过 `channels.slack.commands.native: true` 或全局配置中的 `commands.native: true` 启用。
原生命令要求你的 Slack 应用中有[额外清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 启用，或在全局配置中通过 `commands.native: true` 启用。
- Slack 的原生命令自动模式为**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。
@ -687,7 +703,7 @@ Slack 操作由 `channels.slack.actions.*` 控制。
/help
```
原生参数菜单使用自适应渲染策略，在分派所选选项值之前显示确认模态框：
原生参数菜单使用自适应渲染策略，会在分派所选选项值之前显示确认模态框：
- 最多 5 个选项：按钮块
- 6-100 个选项：静态选择菜单
@ -698,11 +714,11 @@ Slack 操作由 `channels.slack.actions.*` 控制。
/think
```
斜杠会话使用类似 `agent:<agentId>:slack:slash:<userId>` 的隔离键，并仍使用 `CommandTargetSessionKey` 将命令执行路由到目标会话。
斜杠会话使用类似 `agent:<agentId>:slack:slash:<userId>` 的隔离键，并仍会使用 `CommandTargetSessionKey` 将命令执行路由到目标会话。
## 交互式回复
Slack 可以渲染智能体编写的交互式回复控件，但此功能默认禁用。
Slack 可以渲染智能体创作的交互式回复控件，但此功能默认禁用。
全局启用：
@ -718,7 +734,7 @@ Slack 可以渲染智能体编写的交互式回复控件，但此功能默认
}
```
或仅为一个 Slack 账号启用：
或仅为一个 Slack 账号启用它：
```json5
{
@ -736,41 +752,42 @@ Slack 可以渲染智能体编写的交互式回复控件，但此功能默认
}
```
启用后，智能体可以发出仅 Slack 使用的回复指令：
启用后，智能体可以发出仅适用于 Slack 的回复指令：
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
这些指令会编译成 Slack Block Kit，并通过现有的 Slack 交互事件路径路由点击或选择。
这些指令会编译为 Slack Block Kit，并通过现有 Slack 交互事件路径将点击或选择路由回来。
注意：
- 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令转换成自己的按钮系统。
- 交互式回调值是 OpenClaw 生成的不透明令牌，而不是智能体编写的原始值。
- 如果生成的交互式块会超出 Slack Block Kit 限制，OpenClaw 会回退到原始文本回复，而不是发送无效的 blocks 载荷。
- 这是 Slack 专属 UI。其他渠道不会把 Slack Block Kit 指令转换为自己的按钮系统。
- 交互回调值是 OpenClaw 生成的不透明令牌，而不是智能体编写的原始值。
- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退到原始文本回复，而不是发送无效的 blocks 载荷。
## Slack 中的 exec 审批
## Slack 中的执行审批
Slack 可以作为带有交互式按钮和交互的原生审批客户端，而不是回退到 Web UI 或终端。
Slack 可以作为带有交互按钮和交互事件的原生审批客户端，而不是回退到 Web UI 或终端。
- Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。
- 当请求已进入 Slack 且审批 id 类型为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面完成。
- 审批者授权仍会强制执行：只有被识别为审批者的用户才能通过 Slack 批准或拒绝请求。
- 执行审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。
- 当请求已经到达 Slack 且审批 ID 类型为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面解析。
- 仍会强制执行审批人授权：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。
这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用 `interactivity` 时，审批提示会直接在对话中渲染为 Block Kit 按钮。
当这些按钮存在时，它们是主要审批用户体验；OpenClaw 只有在工具结果表明聊天审批不可用或手动审批是唯一路径时，才应包含手动 `/approve` 命令。
当这些按钮存在时，它们就是主要审批 UX；OpenClaw
仅应在工具结果表示聊天审批不可用或手动审批是唯一路径时，才包含手动 `/approve` 命令。
配置路径：
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers`（可选；可行时回退到 `commands.ownerAllowFrom`）
- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认值：`dm`）
- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`）
- `agentFilter`、`sessionFilter`
当 `enabled` 未设置或为 `"auto"`，且至少能解析出一个审批者时，Slack 会自动启用原生 exec 审批。设置 `enabled: false` 可明确禁用 Slack 作为原生审批客户端。
设置 `enabled: true` 可在审批者可解析时强制开启原生审批。
当 `enabled` 未设置或为 `"auto"`，且至少解析出一个审批人时，Slack 会自动启用原生执行审批。设置 `enabled: false` 可明确禁用 Slack 作为原生审批客户端。
设置 `enabled: true` 可在审批人解析成功时强制启用原生审批。
没有显式 Slack exec 审批配置时的默认行为：
没有显式 Slack 执行审批配置时的默认行为：
```json5
{
@ -780,7 +797,7 @@ Slack 可以作为带有交互式按钮和交互的原生审批客户端，而
}
```
只有在你想覆盖审批者、添加过滤器，或选择启用来源聊天投递时，才需要显式 Slack 原生配置：
只有在你想覆盖审批人、添加筛选器或选择启用来源聊天投递时，才需要显式 Slack 原生配置：
```json5
{
@ -796,22 +813,24 @@ Slack 可以作为带有交互式按钮和交互的原生审批客户端，而
}
```
共享的 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须路由到其他聊天或显式的带外目标时才使用它。共享的 `approvals.plugin` 转发也是独立的；当这些请求已进入 Slack 时，Slack 原生按钮仍可完成插件审批。
共享 `approvals.exec` 转发是独立的。仅当执行审批提示还必须
路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是
独立的；当这些请求已经到达 Slack 时，Slack 原生按钮仍可解析插件审批。
同一聊天中的 `/approve` 也适用于已支持命令的 Slack 渠道和私信。完整的审批转发模型请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)。
同聊天 `/approve` 也适用于已经支持命令的 Slack 渠道和私信。完整审批转发模型见[执行审批](/zh-CN/tools/exec-approvals)。
## 事件与运维行为
## 事件和运维行为
- 消息编辑/删除会映射为系统事件。
- 线程广播（“同时发送到渠道”的线程回复）会作为普通用户消息处理。
- 添加/移除表情回应事件会映射为系统事件。
- 成员加入/离开、渠道创建/重命名，以及图钉添加/移除事件会映射为系统事件。
- 启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。
- 渠道主题/用途元数据会被视为不可信上下文，并可注入到路由上下文中。
- 适用时，线程发起消息和初始线程历史上下文种子会按配置的发送者允许列表过滤。
- Block 操作和模态框交互会发出带有丰富载荷字段的结构化 `Slack interaction: ...` 系统事件：
- block 操作：所选值、标签、选择器值，以及 `workflow_*` 元数据
- 模态框 `view_submission` 和 `view_closed` 事件，包含路由后的渠道元数据和表单输入
- 线程广播（“同时发送到渠道”的线程回复）会按普通用户消息处理。
- 表情回应添加/移除事件会映射为系统事件。
- 成员加入/离开、渠道创建/重命名，以及置顶添加/移除事件会映射为系统事件。
- 启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键名。
- 渠道主题/用途元数据会被视为不可信上下文，并可注入路由上下文。
- 适用时，线程发起消息和初始线程历史上下文种子会按配置的发送者允许列表筛选。
- 块操作和模态交互会发出带有丰富载荷字段的结构化 `Slack interaction: ...` 系统事件：
- 块操作：所选值、标签、选择器值和 `workflow_*` 元数据
- 模态 `view_submission` 和 `view_closed` 事件，带有路由后的渠道元数据和表单输入
## 配置参考
@ -819,9 +838,9 @@ Slack 可以作为带有交互式按钮和交互的原生审批客户端，而
<Accordion title="高信号 Slack 字段">
- 模式/认证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*`
- 模式/凭证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*`
- 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels`
- 兼容性开关：`dangerouslyAllowNameMatching`（应急选项；除非需要，否则保持关闭）
- 兼容性开关：`dangerouslyAllowNameMatching`（紧急开关；除非需要，否则保持关闭）
- 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention`
- 线程/历史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
- 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress`
@ -838,7 +857,7 @@ Slack 可以作为带有交互式按钮和交互的原生审批客户端，而
- `groupPolicy`
- 渠道允许列表（`channels.slack.channels`）
- `requireMention`
- 每个渠道的 `users` 允许列表
- 每渠道 `users` 允许列表
有用的命令：
@ -856,7 +875,9 @@ openclaw doctor
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy`（或旧版 `channels.slack.dm.policy`）
- 配对审批 / 允许列表条目
- Slack Assistant 私信事件：提到 `drop message_changed` 的详细日志通常表示 Slack 发送了一个编辑过的 Assistant 线程事件，但消息元数据中没有可恢复的人类发送者
- Slack Assistant 私信事件：提到 `drop message_changed` 的详细日志
通常表示 Slack 发送了一个已编辑的 Assistant 线程事件，但消息元数据中
没有可恢复的人类发送者
```bash
openclaw pairing list slack
@ -865,55 +886,59 @@ openclaw pairing list slack
</Accordion>
<Accordion title="Socket 模式未连接">
在 Slack 应用设置中验证 bot + app 令牌以及 Socket Mode 启用状态。
验证 Slack 应用设置中的机器人 + 应用令牌以及 Socket Mode 启用状态。
如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或
`appTokenStatus: "configured_unavailable"`，说明 Slack 账号已配置，但当前运行时无法解析由 SecretRef 支持的值。
`appTokenStatus: "configured_unavailable"`，则表示 Slack 账号已
配置，但当前运行时无法解析由 SecretRef 支持的
值。
</Accordion>
<Accordion title="HTTP 模式未接收事件">
<Accordion title="HTTP 模式未收到事件">
验证：
- 签名密钥
- webhook 路径
- Slack Request URL（Events + Interactivity + Slash Commands）
- 每个 HTTP 账号唯一的 `webhookPath`
- Slack Request URLs（Events + Interactivity + Slash Commands）
- 每个 HTTP 账号使用唯一的 `webhookPath`
如果账号快照中出现 `signingSecretStatus: "configured_unavailable"`，说明 HTTP 账号已配置，但当前运行时无法解析由 SecretRef 支持的签名密钥。
如果账号快照中出现 `signingSecretStatus: "configured_unavailable"`，
则表示 HTTP 账号已配置，但当前运行时无法
解析由 SecretRef 支持的签名密钥。
</Accordion>
<Accordion title="原生/slash 命令未触发">
确认你原本想使用的是：
<Accordion title="原生命令/斜杠命令未触发">
验证你的预期是：
- 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册了匹配的 slash 命令
- 或单一 slash 命令模式（`channels.slack.slashCommand.enabled: true`）
- 原生命令模式（`channels.slack.commands.native: true`），并在 Slack 中注册了匹配的斜杠命令
- 或单斜杠命令模式（`channels.slack.slashCommand.enabled: true`）
另请检查 `commands.useAccessGroups` 以及渠道/用户允许列表。
同时检查 `commands.useAccessGroups` 和渠道/用户允许列表。
</Accordion>
</AccordionGroup>
## 附件视觉参考
当 Slack 文件下载成功且大小限制允许时，Slack 可以将下载的媒体附加到智能体回合。图像文件可以通过媒体理解路径传递，或直接传递给支持视觉的回复模型；其他文件会保留为可下载文件上下文，而不是作为图像输入处理。
当 Slack 文件下载成功且大小限制允许时，Slack 可以将下载的媒体附加到智能体轮次。图像文件可以通过媒体理解路径传递，或直接传递给支持视觉的回复模型；其他文件会保留为可下载文件上下文，而不是被当作图像输入处理。
### 支持的媒体类型
| 媒体类型 | 来源 | 当前行为 | 备注 |
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| JPEG / PNG / GIF / WebP 图像 | Slack 文件 URL | 下载并附加到该回合，以便支持视觉的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） |
| PDF 文件 | Slack 文件 URL | 下载并作为文件上下文暴露给 `download-file` 或 `pdf` 等工具 | Slack 入站不会自动将 PDF 转换为图像视觉输入 |
| 其他文件 | Slack 文件 URL | 可行时下载并作为文件上下文暴露 | 二进制文件不会作为图像输入处理 |
| 线程回复 | 线程发起消息文件 | 当回复没有直接媒体时，根消息文件可作为上下文水合 | 仅包含文件的发起消息使用附件占位符 |
| 多图像消息 | 多个 Slack 文件 | 每个文件都会独立评估 | Slack 处理限制为每条消息最多八个文件 |
| JPEG / PNG / GIF / WebP 图像 | Slack 文件 URL | 下载并附加到轮次中，以便支持视觉的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） |
| PDF 文件 | Slack 文件 URL | 下载并公开为文件上下文，供 `download-file` 或 `pdf` 等工具使用 | Slack 入站不会自动把 PDF 转换为图像视觉输入 |
| 其他文件 | Slack 文件 URL | 可行时下载并公开为文件上下文 | 二进制文件不会被当作图像输入 |
| 线程回复 | 线程发起消息文件 | 当回复没有直接媒体时，根消息文件可作为上下文补充 | 仅文件发起消息会使用附件占位符 |
| 多图像消息 | 多个 Slack 文件 | 每个文件会独立评估 | Slack 处理每条消息最多八个文件 |
### 入站流水线
### 入站管线
当带有文件附件的 Slack 消息到达时：
1. OpenClaw 使用 bot 令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。
1. OpenClaw 使用机器人令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。
2. 下载成功后，文件会写入媒体存储。
3. 下载的媒体路径和内容类型会添加到入站上下文。
4. 支持图像的模型/工具路径可以使用该上下文中的图像附件。
@ -921,17 +946,17 @@ openclaw pairing list slack
### 线程根附件继承
当消息进入线程（有 `thread_ts` 父级）时：
当消息到达线程中（有 `thread_ts` 父级）时：
- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以将根文件水合为线程发起消息上下文。
- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以把根文件补充为线程发起消息上下文。
- 直接回复附件优先于根消息附件。
- 只有文件且没有文本的根消息会用附件占位符表示，因此回退仍可包含其文件。
- 只有文件而没有文本的根消息会用附件占位符表示，以便回退仍可包含其文件。
### 多附件处理
当单条 Slack 消息包含多个文件附件时：
- 每个附件都会通过媒体流水线独立处理。
- 每个附件都会通过媒体管线独立处理。
- 下载的媒体引用会聚合到消息上下文中。
- 处理顺序遵循事件载荷中的 Slack 文件顺序。
- 一个附件下载失败不会阻塞其他附件。
@ -939,46 +964,46 @@ openclaw pairing list slack
### 大小、下载和模型限制
- **大小上限**：默认每个文件 20 MB。可通过 `channels.slack.mediaMaxMb` 配置。
- **下载失败**：Slack 无法提供的文件、过期 URL、不可访问文件、超大文件，以及 Slack 认证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。
- **视觉模型**：图像分析会在活动回复模型支持视觉时使用它，否则使用在 `agents.defaults.imageModel` 配置的图像模型。
- **下载失败**：Slack 无法提供的文件、过期 URL、不可访问文件、超大文件，以及 Slack 凭证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。
- **视觉模型**：当活动回复模型支持视觉时，图像分析使用该模型；否则使用 `agents.defaults.imageModel` 配置的图像模型。
### 已知限制
| 场景 | 当前行为 | 解决方法 |
| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Slack 文件 URL 已过期 | 跳过文件；不显示错误 | 在 Slack 中重新上传文件 |
| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用具备视觉能力的回复模型 |
| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，请增大 `channels.slack.mediaMaxMb` |
| 转发/共享的附件 | 文本以及 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新共享 |
| 已过期的 Slack 文件 URL | 跳过文件；不显示错误 | 在 Slack 中重新上传文件 |
| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用支持视觉的回复模型 |
| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，增大 `channels.slack.mediaMaxMb` |
| 转发/共享的附件 | 文本和 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新共享 |
| PDF 附件 | 存储为文件/媒体上下文，不会自动通过图像视觉处理 | 使用 `download-file` 获取文件元数据，或使用 `pdf` 工具进行 PDF 分析 |
### 相关文档
- [媒体理解流水线](/zh-CN/nodes/media-understanding)
- [媒体理解管线](/zh-CN/nodes/media-understanding)
- [PDF 工具](/zh-CN/tools/pdf)
- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 附件视觉能力启用
- 回归测试: [#51353](https://github.com/openclaw/openclaw/issues/51353)
- 实时验证: [#51354](https://github.com/openclaw/openclaw/issues/51354)
- 史诗任务：[#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 附件视觉启用
- 回归测试：[#51353](https://github.com/openclaw/openclaw/issues/51353)
- 实时验证：[#51354](https://github.com/openclaw/openclaw/issues/51354)
## 相关
<CardGroup cols={2}>
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
<Card title="Pairing" icon="link" href="/zh-CN/channels/pairing">
将 Slack 用户与 Gateway 网关配对。
</Card>
<Card title="群组" icon="users" href="/zh-CN/channels/groups">
<Card title="Groups" icon="users" href="/zh-CN/channels/groups">
渠道和群组私信行为。
</Card>
<Card title="渠道路由" icon="route" href="/zh-CN/channels/channel-routing">
<Card title="Channel routing" icon="route" href="/zh-CN/channels/channel-routing">
将入站消息路由到智能体。
</Card>
<Card title="安全" icon="shield" href="/zh-CN/gateway/security">
<Card title="Security" icon="shield" href="/zh-CN/gateway/security">
威胁模型和加固。
</Card>
<Card title="配置" icon="sliders" href="/zh-CN/gateway/configuration">
<Card title="Configuration" icon="sliders" href="/zh-CN/gateway/configuration">
配置布局和优先级。
</Card>
<Card title="斜杠命令" icon="terminal" href="/zh-CN/tools/slash-commands">
<Card title="Slash commands" icon="terminal" href="/zh-CN/tools/slash-commands">
命令目录和行为。
</Card>
</CardGroup>

181
docs/zh-CN/cli/config.md
View File

@ -2,23 +2,23 @@
read_when:
- 你想以非交互方式读取或编辑配置
sidebarTitle: Config
summary: 用于 `openclaw config` 的 CLI 参考（get/set/unset/file/schema/validate）
summary: 用于 `openclaw config` 的 CLI 参考（get/set/patch/unset/file/schema/validate）
title: 配置
x-i18n:
generated_at: "2026-04-28T11:47:13Z"
generated_at: "2026-04-29T21:05:38Z"
model: gpt-5.5
provider: openai
source_hash: 3e90f979a102a6c54f8458f8a2c7f36bec5b1e82ea4bdd30e9c3a4b1d903cf11
source_hash: f1f55c4b932d469cb9112d9f55b66f0ff88dbe066250651df7a0a753060a223d
source_path: cli/config.md
workflow: 16
---
`openclaw.json` 中用于非交互式编辑的配置助手：按路径获取/设置/取消设置/输出文件/输出 schema/验证值，并打印当前生效的配置文件。不带子命令运行时会打开配置向导（等同于 `openclaw configure`）。
配置辅助工具用于在 `openclaw.json` 中进行非交互式编辑：按路径 get/set/patch/unset/file/schema/validate 值，并打印当前活动的配置文件。不带子命令运行会打开配置向导（等同于 `openclaw configure`）。
## 根选项
<ParamField path="--section <section>" type="string">
不带子命令运行 `openclaw config` 时，可重复使用的引导式设置分区过滤器。
当你不带子命令运行 `openclaw config` 时，可重复使用的引导式设置分区过滤器。
</ParamField>
支持的引导式分区：`workspace`、`model`、`web`、`gateway`、`daemon`、`channels`、`plugins`、`skills`、`health`。
@ -38,6 +38,7 @@ openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
@ -49,17 +50,17 @@ openclaw config validate --json
将为 `openclaw.json` 生成的 JSON schema 以 JSON 形式打印到 stdout。
<AccordionGroup>
<Accordion title="包含内容">
- 当前根配置 schema，以及用于编辑器工具的根 `$schema` 字符串字段。
<Accordion title="What it includes">
- 当前根配置 schema，加上用于编辑器工具的根 `$schema` 字符串字段。
- Control UI 使用的字段 `title` 和 `description` 文档元数据。
- 嵌套对象、通配符（`*`）和数组项（`[]`）节点在存在匹配字段文档时，会继承相同的 `title` / `description` 元数据。
- `anyOf` / `oneOf` / `allOf` 分支在存在匹配字段文档时，也会继承相同的文档元数据。
- 运行时清单可加载时，尽力提供实时插件 + 渠道 schema 元数据。
- 当存在匹配的字段文档时，嵌套对象、通配符（`*`）和数组项（`[]`）节点会继承相同的 `title` / `description` 元数据。
- 当存在匹配的字段文档时，`anyOf` / `oneOf` / `allOf` 分支也会继承相同的文档元数据。
- 当可以加载运行时 manifest 时，尽力提供实时插件 + 渠道 schema 元数据。
- 即使当前配置无效，也会提供干净的回退 schema。
</Accordion>
<Accordion title="相关运行时 RPC">
`config.schema.lookup` 会返回一个规范化的配置路径，包含浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据，以及直接子项摘要。可用于 Control UI 或自定义客户端中的路径级下钻。
<Accordion title="Related runtime RPC">
`config.schema.lookup` 返回一个规范化配置路径，包含一个浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据，以及直接子项摘要。可在 Control UI 或自定义客户端中用于按路径深入查看。
</Accordion>
</AccordionGroup>
@ -67,7 +68,7 @@ openclaw config validate --json
openclaw config schema
```
如果要用其他工具检查或验证它，可以将其通过管道写入文件：
当你想用其他工具检查或验证它时，可以通过管道写入文件：
```bash
openclaw config schema > openclaw.schema.json
@ -75,7 +76,7 @@ openclaw config schema > openclaw.schema.json
### 路径
路径使用点号或方括号表示法：
路径使用点号或括号表示法：
```bash
openclaw config get agents.defaults.workspace
@ -91,7 +92,7 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
## 值
值会在可能时按 JSON5 解析；否则按字符串处理。使用 `--strict-json` 要求必须按 JSON5 解析。`--json` 仍作为旧版别名受支持。
值会尽可能按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 要求必须按 JSON5 解析。`--json` 仍作为旧版别名受支持。
```bash
openclaw config set agents.defaults.heartbeat.every "0m"
@ -99,32 +100,32 @@ openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
```
`config get <path> --json` 会以 JSON 打印原始值，而不是终端格式化文本。
`config get <path> --json` 会将原始值以 JSON 打印，而不是打印终端格式化文本。
<Note>
对象赋值默认会替换目标路径。受保护的 map/list 路径通常保存用户添加的条目，例如 `agents.defaults.models`、`models.providers`、`models.providers.<id>.models`、`plugins.entries` 和 `auth.profiles`，除非传入 `--replace`，否则会拒绝移除现有条目的替换操作。
默认情况下，对象赋值会替换目标路径。常用于保存用户新增条目的受保护 map/list 路径，例如 `agents.defaults.models`、`models.providers`、`models.providers.<id>.models`、`plugins.entries` 和 `auth.profiles`，会拒绝可能移除现有条目的替换，除非你传入 `--replace`。
</Note>
向这些 map 添加条目时使用 `--merge`：
向这些映射添加条目时使用 `--merge`：
```bash
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge
```
仅当你确实希望提供的值成为完整目标值时，才使用 `--replace`。
只有当你明确希望提供的值成为完整目标值时，才使用 `--replace`。
## `config set` 模式
`openclaw config set` 支持四种赋值样式：
`openclaw config set` 支持四种赋值方式：
<Tabs>
<Tab title="值模式">
<Tab title="Value mode">
```bash
openclaw config set <path> <value>
```
</Tab>
<Tab title="SecretRef 构建器模式">
<Tab title="SecretRef builder mode">
```bash
openclaw config set channels.discord.token \
--ref-provider default \
@ -132,8 +133,8 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll
--ref-id DISCORD_BOT_TOKEN
```
</Tab>
<Tab title="提供商构建器模式">
提供商构建器模式仅针对 `secrets.providers.<alias>` 路径：
<Tab title="Provider builder mode">
提供商构建器模式仅面向 `secrets.providers.<alias>` 路径：
```bash
openclaw config set secrets.providers.vault \
@ -145,7 +146,7 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll
```
</Tab>
<Tab title="批处理模式">
<Tab title="Batch mode">
```bash
openclaw config set --batch-json '[
{
@ -167,12 +168,68 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll
</Tabs>
<Warning>
SecretRef 赋值会在不受支持的运行时可变 surface 上被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook 令牌，以及 WhatsApp 凭证 JSON）。参阅 [SecretRef 凭证 Surface](/zh-CN/reference/secretref-credential-surface)。
SecretRef 赋值会在不支持运行时可变的表面上被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook 令牌，以及 WhatsApp 凭证 JSON）。参见 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)。
</Warning>
批处理解析始终使用批处理负载（`--batch-json`/`--batch-file`）作为事实来源。`--strict-json` / `--json` 不会改变批处理解析行为。
批量解析始终使用批量载荷（`--batch-json`/`--batch-file`）作为事实来源。`--strict-json` / `--json` 不会改变批量解析行为。
JSON 路径/值模式仍同时支持 SecretRefs 和提供商：
## `config patch`
当你想粘贴或通过管道传入一个配置形状的补丁，而不是运行许多基于路径的 `config set` 命令时，使用 `config patch`。输入是一个 JSON5 对象。对象会递归合并，数组和标量值会替换目标值，`null` 会删除目标路径。
```bash
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config patch --file ./openclaw.patch.json5
```
你也可以通过 stdin 传入补丁，这对远程设置脚本很有用：
```bash
ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5
```
示例补丁：
```json5
{
channels: {
slack: {
enabled: true,
mode: "socket",
botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
groupPolicy: "open",
requireMention: false,
},
discord: {
enabled: true,
token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
dmPolicy: "disabled",
dm: { enabled: false },
groupPolicy: "allowlist",
},
},
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" },
models: {
"openai/gpt-5.5": { params: { fastMode: true } },
},
},
},
}
```
当某个对象或数组必须精确变为提供的值，而不是被递归补丁处理时，使用 `--replace-path <path>`：
```bash
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'
```
`--dry-run` 会在不写入的情况下运行 schema 和 SecretRef 可解析性检查。默认情况下，dry-run 期间会跳过基于 exec 的 SecretRefs；当你明确希望 dry-run 执行提供商命令时，添加 `--allow-exec`。
JSON 路径/值模式仍然同时支持 SecretRefs 和提供商：
```bash
openclaw config set channels.discord.token \
@ -189,23 +246,23 @@ openclaw config set secrets.providers.vaultfile \
提供商构建器目标必须使用 `secrets.providers.<alias>` 作为路径。
<AccordionGroup>
<Accordion title="通用标志">
<Accordion title="Common flags">
- `--provider-source <env|file|exec>`
- `--provider-timeout-ms <ms>`（`file`、`exec`）
</Accordion>
<Accordion title="Env 提供商（--provider-source env）">
<Accordion title="Env provider (--provider-source env)">
- `--provider-allowlist <ENV_VAR>`（可重复）
</Accordion>
<Accordion title="File 提供商（--provider-source file）">
<Accordion title="File provider (--provider-source file)">
- `--provider-path <path>`（必需）
- `--provider-mode <singleValue|json>`
- `--provider-max-bytes <bytes>`
- `--provider-allow-insecure-path`
</Accordion>
<Accordion title="Exec 提供商（--provider-source exec）">
<Accordion title="Exec provider (--provider-source exec)">
- `--provider-command <path>`（必需）
- `--provider-arg <arg>`（可重复）
- `--provider-no-output-timeout-ms <ms>`
@ -234,9 +291,9 @@ openclaw config set secrets.providers.vault \
--provider-timeout-ms 5000
```
## 空运行
## Dry run
使用 `--dry-run` 验证变更而不写入 `openclaw.json`。
使用 `--dry-run` 在不写入 `openclaw.json` 的情况下验证更改。
```bash
openclaw config set channels.discord.token \
@ -261,26 +318,26 @@ openclaw config set channels.discord.token \
```
<AccordionGroup>
<Accordion title="空运行行为">
- 构建器模式：对已变更的 refs/提供商运行 SecretRef 可解析性检查。
- JSON 模式（`--strict-json`、`--json` 或批处理模式）：运行 schema 验证和 SecretRef 可解析性检查。
- 对已知不受支持的 SecretRef 目标 surface，也会运行策略验证。
- 策略检查会评估完整的变更后配置，因此父对象写入（例如将 `hooks` 设置为对象）无法绕过不受支持 surface 的验证。
- 为避免命令副作用，空运行期间默认跳过 Exec SecretRef 检查。
- 将 `--allow-exec` 与 `--dry-run` 一起使用，可选择启用 exec SecretRef 检查（这可能会执行提供商命令）。
- `--allow-exec` 仅用于空运行；如果不带 `--dry-run` 使用则会报错。
<Accordion title="Dry-run behavior">
- 构建器模式：对已更改的 refs/providers 运行 SecretRef 可解析性检查。
- JSON 模式（`--strict-json`、`--json` 或批量模式）：运行 schema 验证以及 SecretRef 可解析性检查。
- 策略验证也会针对已知不支持的 SecretRef 目标表面运行。
- 策略检查会评估完整的更改后配置，因此父对象写入（例如将 `hooks` 设置为对象）无法绕过不支持表面的验证。
- dry-run 期间默认跳过 exec SecretRef 检查，以避免命令副作用。
- 将 `--allow-exec` 与 `--dry-run` 一起使用可选择启用 exec SecretRef 检查（这可能会执行提供商命令）。
- `--allow-exec` 仅用于 dry-run；如果不与 `--dry-run` 一起使用会报错。
</Accordion>
<Accordion title="--dry-run --json 字段">
<Accordion title="--dry-run --json fields">
`--dry-run --json` 会打印机器可读报告：
- `ok`：空运行是否通过
- `ok`：dry-run 是否通过
- `operations`：已评估的赋值数量
- `checks`：是否运行了 schema/可解析性检查
- `checks.resolvabilityComplete`：可解析性检查是否运行完成（跳过 exec refs 时为 false）
- `refsChecked`：空运行期间实际解析的 refs 数量
- `skippedExecRefs`：因未设置 `--allow-exec` 而跳过的 exec refs 数量
- `errors`：`ok=false` 时的结构化 schema/可解析性失败
- `refsChecked`：dry-run 期间实际解析的 refs 数量
- `skippedExecRefs`：由于未设置 `--allow-exec` 而跳过的 exec refs 数量
- `errors`：当 `ok=false` 时的结构化 schema/可解析性失败信息
</Accordion>
</AccordionGroup>
@ -356,10 +413,10 @@ openclaw config set channels.discord.token \
<AccordionGroup>
<Accordion title="如果 dry-run 失败">
- `config schema validation failed`：你的变更后配置形状无效；修复路径/值或提供商/ref 对象形状。
- `Config policy validation failed: unsupported SecretRef usage`：将该凭据移回明文/字符串输入，并仅在支持的表面上保留 SecretRefs。
- `SecretRef assignment(s) could not be resolved`：当前无法解析引用的提供商/ref（缺少环境变量、文件指针无效、exec 提供商失败，或提供商/源不匹配）。
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`：dry-run 跳过了 exec refs；如果你需要 exec 可解析性验证，请使用 `--allow-exec` 重新运行。
- `config schema validation failed`：变更后的配置结构无效；修正路径/值或提供商/ref 对象结构。
- `Config policy validation failed: unsupported SecretRef usage`：将该凭证移回明文/字符串输入，并仅在受支持的表面使用 SecretRefs。
- `SecretRef assignment(s) could not be resolved`：当前无法解析引用的提供商/ref（缺少环境变量、文件指针无效、exec 提供商失败，或提供商/来源不匹配）。
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`：dry-run 跳过了 exec 引用；如果你需要 exec 可解析性验证，请使用 `--allow-exec` 重新运行。
- 对于批处理模式，请修复失败条目，并在写入前重新运行 `--dry-run`。
</Accordion>
@ -367,13 +424,13 @@ openclaw config set channels.discord.token \
## 写入安全
`openclaw config set` 和其他 OpenClaw 拥有的配置写入器会在提交到磁盘前验证完整的变更后配置。如果新的载荷未通过 schema 验证，或看起来像破坏性覆盖，活动配置会保持不变，被拒绝的载荷会作为 `openclaw.json.rejected.*` 保存到旁边。
`openclaw config set` 和其他 OpenClaw 拥有的配置写入器会在提交到磁盘前验证完整的变更后配置。如果新载荷未通过 schema 验证，或看起来像破坏性覆盖，活动配置会保持不变，被拒绝的载荷会作为 `openclaw.json.rejected.*` 保存在旁边。
<Warning>
活动配置路径必须是常规文件。不支持通过符号链接布局的 `openclaw.json` 进行写入；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
活动配置路径必须是普通文件。写入不支持符号链接的 `openclaw.json` 布局；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
</Warning>
小改动优先使用 CLI 写入：
小幅编辑优先使用 CLI 写入：
```bash
openclaw config set gateway.reload.mode hybrid --dry-run
@ -381,7 +438,7 @@ openclaw config set gateway.reload.mode hybrid
openclaw config validate
```
如果写入被拒绝，请检查保存的载荷并修复完整的配置形状：
如果写入被拒绝，请检查保存的载荷并修复完整配置结构：
```bash
CONFIG="$(openclaw config file)"
@ -389,13 +446,13 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate
```
仍然允许直接用编辑器写入，但运行中的 Gateway 网关会在它们通过验证前将其视为不受信任。无效的直接编辑可以在启动或热重载期间从上次已知良好备份恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
仍然允许直接用编辑器写入，但运行中的 Gateway 网关会在它们通过验证前将其视为不可信。无效的直接编辑可能会在启动或热重载期间从最后已知良好的备份恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
整文件恢复仅用于全局损坏的配置，例如解析错误、根级 schema 失败、旧版迁移失败，或插件与根配置混合失败。如果验证只在 `plugins.entries.<id>...` 下失败，OpenClaw 会保留当前的 `openclaw.json`，并报告插件本地问题，而不是恢复 `.last-good`。这可以防止插件 schema 变更或 `minHostVersion` 偏差回滚无关的用户设置，例如模型、提供商、auth profiles、渠道、Gateway 网关暴露、工具、memory、browser 或 cron 配置。
整文件恢复仅用于全局损坏的配置，例如解析错误、根级 schema 失败、旧版迁移失败，或插件与根配置同时失败。如果验证仅在 `plugins.entries.<id>...` 下失败，OpenClaw 会保留活动的 `openclaw.json`，并报告插件本地问题，而不是恢复 `.last-good`。这可以防止插件 schema 变更或 `minHostVersion` 偏差回滚无关的用户设置，例如模型、提供商、认证配置文件、渠道、Gateway 网关暴露、工具、内存、浏览器或 cron 配置。
## 子命令
- `config file`：打印活动配置文件路径（由 `OPENCLAW_CONFIG_PATH` 或默认位置解析）。该路径应指向常规文件，而不是符号链接。
- `config file`：打印活动配置文件路径（从 `OPENCLAW_CONFIG_PATH` 或默认位置解析）。该路径应指向普通文件，而不是符号链接。
编辑后重启 Gateway 网关。
@ -408,7 +465,7 @@ openclaw config validate
openclaw config validate --json
```
`openclaw config validate` 通过后，你可以使用本地 TUI，让嵌入式智能体在你从同一终端验证每项变更时，将活动配置与文档进行比较：
`openclaw config validate` 通过后，你可以使用本地 TUI，让嵌入式智能体在同一个终端中验证每项变更时，对照文档比较活动配置：
<Note>
如果验证已经失败，请从 `openclaw configure` 或 `openclaw doctor --fix` 开始。`openclaw chat` 不会绕过无效配置保护。
@ -418,7 +475,7 @@ openclaw config validate --json
openclaw chat
```
然后在 TUI 内：
然后在 TUI 中：
```text
!openclaw config file
@ -440,11 +497,11 @@ openclaw chat
每次变更后重新运行 `openclaw config validate`。
</Step>
<Step title="针对运行时问题运行 Doctor">
如果验证通过但运行时仍然不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 来获取迁移和修复帮助。
如果验证通过但运行时仍不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 获取迁移与修复帮助。
</Step>
</Steps>
## 相关内容
## 相关
- [CLI 参考](/zh-CN/cli)
- [配置](/zh-CN/gateway/configuration)

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

@ -1,38 +1,38 @@
---
read_when:
- 你希望为 Gateway 网关使用一台低成本、始终在线的 Linux 主机
- 你希望获得远程 Control UI 访问能力，而无需自行运行 VPS
summary: 在 exe.dev 上运行 OpenClaw Gateway 网关（VM + HTTPS 代理）以实现远程访问
- 你想要一台用于 Gateway 网关的低成本、始终在线的 Linux 主机
- 你想在不运行自己的 VPS 的情况下远程访问控制界面
summary: 在 exe.dev 上运行 OpenClaw Gateway 网关（VM + HTTPS 代理）以进行远程访问
title: exe.dev
x-i18n:
generated_at: "2026-04-27T07:11:38Z"
model: gpt-5.4
generated_at: "2026-04-29T21:05:47Z"
model: gpt-5.5
provider: openai
source_hash: 98bc90ff26ce1773bd0e05f975fcc3427039e90ce50eca21bb2e8232f7ac730f
source_hash: b571f9b29bb2cca0f311db4188c922b2f70ee91cb48b233cf9922e57a7f05340
source_path: install/exe-dev.md
workflow: 15
workflow: 16
---
目标：让 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”，然后等待 Shelley 完成配置
4. 打开 `https://<vm-name>.exe.xyz/`，并使用已配置的共享密钥进行身份验证（本指南默认使用令牌认证，但如果你切换 `gateway.auth.mode`，密码认证也可以使用）
2. 按需填写你的认证密钥/token
3. 点击 VM 旁边的“智能体”，并等待 Shelley 完成预配
4. 打开 `https://<vm-name>.exe.xyz/`，并使用配置的共享密钥进行认证（本指南默认使用 token 认证，但如果你切换 `gateway.auth.mode`，密码认证也可用）
5. 使用 `openclaw devices approve <requestId>` 批准任何待处理的设备配对请求
## 你需要准备的内容
## 你需要准备
- 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 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.
@ -40,9 +40,9 @@ Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-inter
## 手动安装
## 1）创建 VM
## 1) 创建 VM
在你的设备上执行：
从你的设备运行：
```bash
ssh exe.dev new
@ -55,17 +55,17 @@ ssh <vm-name>.exe.xyz
```
<Tip>
请保持此 VM 为**有状态**。OpenClaw 会将 `openclaw.json`、每个智能体的 `auth-profiles.json`、会话以及渠道 / 提供商状态存储在 `~/.openclaw/` 下，并将工作区存储在 `~/.openclaw/workspace/` 下。
保持这个 VM **有状态**。OpenClaw 会将 `openclaw.json`、每个智能体的 `auth-profiles.json`、会话以及渠道/提供商状态存储在 `~/.openclaw/` 下，并将工作区存储在 `~/.openclaw/workspace/` 下。
</Tip>
## 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 +73,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 {
@ -107,15 +107,84 @@ server {
}
```
请覆盖转发头，而不是保留客户端提供的链式值。OpenClaw 只信任来自明确配置代理的转发 IP 元数据，而追加式的 `X-Forwarded-For` 链会被视为一种加固风险。
覆盖转发标头，而不是保留客户端提供的链。
OpenClaw 只信任来自显式配置代理的转发 IP 元数据，
而追加式 `X-Forwarded-For` 链会被视为强化安全风险。
## 5）访问 OpenClaw 并授予权限
## 5) 访问 OpenClaw 并授予权限
访问 `https://<vm-name>.exe.xyz/`（参见新手引导期间的 Control UI 输出）。如果提示认证，请粘贴来自 VM 的已配置共享密钥。本指南使用令牌认证，因此可通过 `openclaw config get gateway.auth.token` 获取 `gateway.auth.token`（或使用 `openclaw doctor --generate-gateway-token` 生成一个）。如果你已将 Gateway 网关改为密码认证，请改用 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`。使用 `openclaw devices list` 和 `openclaw devices approve <requestId>` 批准设备。不确定时，可以直接在浏览器中使用 Shelley！
访问 `https://<vm-name>.exe.xyz/`（参见新手引导中的 Control UI 输出）。如果它提示认证，请粘贴来自 VM 的已配置共享密钥。本指南使用 token 认证，因此使用 `openclaw config get gateway.auth.token` 获取 `gateway.auth.token`（或使用 `openclaw doctor --generate-gateway-token` 生成一个）。
如果你已将 Gateway 网关改为密码认证，请改用 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`。
使用 `openclaw devices list` 和 `openclaw devices approve <requestId>` 批准设备。不确定时，就从浏览器使用 Shelley！
## 远程渠道设置
对于远程主机，优先使用一次 `config patch` 调用，而不是多次 SSH 调用 `config set`。将真实 token 保存在 VM 环境或 `~/.openclaw/.env` 中，并且只在 `openclaw.json` 中放置 SecretRefs。
在 VM 上，让服务环境包含它所需的机密：
```bash
cat >> ~/.openclaw/.env <<'EOF'
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
DISCORD_BOT_TOKEN=...
OPENAI_API_KEY=sk-...
EOF
```
从你的本地机器创建补丁文件，并将其通过管道传给 VM：
```json5
// openclaw.remote.patch.json5
{
secrets: {
providers: {
default: { source: "env" },
},
},
channels: {
slack: {
enabled: true,
mode: "socket",
botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
groupPolicy: "open",
requireMention: false,
},
discord: {
enabled: true,
token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
dmPolicy: "disabled",
dm: { enabled: false },
groupPolicy: "allowlist",
},
},
agents: {
defaults: {
model: { primary: "openai/gpt-5.5" },
models: {
"openai/gpt-5.5": { params: { fastMode: true } },
},
},
},
}
```
```bash
ssh <vm-name>.exe.xyz 'openclaw config patch --stdin --dry-run' < ./openclaw.remote.patch.json5
ssh <vm-name>.exe.xyz 'openclaw config patch --stdin' < ./openclaw.remote.patch.json5
ssh <vm-name>.exe.xyz 'openclaw gateway restart && openclaw health'
```
当嵌套允许列表应当精确变为补丁值时，使用 `--replace-path`，例如替换 Discord 渠道允许列表时：
```bash
ssh <vm-name>.exe.xyz 'openclaw config patch --stdin --replace-path "channels.discord.guilds[\"123\"].channels"' < ./discord.patch.json5
```
## 远程访问
远程访问由 [exe.dev](https://exe.dev) 的认证机制处理。默认情况下，来自端口 8000 的 HTTP 流量会转发到 `https://<vm-name>.exe.xyz`，并使用邮箱认证。
远程访问由 [exe.dev](https://exe.dev) 的认证处理。默认情况下，来自端口 8000 的 HTTP 流量会通过电子邮件认证转发到 `https://<vm-name>.exe.xyz`。
## 更新