openclaw-config-master: Скилл для редактирования конфигурации

--- name: openclaw-config-master description: Edit and validate OpenClaw Gateway config (openclaw.json / JSON5). Covers all config areas — gateway, agents, channels, models, auth, tools, commands, session, hooks, secrets, acp, messages, plugins, skills, $include. Use when adding/changing config keys or diagnosing openclaw doctor/config validation errors, to avoid schema mismatches that prevent the Gateway from starting or weaken security policies. --- # 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` — 日志分析