OpenClaw 中文版

主题

自定义 AI 供应商配置 ​

Openclaw 支持多种 AI 供应商，包括内置供应商和自定义供应商。本文档介绍如何配置自定义 AI 供应商和模型。

快速开始 ​

配置方式 ​

配置文件位于 ~/.openclaw/openclaw.json。

最简配置示例（以硅基流动为例）：

json5
{
  // 环境变量配置 API Key
  env: {
    SILICONFLOW_API_KEY: "sk-xxx..."
  },
  // 设置默认模型
  agents: {
    defaults: {
      model: { primary: "siliconflow/Qwen/Qwen2.5-72B-Instruct" }
    }
  },
  // 配置自定义供应商
  models: {
    providers: {
      siliconflow: {
        baseUrl: "https://api.siliconflow.cn/v1",
        apiKey: "${SILICONFLOW_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "Qwen/Qwen2.5-72B-Instruct", name: "通义千问 2.5 72B" }
        ]
      }
    }
  }
}

API 协议支持 ​

Openclaw 支持两种主流 API 协议：

协议api 值兼容服务
OpenAIopenai-completions硅基流动、DeepSeek、Moonshot、Ollama、vLLM、LM Studio 等
Anthropicanthropic-messagesAnthropic、AWS Bedrock Claude 等

大多数国内服务都兼容 OpenAI 协议，使用 api: "openai-completions" 即可。

国内 AI 服务配置示例 ​

硅基流动 (SiliconFlow) ​

硅基流动提供多种开源模型的 API 服务。

json5
{
  env: { SILICONFLOW_API_KEY: "sk-xxx..." },
  agents: {
    defaults: { model: { primary: "siliconflow/Qwen/Qwen2.5-72B-Instruct" } }
  },
  models: {
    providers: {
      siliconflow: {
        baseUrl: "https://api.siliconflow.cn/v1",
        apiKey: "${SILICONFLOW_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "Qwen/Qwen2.5-72B-Instruct", name: "通义千问 2.5 72B" },
          { id: "deepseek-ai/DeepSeek-V3", name: "DeepSeek V3" },
          { id: "deepseek-ai/DeepSeek-R1", name: "DeepSeek R1", reasoning: true }
        ]
      }
    }
  }
}

DeepSeek ​

DeepSeek 官方 API：

json5
{
  env: { DEEPSEEK_API_KEY: "sk-xxx..." },
  agents: {
    defaults: { model: { primary: "deepseek/deepseek-chat" } }
  },
  models: {
    providers: {
      deepseek: {
        baseUrl: "https://api.deepseek.com/v1",
        apiKey: "${DEEPSEEK_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "deepseek-chat", name: "DeepSeek Chat" },
          { id: "deepseek-reasoner", name: "DeepSeek R1", reasoning: true }
        ]
      }
    }
  }
}

月之暗面 (Moonshot / Kimi) ​

json5
{
  env: { MOONSHOT_API_KEY: "sk-xxx..." },
  agents: {
    defaults: { model: { primary: "moonshot/moonshot-v1-128k" } }
  },
  models: {
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.cn/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "moonshot-v1-8k", name: "Moonshot 8K" },
          { id: "moonshot-v1-32k", name: "Moonshot 32K" },
          { id: "moonshot-v1-128k", name: "Moonshot 128K" }
        ]
      }
    }
  }
}

智谱 AI (GLM) ​

json5
{
  env: { ZHIPU_API_KEY: "xxx..." },
  agents: {
    defaults: { model: { primary: "zhipu/glm-4-plus" } }
  },
  models: {
    providers: {
      zhipu: {
        baseUrl: "https://open.bigmodel.cn/api/paas/v4",
        apiKey: "${ZHIPU_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "glm-4-plus", name: "GLM-4 Plus" },
          { id: "glm-4-flash", name: "GLM-4 Flash" }
        ]
      }
    }
  }
}

通义千问 (阿里云) ​

json5
{
  env: { DASHSCOPE_API_KEY: "sk-xxx..." },
  agents: {
    defaults: { model: { primary: "dashscope/qwen-max" } }
  },
  models: {
    providers: {
      dashscope: {
        baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
        apiKey: "${DASHSCOPE_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "qwen-max", name: "通义千问 Max" },
          { id: "qwen-plus", name: "通义千问 Plus" },
          { id: "qwen-turbo", name: "通义千问 Turbo" }
        ]
      }
    }
  }
}

百川 AI ​

json5
{
  env: { BAICHUAN_API_KEY: "sk-xxx..." },
  agents: {
    defaults: { model: { primary: "baichuan/Baichuan4" } }
  },
  models: {
    providers: {
      baichuan: {
        baseUrl: "https://api.baichuan-ai.com/v1",
        apiKey: "${BAICHUAN_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "Baichuan4", name: "百川 4" },
          { id: "Baichuan3-Turbo", name: "百川 3 Turbo" }
        ]
      }
    }
  }
}

火山引擎 (Volcengine / 豆包) ​

火山引擎提供字节跳动的 AI 模型服务（豆包等）。

json5
{
  env: { VOLCENGINE_API_KEY: "your-api-key..." },
  agents: {
    defaults: { model: { primary: "volcengine/doubao-1-5-pro-32k-250115" } }
  },
  models: {
    providers: {
      volcengine: {
        baseUrl: "https://ark.cn-beijing.volces.com/api/v3",
        apiKey: "${VOLCENGINE_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "doubao-1-5-pro-32k-250115", name: "豆包 1.5 Pro 32K" },
          { id: "doubao-1-5-lite-32k-250115", name: "豆包 1.5 Lite 32K" }
        ]
      }
    }
  }
}

企业用户自定义 Header：如果需要为请求添加自定义 Header（如标识调用来源），可通过环境变量配置：

bash
export MODEL_AGENT_CLIENT_REQ_ID="X-Custom-Header-Name"
export MODEL_AGENT_CLIENT_REQ_VALUE="your-custom-value"

本地模型配置 ​

Ollama ​

Ollama 是最简单的本地模型运行方式。Openclaw 可以自动发现 Ollama 中的模型。

安装和使用：

bash
# 1. 安装 Ollama
# macOS: brew install ollama
# Linux: curl -fsSL https://ollama.com/install.sh | sh

# 2. 拉取模型
ollama pull llama3.3
ollama pull qwen2.5:32b

# 3. 启动 Ollama 服务
ollama serve

配置 Openclaw：

json5
{
  // 设置任意值启用 Ollama（Ollama 本身不需要真正的 key）
  env: { OLLAMA_API_KEY: "ollama-local" },
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } }
  }
}

Openclaw 会自动发现本地 Ollama 中支持工具调用的模型。

手动配置（可选）：

如果 Ollama 运行在非默认端口或其他主机：

json5
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://192.168.1.100:11434/v1",
        apiKey: "ollama-local",
        api: "openai-completions",
        models: [
          { id: "llama3.3", name: "Llama 3.3" }
        ]
      }
    }
  }
}

LM Studio ​

LM Studio 提供 OpenAI 兼容的本地 API：

json5
{
  agents: {
    defaults: { model: { primary: "lmstudio/local-model" } }
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "lm-studio",
        api: "openai-completions",
        models: [
          { id: "local-model", name: "本地模型" }
        ]
      }
    }
  }
}

vLLM ​

vLLM 是高性能的本地推理服务器：

json5
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://localhost:8000/v1",
        apiKey: "vllm-local",
        api: "openai-completions",
        models: [
          { id: "Qwen/Qwen2.5-72B-Instruct", name: "Qwen 2.5 72B" }
        ]
      }
    }
  }
}

模型配置详解 ​

完整模型配置 ​

json5
{
  models: {
    providers: {
      "my-provider": {
        baseUrl: "https://api.example.com/v1",
        apiKey: "${MY_API_KEY}",
        api: "openai-completions",  // 或 "anthropic-messages"
        models: [
          {
            id: "model-id",           // 模型 ID（必填）
            name: "显示名称",          // 显示名称（可选）
            reasoning: false,          // 是否支持推理模式（可选）
            input: ["text"],           // 输入类型（可选）
            contextWindow: 128000,     // 上下文窗口大小（可选）
            maxTokens: 8192,           // 最大输出 token（可选）
            cost: {                    // 成本配置（可选）
              input: 0,
              output: 0,
              cacheRead: 0,
              cacheWrite: 0
            }
          }
        ]
      }
    }
  }
}

配置字段说明 ​

字段必填说明默认值
baseUrl✅API 端点地址-
apiKey✅API 密钥，支持 ${ENV_VAR} 引用-
api✅API 协议类型-
models✅模型列表-
models[].id✅模型 ID（不含 provider 前缀）-
models[].name❌显示名称使用 id
models[].reasoning❌推理模式支持false
models[].contextWindow❌上下文窗口200000
models[].maxTokens❌最大输出8192

⚠️ 重要：models[].id 字段只填写模型名称，不要包含 provider 前缀。

例如，配置硅基流动的 MiniMax 模型：

  • ✅ 正确："id": "Pro/MiniMaxAI/MiniMax-M2.1"
  • ❌ 错误："id": "siliconflow/Pro/MiniMaxAI/MiniMax-M2.1"

系统会自动将 provider 名称和 model id 组合成完整引用（如 siliconflow/Pro/MiniMaxAI/MiniMax-M2.1），用于 agents.defaults.model.primary 等配置项。

CLI 命令 ​

查看模型 ​

bash
# 查看已配置的模型
openclaw models list

# 查看所有可用模型
openclaw models list --all

# 查看模型状态
openclaw models status

设置默认模型 ​

bash
# 设置主模型
openclaw models set <provider/model>

# 设置图像模型
openclaw models set-image <provider/model>

管理回退模型 ​

bash
# 添加回退模型
openclaw models fallbacks add <provider/model>

# 查看回退列表
openclaw models fallbacks list

# 清空回退
openclaw models fallbacks clear

配置命令 ​

bash
# 直接设置供应商配置
openclaw config set models.providers.siliconflow.baseUrl "https://api.siliconflow.cn/v1"
openclaw config set models.providers.siliconflow.apiKey "sk-xxx"

在聊天中切换模型 ​

在 Telegram/WhatsApp 等渠道中，可以使用命令切换模型：

/model              # 查看当前模型
/model list         # 列出可用模型
/model 1            # 选择第 1 个模型
/model deepseek/deepseek-chat  # 切换到指定模型
/model status       # 查看详细状态

故障排除 ​

API 连接失败 ​

  1. 检查 baseUrl 是否正确（注意是否需要 /v1 后缀）
  2. 检查 API Key 是否有效
  3. 检查网络是否可访问 API 端点
bash
# 测试 API 连接
curl -H "Authorization: Bearer $API_KEY" https://api.example.com/v1/models

模型不在列表中 ​

确保在 models 数组中正确配置了模型：

json5
models: [
  { id: "正确的模型ID", name: "显示名称" }  // id 不要包含 provider 前缀
]

模型调用报错 ​

  1. 检查模型 ID 是否正确
  2. 确认 API 协议类型（openai-completions 或 anthropic-messages）
  3. 查看日志：openclaw logs --follow

相关文档 ​

基于 MIT 许可发布

Copyright © 2026-present OpenClaw-CN

💬加入微信