目 录

摘要

配置文件是 AI Agent 系统的"神经中枢"，决定了系统如何运行、如何响应、如何与外部世界交互。本文深入解析 OpenClaw 的核心配置文件 openclaw.yaml，从基础结构到高级配置，全面讲解 Gateway 网关、Model 模型、Browser 浏览器、Channels 渠道、Logging 日志、Security 安全、Performance 性能七大核心模块的配置方法。通过大量实战示例和最佳实践，帮助读者掌握配置文件的优先级规则、敏感信息管理、多环境部署策略，以及性能调优技巧。无论你是初次接触 OpenClaw 的开发者，还是希望优化生产环境配置的运维工程师，都能从本文中获得实用的指导。

1. 引言：配置文件——AI Agent 的"大脑配置中心"

在软件开发的世界里，有一个经典的说法：程序 = 算法 + 数据结构 + 配置。对于 AI Agent 系统而言，配置文件的重要性更是不言而喻——它决定了 Agent 使用哪个模型、连接哪些消息平台、如何处理用户请求、如何保障系统安全。

OpenClaw 作为一个多渠道 AI Agent 框架，其配置文件承载了整个系统的运行参数。一个精心设计的配置文件，可以让 OpenClaw 在不同环境下稳定运行；而一个配置不当的系统，可能会出现性能瓶颈、安全隐患，甚至无法正常启动。

想象一下，你正在搭建一个智能客服系统。你需要决定：使用哪个 AI 模型来回答用户问题？接入哪些消息渠道（Telegram、飞书、微信）？如何保护用户的隐私数据？如何确保系统在高并发下不崩溃？这些问题的答案，都写在配置文件里。

本文将从零开始，带你深入理解 openclaw.yaml 的每一个配置项。我们不仅会告诉你"怎么配置"，更会解释"为什么这样配置"，帮助你建立对配置系统的完整认知。通过本文的学习，你将能够：

  • 理解配置文件的整体架构和设计理念
  • 掌握七大核心模块的配置方法
  • 学会配置优先级规则和多环境部署策略
  • 了解敏感信息管理的最佳实践
  • 避免常见的配置错误和陷阱

2. openclaw.yaml 整体架构

2.1 配置文件定位与加载机制

OpenClaw 的配置文件默认位于用户目录下，采用 JSON 格式编写（虽然文件名为 openclaw.yaml，但实际支持 JSON 格式）。JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，易于人阅读和编写，同时也易于机器解析和生成。

配置文件的默认路径为：

~/.openclaw/openclaw.json

也可以通过命令行参数指定自定义路径：

# 指定配置文件路径
openclaw gateway start --config /path/to/custom-config.json

# 验证配置文件格式
openclaw config validate

# 查看实际加载的配置
openclaw config show

2.2 配置文件整体结构

openclaw.json 采用分层模块化设计，整体结构清晰明了。一个完整的配置文件包含七大核心模块，每个模块负责特定的功能领域：

在这里插入图片描述

上图展示了 openclaw.json 的整体架构。每个模块都有明确的职责边界，同时通过配置继承和覆盖机制实现灵活的组合。这种设计理念遵循了"高内聚、低耦合"的软件工程原则，使得配置文件既易于理解，又便于维护。

2.3 配置优先级机制

OpenClaw 的配置加载遵循严格的优先级机制，理解这一机制对于排查配置问题至关重要。配置来源的优先级从高到低依次为：

存在

不存在

存在

不存在

存在

不存在

🚀 OpenClaw 启动

命令行参数?

使用命令行参数
最高优先级

环境变量?

使用环境变量
OPENCLAW_ 前缀

配置文件?

使用配置文件
openclaw.json

使用内置默认值
最低优先级

✅ 配置加载完成

这个优先级机制的设计理念是：越是临时的、特定场景的配置，优先级越高。命令行参数通常用于临时调试或一次性任务，因此优先级最高；环境变量适合容器化部署和敏感信息管理；配置文件是主要的配置来源；默认值则保证了开箱即用的体验。

配置优先级实战示例：

// openclaw.json 中配置
{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "config-file-token"
    }
  }
}

# 环境变量覆盖
export OPENCLAW_GATEWAY_AUTH_TOKEN="env-token"

# 命令行参数最终覆盖
openclaw gateway start --port 18889 --auth-token "cli-token"

# 最终生效：port=18889, auth_token="cli-token"

3. Gateway 网关配置详解

Gateway 是 OpenClaw 的核心组件，负责接收和分发消息。它是系统的"大门"，所有外部请求都要经过 Gateway 处理。Gateway 配置直接影响系统的网络行为、安全性和可用性。

3.1 Gateway 基础配置

Gateway 的基础配置包括端口、认证、绑定地址等核心参数。这些参数是系统运行的基石，必须正确配置：

{
  "gateway": {
    "port": 18789,
    "bind": "lan",
    "auth": {
      "token": "your-secret-token-here"
    },
    "controlUi": {
      "allowedOrigins": ["*"],
      "dangerouslyAllowHostHeaderOriginFallback": true,
      "dangerouslyDisableDeviceAuth": true
    }
  }
}

上述配置展示了 Gateway 的核心参数。port 定义了服务监听端口，默认为 18789，这是一个非特权端口，无需 root 权限即可绑定。auth.token 是最重要的安全配置，所有 API 调用都需要在请求头中携带此令牌进行身份验证。bind 控制绑定的网卡地址，设置为 lan 会绑定到局域网地址，增强安全性。

3.2 Gateway 认证配置详解

Gateway 的认证配置是安全防护的第一道防线。OpenClaw 支持多种认证方式，可以根据安全需求灵活选择：

{
  "gateway": {
    "auth": {
      "token": "01b2fb03d182a4fd5527c9ff9061d5d47b0606e9e0d14d0b"
    },
    "controlUi": {
      "allowedOrigins": [
        "https://your-frontend.com",
        "https://admin.your-frontend.com"
      ],
      "dangerouslyAllowHostHeaderOriginFallback": false,
      "dangerouslyDisableDeviceAuth": false
    }
  }
}

上述配置展示了 Gateway 的认证参数。auth.token 是 API 访问令牌，建议使用 32 位以上的随机字符串。controlUi.allowedOrigins 控制 CORS 跨域访问，生产环境应精确配置允许的域名。dangerouslyAllowHostHeaderOriginFallback 和 dangerouslyDisableDeviceAuth 是高风险配置，生产环境应设为 false。

3.3 Gateway 配置最佳实践

不同环境下的 Gateway 配置策略有所不同，下表总结了各场景的推荐配置：

配置项 开发环境 测试环境 生产环境 说明
port 18789 18789 18789 保持一致，便于管理
auth.token “dev-token” 随机生成 32位随机字符串 生产环境必须强密码
bind “all” “lan” “lan” 生产环境禁止公网直连
allowedOrigins [“*”] 测试域名 生产域名 生产环境精确配置
dangerouslyDisableDeviceAuth true false false 生产环境必须开启设备认证

生产环境 Gateway 配置清单：

{
  "gateway": {
    "port": 18789,
    "bind": "lan",
    "auth": {
      "token": "${GATEWAY_AUTH_TOKEN}"
    },
    "controlUi": {
      "allowedOrigins": ["https://app.yourcompany.com"],
      "dangerouslyAllowHostHeaderOriginFallback": false,
      "dangerouslyDisableDeviceAuth": false
    }
  }
}

4. Model 模型配置详解

模型配置决定了 OpenClaw 使用哪个 AI 模型，以及如何调用模型 API。这是 AI Agent 系统的核心配置，直接影响 Agent 的智能程度和响应质量。

4.1 模型配置基础

OpenClaw 支持多种 AI 模型提供商，包括 OpenAI、Anthropic、DeepSeek、智谱 AI、讯飞星火等。模型配置的核心是定义默认模型和 API 密钥：

{
  "models": {
    "mode": "merge",
    "providers": {
      "maas": {
        "api": "openai-completions",
        "apiKey": "b5b85f82c16afd23d54859040c7fc0a8:NDJhNTA2NGYyZTRkMGM4MzBlNWEwMzNi",
        "baseUrl": "https://maas-api.cn-huabei-1.xf-yun.com/v2",
        "models": [
          {
            "id": "astronclaw-auto",
            "name": "astronclaw-auto",
            "contextWindow": 100000,
            "maxTokens": 16384,
            "input": ["text"],
            "reasoning": false,
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            }
          }
        ]
      }
    }
  }
}

上述配置展示了模型提供商的完整配置。api 指定 API 类型，apiKey 存储访问密钥，baseUrl 是 API 端点地址。models 数组定义了可用的模型列表，包括上下文窗口大小、最大输出 token 数、输入类型等关键参数。cost 字段记录模型的调用成本，用于预算控制和成本分析。

4.2 Agent 默认模型配置

在 OpenClaw 中，每个 Agent 可以配置自己的默认模型。这是通过 agents.defaults 配置块实现的：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "maas/astronclaw-auto",
        "fallbacks": []
      },
      "models": {
        "maas/astronclaw-auto": {
          "alias": "astronclaw-auto"
        }
      },
      "maxConcurrent": 8,
      "compaction": {
        "mode": "safeguard"
      },
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}

上述配置定义了 Agent 的默认模型设置。model.primary 指定主要使用的模型，格式为 provider/model-id。model.fallbacks 是备用模型列表，当主模型不可用时自动切换。maxConcurrent 控制最大并发会话数，compaction.mode 设置上下文压缩策略。subagents.maxConcurrent 限制子 Agent 的并发数量。

4.3 多模型路由配置

OpenClaw 支持智能模型路由，根据任务类型自动选择最合适的模型。这种设计可以在质量和成本之间取得最佳平衡：

简单对话

代码生成

文档摘要

敏感数据

用户请求

任务类型判断

GPT-4o-mini
快速响应

GPT-4o
深度思考

DeepSeek
低成本

Ollama 本地
完全离线

返回结果

上图展示了多模型路由的工作流程。系统根据任务类型自动选择最合适的模型：简单对话使用轻量模型快速响应，代码生成使用旗舰模型确保质量，文档摘要使用经济模型降低成本，敏感数据处理使用本地模型保护隐私。

4.4 模型配置对比

模型类型 代表模型 适用场景 成本 延迟 质量
旗舰模型 GPT-4o, Claude-3.5-Sonnet 复杂推理、代码生成 💰💰💰 中等 ⭐⭐⭐⭐⭐
轻量模型 GPT-4o-mini, Claude-3-Haiku 日常对话、简单任务 💰 快 ⭐⭐⭐⭐
经济模型 GPT-3.5-Turbo, DeepSeek 批量处理、摘要 💰 很快 ⭐⭐⭐
本地模型 Llama3.2, Qwen2.5 离线场景、敏感数据 免费 取决于硬件 ⭐⭐⭐
国产模型 讯飞星火、通义千问 国内合规、中文优化 💰 快 ⭐⭐⭐⭐

5. Browser 浏览器配置详解

OpenClaw 内置浏览器自动化能力，可以执行网页抓取、表单填写、截图等任务。Browser 配置控制浏览器的运行方式和行为参数。

5.1 浏览器基础配置

浏览器配置的核心是控制浏览器的运行模式，特别是在服务器环境下需要特殊配置：

{
  "browser": {
    "headless": true,
    "noSandbox": true,
    "executablePath": "/usr/bin/google-chrome",
    "defaultProfile": "openclaw",
    "color": "#FF4500",
    "attachOnly": false,
    "profiles": {
      "openclaw": {
        "cdpPort": 18800,
        "color": "#FF4500"
      }
    },
    "remoteCdpHandshakeTimeoutMs": 3000,
    "remoteCdpTimeoutMs": 1500
  }
}

上述配置展示了浏览器自动化的核心参数。headless: true 表示无头模式，浏览器在后台运行不显示窗口，服务器环境必须开启。noSandbox: true 禁用沙箱，Docker 容器中运行时必须设置，否则浏览器无法启动。executablePath 指定 Chrome 浏览器的可执行文件路径。defaultProfile 设置默认使用的浏览器配置文件。profiles 定义多个浏览器配置，每个配置有独立的 CDP 端口和标识颜色。

5.2 浏览器配置场景对比

配置项 本地开发 服务器部署 Docker 容器 说明
headless false true true 开发时可观察浏览器
noSandbox false true true ✅ 容器必须禁用沙箱
executablePath 自动检测 手动指定 容器内置 确保路径正确
remoteCdpTimeoutMs 3000 1500 1500 容器网络延迟更低
attachOnly false false true 容器模式只附加

Docker 环境浏览器配置示例：

{
  "browser": {
    "headless": true,
    "noSandbox": true,
    "executablePath": "/usr/bin/google-chrome",
    "attachOnly": true,
    "remoteCdpHandshakeTimeoutMs": 3000,
    "remoteCdpTimeoutMs": 1500
  }
}

5.3 Chrome 扩展配置（Browser Relay）

OpenClaw 支持 Chrome 扩展（Browser Relay），可以控制用户本地的 Chrome 浏览器，实现更强大的自动化能力。Browser Relay 是 OpenClaw 的独特功能，让 Agent 可以操作用户本地的浏览器，完成登录、表单填写、数据抓取等任务。

使用 Browser Relay 时，用户需要在 Chrome 浏览器中安装 OpenClaw 扩展，并点击工具栏按钮将当前标签页附加到 OpenClaw。Agent 就可以像操作本地浏览器一样操作用户的 Chrome 标签页。

6. Channels 渠道配置详解

渠道配置是 OpenClaw 的核心特色，支持 20+ 消息平台的接入。通过统一的配置格式，开发者可以轻松地将 AI Agent 接入 Telegram、飞书、Discord、微信等主流平台。

6.1 渠道配置整体架构

🤖 OpenClaw Gateway

📱 消息平台

👥 用户

Telegram 用户

飞书用户

Discord 用户

微信用户

Telegram Bot API

飞书开放平台

Discord Gateway

微信公众平台

消息路由器

消息处理器

AI Agent 核心

上图展示了 OpenClaw 的多渠道消息路由架构。用户通过各种消息平台发送消息，消息经过平台 API 到达 OpenClaw Gateway，Gateway 的消息路由器根据来源渠道分发到对应的处理器，最终由 AI Agent 核心处理并返回结果。

6.2 飞书渠道配置

飞书是字节跳动的企业协作平台，在国内企业中广泛使用。飞书的配置需要创建企业自建应用：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_a93fd02ab3b89bdf",
      "appSecret": "your-app-secret",
      "domain": "feishu",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "allowFrom": ["*"]
    }
  }
}

上述配置展示了飞书渠道的核心参数。appId 和 appSecret 是应用凭证，从飞书开放平台创建企业自建应用后获取。dmPolicy 控制私聊策略，groupPolicy 控制群聊策略，可选值包括 open（开放）、pairing（配对）、allowlist（白名单）。allowFrom 定义允许访问的用户列表，["*"] 表示允许所有人。

6.3 Telegram 渠道配置

Telegram 是最流行的即时通讯平台之一，其 Bot API 简洁易用，是 AI Agent 的理想接入渠道：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "webhookUrl": "https://your-domain.com/api/telegram/webhook",
      "allowedUsers": [123456789, 987654321],
      "allowedGroups": [-1001234567890]
    }
  }
}

Telegram 配置中最关键的是 botToken，从 @BotFather 创建机器人后获取。webhookUrl 是 OpenClaw 接收消息的地址，必须是公网可访问的 HTTPS 地址。allowedUsers 和 allowedGroups 用于权限控制，留空则允许所有人使用，生产环境建议配置白名单。

6.4 多渠道统一配置

为了避免重复配置，OpenClaw 支持全局默认配置和渠道级覆盖：

{
  "channels": {
    "defaults": {
      "responseTimeout": 60,
      "deduplication": true,
      "retryCount": 3
    },
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "responseTimeout": 30
    },
    "feishu": {
      "enabled": true,
      "appId": "${FEISHU_APP_ID}",
      "appSecret": "${FEISHU_APP_SECRET}",
      "responseTimeout": 120
    }
  }
}

多渠道配置支持全局默认值和渠道级覆盖。defaults 部分定义所有渠道共享的配置，各渠道可以覆盖特定参数。这种设计避免了重复配置，同时保留了灵活性。

6.5 渠道配置对比

特性 Telegram 飞书 Discord 微信
配置复杂度 ⭐ ⭐⭐⭐ ⭐⭐ ⭐⭐⭐⭐
消息格式 Markdown 富文本/卡片 Markdown/Embed 纯文本
文件支持 ✅ ✅ ✅ ⚠️ 限制
群组支持 ✅ ✅ ✅ ❌
Webhook ✅ ✅ ✅ ❌ 需轮询
国内访问 ⚠️ 需代理 ✅ ⚠️ 需代理 ✅
企业集成 ❌ ✅ 强 ⚠️ 有限 ✅

7. Logging 日志配置详解

日志是系统运行的"黑匣子"，对于问题排查和性能分析至关重要。OpenClaw 的日志配置支持多种输出方式和格式。

7.1 基础日志配置

OpenClaw 的日志配置主要通过命令行参数和环境变量控制，但也可以在配置文件中设置默认值：

{
  "logging": {
    "level": "info",
    "format": "json",
    "console": true,
    "file": "/var/log/openclaw/openclaw.log",
    "rotation": {
      "maxSize": 100,
      "maxFiles": 10,
      "compress": true
    }
  }
}

日志配置中 level 控制日志详细程度，可选值包括 debug、info、warn、error。开发环境建议 debug，生产环境建议 info 或 warn。format 选择日志格式，json 格式便于 ELK、Loki 等日志系统解析，text 格式便于人类阅读。rotation 配置日志轮转策略，避免日志文件无限增长导致磁盘空间耗尽。

7.2 日志级别详解

级别 说明 适用场景 示例
debug 最详细，包含所有调试信息 开发调试、问题排查 变量值、函数调用栈
info 常规信息，生产环境推荐 生产环境、日常监控 请求处理、任务完成
warn 警告信息，可能的问题 生产环境、异常监控 配置缺失、性能下降
error 仅错误信息 生产环境、故障排查 异常堆栈、失败原因

7.3 敏感信息脱敏

对于生产环境，日志脱敏是必不可少的安全措施。OpenClaw 会自动脱敏以下字段：

  • API 密钥（api_key, apiKey）
  • 认证令牌（token, authToken）
  • 密码（password, passwd）
  • 密钥（secret, privateKey）

脱敏后的日志示例：

{
  "timestamp": "2026-03-19T10:22:00Z",
  "level": "info",
  "message": "API call completed",
  "api_key": "***REDACTED***",
  "responseTime": 1234
}

8. Security 安全配置详解

安全配置保护 OpenClaw 免受未授权访问和恶意攻击。在生产环境中，安全配置是必不可少的。

8.1 认证与授权配置

OpenClaw 的安全配置主要通过 Gateway 的认证机制实现：

{
  "gateway": {
    "auth": {
      "token": "your-secure-token"
    }
  },
  "security": {
    "ipWhitelist": {
      "enabled": true,
      "allowed": [
        "127.0.0.1",
        "10.0.0.0/8",
        "172.16.0.0/12",
        "192.168.0.0/16"
      ]
    },
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "window": 60
    }
  }
}

安全配置中 auth.token 控制 API 认证，ipWhitelist 限制访问来源，rateLimit 防止滥用。生产环境强烈建议开启所有安全配置，并根据实际需求调整参数。

8.2 渠道安全策略

每个渠道都可以配置独立的安全策略：

{
  "channels": {
    "feishu": {
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "allowFrom": ["ou_xxx", "ou_yyy"]
    }
  }
}

dmPolicy 控制私聊策略，可选值包括：

  • open：允许所有人
  • pairing：需要先配对
  • allowlist：仅白名单用户
  • disabled：禁用私聊

groupPolicy 控制群聊策略，选项类似。allowFrom 定义白名单用户列表。

8.3 安全配置最佳实践

安全措施 开发环境 生产环境 说明
auth.token 简单密码 32位随机 定期更换
IP 白名单 关闭 开启 只允许可信 IP
速率限制 关闭 开启 防止滥用
渠道策略 open pairing/allowlist 限制访问范围
日志脱敏 可选 必须 防止敏感信息泄露

9. Performance 性能配置详解

性能配置优化 OpenClaw 的运行效率，确保系统在高并发场景下稳定运行。

9.1 并发配置

OpenClaw 的并发配置主要在 agents.defaults 中设置：

{
  "agents": {
    "defaults": {
      "maxConcurrent": 8,
      "subagents": {
        "maxConcurrent": 8
      },
      "compaction": {
        "mode": "safeguard"
      }
    }
  }
}

maxConcurrent 控制最大并发会话数，subagents.maxConcurrent 限制子 Agent 的并发数量。compaction.mode 设置上下文压缩策略，safeguard 模式会在上下文过长时自动压缩，防止 token 爆炸。

9.2 上下文管理配置

上下文管理是 AI Agent 性能优化的关键。OpenClaw 提供了多种上下文管理策略：

正常

超限

safeguard

aggressive

disabled

消息到达

上下文长度检查

正常处理

压缩模式

智能压缩
保留关键信息

激进压缩
大幅删减

拒绝处理
提示用户

继续处理

返回错误

上图展示了上下文管理的工作流程。当消息到达时，系统首先检查上下文长度。如果超限，根据配置的压缩模式采取不同策略：safeguard 模式智能压缩保留关键信息，aggressive 模式激进删减，disabled 模式拒绝处理。

9.3 性能配置调优建议

配置项 低负载 中负载 高负载 说明
maxConcurrent 4 8 16 根据服务器配置调整
subagents.maxConcurrent 4 8 16 子 Agent 并发限制
compaction.mode disabled safeguard aggressive 高负载建议激进压缩

性能调优检查清单：

  • 根据服务器配置设置 maxConcurrent
  • 高负载场景启用上下文压缩
  • 监控 token 消耗，设置预算上限
  • 使用缓存减少重复计算
  • 定期清理历史会话数据

10. Plugins 插件配置详解

OpenClaw 的插件系统允许扩展核心功能。插件配置位于 plugins 配置块：

10.1 插件基础配置

{
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      },
      "astron-claw": {
        "enabled": true,
        "config": {
          "enabled": true,
          "name": "AstronClaw",
          "allowFrom": ["*"],
          "bridge": {
            "url": "ws://astronclaw-channel-api-prod.xf-yun.com/bridge/bot",
            "token": "your-bridge-token"
          }
        }
      }
    },
    "installs": {}
  }
}

plugins.entries 定义已启用的插件列表。每个插件可以有自己的 config 配置块。plugins.installs 记录插件的安装信息。

10.2 常用插件配置示例

插件名称 功能 配置要点
feishu 飞书消息接入 配置 appId、appSecret
telegram Telegram 接入 配置 botToken
discord Discord 接入 配置 botToken
astron-claw 讯飞星火桥接 配置 bridge URL 和 token

11. Skills 技能配置详解

Skills 是 OpenClaw 的扩展机制，允许为 Agent 添加新能力。技能配置位于 skills 配置块：

11.1 技能启用配置

{
  "skills": {
    "entries": {
      "rpe-grafana": {
        "enabled": false
      },
      "weather": {
        "enabled": true
      },
      "hot-finder": {
        "enabled": true
      }
    }
  }
}

skills.entries 定义技能的启用状态。每个技能通过 enabled 字段控制是否启用。

11.2 技能优先级

OpenClaw 的技能加载遵循优先级规则：

  1. 工作空间技能：<workspace>/skills（最高优先级）
  2. 本地技能：~/.openclaw/skills
  3. 内置技能：随安装包提供（最低优先级）

当同名技能存在于多个位置时，优先级高的会覆盖优先级低的。这允许用户自定义覆盖内置技能。

12. Commands 命令配置详解

Commands 配置控制 OpenClaw 的命令行行为：

12.1 命令基础配置

{
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "ownerDisplay": "raw",
    "restart": true
  }
}

native 控制原生命令的启用方式，auto 表示自动检测。nativeSkills 控制原生技能的启用。ownerDisplay 设置所有者显示方式，raw 表示原始显示。restart 控制是否允许通过命令重启服务。

12.2 Messages 消息配置

{
  "messages": {
    "ackReactionScope": "group-mentions"
  }
}

ackReactionScope 控制消息确认反应的范围，group-mentions 表示仅在群组提及时确认。

13. 配置优先级与最佳实践

13.1 配置优先级详解

OpenClaw 的配置优先级机制确保了配置的灵活性和可覆盖性。理解这一机制对于管理多环境配置至关重要：

默认值 配置文件 环境变量 命令行参数 默认值 配置文件 环境变量 命令行参数 配置加载顺序（优先级从高到低） 最终配置 = 命令行 ∪ 环境变量 ∪ 配置文件 ∪ 默认值 1. 检查命令行参数 2. 检查环境变量 3. 检查配置文件 4. 使用默认值

配置优先级的设计理念是：越是临时的、特定场景的配置，优先级越高。这种设计支持以下场景：

  1. 开发调试：使用命令行参数临时修改配置，无需修改配置文件
  2. 容器部署：使用环境变量注入配置，无需修改镜像
  3. 敏感信息：使用环境变量存储密钥，避免写入配置文件

13.2 多环境配置最佳实践

对于需要管理多个环境（开发、测试、生产）的场景，推荐以下配置组织方式：

基础配置文件（所有环境共享）：

{
  "gateway": {
    "port": 18789
  },
  "agents": {
    "defaults": {
      "maxConcurrent": 8,
      "model": {
        "primary": "maas/astronclaw-auto"
      }
    }
  },
  "browser": {
    "headless": true,
    "noSandbox": true
  }
}

环境变量覆盖（敏感信息）：

# .env.production
GATEWAY_AUTH_TOKEN=prod-xxx-xxx-xxx
OPENAI_API_KEY=sk-prod-xxx
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx

13.3 敏感信息管理

❌ 错误做法：明文存储敏感信息

// 不要这样做！
{
  "gateway": {
    "auth": {
      "token": "my-secret-token"
    }
  },
  "models": {
    "providers": {
      "openai": {
        "apiKey": "sk-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

✅ 正确做法：使用环境变量

// 推荐做法
{
  "gateway": {
    "auth": {
      "token": "${GATEWAY_AUTH_TOKEN}"
    }
  },
  "models": {
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      }
    }
  }
}

✅ 最佳做法：使用密钥管理服务

对于企业级部署，建议使用 AWS Secrets Manager、HashiCorp Vault 等密钥管理服务，实现密钥的集中管理、自动轮换和审计追踪。

14. 常见配置问题与解决方案

14.1 配置不生效

问题描述：修改了配置文件，重启后配置没有生效。

排查步骤：

# 1. 验证配置文件格式
openclaw config validate

# 2. 查看实际加载的配置
openclaw config show

# 3. 检查环境变量覆盖
env | grep OPENCLAW

# 4. 检查配置文件路径
openclaw gateway start --verbose

常见原因：

  • JSON 格式错误（缺少引号、逗号、括号不匹配）
  • 环境变量覆盖了配置文件的设置
  • 配置文件路径错误

14.2 敏感信息泄露

问题描述：配置文件中明文存储了 API 密钥，存在安全风险。

解决方案：

# 使用环境变量
export GATEWAY_AUTH_TOKEN="your-token"
export OPENAI_API_KEY="sk-xxx"

# 或使用 .env 文件（不要提交到 Git）
echo "GATEWAY_AUTH_TOKEN=xxx" >> .env
echo ".env" >> .gitignore

14.3 端口冲突

问题描述：Gateway 启动失败，提示端口被占用。

解决方案：

# 查看端口占用
lsof -i :18789
netstat -tlnp | grep 18789

# 终止占用进程
kill -9 <PID>

# 或修改配置使用其他端口
# 通过命令行参数
openclaw gateway start --port 18889

14.4 Docker 环境配置问题

问题描述：在 Docker 容器中运行时，浏览器无法启动或网络不通。

解决方案：

{
  "browser": {
    "headless": true,
    "noSandbox": true,
    "attachOnly": true
  }
}

Docker 容器中必须配置 noSandbox: true，因为容器默认没有足够的权限运行沙箱。同时建议设置 attachOnly: true，使用远程浏览器实例而非本地启动。

14.5 配置问题排查流程

配置不生效

环境变量覆盖

格式错误

路径错误

启动失败

端口冲突

权限问题

依赖缺失

性能问题

内存不足

CPU 满载

网络延迟

配置问题

问题类型?

检查优先级

清除环境变量

验证 JSON 格式

检查配置路径

检查日志

更换端口

检查文件权限

安装依赖

检查资源

减少并发数

优化配置

检查网络

✅ 问题解决

上图展示了配置问题的排查决策树。当遇到配置问题时，首先确定问题类型，然后根据具体症状采取相应的排查措施。

15. 完整配置示例

下面是一个生产环境的完整配置示例，整合了本文介绍的所有最佳实践：

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 8,
      "model": {
        "fallbacks": [],
        "primary": "maas/astronclaw-auto"
      },
      "models": {
        "maas/astronclaw-auto": {
          "alias": "astronclaw-auto"
        }
      },
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "browser": {
    "attachOnly": false,
    "color": "#FF4500",
    "defaultProfile": "openclaw",
    "executablePath": "/usr/bin/google-chrome",
    "headless": true,
    "noSandbox": true,
    "profiles": {
      "openclaw": {
        "cdpPort": 18800,
        "color": "#FF4500"
      }
    },
    "remoteCdpHandshakeTimeoutMs": 3000,
    "remoteCdpTimeoutMs": 1500
  },
  "channels": {
    "feishu": {
      "allowFrom": ["*"],
      "appId": "${FEISHU_APP_ID}",
      "appSecret": "${FEISHU_APP_SECRET}",
      "dmPolicy": "open",
      "domain": "feishu",
      "enabled": true,
      "groupPolicy": "open"
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "ownerDisplay": "raw",
    "restart": true
  },
  "gateway": {
    "auth": {
      "token": "${GATEWAY_AUTH_TOKEN}"
    },
    "bind": "lan",
    "controlUi": {
      "allowedOrigins": ["https://app.yourcompany.com"],
      "dangerouslyAllowHostHeaderOriginFallback": false,
      "dangerouslyDisableDeviceAuth": false
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "maas": {
        "api": "openai-completions",
        "apiKey": "${MAAS_API_KEY}",
        "baseUrl": "https://maas-api.cn-huabei-1.xf-yun.com/v2",
        "models": [
          {
            "contextWindow": 100000,
            "cost": {
              "cacheRead": 0,
              "cacheWrite": 0,
              "input": 0,
              "output": 0
            },
            "id": "astronclaw-auto",
            "input": ["text"],
            "maxTokens": 16384,
            "name": "astronclaw-auto",
            "reasoning": false
          }
        ]
      }
    }
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
    },
    "installs": {}
  },
  "skills": {
    "entries": {}
  }
}

16. 总结

本文全面解析了 OpenClaw 的配置文件 openclaw.json，从基础结构到高级配置，从开发环境到生产环境。通过七大核心模块的详细讲解，读者应该已经掌握了配置文件的编写方法和最佳实践。

核心要点回顾：

1. 配置结构：openclaw.json 采用分层模块化设计，包括 Gateway、Model、Browser、Channels、Logging、Security、Performance 七大模块，每个模块职责明确，相互独立又协同工作。Gateway 是系统的入口，负责网络监听和认证；Model 决定 AI 能力；Browser 提供自动化能力；Channels 实现多平台接入；Logging 记录运行状态；Security 保障系统安全；Performance 优化运行效率。

2. 配置优先级：命令行参数 > 环境变量 > 配置文件 > 默认值。理解这一优先级机制，有助于排查配置问题和设计多环境配置方案。命令行参数适合临时调试，环境变量适合容器部署和敏感信息管理，配置文件是主要配置来源，默认值保证开箱即用。

3. 安全最佳实践：使用环境变量存储敏感信息、开启 IP 白名单和速率限制、配置渠道访问策略、启用日志脱敏。安全无小事，生产环境必须重视每一个安全配置项。特别是 auth.token 应使用 32 位以上随机字符串，并定期更换。

4. 性能优化：合理设置并发参数、启用上下文压缩、配置缓存策略。性能调优是一个持续的过程，需要根据实际负载不断调整。高并发场景建议启用 safeguard 压缩模式，防止 token 爆炸。

5. 多渠道配置：利用 defaults 定义全局配置，各渠道覆盖特定参数，避免重复配置，提高配置文件的可维护性。不同渠道有不同的特性，需要根据实际需求选择合适的渠道策略。

思考题：

  1. 多环境配置策略：如果你的团队需要管理开发、测试、预发布、生产四个环境，你会如何组织配置文件？是使用多个配置文件，还是使用环境变量覆盖？各自的优缺点是什么？

  2. 配置热更新的必要性：OpenClaw 目前需要重启才能加载新配置。你认为哪些配置应该支持热更新（如日志级别、速率限制）？热更新会带来哪些潜在风险（如配置不一致、竞态条件）？

  3. 配置验证机制：如何设计一个配置验证机制，在启动前检测配置错误（如端口冲突、密钥格式错误、必填项缺失），而不是运行时才发现问题？验证机制应该放在哪个层面实现？

参考资料

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

OpenClaw CLI 完整命令手册

avatar 龙虾开发者社区

从.cdsinit到display.drf：定制你的Virtuoso设计环境全攻略

本文详细介绍了如何通过.cdsinit和display.drf文件定制Cadence Virtuoso设计环境，包括设置仿真波形图、快捷键和显示效果等。通过实用的SKILL代码示例和图形化工具操作指南，帮助工程师提升工作效率并解决常见配置问题。

avatar 龙虾开发者社区
cover

【技术干货】用 Everything Claude Code 把 OpenCode 打造成“可持续进化”的 AI 编码助手

avatar 龙虾开发者社区