这份指南将为你提供一个详尽到每一行的配置文件模板和说明，特别是网关部分。
⚠️ 重要提示：安全与规范
在开始编辑前，有几个关键点需要了解：
- 安全底线：将
gateway暴露到公网（如绑定0.0.0.0）时，必须配置auth认证并设置trustedProxies，否则你的网关将面临严重的安全风险。 - 配置校验：OpenClaw 对配置文件的校验非常严格，任何格式错误都会导致网关无法启动。修改后务必运行
openclaw doctor进行验证。 - 配置格式：OpenClaw 使用 JSON5 格式，这意味着你可以在配置中添加
// 注释来记录备忘，非常方便。
📁 最详尽的配置模板：openclaw.json
将以下内容复制并粘贴到 ~/.openclaw/openclaw.json 文件中。这是一个功能完整的生产级配置示例，涵盖了绝大部分常用场景，你可以根据自己的需要保留或删除相应的部分。一定要根据实际情况修改！一定要根据实际情况修改！一定要根据实际情况修改！
json5
{
// -------------------------------------------
// 1. Gateway 网关配置
// -------------------------------------------
"gateway": {
// 网关的唯一标识模式。生产环境强烈建议设置为 "local" 并启用认证。
// 若未设置，网关会拒绝启动。
// 参考: https://docs.openclaw.ai/cli/gateway
"mode": "local",
// WebSocket/HTTP 服务监听的端口号。默认值通常是 18789。
"port": 18789,
// 监听绑定模式。
// - "loopback": 仅本地访问 (127.0.0.1)，最安全。
// - "lan": 允许局域网访问。
// - "tailnet": 通过 Tailscale 网络暴露。
// - "auto": 自动检测。
// 生产环境若需从外部访问，通常需要配合反向代理或 Tailscale。
"bind": "loopback",
// 控制 UI 的配置（Web 管理界面）
"controlUi": {
// 是否启用 Web UI
"enabled": true,
// Web UI 的基础路径，用于反向代理部署
"basePath": "/app/openclaw/default",
// 允许跨域请求的来源。生产环境建议替换为你的具体域名，而不是 "*"
"allowedOrigins": ["*"],
// 是否允许在非 HTTPS 连接下进行身份验证。生产环境应设为 false。
"allowInsecureAuth": true,
// 危险选项：禁用设备配对流程。当网关由外部系统（如 Mission Control）管理时启用。
// 注意：这会将认证完全交由 auth.token 处理，带来风险，通常不建议手动开启。
"dangerouslyDisableDeviceAuth": true
},
// 身份认证配置。这是生产环境中最关键的安全屏障之一。
"auth": {
// 认证模式。可选 "token" (推荐) 或 "password"。
// 启用后，任何连接网关的客户端都必须提供此 token。
// 参考: https://docs.openclaw.ai/cli/gateway#authentication
"token": "__OPENCLAW_REDACTED__"
},
// TLS/HTTPS 配置。用于加密网关的通信。
// 注意：如果你使用 Caddy 或 Nginx 作为反向代理，通常不需要在此处配置 TLS。
"tls": {
// 是否启用 TLS
"enabled": false,
// 证书文件路径
"certPath": "/path/to/cert.pem",
// 私钥文件路径
"keyPath": "/path/to/key.pem"
},
// 可信代理配置。当你的网关前面有反向代理（如 Caddy, Nginx, Cloudflare）时，
// 必须将这些代理的 IP 地址加入此列表，以便网关能正确获取客户端真实 IP。
"trustedProxies": ["127.0.0.1", "::1"]
},
// -------------------------------------------
// 2. Agents 智能体配置
// -------------------------------------------
"agents": {
// 默认智能体的行为配置
"defaults": {
// 智能体的工作目录
"workspace": "~/.openclaw/workspace",
// AI 模型配置
"model": {
// 主要模型。格式为 "提供商/模型名"
"primary": "anthropic/claude-sonnet-4-5",
// 备用模型，当主模型不可用时自动切换
"fallbacks": ["openai/gpt-5.2"]
},
// 模型生成文本的随机性。0.2 平衡了逻辑性和稳定性，适合日常使用。
"temperature": 0.2,
// 安全沙箱配置
"sandbox": {
// 沙箱模式。强烈推荐生产环境设为 "non-main" 或 "full"。
// "non-main": 为非核心任务提供隔离环境
"mode": "non-main"
},
// 智能体技能集配置
"skills": {
// 允许启用的技能白名单
"allowBundled": ["gemini", "peekaboo"]
},
// 心跳任务，让智能体定时在后台执行操作
"heartbeat": {
// 执行间隔，例如 "30m" 代表 30 分钟
"every": "30m",
// 结果发送目标，"last" 表示发送到最后一次对话的窗口
"target": "last"
}
},
// 多智能体配置列表
"list": [
// 示例：定义一个名为 "writer" 的智能体，它将继承 defaults 的配置
{ "id": "writer" },
// 示例：定义一个名为 "docs" 的智能体，并覆盖其 skills 配置
{ "id": "docs", "skills": ["docs-search"] }
]
},
// -------------------------------------------
// 3. Models 模型配置
// -------------------------------------------
"models": {
// 配置合并模式。"merge": 与内置模型列表合并；"replace": 完全替换。
"mode": "merge",
// 模型提供商配置
"providers": {
// 以 OpenAI 为例
"openai": {
// API 密钥，强烈建议使用环境变量引用，提高安全性
"apiKey": "$OPENAI_API_KEY",
// 可用的模型列表
"models": ["gpt-4o", "gpt-4-turbo"]
},
// 以 Anthropic 为例
"anthropic": {
"apiKey": "$ANTHROPIC_API_KEY",
"models": ["claude-3-opus-20240229"]
}
}
},
// -------------------------------------------
// 4. Channels 消息渠道配置
// -------------------------------------------
"channels": {
// 以 Telegram 为例
"telegram": {
// 机器人 Token
"botToken": "$TELEGRAM_BOT_TOKEN",
// 私聊策略。"pairing": 未知用户需管理员批准
"dmPolicy": "pairing",
// 群组策略
"groupPolicy": "allowlist",
// 允许的用户或群组 ID 列表
"allowFrom": ["@myusername"]
},
// 以 WhatsApp 为例
"whatsapp": {
"dmPolicy": "pairing"
},
// 可以为不同渠道指定不同的 AI 模型
"modelByChannel": {
"telegram": "gpt-4o"
}
},
// -------------------------------------------
// 5. Session 会话配置
// -------------------------------------------
"session": {
// 会话重置规则
"reset": {
// 会话空闲多久后自动重置，单位分钟。例如，24小时无活动则开启新会话
"idleMinutes": 1440
}
},
// -------------------------------------------
// 6. Tools 工具配置
// -------------------------------------------
"tools": {
// 工具允许列表
"allow": [
// 允许使用名为 "workflow_tool" 的工具
"workflow_tool",
// 允许使用 "workflow" 插件的所有工具
"workflow"
]
},
// -------------------------------------------
// 7. Skills 技能配置
// -------------------------------------------
"skills": {
// 允许的内置技能白名单
"allowBundled": ["gemini", "peekaboo"],
// 技能加载配置
"load": {
// 额外的技能扫描目录
"extraDirs": ["~/Projects/agent-scripts/skills"],
// 是否监视技能目录的变化并自动刷新
"watch": true,
// 监视事件的防抖延迟，单位毫秒
"watchDebounceMs": 250
},
// 技能安装偏好
"install": {
// 在可用时优先使用 brew 安装器
"preferBrew": true,
// Node 包管理器偏好
"nodeManager": "npm"
},
// 单个技能的详细配置
"entries": {
"nano-banana-pro": {
// 是否启用该技能
"enabled": true,
// 为技能注入 API Key 等环境变量
"env": {
"GEMINI_API_KEY": "YOUR_GEMINI_KEY_HERE"
}
}
}
},
// -------------------------------------------
// 8. Cron 定时任务配置
// -------------------------------------------
"cron": [
{
// 任务唯一标识符
"id": "morning-report",
// Cron 表达式，例如：每天上午9点执行
"schedule": "0 9 * * *",
// 定时任务要执行的消息内容
"payload": {
"type": "message",
"text": "生成今日工作报告"
},
// 执行该任务的智能体
"agent": "main"
}
],
// -------------------------------------------
// 9. Plugins 插件配置
// -------------------------------------------
"plugins": {
// 全局插件允许列表
"allow": ["memory-core", "telegram"],
// 单个插件的详细配置
"entries": {
"antenna": {
"enabled": true
}
}
},
// -------------------------------------------
// 10. Memory 记忆系统配置
// -------------------------------------------
"memory": {
// 记忆插件的配置，由具体插件决定
"config": {
"mode": "auto"
}
},
// -------------------------------------------
// 11. Approvals 操作审批配置
// -------------------------------------------
"approvals": {
// 需要审批的操作列表
"requiredFor": ["delete-file", "run-command"]
},
// -------------------------------------------
// 12. Logging 日志配置
// -------------------------------------------
"logging": {
// 日志级别："debug", "info", "warn", "error"
"level": "info",
// 日志文件路径
"file": "~/.openclaw/logs/openclaw.log"
},
// -------------------------------------------
// 13. Diagnostics 诊断配置
// -------------------------------------------
"diagnostics": {
// 是否启用调试模式
"debug": false
},
// 可选：为编辑器提供 JSON Schema 支持，以获得自动补全和校验
"$schema": "https://raw.githubusercontent.com/openclaw/schema/main/openclaw.json"
}
1. 🤖 Agents：智能体的核心
agents 部分定义了智能体（也就是你的 AI 助手）的行为。
agents.defaults(对象)- 用途：定义所有智能体的“出厂设置”，是 AI 行为的核心配置。
model(对象)：指定智能体使用的 AI 模型。primary(字符串)：主模型，例如"anthropic/claude-sonnet-4-5"。fallbacks(字符串数组)：主模型不可用时的备用模型列表，例如["openai/gpt-5.2"]。
temperature(数字)：控制 AI 回复的随机性。数值越高（接近 1.0）回复越有创意但也可能“发疯”，越低（接近 0.1）回复越严谨可靠。日常使用推荐** 0.2**，以平衡逻辑性和稳定性。workspace(字符串)：智能体的工作目录，用于存放文件和数据，例如"~/.openclaw/workspace"。sandbox(对象)：安全沙箱配置，强烈推荐开启。mode(字符串)：沙箱模式。推荐新手使用"non-main"，为非核心任务提供隔离环境，防止意外操作影响主机。
heartbeat(对象)：心跳任务，让智能体定时在后台执行特定操作。every(字符串)：执行间隔，如"30m"（30分钟）。target(字符串)：结果发送目标，"last"表示发送到最后一次对话的窗口。
agents.list(数组，可选)- 用途：配置多个独立的智能体。每个智能体可以有自己的名字、工作区和模型，实现任务分离。
2. 🧠 Models：连接 AI 大脑
models 部分定义了 OpenClaw 可以连接哪些 AI 模型，这是 AI 能力的来源。
models.mode(字符串)- 用途：控制如何合并配置与 OpenClaw 内置的模型列表。
"merge"(推荐)：将你的配置与内置列表合并，保留所有模型。"replace"：完全用你的配置替换内置列表，只使用你指定的模型。
models.providers(对象)- 用途：在此对象下为每个 AI 服务商（如 OpenAI）创建一个键，详细配置连接信息。
- 常用参数：
apiKey(字符串/SecretInput)：API 密钥，推荐使用环境变量（如$OPENAI_API_KEY）提高安全性。baseUrl(字符串，可选)：自定义 API 地址，用于使用代理或第三方兼容服务。models(数组)：该服务商下可用的模型列表，例如["gpt-4o", "gpt-4-turbo"]。
3. 💬 Channels：连接聊天平台
channels 部分配置 OpenClaw 接入的聊天平台（如 WhatsApp, Telegram, Discord）。
- 通用访问控制 (Access Control)
- 每个渠道都通过 DM Policy 和 Group Policy 来严格控制谁可以和 AI 对话。
"pairing"(推荐)：未知用户会收到一个一次性配对码，需要管理员批准后才能对话。"allowlist"：只允许allowFrom列表中指定的用户或群组。"open"：允许任何人发起对话，生产环境不推荐。"disabled"：完全忽略此类型的消息。
- 渠道特定配置
- 不同渠道的配置字段各不相同，需要查阅官方文档。
4. 🌐 Gateway：网络与 API 服务
gateway 部分控制 OpenClaw 的网络服务，包括 Web UI 和 API。
gateway.port(数字)：服务监听的端口，默认是18789。gateway.auth(对象)：API 认证配置。生产环境必须启用以保证安全。mode(字符串)：认证模式，推荐"token"。token(字符串)：用于 API 调用的强令牌，可通过openclaw doctor --generate-gateway-token生成。
gateway.reload(对象)：配置热重载模式。mode(字符串)："hybrid"（安全热应用，关键变更重启，推荐）、"hot"（仅热应用安全变更）、"off"（关闭热重载）。
5. ⚙️ 其他功能模块 (Tools, Skills, Session, Cron, Plugins)
tools(对象)：用于开启、关闭或配置智能体能使用的底层功能（如读取文件、执行命令、网页搜索）的权限。skills(对象)：技能系统，是封装好的高级工作流。allowBundled(数组)：启用指定的内置技能白名单。entries.<skillKey>(对象)：单独配置某个技能的启用状态或环境变量，例如"enabled": true。
session(对象)：管理会话状态和记忆。reset(对象)：会话重置规则，例如设置idleMinutes在一段时间无活动后自动开启新会话。
cron(数组)：定义定时任务，让智能体在指定时间自动执行操作。- 包含
id,schedule（cron 表达式）,payload（要执行的任务详情）等字段。
- 包含
plugins(对象)：管理第三方插件。entries.<pluginId>(对象)：配置已安装插件的启用状态和专有参数。
memory(对象)：配置长期记忆系统。approvals(对象)：配置人工审批流程，在执行高风险操作前请求批准。sandbox(对象)：配置执行环境的安全隔离级别，强烈建议生产环境启用。logging(对象)：控制日志输出级别和文件位置。diagnostics(对象)：为开发者提供的调试诊断标志。
🔧 关键配置详解
gateway.mode: 生产环境必须设为local，否则网关会拒绝启动。这是确保基础安全的第一步。gateway.trustedProxies: 如果你在网关前使用了 Nginx 或 Caddy 等反向代理，必须将代理服务器的 IP 添加到此列表。这能确保网关获取到的是客户端的真实 IP，而不是代理服务器的 IP，对于日志分析和安全策略至关重要。gateway.auth.token: 这是生产环境的核心安全配置。设置一个强 token 后，任何客户端（包括 Mission Control）连接你的网关时都必须提供此 token。controlUi.dangerouslyDisableDeviceAuth: 这个选项名称已经说明了它的危险性。只有当你的网关被外部系统（如 Mission Control）完全管理时，才考虑启用。一般情况下，请让它保持默认状态（即不配置此项）。
✅ 配置验证与生效
修改 openclaw.json 后，建议按以下步骤进行验证和重启：
bash
# 1. 检查配置文件是否存在语法错误
openclaw doctor
# 2. 如果 doctor 报告无致命错误，重启网关
openclaw gateway restart
# 3. 查看实时日志，确认网关正常启动
openclaw logs
希望这份详尽到每一行的指南能帮你彻底掌握 openclaw.json 的配置。