配置
Gateway 使用 JSON5 格式的配置文件来管理所有运行参数。本文介绍配置文件的结构、管理方式及最佳实践。
配置文件位置
默认配置文件路径：
| 平台 | 路径 |
|---|---|
| macOS / Linux | ~/.openclaw/openclaw.json |
| Windows | %USERPROFILE%\.openclaw\openclaw.json |
JSON5 格式
配置文件使用 JSON5 格式，支持注释、尾部逗号和单引号字符串，比标准 JSON 更易于手动编辑。
配置结构概览
json5
{
// 网关基础配置
"gateway": {
"port": 18789,
"host": "127.0.0.1",
"reloadMode": "hybrid",
"auth": { /* ... */ }
},
// Channel（通道）配置
"channels": [
{ /* ... */ }
],
// 模型路由
"models": { /* ... */ },
// 自动化配置
"automation": { /* ... */ },
// 安全配置
"security": { /* ... */ }
}CLI 配置命令
查看配置
bash
# 查看单个配置项
openclaw config get gateway.port
# 列出所有配置
openclaw config list
# 列出指定分区的配置
openclaw config list --section gateway设置配置
bash
# 设置单个值
openclaw config set gateway.port 18790
# 设置嵌套值
openclaw config set gateway.auth.method token
# 设置数组值
openclaw config set channels[0].provider openai删除配置
bash
# 删除指定配置项（恢复默认值）
openclaw config unset gateway.auth.rateLimitWindow环境变量覆盖
所有配置项均可通过环境变量（Environment Variables）覆盖。变量名规则：
text
OPENCLAW_ + 大写路径 + 下划线分隔
示例：
gateway.port → OPENCLAW_GATEWAY_PORT
gateway.auth.method → OPENCLAW_GATEWAY_AUTH_METHODbash
# 使用环境变量覆盖端口
export OPENCLAW_GATEWAY_PORT=19000
openclaw gateway优先级
环境变量 > CLI 参数 > 配置文件 > 默认值
热加载
Gateway 支持配置热加载（Hot Reload），无需重启即可应用部分配置变更。
热加载模式
bash
# 设置热加载模式
openclaw config set gateway.reloadMode hybrid| 模式 | 说明 | 适用场景 |
|---|---|---|
off | 不自动重载，需手动重启 | 生产环境（严格控制） |
hot | 自动应用所有变更 | 开发环境 |
restart | 变更后自动重启进程 | 需要完全重启的场景 |
hybrid | 部分热加载，部分触发重启 | 推荐 — 平衡灵活性与稳定性 |
可热加载的配置项
| 配置项 | 热加载 | 说明 |
|---|---|---|
channels | ✅ | Channel 增删改 |
models | ✅ | 模型路由调整 |
gateway.port | ❌ | 需要重启 |
gateway.host | ❌ | 需要重启 |
security.sandbox | ✅ | 沙箱策略更新 |
手动触发重载
bash
# 手动触发配置重载
openclaw config reload配置验证
Gateway 在加载配置时会自动验证（Validation）：
bash
# 验证配置文件（不启动 Gateway）
openclaw config validate输出示例：
text
✓ Config file syntax valid
✓ Gateway section valid
✓ Channels section valid
✗ Models section: unknown provider "gpt5" at models.default
1 error found. Please fix before starting gateway.启动前验证
Gateway 启动时若检测到配置错误，会拒绝启动并输出错误详情。建议在修改配置后先运行 validate 验证。
配置备份与恢复
bash
# 导出当前配置
openclaw config export > backup.json
# 从备份恢复
openclaw config import backup.json
# 重置为默认配置
openclaw config reset重置警告
config reset 将不可逆地清除所有自定义配置，包括 Channel 和密钥设置。操作前请先备份。