OpenClaw 配置详解

概述

OpenClaw 的配置核心并不在某一个命令，而在 ~/.openclaw/openclaw.json 这份主配置文件。

官方文档提到，这是一份可选的 JSON5 配置。也就是说，即便你没有手写任何配置，OpenClaw 也能带着默认值运行；但一旦你开始接模型、配渠道、拆 agent、开工具，这个文件就会变得非常重要。

如果你是第一次认真看 OpenClaw 配置，建议按下面这个顺序理解：

1. 先知道配置文件和目录都放在哪
2. 再理解 agents、models、channels、gateway
3. 最后再看 tools、skills、plugins

这样会比从完整 schema 硬啃轻松很多。

关键文件和目录

OpenClaw 常见的本地目录一般是下面这些：

~/.openclaw/
├── openclaw.json
├── .env
├── workspace/
├── credentials/
├── agents/
├── skills/
├── plugins/
└── memory/

可以先抓住这几个重点：

• openclaw.json：主配置文件
• .env：放 API Key、Token 等敏感信息
• workspace/：助手长期工作的目录
• agents/：多 agent 场景下的个体配置
• credentials/：渠道和认证相关数据

三种常见修改方式

交互式修改

对大多数新手来说，最好上手的是：

openclaw onboard
openclaw configure

前者更适合首次引导，后者更适合后续调整。

命令行单点修改

如果你已经知道自己要改哪一个配置项，可以直接用 config 子命令：

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey

这种方式适合改一个字段，不适合大面积调整。

直接编辑配置文件

最灵活的方式仍然是直接编辑：

~/.openclaw/openclaw.json

官方文档提到，Gateway 会监听配置文件变更并自动应用。但前提是你的配置必须合法，否则 Gateway 可能拒绝启动。

配置文件的基本结构

从日常使用角度看，OpenClaw 配置通常可以概括成这样：

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
      },
    },
  },
  channels: {
    telegram: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
  gateway: {
    port: 18789,
    bind: "loopback",
  },
}

你不需要一开始就记住所有字段。真正高频的，通常就这四块：

• agents
• models
• channels
• gateway

agents：定义助手如何工作

agents 可以理解成 OpenClaw 的“大脑编排层”。

最常用的是 agents.defaults，它负责定义所有 agent 的默认行为，例如：

• 默认工作区
• 默认主模型
• 回退模型
• 上下文整理策略
• 并发数量
• 心跳或压缩策略

一个很常见的写法是：

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
    },
  },
}

当你需要多个助手时，还会继续扩展 agents.list。例如，一个负责工作沟通，一个负责编码，一个负责个人事务。

如果你还没有明显的多 agent 需求，先把 defaults 配稳通常就够用了。

models：配置模型提供方和认证

OpenClaw 既能指定默认模型，也能配置不同 provider 的认证方式。

从理解上可以把它分成两层：

• 哪些 provider 可用
• 默认 agent 首选哪一个模型

示例：

{
  models: {
    providers: {
      anthropic: {
        apiKey: "${ANTHROPIC_API_KEY}",
      },
      openai: {
        apiKey: "${OPENAI_API_KEY}",
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
    },
  },
}

这类写法的核心思想很简单：

• provider 负责“能不能连上”
• primary 和 fallbacks 负责“优先用谁”

如果你担心单一模型故障或限流，配置回退模型会更稳。

channels：决定从哪里跟 OpenClaw 对话

channels 是 OpenClaw 区别于普通 AI 客户端的重要部分。

每个渠道会有自己的配置区块，例如 Telegram：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456"],
    },
  },
}

理解渠道配置时，建议重点关注这几个字段：

• enabled：是否启用
• botToken 或其他认证字段：渠道接入凭证
• dmPolicy：私聊访问策略
• allowFrom：允许哪些用户或账号接入
• groupPolicy：群聊中的交互方式

官方文档里，dmPolicy 是一个很重要的安全开关，常见取值包括：

• disabled
• open
• allowlist
• pairing

如果你还不确定安全策略，优先从 pairing 开始会更稳妥。

gateway：控制 OpenClaw 的运行入口

gateway 负责 OpenClaw 的监听端口、绑定方式和认证模式。

一个常见示例是：

{
  gateway: {
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "${GATEWAY_TOKEN}",
    },
  },
}

这里最常见的几个配置含义如下：

• port：Gateway 使用的端口
• bind：绑定地址，loopback 表示只监听本机
• auth.mode：认证方式
• auth.token：访问令牌

如果你只是本机使用，loopback 往往已经足够。只有在明确需要远程访问时，才建议继续扩展网络暴露方式。

tools、skills、plugins：扩展能力层

这一层通常不是安装后马上要改的，但只要你打算长期使用，就很值得理解。

tools

tools 更像系统级工具能力，例如 Web 搜索或媒体处理。

{
  tools: {
    web: {
      search: {
        provider: "brave",
        apiKey: "${BRAVE_SEARCH_KEY}",
      },
    },
  },
}

skills

skills 更偏向特定能力的安装与配置，例如某些专门的自动化技能或第三方能力。

plugins

plugins 主要用来安装和启用扩展组件，适合把系统往更完整的平台方向扩展。

如果你刚开始使用 OpenClaw，不必一开始就把这三层配满。通常是“主链路先跑通，再逐步加能力”。

.env：不要把密钥硬写进主配置

实际配置里，最容易踩坑的地方不是模型，而是密钥管理。

更稳妥的做法，是把敏感信息放进：

~/.openclaw/.env

例如：

ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx
TELEGRAM_BOT_TOKEN=123456:abc
GATEWAY_TOKEN=your-secret-token

然后在 openclaw.json 里用环境变量引用：

{
  models: {
    providers: {
      anthropic: {
        apiKey: "${ANTHROPIC_API_KEY}",
      },
    },
  },
  channels: {
    telegram: {
      botToken: "${TELEGRAM_BOT_TOKEN}",
    },
  },
}

这样做有两个明显好处：

• 主配置文件更干净
• 密钥更容易轮换和统一管理

校验配置时要注意什么

OpenClaw 对配置的校验比较严格。未知字段、类型错误或不合法的值，都可能导致 Gateway 无法启动。

修改配置后，建议至少跑一次：

openclaw doctor

如果你已经知道是配置问题，也可以尝试：

openclaw doctor --fix

除此之外，下面几个命令也很常用：

openclaw health
openclaw status
openclaw logs --follow

新手最值得先改的配置

如果你不想一上来就面对一大堆 schema，可以优先只关注这几类内容：

1. agents.defaults.workspace
2. agents.defaults.model.primary
3. agents.defaults.model.fallbacks
4. channels.<channel>
5. gateway.port
6. gateway.bind

先把这些字段理解清楚，OpenClaw 的日常使用就已经能覆盖大部分场景。

一个适合起步的最小思路

对大多数人来说，配置 OpenClaw 的顺序可以简化成：

1. 先用 openclaw onboard 生成基础配置
2. 把 API Key 和 Token 放进 .env
3. 只选择一个主模型
4. 先接入一个最常用的聊天渠道
5. 最后再考虑 skills 和 plugins

这样做的优点是，问题范围始终可控，不容易在第一次配置时把系统复杂度拉得太高。

参考

• Configuration - OpenClaw
• Configuration Guide - OpenClaw