⚙️ OpenClaw Gateway 配置详解
config.schema.lookup · config.patch · config.apply
从零到生产环境的完整配置指南
📅 2026-06-09⏱️ 阅读 12 分钟🏷️ Gateway · Config · DevOps
1. Gateway 配置系统概览
OpenClaw Gateway 的配置系统基于 JSON Schema，支持三种操作：
| 操作 | 说明 | 使用场景 |
|---|
| config.schema.lookup | 查询配置项的 Schema 定义 | 不确定配置项的格式时 |
| config.get | 获取当前完整配置 | 查看/备份当前配置 |
| config.patch | 部分更新配置（合并） | 修改个别配置项（推荐） |
| config.apply | 全量替换配置 | 批量迁移/重置配置 |
💡 最佳实践：优先使用 config.patch，它只修改你指定的部分，不会影响其他配置。config.apply 是全量替换，用错了会覆盖所有配置。
2. Schema 查询：config.schema.lookup
不确定某个配置项的格式？用 schema.lookup 查看：
# 查询频道配置的 schema
gateway({
action: "config.schema.lookup",
path: "channels"
})
# 查询 Agent 配置的 schema
gateway({
action: "config.schema.lookup",
path: "agents"
})
# 查询安全策略的 schema
gateway({
action: "config.schema.lookup",
path: "security"
})
# 查询插件配置
gateway({
action: "config.schema.lookup",
path: "plugins"
})
📋 常用配置路径
| 路径 | 说明 |
|---|
channels | 频道配置（飞书、Discord、Telegram 等） |
agents | Agent 配置（模型、权限、提示词） |
plugins | 插件配置（SearXNG、MCP 等） |
security | 安全策略（exec 权限、审批等） |
nodes | 节点配置（手机连接等） |
cron | 定时任务配置 |
3. 获取当前配置：config.get
# 获取完整配置
gateway({ action: "config.get" })
# 获取特定路径的配置
gateway({ action: "config.get", path: "channels.feishu" })
⚠️ 注意：config.get 返回的配置包含敏感信息（API Key、Token 等），不要在公开场合展示。
4. 部分更新：config.patch（推荐）
config.patch 只修改你指定的部分，其他配置保持不变。这是最安全的更新方式。
# 示例：添加飞书频道配置
gateway({
action: "config.patch",
raw: JSON.stringify({
channels: {
feishu: {
enabled: true,
appId: "cli_xxx",
appSecret: "xxx",
encryptKey: "xxx",
verificationToken: "xxx"
}
}
}),
note: "添加飞书频道配置"
})
# 示例：修改 Agent 模型
gateway({
action: "config.patch",
raw: JSON.stringify({
agents: {
miaoquai: {
model: "gpt-4o",
thinking: "off"
}
}
}),
note: "将妙趣AI模型切换为 GPT-4o"
})
💡 patch 的合并策略：
- 对象类型：递归合并（只更新指定的字段）
- 数组类型：替换整个数组
- 标量类型：直接替换
- null 值：删除该字段
5. 全量替换：config.apply
# ⚠️ 危险操作：全量替换配置
# 先获取当前配置
const current = gateway({ action: "config.get" })
# 修改后全量应用
gateway({
action: "config.apply",
raw: JSON.stringify(modifiedConfig),
note: "全量更新配置"
})
⚠️ 警告：config.apply 会替换整个配置文件。如果传入的 JSON 缺少某些字段，那些字段会被删除。除非你明确知道在做什么，否则用 config.patch。
6. 频道配置实战
📱 飞书（Feishu）
gateway({
action: "config.patch",
raw: JSON.stringify({
channels: {
feishu: {
enabled: true,
appId: "cli_xxxxx",
appSecret: "xxxxx",
encryptKey: "xxxxx",
verificationToken: "xxxxx"
}
}
}),
note: "配置飞书频道"
})
💬 Discord
gateway({
action: "config.patch",
raw: JSON.stringify({
channels: {
discord: {
enabled: true,
botToken: "MTxxxxx",
guildId: "123456789"
}
}
}),
note: "配置 Discord 频道"
})
📨 Telegram
gateway({
action: "config.patch",
raw: JSON.stringify({
channels: {
telegram: {
enabled: true,
botToken: "123456:ABC-DEF"
}
}
}),
note: "配置 Telegram 频道"
})
7. Agent 配置
gateway({
action: "config.patch",
raw: JSON.stringify({
agents: {
myagent: {
model: "xiaomicoding/mimo-v2.5-pro",
thinking: "off",
persona: "你是一个专业的 AI 助手",
tools: ["web_search", "web_fetch", "write", "edit", "exec"],
security: {
execApproval: "on-miss"
}
}
}
}),
note: "配置 Agent: myagent"
})
📋 Agent 配置项
| 字段 | 类型 | 说明 |
|---|
| model | string | 使用的 AI 模型 |
| thinking | string | 推理模式：off / on / stream |
| persona | string | 系统提示词 |
| tools | array | 允许使用的工具列表 |
| security | object | 安全策略 |
8. 安全策略配置
gateway({
action: "config.patch",
raw: JSON.stringify({
security: {
execApproval: "on-miss", // off | on-miss | always
allowedCommands: ["ls", "cat", "curl", "git"],
blockedCommands: ["rm -rf", "dd", "mkfs"],
maxFileSize: "10MB",
networkAccess: true
}
}),
note: "配置安全策略"
})
🔒 审批模式
| 模式 | 说明 | 适用场景 |
|---|
off | 不审批，直接执行 | 完全信任的环境 |
on-miss | 未明确允许的命令需要审批 | 推荐的默认模式 |
always | 所有命令都需要审批 | 高安全要求环境 |
10. 热更新与重启
大多数配置修改会自动热更新，无需重启。但以下情况需要重启：
- 修改了 Gateway 端口
- 修改了 TLS 证书
- 修改了插件加载配置
# 重启 Gateway
gateway({ action: "restart", reason: "修改了 TLS 配置" })
# 带延迟重启（给当前请求处理时间）
gateway({
action: "restart",
reason: "配置更新",
restartDelayMs: 5000,
note: "5秒后重启，完成配置更新"
})
💡 tip：config.patch 会自动判断是否需要重启。如果修改的配置支持热更新，Gateway 会直接应用；如果需要重启，Gateway 会提示你。