openclaw

关注公众号 jb51net

关闭
AI > openclaw >

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

liu_zhiyi

配置文件概述

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

主要特性

文件格式与位置

主配置文件

# 主配置文件路径
~/.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 类型

配置示例

{
  "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. 安全配置

2. 性能优化

3. 维护建议

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主配置文件参数内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！