聚水潭
118.20M · 2026-03-13
做 OpenClaw 开发 / 部署的同学，是不是都被配置文件难住过？改个参数就报错、API 密钥明文存储有风险、配置修改后不生效、不知道怎么优化性能…… 明明代码没问题，却因为配置踩了无数坑，甚至直接导致服务启动失败。
今天整理了一份OpenClaw 配置文件终极指南，覆盖目录结构、核心配置项、常用命令、最佳实践、故障排查，100% 专业准确，新手能照着配，老手能查细节，收藏起来，再也不用到处找零散的配置教程！
OpenClaw 的所有核心配置、数据、日志都集中在用户主目录下的 .openclaw 目录，先记牢这个结构，找文件不迷路：
bash
运行
~/.openclaw/
├── openclaw.json # 核心主配置文件（重中之重）
├── openclaw.json.bak # 配置文件备份（修改前必看）
├── agents/ # Agent专属配置目录
├── credentials/ # 敏感信息存储（密钥、凭证）
├── workspace/ # Agent工作区（临时文件、产出）
├── skills/ # 技能包目录（自定义技能存放）
├── logs/ # 日志文件（排查问题必看）
└── ... # 其他辅助文件
关键提醒：修改任何配置前，先手动备份 openclaw.json，避免配置改错无法回滚！
openclaw.json 是 OpenClaw 的核心配置文件，涵盖模型、Agent、通信、网关等所有关键设置，下面按模块拆解，每个参数都讲透用途和最佳值：
定义你要使用的大模型（如 Kimi、OpenAI、本地 Ollama），是配置的核心模块：
json
{
"models": {
"providers": {
"moonshot": { // 模型提供商ID（自定义，如moonshot/openai/ollama）
"type": "moonshot", // 提供商类型（与ID对应）
"apiKey": "$MOONSHOT_API_KEY", // 推荐用环境变量，避免明文泄露
"baseUrl": "https://api.moonshot.cn/v1", // 国内服务优先用.cn域名
"api": "openai-completions", // 接口协议（兼容OpenAI格式）
"models": [
{
"id": "kimi-k2.5", // 模型ID（服务商提供）
"name": "Kimi K2.5", // 显示名称（自定义）
"contextWindow": 256000, // 上下文窗口（越大能记住的内容越多）
"maxTokens": 8192, // 单次最大输出Token
"temperature": 0.3 // 随机性（0.2-0.5最佳，越低越稳定）
}
]
}
}
}
}
关键参数说明：
apiKey：绝对不要明文存储！用环境变量（如$MOONSHOT_API_KEY），部署时通过系统环境注入；contextWindow：根据业务调整，比如长文本处理选 256000，普通对话选 8192；temperature：追求精准选 0.2，追求创意选 0.5，生产环境建议 0.3。定义 Agent 的工作目录、会话压缩、心跳检测等，影响运行效率和稳定性：
json
{
"agents": {
"defaults": {
"workspace": "~/.openclaw/workspace", // Agent唯一工作目录（存储临时文件）
"compaction": { // 会话压缩：防止上下文过长导致Token超标
"reserveTokensFloor": 20000, // 保留基础Token（至少留2万，避免截断关键内容）
"enabled": true // 开启压缩（必开）
},
"heartbeat": { // 心跳检测：空闲时自动重置，避免内存泄漏
"every": "30m", // 心跳间隔（30分钟一次最佳）
"enabled": true // 开启心跳（必开）
},
"temperature": 0.3 // 继承模型配置，也可单独设置
}
}
}
功能说明：
compaction：会话过长时，自动总结历史消息，只保留关键内容，既省 Token 又不丢信息；heartbeat：长期运行必开，防止 Agent 僵死，30 分钟间隔兼顾性能和稳定性。定义微信、T@elegrimm、WhatsApp 等 IM 渠道的访问权限，安全配置不到位，容易被滥用：
json
{
"channels": {
"whatsapp": {
"allowFrom": ["+8613800000000"], // 白名单：仅允许指定号码访问
"groupPolicy": "allowlist" // 群组策略：仅允许白名单群组
},
"telegram": {
"allowFrom": ["@username"] // 白名单：仅允许指定T@elegrimm用户
}
}
}
安全必做：
allowFrom：必须设置！否则任何人都能通过 IM 渠道调用你的 Agent，造成数据泄露或资源浪费；groupPolicy：生产环境必选allowlist，仅开放指定群组。定义 OpenClaw 的网关服务端口和绑定地址，影响访问范围：
json
{
"gateway": {
"port": 18789, // 默认端口（建议保留，避免冲突）
"bind": "127.0.0.1" // 仅绑定本地地址（生产环境必选，禁止绑定0.0.0.0）
}
}
安全提醒：bind 不要设为0.0.0.0（允许外网访问），除非你做好了认证和防火墙策略！
定义会话的重置规则，避免长期运行导致内存占用过高：
json
{
"session": {
"reset": {
"dailyTime": "04:00", // 每日重置时间（选凌晨低峰期，如4点）
"mode": "idle" // 仅在空闲时重置（避免打断正在执行的任务）
}
}
}
OpenClaw 提供了专门的配置命令，不用每次都打开openclaw.json编辑，既方便又能避免语法错误：
表格
| 命令 | 功能说明 |
|---|---|
openclaw config | 查看所有配置项（完整输出） |
openclaw config get <key> | 获取指定配置项（如模型 ID） |
openclaw config set <key> <val> | 设置配置项（无需改 JSON） |
openclaw config unset <key> | 删除指定配置项 |
openclaw config edit | 直接打开配置文件编辑（推荐） |
openclaw config validate | 验证配置文件语法（排错必用） |
bash
运行
# 1. 查看Agent工作目录配置
openclaw config get agents.defaults.workspace
# 2. 修改心跳检测间隔为2小时（适合长期运行）
openclaw config set agents.defaults.heartbeat.every "2h"
# 3. 设置会话每日重置时间为凌晨3点
openclaw config set session.reset.dailyTime "03:00"
# 4. 验证配置是否有语法错误（修改后必做）
openclaw config validate
# 5. 重启网关使配置生效（修改后必做）
openclaw gateway restart
API 密钥管理（绝对不要明文存储）
$MOONSHOT_API_KEY），部署时通过export MOONSHOT_API_KEY=xxx注入；~/.openclaw/credentials/目录，不要提交到代码仓库。访问控制（防止滥用）
json
{
"channels": {
"whatsapp": {
"allowFrom": ["+8613800000000"], // 仅开放自己的号码
"groupPolicy": "allowlist", // 仅允许白名单群组
"tools": {
"default-deny": true // 默认禁止所有工具，仅开放必要的
}
}
}
}
json
{
"agents": {
"defaults": {
"compaction": {
"reserveTokensFloor": 20000, // 保留足够Token，避免频繁压缩
"maxContextTokens": 200000 // 根据模型调整上下文上限
},
"temperature": 0.3, // 降低随机性，提升回答精准度
"maxConcurrent": 4 // 控制并发，避免资源耗尽
}
}
}
Docker 部署
/app/data（对应本地~/.openclaw）；chmod 600 ~/.openclaw/openclaw.json（仅自己可读写）；备份策略（必做）
bash
运行
# 手动备份配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
# 定时备份（推荐加入crontab）
0 0 * * * cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.`date +%Y%m%d`
表格
| 问题现象 | 排查步骤 |
|---|---|
| API 连接失败 | 1. 检查网络是否能访问baseUrl；2. 验证apiKey是否有效；3. 确认baseUrl是否带/v1等后缀； |
| 配置修改不生效 | 1. 执行openclaw gateway restart重启网关；2. 用openclaw config validate检查语法；3. 查看日志~/.openclaw/logs/； |
| Agent 无响应 | 1. 检查心跳配置是否开启；2. 查看compaction是否过度压缩；3. 检查maxConcurrent是否设得太小； |
启用详细日志（排错必开）
json
{
"debug": true,
"logLevel": "verbose" // 日志级别：verbose/info/warn/error
}
配置验证（提前发现错误）
bash
运行
openclaw config validate # 验证语法
openclaw gateway check # 检查网关配置
json
{
"models": {
"providers": {
"moonshot": { /* Kimi配置 */ },
"openai": {
"type": "openai",
"apiKey": "$OPENAI_API_KEY",
"baseUrl": "https://api.openai.com/v1",
"models": [{"id": "gpt-4o", "name": "GPT-4o"}]
}
},
"primary": "moonshot/kimi-k2.5" // 默认使用Kimi，可随时切换为openai/gpt-4o
}
}
json
{
"skills": {
"custom": {
"enabled": true,
"path": "~/.openclaw/custom_skills" // 自定义技能存放目录
}
}
}
json
{
"models": {
"mode": "merge",
"providers": {
"custom-127-0-0-1-11434": {
"baseUrl": "http://127.0.0.1:11434/v1",
"apiKey": "ollama",
"api": "openai-completions",
"models": [
{
"id": "qwen3.5:9b",
"name": "Qwen3.5 9B (Local)",
"reasoning": false,
"input": ["text"],
"cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
"contextWindow": 32768,
"maxTokens": 8192
}
]
}
}
},
"agents": {
"defaults": {
"model": {"primary": "custom-127-0-0-1-11434/qwen3.5:9b"},
"workspace": "/Users/{用户名}/.openclaw/workspace",
"compaction": {"mode": "safeguard"},
"maxConcurrent": 4,
"subagents": {"maxConcurrent": 8}
}
},
"session": {"dmScope": "per-channel-peer"},
"hooks": {
"internal": {
"enabled": true,
"entries": {"bootstrap-extra-files": {"enabled": true}, "command-logger": {"enabled": true}}
}
},
"channels": {"telegram": {"enabled": false}},
"gateway": {
"port": 18789,
"mode": "local",
"bind": "loopback",
"auth": {"mode": "token"}
},
"skills": {"install": {"nodeManager": "npm"}}
}
你在配置 OpenClaw 时，踩过最坑的一个问题是什么？是 API 密钥配置错误？还是通信渠道访问被限制？或是性能优化没思路？
评论区留下你的配置问题 + 场景，抽 3 个高频问题，下期专门出《OpenClaw 配置排错实战》，手把手教你解决，还会附赠生产环境最优配置模板！
~/.openclaw/openclaw.json，修改前务必备份，改后需重启网关生效；
