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

游魂

修改于 2026-03-18 17:04:31

3.8K0

文章被收录于专栏：AIAI

配置文件概述

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：主配置文件参数详解指南手册

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

配置文件概述

主要特性

文件格式与位置

主配置文件

配置文件格式

环境变量引用

配置文件结构总览

meta - 元数据

参数说明

配置示例

wizard - 向导记录

参数说明

配置示例

auth - 认证配置

参数说明

认证配置对象

配置示例

models - 模型配置

参数说明

提供商配置结构

支持的 API 类型

配置示例

agents - 代理配置

参数说明

默认代理配置

代理实例配置

配置示例

channels - 频道配置

通用频道参数

Telegram 配置

飞书 (Feishu) 配置

QQ 配置

Discord 配置

WhatsApp 配置

配置示例

gateway - 网关配置

参数说明

认证配置

控制UI配置

Tailscale 配置

配置示例

memory - 内存配置

参数说明

QMD 后端配置

配置示例

plugins - 插件配置

参数说明

插件配置示例

commands - 命令配置

配置示例

messages - 消息配置

参数说明

配置示例

常用配置片段示例

示例1：基础模型配置

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

示例3：频道安全配置

示例4：开发环境配置

示例5：生产环境配置

配置最佳实践

1. 安全配置

2. 性能优化

3. 维护建议

4. 环境区分

配置验证与调试

验证配置

调试配置问题

配置重载

相关资源

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐