**适用版本**：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)

适用版本：OpenClaw 2026.x核心功能：系统全局配置、模型管理、代理编排、多渠道接入

轻松玩转OpenClaw的参数配置

人工智能

开发工具

后端

OpenClaw2026.x配置指南：详解JSON5格式配置文件，支持环境变量注入与热重载。包含模型管理、代理编排、多渠道接入等核心模块配置方法，提供生产环境安全加固方案与场景化模板，助您快速搭建AI代理系统。

向量数据库

数据库

GitHub

JSON

2026新春采购季

tencentdb-catalog

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

轻松玩转OpenClaw的参数配置-腾讯云开发者社区-腾讯云

轻松玩转OpenClaw的参数配置

轻松玩转OpenClaw的参数配置

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐