TokenHub 新手接入文档

最重要的两个地址

新手快速开始

第一次使用 TokenHub，可以按下面 6 步完成接入。建议不要跳过验证步骤，否则后面排错会缺少依据。

不知道自己该看哪一节？

获取 API Key

API Key 是工具调用 TokenHub 网关时使用的凭证。每个工具都需要填写它。

1. 打开控制台：https://bufu1155.com/login。
2. 注册或登录账号；如果已经登录，进入 用户仪表盘。
3. 在左侧菜单进入 API Keys 页面。
4. 点击新建 Key，名称建议写清用途，例如 claude-code-mac、codex-laptop、my-saas-prod。
5. 创建后复制 Key。格式通常以 sk- 开头。
6. 回到本文档，把命令中的 sk-your-api-key 替换成真实 Key。

选择正确地址

不同客户端使用的协议格式不同，Base URL 也不同。只要按下表填写即可。

Claude Code 配置

Claude Code 适合在终端里做代码编辑、文件分析和项目辅助。配置 TokenHub 时使用 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY。

第 1 步：确认 Node.js 已安装

Claude Code 需要 Node.js。先在终端执行：

node -v
npm -v

如果能看到版本号，例如 v18、v20、v22，说明已经安装。没有版本号时先看 Node.js 安装。

第 2 步：安装 Claude Code

npm install -g @anthropic-ai/claude-code

第 3 步：临时配置环境变量

临时配置只在当前终端窗口有效，适合先测试。

export ANTHROPIC_BASE_URL="https://bufu1155.com"
export ANTHROPIC_API_KEY="sk-your-api-key"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_ATTRIBUTION_HEADER=0

请把 sk-your-api-key 替换成你在控制台生成的真实 Key。

第 4 步：启动 Claude Code

claude

如果能进入 Claude Code 交互界面，并且简单提问可以返回内容，说明基础配置已经生效。

第 5 步：持久化配置

不想每次打开终端都重新输入环境变量时，可以写入 Shell 配置文件。

macOS / Linux：先确认你使用的是 Zsh 还是 Bash

echo $SHELL

输出包含 zsh 用 Zsh 命令；输出包含 bash 用 Bash 命令。

Zsh 用户

echo 'export ANTHROPIC_BASE_URL="https://bufu1155.com"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-your-api-key"' >> ~/.zshrc
echo 'export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1' >> ~/.zshrc
echo 'export CLAUDE_CODE_ATTRIBUTION_HEADER=0' >> ~/.zshrc
source ~/.zshrc

Bash 用户

echo 'export ANTHROPIC_BASE_URL="https://bufu1155.com"' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY="sk-your-api-key"' >> ~/.bashrc
echo 'export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1' >> ~/.bashrc
echo 'export CLAUDE_CODE_ATTRIBUTION_HEADER=0' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell 临时配置

$env:ANTHROPIC_BASE_URL="https://bufu1155.com"
$env:ANTHROPIC_API_KEY="sk-your-api-key"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
$env:CLAUDE_CODE_ATTRIBUTION_HEADER="0"

Windows PowerShell 持久化配置

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://bufu1155.com", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-your-api-key", "User")
[Environment]::SetEnvironmentVariable("CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "1", "User")
[Environment]::SetEnvironmentVariable("CLAUDE_CODE_ATTRIBUTION_HEADER", "0", "User")

Windows 持久化后需要关闭当前终端，重新打开 PowerShell 才能读取新环境变量。

Codex CLI 配置

Codex CLI 走 OpenAI 兼容格式，Base URL 需要填写 https://bufu1155.com/v1。如果你的 Codex 版本支持配置文件，推荐使用 ~/.codex/config.toml 和 ~/.codex/auth.json；如果只支持环境变量，也可以直接设置 OPENAI_BASE_URL 和 OPENAI_API_KEY。

第 1 步：确认 Node.js 已安装

node -v
npm -v

第 2 步：安装 Codex CLI

npm install -g @openai/codex

第 3 步：临时配置环境变量

export OPENAI_BASE_URL="https://bufu1155.com/v1"
export OPENAI_API_KEY="sk-your-api-key"

第 4 步：启动 Codex

codex

第 5 步：配置文件方式

如果需要让 Codex 固定使用 TokenHub，可以写入下面的配置。

mkdir -p ~/.codex

cat > ~/.codex/config.toml <<'EOF'
model_provider = "OpenAI"
model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://bufu1155.com/v1"
wire_api = "responses"
requires_openai_auth = true
EOF

cat > ~/.codex/auth.json <<'EOF'
{
  "OPENAI_API_KEY": "sk-your-api-key"
}
EOF

chmod 600 ~/.codex/auth.json

Zsh 用户持久化环境变量

echo 'export OPENAI_BASE_URL="https://bufu1155.com/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="sk-your-api-key"' >> ~/.zshrc
source ~/.zshrc

Bash 用户持久化环境变量

echo 'export OPENAI_BASE_URL="https://bufu1155.com/v1"' >> ~/.bashrc
echo 'export OPENAI_API_KEY="sk-your-api-key"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell 临时配置

$env:OPENAI_BASE_URL="https://bufu1155.com/v1"
$env:OPENAI_API_KEY="sk-your-api-key"

Windows PowerShell 持久化配置

[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://bufu1155.com/v1", "User")
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-api-key", "User")

OpenClaw 配置

OpenClaw 一般按 OpenAI 兼容接口接入。配置时重点填写 Base URL、API Key 和模型名。

第 1 步：打开设置页面

进入 OpenClaw 的 Settings、Provider、API 或模型服务商配置页。不同版本页面名称可能不同，只要找到 OpenAI Compatible 或自定义 API 服务商即可。

第 2 步：填写以下信息

第 3 步：保存并测试

保存后发送一句简单测试，例如：

你好，请用一句话回答：当前 API 是否连接成功？

能正常返回内容说明 OpenClaw 已接入成功。报模型不存在时，优先检查模型名、Key 权限、分组和是否选择了 OpenAI 兼容模式。

项目代码接入 OpenAI 兼容接口

如果要在自己的网站、SaaS、机器人或脚本里调用 TokenHub，使用 OpenAI 兼容方式即可。核心是把官方 SDK 的 baseURL 或 base_url 改为 https://bufu1155.com/v1。

Node.js 示例

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://bufu1155.com/v1"
});

const res = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    { role: "user", content: "Hello" }
  ]
});

console.log(res.choices[0].message.content);

Python 示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://bufu1155.com/v1"
)

res = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello"}]
)

print(res.choices[0].message.content)

curl 示例

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

Gemini CLI 配置

Gemini CLI 使用 Gemini 兼容路径。请确认你的 TokenHub Key 所属分组已经开通 Gemini 模型。

export GOOGLE_GEMINI_BASE_URL="https://bufu1155.com/v1beta"
export GEMINI_API_KEY="sk-your-api-key"
export GEMINI_MODEL="gemini-2.0-flash"

gemini "请用一句话回答：Gemini CLI 是否已接通？"

cc-switch 切换工具

如果经常在官方 API 和 TokenHub 之间切换，可以使用 cc-switch 管理环境变量。这样不需要每次手动修改多个配置项。

安装

npm install -g cc-switch

添加 TokenHub 配置

cc-switch add tokenhub-bufu1155 \
  --anthropic-url https://bufu1155.com \
  --openai-url https://bufu1155.com/v1 \
  --key sk-your-api-key

切换到 TokenHub

cc-switch use tokenhub-bufu1155

查看当前配置

cc-switch status

切换回官方 API

cc-switch use official

配置名称建议使用英文、数字和短横线，例如 tokenhub-bufu1155，避免脚本或终端对中文名称兼容不好。

Node.js 安装

Claude Code、Codex CLI、cc-switch 通常都需要 Node.js 和 npm。建议安装 Node.js LTS 版本。

先检查是否已安装

node -v
npm -v

提示 command not found 或没有版本号时，说明没有安装或当前终端还没有读取到 Node.js。

macOS 安装

# 方式 1：Homebrew
brew install node

# 方式 2：nvm，适合需要切换 Node 版本的用户
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts

Windows 安装

winget install OpenJS.NodeJS.LTS

也可以到 Node.js 官网下载安装包。安装完成后，重新打开 PowerShell，再运行 node -v。

Ubuntu / Debian Linux 安装

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

验证安装成功

node -v
npm -v

验证是否配置成功

客户端配置完成后，建议先做最小验证，再把 Key 放进真实项目。

检查环境变量是否存在

macOS / Linux

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_API_KEY
echo $OPENAI_BASE_URL
echo $OPENAI_API_KEY

Windows PowerShell

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_API_KEY
echo $env:OPENAI_BASE_URL
echo $env:OPENAI_API_KEY

OpenAI 兼容 curl 测试

curl https://bufu1155.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "请用一句话回答：API 是否连接成功？"}
    ]
  }'

成功结果应该是什么样？

如果成功，你会看到 JSON 返回，一般包含：

• id：请求编号；
• choices：模型返回内容；
• usage：Token 用量；
• model：实际调用的模型名。

如果 curl 能成功，但某个客户端失败，通常是客户端里的 Base URL、模型名、Key 或协议模式没有填对。

常见错误

401 Unauthorized

含义：API Key 无效、没有填写、复制错误，或环境变量没有生效。

处理方法：

• 确认命令里的 sk-your-api-key 已替换成真实 Key。
• 确认 Key 没有多复制空格、换行或中文引号。
• 检查环境变量是否能正常输出。
• 进入 API Keys 页面确认 Key 没有被禁用或删除。

echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

404 Not Found

含义：Base URL 路径错误。最常见原因是 /v1 加错或漏加。

• Claude Code：https://bufu1155.com，不带 /v1。
• Codex / OpenClaw / OpenAI SDK：https://bufu1155.com/v1，带 /v1。
• Gemini CLI：https://bufu1155.com/v1beta。

model not found / 模型不存在

常见原因：

• 模型名拼写错误；
• 账号或 Key 所属分组没有开通该模型；
• 客户端使用了默认模型，但默认模型不在你的可用列表中；
• 把 Claude 模型当成 OpenAI 模型调用，或把 OpenAI 模型当成 Claude 模型调用。

处理方法：进入 可用渠道 页面查看模型列表，并复制完整模型名。

insufficient_quota / balance not enough / 余额不足

含义：账号余额不足、Key 的预算不足，或该模型本次请求消耗超过限制。

处理方法：

• 打开 Key 用量 或控制台查看余额；
• 检查 API Key 的预算、每日限额和过期时间；
• 先换低成本模型测试；
• 避免一次性设置过大的 max_tokens。

rate_limit_exceeded / 429

含义：请求频率过高，超过 RPM、TPM 或并发限制。

处理方法：

• 降低并发；
• 增加请求间隔；
• 检查代码是否出现死循环或过度重试；
• 需要更高额度时联系代理商调整分组限制。

Connection refused / timeout

含义：网络连接失败、地址填错、本机代理异常，或服务暂时不可达。

处理方法：

• 确认 Base URL 完整且没有拼写错误。
• 浏览器打开 https://bufu1155.com/home 看是否能访问。
• 检查本机代理、VPN、防火墙和 DNS。
• 稍后重试，或联系代理商查看渠道状态。

npm 权限错误：EACCES

macOS / Linux 安装全局 npm 包时可能遇到权限错误。推荐修改 npm 全局目录：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

node: command not found

说明 Node.js 没安装，或安装后当前终端没有刷新。按 Node.js 安装 重新处理，再打开一个新终端验证。

环境变量不生效

• 确认写入了正确配置文件：Zsh 是 ~/.zshrc，Bash 是 ~/.bashrc。
• 执行 source ~/.zshrc 或重新打开终端。
• Windows 用户持久化设置后，必须重新打开 PowerShell。
• VS Code、JetBrains IDE、终端插件可能需要重启，才能读取新的环境变量。

余额、订单和用量

TokenHub 的用户侧页面围绕“Key 能不能用、用了多少、还有多少额度”来设计。排错时先看这些入口。

代理商后台说明

TokenHub 是帮代理商部署的中转站，代理商后台用于运营客户、渠道和定价。普通用户只需要看前面的接入流程，代理商或管理员才需要关注这一节。

安全使用建议

API 网关能让多个 AI 工具快速接入，但 Key 和额度需要认真管理。

• 不要把 API Key 发布到 GitHub、论坛、截图、聊天群。
• 不要把 API Key 写在浏览器前端代码里。
• 不同项目、不同工具使用不同 Key，便于单独统计和禁用。
• 给每个 Key 设置合理预算、过期时间和频率限制。
• 生产环境上线前，先用小额预算跑一段时间观察用量。
• 发现余额异常消耗时，立即禁用对应 Key 并重新生成。
• 下游产品接入 TokenHub 时，需要自行管理终端用户行为、隐私告知和业务合规。

FAQ

1. sk-your-api-key 是什么？

这是示例占位符。你需要把它替换成 TokenHub 控制台生成的真实 API Key，例如 sk-xxxxxx。

2. Claude Code 为什么不带 /v1？

Claude Code 使用 Anthropic 风格配置，工具会自己拼接接口路径。因此 Base URL 填 https://bufu1155.com 即可。

3. OpenAI 兼容工具为什么要带 /v1？

OpenAI SDK 和多数兼容客户端会请求 /v1/chat/completions、/v1/responses、/v1/models 等路径，所以 Base URL 通常写到 /v1。

4. 我可以同时配置 Claude Code 和 Codex 吗？

可以。它们使用的环境变量不同，互不冲突：

• Claude Code：ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY。
• Codex / OpenAI SDK：OPENAI_BASE_URL、OPENAI_API_KEY。

5. 为什么工具能打开，但模型没有回复？

常见原因是余额不足、模型名错误、Key 没权限、请求超时、客户端默认模型不可用或选择了错误协议。先用 curl 验证，再排查具体客户端。

6. API Key 泄露怎么办？

立即进入 API Keys 页面禁用或删除该 Key，然后新建一个 Key。建议每个工具单独建 Key，泄露时影响范围更小。

7. 可以把 API Key 放在前端网页里吗？

不建议。前端代码会暴露给访问者。正确做法是把 Key 放在你自己的后端服务器，由后端调用 TokenHub。

8. 配置后还是失败，应该提供什么信息给客服？

请提供以下信息，避免只说“不能用”：

• 你使用的工具：Claude Code / Codex / OpenClaw / SDK / Gemini CLI；
• 你填写的 Base URL；
• 错误码或报错截图；
• 请求的大致时间；
• 模型名；
• 不要发送完整 API Key，最多只提供 Key 的前 6 位和后 4 位用于识别。

9. TokenHub 和普通 API 中转有什么区别？

普通中转通常只处理请求转发。TokenHub 面向代理商交付，包含品牌站、用户系统、Key 分发、模型权限、余额计费、支付订单、用量报表、渠道监控和运维部署。

10. 客户为什么只需要一个 API Key？

TokenHub 在网关层处理平台差异、账号池、模型映射和调度。客户只面对代理商站点和自己的 Key，不需要分别管理多个上游订阅。