Api Halo

🚀 快速开始

1. 访问 apihalo.cn 注册并登录，确认账户余额充足
2. 进入控制台「令牌」页面，点击「添加令牌」
3. 填写令牌名称并选择需要的模型分组，然后复制生成的 API Key（通常以 sk- 开头）
4. 从模型广场复制准确模型名，再按下方对应客户端完成配置

按场景阅读专题教程

⬇️ 官方下载与安装入口

请优先从官网或官方 GitHub 下载，避免使用来历不明的安装包。安装完成后，再按下方对应章节接入 Api Halo。

🔀 CC-Switch 快速配置

CC-Switch 适合统一管理 Claude Code、Codex、Gemini CLI 等客户端的供应商配置。

安装方法

1. 打开官方 Releases 页面，展开最新版本的 Assets。
2. 按操作系统下载对应安装包：Windows 通常选择 .exe，macOS 选择 .dmg，Linux 选择对应发行版安装包或 AppImage。
3. 安装并打开 CC-Switch；如果系统拦截，请只在确认文件来自上述官方仓库后允许运行。

OpenAI / Codex

供应商类型：OpenAI Compatible
Base URL：  https://apihalo.cn/v1
API Key：   你的 Api Halo 令牌
Model：     从模型广场复制准确模型名

Anthropic / Claude Code

供应商类型：Anthropic Compatible
Base URL：  https://apihalo.cn
API Key：   你的 Api Halo 令牌
Model：     令牌所属分组支持的 Claude 模型

💬 Chatbox 接入 推荐

Chatbox 是一款跨平台 AI 聊天客户端，支持 Windows / macOS / Linux / iOS / Android。

安装方法

1. 进入官网，按 Windows、macOS、Linux 或移动端选择对应版本。
2. 桌面端运行安装包；移动端请从官网跳转至官方应用商店安装。
3. 启动 Chatbox 后进入设置，再按下方步骤接入 Api Halo。

配置步骤

1. 打开 Chatbox → 左下角「设置」
2. 选择「AI 模型提供方」→ OpenAI API
3. 填写配置：

   API Host：https://apihalo.cn
   API Key： 你的令牌
   模型：    gpt-5.5（或其他模型名）

4. 点击「保存」，发送消息验证

⌨️ Codex CLI / Cursor / Trae / VS Code

这类客户端通常使用 OpenAI 兼容协议。

Codex CLI 安装

Windows / macOS / Linux（需 Node.js 与 npm）

npm install -g @openai/codex
codex --version

安装后进入项目目录运行 codex。Cursor、Trae 与 VS Code 请从上方官网下载系统对应安装包，运行安装程序即可。

Api Halo 配置

Provider： OpenAI Compatible / Custom OpenAI
Base URL： https://apihalo.cn/v1
API Key：  你的 Api Halo 令牌
Model：    从模型广场复制准确模型名

环境变量

# Linux / macOS
export OPENAI_API_KEY="你的 Api Halo API Key"
export OPENAI_BASE_URL="https://apihalo.cn/v1"

# Windows PowerShell
$env:OPENAI_API_KEY="你的 Api Halo API Key"
$env:OPENAI_BASE_URL="https://apihalo.cn/v1"

Codex 配置示例

model = "gpt-5.4"
model_provider = "apihalo"

[model_providers.apihalo]
name = "Api Halo"
base_url = "https://apihalo.cn/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

🖥️ Claude Code 接入

Claude Code 是 Anthropic 官方终端 AI 编程助手，适合在命令行中写代码。

安装 Claude Code

macOS / Linux / WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows WinGet

winget install Anthropic.ClaudeCode

安装后先运行 claude --version 验证。Windows 可原生运行；如使用 Linux 工具链，也可在 WSL 2 内按 Linux 方式安装。

配置 Api Halo

export ANTHROPIC_BASE_URL=https://apihalo.cn
export ANTHROPIC_AUTH_TOKEN=你的令牌
export ANTHROPIC_MODEL=claude-fable-5

永久生效（写入配置文件）

# macOS (zsh)
echo 'export ANTHROPIC_BASE_URL=https://apihalo.cn' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN=你的令牌' >> ~/.zshrc
source ~/.zshrc

# Linux (bash)
echo 'export ANTHROPIC_BASE_URL=https://apihalo.cn' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN=你的令牌' >> ~/.bashrc
source ~/.bashrc

验证

claude "你好"

🧩 OpenCode 接入

安装 OpenCode

macOS / Linux

curl -fsSL https://opencode.ai/install | bash

Windows / macOS / Linux（npm）

npm install -g opencode-ai
opencode --version

Windows 也可使用 choco install opencode 或 scoop install opencode。安装后进入项目目录运行 opencode。

配置 Api Halo

在 OpenCode 中新增 OpenAI 兼容供应商：

{
  "provider": {
    "apihalo": {
      "name": "Api Halo",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://apihalo.cn/v1",
        "apiKey": "你的 Api Halo API Key"
      },
      "models": {
        "gpt-5.4": { "name": "GPT-5.4" }
      }
    }
  }
}

✏️ Cursor 接入

Cursor 是基于 VS Code 的 AI 代码编辑器。

安装方法

1. 打开官方下载页，选择 Windows、macOS 或 Linux 版本。
2. macOS 请区分 Apple 芯片与 Intel；Linux 按发行版选择 AppImage、deb 或 rpm。
3. 安装并启动 Cursor，再按下方步骤配置 Api Halo。

配置步骤

1. 打开 Cursor → Settings → Models
2. 找到 OpenAI API Key，填入你的令牌
3. 设置 Override OpenAI Base URL：https://apihalo.cn/v1
4. 选择模型（如 gpt-5.5）并保存

🐾 OpenClaw / Cherry Studio / 通用客户端

凡支持 OpenAI Compatible 或自定义 OpenAI Base URL 的客户端，均可接入 Api Halo。

安装 OpenClaw

Windows / macOS / Linux（需 Node.js 22 或更高版本）

npm install -g openclaw@latest
openclaw onboard

Cherry Studio 用户从官方 Releases 下载对应系统安装包，安装后在“模型服务”中新增 OpenAI 兼容供应商。

推荐配置

Provider 类型：OpenAI-compatible
Base URL：    https://apihalo.cn/v1
API Key：     你的令牌
主模型：      gpt-5.5
备用模型：    claude-opus-4-6-thinking、claude-sonnet-4-6

模型别名示例

gpt-5.5                  → gpt-5.5
claude-opus-4-6-thinking → claude-opus-4-6-thinking
claude-sonnet-4-6        → claude-sonnet-4-6

通用 JSON 配置片段

不同 OpenClaw 版本的配置文件位置可能不同，请按你的 OpenClaw 文档或控制台填写；核心字段保持一致即可。

{
  "providers": {
    "apihalo": {
      "type": "openai-compatible",
      "baseURL": "https://apihalo.cn/v1",
      "apiKey": "你的令牌"
    }
  },
  "model": "apihalo/gpt-5.5",
  "fallbacks": [
    "apihalo/claude-opus-4-6-thinking",
    "apihalo/claude-sonnet-4-6"
  ]
}

验证调用

curl https://apihalo.cn/v1/chat/completions \
  -H "Authorization: Bearer 你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "回复 OK"}],
    "max_tokens": 128
  }'

⚡ API 直接调用

接口地址

POST https://apihalo.cn/v1/chat/completions

curl 示例

curl https://apihalo.cn/v1/chat/completions \
  -H "Authorization: Bearer 你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

Python 示例

from openai import OpenAI

client = OpenAI(
    api_key="你的令牌",
    base_url="https://apihalo.cn/v1"
)

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

Node.js 示例

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: '你的令牌',
  baseURL: 'https://apihalo.cn/v1'
});

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

Claude / PDF 文件输入

Claude 系列模型支持通过 Anthropic 原生 /v1/messages 上传 PDF 文档；OpenAI-compatible 的 /v1/chat/completions 也已兼容 content[].file.file_data 的非流式 PDF / 文本文件输入。

curl https://apihalo.cn/v1/chat/completions \
  -H "Authorization: Bearer 你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-6-thinking",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "总结这个 PDF"},
        {"type": "file", "file": {
          "filename": "example.pdf",
          "file_data": "PDF_BASE64内容"
        }}
      ]
    }],
    "stream": false
  }'

♊ Gemini CLI 安装与接入

Gemini CLI 是 Google 官方开源终端智能体。使用前请安装 Node.js 20 或更高版本。

安装

npm install -g @google/gemini-cli
gemini --version

不同版本对自定义 OpenAI Base URL 的支持可能不同。若当前版本无法直接配置 Api Halo，建议通过 CC-Switch 管理，或改用支持 OpenAI Compatible 的客户端。

🎨 GPT Image API

图像模型需使用模型广场当前上架的准确模型名，例如 gpt-image-2。

curl https://apihalo.cn/v1/images/generations \
  -H "Authorization: Bearer 你的 Api Halo API Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴着宇航头盔的橘猫，电影级灯光",
    "size": "1024x1024"
  }'

🧠 可用模型

以下为部分热门模型，完整列表请登录控制台「模型广场」查看。

🔧 兼容工具

所有支持 OpenAI API 协议的工具均可接入 Api Halo。

❓ 成功判断与常见问题

最小测试请求

curl https://apihalo.cn/v1/chat/completions \
  -H "Authorization: Bearer 你的 Api Halo API Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "请回复：Api Halo 接入成功"}]
  }'

提示 401 Unauthorized？

检查 API Key 是否复制完整，确认令牌未过期或被禁用。

提示 403 或模型不可用？

确认模型名拼写完全一致，并检查令牌所属分组是否包含该模型。不同分组的可用模型和倍率可能不同。

提示 404 Not Found？

检查 Base URL。OpenAI 兼容客户端通常填写 https://apihalo.cn/v1；若客户端自动添加 /v1，则填写 https://apihalo.cn，避免最终请求变成 /v1/v1/...。

提示 429？

可能是请求过快、渠道并发受限或账户额度不足。请降低并发、稍后重试，并检查余额与控制台日志。

余额不足？

登录控制台 → 钱包 → 充值。支持多种支付方式。

响应速度慢？

深度推理模型（如 thinking 系列）响应时间较长属正常。普通模型如持续超时请联系客服。

Claude 支持上传 PDF 吗？

支持。Claude 原生 Anthropic 协议支持 PDF 文档输入；OpenAI-compatible 的 Claude 文件输入当前支持非流式 PDF / 文本文件。

OpenClaw 应该填哪个地址？

OpenClaw 使用 OpenAI-compatible 接入时，Base URL 填 https://apihalo.cn/v1，API Key 填控制台创建的令牌，模型名可用 gpt-5.5 或 Claude 系列模型。

支持流式输出吗？

支持。请求时加 "stream": true 参数即可实时返回。

支持图片生成吗？

支持。使用 gpt-image-2 等图像模型，通过 Images API 调用。

有并发限制吗？

默认无硬性并发限制，但建议合理控制请求频率。如有大批量需求请联系客服。