openclaw配置文件讲解

一起唠嗑
#1

OpenClaw 配置文件详解

OpenClaw 的配置文件位于 C:\Users\{用户名}\.openclaw\openclaw.json。以下是各配置项的详细说明。

新增模型方法不唯一，自己熟悉哪种用那种（萝卜白菜各有所爱）

                                                                 ——星河璀璨

:star2: 每周速递来了～ - 社区问答- OceanBase社区-分布式数据库

目录

  • 顶层配置项
  • 模型配置
  • 智能体配置
  • 其他重要项配置
  • 如何新增模型
  • 配置文件路径
  • 相关命令

环境

win11 （配置文件都是一样的，学会方法即可）

顶层配置项

meta

"meta": {
  "lastTouchedVersion": "2026.2.5",
  "lastTouchedAt": "2026-03-24T03:21:43.841Z"
}
  • lastTouchedVersion: 最后修改配置时的 Clawdbot 版本
  • lastTouchedAt: 最后修改时间

env (环境变量)

"env": {
  "shellEnv": {
    "enabled": true
  }
}
  • shellEnv.enabled: 是否启用 Shell 环境变量传递

browser (浏览器)

我用的是Edge浏览器，习惯了，用了很多年了

"browser": {
  "enabled": true,
  "defaultProfile": "edge",
  "profiles": {
    "edge": {
      "cdpPort": 18801,
      "color": "#0066CC"
    }
  }
}
配置项 说明
enabled 是否启用浏览器控制功能
defaultProfile 默认使用的浏览器配置
profiles 浏览器配置列表，支持多浏览器
cdpPort Chrome DevTools Protocol 端口
color 浏览器标识颜色

auth (认证配置)

"auth": {
  "profiles": {
    "minimax:default": {
      "provider": "minimax",
      "mode": "api_key"
    },
    ...
  },
  "order": {
    "minimax": ["minimax:default"],
    ...
  }
}
配置项 说明
profiles 认证配置集合，名称:标签 格式
provider 认证提供商 (minimax, qwen-portal, volcengine, openrouter 等)
mode 认证模式 (api_key, oauth)
order 提供商优先级顺序

模型配置 (models)

这是最重要的部分，定义了所有可用的 AI 模型。

"models": {
  "mode": "merge",
  "providers": {
    "提供商名称": {
      "baseUrl": "API 地址",
      "apiKey": "密钥",
      "api": "API 类型",
      "models": [
        {
          "id": "模型ID",
          "name": "显示名称",
          "reasoning": false,
          "input": ["text"],
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      ]
    }
  }
}

模型配置字段说明

字段 必填 说明
id :white_check_mark: 模型唯一标识符，用于调用模型
name :white_check_mark: 人性化的显示名称
reasoning :white_check_mark: 是否为推理模型 (如 DeepSeek R1)
input :white_check_mark: 支持的输入类型 ["text"] 或 ["text", "image"]
cost.input :white_check_mark: 输入价格 (每百万 tokens)
cost.output :white_check_mark: 输出价格 (每百万 tokens)
cost.cacheRead :white_check_mark: 缓存读取价格
cost.cacheWrite :white_check_mark: 缓存写入价格
contextWindow :white_check_mark: 上下文窗口大小
maxTokens :white_check_mark: 最大输出 tokens 数

我当前已配置的提供商

提供商 baseUrl 说明
minimax https://api.minimax.chat/v1 MiniMax API
ollama http://localhost:11434/v1 本地 Ollama
qwen-portal https://portal.qwen.ai/v1 Qwen 开放平台 (OAuth)
volcengine https://ark.cn-beijing.volces.com/api/coding/v3 火山引擎
openrouter https://openrouter.ai/api/v1 OpenRouter 聚合平台

智能体配置 (agents)

定义智能体的默认行为和智能体列表。

agents.defaults (默认配置)

"agents": {
  "defaults": {
    "model": {
      "primary": "qwen-portal/coder-model",
      "fallbacks": ["minimax/MiniMax-M2.5"]
    },
    "models": {
      "qwen-portal/coder-model": {
        "alias": "qwen"
      }
    },
    "workspace": "C:\\Users\\{用户名}\\.openclaw\\workspace",
    "compaction": {
      "mode": "safeguard"
    },
    "typingIntervalSeconds": 6,
    "typingMode": "instant",
    "maxConcurrent": 4,
    "subagents": {
      "maxConcurrent": 8
    }
  }
}
配置项 说明
model.primary 默认主模型，格式 提供商/模型ID
model.fallbacks 备用模型列表
models 模型别名和参数配置
models[].alias 模型别名 (用于简短调用)
models[].params 模型参数 (temperature, top_p 等)
workspace 工作目录路径
compaction.mode 上下文压缩模式 (safeguard)
typingIntervalSeconds 输入打字动画间隔
typingMode 打字模式 (instant)
maxConcurrent 最大并发数
subagents.maxConcurrent 子智能体最大并发数

agents.list (智能体列表)

"agents": {
  "list": [
    {
      "id": "main",
      "model": {
        "primary": "minimax/MiniMax-M2.5",
        "fallbacks": ["qwen-portal/coder-model"]
      },
      "heartbeat": {
        "every": "1h"
      },
      "identity": {
        "name": "main",
        "avatar": ""
      },
      "tools": {
        "profile": "full"
      }
    }
  ]
}
配置项 说明
id 智能体唯一标识
model.primary 该智能体使用的主模型
model.fallbacks 备用模型
heartbeat.every 心跳间隔 (如 “1h”, “30m”)
identity.name 智能体名称
identity.avatar 头像路径
tools.profile 工具配置 (full/limited)
个人示例
"list": [
      {
        "id": "main",
        "model": {
          "primary": "minimax/MiniMax-M2.5",
          "fallbacks": [
            "qwen-portal/coder-model"
          ]
        },
        "heartbeat": {
          "every": "1h"
        },
        "identity": {
          "name": "main",
          "avatar": ""
        },
        "tools": {
          "profile": "full"
        }
      },
      ###我使用了两个agnets
      {
        "id": "backup",
        "model": {
          "primary": "qwen-portal/coder-model",
          "fallbacks": [
            "minimax/MiniMax-M2.5"
          ]
        },
        "heartbeat": {
          "every": "1h"
        },
        "identity": {
          "name": "备份助手",
          "avatar": ""
        },
        "tools": {
          "profile": "full"
        }
      }
    ]

其他重要配置

tools (工具配置)

"tools": {
  "profile": "full",
  "web": {
    "search": { "enabled": false },
    "fetch": { "enabled": true }
  }
}
  • profile: 工具配置模式
  • web.search: 是否启用网页搜索
  • web.fetch: 是否启用网页抓取

channels (频道配置)

"channels": {
  "wecom": {
    "enabled": true,
    "botId": "...",
    "secret": "...",
    "dmPolicy": "pairing"
  }
}
  • 企业微信配置

gateway (网关配置)

"gateway": {
  "port": 18789,
  "mode": "local",
  "bind": "lan",
  "auth": {
    "mode": "token",
    "token": "..."
  }
}
配置项 说明
port 网关端口
mode 模式 (local)
bind 绑定地址 (lan/wlan/localhost)
auth.mode 认证模式 (token)
auth.token 访问令牌

skills (技能配置)

"skills": {
  "load": {
    "extraDirs": [
      "C:\\Users\\James-zhou\\.openclaw\\skills",
      "C:\\Users\\James-zhou\\AppData\\Roaming\\npm\\node_modules\\openclaw-cn\\skills"
    ],
    "watch": true
  },
  "install": {
    "nodeManager": "npm"
  }
}
  • extraDirs: 额外技能目录
  • watch: 是否监听文件变化
  • nodeManager: Node 包管理器

plugins (插件配置)

"plugins": {
  "entries": {
    "qwen-portal-auth": { "enabled": true },
    "wecom-openclaw-plugin": { "enabled": true }
  }
}

如何新增模型

方式一：配置文件

1.在现有提供商中添加模型

在对应的 models.providers.提供商名称.models 数组中添加新模型：

{
  "id": "新模型ID",
  "name": "新模型显示名称",
  "reasoning": false,
  "input": ["text"],
  "cost": {
    "input": 0,
    "output": 0,
    "cacheRead": 0,
    "cacheWrite": 0
  },
  "contextWindow": 128000,
  "maxTokens": 8192
}

示例：在 volcengine 中添加新模型

"volcengine": {
  "models": [
    ...现有模型,
    {
      "id": "新模型ID",
      "name": "我的新模型",
      "reasoning": false,
      "input": ["text"],
      "cost": {
        "input": 0,
        "output": 0,
        "cacheRead": 0,
        "cacheWrite": 0
      },
      "contextWindow": 128000,
      "maxTokens": 8192
    }
  ]
}

2. 添加全新提供商

如果需要添加一个新的 API 提供商：

"models": {
  "providers": {
    "新提供商名称": {
      "baseUrl": "https://api.example.com/v1",
      "apiKey": "你的API密钥",
      "api": "openai-completions",
      "models": [
        {
          "id": "模型ID",
          "name": "模型名称",
          "reasoning": false,
          "input": ["text"],
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      ]
    }
  }
}

3：在 agents 中添加别名

为了方便使用，可以给模型设置别名：

标准规范
"agents": {
  "defaults": {
    "models": {
      "提供商/模型ID": {
        "alias": "简短别名",
        "params": {
          "temperature": 0.7,
          "top_p": 0.9
        }
      }
    }
  }
}

个人实例

"agents": {
    "defaults": {
      "model": {
        "primary": "qwen-portal/coder-model",
        "fallbacks": [
          "minimax/MiniMax-M2.5"
        ]
      },
      "models": {
        "minimax/MiniMax-M2.5": {
          "alias": "Minimax"
        },
        "ollama/qwen3:8b": {
          "alias": "Ollama Qwen3:8b",
          "params": {
            "temperature": 0.7,
            "top_p": 0.9
          }
        },
        "ollama/qwen3.5:4b": {
          "alias": "qwen3.5:4B",
          "params": {
            "temperature": 0.7,
            "top_p": 0.9
          }
        },
        省略部分——**——
        "qwen-portal/coder-model": {
          "alias": "qwen"
        },
        "qwen-portal/vision-model": {},
        "volcengine/doubao-seed-2.0-code": {
          "alias": "Doubao Code"
        },
        "volcengine/doubao-seed-2.0-pro": {
          "alias": "Doubao Pro"
        },
        "volcengine/kimi-k2.5": {
          "alias": "Kimi-K2.5"
        },
      },
      "workspace": "C:\\Users\\James-zhou\\.openclaw\\workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "typingIntervalSeconds": 6,
      "typingMode": "instant",
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },

方法二：CMD

openclaw onboard 界面操作

eg：
openclaw onboard --auth-choice minimax-portal
openclaw onboard --auth-choice opencode-zen
openclaw onboard --auth-choice openai-api-key

添加认证配置

如果新增的提供商需要认证，在 auth 中添加：

"auth": {
  "profiles": {
    "新提供商:default": {
      "provider": "新提供商",
      "mode": "api_key"
    }
  },
  "order": {
    "新提供商": ["新提供商:default"]
  }
}

配置文件路径

  • 主配置: C:\Users\{用户名}\.openclaw\openclaw.json
  • 工作目录: C:\Users\{用户名}\.openclaw\workspace

相关命令

# 获取当前配置
openclaw config.get

# 应用配置 (修改后)
openclaw config.apply

# 查看配置 schema
openclaw config.schema

#启动openclaw
openclaw gateway

# 重启
openclaw gateway restart

# 状态
openclaw status  （-all）

#修复
openclaw doctor --fix

# 切换模型
/model <模型名称>

# 查看模型
/model
/models
/model list

# 压缩上下文
/compact

一般情况下无需重启配置文件生效

[注意]

openclaw默认配置gateway.reload.mode="hybrid",所以一般直接修改配置文件保存即可，不需要重启

热加载配置在 gateway.reload 下：

"gateway": {
  "reload": {
    "mode": "hybrid",  // off | restart | hot | hybrid (推荐)
    "debounceMs": 500  // 防抖时间
  }
}

mode 选项：

  • off - 关闭
  • restart - 完全重启
  • hot - 热加载（部分配置）
  • hybrid - 混合模式（推荐）
3 个赞
#3

顶一下

3 个赞
#4

666

2 个赞
#5
#6

顶~~龙虾养起来

1 个赞
#7