openclaw-config-master
# OpenClaw Config
## 一句话
用 schema-first 工作流安全编辑 OpenClaw 配置文件，验证先行，避免无效 key 导致 Gateway 无法启动或安全策略被破坏。
---
## 核心要点（5条）
1. **Schema 先行** — 不猜 key，用 `gateway config.schema.lookup path="目标路径"` 获取权威 schema
2. **在线修改** — 优先用 `gateway config.patch` 在线修改（自动验证+重启），备选 `openclaw config set` CLI
3. **验证不可跳** — `config.patch` 自动验证；手动编辑后必须跑 `openclaw doctor`
4. **严格模式** — 大多数对象是 `.strict()`，未知 key 会导致 Gateway 拒绝启动
5. **不轻易用 --fix** — `openclaw doctor --fix/--yes` 会写文件，需用户明确同意
6. **受保护路径** — 部分敏感路径（如 `tools.exec.ask`）`config.patch` 无法修改，会返回 `cannot change protected config paths` 错误。遇此情况需直接编辑 `openclaw.json` 后 `openclaw gateway restart`
---
## 配置覆盖范围（全部顶层 key）
| 顶层 key | 子模块 | 说明 |
|---------|--------|------|
| `gateway` | port, mode, bind, auth, tailscale, nodes, controlUi | 网关核心：端口、模式、认证、Tailscale、节点策略 |
| `agents` | defaults, list | Agent 配置：默认模型/工具/工作区 + agent 列表 |
| `channels` | telegram, feishu, discord, slack, whatsapp, signal, imessage, ... | 渠道配置：每个渠道的连接、策略、审批 |
| `models` | providers, mode, bedrockDiscovery | 模型目录：提供者定义、合并模式、Bedrock 发现 |
| `auth` | profiles | 认证配置：API Key / OAuth 认证档案 |
| `tools` | exec, web, fs, media, links, sessions, loopDetection, message, agentToAgent, elevated, subagents, sandbox, sessions_spawn, profile, allow, alsoAllow, deny, byProvider | 工具策略：执行、网络、文件系统、媒体、沙箱、子代理 |
| `commands` | bash, config, mcp, plugins, debug, restart, text, native, nativeSkills, allowFrom, ownerDisplay, ... | 命令控制：聊天命令开关、权限、提权规则 |
| `session` | scope, dmScope, reset, resetByType, resetByChannel, store, typingMode, identityLinks, threadBindings, maintenance, sendPolicy, agentToAgent, ... | 会话管理：路由、重置策略、存储、线程绑定、维护 |
| `hooks` | internal, external | 钩子：内部钩子（session-memory）+ 外部钩子 |
| `secrets` | providers | 密钥管理：文件/环境变量等密钥提供者 |
| `acp` | enabled, backend, defaultAgent, allowedAgents | ACP 后端：Agent 托管运行时配置 |
| `messages` | ackReactionScope | 消息行为：确认反应范围等 |
| `plugins` | enabled, allow, deny, load, slots, entries, installs | 插件系统：启用/禁用、加载路径、安装记录 |
| `skills` | (skills 配置) | 技能配置 |
| `meta` | lastTouchedVersion, lastTouchAt | 系统元数据（自动管理） |
| `wizard` | lastRunAt, lastRunVersion, lastRunCommand, lastRunMode | 向导元数据（自动管理） |
| `$include` | — | 模块化配置：分割到多个 JSON5 文件 |
---
## 工作流程
> **重要**：在提供任何配置指导之前，必须按以下步骤执行前置检查。
### 第一步：查官方文档（必做）
**每次修改配置前，必须先查阅官方最新文档确认字段和用法。** 技能内的文档可能滞后于官方更新。
#### 在线文档（权威来源）
| 文档 | 链接 | 用途 |
|------|------|------|
| **配置指南** | https://docs.openclaw.ai/gateway/configuration | 所有配置项的完整说明 |
| **配置参考** | https://docs.openclaw.ai/gateway/configuration-reference | 字段类型、默认值、示例 |
| **Config CLI** | https://docs.openclaw.ai/cli/config | `config set/get/unset` 用法 |
| **Update CLI** | https://docs.openclaw.ai/cli/update | 版本更新命令 |
| **Channels CLI** | https://docs.openclaw.ai/cli/channels | 渠道管理命令 |
| **Skills CLI** | https://docs.openclaw.ai/cli/skills | 技能管理命令 |
| **Security CLI** | https://docs.openclaw.ai/cli/security | 安全审计命令 |
| **Models** | https://docs.openclaw.ai/gateway/models | 模型提供者配置 |
| **Agents** | https://docs.openclaw.ai/gateway/agents | Agent 配置 |
| **Tools** | https://docs.openclaw.ai/gateway/tools | 工具配置 |
| **Plugins** | https://docs.openclaw.ai/gateway/plugins | 插件配置 |
| **Cron** | https://docs.openclaw.ai/gateway/cron | 定时任务配置 |
| **Session** | https://docs.openclaw.ai/gateway/session | 会话配置 |
#### 内置文档搜索
```bash
# 搜索特定主题的官方文档
openclaw docs "configuration"
openclaw docs "telegram"
openclaw docs "exec approvals"
openclaw docs "models"
openclaw docs "session"
```
#### 在线 Schema 查询
```
# 通过 gateway 工具查询（推荐）
gateway config.schema.lookup path="目标路径"
# CLI 方式
openclaw config schema
```
#### 何时查什么
| 场景 | 查什么 |
|------|--------|
| 添加/修改模型 | 配置参考 + models 文档 + schema lookup |
| 配置渠道 | 配置参考 + Channels CLI + schema lookup |
| 修改安全策略 | 配置指南 + Security CLI + schema lookup |
| 会话/重置策略 | 配置参考 + session 文档 + schema lookup |
| 工具权限控制 | 配置参考 + tools 文档 + schema lookup |
| 版本升级后配置不兼容 | 配置参考 + Update CLI + `references/version-migration.md` |
| 不确定字段名/类型 | **先查 schema lookup**，再查配置参考 |
### 第二步：版本检查
```bash
# 检查本地版本
openclaw --version
# 检查最新版本
openclaw update status --json
```
**如果本地版本不是最新**：提醒用户先更新：`openclaw update`
### 第三步：执行修改
---
## 两种修改模式
### 模式 A：在线修改（推荐）
通过 `gateway` 工具直接修改，自动验证+重启：
```
# 1. 查询当前值
gateway config.get path="commands.bash"
# 2. 查询 schema 确认字段合法性
gateway config.schema.lookup path="commands"
# 3. 应用修改（用户确认后）
gateway config.patch raw='{"commands":{"bash":true}}' note="启用 bash 命令"
```
- `config.patch`：部分更新，与现有配置合并，适合修改少量字段
- `config.apply`：全量替换，适合大规模重构
- 两者都会自动验证 schema + 写入 + 重启 Gateway
- `note` 参数必填，用于重启后通知用户
### 模式 B：CLI 命令（备选）
无法使用 gateway 工具时，生成命令供用户执行：
```bash
# 设置值
openclaw config set <path> <value> --json
# 验证
openclaw config validate
# 重启
openclaw gateway restart
```
---
## 在线修改配置的标准流程
修改任何配置前，按此流程操作：
1. **查 schema** — `gateway config.schema.lookup path="目标路径"`，确认字段名和类型
2. **读当前值** — `gateway config.get path="目标路径"`，了解现状
3. **向用户说明** — 描述要改什么、为什么改、预期影响
4. **执行修改** — 用户确认后，`gateway config.patch raw='{...}' note="变更说明"`
5. **验证结果** — 重启后自动通知，检查新配置是否生效
**注意**：`config.patch` 会自动写入、验证 schema、重启 Gateway。不需要手动 `openclaw doctor`。
---
## 详细配置参考
### gateway — 网关核心
```json
"gateway": {
"port": 18789, // 监听端口
"mode": "local", // 运行模式：local
"bind": "loopback", // 绑定：loopback | 0.0.0.0
"auth": {
"mode": "token", // 认证模式
"token": "..." // 认证 token
},
"tailscale": {
"mode": "off", // Tailscale 模式
"resetOnExit": false
},
"controlUi": {
"allowInsecureAuth": false
},
"nodes": {
"denyCommands": [...] // 节点禁止命令列表
}
}
```
### agents — Agent 配置
```json
"agents": {
"defaults": {
"model": {
"primary": "provider/model-id", // 默认模型
"fallbacks": ["provider/fallback1"] // 回退模型列表
},
"models": { // 可用模型注册 + 别名
"provider/model": { "alias": "别名" }
},
"workspace": "~/.openclaw/workspace", // 工作目录
"contextPruning": { "mode": "cache-ttl", "ttl": "1h" },
"compaction": { "mode": "safeguard" },
"heartbeat": { "every": "30m" },
"maxConcurrent": 2,
"subagents": { "maxConcurrent": 2 }
},
"list": [
{
"id": "main",
"tools": { "alsoAllow": [...] },
"runtime": { "type": "acp", "acp": {...} }
}
]
}
```
### channels — 渠道配置
每个渠道（telegram/feishu/discord/slack/whatsapp/signal/imessage）有独立配置：
```json
"channels": {
"telegram": {
"enabled": true,
"botToken": "...",
"dmPolicy": "allowlist|open",
"groupPolicy": "allowlist|open",
"allowFrom": ["user_id"],
"streaming": "partial|full|off",
"execApprovals": {
"enabled": true,
"approvers": ["user_id"],
"target": "dm"
},
"groups": { "*": { "requireMention": true } }
}
}
```
详细字段见 `references/channels-config.md`
### models — 模型目录
```json
"models": {
"mode": "merge|replace", // merge=保留内置+叠加自定义, replace=仅用自定义
"providers": {
"provider-id": {
"baseUrl": "https://...",
"apiKey": "...|secret-ref",
"api": "openai-completions|anthropic-messages",
"models": [
{
"id": "model-id",
"name": "显示名",
"reasoning": true,
"input": ["text", "image"],
"contextWindow": 200000,
"maxTokens": 8192,
"cost": { "input": 0, "output": 0 }
}
]
}
},
"bedrockDiscovery": { ... } // AWS Bedrock 自动发现
}
```
### auth — 认证档案
```json
"auth": {
"profiles": {
"provider:default": {
"provider": "provider-name",
"mode": "api_key|oauth"
}
}
}
```
### tools — 工具策略
```json
"tools": {
"profile": "...", // 工具策略预设名
"allow": [...], // 绝对白名单（替换 profile 默认）
"alsoAllow": [...], // 白名单补充（叠加 profile）
"deny": [...], // 黑名单（优先级最高）
"byProvider": { ... }, // 按渠道的工具策略覆盖
"exec": {
"security": "allowlist|full",
"ask": "on-miss",
"host": "sandbox",
"safeBins": ["python", "node", "git"],
"safeBinTrustedDirs": [...],
"safeBinProfiles": [...],
"timeoutSec": 120,
"backgroundMs": 10000,
"applyPatch": true
},
"web": { // 搜索/抓取工具策略
"search": { "enabled": true, "provider": "brave" }
},
"fs": { ... }, // 文件系统工具
"media": { ... }, // 媒体工具
"links": { ... }, // 链接工具
"sessions": { ... }, // 会话工具
"loopDetection": { ... }, // 循环检测
"message": { ... }, // 消息工具策略
"agentToAgent": { ... }, // Agent 间工具调用
"elevated": { ... }, // 提权工具访问
"subagents": { ... }, // 子代理工具策略
"sandbox": { ... }, // 沙箱策略
"sessions_spawn": { ... } // spawn 会话策略
}
```
### commands — 命令控制
```json
"commands": {
"native": "auto", // 原生命令注册（Discord/Slack/Telegram 菜单）
"nativeSkills": "auto", // 技能原生命令注册
"text": true, // 文本命令解析
"bash": true, // ! 和 /bash 命令（布尔值）
"config": false, // /config 命令读写配置
"mcp": false, // /mcp 命令管理 MCP 服务器
"plugins": false, // /plugins 命令管理插件
"debug": false, // /debug 运行时调试覆盖
"restart": true, // /restart 和 gateway 重启工具
"useAccessGroups": false, // 启用访问组策略
"ownerAllowFrom": [...], // 显式 owner 白名单
"ownerDisplay": "raw|hash", // owner ID 显示方式
"ownerDisplaySecret": "...", // hash 模式的 HMAC 密钥
"allowFrom": { // 提权命令的 channel→用户映射
"telegram": ["YOUR_TELEGRAM_USER_ID"]
}
}
```
**关键注意**：
- 所有布尔字段必须用 `true`/`false`，不能是字符串 `"true"`
- `allowFrom` 在 `commands` 下，不在 `tools.exec` 下
- 敏感命令（bash/config/mcp/plugins/debug）默认 false，需显式开启
### session — 会话管理
```json
"session": {
"scope": "per-sender|global", // 会话分组策略
"dmScope": "main|per-peer|per-channel-peer|per-account-channel-peer",
"dmScopePolicy": "...", // DM 作用域策略
"identityLinks": { ... }, // 身份映射（跨渠道同一用户）
"resetTriggers": [...], // 会话重置触发词
"idleMinutes": 0, // 空闲重置分钟数（旧版兼容）
"reset": { ... }, // 默认重置策略
"resetByType": { // 按聊天类型覆盖
"direct": { ... },
"group": { ... },
"thread": { ... }
},
"resetByChannel": { ... }, // 按渠道覆盖
"store": "path/to/store.db", // 会话存储路径
"typingMode": "never|instant|thinking|message",
"typingIntervalSeconds": 5,
"parentForkMaxTokens": 0, // 父会话 fork 上限
"mainKey": "...", // 主会话 key 覆盖
"sendPolicy": { // 跨会话发送权限
"allow": [...], "deny": [...]
},
"agentToAgent": { ... }, // Agent 间会话交换
"threadBindings": { ... }, // 线程绑定路由
"maintenance": { // 自动维护
"maxAge": "...", "maxEntries": 1000, "rotateOnStartup": false
}
}
```
### hooks — 钩子
```json
"hooks": {
"internal": {
"enabled": true,
"entries": {
"session-memory": { "enabled": true } // 会话记忆钩子
}
},
"external": { ... } // 外部 webhook 钩子
}
```
### secrets — 密钥管理
```json
"secrets": {
"providers": {
"lark-secrets": {
"source": "file",
"path": "~/.openclaw/credentials/lark.secrets.json"
}
}
}
```
### acp — ACP 后端
```json
"acp": {
"enabled": false,
"backend": "acpx",
"defaultAgent": "claude",
"allowedAgents": ["claude"]
}
```
### messages — 消息行为
```json
"messages": {
"ackReactionScope": "group-mentions" // 确认反应范围
}
```
### plugins — 插件系统
```json
"plugins": {
"enabled": true,
"allow": ["minimax", "telegram", "feishu"], // 插件白名单
"deny": [...], // 插件黑名单
"load": { "paths": [...] }, // 加载路径
"slots": { "memory": "..." }, // 独占槽位
"entries": { // 插件配置
"plugin-id": { "enabled": true, "config": {...} }
},
"installs": { ... } // 安装记录（CLI 管理）
}
```
---
## 版本适配说明（2026.4.x 关键变更）
> **重要**：以下内容记录了从旧版配置格式到当前版本的关键差异。
### 1. `tools.exec` — 不支持 `approvals` 和 `allowFrom`
**错误写法**（会导致 Gateway 崩溃）：
```json
"tools": { "exec": { "approvals": { "enabled": true }, "allowFrom": {...} } }
```
**正确写法**：
```json
"tools": { "exec": { "security": "allowlist", "ask": "on-miss" } }
```
`tools.exec` 支持的字段：`host`, `node`, `security`, `ask`, `pathPrepend`, `safeBins`, `safeBinTrustedDirs`, `safeBinProfiles`, `strictInlineEval`, `backgroundMs`, `timeoutSec`, `cleanupMs`, `notifyOnExit`, `notifyOnExitEmptySuccess`, `applyPatch`。
### 2. exec 审批 → `channels.<channel>.execApprovals`
```json
"channels": {
"telegram": {
"execApprovals": { "enabled": true, "approvers": ["YOUR_TELEGRAM_USER_ID"], "target": "dm" }
}
}
```
### 3. 新旧格式对照速查表
| 功能 | 旧版（错误）位置 | 正确位置 |
|------|-----------------|---------|
| exec 审批 | `tools.exec.approvals` | `channels.telegram.execApprovals` |
| 命令权限白名单 | `tools.exec.allowFrom` | `commands.allowFrom` |
| bash 命令开关 | `commands.bash = "true"` | `commands.bash = true`（布尔值） |
| exec 安全策略 | `tools.exec.security` | `tools.exec.security`（不变） |
---
## $include（模块化配置）
`$include` 在 schema 验证前解析，支持将配置分割到多个 JSON5 文件：
- 支持 `"$include": "./base.json5"` 或数组
- 相对路径相对于当前配置文件目录
- 深度合并规则：对象递归合并，数组拼接，原始值后者覆盖前者
- 限制：最大深度 10；循环 include 被检测并拒绝
---
## Guardrails（避免 Schema 错误）
- **大多数对象是 strict** (`.strict()`)：未知 key 导致 Gateway 拒绝启动
- `channels` 是 `.passthrough()`：扩展 channels 可添加自定义 key
- `env` 是 `.catchall(z.string())`：可直接放字符串环境变量
- **密钥处理**：优先用 `secrets.providers` 或环境变量，避免将 token/API key 写入 `openclaw.json`
---
## 常用配方
**开启 /config 命令**
```
gateway config.patch raw='{"commands":{"config":true}}' note="开启 /config 命令"
```
**配置 exec 安全策略**
```
gateway config.patch raw='{"tools":{"exec":{"security":"allowlist","ask":"on-miss"}}}' note="配置 exec 安全策略"
```
**配置 Telegram（安全模式：仅自己私聊，禁止群聊）**
```
gateway config.patch raw='{"channels":{"telegram":{"enabled":true,"botToken":"YOUR_TELEGRAM_BOT_TOKEN","dmPolicy":"allowlist","allowFrom":["YOUR_TELEGRAM_USER_ID"],"groupPolicy":"disabled"}},"plugins":{"entries":{"telegram":{"enabled":true}}}}' note="配置 Telegram 安全模式"
```
**配置飞书（安全模式：仅自己私聊，群聊开放需 @）**
```
gateway config.patch raw='{"channels":{"feishu":{"enabled":true,"appId":"YOUR_FEISHU_APP_ID","appSecret":"YOUR_FEISHU_APP_SECRET","dmPolicy":"allowlist","allowFrom":["YOUR_FEISHU_USER_ID"],"groupPolicy":"open","groupAllowFrom":["*"],"requireMention":true,"connectionMode":"websocket"}},"plugins":{"allow":["openclaw-lark","minimax"],"entries":{"openclaw-lark":{"enabled":true},"minimax":{"enabled":true}}}}' note="配置飞书安全模式"
```
**获取用户 ID（日志法）**
```bash
# 飞书
tail -500 /tmp/openclaw/openclaw-*.log | grep "message from"
# Telegram
tail -500 /tmp/openclaw/openclaw-*.log | grep "telegram.*message"
```
**验证渠道连接**
```bash
openclaw channels status
openclaw doctor
```
**配置 Telegram exec 审批**
```
gateway config.patch raw='{"channels":{"telegram":{"execApprovals":{"enabled":true,"approvers":["YOUR_TELEGRAM_USER_ID"],"target":"dm"}}}}' note="启用 Telegram exec 审批"
```
**配置命令权限**
```
gateway config.patch raw='{"commands":{"bash":true,"allowFrom":{"telegram":["YOUR_TELEGRAM_USER_ID"]}}}' note="启用 bash 命令并配置权限"
```
**修改会话空闲重置**
```
gateway config.patch raw='{"session":{"idleMinutes":60}}' note="设置会话 60 分钟空闲后重置"
```
**配置会话维护**
```
gateway config.patch raw='{"session":{"maintenance":{"maxEntries":500}}}' note="限制会话存储最多 500 条"
```
**添加模型提供者**
```
gateway config.patch raw='{"models":{"providers":{"new-provider":{"baseUrl":"https://...","api":"openai-completions","models":[...]}}}}' note="添加新模型提供者"
```
**启用插件**
```
gateway config.patch raw='{"plugins":{"allow":["new-plugin"],"entries":{"new-plugin":{"enabled":true}}}}' note="启用新插件"
```
**配置 hooks**
```
gateway config.patch raw='{"hooks":{"internal":{"enabled":true,"entries":{"session-memory":{"enabled":true}}}}}' note="启用 session-memory 钩子"
```
---
## 常见配置错误和修复
| 错误现象 | 常见原因 | 修复方法 |
|---------|---------|---------|
| Gateway 启动崩溃 | `tools.exec` 中有未知字段（如 `approvals`） | 移除不支持的字段 |
| Schema 验证失败 | `commands.bash` 设为字符串 `"true"` | 改为布尔值 `true` |
| exec 审批不生效 | 在 `tools.exec` 中配置审批 | 移至 `channels.telegram.execApprovals` |
| 命令权限不生效 | 在 `tools.exec.allowFrom` 配置白名单 | 移至 `commands.allowFrom` |
| 会话不重置 | `session.reset` 配置不当 | 检查 `resetByType`/`resetByChannel` 是否覆盖 |
---
## 复杂配置操作流程
复杂配置变更（添加新模型提供者、配置新频道等）遵循增强流程：
1. **前置检查** — 确认凭证/参数、验证平台可用性、备份配置
2. **详细配置** — 参考 `references/complex-operations.md`，遵循渐进式修改原则
3. **验证测试** — 逐步测试 + 准备回滚
4. **文档记录** — 记录变更、更新文档
---
## 版本升级流程
1. **升级前准备** — 参阅 `references/version-migration.md`、创建备份、检查兼容性
2. **执行迁移** — 更新字段、处理废弃字段
3. **验证回滚** — 运行测试、准备快速回滚
---
## 快速链接
**Channel 配置** → `references/channels-config.md`
**Telegram + 飞书配置模板** → `references/complex-operations.md`（含安全模式/开放模式模板、AppSecret 安全存储、常见错误）
**复杂配置操作** → `references/complex-operations.md`
**常见错误修复** → `references/common-errors.md`
**版本迁移** → `references/version-migration.md`
**字段索引** → `references/openclaw-config-fields.md`
**Schema 源码** → `references/schema-sources.md`
**工具脚本**
- `scripts/openclaw-config-check.sh` — 配置验证
- `scripts/backup-config.sh` — 配置备份
- `scripts/restore-config.sh` — 配置恢复
- `scripts/validate-config.sh` — 配置验证
- `scripts/validate-migration.sh` — 迁移验证
**官方文档** → 详见上方「第一步：查官方文档」的完整链接表
**故障诊断**
- `openclaw doctor` — 快速诊断
- `~/.openclaw/logs/openclaw.log` — 日志分析
标签
skill
ai
