OpenClaw 自定义模型配置权威教程-洪萨配资

OpenClaw 自定义模型配置权威教程

本教程整合 OpenClaw 自定义模型配置的核心流程、关键步骤及避坑要点，适配 2026 年最新版本 OpenClaw，兼顾新手入门与进阶需求，全程以实战为导向，确保配置后可正常调用自定义模型。

一、前置准备（必做）

1.1 环境依赖安装

OpenClaw 运行依赖 Node.js 环境，建议安装 v18 及以上版本，确保后续安装和配置无兼容性问题，不同系统安装方式如下：

Windows 系统：以管理员身份打开 PowerShell，可通过 Chocolatey 安装（推荐），执行命令choco install nodejs \-\-version=\&\#34;22.22.1\&\#34;，或直接前往 Node.js 官网下载安装包手动安装。
macOS 系统：打开 Terminal，通过 Homebrew 安装brew install nodejs，或官网下载安装。
Linux 系统（Ubuntu/Debian）：执行命令curl \-fsSL https://deb.nodesource.com/setup\_18.x \| sudo \-E bash \- \&\& sudo apt\-get install \-y nodejs。

安装完成后，执行node \-v验证版本，显示 v18 及以上即为合格。若 npm 下载速度较慢，可配置国内镜像：npm config set registry https://registry.npmmirror.com。

1.2 OpenClaw 安装与初始化

采用全局安装方式，操作简单且后续可在任意目录调用，步骤如下：

打开终端（Windows 用 PowerShell/CMD，macOS/Linux 用 Terminal），执行安装命令：npm install \-g openclaw@latest，安装最新版本。
安装完成后，执行初始化命令：openclaw onboard，按照终端交互式提示逐步完成基础设置，该步骤会自动在用户目录下创建.openclaw文件夹（核心配置目录）。

初始化注意：新手可选择 QuickStart 模式，跳过复杂的渠道配置，后续可按需补充；若出现中文用户名导致启动失败，可手动创建不含中文的配置目录（如 Windows 系统C:\\OpenClaw\\Config），并通过环境变量指定配置路径。

1.3 核心配置文件说明

初始化完成后，.openclaw目录下会生成核心配置文件openclaw.json，所有自定义模型的配置均围绕该文件展开，其核心目录结构如下：

~/.openclaw/ ├── openclaw.json# 核心主配置文件（重中之重）├── openclaw.json.bak# 配置文件备份（修改前建议备份）├── credentials/# 敏感信息存储（密钥、凭证）├── workspace/# Agent工作区（临时文件）└── logs/# 运行日志目录

二、自定义模型核心配置（关键步骤）

2.1 配置文件结构解析

openclaw.json分为三大核心模块，直接决定模型能否正常调用：

配置模块	核心作用
`agents.defaults`	定义默认模型、并发数、工作区等基础运行参数
`auth.profiles`	声明各模型服务商的鉴权类型（不存储明文密钥）
`models.providers`	配置服务商接口地址、模型列表、参数规范

2.2 自定义模型配置实战（以诗云 API 为例）

2.2.1 配置文件路径

Windows：C:\\Users\<你的用户名\>.openclaw\\openclaw.json
macOS/Linux：\~/.openclaw/openclaw.json

2.2.2 完整配置示例（直接复用）

{"agents":{"defaults":{"model":{"primary":"shiyunapi/gpt-4o","fallbacks":["shiyunapi/claude-3-5-sonnet","shiyunapi/deepseek-chat"]},"maxConcurrent":4,"workspace":"~/.openclaw/workspace","compaction":{"mode":"safeguard"}}},"auth":{"profiles":{"shiyunapi":{"type":"api-key"}}},"models":{"mode":"merge","providers":{"shiyunapi":{"baseUrl":"https://shiyunapi.com/v1","apiKey":"$SHIYUN_API_KEY","api":"openai-completions","models":[{"id":"gpt-4o","name":"GPT-4o","contextWindow":128000,"maxTokens":8192,"temperature":0.7,"input":["text","image"]},{"id":"claude-3-5-sonnet","name":"Claude 3.5 Sonnet","contextWindow":200000,"maxTokens":8192,"temperature":0.3},{"id":"deepseek-chat","name":"DeepSeek Chat","contextWindow":32768,"maxTokens":8192,"temperature":0.5}]}}}}

2.2.3 关键参数说明

baseUrl：诗云 API 官方接口地址https://shiyunapi.com/v1
apiKey：推荐使用环境变量$SHIYUN\_API\_KEY，避免明文泄露
api：固定为openai\-completions（兼容 OpenAI 协议）
primary：设置默认调用模型，格式为服务商ID/模型ID
fallbacks：备用模型列表，主模型故障时自动切换

2.3 密钥配置（安全方式）

Windows 系统：

[Environment]::SetEnvironmentVariable("SHIYUN_API_KEY","你的诗云API密钥","User")

macOS/Linux 系统：

echo'export SHIYUN_API_KEY="你的诗云API密钥"'>>~/.bashrcsource~/.bashrc

三、配置验证与启动

3.1 配置文件校验

修改完成后，执行校验命令，排查 JSON 语法错误：

openclaw config validate--json

显示Validation passed即为配置合法。

3.2 模型状态检查

openclaw models status--probe

成功状态会显示：

Provider: shiyunapi Status: authenticated Models: gpt-4o, claude-3-5-sonnet, deepseek-chat

3.3 启动 OpenClaw

openclaw start

启动成功后，访问http://localhost:8080即可使用配置的自定义模型。

四、常见问题与避坑指南

配置文件报错：检查 JSON 逗号、引号、括号是否完整，建议用 VSCode 编辑并开启 JSON 校验。
模型调用失败：
- 确认baseUrl正确（诗云 API 为https://shiyunapi.com/v1）
- 检查 API 密钥是否正确配置，环境变量是否生效
- 执行openclaw logs查看详细错误日志
模型不显示：
- 确认models.providers配置正确
- 重启 OpenClaw 服务：openclaw restart
- 清除缓存：openclaw cache clear

五、进阶配置（可选）

5.1 多服务商共存

可在models.providers中添加多个服务商配置，实现多模型自由切换：

"providers":{"shiyunapi":{/* 诗云API配置 */},"ollama":{/* 本地模型配置 */},"deepseek":{/* 其他服务商配置 */}}

5.2 模型参数调优

根据场景调整temperature（0-1，值越低越稳定）、contextWindow（上下文窗口）等参数：

{"id":"custom-model","name":"自定义模型","contextWindow":65536,"maxTokens":4096,"temperature":0.2,"topP":0.95}

5.3 默认模型切换

openclaw models set-default shiyunapi/claude-3-5-sonnet

本教程覆盖 OpenClaw 自定义模型配置全流程，核心配置以诗云 API 为标准示例，适配所有兼容 OpenAI 协议的模型服务。配置完成后可实现多模型统一管理、自动故障切换，大幅提升 AI 使用效率。

OpenClaw 自定义模型配置权威教程