API 文档 - OpenClaw API

简介

OpenClaw API 同时兼容 OpenAI Chat Completions / Responses、Anthropic Messages 和 Gemini 三种 API 格式，支持多种主流大语言模型。原生支持 Claude Code CLI、Codex CLI、Gemini CLI 以及 OpenAI / Anthropic SDK 直接接入。

API 地址

https://api.yunjunet.cn

兼容格式

OpenAI + Anthropic + Gemini

响应格式

JSON / SSE

认证方式

在控制台创建 API Key 后，支持三种认证头格式（使用同一个 Key）：

# OpenAI 格式（适用于 /v1/chat/completions）
Authorization: Bearer sk-your-api-key

# Anthropic 格式（适用于 /v1/messages）
x-api-key: sk-your-api-key

# Gemini 格式（适用于 /v1beta/models/*）
x-goog-api-key: sk-your-api-key

API Key 以 sk- 开头，创建后仅显示一次，请妥善保管。三种认证头均可用于对应端点。

快速接入

Python

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="https://api.yunjunet.cn",
    api_key="sk-your-api-key"
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}]
)
print(resp.choices[0].message.content)

JavaScript / Node.js

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.yunjunet.cn',
  apiKey: 'sk-your-api-key',
});

const completion = await client.chat.completions.create({
  model: 'deepseek-chat',
  messages: [{ role: 'user', content: '你好' }],
});
console.log(completion.choices[0].message.content);

cURL

curl https://api.yunjunet.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Chat Completions

POST/v1/chat/completions

请求参数

参数	类型	必填	说明
`model`	string	是	模型 ID，如 gpt-4o-mini、deepseek-chat
`messages`	array	是	消息数组，每项包含 role 和 content
`stream`	boolean	否	是否流式输出，默认 false
`temperature`	number	否	温度参数 0-2，默认 1
`max_tokens`	integer	否	最大输出 token 数
`top_p`	number	否	核采样参数

响应示例

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "你好！" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 5,
    "total_tokens": 15
  }
}

Messages API（Anthropic 兼容）

POST/v1/messages

完全兼容 Anthropic Messages API 格式，支持 Claude Code CLI、Anthropic SDK 等原生客户端直接接入。所有模型（包括 OpenAI、DeepSeek、NVIDIA 等非 Anthropic 模型）均可通过此端点调用，平台自动完成格式转换。

请求参数

参数	类型	必填	说明
`model`	string	是	模型 ID，如 claude-haiku-4-5、deepseek-chat
`messages`	array	是	消息数组，Anthropic 格式（content blocks）
`max_tokens`	integer	是	最大输出 token 数
`system`	string\|array	否	系统提示词
`stream`	boolean	否	是否流式输出，默认 false
`temperature`	number	否	温度参数 0-1
`tools`	array	否	工具定义（Anthropic tool 格式）

请求示例

curl https://api.yunjunet.cn/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-haiku-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

响应示例

{
  "id": "msg_01XFDUDYJgAACzvnp...",
  "type": "message",
  "role": "assistant",
  "model": "claude-haiku-4-5",
  "content": [
    { "type": "text", "text": "Hello! How can I help you today?" }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 12
  }
}

流式响应格式

设置 stream: true 后，返回 Anthropic 标准 SSE 事件流：

event: message_start
data: {"type":"message_start","message":{"id":"msg_...","type":"message","role":"assistant","model":"claude-haiku-4-5","content":[],"usage":{"input_tokens":10,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}

event: message_stop
data: {"type":"message_stop"}

格式自动转换

通过 /v1/messages 端点调用非 Anthropic 模型（如 DeepSeek、GPT、NVIDIA）时，平台自动完成双向格式转换：

请求：Anthropic Messages 格式 → OpenAI Chat Completions 格式（含 tool_use 转换）
响应：OpenAI 格式 → Anthropic Messages 格式（含 SSE 事件流转换）
对客户端完全透明，无需关心上游差异

Responses API（OpenAI 兼容）

POST/v1/responses

兼容 OpenAI Responses API 格式，支持 Codex CLI 直接接入。平台上所有模型均可通过此端点调用。

请求参数

参数	类型	必填	说明
`model`	string	是	模型 ID，如 claude-sonnet-4-6、gpt-4o
`input`	string\|array	是	输入内容，字符串或结构化消息数组
`instructions`	string	否	系统提示词（等同于 developer 角色消息）
`stream`	boolean	否	是否流式输出，默认 false
`max_output_tokens`	integer	否	最大输出 token 数，默认 4096
`temperature`	number	否	温度参数
`tools`	array	否	工具定义（function calling）

请求示例

curl https://api.yunjunet.cn/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "claude-sonnet-4-6",
    "input": "Hello!",
    "max_output_tokens": 1024
  }'

结构化输入（多轮对话）

{
  "model": "claude-sonnet-4-6",
  "instructions": "You are a helpful assistant",
  "input": [
    {"type": "message", "role": "user", "content": "What is 2+2?"},
    {"type": "message", "role": "assistant", "content": [
      {"type": "output_text", "text": "4"}
    ]},
    {"type": "message", "role": "user", "content": "And 3+3?"}
  ]
}

响应示例

{
  "id": "resp_xxx",
  "object": "response",
  "created_at": 1234567890,
  "status": "completed",
  "model": "claude-sonnet-4-6",
  "output": [{
    "type": "message",
    "id": "msg_xxx",
    "role": "assistant",
    "status": "completed",
    "content": [{"type": "output_text", "text": "6"}]
  }],
  "usage": {
    "input_tokens": 30,
    "output_tokens": 5,
    "total_tokens": 35
  }
}

流式响应

设置 stream: true 后，返回标准 SSE 事件流：

event: response.created
data: {"type":"response.created","response":{...}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Hello"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":" world!"}

event: response.completed
data: {"type":"response.completed","response":{...usage...}}

Gemini API（Google 兼容）

POST/v1beta/models/{model}:generateContent

POST/v1beta/models/{model}:streamGenerateContent

完全兼容 Google Gemini API 格式，支持 Gemini CLI 等原生客户端直接接入。所有平台模型均可通过此端点调用，平台自动完成 Gemini ↔ OpenAI/Anthropic 格式转换。

请求参数

参数	类型	必填	说明
`contents`	array	是	对话内容，每项含 role（user/model）和 parts
`systemInstruction`	object	否	系统提示词，含 parts 数组
`generationConfig`	object	否	生成配置：maxOutputTokens、temperature、topP

请求示例

curl https://api.yunjunet.cn/v1beta/models/claude-sonnet-4-6:generateContent \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: sk-your-api-key" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello!"}]}
    ],
    "generationConfig": {
      "maxOutputTokens": 1024,
      "temperature": 0.7
    }
  }'

响应示例

{
  "candidates": [{
    "content": {
      "parts": [{"text": "Hello! How can I help you today?"}],
      "role": "model"
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 12,
    "totalTokenCount": 22
  },
  "modelVersion": "claude-sonnet-4-6"
}

流式请求

将端点改为 :streamGenerateContent 即可获得 SSE 流式响应：

POST /v1beta/models/claude-sonnet-4-6:streamGenerateContent

# 响应格式（每个 chunk 为独立 JSON）
data: {"candidates":[{"content":{"parts":[{"text":"Hello"}],"role":"model"},"index":0}],"modelVersion":"claude-sonnet-4-6"}

data: {"candidates":[{"content":{"parts":[{"text":"!"}],"role":"model"},"index":0}],"modelVersion":"claude-sonnet-4-6"}

data: {"candidates":[{"content":{"parts":[{"text":""}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":12,"totalTokenCount":22}}

429 自动重试

遇到上游限流（429）时，平台自动切换到其他可用端点重试（最多 2 次），无需客户端处理。

Codex CLI 接入（OpenAI）

OpenClaw API 完全兼容 OpenAI Codex CLI（OpenAI 官方编程助手），您可以使用 OpenClaw 的 API Key 接入平台上的所有模型。

配置文件

编辑 ~/.codex/config.toml：

# ~/.codex/config.toml
model = "claude-sonnet-4-6"
model_provider = "openclaw"

[model_providers.openclaw]
name = "OpenClaw API"
base_url = "https://api.yunjunet.cn/v1"
wire_api = "responses"
env_key = "OPENCLAW_API_KEY"

设置环境变量

# 设置 API Key
export OPENCLAW_API_KEY=sk-your-api-key

# 启动 Codex
codex

写入 Shell 配置（永久生效）

# Bash
echo 'export OPENCLAW_API_KEY=sk-your-api-key' >> ~/.bashrc && source ~/.bashrc

# Zsh
echo 'export OPENCLAW_API_KEY=sk-your-api-key' >> ~/.zshrc && source ~/.zshrc

支持的模型

Codex CLI 通过 /v1/responses 端点通信，平台上所有已启用的模型均可使用。

重要说明

⚠ 注意：
• wire_api 必须设为 "responses"（默认值，使用 Responses API）
• base_url 为 https://api.yunjunet.cn/v1（含 /v1）
• env_key 可自定义变量名，需在 Shell 中设置对应的环境变量
• 模型切换：修改 config.toml 中的 model 字段即可切换任意平台模型

Gemini CLI 接入

OpenClaw API 完全兼容 Gemini CLI，您可以使用 OpenClaw 的 API Key 替代官方 Google API Key，接入平台上的所有模型。

环境变量配置

# 设置环境变量
export GEMINI_API_KEY=sk-your-api-key
export GEMINI_BASE_URL=https://api.yunjunet.cn/v1beta/

# 启动 Gemini CLI
gemini

写入 Shell 配置（永久生效）

# Bash 用户
echo 'export GEMINI_API_KEY=sk-your-api-key' >> ~/.bashrc
echo 'export GEMINI_BASE_URL=https://api.yunjunet.cn/v1beta/' >> ~/.bashrc
source ~/.bashrc

# Zsh 用户
echo 'export GEMINI_API_KEY=sk-your-api-key' >> ~/.zshrc
echo 'export GEMINI_BASE_URL=https://api.yunjunet.cn/v1beta/' >> ~/.zshrc
source ~/.zshrc

支持的模型

Gemini CLI 通过 /v1beta/models/{model}:generateContent 端点通信，平台上所有已启用的模型均可使用：

Anthropic 模型：claude-opus-4-6、claude-sonnet-4-6 等（自动 Gemini→Anthropic 格式转换）
OpenAI 模型：gpt-4o、gpt-4o-mini 等（自动 Gemini→OpenAI 格式转换）
其他模型：DeepSeek、NVIDIA NIM、Qwen 等全系列模型

重要说明

⚠ 注意：
• GEMINI_BASE_URL 必须以 / 结尾：https://api.yunjunet.cn/v1beta/
• 认证方式：Gemini CLI 使用 GEMINI_API_KEY 环境变量，对应 x-goog-api-key 请求头
• 模型 ID：直接使用平台模型 ID（如 claude-sonnet-4-6），无需加 models/ 前缀

Claude Code CLI 接入

OpenClaw API 完全兼容 Claude Code CLI，您可以直接使用 OpenClaw 的 API Key 替代官方 Anthropic Key。

环境变量配置

# 在终端中设置环境变量（注意：不要加 /v1，CLI 会自动拼接）
export ANTHROPIC_BASE_URL=https://api.yunjunet.cn
export ANTHROPIC_AUTH_TOKEN=sk-your-api-key

# 启动 Claude Code（可指定任意已启用的模型）
claude
claude --model deepseek-chat
claude --model claude-haiku-4-5

写入 Shell 配置（永久生效）

# Bash 用户
echo 'export ANTHROPIC_BASE_URL=https://api.yunjunet.cn' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-your-api-key' >> ~/.bashrc
source ~/.bashrc

# Zsh 用户
echo 'export ANTHROPIC_BASE_URL=https://api.yunjunet.cn' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-your-api-key' >> ~/.zshrc
source ~/.zshrc

支持的模型

Claude Code CLI 通过 /v1/messages 端点通信，平台上所有已启用的模型均可使用：

Anthropic 模型：claude-opus-4-6、claude-haiku-4-5 等（直接透传，原生体验）
其他模型：deepseek-chat、GPT 系列、NVIDIA NIM 模型等（自动格式转换）

重要说明

⚠ 注意：
• 统一 Base URL：https://api.yunjunet.cn（所有 SDK 和 CLI 均使用此地址，无需加 /v1）
• Claude Code CLI：使用环境变量 ANTHROPIC_AUTH_TOKEN 认证
• Anthropic Python SDK：使用 api_key 参数认证

Anthropic Python SDK

pip install anthropic

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.yunjunet.cn",
    api_key="sk-your-api-key"
)

message = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
print(message.content[0].text)

模型列表

GET/v1/models

返回当前可用的所有模型及其定价信息。无需认证。

流式输出

设置 stream: true 后，响应以 Server-Sent Events (SSE) 格式返回：

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"你"},"index":0}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"好"},"index":0}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{},"index":0,"finish_reason":"stop"}]}

data: [DONE]

Python 流式读取

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "写一首诗"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

错误码

HTTP 状态码	含义	说明
400	参数错误	缺少必填参数或参数格式不正确
401	认证失败	API Key 无效或已禁用
402	余额不足	账户余额不足以支付本次调用
404	模型不存在	请求的模型不存在或已下线
429	请求过多	超出速率限制，请稍后重试
500	服务器错误	上游模型服务异常

计费说明

按实际使用 token 数计费，精确到每次 API 调用
token 用量优先使用上游模型返回的真实数据，仅在上游未返回时使用估算
账户余额以美元 (USD) 计价，人民币定价模型自动按汇率折算
每次调用的 token 数和费用均记录在调用日志中，可在控制台查看
支持流式 (stream) 和非流式两种调用方式，计费规则一致

限制说明

单个用户最多创建 10 个 API Key
单次请求最大 10MB
流式响应无超时限制
余额为 0 时将无法发起新的 API 调用