轻松玩转OpenClaw的参数配置

**适用版本**：OpenClaw 2026.x **核心功能**：系统全局配置、模型管理、代理编排、多渠道接入 ## 1. 配置文件概览 OpenClaw 采用 **JSON5** 格式作为主配置文件，支持注释、尾随逗号及环境变量注入，极大提升了可读性与维护性。 ### 📂 文件位置与格式 - **主配置文件**：`~/.openclaw/openclaw.json` - **备份文件**：`~/.openclaw/openclaw.json.bak` - **支持格式**：标准 JSON / JSON5 (推荐) ### ⚡ 核心特性 |特性|说明| |:-:|:-:| |**JSON5 支持**|支持 `//` 注释、单引号 `'`、尾随逗号 `,`| |**环境变量**|支持 `${VAR_NAME}` 引用或 `env` 字段定义| |**配置合并**|支持 `主配置` + `环境配置` 自动合并| |**热重载**|部分配置修改后重启网关即可生效| ### 💡 基础语法示例 ``` { // 1. 定义环境变量 (可选，也可在 .env 文件中定义) "env": { "OPENAI_API_KEY": "sk-xxx" }, // 2. 引用环境变量 "models": { "providers": { "openai": { "apiKey": "${OPENAI_API_KEY}", "baseUrl": "https://api.openai.com/v1" } } }, // 3. 设置默认代理模型 "agents": { "defaults": { "model": { "primary": "openai/gpt-4o" } } } } ``` ## 2. 核心模块详解 配置文件由多个顶层对象组成，以下按功能模块详细解析。 ### 2.1 🤖 模型与认证 (Models & Auth) 负责连接大模型提供商及管理 API 密钥。 #### **Auth (认证配置)** 集中管理各提供商的凭证。 - **结构**：`auth.profiles["<provider>:<profile>"]` - **关键字段**： - `provider`: 提供商名称 (如 `openai`, `minimax-cn`) - `mode`: 认证模式 (通常为 `api_key`) - `apiKey`: API 密钥 (建议用环境变量) - `baseUrl`: 自定义 API 地址 (适用于私有部署或中转) #### **Models (模型配置)** 定义可用模型及其属性（成本、上下文、能力）。 - **配置模式**：`merge` (合并默认列表) 或 `replace` (完全覆盖)。 - **模型属性**： - `reasoning`: 是否支持推理 (boolean) - `input`: 支持的输入类型 (`["text", "image"]`) - `cost`: Token 计费详情 (`input`, `output`, `cacheRead/Write`) - `contextWindow`: 上下文窗口大小 - `maxTokens`: 最大输出长度 ``` "models": { "mode": "merge", "providers": { "deepseek": { "baseUrl": "https://api.deepseek.com", "api": "openai-completions", // 兼容类型: openai-completions, anthropic-messages "models": [ { "id": "deepseek-reasoner", "name": "DeepSeek Reasoner", "reasoning": true, "cost": { "input": 0.14, "output": 2.19 }, "contextWindow": 64000 } ] } } } ``` ### 2.2 🧠 代理编排 (Agents) 定义 AI 代理的行为逻辑、工作区及并发策略。 |参数|类型|默认值|说明| |:-:|:-:|:-:|:-:| |`defaults.model.primary`|string|-|**主模型** (格式: provider/id)| |`defaults.model.fallbacks`|array|[]|**回退模型链**，主模型失败时自动切换| |`defaults.workspace`|string|`~/.openclaw/workspace`|默认工作区路径| |`defaults.maxConcurrent`|number|4|最大并发任务数| |`defaults.compaction.mode`|string|`safeguard`|上下文压缩策略 (`safeguard`/`aggressive`/`off`)| |`list`|array|[]|**自定义代理实例列表** (可覆盖默认配置)| **高级用法：子代理控制** ``` "subagents": { "maxConcurrent": 8, // 子代理最大并发 "allowAgents": ["prompt-engineer"] // 仅允许特定子代理 } ``` ### 2.3 🌐 频道接入 (Channels) 配置 Telegram, Discord, 飞书, QQ 等消息渠道。 #### 通用策略参数 - `enabled`: 是否启用该频道。 - `dmPolicy`: 私聊策略 (`pairing`配对, `allowlist`白名单, `open`开放, `disabled`禁用)。 - `groupPolicy`: 群聊策略 (同上)。 - `allowFrom`: 允许访问的用户ID或群组ID列表 (`["*"]` 表示所有)。 - `streaming`: 流式输出模式 (`true`/`false`/`"partial"`). #### 常见渠道配置片段 - **Telegram**: 需 `botToken`。 - **飞书 (Feishu)**: 需 `appId`, `appSecret`, `domain` (feishu/lark)。 - **Discord**: 需 `botToken`, `clientId`。 - **WhatsApp**: 需 `sessionPath`, `qrTimeout`。 ``` "channels": { "telegram": { "enabled": true, "dmPolicy": "pairing", "groupPolicy": "allowlist", "allowFrom": ["@admin_user", "-100123456789"], // 仅允许特定用户和群 "botToken": "${TG_BOT_TOKEN}" }, "feishu": { "enabled": true, "appId": "${FEISHU_APP_ID}", "appSecret": "${FEISHU_APP_SECRET}", "dmPolicy": "allow" } } ``` ### 2.4 🛡️ 网关与安全 (Gateway) 控制 OpenClaw 的网络暴露面及访问权限。 |参数|默认值|说明| |:-:|:-:|:-:| |`port`|18789|WebSocket 监听端口| |`mode`|`local`|运行模式 (`local`/`remote`)| |`bind`|`loopback`|网络绑定 (`loopback`仅本地, `lan`局域网, `tailnet`)| |`auth.mode`|-|认证方式 (`token`/`password`/`none`)| |`controlUi.enabled`|true|是否开启 Web 控制界面| **Tailscale 集成** 支持通过 Tailscale 暴露服务 (`mode`: `off`/`serve`/`funnel`)，实现安全的内网穿透。 ### 2.5 💾 记忆与插件 (Memory & Plugins) - **Memory**: 配置长期记忆后端。 - `backend`: `qmd` (向量数据库) 或 `file` (本地文件)。 - `citations`: 引用来源显示策略 (`auto`/`always`/`never`)。 - `qmd.limits`: 限制检索结果数、片段长度及超时时间。 - **Plugins**: 管理插件的安装与启用状态 (`entries`, `installs`)。 ### 2.6 📟 元数据与其他 (Meta, Commands, Messages) - **meta/wizard**: 系统自动维护的版本记录与向导状态，**通常无需手动修改**。 - **commands**: 命令行行为控制 (如 `restart` 是否允许重启)。 - **messages**: 消息交互细节 (如 `ackReactionScope` 确认反应范围)。 ## 3. 🚀 场景化配置模板 ### 场景 A：新手快速启动 (最小化配置) 仅需配置 API Key 和默认模型即可运行。 ``` { "env": { "OPENAI_API_KEY": "sk-your-key-here" }, "models": { "providers": { "openai": { "apiKey": "${OPENAI_API_KEY}" } } }, "agents": { "defaults": { "model": { "primary": "openai/gpt-4o" } } } } ``` ### 场景 B：多代理协作 (不同任务不同模型) 为“编程”和“研究”创建独立的工作区和模型偏好。 ``` "agents": { "defaults": { "workspace": "~/.openclaw/workspace", "model": { "primary": "openai/gpt-4o" } }, "list": [ { "id": "coder", "name": "编程专家", "model": "deepseek/deepseek-coder", "workspace": "~/.openclaw/ws-coding" }, { "id": "researcher", "name": "研究助手", "model": "anthropic/claude-3-5-sonnet", "workspace": "~/.openclaw/ws-research" } ] } ``` ### 场景 C：生产环境安全加固 启用密码认证、限制局域网访问、关闭不安全的调试选项。 ``` { "gateway": { "port": 18789, "bind": "lan", "auth": { "mode": "password", "password": "${GW_PASSWORD}" }, "controlUi": { "enabled": true, "allowInsecureAuth": false, "dangerouslyAllowHostHeaderOriginFallback": false } }, "channels": { "telegram": { "enabled": true, "dmPolicy": "allowlist", "allowFrom": ["user_id_123"] } } } ``` ## 4. 🛠️ 运维与调试 ### 配置验证 修改配置后，务必先验证语法正确性： ``` # 验证配置文件语法 openclaw config validate # 查看当前生效的完整配置 openclaw config get # 查看特定参数 openclaw config get gateway.port ``` ### 故障排查 ``` # 实时查看包含 config 或 error 的日志 openclaw logs --follow --grep "config\|error" # 检查网关运行状态 openclaw gateway status # 运行系统诊断并尝试自动修复 openclaw doctor --repair ``` ### 配置生效 大部分配置修改后需重启网关： ``` openclaw gateway restart # 或者 openclaw gateway stop && openclaw gateway start ``` ## 5. ✅ 最佳实践清单 1. **敏感信息隔离**：严禁在 `openclaw.json` 中硬编码 API Key 或密码。始终使用 `${ENV_VAR}` 引用环境变量，或在 `.env` 文件中管理。 2. **最小权限原则**： - 生产环境 `dmPolicy` 和 `groupPolicy` 优先设为 `allowlist`。 - `gateway.bind` 除非必要，否则不要设为 `0.0.0.0`，推荐使用 `lan` 或 `tailnet`。 3. **版本控制**：将配置文件纳入 Git 管理（注意 `.gitignore` 掉包含真实密钥的 `.env` 文件）。 4. **渐进式变更**：每次只修改一个模块的配置，验证无误后再进行下一步。 5. **定期备份**：重要操作前手动备份 `openclaw.json.bak`。 **📚 相关资源** - [官方文档](https://docs.openclaw.ai/configuration) - [GitHub 配置示例库](https://github.com/openclaw/openclaw/tree/main/examples/configs) - [问题反馈与建议](https://github.com/openclaw/openclaw/issues)