OpenClaw配置文件完整字段参考

前言

OpenClaw 的所有行为都由一个配置文件驱动——默认位于 ~/.openclaw/openclaw.json。虽然其他文章已经从功能角度介绍了各配置段，但在实际运维中，你往往需要一份"字段级"的速查手册。本文将以表格形式列出 openclaw.json 的每一个合法字段，标注类型、默认值和约束条件，方便你在编辑配置时快速定位。

顶层结构

openclaw.json 的顶层由以下几个配置段组成：

{
  "gateway": {},
  "models": {},
  "channels": {},
  "agents": {},
  "sessions": {},
  "skills": {},
  "persona": {},
  "logging": {},
  "security": {},
  "advanced": {}
}

每个配置段各自独立，你只需要填写实际用到的部分，其余将使用默认值。

gateway 字段参考

网关是 OpenClaw 的 HTTP 入口，负责接收所有频道的 Webhook 回调以及 Dashboard 的请求。

字段	类型	默认值	说明
`port`	number	`18789`	网关监听端口
`host`	string	`"127.0.0.1"`	监听地址，设为 `"0.0.0.0"` 可接受外部连接
`dashboardPassword`	string	`""`	Dashboard 访问密码，留空则无需认证
`apiKey`	string	`""`	REST API 认证密钥
`timeout`	number	`120000`	请求超时，单位毫秒
`maxBodySize`	string	`"10mb"`	请求体大小上限
`cors.enabled`	boolean	`true`	是否启用 CORS
`cors.origins`	string[]	`["*"]`	允许的来源域名列表
`webhookBase`	string	`""`	Webhook 基础 URL，用于自动注册回调地址

models 字段参考

模型配置决定了 OpenClaw 连接哪些 AI 后端。

字段	类型	默认值	说明
`default`	string	`"claude"`	默认模型提供商名称
`providers.<name>.apiKey`	string	必填	提供商 API 密钥
`providers.<name>.model`	string	必填	使用的模型标识
`providers.<name>.maxTokens`	number	`4096`	单次回复最大 token 数
`providers.<name>.temperature`	number	`0.7`	温度参数，0-2 之间
`providers.<name>.baseUrl`	string	视提供商而定	自定义 API 端点
`providers.<name>.headers`	object	`{}`	额外的 HTTP 请求头
`routing.rules`	array	`[]`	模型路由规则数组
`routing.fallback`	string	同 `default`	路由不匹配时的回退模型

channels 字段参考

频道配置定义 OpenClaw 连接的即时通讯平台。每个频道类型都有共享字段和专属字段。

通用频道字段

字段	类型	默认值	说明
`enabled`	boolean	`false`	是否启用此频道
`allowedUsers`	array	`[]`	用户白名单，留空不限制
`allowedGroups`	array	`[]`	群组白名单
`webhookPath`	string	自动生成	自定义 Webhook 路径
`mediaSupport`	object	频道默认	媒体类型支持开关

Telegram 专属字段

字段	类型	说明
`token`	string	Bot Token
`parseMode`	string	消息解析模式：`"Markdown"` 或 `"HTML"`
`groupRules.triggerOnMention`	boolean	是否仅在 @提及时回复

WhatsApp 专属字段

字段	类型	说明
`phoneNumber`	string	绑定的手机号
`accessToken`	string	Business API 访问令牌
`verifyToken`	string	Webhook 验证令牌

Discord 专属字段

字段	类型	说明
`token`	string	Bot Token
`allowedChannels`	string[]	允许交互的频道名或 ID 列表

agents 字段参考

Agent 配置定义了多智能体路由的行为。

字段	类型	默认值	说明
`default`	string	`"default"`	默认 Agent ID
`list[].id`	string	必填	Agent 唯一标识
`list[].name`	string	必填	Agent 显示名称
`list[].model`	string	继承全局	该 Agent 使用的模型
`list[].systemPrompt`	string	`""`	Agent 专属系统提示词
`list[].skills`	string[]	`[]`	该 Agent 可用的技能列表
`list[].knowledgeBase`	string	`""`	知识库目录路径

sessions 字段参考

会话配置控制对话历史的存储和管理。

字段	类型	默认值	说明
`storageFormat`	string	`"jsonl"`	存储格式，目前仅支持 JSONL
`storagePath`	string	`"~/.openclaw/agents/<agentId>/sessions/"`	会话文件目录
`maxHistoryMessages`	number	`50`	上下文中保留的最大消息数
`maxHistoryTokens`	number	`8000`	上下文中保留的最大 token 数
`autoCompaction`	boolean	`true`	上下文溢出时是否自动压缩
`compactionStrategy`	string	`"summary"`	压缩策略：`"summary"` 或 `"truncate"`
`treeStructure`	boolean	`true`	是否启用树形会话结构（支持分支）

security 字段参考

字段	类型	默认值	说明
`rateLimit.enabled`	boolean	`true`	是否启用速率限制
`rateLimit.maxRequests`	number	`60`	每窗口最大请求数
`rateLimit.windowMs`	number	`60000`	窗口时长（毫秒）
`ipWhitelist`	string[]	`[]`	IP 白名单
`ipBlacklist`	string[]	`[]`	IP 黑名单
`tls.enabled`	boolean	`false`	是否启用 HTTPS
`tls.cert`	string	`""`	证书文件路径
`tls.key`	string	`""`	私钥文件路径

logging 字段参考

字段	类型	默认值	说明
`level`	string	`"info"`	日志级别：`debug`、`info`、`warn`、`error`
`file`	string	`""`	日志文件路径，留空仅输出到终端
`maxSize`	string	`"10m"`	单个日志文件最大大小
`maxFiles`	number	`5`	保留的日志文件数量
`format`	string	`"text"`	输出格式：`"text"` 或 `"json"`

advanced 字段参考

字段	类型	默认值	说明
`workers`	number	`0`	工作线程数，0 为自动
`queueSize`	number	`100`	消息队列大小
`storage`	string	`"sqlite"`	数据存储后端
`dbPath`	string	`"~/.openclaw/data/openclaw.db"`	SQLite 数据库路径
`redis.url`	string	`""`	Redis 连接地址
`redis.db`	number	`0`	Redis 数据库编号
`pluginDir`	string	`"~/.openclaw/plugins"`	插件目录

配置验证与调试

修改配置后，务必使用内置工具验证：

# 校验配置文件语法与必填项
openclaw doctor

# 输出当前生效的完整配置（含默认值）
openclaw config --dump

--dump 选项会将所有字段（包括未显式设置的默认值）输出到终端，帮助你确认最终生效的配置。

总结

本文以字段为粒度列出了 openclaw.json 的所有配置项。在日常使用中，建议将本文作为速查手册收藏。大多数情况下你只需关注 gateway、models 和 channels 三个核心段，其余保持默认值即可。如需深入了解某个功能段的用法，可参阅对应的专题教程。