---
title: "五分钟快速接入 · AGI Plan"
url: https://agiplan.dev/docs
description: "选择你的系统和正在使用的工具，按步骤操作即可。每一步都写明了文件位置、要粘贴的内容和成功的标志，无需登录即可阅读。"
language: zh-Hans
markdown: https://agiplan.dev/docs.md
---

[← 回首页](https://agiplan.dev/)

接入文档

# 五分钟快速接入

选择你的系统和正在使用的工具，按步骤操作即可。每一步都写明了文件位置、要粘贴的内容和成功的标志，无需登录即可阅读。

**最后更新**

2026-10-17

## 照着做：选系统，选工具

下面每一步都可以直接复制粘贴。一键配置还在做，现在需要你手动改一次配置——按顺序做，十分钟以内。

你的电脑是

你要用的工具

Anthropic 出的命令行编程助手。**不需要 Claude 账号**，改完配置直接用我们的额度，模型由 Prism 自动挑。

把你的密钥粘贴到这里，下面所有命令会自动填好（可选）密钥只在这个网页里用来替换下面的占位文字，不保存、不上传，关掉页面就没了。不粘也可以，复制后自己把占位文字换掉。

1. ### 第 1：准备：拿到一把密钥

   登录控制台，先选一个档位，再到「密钥」页点「新建」。**密钥只显示一次**，马上复制下来，粘到本页上面的输入框里。然后打开 **PowerShell**：按键盘上的 Windows 键，输入 `PowerShell`，回车。下面所有命令都粘贴到这个窗口里（右键就是粘贴），按回车运行。
2. ### 第 2：安装 Claude Code

   已经装过的跳过这一步。没装过的，复制下面这行粘进去回车，等它跑完。

   PowerShell

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

   成功的样子：跑完后输入 `claude --version` 回车，能看到一个版本号。提示「找不到命令」的话，**关掉窗口重新打开一个**再试——新装的程序要新窗口才认得。
3. ### 第 3：把配置写进去

   复制下面整段（点右上角「复制」），粘进去回车。它会写好 `%USERPROFILE%\.claude\settings.json`；这个文件原来就有的话，旧的会先备份成同名的 `.bak`。里面的 `auto` 表示交给 Prism 按任务难度挑模型。最后一行关掉了 Claude Code 的几个实验功能——别家模型不认这些参数，开着会报 400。

   PowerShell

   这段里有密钥占位。先在页面上方粘贴密钥再复制，或者复制后自己把「在这里换成你的密钥」换掉。

   ```
   New-Item -ItemType Directory -Force "$HOME\.claude" | Out-Null
   if (Test-Path "$HOME\.claude\settings.json") { Copy-Item "$HOME\.claude\settings.json" "$HOME\.claude\settings.json.bak" -Force }
   [IO.File]::WriteAllText("$HOME\.claude\settings.json", @'
   {
     "env": {
       "ANTHROPIC_BASE_URL": "https://agiplan.dev",
       "ANTHROPIC_AUTH_TOKEN": "ap_live_在这里换成你的密钥",
       "ANTHROPIC_MODEL": "auto",
       "ANTHROPIC_DEFAULT_OPUS_MODEL": "auto",
       "ANTHROPIC_DEFAULT_SONNET_MODEL": "auto",
       "ANTHROPIC_DEFAULT_HAIKU_MODEL": "auto",
       "CLAUDE_CODE_SUBAGENT_MODEL": "auto",
       "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
     }
   }
   '@)
   ```

   **不想用命令？手动建这个文件**

   先跑第一段命令，它会用记事本打开 `%USERPROFILE%\.claude\settings.json`（问你要不要新建，点「是」）。再把第二段内容原样粘进记事本，`Ctrl + S` 保存。**别用「另存为」**，记事本会偷偷加上 `.txt`。

   PowerShell

   ```
   New-Item -ItemType Directory -Force "$HOME\.claude" | Out-Null
   notepad "$HOME\.claude\settings.json"
   ```

   %USERPROFILE%\.claude\settings.json

   这段里有密钥占位。先在页面上方粘贴密钥再复制，或者复制后自己把「在这里换成你的密钥」换掉。

   ```
   {
     "env": {
       "ANTHROPIC_BASE_URL": "https://agiplan.dev",
       "ANTHROPIC_AUTH_TOKEN": "ap_live_在这里换成你的密钥",
       "ANTHROPIC_MODEL": "auto",
       "ANTHROPIC_DEFAULT_OPUS_MODEL": "auto",
       "ANTHROPIC_DEFAULT_SONNET_MODEL": "auto",
       "ANTHROPIC_DEFAULT_HAIKU_MODEL": "auto",
       "CLAUDE_CODE_SUBAGENT_MODEL": "auto",
       "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
     }
   }
   ```
4. ### 第 4：打开它，说句话试试

   **先进到你的项目文件夹**（比如 `cd 你的项目路径`），再输入 `claude` 回车。第一次会问你信不信任这个文件夹，选「是」。然后随便说一句话。

   PowerShell

   ```
   claude
   ```

   **报错了？先确认密钥和网络是好的**

   粘贴下面这行回车。返回一串带 `"id"` 的模型列表，说明密钥和网络都没问题，是工具配置哪里没写对——回到上一步重新粘一次。返回 `401` 是密钥不对或已删除；什么都不返回或连不上，是网络问题。

   PowerShell

   这段里有密钥占位。先在页面上方粘贴密钥再复制，或者复制后自己把「在这里换成你的密钥」换掉。

   ```
   curl.exe -s https://agiplan.dev/v1/models -H "Authorization: Bearer ap_live_在这里换成你的密钥"
   ```

   成功的样子：它正常回答你。输入 `/status` 回车，能看到 `Anthropic base URL` 一行是我们的地址——这说明它用的是我们，不是官方账号。

### 不灵的话

- **一打开就让你选登录方式？** 先输入 `claude update` 升级到最新版——老版本会无视配置文件、卡在首次欢迎页。升级后还这样，说明配置文件没写对位置，回到「写配置」整段重跑一次。
- **报 401：** 密钥抄错了，或者被你在控制台删了。回到「写配置」那一步，在上面输入框里重新粘一次密钥，再整段复制运行。
- **报 404：** 你手动改过地址，结尾多了 `/v1`。Claude Code 的地址**不带** `/v1`。
- **用的是 VS Code 里的 Claude Code 插件？** 插件不读这个文件的登录状态。在 VS Code 设置（JSON）里加 `claudeCode.environmentVariables`，把上面配置里的 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN` 两项照抄进去。
- **以前在**`.bashrc` / `.zshrc` 或系统环境变量里设过 `ANTHROPIC_` 开头的变量？**删掉它们，免得和这个文件打架。**
- **别把模型名写成**`xxx[1m]` 去开百万上下文。**超过 400K 的上下文在上游更容易被限流和中途断掉，也贵得多；让它在 200K 左右自动压缩，长任务反而更稳。**

照着做了还是不行？在控制台「支持」里提一张工单，**把你选的系统、工具和报错原文贴进去**（别贴密钥），中文人工回复。

## 自己写代码：只要两样东西

上面的向导是给现成工具用的。自己写程序、或者用官方 SDK 的话，只需要**接口地址**和**密钥**两样东西，其余照你熟悉的那套 SDK 写。

改两样：把接口地址指到我们这里，把密钥换成你的。程序其余部分一个字不用动。

```
# OpenAI 格式的 SDK 填这个（带 /v1）
https://agiplan.dev/v1

# Anthropic 格式的 SDK 填这个（不带 /v1，SDK 会自己拼）
https://agiplan.dev
```

先用一条 curl 确认地址和密钥都对。返回一串模型列表就是通了；`401` 是密钥不对，连不上是地址抄错了。

```
curl -s https://agiplan.dev/v1/models -H "Authorization: Bearer ap_live_你的密钥"
```

**关于 `/setup` 脚本。** 以前首页推荐过 `curl …/setup | sh`，它只是把这两样写进 `~/.config/agiplan/env`（文件权限 600），同一个文件里还会导出 `OPENAI_BASE_URL` / `OPENAI_API_KEY`——加载之后，认这两个名字的程序都会走我们这里。Claude Code、Codex、OpenCode 都不读这个文件，跑完还得自己改工具的配置——所以我们不再推荐它，接工具请直接照上面的向导做。脚本还在（浏览器打开 https://agiplan.dev/setup 就能读全文），自己写代码时想用它管环境变量也可以。

## 认证

所有 `/v1/*` 端点都用 Bearer token；`/v1/messages` 另外认 Anthropic SDK 发的 `x-api-key` 头，**其他端点只认 `Authorization: Bearer`**。密钥在控制台创建，**明文只显示一次**。我们只存储哈希值，密钥无法找回，只能轮换。

```
Authorization: Bearer ap_live_xxxxxxxxxxxx
```

密钥可以设作用域、绑定到自定义模型、限制 IP、设过期时间。轮换时旧密钥可以保留一段宽限期，不会被立即切断。

每把密钥还有一个**调度偏好**（创建时选、随时可改）：自动（默认，按请求类型权衡）、速度优先（首字尽量快，单价可能稍高）、成本优先（响应更慢换更低单价——同一个模型挂多条线路时，CU 按实际服务那条线路的价计）、缓存优先（同一段对话尽量固定线路，减少缓存重写）。偏好只影响线路取舍，不影响熔断与灾备。

**登录控制台**和调用接口是两回事：接口只认密钥，控制台用邮箱验证码登录，也可以在 [账户与安全](https://agiplan.dev/app/account) 里添加**通行密钥**（指纹、面容或手机解锁），之后在登录页点一下邮箱框就能直接进。邮箱验证码一直可用；添加或删除通行密钥前要先确认是你本人，每次增删都会给你发一封通知邮件。

## 兼容哪几套协议

同一个 base URL 下同时提供三套主流协议的兼容端点。用哪套取决于你的 SDK，不需要告诉我们。

三扇门进的是同一间屋子：不管你的 SDK 说哪种话，后面是同一把密钥、同一份额度、同一批模型。

| 端点 | 对应协议 | 说明 |
| --- | --- | --- |
| /v1/chat/completions | OpenAI 风格 | 含 stream、tools、response_format |
| /v1/messages | Anthropic 风格 | 含 stream、tools、system |
| /v1/responses | OpenAI Responses | 含 stream、tools、`reasoning`；Codex 的 `custom_tool_call` / `compaction` / 加密推理原样透传；`previous_response_id` 可以不重传上下文。**在 Codex 里点名 Claude 就是跑 Claude**：`apply_patch` 和 namespace 工具会自动转换，联网搜索这类 OpenAI 托管工具在 Claude 上不可用。只有历史里有 Claude 接不了的条目（`compaction` 压缩过的历史、`web_search_call` 联网搜索结果、`local_shell_call`）时才换成同能力的 GPT，响应头 `x-agiplan-model-actual` 和调用记录里会写明是哪一条 |
| /v1/models | 三者通用 | 返回你此刻能填进 `model` 的名字：`auto`、`auto-fast`、所有可点名的模型真名，以及生图、视频、语音模型。你自己建的自定义模型不在里面，在控制台「自定义模型」里看 |
| /v1/quota | 三者通用 | 不发起调用就能读三个窗口的剩余比例，需要 usage:read |
| /v1/images/{generations,edits} | OpenAI 风格 | 生图 / 改图，按张计费，见[高级用法](https://agiplan.dev/docs/advanced#images) |
| /v1/videos | 异步任务 | 提交视频任务、轮询、取片，按秒计费，见[高级用法](https://agiplan.dev/docs/advanced#videos) |
| /v1/assets | 本站扩展 | 素材库：参考图和参考音频上传一次、反复引用，见[高级用法](https://agiplan.dev/docs/advanced#assets) |
| /v1/media/{id} | 本站扩展 | 生成结果的链接，不需要密钥，保存 7 天，见[高级用法](https://agiplan.dev/docs/advanced#media-links) |

**任何允许修改接口地址的工具都可以直接使用**，无需安装插件或修改业务代码。各协议请求体的差异由网关内部处理，按你熟悉的协议编写即可。

`/v1/responses` 是三者里唯一有状态的：**每次调用（不论带不带 `previous_response_id`），这一轮的输入和输出都会存在我们这边，最长 5 小时**，好让你下一轮用 `previous_response_id` 续接；到期由定时任务删除。不希望产生这项存储，请改用 `/v1/chat/completions` 或 `/v1/messages`。隐私政策中有相同说明。

还有几个端点没列在上面：`/v1/device/code`、`/v1/device/token`、`/v1/keys/current` 是命令行工具的传输层（`agiplan login` / `agiplan use` 用），不是给你直接调的。`/v1/traces/{追踪号}` 见下面的溯源一节。

**发图片只支持内嵌的 `data:` URL（base64），远程 `http(s)` 图片链接还没有做。** 远程链接目前会被替换为一句文本占位。**替换时响应头中会带 `x-agiplan-dropped-params: content[].image_url`**，以免你误以为模型已经看过那张图。音频和文件类型同理，当前直接丢弃并在同一个头里列出。

**要控制细节**（请求头与响应头、严格输出上限、能力标记、生图与视频接口的全部参数、计费口径）请看 [高级用法与 API 参考](https://agiplan.dev/docs/advanced)。

## 指定模型，或交给 Prism

同一个 `model` 字段几种用法：填**模型真名**就固定用这个模型——它挂着的几条线路之间自动灾备，但不会换成别的模型；填**能力组名**就在这一组同能力的模型之间调度和灾备；填 `auto` 或你自己的自定义模型名就交给 Prism 按任务难度动态调度；填 `auto-fast` 是**速度优先、其次成本**——和 `auto` 同一套规则与灾备，先按难度定出至少要哪一档，再在不低于这一档的组里挑此刻最快的（首字等待加吐字速度），快慢相差 20% 以内的挑便宜的，按所选那一组的价计费。

```
"model": "glm-5.3"         // 模型真名：固定用这一个模型（同模型多条线路间灾备），Prism 不介入
"model": "domestic"        // 能力组名：在这一组同能力的模型之间调度、自动灾备
"model": "auto"            // 交给 Prism 自动挑
"model": "auto-fast"       // 速度优先、其次成本（质量不低于 auto 那一档）
"model": "my-coding-model" // 你自己建的自定义模型
```

同一个字段，三种意思。不知道填什么就填 auto。

上面的 `glm-5.3` 只是举例，**能填的模型真名以 `GET /v1/models` 返回的为准**（控制台「模型与价格」是同一份清单）。能力组名有 `frontier`、`balanced`、`domestic`、`fast` 四个。旧文档里出现过的 `frontier-a`、`domestic-a` 这类名字是能力组的别名，效果等同于填组名，**不是固定某一个模型**，`/v1/models` 里也查不到它们。

想在单次请求里覆盖难度判断，加一个请求头即可：`X-AGIPlan-Difficulty: 0.9`。各组系数见 /models 页。

## 流式

三套协议的流式都按各自的原生格式返回 SSE，行为与你熟悉的一致。需要注意的只有一点：**计费在流结束时结算**。

一次流式调用的时间线。预扣发生在最前面，结算发生在最后面；中间断了也走同一个结算。

请求进来时我们先预扣一笔额度：**输入按请求里已经能数出来的 token 算**，输出按你声明的 `max_tokens` 算，但最多按 16k 算。流正常结束、客户端中断、模型服务报错都走同一个收尾逻辑，用真实用量回填、多退少补，所以中途断开不会被按最坏情况扣钱。实际输出超过预扣的部分照实计入，窗口用量因此可能略超上限：**所有进行中的请求加起来最多超出 5 小时窗口额度的 10%**。为保证这一点，`max_tokens` 超过 16k 时，发给模型的上限可能被调低。超出后窗口剩余显示为 0，新请求要等窗口重置。窗口快用完、剩下的装不下 16k 输出时，只要还装得下输入加 4k 输出，请求照样放行，输出按剩余量预扣，发给模型的上限也跟着调低；连这个都装不下才返回 429。

## 配额响应怎么读

三套文本协议端点的每个响应都带三个窗口的**剩余比例**和重置时间（生图、视频端点不带，见[高级用法](https://agiplan.dev/docs/advanced#response-headers)）。绝对用量见控制台的用量明细或月度对账单。触发限流时返回 429，并明确告诉你是哪个窗口满了、什么时候恢复——**429 响应同样带这三个头**。密钥无效（401）时不带这几个头，因为此时无法确定对应的账户。

三个窗口同时计数，每次调用同时记进三个。5 小时窗口最容易让人困惑：它不是固定时段，而是从你一段时间里的第一次调用起算，满 5 小时清零重来——所以歇了 5 小时以上再回来，它总是满的。Max 档不设 5 小时窗口，只受周和计费月约束。

```
X-AGIPlan-Quota-Session: remaining=68%; resets=2026-08-15T09:00:00.000Z
X-AGIPlan-Quota-Week:    remaining=34%; resets=2026-08-18T00:00:00.000Z
X-AGIPlan-Quota-Month:   remaining=81%; resets=2026-09-05T00:00:00.000Z
Retry-After: 1740        // 秒，仅在 429 时出现：窗口挡住时是到重置的秒数，并发满时是 2
```

三个窗口的大小跟着订阅档位走。换档在控制台的「套餐」面板里做，升档可以选两种时机：**现在**——按剩余天数补差价，新额度立即生效；**下期起**——本期额度和价格都不动、不补不退，到期按所选档位当时的价格续费，新额度从下一期开始。**降档只能下期起**：本期照常用原档、不退差价。账单页写着下一次续哪一档、扣多少。

## 错误码与重试

先看状态码决定要不要重试，再看下表里的 code 决定具体做什么。

| 状态码 | 错误码 | 含义 | 该怎么做 |
| --- | --- | --- | --- |
| 401 | invalid_api_key | 密钥无效或已吊销 | 换一个密钥，不要重试 |
| 404 | model_not_found | 生图端点：没有这个生图模型 | 看 /v1/models 里 kind 为 image 的那些 |
| 410 | model_retired | 点名的模型已下架。错误信息里写了下架日期和建议改用的模型 | **重试不会改变结果。** 把 model 改成错误信息里给的替代（例如 auto-fast），控制台「模型与价格」页底下也列着已下架的模型 |
| 503 | size_unavailable | 生图端点：此刻没有线路支持这个尺寸 | 换个尺寸，或稍后重试。失败的调用不计费 |
| 400 | quality_unavailable | 生图端点：这个模型能出这个尺寸的线路都不认你传的 `quality` | **重试不会改变结果。** 改用错误信息里列出的取值，或传 `auto` |
| 404 | unknown_model | `model` 既不是模型真名、能力组名，也不是你的自定义模型 | 查 `GET /v1/models`，或先在控制台「自定义模型」里建一个 |
| 404 | session_expired | `/v1/responses`：`previous_response_id` 指向的会话已超过 5 小时保留期 | 不带 `previous_response_id`、把上下文完整重发 |
| 404 | session_not_found | `/v1/responses`：找不到这个 `previous_response_id`，或它不属于你的账户 | 检查 id 是否来自同一账户的响应 |
| 404 | trace_expired | `/v1/traces/{id}`：追踪号超出 30 天保留期 | 链路已删除，无法再取 |
| 404 | trace_not_found | `/v1/traces/{id}`：找不到这个追踪号，或它不属于你的账户（密钥没有 `usage:read` 作用域时先返回 403 `insufficient_scope`，不会走到这里） | 检查追踪号和密钥 |
| 401 | key_rotation_required | 该密钥超过了组织设定的轮换周期 | 在控制台轮换密钥 |
| 400 | capability_unavailable | 请求声明的能力（视觉、工具…）当前没有任何模型支持。点名的模型不支持而别的模型支持时，网关会改走支持它的模型并在响应头和用量里标明，不会报这个错 | **重试不会改变结果。** 去掉这项要求，或等待支持该能力的模型接入 |
| 400 | context_too_small | 你按真名点名的那个模型，上下文窗口小于这次请求要求的 `min_context_k` | **重试不会改变结果。** 缩短上下文，或换一个窗口更大的模型——/models 上每个模型都标了窗口 |
| 400 | upstream_rejected_request | 模型服务拒绝了请求本身（参数或内容不被接受）；或者输入超出了每一条可用线路的上下文窗口（某条线装不下时网关会先换到装得下的线） | **换模型也无法解决。** 请检查请求（超长的话缩短上下文）；确认请求合法的话，把追踪号发给我们 |
| 400 | upstream_rejected | 生图 / 视频：模型服务拒绝了这次生成（提示词或参考素材不合规、尺寸或参数不被接受） | **换线路也无法解决。** 改一下提示词或尺寸再试；失败的调用不计费 |
| 400 | request_exceeds_mix_cap | 按最坏情况估算超过了你的自定义模型里设的 `max_cu_per_request` | **是你自己设的上限。** 调小 max_tokens、缩短上下文，或改高那个值 |
| 403 | insufficient_scope | 这把密钥没有对应作用域 | 换一把有权限的密钥 |
| 403 | plan_excludes_model | 你的定制套餐不包含这个模型或能力组 | 换一个套餐内的模型，或联系我们调整套餐 |
| 400 | strict_max_tokens_unavailable | 带了 `X-AGIPlan-Strict-Max-Tokens`，而能服务这次请求的线路都不保证遵守 `max_tokens` | **重试不会改变结果。** 去掉这个请求头（超出上限的部分按实际用量计费），或改用 `auto` / 别的能力组 |
| 403 | no_subscription | 这个账号没有生效中的订阅，也没开按量续用（或余额不足） | 去控制台订阅，或开启按量续用并充值 |
| 429 | quota_exceeded | 某个窗口的额度用尽 | 按 Retry-After 等待，或换到消耗更低的能力组。手里有这个窗口的额度重置时，报错里会写明，在控制台总览使用即可立即恢复 |
| 429 | concurrency_exceeded | 同时进行的请求达到档位上限 | 等待进行中的请求完成后再发送。**升档可以解决，充值不能**，这与额度用尽是两种情况 |
| 429 | upstream_busy | 能接这次请求的模型服务此刻都满了（对方限流或并发已满），网关已经等过一会儿空位仍没有 | 按 `Retry-After`（取模型服务给的最短等待，没给时 10 秒）后重试。不是你的额度或并发问题，失败的尝试不计费 |
| 429 | rate_limited | 同一来源请求得太频繁：命令行登录申请设备码、生成结果链接的签发都有次数上限 | 按 Retry-After 等待后再试。正常使用碰不到；脚本循环调用才会撞上 |
| 451 | region_not_available | 该能力组没有向你所在地提供的模型 | **重试不会改变结果。** 换一个能力组，或见 /models 的地域列。所在地选错了的，在控制台 [账户与安全](https://agiplan.dev/app/account#region) 改，立即生效 |
| 503 | no_supply_configured | 这个能力组当前没有可用的模型服务 | **重试不会改变结果。** 换一个能力组，或者用 auto——/models 页上标着每一组此刻有几条线在跑 |
| 503 | policy_unavailable | 你调用的自定义模型当前无法编译，通常是它固定使用的某个模型已下架 | 错误信息里写着是哪个池、哪个模型。去控制台「自定义模型」里把那个池改成别的模型或一个档位，保存后立刻生效 |
| 503 | model_unavailable | 你按真名点名的那个模型当前没有可用线路 | **网关不会替你更换模型。** 请稍后重试，或改用能力组的名字（例如 `domestic`），由网关在同能力的模型之间自动切换 |
| 503 | all_upstreams_failed | 该能力组的模型都试过了，均不可用 | 响应体里带完整尝试记录，可直接报障。失败的尝试不计费 |
| 流式中 | upstream_interrupted | 已经开始输出之后模型服务中断。此时状态码早已是 200，只能在流里发一个错误事件，**不会再有正常的结束标记** | **已经输出的部分按实际 token 计费；一个字都没输出就断的不计费。** 这时换模型会让回答前后不一致，所以网关不做灾备；请重新发起请求 |

**流式请求等得久时会先收到注释行。** 灾备换线、长提示词可能让首个事件晚到；等了 20 秒还没有时，网关先回 200 和流式响应头，之后每 15 秒发一行 SSE 注释 `: keepalive`（按 SSE 规范客户端忽略），免得客户端或中间代理因为长时间没有数据把连接掐掉。这种情况下如果最后失败，错误以流里的错误事件给出（码同上表），响应头里也不带额度和追踪号——追踪号在一行 `: trace tr_…` 注释里。

**5xx 不需要你自己重试。** 灾备已经在网关内部做完了——你看到 503 说明同能力组的模型都试过了。

**这张表列的是网关真的会返回的码。** 额度用尽时返回 429；启用按量续用后，请求会改为从余额扣费而不会被拒绝；余额不足时仍返回 429，错误信息会说明具体原因（未开启、已达上限或余额不足）。

**请按 `code` 判分支，不要按 `message`。** `code` 是稳定契约，改动会走公告；`message` 是给人读的一句话，措辞会变。**`message` 目前只有中文**，`code` 和 HTTP 状态码不受影响。

## 追踪号与溯源

**成功的响应**都带追踪号和实际调用的模型标识。发生过灾备切换时会额外标记出来。**被拒绝的响应没有追踪号**，因为这次调用没有生成用量记录。503 时链路直接放在响应体的 `attempts` 中，报告问题时请一并提供。

```
X-AGIPlan-Trace: tr_01J8FQ3M7X
X-AGIPlan-Model-Actual: deepseek-v4-pro
X-AGIPlan-Failover: true
```

报障只要给追踪号。你自己也能拿它查到这次调用走了哪条路。

使用你自己的密钥即可获取完整链路：`GET /v1/traces/{id}`，返回结构化 JSON，保留 30 天。报告问题时提供追踪号即可。

## 让 AI 代理读文档

让 Claude Code、Codex 这类代理替你接入时，把下面任一地址给它即可，它拿到的是去掉导航和脚本的 Markdown，数字和网页上同一份：

| 地址 | 内容 |
| --- | --- |
| https://agiplan.dev/llms.txt | 站点索引：接口地址、三套协议、每个公开页的 Markdown 链接 |
| https://agiplan.dev/llms-full.txt | 全部公开页的 Markdown 合成一份 |
| 任意公开页加 `.md` | 比如 `/docs.md`、`/pricing.md`、`/en/models.md`；首页是 `/index.md`、`/en.md` |
| 请求头 `Accept: text/markdown` | 同一个页面地址直接返回 Markdown |

## 命令行工具

**命令行工具目前还没有发布渠道**：不在 npm 上，也没有下载地址，运行 `agiplan` 会得到 command not found。下表标注的是各命令的实现状态，不是「你现在敲下去能不能跑」。

| 命令 | 作用 | 状态 |
| --- | --- | --- |
| agiplan login | 设备码授权：浏览器里确认，密钥直接送回终端 | 可用 |
| agiplan status | 三个窗口的剩余比例、档位与重置时间 | 可用 |
| agiplan models | 可用模型与能力组 | 可用 |
| agiplan use <名字> | 给当前密钥绑定自定义模型，--none 解绑 | 可用 |
| agiplan env | 输出可 eval 的环境变量 | 可用 |
| agiplan keys rotate <配置> | 轮换密钥 | 不做，见下 |
| agiplan uninstall | 删掉 setup 写的配置文件（--yes 才真删） | 可用 |

**出于安全考虑，不提供 `keys rotate`。** 如果密钥能为自己签发新密钥，泄露后攻击者可以先轮换一次，你吊销旧密钥后新密钥仍然有效。轮换只能通过浏览器确认：在控制台点击轮换，或重新运行 `agiplan login`。

支持项目级配置文件 `.agiplan`，里面**只存配置名不存密钥**，所以进 git 也安全。

## 从其他服务迁移

如果你已经在用官方 SDK 或别的聚合服务，需要改的只有两处：接口地址和密钥。模型名如果不一致，用自定义模型名做一层映射即可，无需修改业务代码。

**有两处行为与官方不同。** 一是不传 `max_tokens` 时我们会补一个 4096 并发给模型，因此长回答可能在 4096 处截断，并带有 `finish_reason: "length"`；补了的时候响应头里有 `x-agiplan-max-tokens-default: 4096`。二是 `max_tokens` 超过 16k 时，或者窗口快用完时，发给模型的上限可能被调低，用来限制单次超出额度的量（见上文「流式」一节）。被调低时，调用链路里会记下调整前后的值。

**GLM 系列会思考，思考的 token 算在 `max_tokens` 里。** 预算给小了，正文一个字都没有、`finish_reason: "length"`，照常计费。用 `auto` 时我们替你避开：没要思考又只给了不到 1024 的预算，不会落到 GLM。点名 GLM 的话请把 `max_tokens` 留得比平时宽（不低于 1024）；要显式开思考，带 `thinking: { "type": "enabled", "budget_tokens": 2048 }`，两种格式都认。

**还有一处会影响账单：请求需要某项能力、而你指定的能力组给不了时，我们会把它抬到能给的那一组，并按抬到的那一组计费。** 最常见的是发图：自定义模型里选了「快速响应组」，而那一组没有视觉模型，于是这次调用落到国产旗舰组，按该组更高的系数计费。调整只会向上，不会静默降级。**文本端点的每次响应都带 `x-agiplan-billed-group`，写的就是实际计费的那一组**，和用量明细里的记录一致。如果不希望被抬到更高的组，请不要在该自定义模型中发送它不支持的内容，或直接选择支持该能力的组。

- 先建一个自定义模型，把你原来用的模型名当它的名字，路由到对应的能力组。
- 改 base URL 和 key，跑一遍你的测试。
- 对照 /models 页确认系数，用控制台的用量明细核对第一天的账。

## JMRAI 老站余额迁移

老站（jmrai.net）用户可以自助迁移余额：在 jmrai.net 登录老站账号，获取迁移链接，回到本页确认即可。金额以老站关停时点的冻结快照核定，一个老站账号只能绑定一个本站账号，绑定后不可更改。

迁移所得计入**赠送余额**：自到账起 90 天有效，可用于按量付费（不能用于购买或续费套餐），不可提现、不可退款、不可开票。完成任意一笔付费后，另获老站累计充值（含已迁移额度）5% 的补偿，7 天确认期后自动到账，同样 90 天有效。

- 迁移入口：jmrai.net（老站账号密码或微信验证码登录）。
- 迁移窗口至 2027-10-12 自动关闭，逾期未办理视为放弃。
- 金额或资格有异议，凭老站订单记录在控制台提交工单复核。

文档有遗漏或不清楚的地方，请发邮件到 support@agiplan.dev 或在控制台提交工单。