脚本之家 服务器常用软件
快捷导航
您的位置：主页 > AI > openclaw > OpenClaw主配置文件参数

OpenClaw主配置文件参数使用大全

  发布时间：2026-03-10 10:55:45   作者：liu_zhiyi   我要评论
OpenClaw 使用 JSON/JSON5 格式的配置文件来管理系统所有组件的设置，支持灵活的配置覆盖、环境变量注入、多配置文件合并、热重载等功能,本文就来详细的介绍一下OpenClaw主配置文件参数，感兴趣的可以了解一下

配置文件概述

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

主要特性

  • JSON5 支持：支持注释、尾随逗号、单引号等扩展语法
  • 环境变量：可通过 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 - 元数据

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

参数说明

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

配置示例

{
  "meta": {
    "lastTouchedVersion": "2026.3.2",
    "lastTouchedAt": "2026-03-05T05:04:35.393Z"
  }
}

wizard - 向导记录

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

参数说明

参数类型默认值说明
lastRunAtstring-最后运行向导的时间
lastRunVersionstring-运行向导时的版本
lastRunCommandstring-最后运行的命令
lastRunModestring-运行模式 (local/remote)

配置示例

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

auth - 认证配置

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

参数说明

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

认证配置对象

{
  "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 - 模型配置

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

参数说明

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

提供商配置结构

{
  "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）的默认设置和实例列表。

参数说明

参数类型默认值说明
defaultsobject{}默认代理配置
listarray[]代理实例列表

默认代理配置

{
  "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": "/Users/blueboat-mac/.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、飞书、Discord 等）。

通用频道参数

参数类型默认值说明
enabledbooleantrue是否启用频道
dmPolicystring“pairing”私聊策略 (pairing/allowlist/open/disabled)
groupPolicystring“open”群聊策略 (allowlist/open/disabled)
streamingstring/boolean“partial”流式输出 (true/false/“partial”)
allowFromarray[]允许的用户/群组列表
textChunkLimitnumber2000文本块大小限制
mediaMaxMbnumber30媒体文件大小限制 (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"
        }
      }
    }
  }
}

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 网关服务。

参数说明

参数类型默认值说明
portnumber18789WebSocket 端口
modestring“local”网关模式 (local/remote)
bindstring“loopback”绑定模式 (loopback/lan/tailnet/auto)
authobject{}网关认证配置
controlUiobject{}控制UI配置
tailscaleobject{}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）系统。

参数说明

参数类型默认值说明
backendstring“qmd”内存后端 (qmd/file)
citationsstring“auto”引用模式 (auto/always/never)
qmdobject{}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 插件。

参数说明

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

插件配置示例

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

commands - 命令配置

配置命令行行为。

参数说明

参数类型默认值说明
nativestring“auto”本地命令处理 (auto/enabled/disabled)
nativeSkillsstring“auto”本地技能处理
restartbooleantrue允许重启命令
ownerDisplaystring“raw”所有者显示方式

配置示例

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

messages - 消息配置

配置消息处理行为。

参数说明

参数类型默认值说明
ackReactionScopestring“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.2 版本整理
  • 配置参数可能随版本更新而变化，请参考最新官方文档
  • 示例配置中的敏感信息已用占位符替换，请替换为实际值
  • JSON5 语法支持注释和尾随逗号，但标准 JSON 也兼容

到此这篇关于OpenClaw主配置文件参数使用大全的文章就介绍到这了,更多相关OpenClaw主配置文件参数内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！

相关文章

  • 基于VMware+Ubuntu 24.04环境完成OpenClaw安装、配置与使用

    本文将基于 VMware + Ubuntu 24.04 环境，从零开始完成 OpenClaw 的安装、配置，并实现与飞书机器人的打通,本文通过图文并茂的形式给大家介绍的非常详细，对大家的学习或工
    2026-03-09

  • OpenClaw使用DeepSeek官方API_KEY配置超详细教程

    近期 OpenClaw突然火了,但是网上居然没有在openclaw配置deepseek官方apikey的相关教程，所以下面这篇文章主要介绍了OpenClaw使用DeepSeek官方API_KEY配置的相关资料,文中将
    2026-03-09

  • 本地部署OpenClaw安装配置使用教程

    本文给大家分享本地部署OpenClaw安装配置使用教程，本文给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友参考下吧
    2026-03-09

  • Mac mini上部署配置OpenClaw并接入国产大模型与飞书

    本文详细介绍了在Macmini上部署OpenClaw的全过程,包括配置安装及国产大模型接入以及飞书机器人集成,搭建一个的AI助手,满足日常自动化需求，需要的朋友们下面随着小编来一起
    2026-03-09

  • Ubuntu系统OpenClaw版本降级的实例操作

    本文主要介绍了如何将OpenClaw从2026.3.2版本降级到2026.2.3版本,降级的核心动因是新版本存在Bug、兼容性差或功能/性能不符合需求,文章详细描述了命令行版本和桌面端版本的
    2026-03-07

  • OpenClaw使用Ollama本地模型的实现(支持工具调用))

    Ollama 是一个本地 LLM 运行时，可以轻松在你的机器上运行开源模型,OpenClaw 通过 Ollama 的 OpenAI 兼容 API 进行集成，下面就来详细的介绍一下，感兴趣的可以了解一下
    2026-03-06

  • OpenClaw 安装与配置实战指南(含常用命令 + 故障排查)

    OpenClaw安装与配置实战,涵盖了从安装到故障排查的详细流程,重点包括通道配置、模型接入和网关排障,提供了常用命令速查和故障排查步骤,帮助用户顺利上手和解决常见问题，本
    2026-03-06

  • OpenClaw 本地安装与配置十分钟完成(附常用命令速查)

    OpenClaw 是一个开源的个人 AI 助手,支持系统操作、文件读写、代码执行等,它可以通过配置文件进行各种设置,这篇文章给大家介绍OpenClaw 快速入门：10 分钟完成本地安装与配
    2026-03-06

  • openclaw飞书流式回复配置指南

    OpenClaw 支持飞书通过 Card Kit 交互式卡片 实现流式回复,本文就来介绍一下相关配置及其实现步骤，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考
    2026-03-05

  • 在OpenClaw中配置和使用Coding Plan的详细步骤

    OpenClaw （原名Moltbot/Clawdbot ）是一个开源的个人 AI 助手平台，支持通过多种消息渠道与 AI 交互,通过配置可接入阿里云百炼的Coding Plan模型,本文给大家详细介绍了如
    2026-03-04

最新评论

关注微信公众号

扫一扫