OpenClaw 接入自定义模型及 WebUI 智能操作指南

几个关键点要注意：

• primary: 位于 agents.defaults.model，这是必填项。格式必须是 提供商/模型 ID，且必须与下方 providers 中定义的键名和模型 ID 严格对应，否则 Agent 找不到模型。
• mode: 控制合并策略。merge 表示将新配置合并到现有配置，replace 则是完全覆盖，通常建议用 merge 避免误删其他设置。
• providers: 这里是字典结构，每个键代表一个服务商。内部包含 baseUrl（API 地址）、apiKey（支持环境变量引用如 ${ENV_NAME}）、api（接口类型，通常是 openai-completions）以及 models 列表。

实战：接入 LongCat 模型

LongCat 是美团开发的大语言模型，提供了高性能的通用对话和深度思考能力。目前平台支持 Flash-Chat、Flash-Thinking 等多个版本，均兼容 OpenAI 格式。

获取访问凭证

1. 前往 LongCat 开放平台注册账号，新用户通常有免费 Token 额度。
2. 在控制台创建并复制你的 API Key。
3. 留意用量页面，方便后续监控 Token 消耗。

完整配置示例

下面这份配置展示了如何将 LongCat 接入 OpenClaw。注意替换其中的 YOUR_API_KEY_HERE 为你实际申请的密钥：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "longCat/LongCat-Flash-Chat"
      },
      "workspace": "/Users/user/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "longCat": {
        "baseUrl": "https://api.longcat.chat/openai",
        "apiKey": "YOUR_API_KEY_HERE",
        "api": "openai-completions",
        "authHeader": true,
        "models": [
          {
            "id": "LongCat-Flash-Chat",
            "name": "LongCat-Flash-Chat",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8192,
            "compat": {
              "maxTokensField": "max_tokens"
            }
          }
        ]
      }
    }
  }
}

配置细节说明：

• contextWindow: 200000 表示支持 20 万 Token 的上下文窗口，适合处理长文档。
• maxTokens: 8192 限制单次响应长度。
• 修改保存后配置立即生效，不需要重启 Gateway 服务，这点非常省心。

可视化配置方式

如果不喜欢直接改 JSON，Web 界面也能搞定：

1. 启动服务后访问 http://127.0.0.1:18789。
2. 进入 Config → Models → Providers。
3. 按以下表格填入信息：

运行效果验证

配置完成后，Agent 应该能正确识别并使用我们指定的模型。以下是几个关键场景的截图示意：

询问模型能力及当前使用的模型时，应返回 LongCat 相关信息：

在实际操作中，Agent 还能完成本地桌面文件查找等复杂任务：

关键提示

• 配置文件位置：通常在 ~/.openclaw/openclaw.json，请确保路径正确。
• WebUI 地址：默认监听 http://127.0.0.1:18789。
• 调试通信：OpenClaw 基于 WebSocket 全双工通信，如需抓包调试可连接 ws://127.0.0.1:18789/。
• 热更新：修改 openclaw.json 保存即生效，无需重启进程。

参考资料

• OpenClaw 模型提供商快速入门
• OpenClaw 模型提供商配置文档
• LongCat 开放平台
• LongCat OpenClaw 配置指南