你有没有遇到过改了配置文件，结果Gateway直接拒绝启动，半天找不到原因？其实官方早就把解决方案写在文档里了，只是很多人没注意到。
定制放哪里才安全
官方明确推荐，长期定制要把配置放在~/.openclaw/openclaw.json和~/.openclaw/workspace里。这样以后升级软件时，你的个性化设置不会被覆盖。很多用户习惯直接在安装目录里改文件，每次升级都要重新配置一遍，非常麻烦。
workspace目录用来存放skills、prompts、memories这些内容。你可以理解成openclaw.json管规则，workspace管内容。把这两块分开管理后，即使配置文件需要重新生成，你的工作成果也不会丢失。
如果你的需求只是使用最新模型，而不是自己折腾部署环境，也可以直接使用api.
配置文件不是死板的JSON
openclaw.json虽然名字带JSON，但使用体验更接近宽松一点的配置文件。官方文档写得很清楚，未知字段、类型不对、值不合法，Gateway都会拒绝启动。这意味着你不能随便往里填东西，必须按照规范来。
但好消息是官方配置示例里明确支持$include去拆分到.json5文件。你可以把大配置拆成多个小文件管理，比如把渠道配置单独放一个文件，模型配置放另一个文件。这样既保证了规范性，又提升了可维护性。
启动和重载的两种关键设置
Gateway默认会要求gateway.mode=local，否则拒绝启动。本地单机部署时用local模式就够了。端口方面常见的是18789，官方Getting Started也用这个端口来验证Gateway是否正常监听。这两个参数是新手最容易忽略的基础配置。
配置改完要不要重启由gateway.reload控制。官方支持hybrid、hot、restart、off四种模式，默认推荐hybrid。意思是安全的改动就热更新，关键改动就自动重启。OpenClaw的配置文件不是改了必须手动重启的老式玩法，这点很实用。
模型选择的顺序逻辑
OpenClaw选模型时先看agents.defaults.model.primary，再看agents.defaults.model.fallbacks。如果同一个provider内还有认证级别的failover，会先在provider内部切换，再换下一个模型。这个优先级顺序清楚了，你才能准确控制用哪个模型。
如果你想单独给图片、PDF工具配模型，官方也支持imageModel、pdfModel、imageGenerationModel、videoGenerationModel这些独立字段。比如你可以让文字对话用速度快的小模型，图片处理用精度高的大模型，各取所需。
渠道配置的安全边界
每个渠道都放在channels下面，比如channels.telegram、channels.discord、channels.whatsapp等。群里能不能用要看channels.telegram.groups、groupPolicy、groupAllowFrom这些配置，而不是只看你和bot能否成功私聊。很多人卡在这一步，以为私聊通了群聊就自动能用。
exec approvals是沙箱环境去跑真实主机命令时的安全闸门。一旦你让它执行shell、操作真实文件、碰节点主机，这块就会变成最关键的安全边界。官方还提醒，如果没有可用的交互界面而当前请求又需要审批，默认的ask回退策略可能就是拒绝执行。
大配置如何拆分维护
当你开始接多个渠道、多个Agent、多个模型时，openclaw.json很快会变成几百行。官方明确支持$include来拆分配置，而且支持单文件替换、数组深度合并、嵌套include，最多10层。相对路径按包含它的文件来解析，循环引用和缺文件也会给清晰错误。
如果现有配置无效或带legacy keys，官方配置向导甚至会停下来让你先跑openclaw doctor检查。这个doctor命令能帮你找出配置里的问题字段，不用自己一行行排查。建议每次改完大配置都跑一遍，省去启动失败后再调试的时间。
你会不会也在配置OpenClaw时遇到过启动失败或者渠道不响应的问题？欢迎在评论区分享你的踩坑经历，大家一起避雷。觉得有用的话点个赞，让更多人看到正确配置方法。
