配置与目录结构：把 OpenClaw 配成你想要的样子

想象一下：你刚搬进一个新房子，家具都堆在客厅里，厨房里锅碗瓢盆还没拆封。这时候你最需要的是什么？不是急着做饭，而是先搞清楚——什么东西放哪儿、怎么开关、出了问题找谁。

OpenClaw 也是这么回事。这一章不讲什么高深原理，就教你三件事：改哪里能生效、出了问题去哪看、以及怎么配才不容易翻车。

本章你将学会什么

理解配置生效顺序与热更新边界。
掌握 workspace 与 state 目录的职责划分。
正确使用环境变量与配置替换，避免把密钥写死。
搭建”家用 / 公司 / 云主机”三套最小配置策略。
用 config + doctor + status 做配置变更验收。

读者前置

你已经完成第 2 章安装与首轮对话。
你可以运行：

openclaw status

openclaw config get agents.defaults.workspace

5.1 配置的分层与生效顺序

5.1.1 一切从 `~/.openclaw/openclaw.json` 开始

OpenClaw 启动时，会先找一个”总开关清单”，这个文件就是：

~/.openclaw/openclaw.json

你可以把它想象成你家的电箱总闸——所有重要开关都集中在这里。

如果这个文件不存在，OpenClaw 会用一套”安全默认值”勉强启动
但长期使用的话，建议把关键配置项亲手写进去，这样以后想改什么、想迁移到别的机器，一目了然

这里的 ~ 是 home 目录的简写。Windows 用户对应的是 C:\Users\你的用户名，Mac/Linux 用户对应的是 /home/你的用户名。

5.1.2 推荐修改方式：小步改、可回退

新手最容易犯的错：一上来就把 openclaw.json 整个重写一遍。结果不是语法写错，就是结构对不上，OpenClaw 直接罢工。

更安全的做法是：用命令行一条一条改。

比如你想改网关端口，可以这样：

# 先看看当前端口是多少
openclaw config get gateway.port

# 改成 18789
openclaw config set gateway.port 18789 --json

# 不想要这个配置了？删掉它
openclaw config unset tools.web.search.apiKey

为什么要这么麻烦？想象一下：

手改 JSON 就像一次性换掉家里所有电线——一不小心就跳闸
命令行改就像换个灯泡——换错了？再换回来呗

5.1.3 严格校验是朋友，不是敌人

OpenClaw 的配置校验是严格模式。啥意思？

你写错一个字段名？对不起，启动失败
你用了一个已经废弃的配置项？对不起，启动失败
你结构写得不对？对不起，启动失败

这看起来很烦人，但实际上是在保护你。想想看，要是因为配置写错了导致 OpenClaw 偷偷用错误配置运行，结果生成了一堆乱码文件——那才叫欲哭无泪。

遇到校验失败怎么办？别硬撑，跑这个命令：

openclaw doctor

doctor 会帮你诊断哪里出了问题，甚至给出修复建议。它就像你家楼下的社区医生——小毛病自己解决，解决不了的会告诉你该去哪个大医院。

5.2 目录结构与数据落盘

5.2.1 先分清两棵树：workspace vs state

这是最最最关键的概念，没有之一。

目录	名字	放什么	比喻
workspace	工作区	你写的文档、脚本、技能、项目文件	你的办公桌
state	状态区	会话记录、API 密钥、插件、日志	你的保险柜

新手常见误区：把 state 当成 workspace 的备份仓库，每次备份就把整个 ~/.openclaw 打包带走。

后果：你的 API Key、你的会话历史、你的登录凭证，全部被”备份”到了不安全的地方。某天你在群里分享这个备份包…恭喜你，密钥泄露了。

一个简单记法：

workspace = 办公桌（可以让人看）
state = 保险柜（除了你自己，谁都不能看）

5.2.2 workspace 不是硬隔离沙箱

官方文档里特别强调了一点：workspace 是默认工作目录，但不是硬隔离的沙箱。

这是啥意思？

你在 workspace 里用相对路径（比如 ./myfile.txt），文件确实在 workspace 里
但如果你用绝对路径（比如 /etc/passwd），OpenClaw 仍然能访问——它可不会帮你挡住

想要真正的硬隔离？需要配合沙箱策略，这个我们在第 4 章详细讲过。

5.2.3 关键路径速查

下面这些路径，你以后会经常打交道。建议收藏：

用途	路径
主配置文件	`~/.openclaw/openclaw.json`
会话记录	`~/.openclaw/agents/<agentId>/sessions/`
凭证（API Key 等）	`~/.openclaw/credentials/`
托管技能	`~/.openclaw/skills/`
插件	`~/.openclaw/extensions/`

这里的 <agentId> 是个占位符，实际使用时你会看到一个类似 agent-xxxx 的文件夹名。

5.3 环境变量与敏感信息

5.3.1 优先环境变量，避免硬编码

如果你用过 ChatGPT 或者其他 AI 服务，你应该知道要用 API Key 来付费。这个 Key 绝对不能直接写在配置文件里，否则：

你把配置文件发给别人做技术讨论——Key 泄露
你把项目上传到 GitHub——Key 泄露
你重装系统忘记备份——Key 丢失

正确做法：走环境变量。

OpenClaw 支持读取这些环境变量：

ZAI_API_KEY —— 调用 Z.AI 模型时用
MOONSHOT_API_KEY —— 调用 Moonshot 模型时用
MINIMAX_API_KEY —— 调用 MiniMax 模型时用

怎么设？在终端里运行：

# Mac/Linux 用户
export ZAI_API_KEY="你的Key"

# Windows 用户（CMD）
set ZAI_API_KEY=你的Key

# Windows 用户（PowerShell）
$env:ZAI_API_KEY="你的Key"

小技巧：如果你用的是 minimax/MiniMax-M2.5 或 moonshot/kimi-k2.5 模型，记得对应设置相应的环境变量。

5.3.2 配置中的变量替换

OpenClaw 的配置文件支持”从环境变量里取值”。你可以这样写：

{
  "gateway": {
    "apiKey": "${ZAI_API_KEY}"
  }
}

这样配置文件里就不需要写死 Key 了，OpenClaw 启动时会自动去环境变量里找。

一个简单的原则：

能公开的参数 → 放配置文件（比如端口号、功能开关）
敏感的值 → 放环境变量（比如 Key、密码）
永远不要把 Key 写进 README.md、AGENTS.md、或者截图里

5.3.3 权限收紧与检查

你的配置文件和 state 目录里装的都是”身家性命”，可得保护好。

# 配置文件权限设为 600（只有你能读能写）
chmod 600 ~/.openclaw/openclaw.json

# state 目录权限设为 700（只有你能进）
chmod 700 ~/.openclaw

改完以后，务必跑一下：

openclaw security audit

这就像请了个保安来你家巡逻一圈，看看有没有哪扇门没锁好。

5.4 多环境策略（家用/公司/云主机）

不同场景下，OpenClaw 的”最优解”不一样。这一节帮你配好三套常用配置。

5.4.1 家用环境（单人、低风险）

场景：你在自己电脑上跑着玩，主要用来查资料、写代码、辅助学习。

目标：快、稳、不惹事。

建议配置：

{
  "gateway": {
    "mode": "local"
  },
  "agents": {
    "defaults": {
      "dm": "pairing",
      "sandbox": {
        "tools": {
          "deny": ["group:runtime"]
        }
      }
    }
  }
}

人话解释：

gateway.mode: local —— 不走远程服务器，就在自己电脑上跑
dm: "pairing" —— 每次对话都重新配对，安全一点
deny: ["group:runtime"] —— 禁止执行”运行态”工具（比如执行系统命令），避免不小心搞坏电脑

5.4.2 公司环境（多人协作）

场景：团队里好几个人共用 OpenClaw，需要分工、权限隔离、出了问题能追溯。

目标：可追溯、权限清、别乱套。

建议配置：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "tools": {
          "requireApproval": ["group:write", "group:runtime"]
        }
      }
    }
  },
  "workspace": {
    "storage": "private-repo"
  }
}

人话解释：

requireApproval: ["group:write", "group:runtime"] —— 写文件、执行命令这种”危险操作”，必须有人审批才能执行
storage: "private-repo" —— workspace 存到私有仓库里（但注意：别把 credentials 目录一起存进去）

5.4.3 云主机环境（远程长期运行）

场景：你在云服务器上部署 OpenClaw，7×24 小时跑着做自动化任务。

目标：别挂掉、挂了能救回来、数据别丢。

建议配置：

{
  "gateway": {
    "mode": "service",
    "healthCheck": {
      "enabled": true,
      "interval": 60
    },
    "port": 18789,
    "firewall": {
      "enabled": true,
      "allowedIPs": ["你的IP"]
    }
  },
  "backup": {
    "config": true,
    "sessions": true,
    "excludeCredentials": true
  }
}

人话解释：

mode: "service" —— 以系统服务方式运行，关掉终端也不影响
healthCheck: { enabled: true } —— 每 60 秒自检一次，挂了会自己报警
firewall —— 只允许你的 IP 访问，陌生人别想进来
backup —— 定期备份配置和会话，但不备份凭证（凭证丢了是小事，备份泄露了才要命）

5.5 配置变更的验证方式

5.5.1 变更后立即做三步验收

改完配置后，别急着去干别的。先跑三句话，确认一切正常：

第一步：读配置

openclaw config get agents.defaults

确认你改的值确实写进去了。

第二步：看运行态

openclaw gateway status

确认网关正在正常运行，没有罢工。

第三步：看诊断

openclaw doctor

确认没有隐藏的配置冲突或警告。

这三步就像去医院体检——心电图、血压、血常规都查一遍，没问题就放心。

5.5.2 变更日志建议

每次改配置，建议在笔记本或者笔记软件里记一下：

时间	改了什么	为什么改	怎么回滚
2026-02-09	gateway.port 改成 18789	避免和 8080 冲突	`openclaw config set gateway.port 8080`

这个习惯能救你的命——尤其是配置改多了以后，你根本记不得三个月前那个 deny 到底设的是 true 还是 false。

5.5.3 你可以直接复用的”安全变更流程”

备份配置 -> 改一项 -> 重启/热应用 -> status/doctor 验证 -> 留回滚点

具体操作：

# 1. 备份
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup-$(date +%Y%m%d)

# 2. 改一项（别贪多）
openclaw config set gateway.port 18789 --json

# 3. 重启网关
openclaw gateway restart

# 4. 验证
openclaw status
openclaw doctor

# 5. 如果出问题，回滚
cp ~/.openclaw/openclaw.json.backup-20260209 ~/.openclaw/openclaw.json
openclaw gateway restart

核心原则：一次只改一项。

这就像换轮胎——你不会同时拆四个轮子吧？万一哪个拧不紧，车就趴窝了。配置也是一个道理。

本章小结

配置管理的核心是可追踪 + 可回滚，不是”写得炫”。
workspace 和 state 必须分清——办公桌和保险柜，别混为一谈。
环境变量是保护 API Key 的第一道防线，能用环境变量就別硬编码。
三种部署环境（家用/公司/云）关注点不同，但都要坚持小步变更 + 立即验证。
遇到问题先跑 doctor，它比你自己排查更靠谱。

下一步可以干什么？

试着运行 openclaw config get gateway 看看当前配置

用 openclaw doctor 给你的环境做个体检

如果你想深入了解某个工具的权限配置，可以跳到第 6 章

配置与目录结构：把 OpenClaw 配成你想要的样子

本章你将学会什么

读者前置

5.1 配置的分层与生效顺序

5.1.1 一切从 ~/.openclaw/openclaw.json 开始

5.1.2 推荐修改方式：小步改、可回退

5.1.3 严格校验是朋友，不是敌人

5.2 目录结构与数据落盘

5.2.1 先分清两棵树：workspace vs state

5.2.2 workspace 不是硬隔离沙箱

5.2.3 关键路径速查

5.3 环境变量与敏感信息

5.3.1 优先环境变量，避免硬编码

5.3.2 配置中的变量替换

5.3.3 权限收紧与检查

5.4 多环境策略（家用/公司/云主机）

5.4.1 家用环境（单人、低风险）

5.4.2 公司环境（多人协作）

5.4.3 云主机环境（远程长期运行）

5.5 配置变更的验证方式

5.5.1 变更后立即做三步验收

5.5.2 变更日志建议

5.5.3 你可以直接复用的”安全变更流程”

本章小结

5.1.1 一切从 `~/.openclaw/openclaw.json` 开始