OpenClaw 接入自定义大模型

以 AI Click 中转接口为案例，覆盖 OpenAI Chat Completions 与 Anthropic Messages 两种协议，完成接口测试、OpenClaw 配置、模型切换、回退模型和常见错误排查。

以 AI Click 中转接口为案例，覆盖 OpenAI Chat Completions 与 Anthropic Messages 两种协议，完成接口测试、OpenClaw 配置、模型切换、回退模型和常见错误排查。

接入参数示例

Base URL https://ai.aiclick.cc/v1

OpenAI Chat Completions / gpt-5.5 / gpt-5.4

Anthropic claude-sonnet-4-6 / claude-opus-4-8

Default openai/你的模型ID

开始前准备

你只需要确认三样东西：接口地址、API Key、模型 ID。只要接口兼容 OpenAI 格式，OpenClaw 接入会很直接。

1

Base URL

通常以 /v1 结尾。

示例 https://ai.aiclick.cc/v1

2

API Key

从中转站后台生成。

格式 sk-xxxx 或平台生成的专属 Key

3

Model ID

必须填写接口真实支持的模型名。

示例 gpt-5.5 / gpt-5.4

先测试模型接口

不要一上来就改 OpenClaw 配置，先用 curl 确认接口可用。

A

测试模型列表

如果服务支持 /v1/models，先用这个确认 Key 和地址。

curl https://ai.aiclick.cc/v1/models \
  -H "Authorization: Bearer 你的_API_KEY"

测试对话接口

如果模型列表不可用，直接测 Chat Completions。

curl https://ai.aiclick.cc/v1/chat/completions \
  -H "Authorization: Bearer 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "你好，简单介绍一下你自己"}
    ]
  }'

推荐方案：复用 OpenAI Provider

如果你的接口是 OpenAI 兼容中转，这是最稳、最少配置的方案。

✓

适合场景

中转 API / One API / New API / LiteLLM / OpenRouter 类网关。

请求格式兼容 /v1/chat/completions
模型 ID 由网关后台提供
希望快速设成 OpenClaw 默认模型

备份配置文件

修改前先备份，避免误改后难恢复。

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%F-%H%M%S)

写入推荐配置

把 Key、Base URL 和模型 ID 换成你自己的。

{
  "env": {
    "OPENAI_API_KEY": "你的中转_API_KEY",
    "OPENAI_BASE_URL": "https://ai.aiclick.cc/v1"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-5.5",
        "fallbacks": []
      }
    }
  }
}

示例：如果模型 ID 是 deepseek-chat，默认模型就写 openai/gpt-5.5。

进阶方案：新增自定义 Provider

如果你不想占用 OpenAI Provider，可以单独创建 my-custom 这类 provider。

P

完整配置模板

primary 的格式是 provider名称/模型别名，不是直接写接口模型 ID。

{
  "env": {
    "CUSTOM_MODEL_API_KEY": "你的_API_KEY"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "my-custom": {
        "api": "openai-chat",
        "baseURL": "https://ai.aiclick.cc/v1",
        "apiKey": "${CUSTOM_MODEL_API_KEY}",
        "models": {
          "my-model": {
            "id": "你的模型ID",
            "name": "我的自定义模型"
          }
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "my-custom/my-model",
        "fallbacks": []
      }
    }
  }
}

Anthropic 协议配置

如果客户端或 OpenClaw Provider 走 Anthropic Messages 协议，网关地址使用 https://ai.aiclick.cc，模型从下方列表选择。

A

Anthropic 接口测试

先用 Messages 接口确认 Key、地址和模型名都可用。

curl https://ai.aiclick.cc/v1/messages \
  -H "x-api-key: 你的_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 512,
    "messages": [
      {"role": "user", "content": "你好，测试一下 Anthropic 协议是否可用"}
    ]
  }'

支持的 Claude 模型

优先选 Sonnet 做日常，Opus/Thinking 用于复杂任务。

Haiku claude-haiku-4-5

Opus claude-opus-4-5 / claude-opus-4-6 / claude-opus-4-7 / claude-opus-4-8

Thinking claude-opus-4-6-thinking

Sonnet claude-sonnet-4-5 / claude-sonnet-4-6

P

OpenClaw Anthropic Provider 模板

如果当前 OpenClaw 版本支持自定义 Anthropic-compatible provider，可参考这个结构；若不支持，优先使用内置 Anthropic 认证或客户端侧 Anthropic 网关配置。

{
  "env": {
    "ANTHROPIC_API_KEY": "你的_API_KEY",
    "ANTHROPIC_BASE_URL": "https://ai.aiclick.cc"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6",
        "fallbacks": [
          "anthropic/claude-haiku-4-5"
        ]
      }
    }
  }
}

如果你的 OpenClaw 版本不读取 ANTHROPIC_BASE_URL，就改用 models.providers 的自定义 provider 方式，或者在客户端侧直接配置 Anthropic Gateway URL。

配置备用模型

主模型限流或不可用时，fallback 可以自动兜底。

JSON

配置文件方式

适合一次性写入固定备用链。

"model": {
  "primary": "openai/gpt-5.5",
  "fallbacks": [
    "openai/gpt-5.4"
  ]
}

CLI

命令行方式

适合快速追加或清空。

openclaw models fallbacks add openai/gpt-5.4
openclaw models fallbacks list
openclaw models fallbacks clear

验证是否接入成功

配置完成后，按顺序执行检查命令。--probe 会真实请求模型接口，可能消耗 token。

OK

最终检查命令

四个命令都正常，说明 OpenClaw 已经接入你的自定义模型。

openclaw doctor
openclaw models status
openclaw models status --probe
openclaw infer model "测试一下：你现在使用的是哪个模型？"

常见问题排查

失败时不要乱改，按状态码和字段逐项定位。

401

Unauthorized

通常是 API Key 错误。

确认 Key 没复制多余空格
确认后台 Key 没过期或被禁用
先用 curl 测通，再回 OpenClaw

404

接口或模型不存在

通常是 Base URL 或模型 ID 写错。

baseURL 建议以 /v1 结尾
模型 ID 必须用接口真实返回的名称
不要把展示名当成模型 ID

LAN

本地/私网模型

访问 127.0.0.1 或内网地址时，可能需要打开私网访问。

"request": {
  "allowPrivateNetwork": true
}

只建议对你完全控制的本地或私网模型服务开启。

一句话总结

OpenAI 兼容接口接入 OpenClaw，本质只需要三步。

1设置 OPENAI_BASE_URL 为你的接口地址。
2设置 OPENAI_API_KEY 为你的 Key。
3设置 agents.defaults.model.primary 为 openai/你的模型ID。

OpenClaw 接入 自定义大模型