3104 lines
111 KiB
Markdown
3104 lines
111 KiB
Markdown
---
|
||
description: Complete field-by-field reference for ~/.openclaw/openclaw.json
|
||
read_when:
|
||
- 你需要精确到字段级别的配置语义或默认值
|
||
- 你正在验证渠道、模型、Gateway 网关或工具配置块
|
||
summary: 每个 OpenClaw 配置键、默认值和渠道设置的完整参考
|
||
title: 配置参考
|
||
x-i18n:
|
||
generated_at: "2026-03-16T06:27:43Z"
|
||
model: gpt-5.4
|
||
provider: openai
|
||
source_hash: c2926153fa94bbb3141ac7cd9ebfa381394c9c9ad7a1cf1d21fb91c879905d51
|
||
source_path: gateway/configuration-reference.md
|
||
workflow: 15
|
||
---
|
||
|
||
# 配置参考
|
||
|
||
`~/.openclaw/openclaw.json` 中所有可用字段。若需面向任务的概览，请参见 [Configuration](/gateway/configuration)。
|
||
|
||
配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全默认值。
|
||
|
||
---
|
||
|
||
## 渠道
|
||
|
||
只要某个渠道的配置节存在，它就会自动启动（除非设置了 `enabled: false`）。
|
||
|
||
### 私信和群组访问
|
||
|
||
所有渠道都支持私信策略和群组策略：
|
||
|
||
| DM policy | Behavior |
|
||
| ----------------- | --------------------------------------------------- |
|
||
| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 |
|
||
| `allowlist` | 仅 `allowFrom` 中的发送者（或已配对的允许列表存储） |
|
||
| `open` | 允许所有入站私信（要求 `allowFrom: ["*"]`） |
|
||
| `disabled` | 忽略所有入站私信 |
|
||
|
||
| Group policy | Behavior |
|
||
| ------------------- | -------------------------------------- |
|
||
| `allowlist`（默认） | 仅允许匹配已配置 allowlist 的群组 |
|
||
| `open` | 绕过群组 allowlist（仍会应用提及门控） |
|
||
| `disabled` | 阻止所有群组/房间消息 |
|
||
|
||
<Note>
|
||
`channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。
|
||
配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。
|
||
如果某个提供商配置块完全缺失（`channels.<provider>` 不存在），运行时群组策略会回退到 `allowlist`（默认拒绝），并在启动时发出警告。
|
||
</Note>
|
||
|
||
### 渠道模型覆盖
|
||
|
||
使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当会话尚未存在模型覆盖时（例如通过 `/model` 设置），才会应用渠道映射。
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
modelByChannel: {
|
||
discord: {
|
||
"123456789012345678": "anthropic/claude-opus-4-6",
|
||
},
|
||
slack: {
|
||
C1234567890: "openai/gpt-4.1",
|
||
},
|
||
telegram: {
|
||
"-1001234567890": "openai/gpt-4.1-mini",
|
||
"-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
### 渠道默认值和心跳
|
||
|
||
使用 `channels.defaults` 为多个提供商共享群组策略和心跳行为：
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
defaults: {
|
||
groupPolicy: "allowlist", // open | allowlist | disabled
|
||
heartbeat: {
|
||
showOk: false,
|
||
showAlerts: true,
|
||
useIndicator: true,
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `channels.defaults.groupPolicy`：当提供商级 `groupPolicy` 未设置时使用的回退群组策略。
|
||
- `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康的渠道状态。
|
||
- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。
|
||
- `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。
|
||
|
||
### WhatsApp
|
||
|
||
WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已关联的会话时，它会自动启动。
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
whatsapp: {
|
||
dmPolicy: "pairing", // pairing | allowlist | open | disabled
|
||
allowFrom: ["+15555550123", "+447700900123"],
|
||
textChunkLimit: 4000,
|
||
chunkMode: "length", // length | newline
|
||
mediaMaxMb: 50,
|
||
sendReadReceipts: true, // 蓝色双勾（自聊模式下为 false）
|
||
groups: {
|
||
"*": { requireMention: true },
|
||
},
|
||
groupPolicy: "allowlist",
|
||
groupAllowFrom: ["+15551234567"],
|
||
},
|
||
},
|
||
web: {
|
||
enabled: true,
|
||
heartbeatSeconds: 60,
|
||
reconnect: {
|
||
initialMs: 2000,
|
||
maxMs: 120000,
|
||
factor: 1.4,
|
||
jitter: 0.2,
|
||
maxAttempts: 0,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
<Accordion title="多账户 WhatsApp">
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
whatsapp: {
|
||
accounts: {
|
||
default: {},
|
||
personal: {},
|
||
biz: {
|
||
// authDir: "~/.openclaw/credentials/whatsapp/biz",
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 出站命令默认使用账户 `default`（若存在）；否则使用第一个已配置的账户 ID（排序后）。
|
||
- 可选的 `channels.whatsapp.defaultAccount` 会在其与某个已配置账户 ID 匹配时，覆盖该回退默认账户选择。
|
||
- 旧版单账户 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。
|
||
- 按账户覆盖：`channels.whatsapp.accounts.<id>.sendReadReceipts`、`channels.whatsapp.accounts.<id>.dmPolicy`、`channels.whatsapp.accounts.<id>.allowFrom`。
|
||
|
||
</Accordion>
|
||
|
||
### Telegram
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
telegram: {
|
||
enabled: true,
|
||
botToken: "your-bot-token",
|
||
dmPolicy: "pairing",
|
||
allowFrom: ["tg:123456789"],
|
||
groups: {
|
||
"*": { requireMention: true },
|
||
"-1001234567890": {
|
||
allowFrom: ["@admin"],
|
||
systemPrompt: "Keep answers brief.",
|
||
topics: {
|
||
"99": {
|
||
requireMention: false,
|
||
skills: ["search"],
|
||
systemPrompt: "Stay on topic.",
|
||
},
|
||
},
|
||
},
|
||
},
|
||
customCommands: [
|
||
{ command: "backup", description: "Git backup" },
|
||
{ command: "generate", description: "Create an image" },
|
||
],
|
||
historyLimit: 50,
|
||
replyToMode: "first", // off | first | all
|
||
linkPreview: true,
|
||
streaming: "partial", // off | partial | block | progress（默认：off）
|
||
actions: { reactions: true, sendMessage: true },
|
||
reactionNotifications: "own", // off | own | all
|
||
mediaMaxMb: 100,
|
||
retry: {
|
||
attempts: 3,
|
||
minDelayMs: 400,
|
||
maxDelayMs: 30000,
|
||
jitter: 0.1,
|
||
},
|
||
network: {
|
||
autoSelectFamily: true,
|
||
dnsResultOrder: "ipv4first",
|
||
},
|
||
proxy: "socks5://localhost:9050",
|
||
webhookUrl: "https://example.com/telegram-webhook",
|
||
webhookSecret: "secret",
|
||
webhookPath: "/telegram-webhook",
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 机器人令牌：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅常规文件；拒绝符号链接），默认账户还可回退到 `TELEGRAM_BOT_TOKEN`。
|
||
- 可选的 `channels.telegram.defaultAccount` 会在其与某个已配置账户 ID 匹配时覆盖默认账户选择。
|
||
- 在多账户设置（2 个及以上账户 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`），以避免回退路由；如果缺失或无效，`openclaw doctor` 会发出警告。
|
||
- `configWrites: false` 会阻止 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。
|
||
- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为论坛话题配置持久化 ACP 绑定（在 `match.peer.id` 中使用规范形式 `chatId:topic:topicId`）。字段语义与 [ACP Agents](/tools/acp-agents#channel-specific-settings) 共享。
|
||
- Telegram 流式预览使用 `sendMessage` + `editMessageText`（适用于私聊和群聊）。
|
||
- 重试策略：参见 [Retry policy](/concepts/retry)。
|
||
|
||
### Discord
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
discord: {
|
||
enabled: true,
|
||
token: "your-bot-token",
|
||
mediaMaxMb: 8,
|
||
allowBots: false,
|
||
actions: {
|
||
reactions: true,
|
||
stickers: true,
|
||
polls: true,
|
||
permissions: true,
|
||
messages: true,
|
||
threads: true,
|
||
pins: true,
|
||
search: true,
|
||
memberInfo: true,
|
||
roleInfo: true,
|
||
roles: false,
|
||
channelInfo: true,
|
||
voiceStatus: true,
|
||
events: true,
|
||
moderation: false,
|
||
},
|
||
replyToMode: "off", // off | first | all
|
||
dmPolicy: "pairing",
|
||
allowFrom: ["1234567890", "123456789012345678"],
|
||
dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
|
||
guilds: {
|
||
"123456789012345678": {
|
||
slug: "friends-of-openclaw",
|
||
requireMention: false,
|
||
ignoreOtherMentions: true,
|
||
reactionNotifications: "own",
|
||
users: ["987654321098765432"],
|
||
channels: {
|
||
general: { allow: true },
|
||
help: {
|
||
allow: true,
|
||
requireMention: true,
|
||
users: ["987654321098765432"],
|
||
skills: ["docs"],
|
||
systemPrompt: "Short answers only.",
|
||
},
|
||
},
|
||
},
|
||
},
|
||
historyLimit: 20,
|
||
textChunkLimit: 2000,
|
||
chunkMode: "length", // length | newline
|
||
streaming: "off", // off | partial | block | progress（在 Discord 上 progress 映射为 partial）
|
||
maxLinesPerMessage: 17,
|
||
ui: {
|
||
components: {
|
||
accentColor: "#5865F2",
|
||
},
|
||
},
|
||
threadBindings: {
|
||
enabled: true,
|
||
idleHours: 24,
|
||
maxAgeHours: 0,
|
||
spawnSubagentSessions: false, // 为 `sessions_spawn({ thread: true })` 选择性启用
|
||
},
|
||
voice: {
|
||
enabled: true,
|
||
autoJoin: [
|
||
{
|
||
guildId: "123456789012345678",
|
||
channelId: "234567890123456789",
|
||
},
|
||
],
|
||
daveEncryption: true,
|
||
decryptionFailureTolerance: 24,
|
||
tts: {
|
||
provider: "openai",
|
||
openai: { voice: "alloy" },
|
||
},
|
||
},
|
||
retry: {
|
||
attempts: 3,
|
||
minDelayMs: 500,
|
||
maxDelayMs: 30000,
|
||
jitter: 0.1,
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 令牌：`channels.discord.token`，默认账户还可回退到 `DISCORD_BOT_TOKEN`。
|
||
- 显式提供 Discord `token` 的直接出站调用会使用该令牌；账户重试/策略设置仍来自当前活动运行时快照中的所选账户。
|
||
- 可选的 `channels.discord.defaultAccount` 会在其与某个已配置账户 ID 匹配时覆盖默认账户选择。
|
||
- 对投递目标请使用 `user:<id>`（私信）或 `channel:<id>`（服务器频道）；裸数字 ID 会被拒绝。
|
||
- 服务器 slug 为小写且空格替换为 `-`；频道键使用 slug 化名称（不含 `#`）。优先使用 guild ID。
|
||
- 默认会忽略机器人自己发出的消息。`allowBots: true` 可启用；使用 `allowBots: "mentions"` 可仅接受提及该机器人的机器人消息（仍会过滤自己的消息）。
|
||
- `channels.discord.guilds.<id>.ignoreOtherMentions`（及频道级覆盖）会丢弃那些提及了其他用户或角色但未提及机器人的消息（不含 @everyone/@here）。
|
||
- `maxLinesPerMessage`（默认 17）会在消息过高时拆分，即便未超过 2000 个字符。
|
||
- `channels.discord.threadBindings` 控制 Discord 线程绑定路由：
|
||
- `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age` 以及绑定后的投递/路由）
|
||
- `idleHours`：不活动自动取消聚焦的 Discord 覆盖值（小时，`0` 表示禁用）
|
||
- `maxAgeHours`：硬性最大年龄的 Discord 覆盖值（小时，`0` 表示禁用）
|
||
- `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程的选择性开关
|
||
- 顶层 `bindings[]` 中 `type: "acp"` 的条目会为频道和线程配置持久化 ACP 绑定（在 `match.peer.id` 中使用频道/线程 ID）。字段语义与 [ACP Agents](/tools/acp-agents#channel-specific-settings) 共享。
|
||
- `channels.discord.ui.components.accentColor` 设置 Discord components v2 容器的强调色。
|
||
- `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。
|
||
- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。
|
||
- 在重复解密失败后，OpenClaw 还会尝试通过离开/重新加入语音会话来恢复语音接收。
|
||
- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。
|
||
- `channels.discord.autoPresence` 将运行时可用性映射为机器人状态（健康 => online，降级 => idle，耗尽 => dnd），并允许可选的状态文本覆盖。
|
||
- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急兼容模式）。
|
||
|
||
**反应通知模式：**`off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（`guilds.<id>.users` 中所有消息）。
|
||
|
||
### Google Chat
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
googlechat: {
|
||
enabled: true,
|
||
serviceAccountFile: "/path/to/service-account.json",
|
||
audienceType: "app-url", // app-url | project-number
|
||
audience: "https://gateway.example.com/googlechat",
|
||
webhookPath: "/googlechat",
|
||
botUser: "users/1234567890",
|
||
dm: {
|
||
enabled: true,
|
||
policy: "pairing",
|
||
allowFrom: ["users/1234567890"],
|
||
},
|
||
groupPolicy: "allowlist",
|
||
groups: {
|
||
"spaces/AAAA": { allow: true, requireMention: true },
|
||
},
|
||
actions: { reactions: true },
|
||
typingIndicator: "message",
|
||
mediaMaxMb: 20,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 服务账户 JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。
|
||
- 也支持服务账户 SecretRef（`serviceAccountRef`）。
|
||
- 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
|
||
- 对投递目标使用 `spaces/<spaceId>` 或 `users/<userId>`。
|
||
- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。
|
||
|
||
### Slack
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
slack: {
|
||
enabled: true,
|
||
botToken: "xoxb-...",
|
||
appToken: "xapp-...",
|
||
dmPolicy: "pairing",
|
||
allowFrom: ["U123", "U456", "*"],
|
||
dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
|
||
channels: {
|
||
C123: { allow: true, requireMention: true, allowBots: false },
|
||
"#general": {
|
||
allow: true,
|
||
requireMention: true,
|
||
allowBots: false,
|
||
users: ["U123"],
|
||
skills: ["docs"],
|
||
systemPrompt: "Short answers only.",
|
||
},
|
||
},
|
||
historyLimit: 50,
|
||
allowBots: false,
|
||
reactionNotifications: "own",
|
||
reactionAllowlist: ["U123"],
|
||
replyToMode: "off", // off | first | all
|
||
thread: {
|
||
historyScope: "thread", // thread | channel
|
||
inheritParent: false,
|
||
},
|
||
actions: {
|
||
reactions: true,
|
||
messages: true,
|
||
pins: true,
|
||
memberInfo: true,
|
||
emojiList: true,
|
||
},
|
||
slashCommand: {
|
||
enabled: true,
|
||
name: "openclaw",
|
||
sessionPrefix: "slack:slash",
|
||
ephemeral: true,
|
||
},
|
||
typingReaction: "hourglass_flowing_sand",
|
||
textChunkLimit: 4000,
|
||
chunkMode: "length",
|
||
streaming: "partial", // off | partial | block | progress（预览模式）
|
||
nativeStreaming: true, // 当 streaming=partial 时使用 Slack 原生流式 API
|
||
mediaMaxMb: 20,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账户环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
|
||
- **HTTP mode** 需要 `botToken`，外加 `signingSecret`（根级或按账户）。
|
||
- `configWrites: false` 会阻止 Slack 发起的配置写入。
|
||
- 可选的 `channels.slack.defaultAccount` 会在其与某个已配置账户 ID 匹配时覆盖默认账户选择。
|
||
- `channels.slack.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会自动迁移。
|
||
- 对投递目标使用 `user:<id>`（私信）或 `channel:<id>`（频道）。
|
||
|
||
**反应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
|
||
|
||
**线程会话隔离：**`thread.historyScope` 可设为按线程（默认）或在频道内共享。`thread.inheritParent` 会将父频道记录复制到新线程。
|
||
|
||
- `typingReaction` 会在回复运行期间，为入站 Slack 消息添加一个临时反应，并在完成后移除。请使用 Slack emoji 短代码，例如 `"hourglass_flowing_sand"`。
|
||
|
||
| Action group | Default | Notes |
|
||
| ------------ | ------- | ------------------- |
|
||
| reactions | 已启用 | 添加反应 + 列出反应 |
|
||
| messages | 已启用 | 读取/发送/编辑/删除 |
|
||
| pins | 已启用 | 置顶/取消置顶/列出 |
|
||
| memberInfo | 已启用 | 成员信息 |
|
||
| emojiList | 已启用 | 自定义 emoji 列表 |
|
||
|
||
### Mattermost
|
||
|
||
Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
mattermost: {
|
||
enabled: true,
|
||
botToken: "mm-token",
|
||
baseUrl: "https://chat.example.com",
|
||
dmPolicy: "pairing",
|
||
chatmode: "oncall", // oncall | onmessage | onchar
|
||
oncharPrefixes: [">", "!"],
|
||
commands: {
|
||
native: true, // 选择性启用
|
||
nativeSkills: true,
|
||
callbackPath: "/api/channels/mattermost/command",
|
||
// 为反向代理/公共部署提供可选的显式 URL
|
||
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
|
||
},
|
||
textChunkLimit: 4000,
|
||
chunkMode: "length",
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
聊天模式：`oncall`（在 @ 提及时回复，默认）、`onmessage`（每条消息都回复）、`onchar`（以触发前缀开头的消息）。
|
||
|
||
启用 Mattermost 原生命令时：
|
||
|
||
- `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。
|
||
- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可以访问它。
|
||
- 对于私有/tailnet/内网回调主机，Mattermost 可能要求
|
||
`ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机/域名。
|
||
请使用主机/域名值，而不是完整 URL。
|
||
- `channels.mattermost.configWrites`：允许或拒绝 Mattermost 发起的配置写入。
|
||
- `channels.mattermost.requireMention`：在频道中回复前要求 `@mention`。
|
||
- 可选的 `channels.mattermost.defaultAccount` 会在其与某个已配置账户 ID 匹配时覆盖默认账户选择。
|
||
|
||
### Signal
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
signal: {
|
||
enabled: true,
|
||
account: "+15555550123", // 可选账户绑定
|
||
dmPolicy: "pairing",
|
||
allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
|
||
configWrites: true,
|
||
reactionNotifications: "own", // off | own | all | allowlist
|
||
reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
|
||
historyLimit: 50,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
**反应通知模式：**`off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。
|
||
|
||
- `channels.signal.account`：将渠道启动固定到特定 Signal 账户身份。
|
||
- `channels.signal.configWrites`：允许或拒绝 Signal 发起的配置写入。
|
||
- 可选的 `channels.signal.defaultAccount` 会在其与某个已配置账户 ID 匹配时覆盖默认账户选择。
|
||
|
||
### BlueBubbles
|
||
|
||
BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置在 `channels.bluebubbles` 下）。
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
bluebubbles: {
|
||
enabled: true,
|
||
dmPolicy: "pairing",
|
||
// serverUrl、password、webhookPath、群组控制和高级操作：
|
||
// 见 /channels/bluebubbles
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。
|
||
- 可选的 `channels.bluebubbles.defaultAccount` 会在其与某个已配置账户 ID 匹配时覆盖默认账户选择。
|
||
- 完整的 BlueBubbles 渠道配置文档见 [BlueBubbles](/channels/bluebubbles)。
|
||
|
||
### iMessage
|
||
|
||
OpenClaw 会启动 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护进程或端口。
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
imessage: {
|
||
enabled: true,
|
||
cliPath: "imsg",
|
||
dbPath: "~/Library/Messages/chat.db",
|
||
remoteHost: "user@gateway-host",
|
||
dmPolicy: "pairing",
|
||
allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
|
||
historyLimit: 50,
|
||
includeAttachments: false,
|
||
attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
|
||
remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
|
||
mediaMaxMb: 16,
|
||
service: "auto",
|
||
region: "US",
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 可选的 `channels.imessage.defaultAccount` 会在其与某个已配置账户 ID 匹配时覆盖默认账户选择。
|
||
|
||
- 需要对 Messages DB 具有 Full Disk Access。
|
||
- 优先使用 `chat_id:<id>` 目标。使用 `imsg chats --limit 20` 列出聊天。
|
||
- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。
|
||
- `attachmentRoots` 和 `remoteAttachmentRoots` 会限制入站附件路径（默认：`/Users/*/Library/Messages/Attachments`）。
|
||
- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts`。
|
||
- `channels.imessage.configWrites`：允许或拒绝 iMessage 发起的配置写入。
|
||
|
||
<Accordion title="iMessage SSH 包装器示例">
|
||
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
exec ssh -T gateway-host imsg "$@"
|
||
```
|
||
|
||
</Accordion>
|
||
|
||
### Microsoft Teams
|
||
|
||
Microsoft Teams 由扩展支持，并配置在 `channels.msteams` 下。
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
msteams: {
|
||
enabled: true,
|
||
configWrites: true,
|
||
// appId、appPassword、tenantId、webhook、团队/频道策略：
|
||
// 见 /channels/msteams
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。
|
||
- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按频道覆盖）见 [Microsoft Teams](/channels/msteams)。
|
||
|
||
### IRC
|
||
|
||
IRC 由扩展支持，并配置在 `channels.irc` 下。
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
irc: {
|
||
enabled: true,
|
||
dmPolicy: "pairing",
|
||
configWrites: true,
|
||
nickserv: {
|
||
enabled: true,
|
||
service: "NickServ",
|
||
password: "${IRC_NICKSERV_PASSWORD}",
|
||
register: false,
|
||
registerEmail: "bot@example.com",
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
|
||
- 可选的 `channels.irc.defaultAccount` 会在其与某个已配置账户 ID 匹配时覆盖默认账户选择。
|
||
- 完整的 IRC 渠道配置（主机/端口/TLS/频道/allowlist/提及门控）见 [IRC](/channels/irc)。
|
||
|
||
### 多账户（所有渠道）
|
||
|
||
按渠道运行多个账户（每个账户有自己的 `accountId`）：
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
telegram: {
|
||
accounts: {
|
||
default: {
|
||
name: "Primary bot",
|
||
botToken: "123456:ABC...",
|
||
},
|
||
alerts: {
|
||
name: "Alerts bot",
|
||
botToken: "987654:XYZ...",
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 省略 `accountId` 时使用 `default`（CLI + 路由）。
|
||
- 环境变量令牌仅适用于 **default** 账户。
|
||
- 基础渠道设置适用于所有账户，除非按账户覆盖。
|
||
- 使用 `bindings[].match.accountId` 将每个账户路由到不同智能体。
|
||
- 如果你通过 `openclaw channels add`（或渠道新手引导）添加了一个非默认账户，而当前仍是单账户顶层渠道配置，OpenClaw 会先将带账户作用域的顶层单账户值移动到 `channels.<channel>.accounts.default`，以便原始账户继续工作。
|
||
- 现有仅渠道绑定（无 `accountId`）仍会匹配默认账户；账户作用域绑定仍是可选的。
|
||
- 当存在命名账户但缺少 `default` 时，`openclaw doctor --fix` 也会通过将带账户作用域的顶层单账户值移动到 `accounts.default` 来修复混合形状。
|
||
|
||
### 其他扩展渠道
|
||
|
||
许多扩展渠道都配置为 `channels.<id>`，并在其专属渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
|
||
查看完整渠道索引：[Channels](/channels)。
|
||
|
||
### 群聊提及门控
|
||
|
||
群消息默认**要求提及**（元数据提及或安全正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。
|
||
|
||
**提及类型：**
|
||
|
||
- **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式中会被忽略。
|
||
- **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。
|
||
- 只有在可以检测提及的情况下（原生提及或至少一个模式），才会强制执行提及门控。
|
||
|
||
```json5
|
||
{
|
||
messages: {
|
||
groupChat: { historyLimit: 50 },
|
||
},
|
||
agents: {
|
||
list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
|
||
},
|
||
}
|
||
```
|
||
|
||
`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels.<channel>.historyLimit`（或按账户）覆盖。设为 `0` 可禁用。
|
||
|
||
#### 私信历史限制
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
telegram: {
|
||
dmHistoryLimit: 30,
|
||
dms: {
|
||
"123456789": { historyLimit: 50 },
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
解析顺序：按私信覆盖 → 提供商默认值 → 无限制（全部保留）。
|
||
|
||
支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。
|
||
|
||
#### 自聊模式
|
||
|
||
将你自己的号码包含在 `allowFrom` 中可启用自聊模式（忽略原生 @ 提及，仅响应文本模式）：
|
||
|
||
```json5
|
||
{
|
||
channels: {
|
||
whatsapp: {
|
||
allowFrom: ["+15555550123"],
|
||
groups: { "*": { requireMention: true } },
|
||
},
|
||
},
|
||
agents: {
|
||
list: [
|
||
{
|
||
id: "main",
|
||
groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
|
||
},
|
||
],
|
||
},
|
||
}
|
||
```
|
||
|
||
### 命令（聊天命令处理）
|
||
|
||
```json5
|
||
{
|
||
commands: {
|
||
native: "auto", // 在支持时注册原生命令
|
||
text: true, // 解析聊天消息中的 /commands
|
||
bash: false, // 允许 !（别名：/bash）
|
||
bashForegroundMs: 2000,
|
||
config: false, // 允许 /config
|
||
debug: false, // 允许 /debug
|
||
restart: false, // 允许 /restart + gateway restart 工具
|
||
allowFrom: {
|
||
"*": ["user1"],
|
||
discord: ["user:123"],
|
||
},
|
||
useAccessGroups: true,
|
||
},
|
||
}
|
||
```
|
||
|
||
<Accordion title="命令详情">
|
||
|
||
- 文本命令必须是以 `/` 开头的**独立**消息。
|
||
- `native: "auto"` 会为 Discord/Telegram 打开原生命令，而让 Slack 保持关闭。
|
||
- 可按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册的命令。
|
||
- `channels.telegram.customCommands` 可添加额外的 Telegram 机器人菜单项。
|
||
- `bash: true` 会为主机 shell 启用 `! <cmd>`。要求 `tools.elevated.enabled` 已启用，且发送者在 `tools.elevated.allowFrom.<channel>` 中。
|
||
- `config: true` 启用 `/config`（读取/写入 `openclaw.json`）。对于 gateway `chat.send` 客户端，持久化的 `/config set|unset` 写入还要求 `operator.admin`；只读的 `/config show` 对普通写作用域 operator 客户端仍然可用。
|
||
- `channels.<provider>.configWrites` 按渠道控制配置变更（默认：true）。
|
||
- 对多账户渠道，`channels.<provider>.accounts.<id>.configWrites` 也会控制针对该账户的写入（例如 `/allowlist --config --account <id>` 或 `/config set channels.<provider>.accounts.<id>...`）。
|
||
- `allowFrom` 是按提供商配置的。设置后，它将成为**唯一**的授权来源（渠道 allowlist/配对和 `useAccessGroups` 都会被忽略）。
|
||
- 当 `allowFrom` 未设置时，`useAccessGroups: false` 允许命令绕过访问组策略。
|
||
|
||
</Accordion>
|
||
|
||
---
|
||
|
||
## 智能体默认值
|
||
|
||
### `agents.defaults.workspace`
|
||
|
||
默认值：`~/.openclaw/workspace`。
|
||
|
||
```json5
|
||
{
|
||
agents: { defaults: { workspace: "~/.openclaw/workspace" } },
|
||
}
|
||
```
|
||
|
||
### `agents.defaults.repoRoot`
|
||
|
||
可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从工作区向上遍历自动检测。
|
||
|
||
```json5
|
||
{
|
||
agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
|
||
}
|
||
```
|
||
|
||
### `agents.defaults.skipBootstrap`
|
||
|
||
禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。
|
||
|
||
```json5
|
||
{
|
||
agents: { defaults: { skipBootstrap: true } },
|
||
}
|
||
```
|
||
|
||
### `agents.defaults.bootstrapMaxChars`
|
||
|
||
单个工作区引导文件在截断前的最大字符数。默认：`20000`。
|
||
|
||
```json5
|
||
{
|
||
agents: { defaults: { bootstrapMaxChars: 20000 } },
|
||
}
|
||
```
|
||
|
||
### `agents.defaults.bootstrapTotalMaxChars`
|
||
|
||
所有工作区引导文件注入时的最大总字符数。默认：`150000`。
|
||
|
||
```json5
|
||
{
|
||
agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
|
||
}
|
||
```
|
||
|
||
### `agents.defaults.bootstrapPromptTruncationWarning`
|
||
|
||
控制引导上下文被截断时，对智能体可见的警告文本。
|
||
默认：`"once"`。
|
||
|
||
- `"off"`：绝不向系统提示注入警告文本。
|
||
- `"once"`：对每个唯一的截断签名仅注入一次警告（推荐）。
|
||
- `"always"`：只要存在截断，就在每次运行时注入警告。
|
||
|
||
```json5
|
||
{
|
||
agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
|
||
}
|
||
```
|
||
|
||
### `agents.defaults.imageMaxDimensionPx`
|
||
|
||
在调用提供商之前，记录/工具图像块中最长边的最大像素尺寸。
|
||
默认：`1200`。
|
||
|
||
较低的值通常会降低视觉 token 用量以及截图密集型运行的请求负载大小。
|
||
较高的值可保留更多视觉细节。
|
||
|
||
```json5
|
||
{
|
||
agents: { defaults: { imageMaxDimensionPx: 1200 } },
|
||
}
|
||
```
|
||
|
||
### `agents.defaults.userTimezone`
|
||
|
||
系统提示上下文使用的时区（不是消息时间戳）。回退到主机时区。
|
||
|
||
```json5
|
||
{
|
||
agents: { defaults: { userTimezone: "America/Chicago" } },
|
||
}
|
||
```
|
||
|
||
### `agents.defaults.timeFormat`
|
||
|
||
系统提示中的时间格式。默认：`auto`（操作系统偏好）。
|
||
|
||
```json5
|
||
{
|
||
agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
|
||
}
|
||
```
|
||
|
||
### `agents.defaults.model`
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
models: {
|
||
"anthropic/claude-opus-4-6": { alias: "opus" },
|
||
"minimax/MiniMax-M2.5": { alias: "minimax" },
|
||
},
|
||
model: {
|
||
primary: "anthropic/claude-opus-4-6",
|
||
fallbacks: ["minimax/MiniMax-M2.5"],
|
||
},
|
||
imageModel: {
|
||
primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
|
||
fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
|
||
},
|
||
pdfModel: {
|
||
primary: "anthropic/claude-opus-4-6",
|
||
fallbacks: ["openai/gpt-5-mini"],
|
||
},
|
||
pdfMaxBytesMb: 10,
|
||
pdfMaxPages: 20,
|
||
thinkingDefault: "low",
|
||
verboseDefault: "off",
|
||
elevatedDefault: "on",
|
||
timeoutSeconds: 600,
|
||
mediaMaxMb: 5,
|
||
contextTokens: 200000,
|
||
maxConcurrent: 3,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||
- 字符串形式只设置主模型。
|
||
- 对象形式设置主模型以及按顺序排列的故障切换模型。
|
||
- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||
- 由 `image` 工具路径作为其视觉模型配置使用。
|
||
- 当所选/默认模型无法接受图像输入时，也用作回退路由。
|
||
- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||
- 由 `pdf` 工具用于模型路由。
|
||
- 如果省略，PDF 工具会回退到 `imageModel`，再回退到提供商的尽力默认值。
|
||
- `pdfMaxBytesMb`：`pdf` 工具在调用时未传入 `maxBytesMb` 时使用的默认 PDF 大小限制。
|
||
- `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。
|
||
- `model.primary`：格式为 `provider/model`（例如 `anthropic/claude-opus-4-6`）。如果省略 provider，OpenClaw 会假定为 `anthropic`（已弃用）。
|
||
- `models`：为 `/model` 配置的模型目录和 allowlist。每项可包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。
|
||
- `params` 合并优先级（配置）：`agents.defaults.models["provider/model"].params` 为基础，然后由 `agents.list[].params`（匹配的智能体 ID）按键覆盖。
|
||
- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及故障切换增删命令）会保存为规范的对象形式，并尽可能保留现有故障切换列表。
|
||
- `maxConcurrent`：会话之间并行的智能体运行最大数（每个会话本身仍是串行）。默认：1。
|
||
|
||
**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）：
|
||
|
||
| Alias | Model |
|
||
| ------------------- | -------------------------------------- |
|
||
| `opus` | `anthropic/claude-opus-4-6` |
|
||
| `sonnet` | `anthropic/claude-sonnet-4-6` |
|
||
| `gpt` | `openai/gpt-5.4` |
|
||
| `gpt-mini` | `openai/gpt-5-mini` |
|
||
| `gemini` | `google/gemini-3.1-pro-preview` |
|
||
| `gemini-flash` | `google/gemini-3-flash-preview` |
|
||
| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
|
||
|
||
你配置的别名始终优先于默认值。
|
||
|
||
Z.AI 的 GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/<model>"].params.thinking`。
|
||
Z.AI 模型默认启用 `tool_stream` 以支持工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设为 `false` 可禁用。
|
||
Anthropic Claude 4.6 模型在未显式设置 thinking 级别时，默认使用 `adaptive` thinking。
|
||
|
||
### `agents.defaults.cliBackends`
|
||
|
||
文本专用回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，可作为备份。
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
cliBackends: {
|
||
"claude-cli": {
|
||
command: "/opt/homebrew/bin/claude",
|
||
},
|
||
"my-cli": {
|
||
command: "my-cli",
|
||
args: ["--json"],
|
||
output: "json",
|
||
modelArg: "--model",
|
||
sessionArg: "--session",
|
||
sessionMode: "existing",
|
||
systemPromptArg: "--system",
|
||
systemPromptWhen: "first",
|
||
imageArg: "--image",
|
||
imageMode: "repeat",
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- CLI 后端以文本为主；工具始终禁用。
|
||
- 设置了 `sessionArg` 时支持会话。
|
||
- 当 `imageArg` 接受文件路径时，支持图像透传。
|
||
|
||
### `agents.defaults.heartbeat`
|
||
|
||
周期性心跳运行。
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
heartbeat: {
|
||
every: "30m", // 0m 表示禁用
|
||
model: "openai/gpt-5.2-mini",
|
||
includeReasoning: false,
|
||
lightContext: false, // 默认：false；true 仅保留工作区引导文件中的 HEARTBEAT.md
|
||
isolatedSession: false, // 默认：false；true 表示每次心跳都在全新会话中运行（无对话历史）
|
||
session: "main",
|
||
to: "+15555550123",
|
||
directPolicy: "allow", // allow（默认）| block
|
||
target: "none", // 默认：none | 可选：last | whatsapp | telegram | discord | ...
|
||
prompt: "Read HEARTBEAT.md if it exists...",
|
||
ackMaxChars: 300,
|
||
suppressToolErrorWarnings: false,
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `every`：时长字符串（ms/s/m/h）。默认：`30m`。
|
||
- `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告负载。
|
||
- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。
|
||
- `lightContext`：为 true 时，心跳运行使用轻量引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。
|
||
- `isolatedSession`：为 true 时，每次心跳都会在无先前对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降到约 2-5K。
|
||
- 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。
|
||
- 心跳会执行完整的智能体轮次——间隔越短，消耗的 token 越多。
|
||
|
||
### `agents.defaults.compaction`
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
compaction: {
|
||
mode: "safeguard", // default | safeguard
|
||
timeoutSeconds: 900,
|
||
reserveTokensFloor: 24000,
|
||
identifierPolicy: "strict", // strict | off | custom
|
||
identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用
|
||
postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入
|
||
model: "openrouter/anthropic/claude-sonnet-4-5", // 可选，仅用于压缩的模型覆盖
|
||
memoryFlush: {
|
||
enabled: true,
|
||
softThresholdTokens: 6000,
|
||
systemPrompt: "Session nearing compaction. Store durable memories now.",
|
||
prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `mode`：`default` 或 `safeguard`（用于长历史的分块摘要）。见 [Compaction](/concepts/compaction)。
|
||
- `timeoutSeconds`：OpenClaw 中止前，单次压缩操作允许的最大秒数。默认：`900`。
|
||
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要时预置内置的不透明标识符保留指导。
|
||
- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。
|
||
- `postCompactionSections`：压缩后重新注入的可选 AGENTS.md H2/H3 节名称。默认是 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置或显式设置为该默认组合时，旧版 `Every Session`/`Safety` 标题也会作为兼容回退被接受。
|
||
- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应保留一个模型，但压缩摘要应在另一个模型上运行时使用；未设置时，压缩会使用会话的主模型。
|
||
- `memoryFlush`：自动压缩前的静默智能体轮次，用于存储持久记忆。工作区为只读时会跳过。
|
||
|
||
### `agents.defaults.contextPruning`
|
||
|
||
在发送到 LLM 之前，从内存上下文中裁剪**旧的工具结果**。**不会**修改磁盘上的会话历史。
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
contextPruning: {
|
||
mode: "cache-ttl", // off | cache-ttl
|
||
ttl: "1h", // 时长（ms/s/m/h），默认单位：分钟
|
||
keepLastAssistants: 3,
|
||
softTrimRatio: 0.3,
|
||
hardClearRatio: 0.5,
|
||
minPrunableToolChars: 50000,
|
||
softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
|
||
hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
|
||
tools: { deny: ["browser", "canvas"] },
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
<Accordion title="cache-ttl 模式行为">
|
||
|
||
- `mode: "cache-ttl"` 启用裁剪过程。
|
||
- `ttl` 控制在上次缓存触碰后，多久才能再次运行裁剪。
|
||
- 裁剪会先对过大的工具结果进行软裁剪，如仍有需要，再对更旧的工具结果执行硬清除。
|
||
|
||
**软裁剪**保留开头和结尾，并在中间插入 `...`。
|
||
|
||
**硬清除**用占位符替换整个工具结果。
|
||
|
||
说明：
|
||
|
||
- 图像块永远不会被裁剪/清除。
|
||
- 比例是基于字符的（近似），不是精确 token 数。
|
||
- 如果 assistant 消息少于 `keepLastAssistants`，则跳过裁剪。
|
||
|
||
</Accordion>
|
||
|
||
行为细节见 [Session Pruning](/concepts/session-pruning)。
|
||
|
||
### 分块流式传输
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
blockStreamingDefault: "off", // on | off
|
||
blockStreamingBreak: "text_end", // text_end | message_end
|
||
blockStreamingChunk: { minChars: 800, maxChars: 1200 },
|
||
blockStreamingCoalesce: { idleMs: 1000 },
|
||
humanDelay: { mode: "natural" }, // off | natural | custom（使用 minMs/maxMs）
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。
|
||
- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及按账户变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
|
||
- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。
|
||
|
||
行为和分块细节见 [Streaming](/concepts/streaming)。
|
||
|
||
### 输入指示器
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
typingMode: "instant", // never | instant | thinking | message
|
||
typingIntervalSeconds: 6,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 默认值：私聊/被提及时为 `instant`，未提及的群聊中为 `message`。
|
||
- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。
|
||
|
||
见 [Typing Indicators](/concepts/typing-indicators)。
|
||
|
||
### `agents.defaults.sandbox`
|
||
|
||
嵌入式智能体的可选沙箱隔离。完整指南见 [沙箱隔离](/gateway/sandboxing)。
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
sandbox: {
|
||
mode: "non-main", // off | non-main | all
|
||
backend: "docker", // docker | ssh | openshell
|
||
scope: "agent", // session | agent | shared
|
||
workspaceAccess: "none", // none | ro | rw
|
||
workspaceRoot: "~/.openclaw/sandboxes",
|
||
docker: {
|
||
image: "openclaw-sandbox:bookworm-slim",
|
||
containerPrefix: "openclaw-sbx-",
|
||
workdir: "/workspace",
|
||
readOnlyRoot: true,
|
||
tmpfs: ["/tmp", "/var/tmp", "/run"],
|
||
network: "none",
|
||
user: "1000:1000",
|
||
capDrop: ["ALL"],
|
||
env: { LANG: "C.UTF-8" },
|
||
setupCommand: "apt-get update && apt-get install -y git curl jq",
|
||
pidsLimit: 256,
|
||
memory: "1g",
|
||
memorySwap: "2g",
|
||
cpus: 1,
|
||
ulimits: {
|
||
nofile: { soft: 1024, hard: 2048 },
|
||
nproc: 256,
|
||
},
|
||
seccompProfile: "/path/to/seccomp.json",
|
||
apparmorProfile: "openclaw-sandbox",
|
||
dns: ["1.1.1.1", "8.8.8.8"],
|
||
extraHosts: ["internal.service:10.0.0.5"],
|
||
binds: ["/home/user/source:/source:rw"],
|
||
},
|
||
ssh: {
|
||
target: "user@gateway-host:22",
|
||
command: "ssh",
|
||
workspaceRoot: "/tmp/openclaw-sandboxes",
|
||
strictHostKeyChecking: true,
|
||
updateHostKeys: true,
|
||
identityFile: "~/.ssh/id_ed25519",
|
||
certificateFile: "~/.ssh/id_ed25519-cert.pub",
|
||
knownHostsFile: "~/.ssh/known_hosts",
|
||
// 也支持 SecretRef / 内联内容：
|
||
// identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
|
||
// certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
|
||
// knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
|
||
},
|
||
browser: {
|
||
enabled: false,
|
||
image: "openclaw-sandbox-browser:bookworm-slim",
|
||
network: "openclaw-sandbox-browser",
|
||
cdpPort: 9222,
|
||
cdpSourceRange: "172.21.0.1/32",
|
||
vncPort: 5900,
|
||
noVncPort: 6080,
|
||
headless: false,
|
||
enableNoVnc: true,
|
||
allowHostControl: false,
|
||
autoStart: true,
|
||
autoStartTimeoutMs: 12000,
|
||
},
|
||
prune: {
|
||
idleHours: 24,
|
||
maxAgeDays: 7,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
tools: {
|
||
sandbox: {
|
||
tools: {
|
||
allow: [
|
||
"exec",
|
||
"process",
|
||
"read",
|
||
"write",
|
||
"edit",
|
||
"apply_patch",
|
||
"sessions_list",
|
||
"sessions_history",
|
||
"sessions_send",
|
||
"sessions_spawn",
|
||
"session_status",
|
||
],
|
||
deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
<Accordion title="沙箱详情">
|
||
|
||
**后端：**
|
||
|
||
- `docker`：本地 Docker 运行时（默认）
|
||
- `ssh`：通用的 SSH 远程运行时
|
||
- `openshell`：OpenShell 运行时
|
||
|
||
选择 `backend: "openshell"` 时，运行时特定设置会移动到
|
||
`plugins.entries.openshell.config`。
|
||
|
||
**SSH 后端配置：**
|
||
|
||
- `target`：`user@host[:port]` 形式的 SSH 目标
|
||
- `command`：SSH 客户端命令（默认：`ssh`）
|
||
- `workspaceRoot`：按作用域工作区使用的远程绝对根目录
|
||
- `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件
|
||
- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其物化为临时文件
|
||
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关
|
||
|
||
**SSH 认证优先级：**
|
||
|
||
- `identityData` 优先于 `identityFile`
|
||
- `certificateData` 优先于 `certificateFile`
|
||
- `knownHostsData` 优先于 `knownHostsFile`
|
||
- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从活动 secrets 运行时快照中解析
|
||
|
||
**SSH 后端行为：**
|
||
|
||
- 在创建或重建后，对远程工作区进行一次种子初始化
|
||
- 之后保持远程 SSH 工作区为规范副本
|
||
- 通过 SSH 路由 `exec`、文件工具和媒体路径
|
||
- 不会自动将远程更改同步回主机
|
||
- 不支持沙箱浏览器容器
|
||
|
||
**工作区访问：**
|
||
|
||
- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域划分的沙箱工作区
|
||
- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent`
|
||
- `rw`：智能体工作区以读写方式挂载到 `/workspace`
|
||
|
||
**作用域：**
|
||
|
||
- `session`：每个会话一个容器 + 工作区
|
||
- `agent`：每个智能体一个容器 + 工作区（默认）
|
||
- `shared`：共享容器和工作区（无跨会话隔离）
|
||
|
||
**OpenShell 插件配置：**
|
||
|
||
```json5
|
||
{
|
||
plugins: {
|
||
entries: {
|
||
openshell: {
|
||
enabled: true,
|
||
config: {
|
||
mode: "mirror", // mirror | remote
|
||
from: "openclaw",
|
||
remoteWorkspaceDir: "/sandbox",
|
||
remoteAgentWorkspaceDir: "/agent",
|
||
gateway: "lab", // 可选
|
||
gatewayEndpoint: "https://lab.example", // 可选
|
||
policy: "strict", // 可选的 OpenShell policy id
|
||
providers: ["openai"], // 可选
|
||
autoProviders: true,
|
||
timeoutSeconds: 120,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
**OpenShell 模式：**
|
||
|
||
- `mirror`：执行前从本地为远程植入种子，执行后同步回本地；本地工作区保持为规范副本
|
||
- `remote`：在创建沙箱时只为远程植入一次种子，之后保持远程工作区为规范副本
|
||
|
||
在 `remote` 模式下，在 OpenClaw 外部对主机本地所做的编辑，不会在种子步骤后自动同步进沙箱。
|
||
传输层是通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期以及可选的镜像同步。
|
||
|
||
**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统以及 root 用户。
|
||
|
||
**容器默认使用 `network: "none"`** ——如果智能体需要出站访问，请设为 `"bridge"`（或自定义 bridge 网络）。
|
||
默认会阻止 `"host"`。除非你显式设置
|
||
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急模式），否则默认也会阻止 `"container:<id>"`。
|
||
|
||
**入站附件** 会暂存到活动工作区中的 `media/inbound/*`。
|
||
|
||
**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。
|
||
|
||
**沙箱浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示中。不要求在 `openclaw.json` 中启用 `browser.enabled`。
|
||
noVNC 观察者访问默认使用 VNC 身份验证，OpenClaw 会发出一个短期有效的 token URL（而不是在共享 URL 中暴露密码）。
|
||
|
||
- `allowHostControl: false`（默认）会阻止沙箱会话指向主机浏览器。
|
||
- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连接时，才设为 `bridge`。
|
||
- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。
|
||
- `sandbox.browser.binds` 仅将额外主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
|
||
- 启动默认值定义于 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优：
|
||
- `--remote-debugging-address=127.0.0.1`
|
||
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
|
||
- `--user-data-dir=${HOME}/.chrome`
|
||
- `--no-first-run`
|
||
- `--no-default-browser-check`
|
||
- `--disable-3d-apis`
|
||
- `--disable-gpu`
|
||
- `--disable-software-rasterizer`
|
||
- `--disable-dev-shm-usage`
|
||
- `--disable-background-networking`
|
||
- `--disable-features=TranslateUI`
|
||
- `--disable-breakpad`
|
||
- `--disable-crash-reporter`
|
||
- `--renderer-process-limit=2`
|
||
- `--no-zygote`
|
||
- `--metrics-recording-only`
|
||
- `--disable-extensions`（默认启用）
|
||
- `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`
|
||
默认启用，如果 WebGL/3D 使用场景需要，可通过
|
||
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。
|
||
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展，如果你的工作流
|
||
依赖它们。
|
||
- `--renderer-process-limit=2` 可通过
|
||
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 更改；设为 `0` 将使用 Chromium 的
|
||
默认进程上限。
|
||
- 若启用了 `noSandbox`，还会额外加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。
|
||
- 默认值是容器镜像的基线；若要更改容器默认值，请使用自定义浏览器镜像及自定义
|
||
entrypoint。
|
||
|
||
</Accordion>
|
||
|
||
浏览器沙箱隔离和 `sandbox.docker.binds` 当前仅支持 Docker。
|
||
|
||
构建镜像：
|
||
|
||
```bash
|
||
scripts/sandbox-setup.sh # 主沙箱镜像
|
||
scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
|
||
```
|
||
|
||
### `agents.list`（按智能体覆盖）
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
list: [
|
||
{
|
||
id: "main",
|
||
default: true,
|
||
name: "Main Agent",
|
||
workspace: "~/.openclaw/workspace",
|
||
agentDir: "~/.openclaw/agents/main/agent",
|
||
model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks }
|
||
params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params
|
||
identity: {
|
||
name: "Samantha",
|
||
theme: "helpful sloth",
|
||
emoji: "🦥",
|
||
avatar: "avatars/samantha.png",
|
||
},
|
||
groupChat: { mentionPatterns: ["@openclaw"] },
|
||
sandbox: { mode: "off" },
|
||
runtime: {
|
||
type: "acp",
|
||
acp: {
|
||
agent: "codex",
|
||
backend: "acpx",
|
||
mode: "persistent",
|
||
cwd: "/workspace/openclaw",
|
||
},
|
||
},
|
||
subagents: { allowAgents: ["*"] },
|
||
tools: {
|
||
profile: "coding",
|
||
allow: ["browser"],
|
||
deny: ["canvas"],
|
||
elevated: { enabled: true },
|
||
},
|
||
},
|
||
],
|
||
},
|
||
}
|
||
```
|
||
|
||
- `id`：稳定的智能体 ID（必填）。
|
||
- `default`：若设置了多个，则第一个生效（会记录警告）。若一个都未设，则列表第一项为默认。
|
||
- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局故障切换）。仅覆盖 `primary` 的 Cron 作业仍会继承默认故障切换，除非你设置 `fallbacks: []`。
|
||
- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中所选模型条目之上。用于为智能体添加特定覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。
|
||
- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，可使用 `type: "acp"`，并在 `runtime.acp` 中设置默认值（`agent`、`backend`、`mode`、`cwd`）。
|
||
- `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。
|
||
- `identity` 会派生默认值：从 `emoji` 派生 `ackReaction`，从 `name`/`emoji` 派生 `mentionPatterns`。
|
||
- `subagents.allowAgents`：`sessions_spawn` 的智能体 ID allowlist（`["*"]` = 任意；默认：仅同一智能体）。
|
||
- 沙箱继承保护：若请求方会话处于沙箱中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。
|
||
|
||
---
|
||
|
||
## 多智能体路由
|
||
|
||
在一个 Gateway 网关中运行多个隔离的智能体。见 [Multi-Agent](/concepts/multi-agent)。
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
list: [
|
||
{ id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
|
||
{ id: "work", workspace: "~/.openclaw/workspace-work" },
|
||
],
|
||
},
|
||
bindings: [
|
||
{ agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
|
||
{ agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
|
||
],
|
||
}
|
||
```
|
||
|
||
### 绑定匹配字段
|
||
|
||
- `type`（可选）：普通路由使用 `route`（缺失时默认为 route），持久化 ACP 对话绑定使用 `acp`。
|
||
- `match.channel`（必填）
|
||
- `match.accountId`（可选；`*` = 任意账户；省略 = 默认账户）
|
||
- `match.peer`（可选；`{ kind: direct|group|channel, id }`）
|
||
- `match.guildId` / `match.teamId`（可选；渠道特定）
|
||
- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }`
|
||
|
||
**确定性匹配顺序：**
|
||
|
||
1. `match.peer`
|
||
2. `match.guildId`
|
||
3. `match.teamId`
|
||
4. `match.accountId`（精确匹配，无 peer/guild/team）
|
||
5. `match.accountId: "*"`（全渠道）
|
||
6. 默认智能体
|
||
|
||
在每一层内，第一个匹配的 `bindings` 条目胜出。
|
||
|
||
对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + account + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。
|
||
|
||
### 按智能体的访问配置
|
||
|
||
<Accordion title="完全访问（无沙箱）">
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
list: [
|
||
{
|
||
id: "personal",
|
||
workspace: "~/.openclaw/workspace-personal",
|
||
sandbox: { mode: "off" },
|
||
},
|
||
],
|
||
},
|
||
}
|
||
```
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="只读工具 + 工作区">
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
list: [
|
||
{
|
||
id: "family",
|
||
workspace: "~/.openclaw/workspace-family",
|
||
sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
|
||
tools: {
|
||
allow: [
|
||
"read",
|
||
"sessions_list",
|
||
"sessions_history",
|
||
"sessions_send",
|
||
"sessions_spawn",
|
||
"session_status",
|
||
],
|
||
deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
|
||
},
|
||
},
|
||
],
|
||
},
|
||
}
|
||
```
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="无文件系统访问（仅消息）">
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
list: [
|
||
{
|
||
id: "public",
|
||
workspace: "~/.openclaw/workspace-public",
|
||
sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
|
||
tools: {
|
||
allow: [
|
||
"sessions_list",
|
||
"sessions_history",
|
||
"sessions_send",
|
||
"sessions_spawn",
|
||
"session_status",
|
||
"whatsapp",
|
||
"telegram",
|
||
"slack",
|
||
"discord",
|
||
"gateway",
|
||
],
|
||
deny: [
|
||
"read",
|
||
"write",
|
||
"edit",
|
||
"apply_patch",
|
||
"exec",
|
||
"process",
|
||
"browser",
|
||
"canvas",
|
||
"nodes",
|
||
"cron",
|
||
"gateway",
|
||
"image",
|
||
],
|
||
},
|
||
},
|
||
],
|
||
},
|
||
}
|
||
```
|
||
|
||
</Accordion>
|
||
|
||
优先级细节见 [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools)。
|
||
|
||
---
|
||
|
||
## 会话
|
||
|
||
```json5
|
||
{
|
||
session: {
|
||
scope: "per-sender",
|
||
dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
|
||
identityLinks: {
|
||
alice: ["telegram:123456789", "discord:987654321012345678"],
|
||
},
|
||
reset: {
|
||
mode: "daily", // daily | idle
|
||
atHour: 4,
|
||
idleMinutes: 60,
|
||
},
|
||
resetByType: {
|
||
thread: { mode: "daily", atHour: 4 },
|
||
direct: { mode: "idle", idleMinutes: 240 },
|
||
group: { mode: "idle", idleMinutes: 120 },
|
||
},
|
||
resetTriggers: ["/new", "/reset"],
|
||
store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
|
||
parentForkMaxTokens: 100000, // 超过此 token 数则跳过父线程 fork（0 表示禁用）
|
||
maintenance: {
|
||
mode: "warn", // warn | enforce
|
||
pruneAfter: "30d",
|
||
maxEntries: 500,
|
||
rotateBytes: "10mb",
|
||
resetArchiveRetention: "30d", // 时长或 false
|
||
maxDiskBytes: "500mb", // 可选硬预算
|
||
highWaterBytes: "400mb", // 可选清理目标
|
||
},
|
||
threadBindings: {
|
||
enabled: true,
|
||
idleHours: 24, // 默认不活动自动取消聚焦时长（小时，`0` 表示禁用）
|
||
maxAgeHours: 0, // 默认硬性最大年龄（小时，`0` 表示禁用）
|
||
},
|
||
mainKey: "main", // 旧字段（运行时始终使用 "main"）
|
||
agentToAgent: { maxPingPongTurns: 5 },
|
||
sendPolicy: {
|
||
rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
|
||
default: "allow",
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
<Accordion title="会话字段详情">
|
||
|
||
- **`dmScope`**：私信如何分组。
|
||
- `main`：所有私信共享主会话。
|
||
- `per-peer`：按发送者 ID 跨渠道隔离。
|
||
- `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
|
||
- `per-account-channel-peer`：按账户 + 渠道 + 发送者隔离（推荐用于多账户）。
|
||
- **`identityLinks`**：将规范 ID 映射到带提供商前缀的 peer，用于跨渠道共享会话。
|
||
- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。如果两者都配置，谁先到期谁生效。
|
||
- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍接受为 `direct` 的别名。
|
||
- **`parentForkMaxTokens`**：创建分叉线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。
|
||
- 如果父会话 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父会话的记录历史。
|
||
- 设为 `0` 可禁用此保护，并始终允许父会话分叉。
|
||
- **`mainKey`**：旧字段。运行时现在始终为主直聊桶使用 `"main"`。
|
||
- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 仍为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 生效。
|
||
- **`maintenance`**：会话存储清理 + 保留控制。
|
||
- `mode`：`warn` 仅发出警告；`enforce` 应用清理。
|
||
- `pruneAfter`：过期条目的年龄阈值（默认 `30d`）。
|
||
- `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。
|
||
- `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。
|
||
- `resetArchiveRetention`：`*.reset.<timestamp>` 会话记录归档的保留期限。默认跟随 `pruneAfter`；设为 `false` 可禁用。
|
||
- `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的工件/会话。
|
||
- `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。
|
||
- **`threadBindings`**：线程绑定会话功能的全局默认值。
|
||
- `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
|
||
- `idleHours`：默认不活动自动取消聚焦时长（小时，`0` 表示禁用；提供商可覆盖）
|
||
- `maxAgeHours`：默认硬性最大年龄（小时，`0` 表示禁用；提供商可覆盖）
|
||
|
||
</Accordion>
|
||
|
||
---
|
||
|
||
## 消息
|
||
|
||
```json5
|
||
{
|
||
messages: {
|
||
responsePrefix: "🦞", // 或 "auto"
|
||
ackReaction: "👀",
|
||
ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
|
||
removeAckAfterReply: false,
|
||
queue: {
|
||
mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
|
||
debounceMs: 1000,
|
||
cap: 20,
|
||
drop: "summarize", // old | new | summarize
|
||
byChannel: {
|
||
whatsapp: "collect",
|
||
telegram: "collect",
|
||
},
|
||
},
|
||
inbound: {
|
||
debounceMs: 2000, // 0 表示禁用
|
||
byChannel: {
|
||
whatsapp: 5000,
|
||
slack: 1500,
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
### 回复前缀
|
||
|
||
按渠道/按账户覆盖：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
|
||
|
||
解析顺序（最具体者优先）：账户 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。
|
||
|
||
**模板变量：**
|
||
|
||
| Variable | Description | Example |
|
||
| ----------------- | ------------------ | --------------------------- |
|
||
| `{model}` | 短模型名 | `claude-opus-4-6` |
|
||
| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
|
||
| `{provider}` | 提供商名称 | `anthropic` |
|
||
| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` |
|
||
| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） |
|
||
|
||
变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。
|
||
|
||
### 确认反应
|
||
|
||
- 默认取活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。
|
||
- 按渠道覆盖：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
|
||
- 解析顺序：账户 → 渠道 → `messages.ackReaction` → identity 回退。
|
||
- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。
|
||
- `removeAckAfterReply`：回复后移除确认反应（仅 Slack/Discord/Telegram/Google Chat）。
|
||
|
||
### 入站防抖
|
||
|
||
将同一发送者快速连续发送的纯文本消息合并为一次智能体轮次。媒体/附件会立即冲刷。控制命令会绕过防抖。
|
||
|
||
### TTS（文本转语音）
|
||
|
||
```json5
|
||
{
|
||
messages: {
|
||
tts: {
|
||
auto: "always", // off | always | inbound | tagged
|
||
mode: "final", // final | all
|
||
provider: "elevenlabs",
|
||
summaryModel: "openai/gpt-4.1-mini",
|
||
modelOverrides: { enabled: true },
|
||
maxTextLength: 4000,
|
||
timeoutMs: 30000,
|
||
prefsPath: "~/.openclaw/settings/tts.json",
|
||
elevenlabs: {
|
||
apiKey: "elevenlabs_api_key",
|
||
baseUrl: "https://api.elevenlabs.io",
|
||
voiceId: "voice_id",
|
||
modelId: "eleven_multilingual_v2",
|
||
seed: 42,
|
||
applyTextNormalization: "auto",
|
||
languageCode: "en",
|
||
voiceSettings: {
|
||
stability: 0.5,
|
||
similarityBoost: 0.75,
|
||
style: 0.0,
|
||
useSpeakerBoost: true,
|
||
speed: 1.0,
|
||
},
|
||
},
|
||
openai: {
|
||
apiKey: "openai_api_key",
|
||
baseUrl: "https://api.openai.com/v1",
|
||
model: "gpt-4o-mini-tts",
|
||
voice: "alloy",
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `auto` 控制自动 TTS。`/tts off|always|inbound|tagged` 可按会话覆盖。
|
||
- `summaryModel` 会覆盖 `agents.defaults.model.primary` 用于自动摘要。
|
||
- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认是 `false`（需显式选择启用）。
|
||
- API 密钥回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
|
||
- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序是配置、然后 `OPENAI_TTS_BASE_URL`、再然后 `https://api.openai.com/v1`。
|
||
- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。
|
||
|
||
---
|
||
|
||
## Talk
|
||
|
||
Talk 模式的默认值（macOS/iOS/Android）。
|
||
|
||
```json5
|
||
{
|
||
talk: {
|
||
voiceId: "elevenlabs_voice_id",
|
||
voiceAliases: {
|
||
Clawd: "EXAVITQu4vr4xnSDxMaL",
|
||
Roger: "CwhRBWXzGAHq8TQ4Fs17",
|
||
},
|
||
modelId: "eleven_v3",
|
||
outputFormat: "mp3_44100_128",
|
||
apiKey: "elevenlabs_api_key",
|
||
silenceTimeoutMs: 1500,
|
||
interruptOnSpeech: true,
|
||
},
|
||
}
|
||
```
|
||
|
||
- 语音 ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
|
||
- `apiKey` 和 `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。
|
||
- 仅在未配置 Talk API key 时，才会回退到 `ELEVENLABS_API_KEY`。
|
||
- `voiceAliases` 让 Talk 指令可以使用友好的名称。
|
||
- `silenceTimeoutMs` 控制 Talk 模式在用户停止说话后等待多久才发送转录。未设置时使用平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。
|
||
|
||
---
|
||
|
||
## 工具
|
||
|
||
### 工具配置文件
|
||
|
||
`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础 allowlist：
|
||
|
||
本地新手引导会在未设置时，把新的本地配置默认设为 `tools.profile: "coding"`（现有显式配置文件会保留）。
|
||
|
||
| Profile | Includes |
|
||
| ----------- | ----------------------------------------------------------------------------------------- |
|
||
| `minimal` | 仅 `session_status` |
|
||
| `coding` | `group:fs`、`group:runtime`、`group:sessions`、`group:memory`、`image` |
|
||
| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` |
|
||
| `full` | 不限制（等同于未设置） |
|
||
|
||
### 工具组
|
||
|
||
| Group | Tools |
|
||
| ------------------ | ---------------------------------------------------------------------------------------- |
|
||
| `group:runtime` | `exec`、`process`（`bash` 可作为 `exec` 的别名） |
|
||
| `group:fs` | `read`、`write`、`edit`、`apply_patch` |
|
||
| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`session_status` |
|
||
| `group:memory` | `memory_search`、`memory_get` |
|
||
| `group:web` | `web_search`、`web_fetch` |
|
||
| `group:ui` | `browser`、`canvas` |
|
||
| `group:automation` | `cron`、`gateway` |
|
||
| `group:messaging` | `message` |
|
||
| `group:nodes` | `nodes` |
|
||
| `group:openclaw` | 所有内置工具（不含提供商插件） |
|
||
|
||
### `tools.allow` / `tools.deny`
|
||
|
||
全局工具 allow/deny 策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭，也会应用。
|
||
|
||
```json5
|
||
{
|
||
tools: { deny: ["browser", "canvas"] },
|
||
}
|
||
```
|
||
|
||
### `tools.byProvider`
|
||
|
||
进一步限制特定提供商或模型的工具。顺序：基础配置文件 → 提供商配置文件 → allow/deny。
|
||
|
||
```json5
|
||
{
|
||
tools: {
|
||
profile: "coding",
|
||
byProvider: {
|
||
"google-antigravity": { profile: "minimal" },
|
||
"openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
### `tools.elevated`
|
||
|
||
控制提升权限（主机）`exec` 访问：
|
||
|
||
```json5
|
||
{
|
||
tools: {
|
||
elevated: {
|
||
enabled: true,
|
||
allowFrom: {
|
||
whatsapp: ["+15555550123"],
|
||
discord: ["1234567890123", "987654321098765432"],
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。
|
||
- `/elevated on|off|ask|full` 会按会话保存状态；内联指令仅作用于单条消息。
|
||
- 提升权限的 `exec` 会在主机上运行，并绕过沙箱隔离。
|
||
|
||
### `tools.exec`
|
||
|
||
```json5
|
||
{
|
||
tools: {
|
||
exec: {
|
||
backgroundMs: 10000,
|
||
timeoutSec: 1800,
|
||
cleanupMs: 1800000,
|
||
notifyOnExit: true,
|
||
notifyOnExitEmptySuccess: false,
|
||
applyPatch: {
|
||
enabled: false,
|
||
allowModels: ["gpt-5.2"],
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
### `tools.loopDetection`
|
||
|
||
工具循环安全检查**默认禁用**。设置 `enabled: true` 可启用检测。
|
||
可在全局 `tools.loopDetection` 中定义设置，并在 `agents.list[].tools.loopDetection` 中按智能体覆盖。
|
||
|
||
```json5
|
||
{
|
||
tools: {
|
||
loopDetection: {
|
||
enabled: true,
|
||
historySize: 30,
|
||
warningThreshold: 10,
|
||
criticalThreshold: 20,
|
||
globalCircuitBreakerThreshold: 30,
|
||
detectors: {
|
||
genericRepeat: true,
|
||
knownPollNoProgress: true,
|
||
pingPong: true,
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `historySize`：为循环分析保留的最大工具调用历史。
|
||
- `warningThreshold`：用于发出警告的重复无进展模式阈值。
|
||
- `criticalThreshold`：用于阻止严重循环的更高重复阈值。
|
||
- `globalCircuitBreakerThreshold`：对任何无进展运行的硬性停止阈值。
|
||
- `detectors.genericRepeat`：对重复的相同工具/相同参数调用发出警告。
|
||
- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。
|
||
- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。
|
||
- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，校验会失败。
|
||
|
||
### `tools.web`
|
||
|
||
```json5
|
||
{
|
||
tools: {
|
||
web: {
|
||
search: {
|
||
enabled: true,
|
||
apiKey: "brave_api_key", // 或 BRAVE_API_KEY 环境变量
|
||
maxResults: 5,
|
||
timeoutSeconds: 30,
|
||
cacheTtlMinutes: 15,
|
||
},
|
||
fetch: {
|
||
enabled: true,
|
||
maxChars: 50000,
|
||
maxCharsCap: 50000,
|
||
timeoutSeconds: 30,
|
||
cacheTtlMinutes: 15,
|
||
userAgent: "custom-ua",
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
### `tools.media`
|
||
|
||
配置入站媒体理解（图像/音频/视频）：
|
||
|
||
```json5
|
||
{
|
||
tools: {
|
||
media: {
|
||
concurrency: 2,
|
||
audio: {
|
||
enabled: true,
|
||
maxBytes: 20971520,
|
||
scope: {
|
||
default: "deny",
|
||
rules: [{ action: "allow", match: { chatType: "direct" } }],
|
||
},
|
||
models: [
|
||
{ provider: "openai", model: "gpt-4o-mini-transcribe" },
|
||
{ type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
|
||
],
|
||
},
|
||
video: {
|
||
enabled: true,
|
||
maxBytes: 52428800,
|
||
models: [{ provider: "google", model: "gemini-3-flash-preview" }],
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
<Accordion title="媒体模型条目字段">
|
||
|
||
**提供商条目**（`type: "provider"` 或省略）：
|
||
|
||
- `provider`：API 提供商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等）
|
||
- `model`：模型 ID 覆盖
|
||
- `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择
|
||
|
||
**CLI 条目**（`type: "cli"`）：
|
||
|
||
- `command`：要运行的可执行文件
|
||
- `args`：模板化参数（支持 `{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` 等）
|
||
|
||
**通用字段：**
|
||
|
||
- `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → 图像，`google` → 图像+音频+视频，`groq` → 音频。
|
||
- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。
|
||
- 失败时会回退到下一个条目。
|
||
|
||
提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。
|
||
|
||
</Accordion>
|
||
|
||
### `tools.agentToAgent`
|
||
|
||
```json5
|
||
{
|
||
tools: {
|
||
agentToAgent: {
|
||
enabled: false,
|
||
allow: ["home", "work"],
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
### `tools.sessions`
|
||
|
||
控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以定位哪些会话。
|
||
|
||
默认值：`tree`（当前会话 + 由其派生的会话，例如子智能体）。
|
||
|
||
```json5
|
||
{
|
||
tools: {
|
||
sessions: {
|
||
// "self" | "tree" | "agent" | "all"
|
||
visibility: "tree",
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `self`：仅当前会话键。
|
||
- `tree`：当前会话 + 由当前会话派生的会话（子智能体）。
|
||
- `agent`：属于当前智能体 ID 的任意会话（如果你在相同智能体 ID 下运行按发送者划分的会话，可能包含其他用户）。
|
||
- `all`：任意会话。跨智能体定位仍需要 `tools.agentToAgent`。
|
||
- 沙箱钳制：当当前会话处于沙箱中且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。
|
||
|
||
### `tools.sessions_spawn`
|
||
|
||
控制 `sessions_spawn` 的内联附件支持。
|
||
|
||
```json5
|
||
{
|
||
tools: {
|
||
sessions_spawn: {
|
||
attachments: {
|
||
enabled: false, // 选择性启用：设为 true 以允许内联文件附件
|
||
maxTotalBytes: 5242880, // 所有文件合计 5 MB
|
||
maxFiles: 50,
|
||
maxFileBytes: 1048576, // 每个文件 1 MB
|
||
retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。
|
||
- 文件会被物化到子工作区中的 `.openclaw/attachments/<uuid>/`，并附带一个 `.manifest.json`。
|
||
- 附件内容会自动从会话记录持久化中脱敏。
|
||
- Base64 输入会通过严格的字母表/填充检查和解码前大小保护进行校验。
|
||
- 文件权限为目录 `0700`、文件 `0600`。
|
||
- 清理遵循 `cleanup` 策略：`delete` 总会删除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。
|
||
|
||
### `tools.subagents`
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
subagents: {
|
||
model: "minimax/MiniMax-M2.5",
|
||
maxConcurrent: 1,
|
||
runTimeoutSeconds: 900,
|
||
archiveAfterMinutes: 60,
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `model`：派生子智能体的默认模型。如果省略，子智能体会继承调用方的模型。
|
||
- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。
|
||
- 每个子智能体的工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。
|
||
|
||
---
|
||
|
||
## 自定义提供商和 base URL
|
||
|
||
OpenClaw 使用 pi-coding-agent 模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents/<agentId>/agent/models.json` 添加自定义提供商。
|
||
|
||
```json5
|
||
{
|
||
models: {
|
||
mode: "merge", // merge（默认）| replace
|
||
providers: {
|
||
"custom-proxy": {
|
||
baseUrl: "http://localhost:4000/v1",
|
||
apiKey: "LITELLM_KEY",
|
||
api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
|
||
models: [
|
||
{
|
||
id: "llama-3.1-8b",
|
||
name: "Llama 3.1 8B",
|
||
reasoning: false,
|
||
input: ["text"],
|
||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||
contextWindow: 128000,
|
||
maxTokens: 32000,
|
||
},
|
||
],
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 对自定义认证需求可使用 `authHeader: true` + `headers`。
|
||
- 使用 `OPENCLAW_AGENT_DIR`（或 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。
|
||
- 对匹配的 provider ID，合并优先级如下：
|
||
- 非空的智能体 `models.json` `baseUrl` 优先。
|
||
- 非空的智能体 `apiKey` 仅在该提供商未由当前配置/auth-profile 上下文中的 SecretRef 管理时优先。
|
||
- 由 SecretRef 管理的提供商 `apiKey` 会从源标记（环境变量引用为 `ENV_VAR_NAME`，file/exec 引用为 `secretref-managed`）刷新，而不是持久化已解析的密钥。
|
||
- 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用为 `secretref-env:ENV_VAR_NAME`，file/exec 引用为 `secretref-managed`）。
|
||
- 为空或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
|
||
- 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值与隐式目录值之间取较大者。
|
||
- 当你希望配置完全重写 `models.json` 时，请使用 `models.mode: "replace"`。
|
||
- 标记持久化以源为准：写入的标记来自活动源配置快照（解析前），而不是解析后的运行时密钥值。
|
||
|
||
### 提供商字段详情
|
||
|
||
- `models.mode`：提供商目录行为（`merge` 或 `replace`）。
|
||
- `models.providers`：以提供商 ID 为键的自定义提供商映射。
|
||
- `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。
|
||
- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。
|
||
- `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。
|
||
- `models.providers.*.injectNumCtxForOpenAICompat`：对 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求（默认：`true`）。
|
||
- `models.providers.*.authHeader`：在需要时强制通过 `Authorization` 头传输凭证。
|
||
- `models.providers.*.baseUrl`：上游 API base URL。
|
||
- `models.providers.*.headers`：用于代理/租户路由的额外静态 header。
|
||
- `models.providers.*.models`：显式的提供商模型目录条目。
|
||
- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选的兼容性提示。对 `api: "openai-completions"` 且非空、非原生 `baseUrl`（主机不是 `api.openai.com`）的情况，OpenClaw 会在运行时将其强制设为 `false`。空或省略的 `baseUrl` 会保留默认 OpenAI 行为。
|
||
- `models.bedrockDiscovery`：Bedrock 自动发现设置根。
|
||
- `models.bedrockDiscovery.enabled`：开启/关闭发现轮询。
|
||
- `models.bedrockDiscovery.region`：发现使用的 AWS 区域。
|
||
- `models.bedrockDiscovery.providerFilter`：用于定向发现的可选 provider-id 过滤器。
|
||
- `models.bedrockDiscovery.refreshInterval`：发现刷新的轮询间隔。
|
||
- `models.bedrockDiscovery.defaultContextWindow`：发现模型的回退上下文窗口。
|
||
- `models.bedrockDiscovery.defaultMaxTokens`：发现模型的回退最大输出 token 数。
|
||
|
||
### 提供商示例
|
||
|
||
<Accordion title="Cerebras（GLM 4.6 / 4.7）">
|
||
|
||
```json5
|
||
{
|
||
env: { CEREBRAS_API_KEY: "sk-..." },
|
||
agents: {
|
||
defaults: {
|
||
model: {
|
||
primary: "cerebras/zai-glm-4.7",
|
||
fallbacks: ["cerebras/zai-glm-4.6"],
|
||
},
|
||
models: {
|
||
"cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
|
||
"cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" },
|
||
},
|
||
},
|
||
},
|
||
models: {
|
||
mode: "merge",
|
||
providers: {
|
||
cerebras: {
|
||
baseUrl: "https://api.cerebras.ai/v1",
|
||
apiKey: "${CEREBRAS_API_KEY}",
|
||
api: "openai-completions",
|
||
models: [
|
||
{ id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
|
||
{ id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
|
||
],
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
对 Cerebras 使用 `cerebras/zai-glm-4.7`；对 Z.AI 直连使用 `zai/glm-4.7`。
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="OpenCode">
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
model: { primary: "opencode/claude-opus-4-6" },
|
||
models: { "opencode/claude-opus-4-6": { alias: "Opus" } },
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。Zen 目录使用 `opencode/...` 引用，Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Z.AI（GLM-4.7）">
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
model: { primary: "zai/glm-4.7" },
|
||
models: { "zai/glm-4.7": {} },
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。
|
||
|
||
- 通用端点：`https://api.z.ai/api/paas/v4`
|
||
- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4`
|
||
- 对于通用端点，请定义一个带有 base URL 覆盖的自定义提供商。
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Moonshot AI（Kimi）">
|
||
|
||
```json5
|
||
{
|
||
env: { MOONSHOT_API_KEY: "sk-..." },
|
||
agents: {
|
||
defaults: {
|
||
model: { primary: "moonshot/kimi-k2.5" },
|
||
models: { "moonshot/kimi-k2.5": { alias: "Kimi K2.5" } },
|
||
},
|
||
},
|
||
models: {
|
||
mode: "merge",
|
||
providers: {
|
||
moonshot: {
|
||
baseUrl: "https://api.moonshot.ai/v1",
|
||
apiKey: "${MOONSHOT_API_KEY}",
|
||
api: "openai-completions",
|
||
models: [
|
||
{
|
||
id: "kimi-k2.5",
|
||
name: "Kimi K2.5",
|
||
reasoning: false,
|
||
input: ["text"],
|
||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||
contextWindow: 256000,
|
||
maxTokens: 8192,
|
||
},
|
||
],
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
中国端点可使用：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Kimi Coding">
|
||
|
||
```json5
|
||
{
|
||
env: { KIMI_API_KEY: "sk-..." },
|
||
agents: {
|
||
defaults: {
|
||
model: { primary: "kimi-coding/k2p5" },
|
||
models: { "kimi-coding/k2p5": { alias: "Kimi K2.5" } },
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
兼容 Anthropic 的内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Synthetic（兼容 Anthropic）">
|
||
|
||
```json5
|
||
{
|
||
env: { SYNTHETIC_API_KEY: "sk-..." },
|
||
agents: {
|
||
defaults: {
|
||
model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
|
||
models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
|
||
},
|
||
},
|
||
models: {
|
||
mode: "merge",
|
||
providers: {
|
||
synthetic: {
|
||
baseUrl: "https://api.synthetic.new/anthropic",
|
||
apiKey: "${SYNTHETIC_API_KEY}",
|
||
api: "anthropic-messages",
|
||
models: [
|
||
{
|
||
id: "hf:MiniMaxAI/MiniMax-M2.5",
|
||
name: "MiniMax M2.5",
|
||
reasoning: true,
|
||
input: ["text"],
|
||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||
contextWindow: 192000,
|
||
maxTokens: 65536,
|
||
},
|
||
],
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
Base URL 不应包含 `/v1`（Anthropic 客户端会追加它）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="MiniMax M2.5（直连）">
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
model: { primary: "minimax/MiniMax-M2.5" },
|
||
models: {
|
||
"minimax/MiniMax-M2.5": { alias: "Minimax" },
|
||
},
|
||
},
|
||
},
|
||
models: {
|
||
mode: "merge",
|
||
providers: {
|
||
minimax: {
|
||
baseUrl: "https://api.minimax.io/anthropic",
|
||
apiKey: "${MINIMAX_API_KEY}",
|
||
api: "anthropic-messages",
|
||
models: [
|
||
{
|
||
id: "MiniMax-M2.5",
|
||
name: "MiniMax M2.5",
|
||
reasoning: true,
|
||
input: ["text"],
|
||
cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
|
||
contextWindow: 200000,
|
||
maxTokens: 8192,
|
||
},
|
||
],
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
设置 `MINIMAX_API_KEY`。快捷方式：`openclaw onboard --auth-choice minimax-api`。
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="本地模型（LM Studio）">
|
||
|
||
参见 [Local Models](/gateway/local-models)。简而言之：在强劲硬件上通过 LM Studio Responses API 运行 MiniMax M2.5；并保留托管模型合并，以便故障切换。
|
||
|
||
</Accordion>
|
||
|
||
---
|
||
|
||
## Skills
|
||
|
||
```json5
|
||
{
|
||
skills: {
|
||
allowBundled: ["gemini", "peekaboo"],
|
||
load: {
|
||
extraDirs: ["~/Projects/agent-scripts/skills"],
|
||
},
|
||
install: {
|
||
preferBrew: true,
|
||
nodeManager: "npm", // npm | pnpm | yarn
|
||
},
|
||
entries: {
|
||
"nano-banana-pro": {
|
||
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或明文字符串
|
||
env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
|
||
},
|
||
peekaboo: { enabled: true },
|
||
sag: { enabled: false },
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `allowBundled`：仅针对捆绑 Skills 的可选 allowlist（托管/工作区 Skills 不受影响）。
|
||
- `entries.<skillKey>.enabled: false`：即使某个技能已捆绑/已安装，也会禁用它。
|
||
- `entries.<skillKey>.apiKey`：针对声明主环境变量的技能提供的便捷字段（明文字符串或 SecretRef 对象）。
|
||
|
||
---
|
||
|
||
## 插件
|
||
|
||
```json5
|
||
{
|
||
plugins: {
|
||
enabled: true,
|
||
allow: ["voice-call"],
|
||
deny: [],
|
||
load: {
|
||
paths: ["~/Projects/oss/voice-call-extension"],
|
||
},
|
||
entries: {
|
||
"voice-call": {
|
||
enabled: true,
|
||
hooks: {
|
||
allowPromptInjection: false,
|
||
},
|
||
config: { provider: "twilio" },
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 从 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions` 以及 `plugins.load.paths` 加载。
|
||
- 设备发现同时接受原生 OpenClaw 插件、兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。
|
||
- **配置更改需要重启 Gateway 网关。**
|
||
- `allow`：可选 allowlist（仅加载列出的插件）。`deny` 优先。
|
||
- `plugins.entries.<id>.apiKey`：插件级 API key 便捷字段（插件支持时）。
|
||
- `plugins.entries.<id>.env`：插件作用域环境变量映射。
|
||
- `plugins.entries.<id>.hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改 prompt 的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hook 以及受支持 bundle 提供的 hook 目录。
|
||
- `plugins.entries.<id>.config`：插件定义的配置对象（如有可用原生 OpenClaw 插件 schema，则会校验）。
|
||
- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为净化后的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。
|
||
- `plugins.slots.memory`：选择活动记忆插件 ID，或设为 `"none"` 以禁用记忆插件。
|
||
- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；默认是 `"legacy"`，除非你安装并选择了其他引擎。
|
||
- `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。
|
||
- 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。
|
||
- 请将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。
|
||
|
||
见 [Plugins](/tools/plugin)。
|
||
|
||
---
|
||
|
||
## 浏览器
|
||
|
||
```json5
|
||
{
|
||
browser: {
|
||
enabled: true,
|
||
evaluateEnabled: true,
|
||
defaultProfile: "user",
|
||
ssrfPolicy: {
|
||
dangerouslyAllowPrivateNetwork: true, // 默认可信网络模式
|
||
// allowPrivateNetwork: true, // 旧别名
|
||
// hostnameAllowlist: ["*.example.com", "example.com"],
|
||
// allowedHostnames: ["localhost"],
|
||
},
|
||
profiles: {
|
||
openclaw: { cdpPort: 18800, color: "#FF4500" },
|
||
work: { cdpPort: 18801, color: "#0066CC" },
|
||
remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
|
||
},
|
||
color: "#FF4500",
|
||
// headless: false,
|
||
// noSandbox: false,
|
||
// extraArgs: [],
|
||
// relayBindHost: "0.0.0.0", // 仅在扩展 relay 需要跨命名空间可达时（例如 WSL2）
|
||
// executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
|
||
// attachOnly: false,
|
||
},
|
||
}
|
||
```
|
||
|
||
- `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。
|
||
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时默认为 `true`（可信网络模型）。
|
||
- 若要启用严格的仅公共网络浏览导航，请设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`。
|
||
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也受相同的私有网络阻止规则限制。
|
||
- `ssrfPolicy.allowPrivateNetwork` 仍支持作为旧别名。
|
||
- 在严格模式下，可使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 显式放行例外。
|
||
- 远程配置文件为仅附加模式（禁止启动/停止/重置）。
|
||
- 自动检测顺序：默认浏览器如果是基于 Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary。
|
||
- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。
|
||
- `extraArgs` 会向本地 Chromium 启动追加额外标志（例如
|
||
`--disable-gpu`、窗口大小设置或调试标志）。
|
||
- `relayBindHost` 更改 Chrome 扩展 relay 的监听地址。若只需 loopback 访问请保持未设置；仅当 relay 必须跨命名空间边界可达（例如 WSL2）且主机网络已受信任时，才显式设置为非 loopback 地址，例如 `0.0.0.0`。
|
||
|
||
---
|
||
|
||
## UI
|
||
|
||
```json5
|
||
{
|
||
ui: {
|
||
seamColor: "#FF4500",
|
||
assistant: {
|
||
name: "OpenClaw",
|
||
avatar: "CB", // emoji、短文本、图片 URL 或 data URI
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。
|
||
- `assistant`：Control UI 身份覆盖。回退到活动智能体身份。
|
||
|
||
---
|
||
|
||
## Gateway 网关
|
||
|
||
```json5
|
||
{
|
||
gateway: {
|
||
mode: "local", // local | remote
|
||
port: 18789,
|
||
bind: "loopback",
|
||
auth: {
|
||
mode: "token", // none | token | password | trusted-proxy
|
||
token: "your-token",
|
||
// password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD
|
||
// trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；见 /gateway/trusted-proxy-auth
|
||
allowTailscale: true,
|
||
rateLimit: {
|
||
maxAttempts: 10,
|
||
windowMs: 60000,
|
||
lockoutMs: 300000,
|
||
exemptLoopback: true,
|
||
},
|
||
},
|
||
tailscale: {
|
||
mode: "off", // off | serve | funnel
|
||
resetOnExit: false,
|
||
},
|
||
controlUi: {
|
||
enabled: true,
|
||
basePath: "/openclaw",
|
||
// root: "dist/control-ui",
|
||
// allowedOrigins: ["https://control.example.com"], // 非 loopback Control UI 必需
|
||
// dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header origin 回退模式
|
||
// allowInsecureAuth: false,
|
||
// dangerouslyDisableDeviceAuth: false,
|
||
},
|
||
remote: {
|
||
url: "ws://gateway.tailnet:18789",
|
||
transport: "ssh", // ssh | direct
|
||
token: "your-token",
|
||
// password: "your-password",
|
||
},
|
||
trustedProxies: ["10.0.0.1"],
|
||
// 可选。默认 false。
|
||
allowRealIpFallback: false,
|
||
tools: {
|
||
// 额外的 /tools/invoke HTTP deny
|
||
deny: ["browser"],
|
||
// 从默认 HTTP deny 列表中移除工具
|
||
allow: ["gateway"],
|
||
},
|
||
push: {
|
||
apns: {
|
||
relay: {
|
||
baseUrl: "https://relay.example.com",
|
||
timeoutMs: 10000,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
<Accordion title="Gateway 网关字段详情">
|
||
|
||
- `mode`：`local`（运行网关）或 `remote`（连接远程网关）。除非为 `local`，否则 Gateway 网关拒绝启动。
|
||
- `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
|
||
- `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。
|
||
- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
|
||
- **Docker 说明**：默认的 `loopback` bind 在容器内监听 `127.0.0.1`。在 Docker bridge 网络（`-p 18789:18789`）下，流量从 `eth0` 进入，因此网关不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。
|
||
- **认证**：默认要求认证。非 loopback bind 需要共享 token/password。新手引导默认会生成一个 token。
|
||
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。如果两者都已配置但 mode 未设置，启动和服务安装/修复流程都会失败。
|
||
- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中故意不提供此选项。
|
||
- `gateway.auth.mode: "trusted-proxy"`：将认证委托给具备身份感知能力的反向代理，并信任来自 `gateway.trustedProxies` 的身份头（见 [Trusted Proxy Auth](/gateway/trusted-proxy-auth)）。
|
||
- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）；HTTP API 端点仍要求 token/password 认证。这种无 token 流程假定网关主机是受信任的。当 `tailscale.mode = "serve"` 时默认值为 `true`。
|
||
- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证范围生效（共享密钥和设备 token 分别跟踪）。被阻止的尝试返回 `429` + `Retry-After`。
|
||
- `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；当你有意希望 localhost 流量也受限流时（用于测试设置或严格代理部署），请设为 `false`。
|
||
- 来自浏览器 origin 的 WS 认证尝试始终会在禁用 loopback 豁免的情况下限流（作为对基于浏览器的 localhost 暴力破解的纵深防御）。
|
||
- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开，需要认证）。
|
||
- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器 origin allowlist。当浏览器客户端预期来自非 loopback origin 时必须设置。
|
||
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为那些刻意依赖 Host-header origin 策略的部署启用 Host-header origin 回退。
|
||
- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。
|
||
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧的紧急覆盖，允许对受信任的私有网络 IP 使用明文 `ws://`；默认仍只允许 loopback 使用明文。
|
||
- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置网关认证。
|
||
- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 版本在将基于 relay 的注册发布到网关后，供网关使用的外部 APNs relay 基础 HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。
|
||
- `gateway.push.apns.relay.timeoutMs`：网关到 relay 的发送超时（毫秒）。默认值为 `10000`。
|
||
- 基于 relay 的注册会被委派给一个特定网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，将该身份包含到 relay 注册中，并将带注册作用域的发送授权转发给网关。其他网关不能复用该已存储注册。
|
||
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：用于覆盖上述 relay 配置的临时环境变量。
|
||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅开发用的逃生口，用于 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。
|
||
- `gateway.channelHealthCheckMinutes`：渠道健康检查监视间隔（分钟）。设为 `0` 可全局禁用健康检查重启。默认：`5`。
|
||
- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认：`30`。
|
||
- `gateway.channelMaxRestartsPerHour`：滚动一小时内，每个渠道/账户允许的最大健康检查重启次数。默认：`10`。
|
||
- `channels.<provider>.healthMonitor.enabled`：按渠道选择退出健康检查重启，同时保留全局监视器开启。
|
||
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账户渠道的按账户覆盖。设置后，它优先于渠道级覆盖。
|
||
- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可回退到 `gateway.remote.*`。
|
||
- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，解析会以默认拒绝方式失败（不会用 remote 回退掩盖）。
|
||
- `trustedProxies`：终止 TLS 的反向代理 IP。仅列出你控制的代理。
|
||
- `allowRealIpFallback`：为 `true` 时，当缺失 `X-Forwarded-For` 时，Gateway 网关接受 `X-Real-IP`。默认为 `false`，以实现默认拒绝行为。
|
||
- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认 deny 列表）。
|
||
- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名。
|
||
|
||
</Accordion>
|
||
|
||
### 兼容 OpenAI 的端点
|
||
|
||
- Chat Completions：默认禁用。通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。
|
||
- Responses API：`gateway.http.endpoints.responses.enabled`。
|
||
- Responses URL 输入加固：
|
||
- `gateway.http.endpoints.responses.maxUrlParts`
|
||
- `gateway.http.endpoints.responses.files.urlAllowlist`
|
||
- `gateway.http.endpoints.responses.images.urlAllowlist`
|
||
- 可选的响应加固 header：
|
||
- `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS origin 设置；见 [Trusted Proxy Auth](/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
|
||
|
||
### 多实例隔离
|
||
|
||
使用不同端口和状态目录，在一台主机上运行多个网关：
|
||
|
||
```bash
|
||
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
|
||
OPENCLAW_STATE_DIR=~/.openclaw-a \
|
||
openclaw gateway --port 19001
|
||
```
|
||
|
||
便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile <name>`（使用 `~/.openclaw-<name>`）。
|
||
|
||
见 [Multiple Gateways](/gateway/multiple-gateways)。
|
||
|
||
---
|
||
|
||
## Hooks
|
||
|
||
```json5
|
||
{
|
||
hooks: {
|
||
enabled: true,
|
||
token: "shared-secret",
|
||
path: "/hooks",
|
||
maxBodyBytes: 262144,
|
||
defaultSessionKey: "hook:ingress",
|
||
allowRequestSessionKey: false,
|
||
allowedSessionKeyPrefixes: ["hook:"],
|
||
allowedAgentIds: ["hooks", "main"],
|
||
presets: ["gmail"],
|
||
transformsDir: "~/.openclaw/hooks/transforms",
|
||
mappings: [
|
||
{
|
||
match: { path: "gmail" },
|
||
action: "agent",
|
||
agentId: "hooks",
|
||
wakeMode: "now",
|
||
name: "Gmail",
|
||
sessionKey: "hook:gmail:{{messages[0].id}}",
|
||
messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
|
||
deliver: true,
|
||
channel: "last",
|
||
model: "openai/gpt-5.2-mini",
|
||
},
|
||
],
|
||
},
|
||
}
|
||
```
|
||
|
||
认证：`Authorization: Bearer <token>` 或 `x-openclaw-token: <token>`。
|
||
|
||
**端点：**
|
||
|
||
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
|
||
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
|
||
- 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受请求负载中的 `sessionKey`。
|
||
- `POST /hooks/<name>` → 通过 `hooks.mappings` 解析
|
||
|
||
<Accordion title="映射详情">
|
||
|
||
- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。
|
||
- `match.source` 匹配通用路径中的某个负载字段。
|
||
- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取。
|
||
- `transform` 可指向返回 hook 操作的 JS/TS 模块。
|
||
- `transform.module` 必须是相对路径，并且始终位于 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。
|
||
- `agentId` 会路由到指定智能体；未知 ID 会回退到默认值。
|
||
- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。
|
||
- `defaultSessionKey`：可选的固定会话键，用于未显式提供 `sessionKey` 的 hook 智能体运行。
|
||
- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方设置 `sessionKey`（默认：`false`）。
|
||
- `allowedSessionKeyPrefixes`：针对显式 `sessionKey` 值（请求 + 映射）的可选前缀 allowlist，例如 `["hook:"]`。
|
||
- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。
|
||
- `model` 会覆盖此次 hook 运行的 LLM（如果已设置模型目录，则必须是允许的模型）。
|
||
|
||
</Accordion>
|
||
|
||
### Gmail 集成
|
||
|
||
```json5
|
||
{
|
||
hooks: {
|
||
gmail: {
|
||
account: "openclaw@gmail.com",
|
||
topic: "projects/<project-id>/topics/gog-gmail-watch",
|
||
subscription: "gog-gmail-watch-push",
|
||
pushToken: "shared-push-token",
|
||
hookUrl: "http://127.0.0.1:18789/hooks/gmail",
|
||
includeBody: true,
|
||
maxBytes: 20000,
|
||
renewEveryMinutes: 720,
|
||
serve: { bind: "127.0.0.1", port: 8788, path: "/" },
|
||
tailscale: { mode: "funnel", path: "/gmail-pubsub" },
|
||
model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
|
||
thinking: "off",
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。
|
||
- 不要与 Gateway 网关同时单独运行 `gog gmail watch serve`。
|
||
|
||
---
|
||
|
||
## Canvas host
|
||
|
||
```json5
|
||
{
|
||
canvasHost: {
|
||
root: "~/.openclaw/workspace/canvas",
|
||
liveReload: true,
|
||
// enabled: false, // 或 OPENCLAW_SKIP_CANVAS_HOST=1
|
||
},
|
||
}
|
||
```
|
||
|
||
- 在 Gateway 网关端口下，通过 HTTP 提供可由智能体编辑的 HTML/CSS/JS 和 A2UI：
|
||
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
|
||
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
|
||
- 仅限本地：保持 `gateway.bind: "loopback"`（默认）。
|
||
- 非 loopback bind：canvas 路由需要 Gateway 网关认证（token/password/trusted-proxy），与其他 Gateway 网关 HTTP 界面一致。
|
||
- Node WebView 通常不会发送认证头；在某个节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告带节点作用域的 capability URL。
|
||
- Capability URL 绑定到活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。
|
||
- 会向所服务的 HTML 中注入 live-reload 客户端。
|
||
- 空目录时会自动创建起始 `index.html`。
|
||
- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。
|
||
- 更改需要重启 Gateway 网关。
|
||
- 对于大型目录或 `EMFILE` 错误，请禁用 live reload。
|
||
|
||
---
|
||
|
||
## 设备发现
|
||
|
||
### mDNS（Bonjour）
|
||
|
||
```json5
|
||
{
|
||
discovery: {
|
||
mdns: {
|
||
mode: "minimal", // minimal | full | off
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `minimal`（默认）：从 TXT 记录中省略 `cliPath` + `sshPort`。
|
||
- `full`：包含 `cliPath` + `sshPort`。
|
||
- 主机名默认为 `openclaw`。可使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。
|
||
|
||
### 广域（DNS-SD）
|
||
|
||
```json5
|
||
{
|
||
discovery: {
|
||
wideArea: { enabled: true },
|
||
},
|
||
}
|
||
```
|
||
|
||
在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。对于跨网络设备发现，可与 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS 搭配使用。
|
||
|
||
设置：`openclaw dns setup --apply`。
|
||
|
||
---
|
||
|
||
## 环境
|
||
|
||
### `env`（内联环境变量）
|
||
|
||
```json5
|
||
{
|
||
env: {
|
||
OPENROUTER_API_KEY: "sk-or-...",
|
||
vars: {
|
||
GROQ_API_KEY: "gsk-...",
|
||
},
|
||
shellEnv: {
|
||
enabled: true,
|
||
timeoutMs: 15000,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 仅当进程环境中缺少该键时，才会应用内联环境变量。
|
||
- `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。
|
||
- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。
|
||
- 完整优先级见 [Environment](/help/environment)。
|
||
|
||
### 环境变量替换
|
||
|
||
可在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量：
|
||
|
||
```json5
|
||
{
|
||
gateway: {
|
||
auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
|
||
},
|
||
}
|
||
```
|
||
|
||
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。
|
||
- 缺失/为空的变量会在配置加载时抛出错误。
|
||
- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。
|
||
- 适用于 `$include`。
|
||
|
||
---
|
||
|
||
## 密钥
|
||
|
||
Secret refs 是增量能力：明文值仍然可用。
|
||
|
||
### `SecretRef`
|
||
|
||
使用以下对象形式之一：
|
||
|
||
```json5
|
||
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
|
||
```
|
||
|
||
校验：
|
||
|
||
- `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$`
|
||
- `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$`
|
||
- `source: "file"` 的 id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`）
|
||
- `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
|
||
- `source: "exec"` 的 id 不能包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝）
|
||
|
||
### 支持的凭证表面
|
||
|
||
- 规范矩阵：[SecretRef Credential Surface](/reference/secretref-credential-surface)
|
||
- `secrets apply` 会定位受支持的 `openclaw.json` 凭证路径。
|
||
- `auth-profiles.json` 中的 ref 也包含在运行时解析和审计覆盖范围内。
|
||
|
||
### Secret providers 配置
|
||
|
||
```json5
|
||
{
|
||
secrets: {
|
||
providers: {
|
||
default: { source: "env" }, // 可选的显式环境变量提供商
|
||
filemain: {
|
||
source: "file",
|
||
path: "~/.openclaw/secrets.json",
|
||
mode: "json",
|
||
timeoutMs: 5000,
|
||
},
|
||
vault: {
|
||
source: "exec",
|
||
command: "/usr/local/bin/openclaw-vault-resolver",
|
||
passEnv: ["PATH", "VAULT_ADDR"],
|
||
},
|
||
},
|
||
defaults: {
|
||
env: "default",
|
||
file: "filemain",
|
||
exec: "vault",
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。
|
||
- `exec` 提供商要求绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。
|
||
- 默认会拒绝符号链接命令路径。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时校验解析后的目标路径。
|
||
- 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。
|
||
- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传递所需变量。
|
||
- Secret refs 会在激活时解析为内存快照，之后请求路径只读取该快照。
|
||
- 激活期间会应用活动表面过滤：已启用表面上的未解析 ref 会导致启动/重载失败，而非活动表面会被跳过并记录诊断信息。
|
||
|
||
---
|
||
|
||
## 认证存储
|
||
|
||
```json5
|
||
{
|
||
auth: {
|
||
profiles: {
|
||
"anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
|
||
"anthropic:work": { provider: "anthropic", mode: "api_key" },
|
||
},
|
||
order: {
|
||
anthropic: ["anthropic:me@example.com", "anthropic:work"],
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- 每个智能体的配置文件存储在 `<agentDir>/auth-profiles.json`。
|
||
- `auth-profiles.json` 支持值级 ref（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
|
||
- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会进行清理。
|
||
- 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。
|
||
- 见 [OAuth](/concepts/oauth)。
|
||
- Secrets 运行时行为以及 `audit/configure/apply` 工具：见 [Secrets Management](/gateway/secrets)。
|
||
|
||
---
|
||
|
||
## 日志
|
||
|
||
```json5
|
||
{
|
||
logging: {
|
||
level: "info",
|
||
file: "/tmp/openclaw/openclaw.log",
|
||
consoleLevel: "info",
|
||
consoleStyle: "pretty", // pretty | compact | json
|
||
redactSensitive: "tools", // off | tools
|
||
redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
|
||
},
|
||
}
|
||
```
|
||
|
||
- 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。
|
||
- 设置 `logging.file` 以获得稳定路径。
|
||
- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。
|
||
|
||
---
|
||
|
||
## CLI
|
||
|
||
```json5
|
||
{
|
||
cli: {
|
||
banner: {
|
||
taglineMode: "off", // random | default | off
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `cli.banner.taglineMode` 控制横幅标语样式：
|
||
- `"random"`（默认）：轮换的有趣/季节性标语。
|
||
- `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。
|
||
- `"off"`：不显示标语文本（仍显示横幅标题/版本）。
|
||
- 若要隐藏整个横幅（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
|
||
|
||
---
|
||
|
||
## 向导
|
||
|
||
由 CLI 向导（`onboard`、`configure`、`doctor`）写入的元数据：
|
||
|
||
```json5
|
||
{
|
||
wizard: {
|
||
lastRunAt: "2026-01-01T00:00:00.000Z",
|
||
lastRunVersion: "2026.1.4",
|
||
lastRunCommit: "abc1234",
|
||
lastRunCommand: "configure",
|
||
lastRunMode: "local",
|
||
},
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 身份
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
list: [
|
||
{
|
||
id: "main",
|
||
identity: {
|
||
name: "Samantha",
|
||
theme: "helpful sloth",
|
||
emoji: "🦥",
|
||
avatar: "avatars/samantha.png",
|
||
},
|
||
},
|
||
],
|
||
},
|
||
}
|
||
```
|
||
|
||
由 macOS 新手引导助手写入。会派生默认值：
|
||
|
||
- 从 `identity.emoji` 派生 `messages.ackReaction`（回退为 👀）
|
||
- 从 `identity.name`/`identity.emoji` 派生 `mentionPatterns`
|
||
- `avatar` 接受：工作区相对路径、`http(s)` URL 或 `data:` URI
|
||
|
||
---
|
||
|
||
## Bridge（旧版，已移除）
|
||
|
||
当前版本不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前校验会失败；`openclaw doctor --fix` 可清除未知键）。
|
||
|
||
<Accordion title="旧版 bridge 配置（历史参考）">
|
||
|
||
```json
|
||
{
|
||
"bridge": {
|
||
"enabled": true,
|
||
"port": 18790,
|
||
"bind": "tailnet",
|
||
"tls": {
|
||
"enabled": true,
|
||
"autoGenerate": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
</Accordion>
|
||
|
||
---
|
||
|
||
## Cron
|
||
|
||
```json5
|
||
{
|
||
cron: {
|
||
enabled: true,
|
||
maxConcurrentRuns: 2,
|
||
webhook: "https://example.invalid/legacy", // 旧版回退，仅用于已存储的 notify:true 作业
|
||
webhookToken: "replace-with-dedicated-token", // 可选，用于出站 webhook 认证的 bearer token
|
||
sessionRetention: "24h", // 时长字符串或 false
|
||
runLog: {
|
||
maxBytes: "2mb", // 默认 2_000_000 字节
|
||
keepLines: 2000, // 默认 2000
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- `sessionRetention`：已完成的隔离 Cron 运行会话在从 `sessions.json` 清理前保留多久。也控制已归档、已删除的 Cron 记录清理。默认：`24h`；设为 `false` 可禁用。
|
||
- `runLog.maxBytes`：每个运行日志文件（`cron/runs/<jobId>.jsonl`）在清理前的最大大小。默认：`2_000_000` 字节。
|
||
- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认：`2000`。
|
||
- `webhookToken`：用于 Cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略则不发送认证头。
|
||
- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍然具有 `notify: true` 的已存储作业。
|
||
|
||
见 [Cron Jobs](/automation/cron-jobs)。
|
||
|
||
---
|
||
|
||
## 媒体模型模板变量
|
||
|
||
会在 `tools.media.models[].args` 中展开的模板占位符：
|
||
|
||
| Variable | Description |
|
||
| ------------------ | -------------------------------------------- |
|
||
| `{{Body}}` | 完整入站消息正文 |
|
||
| `{{RawBody}}` | 原始正文（无历史/发送者包装） |
|
||
| `{{BodyStripped}}` | 去除群组提及后的正文 |
|
||
| `{{From}}` | 发送者标识符 |
|
||
| `{{To}}` | 目标标识符 |
|
||
| `{{MessageSid}}` | 渠道消息 ID |
|
||
| `{{SessionId}}` | 当前会话 UUID |
|
||
| `{{IsNewSession}}` | 新建会话时为 `"true"` |
|
||
| `{{MediaUrl}}` | 入站媒体伪 URL |
|
||
| `{{MediaPath}}` | 本地媒体路径 |
|
||
| `{{MediaType}}` | 媒体类型（image/audio/document/…） |
|
||
| `{{Transcript}}` | 音频转录 |
|
||
| `{{Prompt}}` | 为 CLI 条目解析后的媒体提示 |
|
||
| `{{MaxChars}}` | 为 CLI 条目解析后的最大输出字符数 |
|
||
| `{{ChatType}}` | `"direct"` 或 `"group"` |
|
||
| `{{GroupSubject}}` | 群组主题（尽力而为） |
|
||
| `{{GroupMembers}}` | 群组成员预览（尽力而为） |
|
||
| `{{SenderName}}` | 发送者显示名（尽力而为） |
|
||
| `{{SenderE164}}` | 发送者电话号码（尽力而为） |
|
||
| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） |
|
||
|
||
---
|
||
|
||
## 配置 includes（`$include`）
|
||
|
||
将配置拆分为多个文件：
|
||
|
||
```json5
|
||
// ~/.openclaw/openclaw.json
|
||
{
|
||
gateway: { port: 18789 },
|
||
agents: { $include: "./agents.json5" },
|
||
broadcast: {
|
||
$include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
|
||
},
|
||
}
|
||
```
|
||
|
||
**合并行为：**
|
||
|
||
- 单个文件：替换包含它的对象。
|
||
- 文件数组：按顺序深度合并（后者覆盖前者）。
|
||
- 同级键：在 include 之后再合并（覆盖被包含的值）。
|
||
- 嵌套 include：最多 10 层。
|
||
- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。只有在最终解析结果仍位于该边界内时，才允许使用绝对路径/`../` 形式。
|
||
- 错误：缺失文件、解析错误和循环 include 都会给出清晰错误信息。
|
||
|
||
---
|
||
|
||
_相关内容：[Configuration](/gateway/configuration) · [Configuration Examples](/gateway/configuration-examples) · [Doctor](/gateway/doctor)_
|