收藏！OpenClaw 配置文件保姆级详解｜从入门到精通，避坑 + 优化全搞定

码龙手记
36 阅读6分钟

做 OpenClaw 开发 / 部署的同学，是不是都被配置文件难住过？改个参数就报错、API 密钥明文存储有风险、配置修改后不生效、不知道怎么优化性能…… 明明代码没问题，却因为配置踩了无数坑，甚至直接导致服务启动失败。

今天整理了一份OpenClaw 配置文件终极指南，覆盖目录结构、核心配置项、常用命令、最佳实践、故障排查，100% 专业准确，新手能照着配，老手能查细节，收藏起来，再也不用到处找零散的配置教程！

📂 一、先搞懂：OpenClaw 配置目录结构（核心存储位置）

OpenClaw 的所有核心配置、数据、日志都集中在用户主目录下的 .openclaw 目录，先记牢这个结构，找文件不迷路：

bash

运行

~/.openclaw/
├── openclaw.json          # 核心主配置文件（重中之重）
├── openclaw.json.bak      # 配置文件备份（修改前必看）
├── agents/                # Agent专属配置目录
├── credentials/           # 敏感信息存储（密钥、凭证）
├── workspace/             # Agent工作区（临时文件、产出）
├── skills/                # 技能包目录（自定义技能存放）
├── logs/                  # 日志文件（排查问题必看）
└── ...                    # 其他辅助文件

关键提醒：修改任何配置前，先手动备份 openclaw.json，避免配置改错无法回滚！

🔧 二、核心配置：openclaw.json 逐行拆解（重点中的重点）

openclaw.json 是 OpenClaw 的核心配置文件，涵盖模型、Agent、通信、网关等所有关键设置，下面按模块拆解，每个参数都讲透用途和最佳值：

2.1 模型与提供商配置（AI 大脑设置）

定义你要使用的大模型（如 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。

2.2 Agent 配置（AI 助手行为设置）

定义 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 分钟间隔兼顾性能和稳定性。

2.3 通信渠道配置（安全第一！）

定义微信、Telegram、WhatsApp 等 IM 渠道的访问权限，安全配置不到位，容易被滥用：

json

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+8613800000000"],  // 白名单：仅允许指定号码访问
      "groupPolicy": "allowlist"  // 群组策略：仅允许白名单群组
    },
    "telegram": {
      "allowFrom": ["@username"]  // 白名单：仅允许指定Telegram用户
    }
  }
}

安全必做：

  • allowFrom：必须设置！否则任何人都能通过 IM 渠道调用你的 Agent，造成数据泄露或资源浪费；
  • groupPolicy：生产环境必选allowlist，仅开放指定群组。

2.4 网关配置（API 接口设置）

定义 OpenClaw 的网关服务端口和绑定地址，影响访问范围：

json

{
  "gateway": {
    "port": 18789,  // 默认端口（建议保留，避免冲突）
    "bind": "127.0.0.1"  // 仅绑定本地地址（生产环境必选，禁止绑定0.0.0.0）
  }
}

安全提醒：bind 不要设为0.0.0.0（允许外网访问），除非你做好了认证和防火墙策略！

2.5 会话管理（记忆与重置）

定义会话的重置规则，避免长期运行导致内存占用过高：

json

{
  "session": {
    "reset": {
      "dailyTime": "04:00",  // 每日重置时间（选凌晨低峰期，如4点）
      "mode": "idle"  // 仅在空闲时重置（避免打断正在执行的任务）
    }
  }
}

⌨️ 三、常用配置命令（不用手动改文件，效率翻倍）

OpenClaw 提供了专门的配置命令，不用每次都打开openclaw.json编辑，既方便又能避免语法错误：

3.1 核心命令速查表

表格

命令功能说明
openclaw config查看所有配置项（完整输出）
openclaw config get <key>获取指定配置项（如模型 ID）
openclaw config set <key> <val>设置配置项（无需改 JSON）
openclaw config unset <key>删除指定配置项
openclaw config edit直接打开配置文件编辑（推荐）
openclaw config validate验证配置文件语法（排错必用）

3.2 实战命令示例（直接复制用）

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

🚀 四、最佳实践指南（避坑 + 优化，生产环境必看）

4.1 安全配置（重中之重）

  1. API 密钥管理（绝对不要明文存储）

    • 用环境变量引用（如$MOONSHOT_API_KEY），部署时通过export MOONSHOT_API_KEY=xxx注入；
    • 定期轮换密钥，设置最小权限（比如仅允许模型调用，禁止管理操作）；
    • 密钥存储在~/.openclaw/credentials/目录，不要提交到代码仓库。

  2. 访问控制（防止滥用）

    json

    {
  "channels": {
    "whatsapp": {
      "allowFrom": ["+8613800000000"],  // 仅开放自己的号码
      "groupPolicy": "allowlist",  // 仅允许白名单群组
      "tools": {
        "default-deny": true  // 默认禁止所有工具，仅开放必要的
      }
    }
  }
}

4.2 性能优化（提升运行效率）

json

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,  // 保留足够Token，避免频繁压缩
        "maxContextTokens": 200000  // 根据模型调整上下文上限
      },
      "temperature": 0.3,  // 降低随机性，提升回答精准度
      "maxConcurrent": 4  // 控制并发，避免资源耗尽
    }
  }
}

4.3 部署注意事项

  1. Docker 部署

    • 数据卷挂载路径：/app/data（对应本地~/.openclaw）；
    • 确保配置文件权限：chmod 600 ~/.openclaw/openclaw.json（仅自己可读写）；

  2. 备份策略（必做）

    bash

    运行

    # 手动备份配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
# 定时备份（推荐加入crontab）
0 0 * * * cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.`date +%Y%m%d`

🚨 五、故障排查指南（配置报错不用慌）

5.1 常见问题及解决方法

表格

问题现象排查步骤
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是否设得太小；

5.2 调试技巧（快速定位问题）

  1. 启用详细日志（排错必开）

    json

    {
  "debug": true,
  "logLevel": "verbose"  // 日志级别：verbose/info/warn/error
}

  2. 配置验证（提前发现错误）

    bash

    运行

    openclaw config validate  # 验证语法
openclaw gateway check    # 检查网关配置

📝 六、扩展配置示例（满足个性化需求）

6.1 多模型配置（切换不同模型）

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
  }
}

6.2 自定义技能配置（扩展 Agent 能力）

json

{
  "skills": {
    "custom": {
      "enabled": true,
      "path": "~/.openclaw/custom_skills"  // 自定义技能存放目录
    }
  }
}

6.3 完整配置示例（直接复用）

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 配置排错实战》，手把手教你解决，还会附赠生产环境最优配置模板！

总结

  1. OpenClaw 核心配置文件是~/.openclaw/openclaw.json，修改前务必备份，改后需重启网关生效；
  2. 安全配置是重中之重：API 密钥用环境变量、通信渠道设白名单、网关仅绑定本地地址；
  3. 性能优化关键：合理设置会话压缩、心跳间隔、并发数，根据业务调整模型参数；
  4. 配置报错先验证语法，再查看日志，启用详细日志能快速定位问题。
avatar
文章
阅读
粉丝