XCoffee API 使用教程
从取得客户 Key 开始,设置 Codex、Claude Code、OpenClaw、Hermes、Pi 与 Cursor,附 Windows 范例与连接验证。
最近更新: 2026-11-07
选择你的工具
先到 API 控制台 拷贝客户 Key、对应协议的 Base URL 和可用模型组,再选择下面的教程。Codex、Claude Code 与 OpenClaw 的步骤预设展开,可以直接阅读和拷贝。
三步接入
- 在用户中心取得月卡并拷贝客户 Key。不要使用管理员 Key 或 Magpie 内部 Key。
- 在 API 控制台选择客户端使用的协议,拷贝对应 Base URL 和范例。
- 将模型名设为可用用途组的调用名。首页列出管理员公开的组内模型;组名和名单可能更新。
本站按请求的用途组路由,任务拆分和为子任务选组由客户端完成。Magpie 可依管理员的组设置,在开始输出前尝试组内下一个候选;网站不会在已输出部分内容或用户取消后重放生成请求。
选择你的 Agent
已安装客户端、已有有效月卡和客户 Key,就可以开始。第一次设置建议用 xcoffee-coding 做编码任务;若 API 控制台没有这个组,请换成控制台列出的可用调用名。
| 你使用的工具 | 选择的协议 | 填入的 Base URL |
|---|---|---|
| Claude Code/CC Switch 的 Claude Code 设置 | Anthropic Messages | https://api.xcoff.ee |
| Codex CLI | OpenAI Responses | https://api.xcoff.ee/v1 |
| OpenClaw | OpenAI Chat Completions | https://api.xcoff.ee/v1 |
| Hermes / Pi | OpenAI Chat Completions | https://api.xcoff.ee/v1 |
| Cursor(需自订接口入口) | OpenAI Compatible | https://api.xcoff.ee/v1 |
| 支持 Chat Completions 的其他 Agent | OpenAI Compatible/Chat Completions | https://api.xcoff.ee/v1 |
模型填用途组调用名,不是首页展示的组内模型名。编码与工具任务可选 xcoffee-coding,短任务可选 xcoffee-fast,通用任务可选 xcoffee;实际可用组、协议、倍率以 API 控制台为准。选组后由服务端在组内路由,不能指定某个组内模型。
先把 Key 放在自己的电脑
以下终端范例适用 macOS/Linux 的 Bash 或 Zsh,且假设已安装相应 CLI。在将要启动 Agent 的同一个终端运行,提示后粘贴客户 Key 并按 Enter;输入时不显示字符:
printf 'XCoffee API Key: '
read -rs XCOFFEE_API_KEY
export XCOFFEE_API_KEY
printf '\n'
Key 只保留于这个终端及其启动的程序,关闭后需重新设置。不要把 Key 写进项目、提交 Git 或贴进聊天;需要长期保存时,使用客户端的凭证设置。图形界面与其他终端不会自动取得这个变量。
Windows PowerShell:输入 Key
在新的 PowerShell 窗口运行,提示后粘贴自己的客户 Key:
$secret = Read-Host "XCoffee API Key" -AsSecureString
$env:XCOFFEE_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password
Remove-Variable secret
先验证地址与 Key
macOS / Linux:
curl --fail-with-body https://api.xcoff.ee/v1/models \
-H "Authorization: Bearer $XCOFFEE_API_KEY"
PowerShell:
Invoke-RestMethod -Uri "https://api.xcoff.ee/v1/models" `
-Headers @{ Authorization = "Bearer $env:XCOFFEE_API_KEY" }
成功时应看到模型列表。这一步验证地址、认证与可见组名;还需要选择正确协议并完成下面的真实对话及工具测试。
通用图形界面怎么填
添加自订提供商,填入上表对应地址、自己的客户 Key,以及可用的用途组调用名,保存后切换到这个提供商。Key 栏通常只填 Key 本身,不自行加 Bearer 。若表单问的是完整请求 URL而不是 Base URL,Chat Completions 填 https://api.xcoff.ee/v1/chat/completions。不要重复加 /v1。
按客户端查看步骤
点开你使用的工具即可,不需要阅读全部教学。
Claude Code:接入 XCoffee
1. 安装并确认版本
若尚未安装,先按 Claude Code 官方安装说明 安装。然后运行 claude --version。这一节针对 Claude Code CLI;桌面应用与编辑器扩展的设置入口不同。
2. macOS / Linux:在同一终端启动
先按上方步骤设置 XCOFFEE_API_KEY。在 API 控制台选 Anthropic Messages,确认 xcoffee-coding 是你可用的组名;若名称不同,替换以下模型值。
env -u ANTHROPIC_API_KEY \
ANTHROPIC_BASE_URL=https://api.xcoff.ee \
ANTHROPIC_AUTH_TOKEN="$XCOFFEE_API_KEY" \
claude --model xcoffee-coding
Base URL 填站点根地址,不要加 /v1/messages。ANTHROPIC_AUTH_TOKEN 会以 Bearer 标头发送你的客户 Key;本站也支持 x-api-key,但首次设置请选一种认证方式。
3. Windows:在新的 PowerShell 窗口设置
先完成上方 PowerShell 的 Key 输入,再运行:
Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue
$env:ANTHROPIC_BASE_URL = "https://api.xcoff.ee"
$env:ANTHROPIC_AUTH_TOKEN = $env:XCOFFEE_API_KEY
claude --model xcoffee-coding
这些变量供目前终端及它启动的程序使用。启动后送出「只回复:连接成功」,再输入 /status,确认 Base URL 是 XCoffee,并到本站 API 控制台核对这次调用。
4. 长期设置与其他启动方式
长期使用时,可在自己的 ~/.claude/settings.json 中合并 env 设置;Windows 对应 %USERPROFILE%\.claude\settings.json。保留其他设置,只修改接入所需字段;不要将含真实 Key 的设置放进版本控制。设置档中的同名 env 可覆盖终端变量,若仍连到旧地址,先检查这里。
使用 CC Switch 时,在 Claude Code 的自订提供商中填 XCoffee、根地址 https://api.xcoff.ee、客户 Key 和可用组名;如有协议选项,选 Anthropic Messages。使用 VS Code 扩展时,按官方网关文档设置 claudeCode.environmentVariables,不要假设从 Dock 或开始菜单启动的编辑器会继承终端变量。
若后台调用记录显示客户端另外请求了未开放的 sonnet、opus 或 haiku,可在启动器环境中把对应别名指向同一个可用 Messages 组,或分别选择其他已开放的组:
export ANTHROPIC_DEFAULT_SONNET_MODEL=xcoffee-coding
export ANTHROPIC_DEFAULT_OPUS_MODEL=xcoffee-coding
export ANTHROPIC_DEFAULT_HAIKU_MODEL=xcoffee-coding
常见问题
- 显示
Model isn't recognized时,先核对组名和协议;客户端显示的预设上下文容量不是本站保证。 - 出现旧认证冲突时,核对
ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN和设置档,而不是反复换 Key。 - 若上游拒绝实验性工具参数,再按需使用以下排查组合,不把它当作所有用户的预设:
env -u ANTHROPIC_API_KEY \
ANTHROPIC_BASE_URL=https://api.xcoff.ee \
ANTHROPIC_AUTH_TOKEN="$XCOFFEE_API_KEY" \
ENABLE_TOOL_SEARCH=false \
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 \
claude --model xcoffee-coding
基本对话、读取测试文件、创建并读回文件都成功后,再投入正式任务。上游能力及客户端版本仍会影响可用功能。
Codex CLI:独立配置与启动
1. 确认版本与协议
先按 OpenAI 官方快速开始 安装 Codex CLI,运行 codex --version。在本站 API 控制台选 OpenAI Responses,确认可用组名。以下独立 profile 适用 Codex CLI 0.134.0 及之后的版本。
2. 添加自己的 XCoffee 配置档
创建 ~/.codex/xcoffee.config.toml;Windows 为 %USERPROFILE%\.codex\xcoffee.config.toml。若已存在,先备份并合并,不要重复声明同名区段。把 xcoffee-coding 换成你可用的 Responses 组:
model = "xcoffee-coding"
model_provider = "xcoffee"
model_reasoning_effort = "medium"
[model_providers.xcoffee]
name = "XCoffee"
base_url = "https://api.xcoff.ee/v1"
env_key = "XCOFFEE_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
文件内使用顶层设置,不要再包一层 [profiles.xcoffee]。新版 --profile 读的是这个独立文件。env_key 是环境变量的名称,不是真实 Key;无需改写 auth.json。
3. 设置 Key 并启动
在同一终端按上方步骤设置 XCOFFEE_API_KEY,进入你的测试目录后运行:
codex --profile xcoffee
PowerShell 也是同一条启动命令。开新会话,先请它回复一句话,再测试读写测试文件,最后到本站查看用量记录。
要启用网页搜索,加上 --search。它是顶层选项,必须写在 exec 之前(codex exec --search 会失败)。
交互式:
codex --profile xcoffee --search
非交互式:
codex --profile xcoffee --search exec "…"
这个 profile 只在你选用它时套用。若要保留全局预设提供商,平时仍用原来的启动方式。较旧版本及需要全局提供商设置的界面,可将同样内容合并到用户 ~/.codex/config.toml 后运行 codex,但那会改变全局预设。不要把这些凭证路由设置写入项目的 .codex/config.toml。
常见问题
401:确认启动 Codex 的终端能取得XCOFFEE_API_KEY,使用的是本站客户 Key。- 模型或接口不支持:先确认组名有 Responses 能力;Chat Completions 地址不适用 Codex 的这个配置。
- 仍连到其他提供商:确认启动时有带
--profile xcoffee,并检查是否有额外命令行覆写。 - 本站使用 HTTP Responses,所以配置禁用 WebSocket。请求需携带完整对话,
previous_response_id和保存式上游会话不开放;不要自行套用官方模型的上下文容量。
客户端子代理与本机工具不是供应商托管工具,多个 Agent 的请求仍共用帐号积分和并发。网页搜索与其他附加能力以本页支持范围及用户中心显示为准。
OpenClaw:添加 XCoffee 提供商
- 安装 OpenClaw 并运行
openclaw --version;先备份自己的~/.openclaw/openclaw.json。 - 在 API 控制台选 Chat Completions,确认要使用的组名。
- 将以下内容合并到既有设置。保留其他提供商、Agent 和频道;
xcoffee-coding是示例,请按实际可用组名修改:
{
"models": {
"mode": "merge",
"providers": {
"xcoffee": {
"baseUrl": "https://api.xcoff.ee/v1",
"api": "openai-completions",
"apiKey": {
"source": "env",
"provider": "default",
"id": "XCOFFEE_API_KEY"
},
"models": [{ "id": "xcoffee-coding", "name": "XCoffee Coding" }]
}
}
},
"agents": {
"defaults": {
"model": { "primary": "xcoffee/xcoffee-coding" }
}
}
}
xcoffee/ 是 OpenClaw 内部的提供商前缀,真正发到本站的模型名仍是 xcoffee-coding。SecretRef 引用本机环境变量,不需要将真实 Key 写进 JSON;请让实际运行 OpenClaw 的进程取得 XCOFFEE_API_KEY。
- 按你的原有方式启动或重启 OpenClaw。若 Gateway 作为服务运行,为那个服务配置环境变量;在另一个终端
export不会更新已运行的服务。 - 运行以下命令确认配置和模型列表,再用新对话完成基本回复与工具测试:
openclaw models status
openclaw models list
状态和列表检查不等同真实生成成功。若现有 Agent 有模型白名单或会话自己的模型覆写,也需要加入或选择 xcoffee/xcoffee-coding。上下文及图片能力应依该组实际能力填写,不照抄其他提供商的数值。
Hermes:终端与 Telegram 使用同一个提供商
先退出正在运行的 Hermes 会话,在终端运行:
hermes model
- 选择
Custom endpoint(自订接口),不要选 ChatGPT 订阅或官方 Anthropic 登录。 - Base URL 填
https://api.xcoff.ee/v1,API Key 填本站客户 Key。 - 若询问传输协议,选
chat_completions;模型填xcoffee-coding,或 API 控制台中其他可用组名。 - 若询问上下文长度,先留空让客户端侦测,不要因画面显示 256K 就认定组内所有模型都有这个容量。
- 保存后运行
hermes,开新会话测试。
支持具名提供商的版本,也可备份并合并以下内容到 ~/.hermes/config.yaml 的既有 providers 中。这是向导的替代方式,Key 使用前面的环境变量:
providers:
xcoffee:
api: https://api.xcoff.ee/v1
key_env: XCOFFEE_API_KEY
transport: chat_completions
default_model: xcoffee-coding
启动 Hermes 后用 /model 选择 XCoffee 的模型组。若用 Telegram,请在运行 Hermes gateway 的那台电脑和对应设置目录配置,而不是只修改另一台电脑。环境变量须提供给 gateway 服务;交互终端的 export 不会自动更新已运行的服务。透过原来的服务管理方式重新启动 gateway,再用新会话测试;原会话可能保留自己的模型选择。只在本机安全保存 Key,不要把 Key 发给 Telegram Bot。
Pi:加入自订模型组
这里的 Pi 指 pi-mono 的 coding agent。先设置上方的 XCOFFEE_API_KEY,再备份并编辑 ~/.pi/agent/models.json;若自订过 Pi agent 目录,使用该目录的文件。将 xcoffee 合并到既有 providers,不要覆盖其他提供商:
{
"providers": {
"xcoffee": {
"baseUrl": "https://api.xcoff.ee/v1",
"api": "openai-completions",
"apiKey": "${XCOFFEE_API_KEY}",
"models": [
{ "id": "xcoffee-coding", "name": "XCoffee Coding" },
{ "id": "xcoffee-fast", "name": "XCoffee Fast" },
{ "id": "xcoffee", "name": "XCoffee" }
]
}
}
}
范例列出三个组,只保留 API 控制台中实际可用的组。apiKey 是环境变量引用,不是让你把真实 Key 贴进文件。启动 pi,输入 /model 选择 XCoffee;重新打开模型菜单会重新加载模型设置。请勿照抄其他模型的上下文或图片能力,必要时按本站公布的组能力填写。
Cursor:先确认版本提供自订接口入口
- 打开 Cursor Settings → Models,找到 API Key 设置。
- 如果你的版本有 OpenAI Base URL 覆写或自订提供商功能,地址填
https://api.xcoff.ee/v1,Key 填本站客户 Key。 - 如果可以添加自订模型,加入 API 控制台的组名,例如
xcoffee-coding,再于对话模型菜单选中它。 - 开新对话完成下方三个测试;只验证 Key 成功,不代表编辑和工具功能一定可用。
若找不到自订地址或模型入口,先不要将本站 Key 填到官方供应商地址。Cursor 官方 BYOK 文档没有保证任意第三方组名都能使用,这里是有相应入口时的设置指引,尚非 XCoffee 的完整 Cursor 实测认证。自订 Key 不替代 Cursor Tab 的内置模型;Agent、推理模型和其他专属功能依 Cursor 版本及其支持范围而定。Cursor 的请求会经过其后端,不是完全由本机直连本站。
配好后,做三个小测试
在一个空的测试目录启动 Agent,依序发送:
- 「只回复:连接成功。」确认基本对话。
- 「列出这个测试目录的文件。」确认本机工具调用。
- 「创建 hello.txt,内容是 Hello XCoffee,再读取它确认内容。」依客户端提示批准测试文件操作。
完成后到用户中心查看该 Key 的调用记录和积分。只收到文字回复,不能证明工具调用已成功。遇到错误请提供客户端版本、时间、用途组、错误码或请求 ID,不要附 Key 或完整私密对话。
让 Agent 帮你设置
把以下文字发给能读取网页和编辑本机设置的 Agent,并把「我的客户端」换成 Claude Code、Codex 或你使用的工具:
请阅读 https://api.xcoff.ee/zh-CN/guide,帮我把「我的客户端」接入 XCoffee。
先检查客户端版本并备份设置,只修改接入所需项目,保留其他提供商。
模型先使用 API 控制台可用的 xcoffee-coding;若不可用,请让我选择可用组。
我会自行在本机设置 XCOFFEE_API_KEY;不要读取、显示或要求我贴出 Key。
请按照教程区分协议和地址,不要自行放大上下文或关闭工具操作的安全确认。
完成后告诉我如何启动及验证,不要自行修改或部署其他项目。
这是交给 Agent 的工作说明,不会在网页上自动安装或修改你的电脑。
协议与地址
请把 https://YOUR_HOST 换成本站根地址,把 YOUR_GROUP 换成可用用途组名。API 路径不加语言前缀。
| 协议 | 客户端 Base URL | 生成接口 | Key 请求标头 |
|---|---|---|---|
| OpenAI Chat Completions | https://YOUR_HOST/v1 | /v1/chat/completions | Authorization: Bearer YOUR_KEY |
| OpenAI Responses | https://YOUR_HOST/v1 | /v1/responses | Authorization: Bearer YOUR_KEY |
| Anthropic Messages | https://YOUR_HOST | /v1/messages | x-api-key: YOUR_KEY |
| Gemini 原生 | https://YOUR_HOST | /v1beta/models/YOUR_GROUP:generateContent | x-goog-api-key: YOUR_KEY |
支持 JSON 和 SSE 串流。Anthropic 也接受 Bearer 验证,需带 anthropic-version 标头,预设为 2023-06-01。Gemini 串流使用 :streamGenerateContent?alt=sse;Key 请放标头,不放网址查找参数。模型列表为 /v1/models 或 /v1beta/models,同样需要客户 Key。
管理员须在上游设置中勾选实际支持的接口。既有上游预设只激活 Chat Completions,增加网站入口不代表上游自动具备原生协议。用户中心会依所选协议列出可用用途组。支持客户端函数/工具调用与结构化字段透传,具体能力仍取决于上游模型。
Responses 范例
curl https://YOUR_HOST/v1/responses \
-H "Authorization: Bearer $CUSTOMER_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_GROUP","input":"Hello","max_output_tokens":128,"stream":true,"store":false}'
Anthropic 范例
curl https://YOUR_HOST/v1/messages \
-H "x-api-key: $CUSTOMER_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_GROUP","messages":[{"role":"user","content":"Hello"}],"max_tokens":128,"stream":true}'
Gemini 范例
curl 'https://YOUR_HOST/v1beta/models/YOUR_GROUP:streamGenerateContent?alt=sse' \
-H "x-goog-api-key: $CUSTOMER_KEY" \
-H "Content-Type: application/json" \
-d '{"contents":[{"role":"user","parts":[{"text":"Hello"}]}],"generationConfig":{"maxOutputTokens":128}}'
客户端设置与支持范围
Codex、Claude Code、Gemini CLI 等工具需选用对应 HTTP 协议、自订接口地址与可用用途组名,并按所选上游模型设置适合的输出预算。本站提供这些 API 路径,不代表每个 CLI 版本的全部功能均已验证。
未指定输出预算时预设 4096 Token。预设用途组上限为 coding 128,000、fast 32,000、xcoffee 64,000 Token,管理员可调整;上游较低上限仍适用,这不是上下文长度。超出的请求预算会下调。Chat 使用 max_tokens 或 max_completion_tokens;Responses 使用 max_output_tokens;Anthropic 使用 max_tokens;Gemini 使用 generationConfig.maxOutputTokens。推理强度最高 medium,已明确选用的较低强度保留;数值型思考预算另受设置上限保护,未激活推理时不添加参数。上游未提供可控参数的预设推理行为仍由上游管理。输出包含上游回报的推理 Token,不重复加计。
请由客户端发送完整对话历史。Responses 强制 store:false,不开放 previous_response_id、保存式会话、背景运行和共用上游文件引用;客户端携带的加密推理项目可透传。网页搜索只支持 Responses(Codex 的 web_search)与 Anthropic(Claude Code 的 web_search_*)。闸道回报的每次搜索另扣 1 积分,每个 UTC 日最多 50 次。Chat 的 web_search_options 与 Gemini 的 googleSearch、googleSearchRetrieval 会在转发前移除,其余请求保留。Gemini 保存式缓存与远程文件引用、Anthropic 服务器托管容器/MCP、web_fetch、程序运行、文件上传接口、图片生成与 WebSocket 不在本次接口范围。内嵌内容是否可用仍取决于上游模型。
共用用量与限制
所有 Key、协议与用途组共用帐号每日积分、滚动小时积分、请求频率与并发。每日与滚动小时积分以用户中心显示的现行配额为准。每日 UTC 00:00 重置,未用完不累积;每日与滚动小时配额依所购套餐分别设置,不按当天剩余积分计算。跨日请求计入开始调用的 UTC 日期。换日不重置滚动小时用量;暂停、删除或重设 Key 都不会清空用量或延长月卡。
并行、每分钟及各滚动时间窗的请求或 Token 限制依所购套餐而异,以购买时确认的套餐与用户中心已生效的权益为准。所有 Key 共用限制,串流结束才释放名额。采加权请求的套餐按总输入(含缓存)计权:不超过 32,000 Token 为 1,超过为 2,超过 80,000 为 4。请求前先预扣输入及输出预算,回报用量后结算;历史不补扣、不重算。
积分=(非缓存输入+缓存读取 × 缓存折算+输出 × 输出倍率)÷ 每积分计费 Token × 分组倍率,再加上 Responses 或 Anthropic 回报的每次网页搜索 1 积分。现行公式、配额与今日搜索次数请查看用户中心,各组倍率请查看首页模型组。缓存写入全价,缺少缓存数据时不折扣。Anthropic 的缓存读写会加入范式总输入;Gemini 缓存已含在提示词总量。思考用量计入输出一次。积分显示两位小数,内部以 10^-8 精度记帐。计数 Token 接口不扣积分,仍受请求与并发限制。搜索只计 Responses 与 Anthropic,上限为每帐号每个 UTC 日 50 次;开始时未达上限的请求可以略为超过。
POST /v1/messages/count_tokens 和 POST /v1beta/models/YOUR_GROUP:countTokens 须由管理员另行激活上游的原生 Token 计数能力。共用 Key 与用途组权限,消耗请求次数与并发名额,不扣生成 Tokens。计数结果为上游估算。
明确的生成前拒绝只计次数、不计 Tokens。流中断或缺少 usage 会保留保守估算,不作免费调用。请在用户中心查看剩余天数、今日总量与各 Key 用量。
同一用途组遇到明确的生成前拒绝(401/403/404/405/429)时,可尝试另一个已配置上游,每次最多尝试三个不同目标,共用一次额度预留与帐本。网络错误、5xx、客户端取消及已开始回应的请求不会自动重放;Magpie 自己的模型组路由须另外设置。
出错时
401 请检查 Key 与月卡状态;403 检查用途组权限;429 表示帐号或上游限额;502/503/504 请检查上游可用性、协议兼容性或超时。已收到部分输出后盲目重试,可能再次消耗用量。
在 用户中心 的支持入口提交时间与请求 ID,勿提交 Key 或完整敏感提示词。
官方文档与更新日期
本页于 2026-11-07 核对客户端官方配置文档;XCoffee 的组名、协议及额度以 API 控制台为准。