配置与目录结构：把 OpenClaw 配成你想要的样子
OpenClaw 能不能稳，很多时候不靠“玄学调参”，而靠配置和目录是不是清楚。
这一章不讲花活，只讲三件实在事：改哪里、为什么生效、出问题去哪找。
本章你将学会什么
Section titled “本章你将学会什么”- 理解配置生效顺序与热更新边界。
- 掌握 workspace 与 state 目录的职责划分。
- 正确使用环境变量与配置替换，避免把密钥写死。
- 搭建“家用 / 公司 / 云主机”三套最小配置策略。
- 用
config + doctor + status做配置变更验收。
- 你已经完成第 2 章安装与首轮对话。
- 你可以运行：
openclaw statusopenclaw config get agents.defaults.workspace5.1 配置的分层与生效顺序
Section titled “5.1 配置的分层与生效顺序”5.1.1 一切从 ~/.openclaw/openclaw.json 开始
Section titled “5.1.1 一切从 ~/.openclaw/openclaw.json 开始”OpenClaw 主配置文件是：
~/.openclaw/openclaw.json
你可以把它当成“总开关清单”。
缺省时系统会用安全默认值启动，但真正长期使用时，建议把关键项显式写出来，后续检查和迁移都省心。
5.1.2 推荐修改方式：小步改、可回退
Section titled “5.1.2 推荐修改方式：小步改、可回退”优先用 CLI 改单项：
openclaw config get gateway.portopenclaw config set gateway.port 18789 --jsonopenclaw config unset tools.web.search.apiKey这样比“手改大段 JSON”更不容易手滑引入语法或结构错误。
5.1.3 严格校验是朋友，不是敌人
Section titled “5.1.3 严格校验是朋友，不是敌人”官方配置校验是严格模式。
遇到历史字段或不兼容结构时，优先跑：
openclaw doctor不要绕过校验去“强行启动”，否则问题只会被延后，而且更隐蔽。
5.2 目录结构与数据落盘
Section titled “5.2 目录结构与数据落盘”5.2.1 先分清两棵树：workspace vs state
Section titled “5.2.1 先分清两棵树：workspace vs state”- workspace：你的工作目录（文档、脚本、技能、项目文件）。
- state（默认
~/.openclaw）：会话、凭证、日志、插件、内部状态。
新手常见误解是把 state 当 workspace 备份仓库，这样做很容易把敏感信息一并带出去。
一个简单记法：workspace 像你的“工作台”，state 像“保险柜”，别把保险柜内容随手打包外传。
5.2.2 workspace 不是硬隔离沙箱
Section titled “5.2.2 workspace 不是硬隔离沙箱”官方文档强调：workspace 是默认 cwd，不是硬隔离。
相对路径在 workspace 下解析，但绝对路径仍可能越界访问。
要硬隔离，需要沙箱策略配合（见第 4 章）。
5.2.3 关键路径速查
Section titled “5.2.3 关键路径速查”- 配置：
~/.openclaw/openclaw.json - 会话：
~/.openclaw/agents/<agentId>/sessions/ - 凭证：
~/.openclaw/credentials/ - 托管技能：
~/.openclaw/skills/ - 插件：
~/.openclaw/extensions/
5.3 环境变量与敏感信息
Section titled “5.3 环境变量与敏感信息”5.3.1 优先环境变量，避免硬编码
Section titled “5.3.1 优先环境变量，避免硬编码”模型 Key 建议走环境变量（如 ZAI_API_KEY、MOONSHOT_API_KEY、MINIMAX_API_KEY）。
这样做的好处很直接：换 Key 不用改业务文件，多环境也不容易串。
5.3.2 配置中的变量替换
Section titled “5.3.2 配置中的变量替换”配置支持 env substitution。
建议规则：
- 可公开参数放配置；
- 敏感值放环境变量；
- 绝不把密钥写进
README、AGENTS.md或示例截图。
5.3.3 权限收紧与检查
Section titled “5.3.3 权限收紧与检查”配置文件建议权限 600，state 目录建议 700。
变更后执行：
openclaw security audit5.4 多环境策略（家用/公司/云主机）
Section titled “5.4 多环境策略（家用/公司/云主机）”5.4.1 家用环境（单人、低风险）
Section titled “5.4.1 家用环境（单人、低风险）”目标：快速稳定。
建议：
gateway.mode: local- DM 使用
pairing - 工具默认 deny
group:runtime
5.4.2 公司环境（多人协作）
Section titled “5.4.2 公司环境（多人协作）”目标：可追溯与权限隔离。
建议：
- 多 agent + 多 workspace 拆分职责；
- 所有高风险执行启用审批；
- 使用私有仓库存储 workspace（不含凭证）。
5.4.3 云主机环境（远程长期运行）
Section titled “5.4.3 云主机环境（远程长期运行）”目标：高可用与可恢复。
建议：
- 开启服务守护与健康检查；
- 固化端口、防火墙、网关鉴权；
- 定期备份
openclaw.json与 sessions（脱敏后）。
5.5 配置变更的验证方式
Section titled “5.5 配置变更的验证方式”5.5.1 变更后立即做三步验收
Section titled “5.5.1 变更后立即做三步验收”- 读配置：
openclaw config get agents.defaults- 看运行态：
openclaw gateway status- 看诊断：
openclaw doctor5.5.2 变更日志建议
Section titled “5.5.2 变更日志建议”每次改配置都记录三件事：
- 改了什么；
- 为什么改；
- 如何回滚。
这会在后续排障时帮你省下大量时间。
5.5.3 你可以直接复用的“安全变更流程”
Section titled “5.5.3 你可以直接复用的“安全变更流程””备份配置 -> 改一项 -> 重启/热应用 -> status/doctor 验证 -> 留回滚点不要一次改十项。
“每次只改一项”是对新手最友好的稳定性策略：出事时你能立刻知道是哪一项惹的祸。
- 配置管理的核心是可追踪与可回滚，不是“写得炫”。
- workspace 与 state 职责必须分离，敏感资产只放 state。
- 环境变量管理好，能大幅降低密钥泄漏概率。
- 三种部署环境关注点不同，但都要坚持“小步变更 + 立即验证”。