"OpenClaw 配置文件结构详解"

龙虾学堂2026年5月7日

"深入解析 openclaw.json 的核心字段，掌握 agents、providers、channels 三大配置模块的设计逻辑与最佳实践。"

OpenClaw 配置文件结构详解

本文聚焦：openclaw.json 核心字段解析 + agents/providers/channels 三大模块配置逻辑

前置知识：第一个 Agent 下一篇：模型配置详解

OpenClaw 的所有运行行为都由一个 JSON 配置文件控制——openclaw.json。理解它的结构，是掌握 OpenClaw 的必经之路。

知识点 1：配置文件的位置与层级

配置文件在哪里？

OpenClaw 按以下优先级查找配置：

环境变量：OPENCLAW_CONFIG 指定的路径
当前目录：./openclaw.json
用户目录：~/.openclaw/openclaw.json
系统目录：/etc/openclaw/openclaw.json

最常用的是 用户目录 下的配置文件：

# OpenClaw 默认使用以下位置的配置文件
~/.openclaw/openclaw.json

# 你也可以通过环境变量指定自定义路径
export OPENCLAW_CONFIG=/path/to/your/openclaw.json

配置文件的层级结构

一个完整的 openclaw.json 包含四大顶级字段：

{
  "agents": {},      // Agent 定义
  "providers": {},   // 模型提供商配置
  "channels": {},    // 消息通道配置
  "skills": {}       // Skill 加载配置（可选）
}

每个字段都是一个对象，键是标识符，值是具体配置。

最小可用配置示例

以下是一个能让 OpenClaw 跑起来的最小配置：

{
  "agents": {
    "main": {
      "provider": "gemini",
      "model": "gemini-2.0-flash",
      "systemPrompt": "你是一个 helpful 的 AI 助手。"
    }
  },
  "providers": {
    "gemini": {
      "kind": "google",
      "apiKey": "${GEMINI_API_KEY}"
    }
  },
  "channels": {
    "telegram": {
      "kind": "telegram",
      "token": "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

这个配置定义了：

一个名为 main 的 Agent，使用 Gemini 模型
一个 gemini 提供商，从环境变量读取 API Key
一个 telegram 通道，从环境变量读取 Bot Token

知识点 2：三大核心模块详解

Agents 模块：定义"谁"在回答问题

agents 对象中的每个键值对定义一个独立的 Agent：

{
  "agents": {
    "main": {
      "provider": "gemini",
      "model": "gemini-2.0-flash",
      "systemPrompt": "你是主助手，擅长日常问答。",
      "tools": ["web_search", "web_fetch"],
      "skills": ["my-skill"]
    },
    "coder": {
      "provider": "openai",
      "model": "gpt-4o",
      "systemPrompt": "你是代码专家，擅长编程问题。",
      "tools": ["exec", "read", "write"]
    }
  }
}

关键字段说明：

字段	必填	说明
`provider`	✅	引用 providers 中的配置键名
`model`	✅	具体的模型名称或别名
`systemPrompt`	❌	Agent 的系统提示词
`tools`	❌	允许使用的工具列表（白名单模式）
`skills`	❌	自动加载的 Skill 目录名列表

重要设计：tools 字段是白名单机制——只有列出的工具才会被授权给该 Agent。如果不指定，Agent 可以使用所有可用工具。

Providers 模块：定义"用什么"模型

providers 配置模型提供商的接入方式：

{
  "providers": {
    "gemini": {
      "kind": "google",
      "apiKey": "${GEMINI_API_KEY}",
      "baseUrl": "https://generativelanguage.googleapis.com"
    },
    "openai": {
      "kind": "openai",
      "apiKey": "${OPENAI_API_KEY}",
      "baseUrl": "https://api.openai.com/v1"
    },
    "local-llm": {
      "kind": "openai-compatible",
      "apiKey": "sk-dummy",
      "baseUrl": "http://localhost:11434/v1"
    }
  }
}

支持的 kind 类型：

kind	说明	适用场景
`google`	Google Gemini API	Gemini 系列模型
`openai`	OpenAI 官方 API	GPT-4, GPT-3.5 等
`anthropic`	Anthropic Claude API	Claude 系列模型
`openai-compatible`	兼容 OpenAI 格式的 API	本地模型、第三方代理

环境变量替换：

配置中可以使用 ${VAR_NAME} 语法引用环境变量，这在管理密钥时非常有用：

{
  "apiKey": "${GEMINI_API_KEY}"
}

OpenClaw 启动时会自动将 ${GEMINI_API_KEY} 替换为对应的环境变量值。

Channels 模块：定义"在哪"接收消息

channels 配置消息通道，决定 Agent 可以从哪里接收用户输入：

{
  "channels": {
    "telegram": {
      "kind": "telegram",
      "token": "${TELEGRAM_BOT_TOKEN}",
      "defaultAgent": "main"
    },
    "feishu": {
      "kind": "feishu",
      "appId": "${FEISHU_APP_ID}",
      "appSecret": "${FEISHU_APP_SECRET}",
      "defaultAgent": "main"
    },
    "discord": {
      "kind": "discord",
      "token": "${DISCORD_BOT_TOKEN}",
      "defaultAgent": "coder"
    }
  }
}