题头图

第004期_类OpenClaw应用模型配置完全指南-从入门到精通

在国产的各类“龙虾”应用（如OpenClaw、LobsterAI、AutoClaw、ArkClaw、Linclaw等）中配置新模型，核心都是修改配置文件。这些应用普遍遵循 OpenAI API 格式 标准，因此配置逻辑高度统一。本文整合了多份权威资料，为你提供一份从零基础到高级自定义的完整操作手册，涵盖 DeepSeek、智谱AI（GLM）、硅基流动、OpenRouter 四大主流平台的详细配置实例，并汇总了所有关键的避坑细节，确保你一次配置成功。

一、预备知识：配置文件在哪里？

所有龙虾类应用的模型配置都集中在 openclaw.json 文件中。在进行任何操作前，请先找到它。

操作系统 配置文件路径（默认）
Windows C:\Users\<你的用户名>\.openclaw\openclaw.json
macOS / Linux ~/.openclaw/openclaw.json
Docker / 云服务器 进入容器后，执行 cat ~/.openclaw/openclaw.json 查看具体位置

💡 提示：如果文件不存在，请先运行一次 openclaw onboard 命令完成初始化配置，文件会自动生成。

二、两种配置方法：新手与高手的路径

方法一：交互式配置向导（新手首选，零代码）

这是最简单、最安全的方法，通过命令行问答式引导快速完成配置。

  1. 打开终端（Windows用PowerShell，macOS/Linux用Terminal）。

  2. 执行核心命令：openclaw onboard。

  3. 按照终端提示逐步操作：

    • 选择配置模式：推荐 QuickStart（快速开始）。

    • 选择模型提供商：向导会列出主流服务商（如智谱AI、硅基流动），直接选择即可。

    • 输入API Key：粘贴你从对应平台官网获取的密钥。

    • 选择具体模型：如 glm-4-flash、deepseek-chat 等。

    • 完成后续配置：按提示设置通讯渠道等，配置结束后应用会自动重启。

  4. 如果向导中没有你想要的模型（如OpenRouter），可以选择 Skip for now 跳过，然后使用方法二手动添加。

方法二：手动编辑配置文件（高级用户，全模型支持）

通过直接修改 openclaw.json，你可以实现精细的模型管理，如同时添加多个模型、设置备用模型自动切换等。

1. 配置前的安全准备

  • 备份原文件：将 openclaw.json 复制一份，例如命名为 openclaw.json.bak。这是防止配置错误导致服务无法恢复的最佳习惯。

  • 使用专业编辑器：强烈建议使用 VS Code 或 Notepad++ 等支持JSON语法高亮和校验的编辑器。VS Code会用红色波浪线直观地标出语法错误，避免因一个多余逗号导致整个应用无法启动。

2. 通用配置结构（核心必读）

所有模型配置都添加在 models.providers 对象下。核心结构如下：

json

{ “models”: { “mode”: “merge”, // 保持merge，表示将新模型合并到现有模型列表，不覆盖原有配置 “providers”: { // 在这里添加你的新模型提供商配置（如 deepseek, zhipu 等） “提供商ID”: { “baseUrl”: “模型API接口地址”, // 注意末尾不加 / “apiKey”: “你的API_Key”, // 或使用环境变量 “${YOUR_API_KEY}” “api”: “openai-completions”, // 99%的国产模型为此值 “models”: [ // 该提供商下的模型列表 { “id”: “模型官方唯一ID”, // 必须与官方文档完全一致 “name”: “模型自定义显示名称”, “reasoning”: false, // 推理模型设为true，普通模型为false “input”: [“text”], // 多模态模型可添加 “image” “contextWindow”: 128000, // 模型上下文长度（token数） “maxTokens”: 8192 // 单次回复最大token数 } ] } } }, “agents”: { “defaults”: { “model”: { “primary”: “提供商ID/模型ID”, // 设置默认使用的主模型 “fallbacks”: [] // 可选，主模型不可用时的备用模型列表 } } } }

三、四大主流模型配置实例（直接可用）

请将下面代码块中的 "你的API_Key" 替换为你从各平台获取的真实API Key。你可以将多个实例组合添加至同一配置文件，实现多模型切换。

1️⃣ 配置 DeepSeek 模型（国内直连，推荐首选）

DeepSeek 官方API完全兼容OpenAI格式，配置最为简单，国内可直连。

json

“deepseek”: { “baseUrl”: “https://api.deepseek.com/v1”, “apiKey”: “你的DeepSeek_API_Key”, “api”: “openai-completions”, “models”: [ { “id”: “deepseek-chat”, “name”: “DeepSeek V3”, “reasoning”: false, “input”: [“text”], “contextWindow”: 128000, “maxTokens”: 8192 }, { “id”: “deepseek-reasoner”, “name”: “DeepSeek R1 (推理模式)”, “reasoning”: true, // 关键：推理模型必须设为true “input”: [“text”], “contextWindow”: 128000, “maxTokens”: 32768 } ] }

  • 默认模型："primary": "deepseek/deepseek-chat"

2️⃣ 配置智谱AI (GLM) 模型（国内生态，支持多模态）

智谱AI提供标准的OpenAI兼容接口，生态适配好，支持多模态模型。

json

“zhipu”: { “baseUrl”: “https://open.bigmodel.cn/api/paas/v4”, “apiKey”: “你的智谱_API_Key”, “api”: “openai-completions”, “models”: [ { “id”: “glm-4-flash”, “name”: “GLM-4-Flash (快速版)”, “reasoning”: false, “input”: [“text”], “contextWindow”: 128000, “maxTokens”: 8192 }, { “id”: “glm-4-plus”, “name”: “GLM-4-Plus (标准版)”, “reasoning”: false, “input”: [“text”], “contextWindow”: 128000, “maxTokens”: 8192 }, { “id”: “glm-4v-plus”, “name”: “GLM-4V-Plus (多模态版)”, “reasoning”: false, “input”: [“text”, “image”], // 支持图文输入 “contextWindow”: 128000, “maxTokens”: 8192 } ] }

  • 默认模型："primary": "zhipu/glm-4-flash"

3️⃣ 配置硅基流动 (SiliconFlow) 模型（国内聚合平台，上百款模型）

硅基流动聚合了众多开源模型，配置时模型ID需要按平台规范填写，一次配置多模型可用。

  • API Key申请：硅基流动官网（密钥以 sk- 开头）

  • 关键要求：models.id 必须从平台「模型广场」复制完整格式（作者/模型名），不可手动编写。

json

“siliconflow”: { “baseUrl”: “https://api.siliconflow.cn/v1”, // 必须包含 /v1 “apiKey”: “你的硅基流动_API_Key”, “api”: “openai-completions”, “models”: [ { “id”: “deepseek-ai/DeepSeek-V3.2”, // 格式：作者/模型名 “name”: “SiliconFlow-DeepSeek V3.2”, “reasoning”: false, “input”: [“text”], “contextWindow”: 200000, “maxTokens”: 8192 }, { “id”: “Qwen/Qwen2.5-72B-Instruct”, “name”: “SiliconFlow-Qwen2.5 72B”, “reasoning”: false, “input”: [“text”], “contextWindow”: 128000, “maxTokens”: 4096 }, { “id”: “THUDM/glm-4-9b-chat”, “name”: “SiliconFlow-GLM-4 9B”, “reasoning”: false, “input”: [“text”], “contextWindow”: 32768, “maxTokens”: 4096 } ] }

  • 默认模型："primary": "siliconflow/deepseek-ai/DeepSeek-V3.2"

4️⃣ 配置 OpenRouter 模型（全球聚合网关，支持Claude/GPT）

OpenRouter 是一个全球模型聚合网关，一个API Key可以调用Claude、GPT、Gemini等全球主流模型。

  • API Key申请：OpenRouter官网（密钥以 sk-or- 开头，支持支付宝充值）

  • 网络要求：国内服务器必须配置合规的境外代理，否则会被墙或超时。

json

“openrouter”: { “baseUrl”: “https://openrouter.ai/api/v1”, “apiKey”: “你的OpenRouter_API_Key”, “api”: “openai-completions”, “models”: [ { “id”: “anthropic/claude-sonnet-4-5”, “name”: “Claude Sonnet 4.5”, “reasoning”: false, “input”: [“text”], “contextWindow”: 200000, “maxTokens”: 8192 }, { “id”: “openai/gpt-4o-mini”, “name”: “GPT-4o Mini”, “reasoning”: false, “input”: [“text”], “contextWindow”: 128000, “maxTokens”: 8192 }, { “id”: “google/gemini-2.0-flash-exp”, “name”: “Gemini 2.0 Flash”, “reasoning”: false, “input”: [“text”], “contextWindow”: 128000, “maxTokens”: 4096 } ] }

  • 默认模型："primary": "openrouter/anthropic/claude-sonnet-4-5"

5️⃣ 多模型组合配置（主模型+备用模型，生产环境推荐）

将上述多个模型配置组合添加至同一 openclaw.json，并设置 fallbacks 备用模型列表，主模型不可用时自动切换，大幅提升服务稳定性。

json

{ “models”: { “mode”: “merge”, “providers”: { “deepseek”: { … }, // 直接复制DeepSeek完整配置 “zhipu”: { … }, // 直接复制智谱AI完整配置 “siliconflow”: { … } // 直接复制硅基流动完整配置 } }, “agents”: { “defaults”: { “model”: { “primary”: “deepseek/deepseek-chat”, // 主模型 “fallbacks”: [ // 备用模型列表，按顺序尝试 “zhipu/glm-4-flash”, “siliconflow/deepseek-ai/DeepSeek-V3.2” ] } } } }

四、完整可直接复用的 openclaw.json 模板

整合了DeepSeek、智谱AI、硅基流动、OpenRouter四大模型的全量配置模板。你只需替换其中的API Key即可直接使用。不用的模型可直接删除对应的段落。

json

{ “models”: { “mode”: “merge”, “providers”: { “deepseek”: { “baseUrl”: “https://api.deepseek.com/v1”, “apiKey”: “这里填你的DeepSeek API Key”, “api”: “openai-completions”, “models”: [ { “id”: “deepseek-chat”, “name”: “DeepSeek-V3”, “contextWindow”: 128000, “maxTokens”: 8192 }, { “id”: “deepseek-reasoner”, “name”: “DeepSeek-R1”, “contextWindow”: 128000, “maxTokens”: 8192 } ] }, “zhipu”: { “baseUrl”: “https://open.bigmodel.cn/api/paas/v4”, “apiKey”: “这里填你的智谱API Key”, “api”: “openai-completions”, “models”: [ { “id”: “glm-4-flash”, “name”: “GLM-4-Flash”, “contextWindow”: 128000, “maxTokens”: 8192 }, { “id”: “glm-4-plus”, “name”: “GLM-4-Plus”, “contextWindow”: 128000, “maxTokens”: 8192 } ] }, “siliconflow”: { “baseUrl”: “https://api.siliconflow.cn/v1”, “apiKey”: “这里填你的硅基流动API Key”, “api”: “openai-completions”, “models”: [ { “id”: “deepseek-ai/DeepSeek-V3.2”, “name”: “硅基-DeepSeek-V3.2”, “contextWindow”: 200000, “maxTokens”: 8192 }, { “id”: “THUDM/glm-4-9b-chat”, “name”: “硅基-GLM-4-9B”, “contextWindow”: 32768, “maxTokens”: 4096 } ] }, “openrouter”: { “baseUrl”: “https://openrouter.ai/api/v1”, “apiKey”: “这里填你的OpenRouter API Key”, “api”: “openai-completions”, “models”: [ { “id”: “anthropic/claude-sonnet-4-5”, “name”: “Claude Sonnet 4.5”, “contextWindow”: 200000, “maxTokens”: 8192 }, { “id”: “openai/gpt-4o-mini”, “name”: “GPT-4o Mini”, “contextWindow”: 128000, “maxTokens”: 8192 } ] } } }, “agents”: { “defaults”: { “model”: { “primary”: “deepseek/deepseek-chat”, “fallbacks”: [ “zhipu/glm-4-flash”, “siliconflow/deepseek-ai/DeepSeek-V3.2” ] } } }, “gateway”: { “host”: “127.0.0.1”, “port”: 18789 } }

五、保存与生效：最后的关键一步

  1. 填写Key：将上述模板中所有 “这里填你的... API Key” 替换为你的真实密钥。

  2. 保存文件：Ctrl + S 保存。

  3. 重启服务：这是最关键的一步！必须在终端运行命令重启网关，新配置才会被加载：

    bash

    openclaw gateway restart

  4. 验证配置：

    • 运行 openclaw doctor 进行诊断。

    • 或运行 openclaw models list 查看当前可用的模型列表，确认新增模型状态是否为 connected。

    • 打开浏览器访问 http://127.0.0.1:18789，发送一条测试消息（如“你好，用的什么模型？”），回复中包含模型名称，即配置成功。

六、核心注意事项与避坑指南（必读）

1. 安全与费用（核心重点）

  • 严禁硬编码：切勿将API Key直接写在配置文件中并提交到公开代码仓库。API Key泄露可能导致账户被盗刷，产生高额费用。

  • 推荐使用环境变量：

    1. 在系统或 .env 文件中设置变量，如 export DEEPSEEK_API_KEY="sk-xxx"。

    2. 在配置文件中通过 "apiKey": "${DEEPSEEK_API_KEY}" 引用。

  • 防盗刷：若Key不慎泄露，立即在平台官网作废并重新申请。

2. 参数细节（决定成败）

  • baseUrl格式：

    • 末尾不加 /：例如 https://api.deepseek.com/v1/ 是错的，正确是 https://api.deepseek.com/v1。

    • 版本号：DeepSeek、硅基流动、OpenRouter必须包含 /v1；智谱AI必须包含 /api/paas/v4。

  • reasoning参数：只有明确使用深度推理模型（如 deepseek-reasoner）时才设为 true。普通对话模型（如 glm-4-flash）若设为 true，会导致返回空响应或报错。

  • 模型ID：必须与平台官方文档中的ID完全一致（区分大小写和斜杠）。硅基流动和OpenRouter的ID格式为 提供商/模型名，少写一个字符都会报错。

3. 网络与服务器地域

  • 国内模型（DeepSeek、智谱AI、硅基流动）：国内服务器/本地可直连，无需代理，优先选择国内云服务器部署。

  • 国外模型（OpenRouter、Claude、GPT）：国内服务器会被墙或超时，必须选择中国香港/新加坡/美国等海外服务器，或使用合规的境外代理。

  • 若同时配置国内+国外模型，建议将服务部署在海外服务器（如新加坡），确保所有模型均可正常调用。

4. JSON语法严格要求

  • 逗号问题：providers 下的不同服务商之间必须用逗号 , 隔开。最后一个服务商后面不能有逗号。

  • 引号问题：所有Key和Value必须用双引号 " 包裹，不能用单引号。

  • 工具辅助：强烈建议使用VS Code编辑，它会用红色波浪线直接告诉你哪里写错了。

七、常见报错与排错方案

报错信息 核心原因 解决方案
401 Unauthorized API Key错误、未设置环境变量或密钥过期。 1. 核对API Key是否复制完整。2. 如果使用环境变量，确认变量名和引用格式 "${VAR_NAME}" 是否正确。3. 重新申请新的API Key。
404 Not Found baseUrl 地址错误，或模型ID不存在于该端点。 1. 检查baseUrl是否按示例填写（如是否包含/v1）。2. 确认模型ID是否从官方文档准确复制。
Model not found 默认模型名称拼写错误，或未在providers中定义。 检查 agents.defaults.model.primary 中的 “提供商ID/模型ID” 是否与 providers 下的配置对象名称和模型ID完全匹配。
Connection Timeout / 超时 网络不通。 1. 如果是调用国外服务（如OpenRouter），国内服务器需配置合规代理或使用海外服务器。2. 优先使用国内服务商（DeepSeek、智谱、硅基流动）以保障连接稳定性。
应用无法启动 JSON语法错误（多余逗号、引号、括号错误）。 1. 用VS Code打开文件，修复所有红色波浪线标注的错误。2. 对比本文的通用配置结构，逐项检查语法问题。
模型返回空响应 reasoning 参数错误地设为 true。 将 reasoning 改为 false，保存后重启服务。

八、参数速查表（快速参考）

参数 核心说明 通用示例值 特殊要求
baseUrl 模型API接口地址 https://api.deepseek.com/v1 末尾不加/，硅基/OpenRouter带/v1
apiKey 平台申请的访问密钥 sk-xxx 或 ${DEEPSEEK_API_KEY} 支持环境变量引用，不同平台格式不同
api API协议类型 openai-completions 国产模型默认值，原生Claude用anthropic-messages
id 模型官方唯一标识符 deepseek-chat / glm-4-flash 硅基/OpenRouter为「提供商/模型名」格式
reasoning 是否为推理模型 false / true 普通模型必设false，推理模型设true
input 模型输入类型 [“text”] / [“text”,“image”] 多模态模型需添加“image”
contextWindow 模型上下文长度（token） 128000 / 200000 按平台官方参数填写
maxTokens 单次回复最大token数 4096 / 8192 按平台官方参数填写
primary 默认主模型 deepseek/deepseek-chat 格式为「提供商ID/模型ID」
fallbacks 备用模型列表 [“zhipu/glm-4-flash”, …] 多个模型用逗号分隔，格式同primary

按照以上步骤和实例配置，你就可以在自己的“龙虾应用”中自由配置和使用各类AI模型了。如果遇到问题，请先使用 openclaw doctor 命令进行诊断，它通常会给出明确的错误提示。

相关文章