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

目录

• 配置文件概述
• 主要特性
• 文件格式与位置
• 主配置文件
• 配置文件格式
• 环境变量引用
• 配置文件结构总览
• meta – 元数据
• 参数说明
• 配置示例
• wizard – 向导记录
• 参数说明
• 配置示例
• auth – 认证配置
• 参数说明
• 认证配置对象
• 配置示例
• models – 模型配置
• 参数说明
• 提供商配置结构
• 支持的 API 类型
• 配置示例
• agents – 代理配置
• 参数说明
• 默认代理配置
• 代理实例配置
• 配置示例
• channels – 频道配置
• 通用频道参数
• Telegram 配置
• 飞书 (Feishu) 配置
• Discord 配置
• WhatsApp 配置
• 配置示例
• gateway – 网关配置
• 参数说明
• 认证配置
• 控制UI配置
• Tailscale 配置
• 配置示例
• memory – 内存配置
• 参数说明
• QMD 后端配置
• 配置示例
• plugins – 插件配置
• 参数说明
• 插件配置示例
• commands – 命令配置
• 参数说明
• 配置示例
• messages – 消息配置
• 参数说明
• 配置示例
• 常用配置片段示例
• 示例1：基础模型配置
• 示例2：多代理工作区配置
• 示例3：频道安全配置
• 示例4：开发环境配置
• 示例5：生产环境配置
• 配置最佳实践
• 1. 安全配置
• 2. 性能优化
• 3. 维护建议
• 4. 环境区分
• 配置验证与调试
• 验证配置
• 调试配置问题
• 配置重载
• 相关资源

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": [],                // 代理绑定（可选）
}

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

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

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

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

参数	类型	默认值	说明
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"
  }
}

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

参数	类型	默认值	说明
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"
      }
    }
  }
}

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

参数	类型	默认值	说明
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数
          }
        ]
      }
    }
  }
}

• 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
          }
        ]
      }
    }
  }
}

配置代理（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": "/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"
      }
    ]
  }
}

配置聊天频道（如 Telegram、飞书、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)

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

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

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

{
  "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": ["*"]
    }
  }
}

配置 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"   // 认证密码
    }
  }
}

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

{
  "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）系统。

参数	类型	默认值	说明
backend	string	“qmd”	内存后端 (qmd/file)
citations	string	“auto”	引用模式 (auto/always/never)
qmd	object	{}	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"
            }
          }
        ]
      }
    }
  }
}

管理 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" // 插件路径
      }
    }
  }
}

配置命令行行为。

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

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

配置消息处理行为。

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

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

// 基础模型配置
{
  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"]
      }
    }
  }
}

// 多代理配置
{
  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"
      }
    ]
  }
}

// 安全的频道配置
{
  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"
    }
  }
}

// 开发环境配置
{
  gateway: {
    port: 19001,          // 开发端口
    bind: "loopback",     // 仅本地访问
    controlUi: {
      enabled: true,
      allowInsecureAuth: true  // 开发时允许不安全认证
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "deepseek/deepseek-chat",
        fallbacks: []
      }
    }
  },
  memory: {
    backend: "file",      // 使用文件后端（简化）
    citations: "never"    // 开发时不显示引用
  }
}

// 生产环境配置
{
  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
      }
    }
  }
}

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

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

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

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

# 验证配置文件语法
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

• 官方文档：https://docs.openclaw.ai/configuration
• 配置示例：https://github.com/openclaw/openclaw/tree/main/examples/configs
• 问题反馈：https://github.com/openclaw/openclaw/issues

文档说明：

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

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