首页 / 玩转OpenClaw：主配置文件参数详解指南手册

玩转OpenClaw：主配置文件参数详解指南手册

03-13 24人

玩转OpenClaw主配置文件参数详解指南手册

配置文件概述

OpenClaw 使用 JSON / JSON5 格式的配置文件来管理系统所有组件的设置。配置文件采用分层结构，支持灵活的配置覆盖和环境变量注入。

主要特性

  • JSON5 支持：支持注释、尾随逗号、单引号等扩展语法
  • 环境变量：可通过 env 字段或者 .env文件注入环境变量
  • 配置合并：支持多配置文件合并（主配置 + 环境配置）
  • 热重载：部分配置支持运行时重载（需重启网关）

文件格式与位置

主配置文件

# 主配置文件路径
~/.openclaw/openclaw.json

# 配置文件备份
~/.openclaw/openclaw.json.bak

配置文件格式

OpenClaw 支持标准的 JSON 和 JSON5 格式

// JSON5 示例（支持注释）
{
  // 模型配置
  models: {
    // 提供商列表
    providers: {
      openai: {
        apiKey: "${OPENAI_API_KEY}",  // 环境变量引用
      },
    },
  },

  // 代理配置
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-4o",
      },
    },
  },
}

环境变量引用

{
  env: {
    // 设置环境变量
    "OPENAI_API_KEY": "sk-xxx",
  },

  models: {
    providers: {
      openai: {
        // 引用环境变量
        apiKey: "${OPENAI_API_KEY}",
      },
    },
  },
}

配置文件结构总览

{
  "meta": {},                    // 元数据
  "wizard": {},                  // 向导记录
  "auth": {},                    // 认证配置
  "models": {},                  // 模型配置
  "agents": {},                  // 代理配置
  "channels": {},                // 频道配置
  "gateway": {},                 // 网关配置
  "memory": {},                  // 内存配置
  "plugins": {},                 // 插件配置
  "commands": {},                // 命令配置
  "messages": {},                // 消息配置
  "env": {},                     // 环境变量（可选）
  "tools": {},                   // 工具配置（可选）
  "bindings": [],                // 代理绑定（可选）
}

meta - 元数据

记录配置文件的元数据信息，由系统自动维护。

参数说明

参数 类型 默认值 说明
lastTouchedVersion string - 最后修改配置的 OpenClaw 版本
lastTouchedAt string - 最后修改时间 (ISO 8601)

配置示例

{
  "meta": {
    "lastTouchedVersion": "2026.3.11",
    "lastTouchedAt": "2026-03-13T01:42:30.878Z"
  }
}

wizard - 向导记录

记录配置向导的运行状态。

参数说明

参数 类型 默认值 说明
lastRunAt string - 最后运行向导的时间
lastRunVersion string - 运行向导时的版本
lastRunCommand string - 最后运行的命令
lastRunMode string - 运行模式 (local/remote)

配置示例

{
  "wizard": {
    "lastRunAt": "2026-02-25T12:06:39.761Z",
    "lastRunVersion": "2026.2.24",
    "lastRunCommand": "configure",
    "lastRunMode": "local"
  }
}

auth - 认证配置

管理模型提供商的认证信息。

参数说明

参数 类型 默认值 说明
profiles object {} 认证配置集合

认证配置对象

{
  "auth": {
    "profiles": {
      "<provider>:<profile>": {
        "provider": "openai",        // 提供商名称
        "mode": "api_key",          // 认证模式
        "apiKey": "sk-xxx",         // API密钥
        "baseUrl": "https://api.openai.com/v1"  // API基础URL
      }
    }
  }
}

配置示例

{
  "auth": {
    "profiles": {
      "minimax-cn:default": {
        "provider": "minimax-cn",
        "mode": "api_key"
      },
      "openai:default": {
        "provider": "openai",
        "mode": "api_key"
      }
    }
  }
}

models - 模型配置

配置模型提供商和可用模型。

参数说明

参数 类型 默认值 说明
mode string “merge” 配置模式 (merge/replace)
providers object {} 模型提供商配置

提供商配置结构

{
  "models": {
    "providers": {
      "<provider-name>": {
        "baseUrl": "https://api.example.com",  // API基础URL
        "apiKey": "sk-xxx",                    // API密钥
        "api": "openai-completions",          // API类型
        "models": [                           // 可用模型列表
          {
            "id": "model-name",               // 模型ID
            "name": "显示名称",               // 模型显示名称
            "reasoning": true,                // 是否支持推理
            "input": ["text", "image"],       // 支持的输入类型
            "cost": {                         // 成本配置
              "input": 0.1,                   // 输入token成本
              "output": 0.3,                  // 输出token成本
              "cacheRead": 0.01,              // 缓存读取成本
              "cacheWrite": 0.05              // 缓存写入成本
            },
            "contextWindow": 128000,          // 上下文窗口大小
            "maxTokens": 4096                 // 最大输出token数
          }
        ]
      }
    }
  }
}

支持的 API 类型

  • openai-completions - OpenAI 兼容的补全API
  • anthropic-messages - Anthropic Messages API
  • openrouter - OpenRouter API

配置示例

{
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-reasoner",
            "name": "DeepSeek Reasoner",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0.14,
              "output": 2.19
            },
            "contextWindow": 64000,
            "maxTokens": 8192
          }
        ]
      },
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "input": ["text", "image"],
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

agents - 代理配置

配置代理（agent）的默认设置和实例列表。

参数说明

参数 类型 默认值 说明
defaults object {} 默认代理配置
list array [] 代理实例列表

默认代理配置

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-4o",       // 主要模型
        "fallbacks": [                    // 回退模型列表
          "anthropic/claude-3-5-sonnet",
          "deepseek/deepseek-chat"
        ]
      },
      "models": {                         // 模型别名和参数
        "openai/gpt-4o": {
          "alias": "GPT-4o",
          "params": {
            "temperature": 0.7,
            "max_tokens": 4096
          }
        }
      },
      "workspace": "~/.openclaw/workspace",  // 工作区路径
      "compaction": {                        // 压缩配置
        "mode": "safeguard"                  // 模式：safeguard/aggressive/off
      },
      "maxConcurrent": 4,                    // 最大并发数
      "subagents": {                         // 子代理配置
        "maxConcurrent": 8,                  // 子代理最大并发数
        "allowAgents": []                    // 允许的子代理列表
      }
    }
  }
}

代理实例配置

{
  "agents": {
    "list": [
      {
        "id": "main",                      // 代理ID
        "name": "主代理",                  // 显示名称（可选）
        "model": "deepseek/deepseek-chat", // 模型覆盖
        "workspace": "/path/to/workspace", // 工作区覆盖
        "subagents": {                     // 子代理配置
          "allowAgents": [                 // 允许的子代理ID
            "prompt-engineer",
            "media-generator"
          ]
        }
      }
    ]
  }
}

配置示例

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "minimax/MiniMax-M2.5",
        "fallbacks": [
          "minimax-cn/MiniMax-M2.5",
          "deepseek/deepseek-reasoner"
        ]
      },
      "models": {
        "minimax/MiniMax-M2.5": {
          "alias": "Minimax"
        }
      },
      "workspace": "~/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    },
    "list": [
      {
        "id": "main",
        "model": "deepseek/deepseek-reasoner"
      },
      {
        "id": "support",
        "name": "支持代理",
        "workspace": "/path/to/support-workspace"
      }
    ]
  }
}

channels - 频道配置

配置聊天频道（如 Telegram、飞书、QQ、Discord 等）。

通用频道参数

参数 类型 默认值 说明
enabled boolean true 是否启用频道
dmPolicy string “pairing” 私聊策略 (pairing/allowlist/open/disabled)
groupPolicy string “open” 群聊策略 (allowlist/open/disabled)
streaming string/boolean “partial” 流式输出 (true/false/“partial”)
allowFrom array [] 允许的用户/群组列表
textChunkLimit number 2000 文本块大小限制
mediaMaxMb number 30 媒体文件大小限制 (MB)

Telegram 配置

{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "botToken": "YOUR_BOT_TOKEN",  // Telegram Bot Token
      "groupPolicy": "allowlist",
      "streaming": "partial",
      "allowFrom": ["@username", "chat_id"]
    }
  }
}

飞书 (Feishu) 配置

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",           // 飞书应用ID
      "appSecret": "xxx",           // 飞书应用Secret
      "domain": "feishu",           // 域名 (feishu/lark)
      "dmPolicy": "allow",
      "accounts": {
        "default": {
          "appId": "cli_xxx"
        }
      }
    }
  }
}

QQ 配置

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "allowFrom": [
        "*"
      ],
      "appId": "12345xxxx",           // 机器人AppId
      "clientSecret": "xxx",           // 机器人AppSecret
    }
  }
}

Discord 配置

{
  "channels": {
    "discord": {
      "enabled": true,
      "botToken": "YOUR_DISCORD_TOKEN",
      "clientId": "YOUR_CLIENT_ID",
      "dmPolicy": "pairing",
      "groupPolicy": "open"
    }
  }
}

WhatsApp 配置

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "sessionPath": "~/.openclaw/whatsapp-session",
      "dmPolicy": "pairing",
      "qrTimeout": 300000  // QR码超时时间(ms)
    }
  }
}

配置示例

{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "streaming": "partial"
    },
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",
      "domain": "feishu",
      "dmPolicy": "allow",
      "allowFrom": ["*"]
    }
  }
}

gateway - 网关配置

配置 OpenClaw 网关服务。

参数说明

参数 类型 默认值 说明
port number 18789 WebSocket 端口
mode string “local” 网关模式 (local/remote)
bind string “loopback” 绑定模式 (loopback/lan/tailnet/auto)
auth object {} 网关认证配置
controlUi object {} 控制UI配置
tailscale object {} Tailscale 集成配置

认证配置

{
  "gateway": {
    "auth": {
      "mode": "token",              // 认证模式 (token/password/none)
      "token": "your_token_here",   // 认证令牌
      "password": "your_password"   // 认证密码
    }
  }
}

控制UI配置

{
  "gateway": {
    "controlUi": {
      "enabled": true,                            // 启用控制UI
      "dangerouslyAllowHostHeaderOriginFallback": false,  // 允许Host头回退
      "allowInsecureAuth": false                  // 允许不安全认证
    }
  }
}

Tailscale 配置

{
  "gateway": {
    "tailscale": {
      "mode": "off",              // Tailscale模式 (off/serve/funnel)
      "resetOnExit": false        // 退出时重置配置
    }
  }
}

配置示例

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "enabled": true,
      "allowInsecureAuth": true
    },
    "auth": {
      "mode": "token"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  }
}

memory - 内存配置

配置记忆（memory）系统。

参数说明

参数 类型 默认值 说明
backend string “qmd” 内存后端 (qmd/file)
citations string “auto” 引用模式 (auto/always/never)
qmd object {} QMD 后端配置

QMD 后端配置

{
  "memory": {
    "qmd": {
      "includeDefaultMemory": true,    // 包含默认内存
      "update": {                      // 更新配置
        "interval": "5m",              // 更新间隔
        "debounceMs": 15000,           // 防抖时间(ms)
        "onBoot": true                 // 启动时更新
      },
      "limits": {                      // 限制配置
        "maxResults": 10,              // 最大结果数
        "maxSnippetChars": 2000,       // 最大片段字符数
        "timeoutMs": 10000             // 超时时间(ms)
      },
      "scope": {                       // 作用域配置
        "default": "deny",             // 默认动作
        "rules": [                     // 规则列表
          {
            "action": "allow",         // 动作 (allow/deny)
            "match": {                 // 匹配条件
              "chatType": "direct"     // 聊天类型
            }
          }
        ]
      }
    }
  }
}

配置示例

{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "includeDefaultMemory": true,
      "update": {
        "interval": "5m",
        "debounceMs": 15000,
        "onBoot": true
      },
      "limits": {
        "maxResults": 10,
        "maxSnippetChars": 2000,
        "timeoutMs": 10000
      },
      "scope": {
        "default": "deny",
        "rules": [
          {
            "action": "allow",
            "match": {
              "chatType": "direct"
            }
          }
        ]
      }
    }
  }
}

plugins - 插件配置

管理 OpenClaw 插件。

参数说明

参数 类型 默认值 说明
entries object {} 插件条目配置
installs object {} 插件安装记录

插件配置示例

{
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true          // 启用Telegram插件
      },
      "feishu": {
        "enabled": true          // 启用飞书插件
      }
    },
    "installs": {
      "@openclaw/feishu": {
        "version": "1.0.0",      // 插件版本
        "path": "/path/to/plugin" // 插件路径
      }
    }
  }
}

commands - 命令配置

配置命令行行为。

参数 类型 默认值 说明
native string “auto” 本地命令处理 (auto/enabled/disabled)
nativeSkills string “auto” 本地技能处理
restart boolean true 允许重启命令
ownerDisplay string “raw” 所有者显示方式

配置示例

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

messages - 消息配置

配置消息处理行为。

参数说明

参数 类型 默认值 说明
ackReactionScope string “group-mentions” 确认反应范围

配置示例

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

常用配置片段示例

示例1：基础模型配置

// 基础模型配置
{
  env: {
    "OPENAI_API_KEY": "sk-xxx",
    "ANTHROPIC_API_KEY": "sk-ant-xxx"
  },

  models: {
    providers: {
      openai: {
        apiKey: "${OPENAI_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gpt-4o",
            name: "GPT-4o",
            input: ["text", "image"],
            contextWindow: 128000
          }
        ]
      }
    }
  },

  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-4o",
        fallbacks: ["anthropic/claude-3-5-sonnet"]
      }
    }
  }
}

示例2：多代理工作区配置

// 多代理配置
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      maxConcurrent: 4
    },
    list: [
      {
        id: "main",
        name: "主代理",
        model: "deepseek/deepseek-chat"
      },
      {
        id: "research",
        name: "研究代理",
        workspace: "~/.openclaw/workspace-research",
        model: "openai/gpt-4o"
      },
      {
        id: "coding",
        name: "编程代理",
        workspace: "~/.openclaw/workspace-coding",
        model: "deepseek/deepseek-coder"
      }
    ]
  }
}

示例3：频道安全配置

// 安全的频道配置
{
  channels: {
    telegram: {
      enabled: true,
      dmPolicy: "allowlist",
      groupPolicy: "allowlist",
      allowFrom: [
        "user_id_1",      // 允许的用户ID
        "group_id_1"      // 允许的群组ID
      ]
    },

    feishu: {
      enabled: true,
      dmPolicy: "pairing",  // 需要配对
      groupPolicy: "open",
      allowFrom: ["*"]      // 允许所有（仅当policy为open时）
    }
  },

  gateway: {
    auth: {
      mode: "token",        // 要求令牌认证
      token: "secure_token_here"
    }
  }
}

示例4：开发环境配置

// 开发环境配置
{
  gateway: {
    port: 19001,          // 开发端口
    bind: "loopback",     // 仅本地访问
    controlUi: {
      enabled: true,
      allowInsecureAuth: true  // 开发时允许不安全认证
    }
  },

  agents: {
    defaults: {
      model: {
        primary: "deepseek/deepseek-chat",
        fallbacks: []
      }
    }
  },

  memory: {
    backend: "file",      // 使用文件后端（简化）
    citations: "never"    // 开发时不显示引用
  }
}

示例5：生产环境配置

// 生产环境配置
{
  gateway: {
    port: 18789,
    bind: "lan",          // 局域网访问
    auth: {
      mode: "password",   // 密码认证
      password: "strong_password_here"
    },
    controlUi: {
      enabled: true,
      dangerouslyAllowHostHeaderOriginFallback: false,
      allowInsecureAuth: false
    }
  },

  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-4o",
        fallbacks: [
          "anthropic/claude-3-5-sonnet",
          "deepseek/deepseek-chat"
        ]
      },
      maxConcurrent: 8,
      subagents: {
        maxConcurrent: 16
      }
    }
  },

  memory: {
    backend: "qmd",
    qmd: {
      update: {
        interval: "1h",   // 生产环境更新间隔较长
        debounceMs: 30000
      }
    }
  }
}

配置最佳实践

1. 安全配置

  • 使用环境变量：敏感信息（API密钥、令牌）应通过环境变量注入
  • 限制访问：根据需求设置 dmPolicy 和 groupPolicy
  • 网关认证：生产环境务必启用网关认证（token 或 password）
  • 网络绑定：根据部署环境选择合适的 bind 模式

2. 性能优化

  • 并发控制：根据服务器资源调整 maxConcurrent
  • 模型回退：配置合理的回退模型链确保服务可用性
  • 内存管理：根据使用场景调整内存更新间隔

3. 维护建议

  • 版本控制：将配置文件纳入版本控制系统
  • 配置验证：修改后运行 openclaw config validate
  • 备份配置：定期备份 openclaw.json 文件
  • 渐进变更：一次只修改少量配置，验证后再继续

4. 环境区分

  • 开发环境：使用简化配置，禁用不必要的安全检查
  • 测试环境：模拟生产配置，但使用测试密钥
  • 生产环境：启用所有安全特性，使用正式密钥

配置验证与调试

验证配置

# 验证配置文件语法
openclaw config validate

# 查看完整配置
openclaw config get

# 查看特定配置项
openclaw config get gateway.port
openclaw config get agents.defaults.model.primary

调试配置问题

# 查看配置相关日志
openclaw logs --follow --grep "config\|error"

# 检查网关状态
openclaw gateway status

# 运行诊断
openclaw doctor --repair

配置重载

# 重启网关使配置生效
openclaw gateway restart

# 或停止后重新启动
openclaw gateway stop
openclaw gateway start

相关资源

  • 文档说明：
    • 本文档基于 OpenClaw 2026.3.11 版本整理
    • 配置参数可能随版本更新而变化，请参考最新官方文档
    • 示例配置中的敏感信息已用占位符替换，请替换为实际值
    • JSON5 语法支持注释和尾随逗号，但标准 JSON 也兼容
继续浏览有关 OpenClaw配置OpenClawOpenClaw参数openclaw.json 的文章

版权属于: 游魂博客

原文地址: https://www.iyouhun.com/post-309.html

转载时必须以链接形式注明原始出处及本声明。

欢迎留言