OpenClaw配置文件openclaw.json5完全指南

前言

OpenClaw 的核心配置文件是 openclaw.json5，默认位于 ~/.config/openclaw/openclaw.json5。这个文件采用 JSON5 格式，支持注释和更宽松的语法，让配置过程更加友好。本文将逐一讲解所有配置段及其选项。

JSON5 格式简介

JSON5 是 JSON 的超集，主要增加了以下特性：

{
  // 支持单行注释
  /* 也支持多行注释 */

  // 键名不需要引号
  gateway: {
    port: 18789,
  },

  // 支持尾逗号
  tags: [
    "ai",
    "assistant",
  ],

  // 支持单引号字符串
  name: 'OpenClaw',

  // 支持多行字符串
  prompt: "第一行\
    第二行",
}

如果你不熟悉 JSON5，把它当作"可以写注释的 JSON"就好。

配置文件路径

平台	默认路径
Linux	`~/.config/openclaw/openclaw.json5`
macOS	`~/.config/openclaw/openclaw.json5`
Windows	`%USERPROFILE%\.config\openclaw\openclaw.json5`
Docker	`/app/config/openclaw.json5`（通过卷映射）

你也可以通过环境变量指定自定义路径：

export OPENCLAW_CONFIG=/path/to/your/openclaw.json5
openclaw up

完整配置结构概览

{
  gateway: { /* 网关设置 */ },
  models: { /* 模型配置 */ },
  channels: { /* 频道对接 */ },
  skills: { /* 技能插件 */ },
  persona: { /* AI 人设 */ },
  logging: { /* 日志设置 */ },
  security: { /* 安全设置 */ },
  advanced: { /* 高级选项 */ },
}

下面逐一详解每个配置段。

gateway：网关设置

网关是 OpenClaw 的核心入口，处理所有 HTTP 请求和频道消息。

{
  gateway: {
    // 监听端口，默认 18789
    port: 18789,

    // 监听地址
    // "127.0.0.1" 仅本机访问
    // "0.0.0.0" 允许所有网络访问
    host: "0.0.0.0",

    // Dashboard 密码（建议在生产环境设置）
    dashboardPassword: "your-strong-password",

    // API 密钥（用于外部调用 OpenClaw API）
    apiKey: "your-api-key",

    // 请求超时（毫秒）
    timeout: 120000,

    // 最大请求体大小
    maxBodySize: "10mb",

    // CORS 设置
    cors: {
      enabled: true,
      origins: ["*"],
    },
  },
}

关键参数说明

参数	类型	默认值	说明
`port`	number	18789	网关端口
`host`	string	"127.0.0.1"	监听地址
`dashboardPassword`	string	无	Dashboard 访问密码
`apiKey`	string	无	API 认证密钥
`timeout`	number	120000	请求超时（ms）
`maxBodySize`	string	"10mb"	最大请求体

models：模型配置

模型配置定义了 OpenClaw 使用哪些 AI 模型以及如何调用它们。

{
  models: {
    // 默认使用的模型提供商
    default: "claude",

    // 各模型提供商配置
    providers: {
      claude: {
        apiKey: "sk-ant-xxxxx",
        model: "claude-sonnet-4-20250514",
        maxTokens: 4096,
        temperature: 0.7,
        baseUrl: "https://api.anthropic.com",  // 可选，自定义API端点
      },

      openai: {
        apiKey: "sk-xxxxx",
        model: "gpt-4o",
        maxTokens: 4096,
        temperature: 0.7,
        baseUrl: "https://api.openai.com/v1",
      },

      ollama: {
        baseUrl: "http://localhost:11434",
        model: "llama3.1",
        maxTokens: 2048,
      },

      gemini: {
        apiKey: "AIzaSyxxxxx",
        model: "gemini-2.0-flash",
        maxTokens: 4096,
      },

      openrouter: {
        apiKey: "sk-or-xxxxx",
        model: "anthropic/claude-sonnet-4-20250514",
        baseUrl: "https://openrouter.ai/api/v1",
      },
    },

    // 模型路由规则（详见多模型切换教程）
    routing: {
      rules: [],
      fallback: "claude",
    },
  },
}

各提供商必填参数

提供商	必填参数	可选参数
Claude	`apiKey`, `model`	`maxTokens`, `temperature`, `baseUrl`
OpenAI	`apiKey`, `model`	`maxTokens`, `temperature`, `baseUrl`
Ollama	`baseUrl`, `model`	`maxTokens`, `temperature`
Gemini	`apiKey`, `model`	`maxTokens`, `temperature`
OpenRouter	`apiKey`, `model`	`maxTokens`, `baseUrl`

channels：频道对接

频道配置定义了 OpenClaw 连接哪些即时通讯平台。

{
  channels: {
    whatsapp: {
      enabled: true,
      phoneNumber: "+86138xxxx",
      // WhatsApp Business API 配置
      accessToken: "your-access-token",
      verifyToken: "your-verify-token",
      webhookPath: "/webhook/whatsapp",
    },

    telegram: {
      enabled: true,
      token: "123456:ABC-DEF...",
      // 可选：限制允许的用户
      allowedUsers: [12345678, 87654321],
      // 可选：限制允许的群组
      allowedGroups: [-100123456789],
    },

    discord: {
      enabled: true,
      token: "your-discord-bot-token",
      allowedChannels: ["general", "ai-chat"],
    },

    slack: {
      enabled: true,
      appToken: "xapp-xxxxx",
      botToken: "xoxb-xxxxx",
    },

    // 更多频道...
    // imessage, signal, teams, googlechat, matrix, line, irc
  },
}

skills：技能插件

技能是 OpenClaw 的扩展机制，以 SKILL.md 文件形式存放在 ~/.openclaw/skills/ 目录中。

{
  skills: {
    // 技能文件存放目录
    directory: "~/.openclaw/skills",

    // 启用的技能列表（留空则全部启用）
    enabled: [
      "weather",
      "calculator",
      "translator",
    ],

    // 禁用的技能列表
    disabled: [],

    // MCP Server 集成
    mcpServers: {
      filesystem: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"],
      },
      web: {
        command: "npx",
        args: ["-y", "@anthropic/mcp-server-web"],
      },
    },
  },
}

persona：AI 人设

人设配置决定了 AI 助手的性格和回复风格。

{
  persona: {
    // 系统提示词
    systemPrompt: "你是一个友好、专业的AI助手，名叫小智。你会用简洁明了的中文回答问题。",

    // 人设名称
    name: "小智",

    // 回复语言（auto 为自动检测）
    language: "zh-CN",

    // 语气风格：formal, casual, friendly, professional
    tone: "friendly",

    // 每个频道的独立人设（覆盖全局设置）
    channelOverrides: {
      telegram: {
        systemPrompt: "你是Telegram群组的管理助手...",
        tone: "casual",
      },
      slack: {
        systemPrompt: "你是团队的工作助手，回复专业简洁...",
        tone: "professional",
      },
    },
  },
}

logging：日志设置

{
  logging: {
    // 日志级别：debug, info, warn, error
    level: "info",

    // 日志文件路径（留空则仅输出到控制台）
    file: "~/.openclaw/logs/openclaw.log",

    // 日志文件最大大小
    maxSize: "10m",

    // 保留日志文件数量
    maxFiles: 5,

    // 是否在控制台输出彩色日志
    colorize: true,

    // 日志格式：json, text
    format: "text",
  },
}

security：安全设置

{
  security: {
    // 启用请求频率限制
    rateLimit: {
      enabled: true,
      maxRequests: 60,     // 每分钟最大请求数
      windowMs: 60000,     // 窗口时间（毫秒）
    },

    // IP 白名单（留空不限制）
    ipWhitelist: [],

    // IP 黑名单
    ipBlacklist: [],

    // 启用 HTTPS（需要提供证书）
    tls: {
      enabled: false,
      cert: "/path/to/cert.pem",
      key: "/path/to/key.pem",
    },
  },
}

advanced：高级选项

{
  advanced: {
    // 工作线程数（0 为自动）
    workers: 0,

    // 消息队列大小
    queueSize: 100,

    // 上下文记忆的最大消息数
    maxContextMessages: 20,

    // 上下文记忆的最大 token 数
    maxContextTokens: 8000,

    // 数据存储后端：memory, sqlite, redis
    storage: "sqlite",

    // SQLite 数据库路径
    dbPath: "~/.openclaw/data/openclaw.db",

    // Redis 连接（如果 storage 为 redis）
    redis: {
      url: "redis://localhost:6379",
      db: 0,
    },
  },
}

环境变量覆盖

配置文件中的部分敏感字段可以通过环境变量覆盖，避免将密钥直接写入文件：

# 模型 API 密钥
export OPENCLAW_CLAUDE_API_KEY="sk-ant-xxxxx"
export OPENCLAW_OPENAI_API_KEY="sk-xxxxx"

# 频道 Token
export OPENCLAW_TELEGRAM_TOKEN="123456:ABC-DEF..."
export OPENCLAW_DISCORD_TOKEN="your-discord-token"

# 网关密码
export OPENCLAW_DASHBOARD_PASSWORD="your-password"

在配置文件中使用 $env 引用：

{
  models: {
    providers: {
      claude: {
        apiKey: "$env:OPENCLAW_CLAUDE_API_KEY",
        model: "claude-sonnet-4-20250514",
      },
    },
  },
}

配置验证

修改配置文件后，可以在启动前验证配置是否正确：

# 检查配置文件语法和必填项
openclaw doctor

# 仅验证配置文件（不启动服务）
openclaw doctor --config-only

最小化配置示例

如果你只需要最基本的功能，配置文件可以非常简洁：

{
  models: {
    default: "claude",
    providers: {
      claude: {
        apiKey: "sk-ant-xxxxx",
        model: "claude-sonnet-4-20250514",
      },
    },
  },
  channels: {
    telegram: {
      enabled: true,
      token: "your-telegram-bot-token",
    },
  },
}

未显式配置的选项将使用默认值。

总结

openclaw.json5 是 OpenClaw 的核心配置文件，采用人性化的 JSON5 格式，支持注释和灵活的语法。理解各配置段的作用后，你可以根据实际需求精确调整 OpenClaw 的行为。建议从最小化配置开始，逐步添加所需的功能模块。修改配置后别忘了运行 openclaw doctor 验证，然后用 openclaw restart 重载。