# aicentos 文档

> aicentos 是面向开发者与企业的 AI API 中转聚合平台。一个 API Key 统一调用 OpenAI、Anthropic、Google、xAI 等主流大模型，上游为自建官方账号池、直连厂商官方 API，多账号兜底自动故障转移，可用率实时公开，支持对公合同与私有化部署。

本文汇总中文文档，每篇附原页面地址。

[文档目录](https://docs.aicentos.com/llms.txt)

# 关于我们

来源: https://docs.aicentos.com/about

Language: zh-CN

> aicentos 是什么、提供哪些能力、文档如何使用与许可、怎么联系我们

## aicentos 是什么

**aicentos 是面向开发者与企业的 AI API 中转聚合平台。** 用一组 API Key 统一调用 OpenAI、Anthropic、Google、xAI、DeepSeek、阿里通义、智谱、Moonshot、MiniMax 等厂商的大模型，兼容 OpenAI、Anthropic、Gemini 三种主流协议，适合需要统一计费、额度管控与使用审计的场景。

完整的产品介绍见 [aicentos 介绍](https://docs.aicentos.com/introduction)。

## 我们提供什么

* **统一接入**：一个 Base URL、一组 Key，切换模型只改 `model` 参数
* **协议兼容**：OpenAI 兼容、Anthropic 原生、Gemini 原生三种格式
* **上游冗余**：自建官方账号池，直连厂商官方 API，多账号兜底、失败自动重试与恢复，见[上游冗余与可用性](https://docs.aicentos.com/enterprise/pool-verification)
* **公开可用率**：[状态监控](https://docs.aicentos.com/status)公开每个在测模型的 1 小时 / 24 小时 / 7 天可用率、响应延迟与端点 PING
* **密钥治理**：额度上限、模型白名单、IP 白名单、有效期与即时吊销
* **计费透明**：人民币预充值 + 按量计费，余额永不过期，官方参考价逐项列示于[官方定价参考](https://docs.aicentos.com/billing/official-pricing)
* **企业合作**：合同、对公转账、发票，以及把网关部署到你自有环境的[私有化部署](https://docs.aicentos.com/enterprise/deployment)
* **开箱即用的教程**：69 款 AI 编码工具与聊天客户端的图文配置教程，见[客户端接入](https://docs.aicentos.com/clients/claude-code)

## 我们明确不承诺什么

把边界写出来，比把形容词堆满更有用：

* **不提供“原厂鉴定”**：上游是自建官方账号池、全部直连厂商官方 API，但转发型网关无法向调用方出具来源证明——响应里没有可验证的水印，任何中转层在技术上都无法做到，这是能力边界而不是直连与否的问题
* **不是端到端加密**：转发型网关需要在上游还原请求原文，真实做到的是传输链路加密 + 存储侧数据范围最小化
* **不承诺 7×24 专属人工值守**：通过邮箱在工作时段响应，不提供电话支持
* **不替调用方承担内容合规责任**：请求与生成内容的合规性由调用方负责

完整的服务边界见[服务模式与能力边界](https://docs.aicentos.com/enterprise/overview)。

## 文档的许可与使用

本站文档采用 **CC BY 4.0** 许可协议：允许转载、改编与商用，保留署名即可。

面向 AI 与机器阅读的资源：

* [llms.txt](https://docs.aicentos.com/llms.txt) / [llms-full.txt](https://docs.aicentos.com/llms-full.txt)：文档索引与全文
* 每篇文档都有对应的 Markdown 副本，页面上的「复制 Markdown」可直接取用
* 支持 `Accept: text/markdown` 内容协商

## 联系与支持

| 场景         | 入口                                                   |
| ---------- | ---------------------------------------------------- |
| 故障、账号与一般咨询 | 邮箱 [aicentos@88.cn](mailto:aicentos@88.cn)           |
| 即时沟通       | 页面左下角「客服」悬浮按钮，扫码或搜索微信号 `dext7r`                      |
| 对公合作、合同与结算 | 邮箱沟通，按工作时段回复                                         |
| 服务是否异常     | 先查[状态监控](https://docs.aicentos.com/status)，多数问题当场有答案 |

完整说明见[服务与支持](https://docs.aicentos.com/enterprise/support)。

## 数据与隐私

正文不写日志、密钥以指纹记录、私有化部署下数据全部留在你的边界内。详见[数据与隐私](https://docs.aicentos.com/faq/data-privacy)与[数据安全与合规](https://docs.aicentos.com/enterprise/security-compliance)。

---

# 原生 Claude 格式

来源: https://docs.aicentos.com/api/chat/claude

Language: zh-CN

> Claude 原生格式的消息接口：端点、鉴权与请求示例

Anthropic Messages 格式的对话接口。

`POST /v1/messages`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## 请求

`Content-Type: application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 256,
    "messages": [
      { "role": "user", "content": "用一句话介绍你自己" }
    ]
  }'
```

参数与 Anthropic 官方一致，`max_tokens` 必填。

## 响应

回复内容取 `content[0].text`，用量在 `usage`（`input_tokens` / `output_tokens`）：

```json
{
  "id": "string",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "string" }
  ],
  "model": "string",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 0, "output_tokens": 0 }
}
```

鉴权失败时返回 `invalid_api_key` 错误，排查方法见[错误处理](https://docs.aicentos.com/billing/errors)：

```json
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

---

# Gemini 文本聊天

来源: https://docs.aicentos.com/api/chat/gemini/text

Language: zh-CN

> Gemini 原生格式的文本生成接口：端点、鉴权与请求示例

Gemini 原生格式的文本生成接口。

`POST /v1beta/models/{model}:generateContent`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## Path 参数

| 参数    | 类型     | 说明                       |
| ----- | ------ | ------------------------ |
| model | string | 模型 ID，如 `gemini-2.0-pro` |

## 请求

`Content-Type: application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1beta/models/gemini-2.0-pro:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "用一句话介绍你自己" }]
      }
    ]
  }'
```

请求结构（`contents` / `parts`）与 Gemini 官方一致。

## 响应

回复取 `candidates[0].content.parts[0].text`，用量在 `usageMetadata`：

```json
{
  "candidates": [
    {
      "content": {},
      "finishReason": "string",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 0,
    "candidatesTokenCount": 0,
    "totalTokenCount": 0
  }
}
```

---

# ChatCompletions 格式

来源: https://docs.aicentos.com/api/chat/openai/chat-completions

Language: zh-CN

> OpenAI 兼容的对话补全接口：端点、鉴权与请求示例

OpenAI 兼容格式的对话补全接口。

`POST /v1/chat/completions`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## 请求

`Content-Type: application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "用一句话介绍你自己" }
    ]
  }'
```

除 `model` 与 `messages` 外，其余参数与 OpenAI 官方一致（`temperature`、`stream`、`tools` 等），原样传入即可。

## 响应

返回 OpenAI 标准结构，回复取 `choices[0].message.content`，用量在 `usage`：

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "我是 aicentos。" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 21, "completion_tokens": 9, "total_tokens": 30 }
}
```

鉴权失败时返回 `invalid_api_key` 错误，排查方法见[错误处理](https://docs.aicentos.com/billing/errors)：

```json
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

---

# Responses 格式

来源: https://docs.aicentos.com/api/chat/openai/responses

Language: zh-CN

> OpenAI Responses 风格的对话接口：端点、鉴权与调用示例

OpenAI Responses 风格的对话接口。

`POST /responses`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## 请求

`Content-Type: application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{
    "model": "gpt-5",
    "input": "用一句话介绍你自己"
  }'
```

`input` 可以直接传字符串，也可以传 OpenAI 官方的结构化消息数组，参数与官方一致。

## 响应

```json
{
  "id": "string",
  "object": "response",
  "status": "completed",
  "output": [],
  "usage": {}
}
```

鉴权失败时返回 `invalid_api_key` 错误，排查方法见[错误处理](https://docs.aicentos.com/billing/errors)：

```json
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

---

# Gemini 原生格式

来源: https://docs.aicentos.com/api/images/nano-banana/gemini

Language: zh-CN

> Nano Banana 2 的 Gemini 原生图像生成接口：端点与请求示例

Nano Banana 2 的 Gemini 原生格式接口。

`POST /v1beta/models/gemini-3-pro-image-preview:generateContent`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## 请求

`Content-Type: application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "一只穿宇航服的水豚漂浮在太空里" }]
      }
    ],
    "generationConfig": {
      "responseModalities": ["IMAGE"]
    }
  }'
```

`generationConfig.responseModalities` 设为 `IMAGE` 时返回图像。

## 响应

生成的图像在 `candidates[0].content.parts` 里，以 `inlineData`（base64）返回：

```json
{
  "candidates": [
    {
      "content": {
        "role": "string",
        "parts": [
          {
            "text": "string",
            "inlineData": {
              "mimeType": "string",
              "data": "string"
            }
          }
        ]
      },
      "finishReason": "string",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 0,
    "candidatesTokenCount": 0,
    "totalTokenCount": 0
  },
  "modelVersion": "string"
}
```

---

# 编辑图像

来源: https://docs.aicentos.com/api/images/openai/edits

Language: zh-CN

> OpenAI 兼容的图像编辑接口：端点、鉴权与请求示例

OpenAI 兼容格式的图像编辑接口，请求体为 `multipart/form-data`。

`POST /images/edits`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## 请求

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/images/edits" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -F "image=@photo.png" \
  -F "prompt=把背景换成夜晚的霓虹街头"
```

`image` 为要编辑的原图，`prompt` 描述编辑要求。

## 响应

`data` 数组返回编辑后的图像（`url` 或 `b64_json`）：

```json
{
  "created": 0,
  "background": "string",
  "output_format": "string",
  "size": "string",
  "data": [
    {
      "url": "string",
      "b64_json": "string"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}
```

---

# 生成图像

来源: https://docs.aicentos.com/api/images/openai/generations

Language: zh-CN

> OpenAI 兼容的图像生成接口：端点、鉴权与请求示例

OpenAI 兼容格式的图像生成接口。

`POST /images/generations`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## 请求

`Content-Type: application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A futuristic city skyline at sunset, neon lights, cinematic",
    "size": "1024x1024",
    "quality": "hd"
  }'
```

参数与 OpenAI 官方一致。

## 响应

`data` 数组返回生成结果（`url` 或 `b64_json`）：

```json
{
  "created": 0,
  "background": "string",
  "output_format": "string",
  "quality": "string",
  "size": "string",
  "data": [
    {
      "url": "string",
      "b64_json": "string",
      "revised_prompt": "string"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}
```

---

# 模型列表（Gemini 原生）

来源: https://docs.aicentos.com/api/models/gemini

Language: zh-CN

> Gemini 原生的模型列表接口：查询当前可用的模型

Gemini 原生格式的模型列表接口。

`GET /v1beta/models`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## 请求

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl "https://aicentos.com/v1beta/models" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

## 响应

```json
{
  "models": [
    {
      "name": "models/gemini-2.0-pro",
      "displayName": "string",
      "description": "string",
      "inputTokenLimit": 0,
      "outputTokenLimit": 0,
      "supportedGenerationMethods": [
        "string"
      ]
    }
  ]
}
```

---

# 模型列表（OpenAI 兼容）

来源: https://docs.aicentos.com/api/models/openai

Language: zh-CN

> OpenAI 兼容的模型列表接口：查询当前可用的模型

OpenAI 兼容格式的模型列表接口。

`GET /v1/models`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## 请求

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl "https://aicentos.com/v1/models" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

## 响应

```json
{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1715000000,
      "owned_by": "openai"
    }
  ]
}
```

鉴权失败时返回 `invalid_api_key` 错误，排查方法见[错误处理](https://docs.aicentos.com/billing/errors)：

```json
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

---

# Dreamina · 创建视频

来源: https://docs.aicentos.com/api/videos/dreamina/create

Language: zh-CN

> 提交即梦（Dreamina）视频生成任务，返回任务 ID 与初始状态

即梦（Dreamina）视频生成任务创建接口，与 Sora 共用同一个端点，通过 `model` 参数区分。

`POST /videos`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## 请求

`Content-Type: application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/videos" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "dj在打碟",
    "size": "1920x1080",
    "seconds": "8"
  }'
```

## 响应

返回任务 ID 与初始状态，进度用[任务查询](https://docs.aicentos.com/api/videos/dreamina/get-task)轮询：

```json
{
  "id": "string",
  "task_id": "string",
  "status": "queued"
}
```

---

# Dreamina · 获取视频任务状态

来源: https://docs.aicentos.com/api/videos/dreamina/get-task

Language: zh-CN

> 按任务 ID 查询即梦（Dreamina）视频生成进度与结果

按任务 ID 查询即梦视频生成进度与结果。

`GET /videos/{task_id}`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## Path 参数

| 参数       | 类型     | 说明            |
| -------- | ------ | ------------- |
| task\_id | string | 创建任务时返回的任务 ID |

## 请求

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl "https://aicentos.com/v1/videos/{task_id}" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

## 响应

`status` 为生成状态；完成后 `url` 给出视频地址，失败时 `error` 说明原因：

```json
{
  "id": "string",
  "task_id": "string",
  "status": "queued",
  "progress": 0,
  "url": "string",
  "error": "string"
}
```

---

# Sora · 创建视频

来源: https://docs.aicentos.com/api/videos/sora/create

Language: zh-CN

> 提交 Sora 视频生成任务，返回任务 ID 与初始状态，后续用任务 ID 查询进度

视频生成接口，OpenAI 兼容格式。同一个端点通过 `model` 参数区分视频模型。

`POST /videos`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## 请求

`Content-Type: application/json`

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl -X POST "https://aicentos.com/v1/videos" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "dj在打碟",
    "size": "1920x1080",
    "seconds": "8"
  }'
```

## 响应

返回任务 ID 与初始状态，进度用[任务查询](https://docs.aicentos.com/api/videos/sora/get-task)轮询：

```json
{
  "id": "string",
  "task_id": "string",
  "status": "queued"
}
```

---

# Sora · 获取视频内容

来源: https://docs.aicentos.com/api/videos/sora/get-content

Language: zh-CN

> 任务完成后按任务 ID 获取 Sora 生成的视频文件地址

任务完成后获取生成的视频文件地址。

`GET /videos/{task_id}/content`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## Path 参数

| 参数       | 类型     | 说明            |
| -------- | ------ | ------------- |
| task\_id | string | 创建任务时返回的任务 ID |

## 请求

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl "https://aicentos.com/v1/videos/{task_id}/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

## 响应

`url` 为视频文件地址，`expires_at` 是它的过期时间——拿到后尽快下载：

```json
{
  "url": "string",
  "expires_at": 0
}
```

---

# Sora · 获取视频任务状态

来源: https://docs.aicentos.com/api/videos/sora/get-task

Language: zh-CN

> 按任务 ID 查询 Sora 视频生成进度，获取状态与失败原因

按任务 ID 查询视频生成进度。

`GET /videos/{task_id}`

## 鉴权

Bearer Token：API Key 在控制台「令牌管理」获取，放在请求头 `Authorization`。

## Path 参数

| 参数       | 类型     | 说明            |
| -------- | ------ | ------------- |
| task\_id | string | 创建任务时返回的任务 ID |

## 请求

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"

curl "https://aicentos.com/v1/videos/{task_id}" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

## 响应

`status` 为生成状态；完成后 `url` 给出视频地址，失败时 `error` 说明原因：

```json
{
  "id": "string",
  "task_id": "string",
  "status": "queued",
  "progress": 0,
  "url": "string",
  "error": "string"
}
```

---

# 错误

来源: https://docs.aicentos.com/billing/errors

Language: zh-CN

> HTTP 状态码、错误响应结构、常见错误与解决方案

aicentos 完全沿用 **OpenAI 错误响应格式**。SDK 抛错时直接 catch 对应异常即可。

## 错误响应结构

所有错误响应都是这个格式：

```bash
{
  "error": {
    "message": "你的 API Key 没有访问 gpt-5 的权限",
    "type": "permission_denied",
    "code": "model_not_allowed",
    "param": "model"
  }
}
```

| 字段        | 含义             |
| --------- | -------------- |
| `message` | 人类可读的错误描述      |
| `type`    | 错误类别（见下表）      |
| `code`    | 细粒度错误码（用于程序判断） |
| `param`   | 出错的字段名（如果有）    |

## HTTP 状态码速查

| 状态码   | 类型                       | 常见原因                   |
| ----- | ------------------------ | ---------------------- |
| `400` | `invalid_request_error`  | 请求体格式错、参数非法、model 名拼错  |
| `401` | `authentication_error`   | API Key 缺失 / 错误 / 已被吊销 |
| `402` | `insufficient_quota`     | 余额不足                   |
| `403` | `permission_denied`      | Key 被禁用、模型未授权、IP 不在白名单 |
| `404` | `not_found`              | 接口路径错、模型 ID 错          |
| `408` | `request_timeout`        | 上游超时（通常 > 60s 无响应）     |
| `413` | `payload_too_large`      | 请求体过大（图像、文件）           |
| `415` | `unsupported_media_type` | Content-Type 不对        |
| `422` | `invalid_request_error`  | 请求体能解析但语义不对            |
| `429` | `rate_limit_exceeded`    | 触发限流，降低请求频率后重试         |
| `500` | `server_error`           | 平台内部错（罕见）              |
| `502` | `bad_gateway`            | 上游服务异常                 |
| `503` | `service_unavailable`    | 上游过载，建议稍后重试            |
| `504` | `gateway_timeout`        | 上游响应超时                 |

## 常见错误与解决

### 401 — Invalid API key

```bash
{ "error": { "message": "Incorrect API key provided", "type": "authentication_error" } }
```

**排查清单**：

* `Authorization` 头是不是 `Bearer sk-xxx` 格式（注意有空格）
* Key 是不是从控制台复制时带了空格 / 换行
* Key 是不是已删除 / 已禁用 / 已过期
* 是不是把测试 Key 提交进生产了

### 402 — Insufficient quota

```bash
{ "error": { "message": "Insufficient quota", "type": "insufficient_quota" } }
```

充值 → 控制台「钱包管理」。开启 [余额预警](https://docs.aicentos.com/billing/pricing#%E4%BD%99%E9%A2%9D%E9%A2%84%E8%AD%A6) 避免再发生。

### 403 — Model not allowed

```bash
{ "error": { "message": "Model gpt-5 not allowed for this key", "code": "model_not_allowed" } }
```

创建令牌时勾了「**可用模型**」白名单，请求的 model 不在里面。改令牌设置或换 Key。

### 404 — Model not found

```bash
{ "error": { "message": "The model 'gpt-4-turbo-2024-04-09' does not exist", "code": "model_not_found" } }
```

模型 ID 拼错或已下线。去[模型广场](https://aicentos.com/pricing)确认当前可用 ID。

### 429 — Rate limit exceeded

响应头 `Retry-After` 告诉你多少秒后重试。降低并发与请求频率即可恢复。

### 500 / 502 / 503 — 服务异常

通常是上游波动。**自动重试 2-3 次**通常能成功。如果持续 5 分钟以上：

* 查 [状态页](https://status.aicentos.com)（如有）
* 联系客服

### 408 / 504 — 超时

请求超过 60s 无响应。常见原因：

* prompt 太长，让模型"思考"超时
* 流式输出未启用（长响应建议加 `stream: true`）

**解决**：

* 缩短 prompt
* 开启流式：`{ "model": "...", "messages": [...], "stream": true }`
* 切到更快的模型（如从 `gpt-4o` 换 `gpt-4o-mini`）

## SDK 错误处理示例

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"
```

### Python

```python
import os
from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI(api_key=os.environ["AICENTOS_API_KEY"], base_url="https://aicentos.com/v1")

try:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "hi"}],
    )
except AuthenticationError:
    print("Key 错了")
except RateLimitError as e:
    print(f"被限流，{e.response.headers.get('Retry-After')}s 后重试")
except APIError as e:
    print(f"其他 API 错误：{e.status_code} {e.message}")
```

### Node.js

```js
import OpenAI, { APIError } from 'openai';

const client = new OpenAI({
  apiKey: process.env.AICENTOS_API_KEY,
  baseURL: 'https://aicentos.com/v1',
});

try {
  const resp = await client.chat.completions.create({ ... });
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status, err.code, err.message);
  }
}
```

## 重试与降级建议

| 错误类型                                  | 建议处理                    |
| ------------------------------------- | ----------------------- |
| `400` / `401` / `402` / `403` / `404` | **不重试**，代码 / 配置错，先排查    |
| `429`                                 | 按 `Retry-After` 重试，指数退避 |
| `500` / `502` / `503` / `504` / `408` | 立刻重试 1-3 次，间隔 1-5s      |

OpenAI 官方 SDK 默认有合理的重试策略，**生产代码直接用 SDK 不要自己 fetch**。

---

# 支持的模型

来源: https://docs.aicentos.com/billing/models-list

Language: zh-CN

> Google / xAI / OpenAI / Anthropic / 阿里 / DeepSeek / 智谱 / Moonshot / MiniMax 全系列模型清单

aicentos 已接入 OpenAI、Anthropic、Google、xAI、阿里通义、DeepSeek、智谱、Moonshot、MiniMax 等主流厂商的模型，覆盖聊天、推理、代码、图像、视频、嵌入等能力。

## 厂商与代表模型

厂商与在售模型会随上游上下架变化，实际数量以模型广场实时显示为准。下表只列代表性模型：

| 厂商        | 代表模型                                                  |
| --------- | ----------------------------------------------------- |
| Google    | `gemini-3.8-flash`、`gemini-3.1-pro`、`nano-banana-2`   |
| xAI       | `grok-4.7`、`grok-4.6`、`grok-build-0.1`                |
| OpenAI    | `gpt-5.6-sol`、`gpt-6-astra`、`gpt-image-2.5`           |
| Anthropic | `claude-opus-4-8`、`claude-opus-4-7`、`claude-sonnet-5` |
| 阿里通义      | `qwen3.8-max`、`qwen3-coder-plus`                      |
| DeepSeek  | `deepseek-v4-pro`、`deepseek-v4.1-flash`               |
| 智谱        | `glm-5.3`、`glm-5.2`                                   |
| Moonshot  | `kimi-k3`、`kimi-k2.6`                                 |
| MiniMax   | `minimax-m3`、`minimax-m2.7`                           |

完整的实时模型清单与定价以控制台为准：

模型广场

模型广场支持按**供应商**、**可用令牌分组**、**计费类型**、**标签**筛选，也能在卡片视图与表格视图之间切换。

[👉 打开模型定价页](https://aicentos.com/pricing)

## 用模型时填什么

`model` 字段填**模型 ID**（在模型定价页每个卡片上可一键复制）。常见示例：

| 你想用            | `model` 字段填        |
| -------------- | ------------------ |
| Claude Opus 最新 | `claude-opus-4-8`  |
| Claude Sonnet  | `claude-sonnet-5`  |
| Claude Haiku   | `claude-haiku-4-5` |
| GPT 旗舰         | `gpt-5.6-sol`      |
| GPT 图像         | `gpt-image-2.5`    |
| Gemini Pro     | `gemini-3.1-pro`   |
| Gemini Flash   | `gemini-3.8-flash` |
| Grok           | `grok-4.7`         |
| DeepSeek       | `deepseek-v4-pro`  |
| 通义千问           | `qwen3.8-max`      |
| 智谱 GLM         | `glm-5.3`          |
| Kimi           | `kimi-k3`          |
| MiniMax        | `minimax-m3`       |

## 查看模型实时可用性

各家上游模型会不定期维护或限流。接入前可以先看**模型健康面板**，确认目标模型的近期可用率与延迟：

[👉 查看模型状态监控](https://docs.aicentos.com/status)

面板每轮巡检记录每个模型的 1 小时 / 24 小时 / 7 天可用率、响应延迟与端点 PING，连续失败会自动标记。

## 限制可用模型

如果你想让某个密钥只能调特定几个模型，在创建 **API 密钥**时勾选「**可用模型**」做白名单。比如对外提供的 demo Key 只放开 `claude-haiku-4-5` 和 `gemini-3.8-flash`。

## 没有找到想要的模型？

上游厂商发布新模型后我们会陆续适配。如果你需要的模型还没上线，可以通过控制台的联系方式告诉我们，或关注 [X / Twitter](https://x.com/aicentos) 的更新通知。

---

# 官方定价参考

来源: https://docs.aicentos.com/billing/official-pricing

Language: zh-CN

> aicentos 已接入的全部模型，对应 OpenAI / Anthropic / Google 官方 API 定价

下表列出 **aicentos 已接入的全部模型**，价格为各厂商官网公布的**官方 API 定价**（截至 2026 年 5 月）。

* 单位：**美元 / 每 1M tokens**（图像、语音、视频单独标注）。
* “缓存读取”为命中缓存时的输入价；Anthropic 另有缓存写入价（标准输入的 1.25×）。
* 同一基础模型的 `-thinking` / `-nothinking` / 日期版本 / `-high/-low/-medium` 等变体，**官方定价与基础模型一致**，已合并展示。

>

实际通过 aicentos 调用的价格远低于官方，以 [aicentos 定价页](https://docs.aicentos.com/billing/pricing) 和 [模型广场](https://aicentos.com/pricing) 实时显示为准。

## OpenAI

### GPT-5.x 系列

| 模型                                                                  | 官方输入   | 官方输出    | 缓存读取   |
| ------------------------------------------------------------------- | ------ | ------- | ------ |
| `gpt-5`、`gpt-5-codex`、`gpt-5-chat-latest`                           | $1.25  | $10.00  | $0.125 |
| `gpt-5-mini`                                                        | $0.25  | $2.00   | $0.025 |
| `gpt-5-nano`                                                        | $0.05  | $0.40   | $0.005 |
| `gpt-5-pro`                                                         | $15.00 | $120.00 | —      |
| `gpt-5.1`、`gpt-5.1-codex`、`gpt-5.1-codex-max`、`gpt-5.1-chat-latest` | $1.25  | $10.00  | $0.125 |
| `gpt-5.1-codex-mini`                                                | $0.25  | $2.00   | $0.025 |
| `gpt-5.2`、`gpt-5.2-codex`、`gpt-5.2-chat-latest`                     | $1.75  | $14.00  | $0.175 |
| `gpt-5.2-pro`                                                       | $21.00 | $168.00 | —      |
| `gpt-5.3-codex`、`gpt-5.3-chat-latest`                               | $1.75  | $14.00  | $0.175 |
| `gpt-5.4`                                                           | $2.50  | $15.00  | $0.25  |
| `gpt-5.4-mini`                                                      | $0.75  | $4.50   | —      |
| `gpt-5.4-nano`                                                      | $0.20  | $1.25   | —      |
| `gpt-5.4-pro`                                                       | $30.00 | $180.00 | —      |
| `gpt-5.5`                                                           | $5.00  | $30.00  | $0.50  |

>

GPT-5.x 上下文约 400K（5.4 / 5.5 旗舰更高）。`-codex` 为代码专用版、`-chat` 为对话版、`-pro` 为高算力版，官方定价同上表。

### GPT-4o 系列

| 模型                                               | 官方输入  | 官方输出   | 缓存读取   |
| ------------------------------------------------ | ----- | ------ | ------ |
| `gpt-4o`、`gpt-4o-2024-08-06`、`gpt-4o-2024-11-20` | $2.50 | $10.00 | $1.25  |
| `gpt-4o-2024-05-13`                              | $5.00 | $15.00 | —      |
| `chatgpt-4o-latest`                              | $5.00 | $15.00 | —      |
| `gpt-4o-mini`、`gpt-4o-mini-2024-07-18`           | $0.15 | $0.60  | $0.075 |
| `gpt-4o-search-preview`                          | $2.50 | $10.00 | —      |
| `gpt-4o-mini-search-preview`                     | $0.15 | $0.60  | —      |

>

上下文 128K。`-search-preview` 另按 $10 / 1000 次检索计搜索费。

### GPT-4.1 系列

| 模型                                       | 官方输入  | 官方输出  | 缓存读取   | 上下文 |
| ---------------------------------------- | ----- | ----- | ------ | --- |
| `gpt-4.1`、`gpt-4.1-2025-04-14`           | $2.00 | $8.00 | $0.50  | 1M  |
| `gpt-4.1-mini`、`gpt-4.1-mini-2025-04-14` | $0.40 | $1.60 | $0.10  | 1M  |
| `gpt-4.1-nano`、`gpt-4.1-nano-2025-04-14` | $0.10 | $0.40 | $0.025 | 1M  |

### GPT-4 / GPT-3.5（旧版）

| 模型                                                                                         | 官方输入   | 官方输出    | 上下文  |
| ------------------------------------------------------------------------------------------ | ------ | ------- | ---- |
| `gpt-4.5-preview`、`gpt-4.5-preview-2025-02-27`                                             | $75.00 | $150.00 | 128K |
| `gpt-4-turbo-2024-04-09`、`gpt-4-turbo-preview`、`gpt-4-0125-preview`、`gpt-4-vision-preview` | $10.00 | $30.00  | 128K |
| `gpt-4-0613`                                                                               | $30.00 | $60.00  | 8K   |
| `gpt-4-32k-0613`                                                                           | $60.00 | $120.00 | 32K  |
| `gpt-3.5-turbo`、`gpt-3.5-turbo-0125`                                                       | $0.50  | $1.50   | 16K  |
| `gpt-3.5-turbo-1106`                                                                       | $1.00  | $2.00   | 16K  |
| `gpt-3.5-turbo-instruct`                                                                   | $1.50  | $2.00   | 4K   |
| `gpt-3.5-turbo-16k`、`gpt-3.5-turbo-16k-0613`                                               | $3.00  | $4.00   | 16K  |
| `gpt-3.5-turbo-0613`                                                                       | $1.50  | $2.00   | 4K   |
| `babbage-002`                                                                              | $0.40  | $0.40   | 16K  |
| `davinci-002`                                                                              | $2.00  | $2.00   | 16K  |

>

`gpt-4.5-preview` 已被 OpenAI 标记弃用，仅作历史价参考。

### o 系列推理模型

| 模型                                                         | 官方输入    | 官方输出    | 缓存读取   | 上下文  |
| ---------------------------------------------------------- | ------- | ------- | ------ | ---- |
| `o1`、`o1-2024-12-17`、`o1-preview`、`o1-preview-2024-09-12`  | $15.00  | $60.00  | $7.50  | 200K |
| `o1-mini`、`o1-mini-2024-09-12`                             | $1.10   | $4.40   | $0.55  | 128K |
| `o1-pro`、`o1-pro-2025-03-19`                               | $150.00 | $600.00 | —      | 200K |
| `o3`                                                       | $2.00   | $8.00   | $0.50  | 200K |
| `o3-pro`、`o3-pro-2025-06-10`                               | $20.00  | $80.00  | —      | 200K |
| `o3-mini`、`o3-mini-2025-01-31`（含 `-high`/`-low`/`-medium`） | $1.10   | $4.40   | $0.55  | 200K |
| `o3-deep-research`                                         | $10.00  | $40.00  | $2.50  | 200K |
| `o4-mini`                                                  | $1.10   | $4.40   | $0.275 | 200K |
| `o4-mini-deep-research`、`o4-mini-deep-research-2025-06-26` | $2.00   | $8.00   | $0.50  | 200K |

### 图像 / 语音 / 实时

| 模型                                         | 官方价格                                       |
| ------------------------------------------ | ------------------------------------------ |
| `gpt-image-1`                              | 文本输入 $5 / 图像输入 $10 / 图像输出 $40（每 1M tokens） |
| `gpt-image-1.5`                            | 文本输入 $5 / 图像输出约 $30（每 1M tokens）           |
| `gpt-image-2`                              | 官方未公布，联系询价                                 |
| `dall-e-3`                                 | $0.040 / 张（1024×1024 标准），$0.080 / 张（HD）    |
| `dall-e-2`                                 | $0.016 \~ $0.020 / 张                       |
| `gpt-4o-realtime-preview`（及日期版）            | 文本 $5 / $20，音频输入 $40 / 音频输出 $80            |
| `gpt-4o-mini-realtime-preview`（及日期版）       | 文本 $0.60 / $2.40，音频输入 $10 / 输出 $20         |
| `gpt-realtime-2`、`gpt-realtime-2025-08-28` | 文本 $4 / $16 + 音频用量另计                       |
| `gpt-4o-audio-preview`（及日期版）               | 文本 $2.50 / $10，音频输入 $40 / 输出 $80           |
| `gpt-4o-mini-audio-preview`                | 文本 $0.15 / $0.60，音频输入 $10 / 输出 $20         |
| `gpt-4o-mini-tts`                          | 约 $0.015 / 分钟                              |

## Anthropic Claude

| 模型                                               | 官方输入   | 官方输出   | 缓存写入(5m) | 缓存读取  | 上下文  |
| ------------------------------------------------ | ------ | ------ | -------- | ----- | ---- |
| `claude-opus-4-7`、`claude-opus-4-7-thinking`     | $5.00  | $25.00 | $6.25    | $0.50 | 1M   |
| `claude-opus-4-6`、`claude-opus-4-6-thinking`     | $5.00  | $25.00 | $6.25    | $0.50 | 1M   |
| `claude-opus-4-5-20251101`（及 `-thinking`）        | $5.00  | $25.00 | $6.25    | $0.50 | 200K |
| `claude-opus-4-1-20250805`（及 `-thinking`）        | $15.00 | $75.00 | $18.75   | $1.50 | 200K |
| `claude-opus-4-20250514`                         | $15.00 | $75.00 | $18.75   | $1.50 | 200K |
| `claude-sonnet-4-6`、`claude-sonnet-4-6-thinking` | $3.00  | $15.00 | $3.75    | $0.30 | 1M   |
| `claude-sonnet-4-5-20250929`（及 `-thinking`）      | $3.00  | $15.00 | $3.75    | $0.30 | 1M   |
| `claude-sonnet-4-20250514`（及 `-thinking`）        | $3.00  | $15.00 | $3.75    | $0.30 | 200K |
| `claude-haiku-4-5-20251001`（及 `-thinking`）       | $1.00  | $5.00  | $1.25    | $0.10 | 200K |

>

Anthropic 缓存读取统一为标准输入价的 **0.1×**（命中缓存便宜 90%）；缓存写入为 1.25×（5 分钟）或 2×（1 小时）。Opus 4 / Sonnet 4 已被官方标记弃用。Opus 4.7 采用新分词器，相同文本可能多耗约 35% token。

## Google Gemini

| 模型                                                                   | 官方输入                             | 官方输出              | 缓存读取            | 上下文 |
| -------------------------------------------------------------------- | -------------------------------- | ----------------- | --------------- | --- |
| `gemini-3.5-flash`                                                   | $1.50                            | $9.00             | $0.15           | 1M  |
| `gemini-3.1-pro-preview`（及 `-customtools`/`-high`/`-low`/`-medium`）  | $2.00 / $4.00\*                  | $12.00 / $18.00\* | $0.20 \~ $0.40  | 1M  |
| `gemini-3.1-flash-lite`、`gemini-3.1-flash-lite-preview`              | $0.25                            | $1.50             | $0.025          | 1M  |
| `gemini-3-pro-preview`（及 `-thinking`）                                | $2.00 / $4.00\*                  | $12.00 / $18.00\* | $0.20 \~ $0.40  | 1M  |
| `gemini-3-flash-preview`（及 `-thinking`）                              | $0.50                            | $3.00             | $0.065          | 1M  |
| `gemini-2.5-pro`（及 `-thinking`/`-nothinking`）                        | $1.25 / $2.50\*                  | $10.00 / $15.00\* | $0.125 \~ $0.25 | 1M  |
| `gemini-2.5-flash`（及 `-thinking`/`-nothinking`）                      | $0.30                            | $2.50             | $0.03           | 1M  |
| `gemini-2.5-flash-lite`                                              | $0.10                            | $0.40             | $0.01           | 1M  |
| `gemini-flash-latest`、`gemini-pro-latest`、`gemini-flash-lite-latest` | 同当前对应 Flash / Pro / Flash-Lite 档 |                   |                 | 1M  |
| `gemini-embedding-001`                                               | $0.15                            | —                 | —               | —   |
| `gemini-embedding-2-preview`                                         | $0.20                            | —                 | —               | —   |

>

\*Gemini Pro 系列按提示长度分两档计价：≤200K tokens 取低价，>200K tokens 取高价。

### 图像 / 语音 / 视频

| 模型                                                                                         | 官方价格                                         |
| ------------------------------------------------------------------------------------------ | -------------------------------------------- |
| `gemini-2.5-flash-image`（Nano Banana）                                                      | 输入 $0.30，图像输出约 $30 / 1M tokens（约 $0.039 / 张） |
| `gemini-3-pro-image-preview`、`gemini-3.1-flash-image-preview`                              | 按图像 token 计，约 $0.04 \~ $0.13 / 张             |
| `gemini-2.5-flash-preview-tts`、`gemini-2.5-pro-preview-tts`、`gemini-3.1-flash-tts-preview` | 语音合成，按音频 token 计                             |
| `veo-3.0-generate-001`、`veo-3.1-generate-preview`                                          | $0.40 / 秒                                    |
| `veo-3.0-fast-generate-001`、`veo-3.1-fast-generate-preview`                                | $0.15 / 秒                                    |

# 以上均为各厂商官方原价，通过 aicentos 中转调用，价格比官方便宜 10 倍不止。

**一个 API Key，接入以上全部模型。**[立即注册 →](https://aicentos.com/) ｜ [查看 aicentos 实时价格 →](https://docs.aicentos.com/billing/pricing)

---

# 计费

来源: https://docs.aicentos.com/billing/pricing

Language: zh-CN

> 充值与按量计费 —— 支付宝充值、按 Token 计费、余额与用量查询

aicentos 走 **预充值 + 按量计费**。充值进钱包余额，每次请求按实际消耗扣费。余额以**人民币 ¥** 结算。

新账号注册即送 **¥1** 体验额度，无需先充值就能跑通第一个请求。

## 充值

控制台 → **钱包** → 「**添加资金**」：

钱包

### 充值档位

**充值 ¥100 及以上有折扣，实付金额低于充值金额**：

| 充值金额                 | 优惠     | 实付     |
| -------------------- | ------ | ------ |
| ¥1 / ¥10 / ¥20 / ¥50 | 无      | 原价     |
| ¥100                 | 1% OFF | ¥99    |
| ¥500                 | 2% OFF | ¥490   |
| ¥1,000               | 3% OFF | ¥970   |
| ¥10,000              | 5% OFF | ¥9,500 |

优惠直接体现在支付金额上：充 ¥500 实付 ¥490，省 ¥10。也可以自定义金额，或使用兑换码兑换额度。

充值档位

### 支付方式

付款方式

* **支付宝**：扫码即付，到账迅速
* 也可以使用**兑换码**兑换额度
* 其他支付通道以钱包页实际显示为准

### 额度有效期

**余额永不过期**，可放心充值，不必担心用不完。

## 按量计费

每次 API 请求按**实际消耗的 Token 数**扣费：

```bash
费用 = (输入 Tokens × 输入单价 + 输出 Tokens × 输出单价) × 分组倍率
```

* 每个模型有独立的输入 / 输出单价，单位通常是 **per 1M tokens**
* **分组倍率**取决于密钥所属分组，不同分组的倍率不同
* 具体单价与倍率以 [模型定价页](https://aicentos.com/pricing) 实时显示为准

### 按次计费的模型

图像、视频等多媒体模型可能按**次**或按**张**计费而非 Token，具体以模型定价页的说明为准。

## 查余额 / 消耗

控制台左侧「**钱包**」查看余额与总用量：

| 指标         | 含义      |
| ---------- | ------- |
| **当前余额**   | 账户剩余额度  |
| **总用量**    | 累计已消耗额度 |
| **API 请求** | 累计请求数   |

更细的消耗明细在「**使用日志**」：可按时间、模型、密钥筛选，查看每次请求的 Token 数与扣费金额。「**数据看板**」提供分模型的调用趋势与额度统计。

## 余额预警

控制台 → **个人资料** → 通知设置，可以设置余额预警阈值。余额低于阈值时自动通知，避免业务中途因余额耗尽而中断。

具体可选的阈值与通知渠道以控制台实际显示为准。

## 退款与发票

* 余额**不退现**
* 异常扣费 / 误调用经客服核实后可补偿额度
* 长期未用账户的余额**不过期**
* 发票：签订合同的企业客户可开具发票，具体票种与开票流程在商务沟通中确认

## 团队 / 共享额度

给团队成员分配额度：

* 在「**API 密钥**」为每个成员单独创建密钥
* 给每个密钥设独立**额度上限**
* 需要时用「**可用模型**」限制该密钥能调哪些模型
* 在「**使用日志**」里按密钥维度审计消耗

## 推荐奖励

控制台 → **钱包** → **推荐计划**：邀请朋友注册，双方都可获得奖励。用你的专属推荐链接注册的用户会与你关联，累计奖励可随时转入余额。

具体奖励比例以钱包页实时说明为准。

## 下一步

* [快速开始](https://docs.aicentos.com/quickstart) — 三步接入，跑通第一个请求
* [支持的模型](https://docs.aicentos.com/billing/models-list) — 查看模型清单
* [错误处理](https://docs.aicentos.com/billing/errors) — 排查余额不足等报错

---

# Amp

来源: https://docs.aicentos.com/clients/amp

Language: zh-CN

> 在 Amp 中使用 aicentos —— 通过配置文件覆盖后端地址

Amp 是 Sourcegraph 推出的编码代理，CLI 与 IDE 扩展共用同一套账号与设置。它没有常见的「OpenAI 兼容 Base URL」输入框，而是通过 `amp.url` 配置项把整个后端指向自定义端点，凭证另外存放在 secrets 文件里。

## 准备工作

先在控制台「API Key」页面为 Amp 创建一个专用 Key（建议命名 `amp-cli`，方便追踪用量）：

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 余额不足时充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| API Key  | 控制台创建的 Key                |
| Base URL | `https://aicentos.com/v1` |
| 模型       | 控制台「模型广场」中的模型名            |

## 配置步骤

Amp 的设置项都带 `amp.` 前缀，用户级配置文件位于：

* macOS / Linux：`~/.config/amp/settings.json`
* Windows：`%USERPROFILE%\.config\amp\settings.json`

先建好目录，再写入后端地址：

```bash
mkdir -p ~/.config/amp ~/.local/share/amp
```

```json
{
  "amp.url": "https://aicentos.com/v1"
}
```

API Key 不写在这个文件里，而是单独放在 secrets 文件中，键名为 `apiKey@<你的 URL>`：

```json
{
  "apiKey@https://aicentos.com/v1": "sk-你的-API-Key"
}
```

配置生效后，`amp login` 不再需要执行，请求会直接走你指定的端点。如果之前登录过，建议先 `amp logout` 退出再重启 `amp`，避免残留的登录态覆盖配置。

也可以用环境变量临时覆盖，适合先做一次性验证：

```bash
export AMP_URL="https://aicentos.com/v1"
export AMP_API_KEY="sk-你的-API-Key"
```

**注意：** 一旦设置了这两个变量，Amp 会跳过登录流程，优先级高于配置文件。

## 测试

先发一条轻量请求，确认端点已经切过去：

```bash
amp -x "用一句话回答：1+1 等于几"
```

能正常返回说明配置生效。若返回 401，多半是 secrets 文件里的键名与 `amp.url` 不完全一致（包括末尾是否带 `/v1`）。

## 注意事项

* Amp 的后端协议是它自己的管理接口，并非通用的 OpenAI 兼容协议，因此 `amp.url` 必须指向同时提供 Anthropic Messages（`/v1/messages`）风格接口的端点。
* aicentos 提供原生 Claude 格式接口（见 [原生 Claude 格式](https://docs.aicentos.com/api/chat/claude)）与 OpenAI 兼容接口（见 [Chat Completions](https://docs.aicentos.com/api/chat/openai/chat-completions)）；Amp 走的是前者。
* Amp 会请求固定的模型 ID，如果端点侧没有同名模型，会出现回落或报错。遇到这种情况，请以控制台「模型广场」为准核对模型名。
* IDE 扩展（VS Code / Cursor / Windsurf）的设置与 CLI 分开维护，需要单独填写 Amp URL 与 Amp API Key。
* 工作区里的 `.amp/settings.json` 会覆盖用户级设置；排查问题时先确认当前目录下没有同名文件。

## 相关链接

* 官方设置文档：[https://ampcode.com/docs/cli/settings](https://ampcode.com/docs/cli/settings)

---

# Antigravity CLI

来源: https://docs.aicentos.com/clients/antigravity-cli

Language: zh-CN

> 在 Antigravity CLI 中使用 aicentos —— 通过 API Key 模式接入

Antigravity CLI 是 Google 推出的命令行工具，支持通过 API Key 模式接入兼容 Gemini API 的服务。本文档介绍如何配置 Antigravity CLI 以使用自定义 API 端点。

## 安装

根据操作系统选择对应的安装方式：

### macOS / Linux

```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

### Windows (PowerShell)

```powershell
irm https://antigravity.google/cli/install.ps1 | iex
```

### Windows (CMD)

```cmd
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
```

### 验证安装

```bash
agy --version
```

## 配置

### 启用 API Key 模式

编辑 `~/.gemini/antigravity-cli/settings.json`，在现有 JSON 中添加：

```json
{
  "modelProvider": "gemini"
}
```

⚠️ **注意**：只设置 `GEMINI_API_KEY` 不会切换认证方式。`modelProvider` 必须设为小写的 `"gemini"`。

### 设置环境变量

```bash
export GOOGLE_GEMINI_BASE_URL="https://aicentos.com"
export GEMINI_API_KEY="your_api_key_here"
```

**重要说明：**

* `GOOGLE_GEMINI_BASE_URL` 填服务根地址，不要带具体接口路径。端点必须兼容 Gemini API。
* `GEMINI_API_KEY` 填你的 API Key。
* 在启动 `agy` 的同一个 shell 中执行以上命令。CLI 不读取 `.env` 或 `GOOGLE_API_KEY`。

需要永久生效时，将两个 `export` 写入 `~/.zshrc` 或 `~/.bashrc`。

## 启动与验证

```bash
agy --model gemini-2.0-flash
```

顶部显示 `Gemini API key` 后，发起一次对话。

### 常见问题排查

* **仍要求登录**：检查 `"modelProvider": "gemini"`，退出并重新启动 `agy`。
* **启动时提示缺少 Key**：在当前 shell 中重新设置 `GEMINI_API_KEY`。
* **请求失败**：检查 API Key、服务根地址和所选模型的访问权限。

## 注意事项

* 必须同时设置 `modelProvider` 配置项和环境变量才能正常使用 API Key 模式
* 环境变量需要在启动 CLI 的 shell 会话中设置，或写入 shell 配置文件永久生效
* 服务端点必须兼容 Gemini API 规范

## 相关链接

* 官方文档：[https://docs.aicentos.com/clients/antigravity-cli.html](https://docs.aicentos.com/clients/antigravity-cli.html)

---

# Antigravity

来源: https://docs.aicentos.com/clients/antigravity

Language: zh-CN

> Google Antigravity 目前不支持自定义 Base URL —— 说明限制与可用替代方案

Antigravity 是 Google 推出的代理式 IDE。需要先说明一个前提：**官方版本的 Antigravity 桌面 IDE 不支持自定义 API 端点，也不提供 BYOK（自带密钥）**，模型选择器里是一份由 Google 维护的固定清单，目前无法指向 aicentos。

本文说明这一限制的依据、验证方法，以及三条可用的替代路径。

## 为什么不能直接接入

Google 的账号方案文档明确表示，Antigravity 暂不支持自带模型或自带端点。社区中流传的若干配置项（例如在 `~/.antigravity/settings.json` 里写 `antigravity.ai.provider`、`antigravity.openai-compatible.endpoint`）并非官方支持的键，实测表现为请求不路由到自定义端点，或静默回落到默认模型，且模型选择器里不会出现自定义条目。

换句话说，这个问题不是「配置写错了」，而是当前版本没有开放这个能力。IDE 的 `Settings → Models` 里也没有 Base URL 字段可填。

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| API Key  | 控制台创建的 Key                |
| Base URL | `https://aicentos.com/v1` |
| 模型       | 控制台「模型广场」中的模型名            |

上表是 aicentos 侧的通用参数，供下面任一种替代方案使用。

## 替代方案

### 方案一：改用 Antigravity CLI（推荐，仅限 Gemini 协议）

同名的命令行工具 `agy` 支持端点覆盖，通过 `GOOGLE_GEMINI_BASE_URL` + `GEMINI_API_KEY` 即可接入，但只接受 Gemini 协议、只能调用 Gemini 系列模型。具体步骤见 [接入 Antigravity CLI](https://docs.aicentos.com/clients/antigravity-cli)。

如果你的需求是「在终端里用 Antigravity 的交互方式」，这条最省事。

### 方案二：把本地模型或第三方服务包成 MCP 工具

Antigravity 的 Customizations 面板支持注册 MCP Server。可以把本地服务封装成 MCP 工具挂进去，作为一个**可调用的工具**使用。需要注意：这不会替换 IDE 的推理模型，只是给代理多了一个工具。

### 方案三：社区分支或本地代理

* 社区分支 `open-antigravity` 支持任意 OpenAI 兼容端点与自定义模型，是官方版本之外最干净的路径。
* 也有人用本地拦截代理改写 IDE 的出站流量。这条路没有官方支持，配置脆弱、升级即失效，不建议在生产环境使用。

## 测试

无论选哪条路径，先用一句简单提示词确认连通，再正式投入使用。Agent 类任务建议先跑一个小仓库。

## 注意事项

* **不要把「配置项看似存在」当成「功能可用」**。IDE 里的 `antigravity.*` 键多为社区猜测，写入后不报错但也不生效。
* 如果你需要的是 OpenAI 兼容协议、或想调用 Claude / GPT 系列模型，Antigravity 桌面版目前无法满足，请优先考虑 [Cursor](https://docs.aicentos.com/clients/cursor)、[Windsurf](https://docs.aicentos.com/clients/windsurf) 等支持自定义 Base URL 的客户端。
* Antigravity CLI 与桌面 IDE 是两套配置，CLI 的端点覆盖不会影响 IDE。
* 使用任何第三方分支或代理前，请自行评估其安全性与后续维护情况。

## 相关链接

* [接入 Antigravity CLI](https://docs.aicentos.com/clients/antigravity-cli)

---

# Augment Code

来源: https://docs.aicentos.com/clients/augment-code

Language: zh-CN

> Augment Code 不开放自定义端点，模型无法换成 aicentos —— 说明依据与替代方案

Augment Code 是 VS Code / JetBrains / Vim 的编码插件，外加 `auggie` CLI。它**不支持自定义 Base URL，也不提供 BYOK**：模型来自官方目录，账号必须通过 `auggie auth login` 登录，请求无法指向 aicentos。

## 为什么不能直接接入

* 配置文件里没有 `baseUrl`、`apiKey` 这类字段，插件设置面板也没有端点输入框。
* CLI 只认两个相关环境变量：`AUGMENT_SESSION_AUTH`（登录态）和 `AUGMENT_DISABLE_AUTO_UPDATE`（关自动更新），没有覆盖端点的变量。
* `--model` 只接受官方模型目录里的名字（Claude、GPT、Gemini、GLM、Kimi 等），填第三方模型名会被拒。
* 官方文档索引 `docs.augmentcode.com/llms.txt` 中没有 BYOK 或自定义 provider 的条目。

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| API Key  | 控制台创建的 Key                |
| Base URL | `https://aicentos.com/v1` |
| 模型       | 控制台「模型广场」中的模型名            |

上表是 aicentos 侧的通用参数，供下面任一种替代方案使用。

## 替代方案

### 方案一：换成支持自定义端点的编码代理

[Craft Agent](https://docs.aicentos.com/clients/craft-agent)、[Gajae Code](https://docs.aicentos.com/clients/gajae-code)、[Oh My Pi](https://docs.aicentos.com/clients/oh-my-pi) 都是终端编码代理，配置里能直接写 `baseUrl`。

### 方案二：留在 VS Code，换插件

[Cline](https://docs.aicentos.com/clients/cline)、[Roo Code](https://docs.aicentos.com/clients/roo-code)、[Kilo](https://docs.aicentos.com/clients/kilo) 都支持 OpenAI 兼容 provider，能直接填 `https://aicentos.com/v1`。

### 方案三：只挪批量任务

如果团队已购 Augment 订阅、又舍不得它的补全体验，可以维持官方模型做日常编辑，把批量重构、脚本化任务挪到支持自定义端点的 CLI 上跑。

## 测试

换到任一替代客户端后，先用一句简单提示词确认连通，再看控制台用量是否记到了新 Key 上。

## 注意事项

* 网上有教程写 `augment.modelProvider: "openai-compatible"`、`augment.baseUrl`、`augment.apiKeyEnv` 这类键。官方配置里不存在，写进去不报错也不生效，`--model` 依然只认官方目录。
* 别把「配置项没报错」当成「配置生效了」。验证方式是问它当前模型名，再对照官方目录。
* Augment 的云端索引与补全没有等价替代，换客户端等于换整套工作流，建议先小仓库试。

## 相关链接

* [Augment Code CLI 文档](https://docs.augmentcode.com/cli/overview)

---

# CC Switch

来源: https://docs.aicentos.com/clients/cc-switch

Language: zh-CN

> 从 aicentos 控制台一键导入配置到 CC Switch，管理 Claude Code / Codex / Gemini CLI

CC Switch 是一个跨平台的 AI CLI 配置管理工具，用于集中管理 Claude Code、Codex、Gemini CLI 等工具的模型提供商（Provider）配置，让你在多个 CLI 工具或多套配置之间一键切换，不必反复修改环境变量。

aicentos 控制台内置了 **CC Switch 一键导入**：不用手抄 Base URL 和密钥，点几下就能把配置写进 CC Switch。

## 准备工作

1. 登录 [aicentos 控制台](https://aicentos.com/)
2. 确认账户有余额（注册赠送 ¥1 体验额度，用完后在「**钱包**」充值）
3. 安装 CC Switch（见下）

## 安装 CC Switch

CC Switch 是开源项目，源码托管在 GitHub：[farion1231/cc-switch](https://github.com/farion1231/cc-switch)。

打开 [Releases 页面](https://github.com/farion1231/cc-switch/releases)，在最新版本的资源列表中，根据自己的操作系统选择对应的安装包：

* macOS：`.dmg`
* Windows：`.msi`
* Linux：`.AppImage` / `.deb`

下载完成后按系统正常方式安装，并**至少打开一次 CC Switch**，这样控制台的导入链接才能识别到本机已安装。

## 一键导入（推荐）

### 第 1 步：在控制台发起导入

进入控制台左侧「**API 密钥**」，在要使用的密钥那一行点右侧的「**⋯**」，在菜单里选「**CC Switch**」：

在 API 密钥列表选择 CC Switch

### 第 2 步：选择应用与模型

弹窗「**填入 CC Switch**」里选择目标应用（Claude / Codex / Gemini），并确认要使用的模型：

填入 CC Switch 配置

| 字段                | 说明                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------ |
| 应用                | 选择要写入哪个 CLI 的配置。**Claude** 走 Anthropic 协议，**Codex** 走 OpenAI 兼容格式，**Gemini** 走 Gemini 原生格式 |
| 名称                | 导入后在 CC Switch 里显示的配置名，可自定义                                                                |
| 主模型               | 该配置默认使用的模型，必填                                                                              |
| Haiku / Sonnet 模型 | Claude 应用下的分档模型，按需指定                                                                       |

模型名可参考[支持的模型](https://docs.aicentos.com/billing/models-list)，例如 `claude-opus-4-8`、`claude-sonnet-5`、`claude-haiku-4-5`。

选好后点「**打开 CC Switch**」。

### 第 3 步：浏览器确认唤起

浏览器会询问是否打开 CC Switch，点「**打开 CC Switch.app**」：

浏览器询问打开 CC Switch

> 如果勾选「始终允许 aicentos.com 在关联的应用中打开此类链接」，之后导入就不会再弹这个确认框。

### 第 4 步：在 CC Switch 确认导入

CC Switch 会弹出「**确认导入供应商配置**」，核对信息后点「**导入**」：

CC Switch 确认导入

弹窗里会列出将写入的端点、密钥与分档模型，核对无误后点「**导入**」。

导入完成后，`aicentos Claude` 会出现在 CC Switch 的配置列表里，点一下即可切换：

导入完成

## 手动配置

如果不想用一键导入，也可以在 CC Switch 里点「**添加新供应商**」手动填写：

CC Switch 添加新供应商

| 字段      | 填什么                                                                        |
| ------- | -------------------------------------------------------------------------- |
| 供应商名称   | `aicentos`（自定义，便于识别即可）                                                     |
| API Key | 控制台「**API 密钥**」页创建的密钥，形如 `sk-xxxxxxxx`                                     |
| 请求地址    | Claude / Gemini 填 `https://aicentos.com`；Codex 填 `https://aicentos.com/v1` |

> **Anthropic 协议只填根地址**，不要手动追加 `/v1/messages`，客户端会自动拼接。

## 下一步

* [模型状态监控](https://docs.aicentos.com/status) — 查看各模型实时可用率
* [支持的模型](https://docs.aicentos.com/billing/models-list) — 查看完整模型清单与 ID
* [计费](https://docs.aicentos.com/billing/pricing) — 了解充值与按量计费

---

# Chatbot UI

来源: https://docs.aicentos.com/clients/chatbot-ui

Language: zh-CN

> 在 Chatbot UI 中使用 aicentos —— 通过自定义 OpenAI 兼容设置接入

Chatbot UI 是一款开源的 ChatGPT 风格 Web 前端，支持自定义 OpenAI 兼容接口。

## 自托管部署配置

对于自托管实例，通过环境变量配置自定义接口：

```bash
OPENAI_API_KEY=codex_your_api_key
OPENAI_API_HOST=https://aicentos.com/v1
```

配置后重启服务，新接口即生效。环境变量设置后，UI 界面中对应输入框会被禁用（防止共享实例泄漏配置）。

## UI 界面配置

对于未限制 UI 设置的实例，在设置面板中填写：

* **OpenAI API Key**: 你的 `codex_...` 或 `sk-...` 等 Key
* **OpenAI API Host / Base URL**: `https://aicentos.com/v1`

## 注意事项

* Chatbot UI 需要配合 Supabase 部署鉴权和数据存储
* API Host 填写包含 `/v1` 的服务根路径
* 可用模型以 `GET /v1/models` 返回列表为准

## 相关链接

* GitHub：[https://github.com/mckaywrigley/chatbot-ui](https://github.com/mckaywrigley/chatbot-ui)

---

# Chatbox

来源: https://docs.aicentos.com/clients/chatbox

Language: zh-CN

> 在 Chatbox 中使用 aicentos —— 通过自定义 OpenAI 兼容设置接入

Chatbox 是一款支持 OpenAI 兼容接口的桌面 AI 客户端，可通过「OpenAI API 兼容」模式对接当前服务。

## 打开设置

点击左侧边栏\*\*设置（Settings）**图标，进入**模型（Model）\*\*选项卡。

## 选择 AI 提供商

在 **Model Provider** 下拉框中选择 `OpenAI API Compatible`（OpenAI API 兼容）。

## 需要填写的配置

填写以下字段：

| 字段               | 填写内容                            |
| ---------------- | ------------------------------- |
| API Key          | 你的 `codex_...` 或 `sk-...` 等 Key |
| API 域名（API Host） | `https://aicentos.com`          |
| 模型（Model）        | `gpt-5-codex-mini` 或其他可用模型      |

**注意：** Chatbox 的 **API 域名**字段只填写服务根地址，**不要**加 `/v1` 后缀。填写示例：`https://aicentos.com`

## 测试

保存后，发起一次对话，确认有正常返回。

## 注意事项

* API 域名填写不带 `/v1` 的服务根路径，Chatbox 会自动拼接接口路径
* 可用模型以 `GET /v1/models` 返回列表为准

## 相关链接

* 官方文档：[https://docs.chatboxai.app/en/guides/providers](https://docs.chatboxai.app/en/guides/providers)

---

# Cherry Studio

来源: https://docs.aicentos.com/clients/cherry-studio

Language: zh-CN

> 在 Cherry Studio 中使用 aicentos —— 添加 OpenAI 兼容服务商接入全部模型

Cherry Studio 支持自定义 OpenAI 兼容的模型服务商，添加 aicentos 后即可在应用内使用 aicentos 接入的全部模型。

## 准备信息

| 字段               | 值                         |
| ---------------- | ------------------------- |
| 服务商名称            | `aicentos`                |
| API 地址（Base URL） | `https://aicentos.com/v1` |
| API Key          | 在 aicentos 控制台创建          |
| 模型名              | 控制台「模型广场」中的完整模型名          |

API Key 的获取步骤见 [快速开始](https://docs.aicentos.com/quickstart)。

## 配置步骤

* 打开 Cherry Studio 设置，进入**模型服务 / 服务商管理**。
* 添加一个新的 **OpenAI 兼容**服务商。
* 服务商名称填 `aicentos`。
* 填入 API Key 与 API 地址 `https://aicentos.com/v1`。
* 保存配置，若有「检测 / 测试连接」按钮可点击验证。

### 添加模型

如果没有自动识别到模型，可手动添加模型名。

>

模型名要完整复制，大小写、连字符、日期后缀都不能改动，以 [模型广场](https://aicentos.com/pricing) / [支持的模型](https://docs.aicentos.com/billing/models-list) 中的为准。

## 测试与排查

发送一条测试消息确认连通，例如：

```bash
你好，请用一句话介绍你自己。
```

常见问题：

* **鉴权错误**：检查 API Key 是否有多余空格。
* **超时**：检查网络或服务状态。
* **模型不可用**：使用控制台中的完整模型名。
* **对话失败**：确认已选中 aicentos 这个服务商。

---

# Claude Code

来源: https://docs.aicentos.com/clients/claude-code

Language: zh-CN

> 从零安装 Claude Code 并接入 aicentos —— Node.js 环境、Windows / Mac 安装、环境变量与 CC Switch 配置，附手机 Termux 教程

Claude Code 兼容 Anthropic 协议，只需把 Base URL 指向 aicentos、填入你的 API Key，即可用上 aicentos 接入的全部 Claude 模型。

## 第一步：安装 Claude Code

### 安装 Node.js 环境

前往 [Node.js 官网](https://nodejs.org/) 下载最新 LTS 版本，请下载与自己操作系统对应的安装包。

Node.js 官网下载

安装完成后，打开终端（Windows 用 git bash 或 cmd），输入：

```bash
node -v
```

看到版本号即表示安装成功。

### 安装 Claude Code

安装前先确认上面的 Node.js 环境已配置完成。

**Windows：** 按 `Win + R`，输入 `cmd` 回车打开终端，执行：

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

**Mac / Linux：** 在终端运行：

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

或使用官方推荐的 curl 脚本：

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

安装完成后测试是否成功：

```bash
claude --version
```

出现版本号即表示安装成功。

claude --version 安装成功

## 第二步：获取 API 密钥

前往 [aicentos 官网](https://aicentos.com/) 控制台创建你的 API 密钥。

详细的密钥创建步骤见 [快速开始](https://docs.aicentos.com/quickstart)。

## 第三步：配置接入

下面提供两种方式：**用 CC Switch 一键管理**（推荐），或**自己手动配置**。

### 方式一：用 CC Switch（推荐）

如果你需要在多套 Provider、多个 CLI 工具之间频繁切换，推荐用 CC Switch 集中管理配置，无需反复改环境变量。

详见 [接入 CC Switch →](https://docs.aicentos.com/clients/cc-switch)

### 方式二：手动配置

不想装额外工具的话，直接配置环境变量即可。三选一。

#### 临时生效（当前终端会话）

适合快速测试，只在当前终端窗口有效：

```bash
export ANTHROPIC_BASE_URL="https://aicentos.com"
export ANTHROPIC_AUTH_TOKEN="sk-你的-API-Key"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude
```

部分版本若不识别 `ANTHROPIC_AUTH_TOKEN`，改用：

```bash
export ANTHROPIC_API_KEY="sk-你的-API-Key"
```

#### 持久化（配置文件，推荐手动方式）

编辑 `~/.claude/settings.json`，写入：

```bash
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://aicentos.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的-API-Key",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}
```

**Windows** 也可以在「系统环境变量」的「用户变量」中点击「新建」，分别创建以下两个变量：

| 变量名                    | 值                      |
| ---------------------- | ---------------------- |
| `ANTHROPIC_BASE_URL`   | `https://aicentos.com` |
| `ANTHROPIC_AUTH_TOKEN` | 第二步创建的密钥               |

保存后重启 Claude Code 生效。

#### 写入 Shell 配置（全局生效）

把环境变量加到 `~/.zshrc` 或 `~/.bashrc`：

```bash
nano ~/.zshrc
```

在文件末尾添加：

```bash
# aicentos API Key（第二步创建的密钥）
export ANTHROPIC_AUTH_TOKEN="你的密钥"

# aicentos Base URL
export ANTHROPIC_BASE_URL="https://aicentos.com"
```

保存并退出，然后执行 `source ~/.zshrc`（或重开终端）生效。

## 第四步：运行 Claude Code

进入你的项目目录并启动：

```bash
cd /path/to/your/project
claude
```

## 指定模型

启动时用 `--model` 指定具体模型：

```bash
claude --model claude-opus-4-7
```

模型名按 aicentos 控制台「模型广场」中列出的为准，可参考 [支持的模型](https://docs.aicentos.com/billing/models-list)。

## 常用命令

| 命令                        | 用途                                      |
| ------------------------- | --------------------------------------- |
| `/add-dir`                | 添加额外的工作目录                               |
| `/resume`                 | 回退到历史对话                                 |
| `/clear`                  | 清除对话历史                                  |
| `/compact [instructions]` | 压缩对话，可选择性地提供重点指令                        |
| `/config`                 | 查看 / 修改配置                               |
| `/cost`                   | 显示令牌使用统计                                |
| `/doctor`                 | 检查 Claude Code 安装的健康状况                  |
| `/help`                   | 获取使用帮助                                  |
| `/init`                   | 使用 CLAUDE.md 指南初始化项目                    |
| `/login`                  | 切换 Anthropic 账户                         |
| `/logout`                 | 从 Anthropic 账户登出                        |
| `/mcp`                    | 管理 MCP 服务器连接和 OAuth 身份验证                |
| `/memory`                 | 编辑 CLAUDE.md 内存文件                       |
| `/model`                  | 选择或更改 AI 模型                             |
| `/permissions`            | 查看或更新权限                                 |
| `/pr_comments`            | 查看拉取请求评论                                |
| `/review`                 | 请求代码审查                                  |
| `/status`                 | 查看账户和系统状态                               |
| `/terminal-setup`         | 安装 Shift+Enter 换行键绑定（仅 iTerm2 和 VSCode） |
| `/vim`                    | 进入 vim 模式，在插入和命令模式之间切换                  |

## 在手机上跑（Termux + Ubuntu）

适合"没带电脑、出门临时改 bug、上下班通勤想 vibe 一下"的场景。不需要 root、不刷机，全程在 Termux 里完成。整套搞下来 10-20 分钟，看网速。

### 你将得到

* 一个跑在手机里的 **Ubuntu** 环境（不影响系统、不占多少空间）
* 完整版 **Claude Code** 命令行工具（和电脑版一模一样）
* 通过 **aicentos** 走低成本接入，秒切 Opus / Sonnet / Haiku

### 准备

只需要两样东西：

* **一部安卓手机**（iOS 装不了 Termux，本教程不适用）
* **一个 [aicentos](https://aicentos.com) 账号 + API Key**（[去钱包充值 →](https://aicentos.com/wallet)，[去创建 Key →](https://aicentos.com/keys)）

**Termux 别从 Google Play 装**，那个版本太旧已经不维护，会装不上后面的脚本。请去 [F-Droid](https://f-droid.org/packages/com.termux/) 或 [Termux GitHub Releases](https://github.com/termux/termux-app/releases) 下最新版。

### 第一步：装 tmoe-linux 一键脚本

打开 Termux，等出现命令提示符（一行 `~ $`），把下面这行**整行**复制进去回车：

```bash
. <(curl -L l.tmoe.me)
```

>

这是中国大陆专用镜像，国外用户用 `. <(curl -L git.io/linux.sh)`。

跑完之后会跳出一个**图形菜单**，长这样：

tmoe 主菜单

用音量键上下选、回车确定（或者直接点屏幕）。

### 第二步：装 Ubuntu 容器

在 tmoe 菜单里一路选 `安装 Linux 发行版` / `Install GNU/Linux container`，会进到发行版列表：

Linux 发行版选择

**强烈建议选 Ubuntu**（兼容性最好，apt 资料最多，遇到问题搜得到答案）。版本选最新的 LTS（比如 22.04 / 24.04）就行。

下载 + 解压会跑几分钟，看网速，等就行。

### 第三步：进容器，认清"你在哪里"

装完之后大概率会自动进入容器。**这一步是新手最容易迷路的地方**，先教你怎么分辨：

**已进入 Ubuntu 容器**（命令提示符大概长这样）：

已进入容器

**还在 Termux 没进去**（提示符比较朴素）：

还在 Termux

如果是后者，回到 Termux 输：

```bash
tmoe
```

再次打开菜单，找到 `启动容器` / `Start container` 进去。

**记住这条规矩**：装 Node、装 Claude Code、跑 Claude 命令——**所有这些都必须在 Ubuntu 容器里做**。Termux 本身的 `pkg` 包系统装不了 Claude Code。

### 第四步：装 Node.js 和 Claude Code

确认自己在 Ubuntu 容器里之后，依次跑：

```bash
# 1. 更新 apt 包索引
apt update

# 2. 装 Node.js + npm（Ubuntu 自带的版本够用）
apt install -y nodejs npm

# 3. 全局装 Claude Code
npm install -g @anthropic-ai/claude-code
```

如果 npm 报权限错，前面加 `sudo`。如果根本没有 `sudo` 命令，那就是你是 root 用户，直接跑就行。

### 第五步：把 aicentos 接入 Claude Code

Claude Code 默认连官方，对国内用户来说有两个问题：**没额度、连不上**。

我们改两个环境变量把它指到 aicentos：

```bash
# 1. 装 nano 文本编辑器（容器里默认可能没有）
apt install -y nano

# 2. 编辑你的 shell 配置
nano ~/.bashrc
```

按方向键移到文件**最末尾**，新起一行粘贴：

```bash
export ANTHROPIC_BASE_URL=https://aicentos.com
export ANTHROPIC_AUTH_TOKEN=你在aicentos.com生成的apikey
```

替换 `你在aicentos.com生成的apikey` 为你在 [aicentos 控制台](https://aicentos.com/keys) 里创建的 API Key（一般是 `sk-` 开头）。

效果大概像这样：

bashrc 末尾添加 env

**保存退出**：

* 按 `Ctrl + X`（手机输入法上的 Ctrl 键，Termux 默认有这个虚拟键）
* 提示 Save 时按 `Y`
* 再按 `Enter` 确认文件名

让配置立刻生效：

```bash
source ~/.bashrc
```

### 第六步：启动

```bash
claude
```

**第一次启动**会让你选登录方式：

* 如果之前用过官方账号登录、想清掉，直接在 Claude Code 里输 `/logout`，它会退出，再 `claude` 进来就会用你的环境变量
* 如果是全新安装，它可能跳过直接用环境变量

一旦看到 Claude Code 的对话框就代表搞定了，随便问句话试试：

```bash
你好，帮我写一个 hello world 的 python 脚本
```

### 手机端常用命令速查

在 Claude Code 内：

| 命令         | 作用                          |
| ---------- | --------------------------- |
| `/model`   | 切换模型（Opus / Sonnet / Haiku） |
| `/logout`  | 退出当前账号（环境变量切换后要用一次）         |
| `/clear`   | 清掉当前会话上下文                   |
| `/help`    | 看所有命令                       |
| `Ctrl + C` | 中断当前生成                      |

容器外（Termux 里）：

| 命令     | 作用              |
| ------ | --------------- |
| `tmoe` | 打开 tmoe 主菜单     |
| 启动容器   | tmoe 菜单里选「启动容器」 |

### 手机端常见坑

**1. `npm install -g` 跑不动 / 卡住**

可能是网络。容器里可以先 `npm config set registry https://registry.npmmirror.com` 换淘宝镜像，再 `npm install -g @anthropic-ai/claude-code`。

**2. `claude` 命令 not found**

`npm install -g` 装的命令路径不在 `PATH` 里。在 `~/.bashrc` 末尾再加：

```bash
export PATH="$PATH:$(npm config get prefix)/bin"
```

然后 `source ~/.bashrc`。

**3. 提示 401 / 余额不足**

检查 [aicentos 钱包](https://aicentos.com/wallet) 余额，以及 `ANTHROPIC_AUTH_TOKEN` 是否复制完整（注意首尾别带空格）。

**4. 想用 Sonnet 不想用 Opus 烧钱**

进入 `claude` 后输 `/model`，选 sonnet 即可。或者在 `.bashrc` 里加 `export ANTHROPIC_MODEL=claude-sonnet-5` 固定默认模型。

### 手机端进阶

* 想要更顺手的输入：装一个 [Termux:Styling](https://f-droid.org/packages/com.termux.styling/) 改字体和配色
* 想要图形界面：tmoe 菜单里有 VNC 桌面，可以在手机上跑完整 GNOME/XFCE
* 想长期跑后台：用 `tmux` 或 `screen`，关掉 Termux 也不掉线

教程到这里。有问题欢迎到 [aicentos 社群](https://aicentos.com) 反馈。

## 常见问题

### Claude Code 需要海外账号或信用卡吗？

不需要。把 Base URL 指向 `https://aicentos.com`、填上 aicentos 的 API Key 就能用，全程不经过 Anthropic 官方账号，也不需要海外支付方式。计费走 aicentos 钱包余额。

### 装 Claude Code 必须先用 npm 装 Node.js 吗？

用 npm 安装时需要，先装 Node.js LTS 并在终端确认 `node -v` 有版本号。如果不装 Node.js，可以用官方 curl 脚本 `curl -fsSL https://claude.ai/install.sh | bash` 直接安装。

### ANTHROPIC\_AUTH\_TOKEN 和 ANTHROPIC\_API\_KEY 该设哪个？

二选一，不要同时设置，否则可能出现鉴权冲突。优先用 `ANTHROPIC_AUTH_TOKEN`；部分旧版本不识别它时，再改用 `ANTHROPIC_API_KEY`。

### Base URL 要不要带 /v1 或 /v1/messages？

不要。只填根地址 `https://aicentos.com`，Claude Code 会自己拼接完整路径。多写一段反而会 404。

### 能不能在手机上用 Claude Code？

可以。Android 用 Termux 装 Ubuntu 容器后按同样步骤安装，具体命令见上面「在手机上跑（Termux + Ubuntu）」一节；iOS 没有同等方案。

## 注意事项

* API Key 在控制台的「API Key」页面获取。
* `ANTHROPIC_AUTH_TOKEN` 和 `ANTHROPIC_API_KEY`**二选一，不要同时设置**。
* Base URL 只填根地址 `https://aicentos.com`，**不要**手动追加 `/v1/messages`，Claude Code 会自动拼接。
* 修改配置后记得重启终端 / 重启 Claude Code。
* 切勿把 API Key 提交到代码仓库。

---

# Cline

来源: https://docs.aicentos.com/clients/cline

Language: zh-CN

> 在 Cline（VS Code 扩展）中填入 aicentos 的 Base URL 与 API Key，用 OpenAI 兼容协议接入全部模型

Cline 官方支持 OpenAI Compatible provider，可直接对接当前服务。

## 安装

按 Cline 官方文档：

* 如果你用 VS Code、Cursor、Windsurf 或 Antigravity，打开扩展市场，搜索 `Cline` 并安装官方扩展
* 如果你用 JetBrains，进入 `Settings / Plugins / Marketplace`，搜索 `Cline` 安装后重启 IDE
* 如果你只想用终端版，也可以看 Cline 官方 CLI 文档：`https://docs.cline.bot/cline-cli/installation`

## 打开设置

在 Cline 面板中点击设置按钮，进入 provider 配置。

## 需要填写的配置

将 `API Provider` 设为 `OpenAI Compatible`，然后填写：

* Base URL：`https://aicentos.com/v1`
* API Key：你的 `codex_...` 或 `sk-...` 等 Key
* Model ID：`gpt-5-codex-mini`

如果下拉列表里没有自动出现该模型，也可以直接手动输入 `gpt-5-codex-mini`。

## 测试

填写后点击 Cline 的 `Verify` 或直接发起一个新任务。如果能正常连接并开始会话，就说明接入成功。

## 注意事项

* Cline 官方文档使用的就是 OpenAI Compatible provider 配置方式
* Base URL 应填写 OpenAI 兼容根路径
* 对当前服务，不需要填写服务根地址，也不需要补成 `/chat/completions` 完整路径

---

# CodeBuddy

来源: https://docs.aicentos.com/clients/codebuddy

Language: zh-CN

> 在 CodeBuddy（IDE / CLI）中通过 models.json 接入 aicentos 的 OpenAI 兼容端点

CodeBuddy 支持自定义模型，通过用户级或项目级的 `models.json` 就能把请求指向 aicentos 的 OpenAI 兼容端点，IDE 和 CodeBuddy Code CLI 共用同一份配置。

## 准备工作

先在控制台「API Key」页面为 CodeBuddy 创建一个专用 Key（建议命名 `codebuddy`）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

## 需要填写的配置

| 字段                                   | 值                                          |
| ------------------------------------ | ------------------------------------------ |
| Base URL                             | `https://aicentos.com/v1`                  |
| 端点 URL（`url` 字段）                     | `https://aicentos.com/v1/chat/completions` |
| API Key（`apiKey`）                    | 控制台创建的 Key                                 |
| 模型 ID（`id`）                          | 控制台「模型广场」中的模型名                             |
| `supportsToolCall`                   | `true`                                     |
| `maxInputTokens` / `maxOutputTokens` | 按所选模型填写                                    |

注意：`models.json` 的 `url` 字段要求**完整接口路径**，必须以 `/chat/completions` 结尾。

## 配置步骤

* 打开一次 CodeBuddy，让它生成配置目录。
* 新建或编辑用户级配置文件：
  * macOS / Linux：`~/.codebuddy/models.json`
  * Windows：`C:\Users\<用户名>\.codebuddy\models.json`
  * 若只想对单个项目生效，可改用项目级 `<项目根>/.codebuddy/models.json`，优先级高于用户级。
* 写入以下内容，把 `id` 换成你在控制台确认可用的模型名：

```json
{
  "models": [
    {
      "id": "gpt-5",
      "name": "GPT-5 (aicentos)",
      "vendor": "aicentos",
      "apiKey": "${AICENTOS_API_KEY}",
      "url": "https://aicentos.com/v1/chat/completions",
      "maxInputTokens": 128000,
      "maxOutputTokens": 16384,
      "supportsToolCall": true,
      "supportsImages": false,
      "supportsReasoning": false
    }
  ]
}
```

* 设置环境变量（`apiKey` 与 `url` 都支持 `${VAR_NAME}` 引用）：

```bash
export AICENTOS_API_KEY="sk-你的aicentos密钥"
```

* 完全退出 CodeBuddy 后重新打开（IDE 面板重启即可）。
* 在模型选择器中选中刚配置的模型。

如果不想编辑文件，也可以在 CodeBuddy IDE 的对话面板下方点击模型选择框 → **配置自定义模型** → 供应商选 **Custom**，把 Base URL 填 `https://aicentos.com/v1`、填入 API Key 和模型名即可。

## 测试

保存后新建一个对话或编码任务，先用一句简单提示词轻量测试，确认能正常返回内容再正式使用。

## 注意事项

* 目前只支持 **OpenAI 接口格式**的 API。
* `url` 必须写成完整的 `/v1/chat/completions` 路径，写成 `https://aicentos.com/v1` 不会生效。
* 最外层必须是 `{"models": [...]}` 结构，`models` 是必填的顶层字段。
* `availableModels` 是白名单：一旦填写，模型下拉框只显示列表里的模型，内置模型会一起消失。不需要限制时请省略该字段。
* 文件请保存为 **UTF-8 无 BOM**，带 BOM 的 JSON 会导致读取本地模型配置失败。
* 环境变量在启动时解析；若变量不存在，配置文件里的 `${AICENTOS_API_KEY}` 会原样保留并导致调用失败。
* 建议把 `models.json` 权限设为 `600`，不要提交到版本库。
* 也可以用环境变量方式配置 CLI：`CODEBUDDY_API_KEY`、`CODEBUDDY_BASE_URL`、`CODEBUDDY_MODEL`。直接设置 `CODEBUDDY_BASE_URL` 时不要带 `/chat/completions`，CLI 会自行追加。
* 更多说明见文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

---

# Codebuff

来源: https://docs.aicentos.com/clients/codebuff

Language: zh-CN

> 在 Codebuff 命令行代理中接入 aicentos 的 OpenAI 兼容端点

Codebuff 是一个运行在终端里的 AI 编码代理，会按任务调度多个子代理来读取代码、制定计划并修改文件。默认情况下它连接官方托管服务；如果手上的版本支持覆盖 OpenAI 兼容端点，就可以通过环境变量把请求指向 aicentos。

## 先确认你的版本是否支持自定义端点

Codebuff 官方主推托管模式：登录后使用官方额度，或通过 `CODEBUFF_API_KEY` 使用官方 API。自定义 Base URL 并非所有版本都提供，请先确认：

* 运行 `codebuff --help`，看是否有 `--base-url`、`--provider` 之类的选项。
* 确认版本是否读取 `OPENAI_BASE_URL`（部分版本为 `CODEBUFF_BASE_URL`）来覆盖端点。
* 如果两者都不支持，说明当前版本只能走官方服务，无法直接接 aicentos。

## 准备工作

如果确认版本支持自定义端点，先在控制台「API Key」页面为 Codebuff 创建一个专用 Key（建议命名 `codebuff-cli`）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

同时确认本机已安装 Node.js，并已全局安装 Codebuff：

```bash
npm install -g codebuff
```

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| Base URL | `https://aicentos.com/v1` |
| API Key  | 控制台创建的 Key                |
| 模型       | 控制台「模型广场」中的模型名            |

## 配置步骤

* 把端点与密钥写入 shell 配置（`~/.zshrc` 或 `~/.bashrc`）：

```bash
export OPENAI_API_KEY="sk-你的aicentos密钥"
export OPENAI_BASE_URL="https://aicentos.com/v1"
```

* 重新加载配置：`source ~/.zshrc`。
* 进入项目目录，直接运行 `codebuff`。
* 如果版本支持 `--model` 参数，可在启动时显式指定模型；否则在交互界面里用模型选择命令切换。

部分版本把配置写在用户配置目录下的 JSON 文件中（凭据类文件默认权限为 `600`，不要提交到版本库）。若你的版本使用配置文件而非环境变量，请按 `codebuff --help` 或官方文档给出的字段名填写同样的 Base URL 与 Key。

## 测试

启动后先用一句简单提示词轻量测试，例如让它读一个文件并总结内容，确认能正常返回结果再正式使用。

## 注意事项

* 自定义端点属于进阶用法，字段名在不同版本间可能不一致；请以本机 `codebuff --help` 输出为准。
* `OPENAI_BASE_URL` 只填到 `https://aicentos.com/v1`，不要补成完整的 `/v1/chat/completions`。
* Codebuff 会把代码片段和终端输出作为上下文发送，使用前请确认这符合你所在团队的数据合规要求。
* 报错时依次检查：环境变量是否在当前终端生效、模型名是否与控制台一致、账户余额是否充足（[https://aicentos.com/wallet）。](https://aicentos.com/wallet）。)
* 更多说明见文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

---

# Codex CLI

来源: https://docs.aicentos.com/clients/codex-cli

Language: zh-CN

> 在 Codex CLI 中使用 aicentos —— 手动配置 config.toml 的 model_providers

Codex CLI 是 OpenAI 官方的命令行编码代理，通过 `~/.codex/config.toml` 定义模型供应商。把自定义 provider 指向 aicentos，即可在终端里使用 aicentos 接入的模型。

如果你更想用图形化方式管理多套配置，也可以走 [CC Switch](https://docs.aicentos.com/clients/cc-switch) 一键切换；本文只讲手动配置。

## 准备工作

先在控制台「API Key」页面为 Codex CLI 创建一个专用 Key（建议命名 `codex-cli`，方便追踪用量）：

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 余额不足时充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

确认已安装 Codex CLI：

```bash
codex --version
```

## 需要填写的配置

| 字段           | 值                         |
| ------------ | ------------------------- |
| Provider ID  | `aicentos`                |
| Provider 名称  | `aicentos`                |
| API Key 环境变量 | `AICENTOS_API_KEY`        |
| Base URL     | `https://aicentos.com/v1` |
| 模型           | 控制台「模型广场」中的模型名            |

## 配置步骤

### 1. 设置 API Key 环境变量

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
```

需要永久生效就写进 `~/.zshrc` 或 `~/.bashrc`，然后 `source` 一下，并用 `echo $AICENTOS_API_KEY` 确认。

### 2. 编辑 config.toml

在 `~/.codex/config.toml` 中加入：

```toml
model = "你的模型名"
model_provider = "aicentos"

[model_providers.aicentos]
name = "aicentos"
base_url = "https://aicentos.com/v1"
env_key = "AICENTOS_API_KEY"
wire_api = "responses"
```

把 `你的模型名` 换成控制台「模型广场」中列出的模型名，可参考 [支持的模型](https://docs.aicentos.com/billing/models-list)。

### 3. 启动 Codex

```bash
codex
```

发一条简单请求，确认 provider 正常工作。

## 测试

```
codex exec "用一句话回答：1+1 等于几"
```

能正常返回内容即接入成功，返回的内容会消耗少量额度，可在控制台用量日志里核对。

## 注意事项

* **Base URL 只填到 `/v1`**，不要补成 `/v1/chat/completions` 的完整路径。
* `base_url`、`env_key` 等字段只在用户级 `~/.codex/config.toml` 生效。写在项目内的 `.codex/config.toml` 会被忽略，并可能出现启动警告。
* `wire_api` 填 `responses`，对应 aicentos 的 [Responses 接口](https://docs.aicentos.com/api/chat/openai/responses)。官方文档目前只支持该取值；若你的版本报 `unknown variant`，说明 CLI 过旧，建议先升级。
* `openai`、`ollama`、`lmstudio` 是保留的 provider ID，**不能**通过改写内置 `openai` 的 base\_url 来指向第三方网关，必须新起一个 provider 名（本文用的是 `aicentos`）。
* 排查顺序：模型名是否与控制台一致 → Base URL 是否只到 `/v1` → 环境变量在**启动 codex 的那个终端**里是否可见 → 账户余额是否充足。

## 相关链接

* [接入 Codex（CC Switch 方式）](https://docs.aicentos.com/clients/codex)

---

# Codex++

来源: https://docs.aicentos.com/clients/codex-plus

Language: zh-CN

> 用 Codex++ 增强启动器把 aicentos 的 GPT API 接入到你电脑上的 Codex，纯 API 模式、图形化配置，几分钟搞定

[Codex++](https://github.com/BigPizzaV3/CodexPlusPlus) 是面向 Codex App 的**外部增强启动器和管理工具**。它不修改 Codex App 的原始安装文件，而是通过外部 launcher 启动 Codex，并用 Chromium DevTools Protocol 注入增强脚本——所以可以放心用，不会动到你原来的 Codex。

本教程教你把 **aicentos 的 GPT API** 接入到电脑上的 Codex 里：全程在 Codex++ 的图形界面里点几下完成，不用手写 `config.toml`。

## 准备

* 一台电脑（Windows / macOS 都支持）
* 一个 [aicentos](https://aicentos.com) 账号，并在 [API Key 页面](https://aicentos.com/keys) 创建一个 Key，建议命名带上 `codex` 方便追踪用量

创建 Key 时注意它所属的**分组**，要和你下面填的模型在同一分组下，否则会提示无权限。

## 第一步：下载并安装 Codex++

打开官方 GitHub Releases 页面：[github.com/BigPizzaV3/CodexPlusPlus/releases](https://github.com/BigPizzaV3/CodexPlusPlus/releases)

Codex++ Releases 下载页

在最新版本里选择**对应你系统**的安装包，下载到本地，安装并打开。打开后看到的就是 Codex++ 管理工具：

Codex++ 管理工具界面

## 第二步：添加供应商

点击「**添加供应商**」，新建一条接入配置：

添加供应商

按下表填写：

| 字段   | 填什么                                                         |
| ---- | ----------------------------------------------------------- |
| 名称   | 中转站名字，自己能认出来就行（如 `aicentos`）                                |
| 接入模式 | **纯 API**                                                   |
| 配置模型 | 填 aicentos 支持的模型，**完整复制模型名**，多个用英文逗号隔开，例如 `gpt-5.5,gpt-5.4` |

## 第三步：填写 Codex 目标

在「Codex 目标」里**启用 ✅**，并填写下面两项：

| 字段       | 值                             |
| -------- | ----------------------------- |
| Base URL | `https://aicentos.com`        |
| Key      | 在 aicentos 令牌管理 生成的、对应分组的 Key |

填写 Base URL 和 Key

**上游协议**记得选 **chat completions**，不要用其它协议，否则请求会失败。

上游协议选 chat completions

填好后点击顶部的「**保存**」。

## 第四步：重启 Codex

保存后点击右上角「**重启**」，让配置生效：

重启 Codex

## 第五步：用 Key 登录

重启后，选择「**使用其他方式登录**」：

使用其他方式登录

把刚才在 [aicentos 令牌管理](https://aicentos.com/keys) 生成的那个 Key 粘贴进去，点「**继续**」：

粘贴 Key 并继续

到这里就接入完成了，可以直接开始使用 Codex。

## 排查问题

请求失败时，对照 Codex 输出和 [aicentos 控制台](https://aicentos.com) 的用量日志排查，常见原因：

* **模型名写错**：以 aicentos [支持的模型](https://docs.aicentos.com/billing/models-list) 为准，要完整复制模型名。
* **上游协议没选对**：必须是 **chat completions**。
* **Base URL 不对**：填 `https://aicentos.com`，首尾别带空格或多余路径。
* **提示 401 / 无权限**：检查 Key 是否复制完整，以及 Key 的分组是否包含你要用的模型；余额请到 [钱包](https://aicentos.com/wallet) 查看。

---

# Codex

来源: https://docs.aicentos.com/clients/codex

Language: zh-CN

> 在 Codex 中使用 aicentos —— CC Switch 一键导入，或手动配置 config.toml

Codex 兼容 OpenAI 协议，把模型提供商指向 aicentos 即可使用 aicentos 接入的全部模型。

下面提供两种接入方式：**用 CC Switch 一键管理**（推荐），或**手动编辑 config.toml**。

## 方式一：用 CC Switch（推荐）

CC Switch 同样支持管理 Codex 的 Provider 配置，多套配置一键切换。

详见 [接入 CC Switch →](https://docs.aicentos.com/clients/cc-switch)

## 方式二：手动配置

### 准备信息

| 项            | 值                         |
| ------------ | ------------------------- |
| Provider ID  | `aicentos`                |
| Provider 名称  | `aicentos`                |
| Base URL     | `https://aicentos.com/v1` |
| API Key 环境变量 | `AICENTOS_API_KEY`        |

先在控制台「API Key」页面创建一个专用 Key，建议命名里带上 `codex` 方便追踪用量。

### 设置 API Key

在终端配置环境变量：

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
```

持久化的话加到 `~/.zshrc` 或 `~/.bashrc`，然后重新加载：

```bash
source ~/.zshrc
```

确认变量已生效：

```bash
echo $AICENTOS_API_KEY
```

### 配置 Codex Provider

编辑 `~/.codex/config.toml`，加入：

```bash
model = "你的模型名"
model_provider = "aicentos"

[model_providers.aicentos]
name = "aicentos"
base_url = "https://aicentos.com/v1"
env_key = "AICENTOS_API_KEY"
wire_api = "responses"
```

把 `你的模型名` 换成控制台「模型广场」中列出的模型名，可参考 [支持的模型](https://docs.aicentos.com/billing/models-list)。

### 启动 Codex

```bash
codex
```

发一条简单请求，确认 Provider 正常工作。

## 排查问题

请求失败时，对照 Codex 终端输出和控制台用量日志排查。常见原因：

* 模型名写错（以模型广场为准）。
* Base URL 格式不对（只填到 `/v1`，不要多加路径）。
* 环境变量没被当前终端读取（重开终端或 `source` 配置文件）。

---

# Command Code

来源: https://docs.aicentos.com/clients/command-code

Language: zh-CN

> 在 Command Code 中使用 aicentos —— 通过 providers.json 添加 BYOK 供应商

Command Code 是终端里的编码代理，默认使用自带供应商，同时支持 BYOK：在 `~/.commandcode/providers.json` 里登记一个自定义供应商，把 baseURL 指向 aicentos 即可。

## 准备工作

先在控制台「API Key」页面为 Command Code 创建一个专用 Key（建议命名 `command-code`，方便追踪用量）：

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 余额不足时充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

## 需要填写的配置

| 字段      | 值                               |
| ------- | ------------------------------- |
| 配置文件    | `~/.commandcode/providers.json` |
| baseURL | `https://aicentos.com/v1`       |
| apiKey  | `$AICENTOS_API_KEY`             |
| 模型      | 控制台「模型广场」中的模型名                  |

## 配置步骤

### 1. 设置环境变量

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
```

写进 `~/.zshrc` 或 `~/.bashrc` 可持久化。

### 2. 编辑 providers.json

编辑 `~/.commandcode/providers.json`，在 `provider` 对象下增加一个条目：

```json
{
  "provider": {
    "aicentos": {
      "name": "aicentos",
      "api": "openai-completions",
      "baseURL": "https://aicentos.com/v1",
      "apiKey": "$AICENTOS_API_KEY",
      "models": {
        "gpt-4o": {}
      }
    }
  }
}
```

字段说明：

| 字段        | 说明                                                  |
| --------- | --------------------------------------------------- |
| `name`    | 显示名称，出现在 `/connect` 与 `/model` 中                    |
| `api`     | `openai-completions`（默认）或 `anthropic-messages`      |
| `baseURL` | 必填，API 根地址，需带 `/v1`                                 |
| `apiKey`  | 支持 `$VAR`、`{env:VAR}`、`!command`，或填 `false` 表示无鉴权端点 |
| `models`  | 必填，`{}` 即可，模型 ID 需与端点一致                             |

`models` 里的模型 ID 换成控制台「模型广场」中的名称，可参考 [支持的模型](https://docs.aicentos.com/billing/models-list)。

### 3. 选择供应商

进入 Command Code 后：

* 执行 `/connect`，选中 `aicentos` 并完成密钥确认；
* 执行 `/model`，选择要用的模型。

注意：**修改 `providers.json` 后需要重新打开 `/model`** 才会加载新配置。

## 测试

选好模型后发一句简单提示词：

```
用一句话回答：1+1 等于几
```

能正常返回即接入成功。也可以在 `/connect` 里对供应商按 `u`，让它调用端点的 `/models` 刷新模型列表。

## 注意事项

* Command Code 默认走 OpenAI 兼容的 Chat Completions，因此 `api` 填 `openai-completions` 即可。
* 若要用 Claude 系列模型，需另建一个 `api: "anthropic-messages"` 的供应商条目——两种协议的路径拼接方式不同（OpenAI SDK 追加 `/chat/completions`，Anthropic SDK 追加 `/v1/messages`），同一个 baseURL 无法同时服务两者。
* `baseURL` 必须带 `/v1`，Command Code 会自行拼接后续路径。
* 直接在 `apiKey` 里粘贴明文密钥会被拒绝，请使用 `$VAR` 形式。
* 排查顺序：`/model` 里能否看到模型 → 环境变量在启动终端中是否可见 → baseURL 是否只到 `/v1` → 余额是否充足。

## 相关链接

* BYOK 官方文档：[https://commandcode.ai/docs/byok](https://commandcode.ai/docs/byok)

---

# GitHub Copilot

来源: https://docs.aicentos.com/clients/copilot

Language: zh-CN

> 在 GitHub Copilot Chat 中通过自带 Key（BYOK）接入 aicentos 的 OpenAI 兼容端点

GitHub Copilot 在 VS Code 里提供了自带 Key（BYOK）能力，可以把对话请求指向自定义的 OpenAI 兼容端点。把端点设成 aicentos、填入在控制台创建的 Key，就能在 Copilot Chat / Agent 中使用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Copilot 创建一个专用 Key（建议命名 `copilot-vscode` 或 `copilot-work`，方便追踪用量）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

同时确认本机 VS Code 与 GitHub Copilot Chat 扩展已更新到支持自定义端点的版本；较旧的版本只有内置厂商的 BYOK，没有通用「自定义端点」入口。

## 需要填写的配置

| 字段           | 值                                                               |
| ------------ | --------------------------------------------------------------- |
| Provider     | Custom Endpoint（旧版本为 OpenAI Compatible）                         |
| Base URL     | `https://aicentos.com/v1`                                       |
| API 类型       | Chat Completions（对应 `https://aicentos.com/v1/chat/completions`） |
| API Key      | 控制台创建的 Key                                                      |
| Model ID     | 控制台「模型广场」中的模型名                                                  |
| Tool Calling | `true`（要在 Agent 模式使用则必须开启）                                      |

## 配置步骤

### 方式一：图形界面

* 打开 VS Code 的 Chat 视图。
* 点击输入框上方的模型选择器，选择 **Manage Language Models**（旧版本为 **Manage Models...**）。
* 点击 **Add Models**，在提供商列表中选择 **Custom Endpoint**（旧版本为 **OpenAI Compatible**）。
* 输入分组名和 API Key。
* API 类型选择 **Chat Completions**。
* 按提示补全模型信息：`id` 填控制台中的模型名，`url` 填 `https://aicentos.com/v1/chat/completions`。
* 保存后回到 Chat，在模型下拉框中选中刚添加的模型。

### 方式二：settings.json

在命令面板执行 **Preferences: Open User Settings (JSON)**，加入：

```json
{
  "github.copilot.chat.customOAIModels": {
    "aicentos-gpt": {
      "name": "aicentos GPT",
      "url": "https://aicentos.com/v1/chat/completions",
      "toolCalling": true,
      "vision": false,
      "maxInputTokens": 128000,
      "maxOutputTokens": 16384
    }
  }
}
```

对象最外层的 key（如 `aicentos-gpt`）就是你在模型选择器里看到的模型 ID，必须是唯一的。

参考官方文档：[https://code.visualstudio.com/docs/copilot/customization/language-models](https://code.visualstudio.com/docs/copilot/customization/language-models)

## 测试

保存设置后，在 Chat 里新建一个对话，先用一句简单提示词轻量测试一下，能正常返回就说明接通了，再正式使用 Agent / Edit 模式。

## 注意事项

* BYOK 只作用于 **Chat / Agent / Edit**，不覆盖内联代码补全（Tab 补全）；语义搜索、embedding 等能力仍走 Copilot 自带服务。
* 想在 **Agent** 模式里使用，模型必须支持 **tool calling**，`toolCalling` 需要设为 `true`；否则该模型不会出现在模型选择器中。
* `url` 字段要填完整的 `https://aicentos.com/v1/chat/completions`，不要只填到 `/v1`。
* `github.copilot.chat.customOAIModels` 是旧写法，新版本已改用 `chatLanguageModels.json` 配合 `customendpoint`；请以你当前 VS Code 版本的实际入口为准。
* 使用 GitHub Copilot Business / Enterprise 时，管理员可能通过策略关闭 BYOK。
* 模型添加后如果没立刻出现，重启一次 VS Code。
* 报错时依次检查：Key 是否有多余空格、模型名是否与控制台一致、账户余额是否充足、API 类型是否选对。余额不足可前往 [https://aicentos.com/wallet](https://aicentos.com/wallet) 充值。

---

# Craft Agent

来源: https://docs.aicentos.com/clients/craft-agent

Language: zh-CN

> 在 Craft Agent 里接入 aicentos —— 自定义 OpenAI 兼容连接，桌面端与 craft-cli 通用

Craft Agent 的 LLM 连接支持 `Custom` 类型，官方描述是「任意 URL，任意 OpenAI 兼容或 Anthropic 兼容端点」。把 Base URL 指向 aicentos，桌面端和 `craft-cli` 都能走。

## 准备工作

先在控制台为 Craft Agent 建一个专用 Key（建议命名 `craft-agent`），方便按 Key 看用量。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

安装桌面端：

```bash
curl -fsSL https://thecraftagents.com/install-app.sh | bash
```

也支持 headless server 和纯命令行用法。

## 需要填写的配置

| 字段       | 值                                                                          |
| -------- | -------------------------------------------------------------------------- |
| 连接类型     | Custom（自定义）                                                                |
| 协议       | `openai-completions`，或 `anthropic-messages`                                |
| Base URL | `https://aicentos.com/v1`（OpenAI 兼容）/ `https://aicentos.com`（Anthropic 兼容） |
| API Key  | 控制台创建的 Key                                                                 |
| 模型       | 控制台「模型广场」中的模型名                                                             |

## 配置步骤

桌面端：打开设置里的 LLM 连接，新增一条，类型选 Custom，按上表填写。

命令行等价写法：

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
craft-cli run --provider openai \
  --base-url https://aicentos.com/v1 \
  --api-key "$AICENTOS_API_KEY" \
  --model 你的模型名 \
  "你好"
```

也可以直接改配置文件 `~/.craft-agent/config.json`：

```json
{
  "llmConnections": [
    {
      "providerType": "pi_compat",
      "baseUrl": "https://aicentos.com/v1",
      "customEndpoint": { "api": "openai-completions" },
      "models": [{ "id": "你的模型名" }],
      "defaultModel": "你的模型名"
    }
  ]
}
```

密钥不写在明文配置里，存在同目录的 `credentials.enc`。用界面填一次即可，不要手改这个文件。

## 测试

```bash
craft-cli run --provider openai \
  --base-url https://aicentos.com/v1 \
  --api-key "$AICENTOS_API_KEY" \
  --model 你的模型名 \
  "用一句话自我介绍"
```

能正常返回即通。再回控制台看用量，确认请求记到了这个 Key 上。

## 注意事项

* `providerType` 保持 `pi_compat`，这是它的自定义端点标识；改成内置 provider 的名字会走官方模型。
* `models` 要手填，它不会自动拉模型列表。名字必须与控制台「模型广场」完全一致（参考 [支持的模型](https://docs.aicentos.com/billing/models-list)）。
* 走 Anthropic 兼容端点时 Base URL 是 `https://aicentos.com`，不带 `/v1`，`--provider` 改成 `anthropic`。
* 桌面端的菜单位置随版本变化，找不到时以 `config.json` 的写法为准。

## 相关链接

* [Craft Agents 文档](https://thecraftagents.com/docs)
* [craft-agents 仓库](https://github.com/craft-ai-agents/craft-agents-oss)

---

# Crush

来源: https://docs.aicentos.com/clients/crush

Language: zh-CN

> 在 Crush 中使用 aicentos —— 通过 crush.json 添加自定义 provider

Crush 是 Charmbracelet 出品的终端编码代理，用 Go 编写，支持在 `crush.json` 里声明任意 OpenAI 兼容的自定义 provider。把 base\_url 指向 aicentos，即可在 TUI 里使用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Crush 创建一个专用 Key（建议命名 `crush`，方便追踪用量）：

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 余额不足时充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

确认已安装 Crush：

```bash
crush --version
```

## 需要填写的配置

| 字段        | 值                            |
| --------- | ---------------------------- |
| 配置文件      | `~/.config/crush/crush.json` |
| type      | `openai-compat`              |
| base\_url | `https://aicentos.com/v1`    |
| api\_key  | `$AICENTOS_API_KEY`          |
| 模型        | 控制台「模型广场」中的模型名               |

## 配置步骤

### 1. 设置 API Key 环境变量

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
```

需要持久化就写进 `~/.zshrc` 或 `~/.bashrc`，然后 `source` 一下。

### 2. 编辑 crush.json

全局配置文件位于 `~/.config/crush/crush.json`（Windows 为 `%USERPROFILE%\AppData\Local\crush\crush.json`）；项目根目录下的 `.crush.json` 或 `crush.json` 会覆盖全局配置。

写入：

```json
{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "aicentos": {
      "type": "openai-compat",
      "base_url": "https://aicentos.com/v1",
      "api_key": "$AICENTOS_API_KEY",
      "models": [
        {
          "id": "gpt-4o",
          "name": "GPT-4o",
          "context_window": 128000,
          "default_max_tokens": 8192,
          "can_reason": true
        }
      ]
    }
  }
}
```

`models[].id` 必须与端点侧的模型 ID 完全一致，请以控制台「模型广场」为准，可参考 [支持的模型](https://docs.aicentos.com/billing/models-list)。

### 3. 选择模型

启动 `crush` 后，在 TUI 中按 `Ctrl+L`（或输入 `/model`），确认能看到 `aicentos` 及其模型。

## 测试

用非交互模式做一次快速验证：

```bash
crush run "用一句话回答：1+1 等于几"
```

需要看请求日志时加 `--debug`。如果出现 404，检查 `base_url` 是否已带 `/v1`。

## 注意事项

* **`type` 不要填 `openai`**。`openai` 是给真正走 OpenAI（或 Azure OpenAI）的代理用的；指向第三方兼容端点时必须填 `openai-compat`，否则会出现模型识别错误或 API 报错。
* `base_url` 填到 `/v1` 即可，不要带尾部斜杠。
* `api_key` 支持 `$VAR` 与 `$(command)` 展开，建议保持密钥在环境变量或密钥文件里，不要写死明文。
* 若接入的是 Anthropic 协议端点（`type` 为 `anthropic`），`base_url` 应止于 `/api`，Crush 会自行追加 `/v1/messages`，且需要额外声明 `extra_headers` 中的 `anthropic-version`。
* 已知问题：使用自定义 provider 时，TUI 里的 token 计数与费用统计可能显示为 0，这不影响实际请求与计费。
* 需要开启思考输出时，OpenAI 风格模型用 `"can_reason": true` 配合 `"reasoning_effort"`；Anthropic 风格模型用 `"think": true`。

## 相关链接

* 自定义 Provider 文档：[https://github.com/charmbracelet/crush](https://github.com/charmbracelet/crush)

---

# Cursor

来源: https://docs.aicentos.com/clients/cursor

Language: zh-CN

> 在 Cursor 中使用 aicentos —— 通过自定义 OpenAI 兼容设置接入

Cursor 支持自定义 OpenAI 兼容的 API，把 Base URL 指向 aicentos、填入 API Key，即可在 Chat / Composer 中使用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Cursor 创建一个专用 Key（建议命名 `cursor-desktop` 或 `cursor-work`，方便追踪用量）。

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| API Key  | 控制台创建的 Key                |
| Base URL | `https://aicentos.com/v1` |
| 模型       | 控制台「模型广场」中的模型名            |

## 配置步骤

* 打开 Cursor 设置（Settings）。
* 进入 **Models** 或 **API Keys** 区域。
* 找到 **OpenAI API Key** / 自定义 OpenAI 兼容设置 / **Base URL** 覆盖选项。
* 填入你在 aicentos 控制台创建的 API Key。
* 把 Base URL 设为：`https://aicentos.com/v1`
* 如需手动添加模型，填入控制台中的模型名（参考 [支持的模型](https://docs.aicentos.com/billing/models-list)）。
* 保存并点击 **Verify**，或直接新建一个对话测试。

## 测试

保存后，先用一句简单提示词轻量测试一下，确认通了再正式使用 Composer / Chat。

## 注意事项

* 自定义 API Key 通常只对标准对话模型生效。
* **Tab 补全**和部分 **Agent** 能力可能仍走 Cursor 自带服务。
* Verify 失败时，检查：Base URL 是否正确（只填到 `/v1`）、Key 是否有多余空格、模型是否可用、账户余额是否充足、是否已选中自定义 OpenAI Provider。

---

# Devin CLI

来源: https://docs.aicentos.com/clients/devin-cli

Language: zh-CN

> 在 Devin CLI 中使用 aicentos —— 通过 OpenAI 兼容配置接入

Devin CLI 是 Devin 的命令行客户端，支持通过环境变量或配置文件指定 OpenAI 兼容的 API 地址。把 Base URL 指向 aicentos、填入 API Key，即可在终端里使用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Devin CLI 创建一个专用 Key（建议命名 `devin-cli`，方便追踪用量）。

## 安装步骤

需要先安装 Node.js 18+ 和 npm：

```bash
node -v
npm -v
```

使用 npm 全局安装：

```bash
npm install -g devin-cli
```

安装完成后验证：

```bash
devin --version
```

## 配置步骤

支持环境变量与配置文件两种方式，环境变量优先级更高。

### 方式一：环境变量（推荐）

```bash
export DEVIN_BASE_URL="https://aicentos.com/v1"
export DEVIN_API_KEY="your_api_key_here"
```

永久生效需写入 `~/.zshrc` 或 `~/.bashrc`，然后执行 `source ~/.zshrc`。

### 方式二：配置文件

编辑 `~/.devin/config.json`：

```json
{
  "apiKey": "your_api_key_here",
  "baseURL": "https://aicentos.com/v1",
  "model": "gpt-4o"
}
```

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| API Key  | 控制台创建的 Key                |
| Base URL | `https://aicentos.com/v1` |
| 模型       | 控制台「模型广场」中的模型名            |

## 测试

配置完成后直接运行：

```bash
devin
```

在交互会话中发送一句简单提示词，能正常收到回复即接入成功。如果报鉴权错误，检查 `DEVIN_API_KEY` 是否正确、`DEVIN_BASE_URL` 是否带 `/v1` 后缀、账户余额是否充足。

## 注意事项

* Base URL 只填到 `/v1`，不要补成 `/v1/chat/completions` 的完整路径
* 环境变量与配置文件同时存在时，以环境变量为准
* 建议先用 `GET /v1/models` 确认可见模型，再填写 Model ID

---

# Devin Desktop

来源: https://docs.aicentos.com/clients/devin-desktop

Language: zh-CN

> 在 Devin Desktop 中使用 aicentos —— 通过自定义 OpenAI 兼容设置接入

Devin Desktop 是 Devin 的桌面客户端，支持自定义 OpenAI 兼容的 API 地址。把 Base URL 指向 aicentos、填入 API Key，即可在客户端中使用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Devin Desktop 创建一个专用 Key（建议命名 `devin-desktop`，方便追踪用量）。

## 安装步骤

前往 Devin 官方站点下载对应平台的安装包：

* macOS：下载 `.dmg` 并拖入「应用程序」
* Windows：下载 `.exe` 安装程序并运行
* Linux：下载 `.AppImage` 或 `.deb` 并按发行版方式安装

安装完成后启动应用，登录进入设置界面。

## 配置步骤

* 打开 **Settings**（设置）。
* 进入 **Models** 或 **AI Provider** 区域。
* 找到 **OpenAI Compatible** / **Custom Provider** / **Base URL** 覆盖选项。
* 填入你在 aicentos 控制台创建的 API Key。
* 把 Base URL 设为：`https://aicentos.com/v1`
* 如需手动添加模型，填入控制台「模型广场」中的模型名。
* 保存设置。

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| API Key  | 控制台创建的 Key                |
| Base URL | `https://aicentos.com/v1` |
| 模型       | 控制台「模型广场」中的模型名            |

## 测试

保存后新建一个对话或编码任务，用一句简单提示词测试，确认能正常返回结果即接入成功。

## 注意事项

* 不同版本的设置入口名称可能不同，关键是找到可编辑的 Base URL 选项
* Base URL 只填到 `/v1`，不要写成 `/v1/chat/completions` 完整路径
* 若版本只支持官方内置模型、无法修改 Base URL，则不能直接接入本网关
* Verify 失败时检查：Key 是否有多余空格、模型是否可用、账户余额是否充足

---

# Droid

来源: https://docs.aicentos.com/clients/droid

Language: zh-CN

> 在 Factory Droid 中使用 aicentos —— 通过 settings.json 注册自定义模型（BYOK）

Droid 是 Factory 推出的命令行编码代理，支持 BYOK：在 `~/.factory/settings.json` 里登记自定义模型，把 `baseUrl` 指向 aicentos 即可。Droid 要求模型上下文窗口至少 64k，选型时留意。

## 准备工作

先在控制台「API Key」页面为 Droid 创建一个专用 Key（建议命名 `droid`，方便追踪用量）：

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 余额不足时充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

## 需要填写的配置

| 字段       | 值                             |
| -------- | ----------------------------- |
| 配置文件     | `~/.factory/settings.json`    |
| provider | `generic-chat-completion-api` |
| baseUrl  | `https://aicentos.com/v1`     |
| apiKey   | `${AICENTOS_API_KEY}`         |
| 模型       | 控制台「模型广场」中的模型名                |

## 配置步骤

### 1. 设置 API Key 环境变量

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
```

写进 `~/.zshrc` 或 `~/.bashrc` 可持久化。

### 2. 编辑 settings.json

编辑 `~/.factory/settings.json`，新增 `customModels` 数组：

```json
{
  "customModels": [
    {
      "model": "gpt-4o",
      "displayName": "GPT-4o (aicentos)",
      "baseUrl": "https://aicentos.com/v1",
      "apiKey": "${AICENTOS_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192
    }
  ]
}
```

关键字段：

| 字段            | 说明                                                     |
| ------------- | ------------------------------------------------------ |
| `model`       | 实际发往端点的模型 ID，需与控制台「模型广场」一致                             |
| `displayName` | 模型选择器中的显示名，可自定义                                        |
| `baseUrl`     | API 地址，建议带 `/v1`                                       |
| `apiKey`      | 支持 `${VAR_NAME}` 展开                                    |
| `provider`    | `anthropic` / `openai` / `generic-chat-completion-api` |

### 3. 选择模型

启动 `droid` 后执行 `/model`，选中刚才注册的模型。**修改配置后需要在新终端里重启 `droid`** 才会重新读取文件。

## 测试

选中模型后发一条简单请求：

```
用一句话回答：1+1 等于几
```

能正常返回即接入成功。

## 注意事项

* **`provider` 建议填 `generic-chat-completion-api`**，它走 OpenAI Chat Completions 协议，也是大多数 BYOK 场景的正确选择。填 `openai` 会走 Responses API，且部分网关下该取值会忽略 `base_url` 直接指向 `api.openai.com`；填 `anthropic` 则走 `/v1/messages`。
* **先清理环境变量**。如果 shell 里导出了 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL` 或 `ANTHROPIC_API_KEY`，它们会覆盖配置文件，导致请求绕过你配置的网关。接入前建议 `unset` 这几个变量。
* Droid 同时读取 `~/.factory/settings.json` 与旧版 `~/.factory/config.json`，前者优先。旧版的字段名是蛇形的 `custom_models` / `model_display_name` / `base_url` / `api_key`，且**不支持** `${VAR_NAME}` 展开，建议统一用 `settings.json`。
* 模型上下文窗口至少 64k，过小的本地模型表现可能异常。
* Factory 只对官方 Anthropic / OpenAI 接口做基准测试，自定义模型的兼容性不作保证；已知子代理（subagent）有时会回落到 Anthropic 官方接口。
* 排查顺序：`/model` 里能否看到模型 → 环境变量是否被 ANTHROPIC\_\* 覆盖 → baseUrl 是否带 `/v1` → 余额是否充足。

## 相关链接

* BYOK 官方文档：[https://docs.factory.ai/model-independence/byok](https://docs.factory.ai/model-independence/byok)

---

# DSH 大肥鱼

来源: https://docs.aicentos.com/clients/dsh

Language: zh-CN

> 在 DeepSeek Harness（DSH）里接入 aicentos 模型，养一条自己刷 B 站和抖音的大肥鱼，再把它接进 QQ 群

DSH（DeepSeek Harness）是 DeepSeek 开源的 Agent 框架，桌面端 DSH Desktop 把运行时、插件和会话打包成一个安装包。「大肥鱼」是社区给它写的插件 `dsh-bili-whale`：一条按作息自己醒来、刷 B 站、看懂视频、写两本日记、把值得看的挑出来 @ 你的 AI 鱼。

本文分四段：先把 DSH 的模型接到 aicentos，再养 B 站的大肥鱼，然后是抖音版，最后用官方插件把它接进 QQ 单聊和群聊。插件分别由社区和腾讯维护，与 B 站、抖音、DeepSeek 官方均无隶属关系。

## 准备工作

| 项                | 要求  | 说明                                         |
| ---------------- | --- | ------------------------------------------ |
| DSH Desktop      | 必装  | 官网下载 macOS / Windows 安装包，自带运行时             |
| Node.js          | 18+ | 只有命令行方式启动 DSH 时才需要；插件工具链是 `.mjs`，要真 node 跑 |
| ffmpeg           | 可选  | 只有「抽帧看画面」用得到；没装也能用字幕、弹幕、热评看懂视频             |
| B 站账号            | 一个  | 大肥鱼自己用的号，登录后取 cookie；建议用小号                 |
| aicentos API Key | 一个  | 建议单独建一个 Key（命名 `dsh`），方便按项目核算用量            |

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

## 需要填写的配置

| 字段           | 值                         |
| ------------ | ------------------------- |
| Provider ID  | `aicentos`                |
| Display name | `aicentos`                |
| Base URL     | `https://aicentos.com/v1` |
| API protocol | `openai-completions`      |
| API Key      | 控制台创建的 Key                |
| Model        | 控制台「模型广场」中的模型名            |

## 配置步骤

### 安装 DSH Desktop

打开 [https://www.dshdesktop.com/](https://www.dshdesktop.com/) ，按系统选安装包（Windows、macOS M 芯片、macOS Intel），下载完双击安装。首次启动按引导走：配置模型 → 新建会话，能正常对话就绪。

### 在 DSH 里接入 aicentos

推荐用界面配置：

1. 打开 **Settings → Models**，点 **Add a custom provider**。
2. 按上表填写 Provider ID、Display name、Base URL、API protocol、API Key。
3. 在 **Model catalog** 点 **Fetch available models**，勾选要用的模型；拉不到就手动填模型 ID。
4. 点 **Save**，回到对话界面，在顶部模型选择器里选中该模型。

也可以直接改 `~/.dsh/settings.yaml`：

```yaml
agent-default-model:
  provider: aicentos
  model: 你的模型名

llm-pi-ai:
  providers:
    aicentos:
      api: openai-completions
      baseURL: https://aicentos.com/v1
      apiKeyEnv: AICENTOS_API_KEY
      models:
        - id: 你的模型名
```

对应设置环境变量后启动：

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
```

API Key 保存后存在本地 `$DSH_HOME/.credentials.yaml`，界面不回显明文。

### 安装大肥鱼插件

不用手动 clone，直接在 DSH 对话框里发一句：

```bash
帮我安装这个插件，插件地址：https://github.com/Alterssss/dsh-bili-whale
```

装完刷新一下 DSH 页面，左侧 **设置 → 养鱼** 就能看到插件设置页。如果没看到「养鱼」入口，先完全退出 DSH 再重新打开：插件在启动时组装，不重启等于没装。

### 给会话完全权限

这一步最容易漏。她的会话在左侧 **工作区 → 未分组** 里（不展开那个文件夹看不见）。点开会话，把权限切到 **完全权限**（`danger-full-access`），否则她醒来后跑不了命令、发不了评论、写不了日记。

### 登录 B 站账号

在 **设置 → 养鱼 → B 站登录** 里点 **扫码登录**，用手机 B 站 App 扫码确认，二维码约 3 分钟有效。扫码取消或过期都不会替换原登录态，重新生成即可。

也可以手动填 cookie：浏览器登录大肥鱼用的那个号，按 F12 打开开发者工具，选 **Application → Cookies → `https://www.bilibili.com`**，复制 `SESSDATA`、`bili_jct`、`buvid3` 三个值逐个粘贴，再点 **写入凭据**。

不要用 `document.cookie` 取 cookie。`SESSDATA` 是 HttpOnly，脚本读不到，照那个做会得到一份缺件的 cookie，然后一直卡在体检。

### 依赖体检

点设置页的 **依赖体检**。它会真的请求一次 B 站验证登录态，并逐项检查 cookie、ffmpeg、Node、数据目录、生物钟，缺哪项就说哪项，全绿（「全部可用 ✓」）才算过关。

提示缺 ffmpeg 时不用自己翻教程装，直接在 DSH 对话里发一句「在电脑上安装 ffmpeg」，让它自己处理，装完回头再跑一次体检。

改完一定要点 **保存**。设置页输入框是先改在本地、点保存才落盘，页面上也会提示「有改动还没保存 = 没生效」。保存即生效；只有换插件代码或版本才需要重启 DSH。

### 设置人设与作息

* **她是谁**：角色名、怎么称呼你、她怎么自称。
* **她的人设**：正文写进 `~/.bili-ai/persona.md`，写完点 **注入人设**（上限 20000 字，注入时只取前 3000 字，每次唤醒和监听都会附上）。
* **你（主人）**：填你的 `mid`，@ 和私信都认这个。
* **分享方式**：评论区 @ 你，或 B 站私信。
* **作息窗口**：默认 20:00–24:00，窗口内随机一个时刻醒来，不是整点。

插件不内置任何人格，默认是中性助手：不叫你「主人」、不撒娇。想让她是「大肥鱼」，就在人设正文里写清身份与来历、说话腔调、在意什么、明确不要的行为。

## 测试

先在命令行跑一次自测，它把配置、凭据、登录态、数据目录、依赖一次全查：

```bash
node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs selftest
```

Windows 把路径换成 `%USERPROFILE%\.dsh\plugins\dsh-bili-whale\tools\bili.mjs`：

```powershell
node "$env:USERPROFILE\.dsh\plugins\dsh-bili-whale\tools\bili.mjs" selftest
```

逐项打勾、最后一句「全部通过 ✓ 可以用了」就算就绪。常用命令：

```bash
node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs deps           # 依赖体检
node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs dm --status    # 私信额度 + 互关状态
node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs traffic status # 请求保护值
```

想立刻看她跑一轮：设置页 **生物钟** 里把作息窗口改成现在之后 2 分钟的一小段，保存，等她醒来（体检 → 选题 → 看懂 → 写两本日记 → 推给你）。也可以直接在对话里让她醒过来刷一次 B 站。

最后回到 aicentos 控制台的用量页，确认请求记在了你给 DSH 建的那个 Key 上。

## 接入抖音

抖音版是同一套玩法的另一个项目：`dsh-douyin-scroll`。它不看画面，只读文案、标签、作者、时长、互动数和高赞评论，每天挑几条写一份 Markdown 日报。

### 安装

```bash
git clone https://github.com/NEWJO123/dsh-douyin-scroll.git
cd dsh-douyin-scroll
node selfcheck.mjs
```

预检全过再装到 `web` profile，装完重启一次 DSH：

```bash
dsh plugin --profile web add "link:$PWD"
```

重启后进 **设置 → 刷抖音**。

### 首次配置

1. 点 **装主依赖**：它建独立 venv 并装 `curl_cffi`、`httpx`（约 30 秒，进度看 `install.log`）。
2. 登录：`node tools/qr-login.mjs start` 扫码，或在设置页把浏览器里已登录抖音的 Cookie 粘进去。
3. 填「刷什么」：关键词、分类、指定作者、每天几条、每次筛几个，然后点 **现在跑一轮**。

Cookie 存在本机 `$DSH_HOME/douyin-duty/douyin_cookie.txt`，不进日志、不上传任何服务器。

### 能力与限制

| 项    | 说明                                      |
| ---- | --------------------------------------- |
| 判断依据 | 文案、标签、作者、时长、互动比值、高赞评论；不看画面、不做语音识别       |
| 取候选  | 只读推荐流 + 热榜；抖音 web 没有可用搜索接口，关键词只写进报告当标注  |
| 日报   | 写到 `out/<日期>.md`，可选 Windows 通知或 webhook |
| 发送   | 私信、分享卡片、评论默认全关，且都要 `confirm` 才发         |
| 群聊   | 作者的观察是「群里可能发不出消息」，换个号不一定一样              |

纯文本网址在抖音里点不开，只有分享卡片能点；发私信、卡片、评论要装 Chrome（只找 `chrome.exe`，不找 Edge），取候选和写日报不需要。频繁评论会触发风控，判断准确率也低于 B 站版——没有字幕，只能读观众反应。

## 接入 QQ 群

QQ Bot 有官方插件 `@tencent-connect/dsh-qqbot`，装进独立的 `qqbot` profile，扫码绑定后就能在 QQ 单聊和群聊里对话。

```bash
npx @deepseek-ai/dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot
npx @deepseek-ai/dsh --profile qqbot
```

首次启动按提示扫码绑定，不需要手动配密钥。绑定后：

* **会话隔离**：每个单聊、每个群聊各自独立上下文，不会串线，重启后自动恢复。
* **切换模型**：在聊天里直接切，切换后原有上下文保留，不用重新开始。
* **安静模式**：设成「@ 机器人才响应」，避免频繁回复打扰群聊。

模型要在 `qqbot` 这个 profile 里配：同样打开 **Settings → Models → Add a custom provider**，按前面的表格填 aicentos。想统一管多个 IM 渠道，可以看社区 bundle `dsh-im`，一个 bundle 管十个渠道、支持多机器人和流式回复。

群里的对话会被读进上下文交给模型，别在群里让它处理账号、密钥这类敏感内容；绑定凭据保存在本地 profile 里，别把整个 profile 目录同步到公开仓库。

## 桌面桌宠与评论区清理

两个可选插件，和大肥鱼不是同一个项目：

| 用途            | 项目                                                                                     | 安装方式                                                                   |
| ------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| 桌面上的动态大肥鱼     | [https://github.com/QCYTSN/dsh-dafeiyu](https://github.com/QCYTSN/dsh-dafeiyu)         | 同样把地址发给 DSH 让它装；桌面上出现透明原生窗口，可拖动，按任务状态切换动画                              |
| 清理评论区疑似 AI 账号 | [https://github.com/liyupi/dafeiyu-cleaner](https://github.com/liyupi/dafeiyu-cleaner) | 浏览器扩展：下载 Releases 的 zip 解压，打开 `chrome://extensions`，开启开发者模式，加载已解压的扩展程序 |

清理插件只在你自己的浏览器里隐藏评论，不删任何人的评论、不自动举报，误判可以放回；离线规则识别率约 85%，这是单一评论区的测试口径，换个社区不一定成立。

## 注意事项

* **自动评论先别开。** 插件默认关闭，开启后每轮只发 1 条、上限 20 条、同一视频只评一次；即便如此，公开刷屏也会变成别人眼里的「鱼灾」。建议先用 B 站私信把内容发给自己。
* **私信通道要双号。** 分享方式选 B 站私信，需要两个不同账号且双方互关（`relation.attribute === 6`）；只有一个号时，看视频、写日记、生成报告照常可用，私信做不到。
* **授权用小号。** 插件用你自己的账号说话，别把主号 cookie 交给第三方插件，也不要去买来源不明的账号。
* **撞风控立刻停。** 遇到 412 / 429、验证码、限流，插件会暂停 5–30 分钟并报告；不要连续重试，签名接口也不能保证绕过平台限制。
* **模型选便宜的。** 她每天要筛 5 条、深读 2–3 条、写两本日记，一轮下来是多次请求。建议在 aicentos 里选单价低、上下文够用的模型（参考[支持的模型](https://docs.aicentos.com/billing/models-list)），并给 DSH 单独建 Key 便于核算成本。
* **无界面模式跑不起来。** 插件必须挂在带网页界面的 DSH 上，否则会一直停在 `pending (waiting for services: sessionController, webServer, connection)`。
* 插件是个人自用工具的公开版，与 B 站、DeepSeek 官方无隶属关系；用你自己的账号做事，后果自负，请遵守平台社区规范。

## 相关链接

* [dsh-bili-whale 插件仓库](https://github.com/Alterssss/dsh-bili-whale)
* [dsh-douyin-scroll 插件仓库](https://github.com/NEWJO123/dsh-douyin-scroll)
* [QQ 机器人官方文档](https://bot.qq.com/wiki/agent-qqbot/)
* [DSH Desktop 官网](https://www.dshdesktop.com/)
* [DSH Desktop 源码](https://github.com/dataelement/dsh-desktop)
* [插件更新记录](https://github.com/Alterssss/dsh-bili-whale/blob/main/CHANGELOG.md)
* [aicentos 支持的模型](https://docs.aicentos.com/billing/models-list)

---

# Freebuff

来源: https://docs.aicentos.com/clients/freebuff

Language: zh-CN

> Freebuff 不需要 API Key，也没有自定义端点配置 —— 说明原因与替代方案

Freebuff 的卖点是「不用订阅、不用额度、不用 API Key」，模型来自内置目录，成本由它自己的账号体系承担。因此它**没有 Base URL 与 Key 的配置项**，无法接入 aicentos。

## 为什么不能直接接入

官方 README 明确写 `No subscription, credits, or API key required`，配置里也没有 `baseUrl`、`apiKey` 一类字段。

它的桌面版可以托管本机已装好的 Claude Code、Codex，并复用那些工具自己的 provider 账号——但那是**被托管的 CLI** 在决定模型，不是 Freebuff 自己的模型配置。想借这条路走 aicentos，要去被托管的 CLI 里配（见 [Claude Code](https://docs.aicentos.com/clients/claude-code)、[Codex CLI](https://docs.aicentos.com/clients/codex-cli)）。

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| API Key  | 控制台创建的 Key                |
| Base URL | `https://aicentos.com/v1` |
| 模型       | 控制台「模型广场」中的模型名            |

上表是 aicentos 侧的通用参数，供下面的替代方案使用。

## 替代方案

* 要终端编码代理：[Craft Agent](https://docs.aicentos.com/clients/craft-agent)、[Gajae Code](https://docs.aicentos.com/clients/gajae-code)、[Oh My Pi](https://docs.aicentos.com/clients/oh-my-pi)。
* 要免费额度先试水：用控制台的试用额度，确认模型合适再换到支持自定义端点的客户端。
* 只想用它的桌面壳托管别的 CLI：在 Claude Code / Codex CLI 侧配好 aicentos 即可。

## 测试

换到任一替代客户端后，发一句提示词确认连通，再回控制台核对用量。

## 注意事项

* 「免费」意味着模型不可选，也换不了供应商，别按「可配置」的思路去找设置项。
* 官方说明提到部分受限区域、或开 VPN 时会被限流。

## 相关链接

* [Freebuff CLI](https://freebuff.com/cli)
* [freebuff 仓库](https://github.com/CodebuffAI/freebuff)

---

# Fx

来源: https://docs.aicentos.com/clients/fx

Language: zh-CN

> 在 Fx 中使用 aicentos —— 通过用户级 settings.json 添加自定义模型连接

Fx 是 Vercel Labs 出品的编码代理，用 Zig 写成单个原生二进制，模型无关。自定义模型连接定义在用户级的 `~/.fx/settings.json` 中，把 base URL 指向 aicentos 即可。

**先说明一个容易踩的坑：** 项目根目录里的 `.fx.json` 是另一回事，它刻意不允许多数字段（包括模型），防止克隆下来的仓库把你的模型或端点换掉。**自定义端点必须写在 `~/.fx/settings.json`**，写在 `.fx.json` 里不会生效。

## 准备工作

先在控制台「API Key」页面为 Fx 创建一个专用 Key（建议命名 `fx`，方便追踪用量）：

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 余额不足时充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

确认已安装 Fx：

```bash
curl -fsSL https://fx.sh/setup.sh | bash
fx --version
```

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| 配置文件     | `~/.fx/settings.json`     |
| Base URL | `https://aicentos.com/v1` |
| API Key  | 控制台创建的 Key                |
| 模型       | 控制台「模型广场」中的模型名            |

## 配置步骤

### 1. 编辑用户级设置

在 `~/.fx/settings.json` 中按「自定义模型连接」的格式登记一个连接。连接对象的字段结构以官方文档为准：

* 文档入口：[https://fx.sh/docs](https://fx.sh/docs)
* README：[https://github.com/vercel-labs/fx](https://github.com/vercel-labs/fx)

把连接里的 API 地址填为：

```
https://aicentos.com/v1
```

API Key 填控制台创建的那一个，模型名以控制台「模型广场」为准。

### 2. 指定使用该连接

Fx 允许在启动时指定 provider 与模型：

```bash
fx provider local FX_MODEL=gpt-4o fx ask "用一句话回答：1+1 等于几"
```

也可以用环境变量指定：

```bash
export FX_MODEL="gpt-4o"
```

### 3. 确认当前 provider

Fx 会按 provider 记住选择，下次启动沿用上次的 provider。

## 测试

先用一条无副作用的提示词验证连通：

```bash
fx ask "用一句话回答：1+1 等于几"
```

能正常返回即接入成功。若报鉴权错误，优先检查 base URL 是否带 `/v1`、API Key 是否有多余空格。

## 注意事项

* **不要改 `.fx.json`**。项目级文件只允许 `provider_order`、`provider_strict` 等少数几个字段，没有 `model` 字段，也不用于配置自定义端点。
* `provider_order` / `provider_strict` 是 Vercel AI Gateway 的路由参数，**只对 Gateway 请求生效，自定义模型连接会忽略它们**，不要指望用它切换上游。
* Fx 官方对自定义模型连接的支持仍在演进中，早期版本可能需要较新的构建才能识别；升级后先跑一次上面的测试命令再正式使用。
* 该二进制安装脚本会从网络拉取，执行前请自行确认来源可信。

## 相关链接

* 项目主页：[https://github.com/vercel-labs/fx](https://github.com/vercel-labs/fx)

---

# Gajae Code

来源: https://docs.aicentos.com/clients/gajae-code

Language: zh-CN

> 在 Gajae Code（gjc）里接入 aicentos —— 在 models.yml 里加一个 OpenAI 兼容 provider

Gajae Code 的 provider 定义在 `~/.gjc/agent/models.yml`，字段是 `baseUrl` / `api` / `apiKey`，加一段就能指向 aicentos。

## 准备工作

先在控制台为 Gajae Code 建一个专用 Key（建议命名 `gajae-code`），然后安装 CLI：

```bash
curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/gajae-code/v0.15.3/scripts/install.sh -o gjc-install.sh
sh gjc-install.sh
gjc --version
```

## 需要填写的配置

| 字段                     | 值                         |
| ---------------------- | ------------------------- |
| provider 名             | 自取，例如 `aicentos`          |
| `baseUrl`              | `https://aicentos.com/v1` |
| `api`                  | `openai-completions`      |
| `apiKey` 或 `apiKeyEnv` | 直接写 Key，或写环境变量名           |
| `models[].id`          | 控制台「模型广场」中的模型名            |

## 配置步骤

编辑 `~/.gjc/agent/models.yml`：

```yaml
providers:
  aicentos:
    baseUrl: https://aicentos.com/v1
    api: openai-completions
    apiKeyEnv: AICENTOS_API_KEY
    discovery:
      type: openai-models-list
    models:
      - id: 你的模型名
        contextWindow: 128000
        maxTokens: 8192
```

把默认模型指过去：

```yaml
modelBindings:
  modelRoles:
    default: aicentos/你的模型名:high
```

然后导出 Key 再启动：

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
gjc
```

`discovery` 段让它自动拉取模型列表；如果你想手工控制可见模型，去掉这一段、只留 `models`。

## 测试

启动 `gjc`，在模型选择器里确认出现 `aicentos` 下的模型，发一句提示词确认能返回。列表为空时先查 `models.yml` 的缩进与 `discovery` 段。

## 注意事项

* `models.yml` 严格校验，未知字段直接报错。别从别的工具照抄 `api_key`、`base_url` 这种下划线写法，这里要求驼峰 `baseUrl`、`apiKey`。
* `contextWindow` 与 `maxTokens` 按实际模型填，写大了会被上游拒。
* `modelRoles.default` 里 `:high` 是推理强度后缀，按需改成其它档位或去掉。
* 项目自述 experimental，升级后字段可能变，以仓库 `docs/models.md` 为准。

## 相关链接

* [gajae-code 仓库](https://github.com/Yeachan-Heo/gajae-code)

---

# Gemini CLI

来源: https://docs.aicentos.com/clients/gemini-cli

Language: zh-CN

> 在 Gemini CLI 中使用 aicentos —— 通过环境变量配置自定义网关

Gemini CLI 是 Google 官方推出的命令行工具，支持通过环境变量配置自定义网关来接入 Codex Proxy 服务，实现在终端中与 Gemini 模型进行交互对话。

## 准备工作

Gemini CLI 通过 npm 全局安装，需要先准备好 Node.js 18+ 和 npm 环境。

### 安装 Node.js

* 访问 Node.js 官网下载页面：[https://nodejs.org/en/download](https://nodejs.org/en/download)
* macOS/Windows：下载并安装 LTS 版本
* Linux：按页面提供的发行版方式安装
* macOS（Homebrew 用户）：执行 `brew install node`

### 验证安装

```bash
node -v
npm -v
```

## 安装 Gemini CLI

使用 npm 全局安装 Gemini CLI：

```bash
npm install -g @google/gemini-cli
```

验证安装：

```bash
gemini --version
```

## 配置环境变量

Gemini CLI 支持通过以下三个环境变量接入自定义网关：

| 环境变量                     | 说明                     |
| ------------------------ | ---------------------- |
| `GOOGLE_GEMINI_BASE_URL` | 网关服务根地址，替换 Google 默认端点 |
| `GEMINI_API_KEY`         | 你的 API Key             |
| `GEMINI_MODEL`           | 默认使用的模型                |

### 配置示例

```bash
export GOOGLE_GEMINI_BASE_URL="https://aicentos.com"
export GEMINI_API_KEY="your_api_key_here"
export GEMINI_MODEL="gemini-2.0-flash"
```

### 注意事项

* `GOOGLE_GEMINI_BASE_URL` 填写服务根地址，不需要带具体接口路径
* 临时测试：直接在当前 shell 会话中执行上述 export 命令
* 永久生效：将 export 语句加入 `~/.zshrc` 或 `~/.bashrc`，然后执行 `source ~/.zshrc` 使其生效

## 启动 Gemini CLI

配置完成后，直接运行以下命令启动：

```bash
gemini
```

启动后即可在终端中与 Gemini 模型进行交互对话。

## 验证接入

在 Gemini CLI 中发起一次对话，如果能正常收到回复，说明接入成功。

### 常见问题排查

* 如果遇到鉴权错误，请确认 `GEMINI_API_KEY` 是否正确
* 检查 `GOOGLE_GEMINI_BASE_URL` 是否指向正确的服务地址

## 注意事项

* 当前服务已支持 Gemini 兼容接口，可直接用于 Gemini CLI
* 环境变量配置建议加入 shell 配置文件以实现永久生效
* Gemini CLI 会自动拼接 API 路径，无需在 BASE\_URL 中添加具体接口路径

## 相关链接

* 官方文档：[https://docs.aicentos.com/clients/gemini-cli.html](https://docs.aicentos.com/clients/gemini-cli.html)

---

# Goose

来源: https://docs.aicentos.com/clients/goose

Language: zh-CN

> 在 Goose 中使用 aicentos —— 声明自定义 OpenAI 兼容 provider

Goose 是 Block 开源的编码代理，支持两种方式指向一个 OpenAI 兼容端点：复用内置的 `openai` provider 并改写 host，或者声明一个独立的自定义 provider。推荐后者，端点信息更集中，也方便同时保留多套配置。

## 准备工作

先在控制台「API Key」页面为 Goose 创建一个专用 Key（建议命名 `goose`，方便追踪用量）：

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 余额不足时充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

## 需要填写的配置

| 字段              | 值                                                |
| --------------- | ------------------------------------------------ |
| 自定义 provider 文件 | `~/.config/goose/custom_providers/aicentos.json` |
| engine          | `openai`                                         |
| base\_url       | `https://aicentos.com/v1/chat/completions`       |
| api\_key\_env   | `AICENTOS_API_KEY`                               |
| 模型              | 控制台「模型广场」中的模型名                                   |

## 配置步骤

### 1. 设置 API Key 环境变量

```bash
export AICENTOS_API_KEY="sk-你的-API-Key"
```

写进 `~/.zshrc` 或 `~/.bashrc` 可持久化。**不要把密钥写进 config.yaml**，官方明确建议用环境变量或系统密钥链。

### 2. 声明自定义 provider

新建 `~/.config/goose/custom_providers/aicentos.json`（Windows 为 `%APPDATA%\Block\goose\config\custom_providers\`）：

```json
{
  "name": "aicentos",
  "engine": "openai",
  "display_name": "aicentos",
  "description": "aicentos 接入的模型",
  "api_key_env": "AICENTOS_API_KEY",
  "base_url": "https://aicentos.com/v1/chat/completions",
  "models": [
    {
      "name": "gpt-4o",
      "context_limit": 128000
    }
  ],
  "supports_streaming": true,
  "dynamic_models": true
}
```

必填字段为 `name`、`engine`、`display_name`、`base_url`、`models`，其中 `engine` 取 `openai` / `anthropic` / `ollama`。

模型名以控制台「模型广场」为准，可参考 [支持的模型](https://docs.aicentos.com/billing/models-list)。

### 3. 在 config.yaml 中设为默认

编辑 `~/.config/goose/config.yaml`：

```yaml
GOOSE_PROVIDER: aicentos
GOOSE_MODEL: gpt-4o
```

Goose 启动时会扫描 `custom_providers/` 目录并自动注册，之后也可以在图形界面里切换。

## 测试

先用非交互会话验证：

```bash
goose run -t "用一句话回答：1+1 等于几"
```

能正常返回即接入成功。

## 注意事项

* **`base_url` 要写到完整路径**（这里带 `/v1/chat/completions`），与多数客户端的写法不同。若需要显式指定路径，新版本还支持 `base_path` 字段，它的优先级高于 URL 解析。
* **环境变量优先级高于 config.yaml**。shell 里若已导出 `OPENAI_HOST`，会静默覆盖文件里的配置，排查时先 `env | grep -i openai`。
* 只有选中了 provider，Goose 才会正常启动。若在 `config.yaml` 里写了配置但从未执行 `goose configure`，可能报 `No provider configured` —— 这是常见误解，配置项本身是 YAML 格式，不是 `.env`。
* `dynamic_models: true` 时 Goose 会调用端点的 `/v1/models` 拉取模型列表；若只想暴露指定模型，删掉该字段或设为 `false`。
* 另一种简易做法是复用内置 provider：在 config.yaml 里设 `GOOSE_PROVIDER: openai`，再用 `OPENAI_HOST` 加 `OPENAI_BASE_PATH` 拼接端点。这种方式更省事，但与环境变量的耦合更强，容易踩到上面的覆盖问题。
* 排查顺序：provider 名与 JSON 文件名是否完全一致 → `base_url` 是否含完整路径 → 环境变量是否可见 → 余额是否充足。

## 相关链接

* 自定义 Provider 文档：[https://block.github.io/goose/docs/api/providers/custom](https://block.github.io/goose/docs/api/providers/custom)

---

# Grok Build

来源: https://docs.aicentos.com/clients/grok-build

Language: zh-CN

> 在 Grok Build 中接入 aicentos —— 通过 config.toml 自定义 model provider

Grok Build 是 xAI 的终端编程 Agent，默认调用 xAI 官方接口，但它支持在 `~/.grok/config.toml` 中声明任意 OpenAI 兼容的 `[model.*]` 端点。把端点指向 aicentos，就能用同一个 Key 调用 grok 系列及其它厂商的模型。

## 准备工作

* 安装 Grok Build（官方脚本）：

  ```bash
  curl -fsSL https://x.ai/cli/install.sh | bash
  ```

* 在 aicentos 控制台创建一个专用 Key（建议命名 `grok-build`）。

## 需要填写的配置

| 字段              | 值                                               |
| --------------- | ----------------------------------------------- |
| base\_url       | `https://aicentos.com/v1`                       |
| api\_backend    | `chat_completions`（默认值）                         |
| env\_key        | `AICENTOS_API_KEY`                              |
| model           | 控制台「模型广场」中的模型 ID，如 `grok-4.7`、`claude-opus-4-8` |
| context\_window | 按所选模型填写，如 `200000`                              |

## 配置步骤

* 把 Key 写入 shell 环境变量（写入 `~/.zshrc` 或 `~/.bashrc` 后 `source` 生效）：

  ```bash
  export AICENTOS_API_KEY="your_api_key_here"
  ```

* 编辑 `~/.grok/config.toml`，新增一个自定义模型：

  ```toml
  [models]
  default = "aicentos-grok"

  [model.aicentos-grok]
  base_url          = "https://aicentos.com/v1"
  env_key           = "AICENTOS_API_KEY"
  api_backend       = "chat_completions"
  context_window    = 200000
  max_completion_tokens = 8192
  description       = "aicentos gateway - grok-4.7"
  ```

  `[model.<name>]` 的 `<name>` 就是模型 ID；若要接入多个模型，例如 `grok-4.7` 与 `claude-opus-4-8`，分别再写一段 `[model.grok-4.7]`、`[model.claude-opus-4-8]`。

* 启动 Grok Build，用模型选择器或命令切换：

  ```bash
  grok
  /model aicentos-grok
  ```

## 测试

先列一下模型是否被识别：

```bash
grok models
```

再发一句轻量提示词（如 `grok -p "用一句话介绍当前目录" -m aicentos-grok`）确认能正常返回。

## 注意事项

* Grok Build **没有 `--base-url` 命令行参数**，自定义端点只能通过配置文件或环境变量指定。
* `api_backend` 默认即 `chat_completions`；若显式写成 `responses` 或 `messages`，需确认网关支持对应端点，否则会失败。
* 凭据解析顺序为：模型配置里的 `api_key` → `env_key` 指定的环境变量 → 已登录会话 token → 全局 `XAI_API_KEY`。这里用 `env_key` 引用自己的变量名即可，不会串到 xAI 官方账号。
* 新增模型若省略 `context_window`，Grok Build 默认按 200,000 处理；建议按所选模型显式填写。
* 接自定义端点后不再依赖订阅 xAI，但被选中的模型仍由 aicentos 侧计费，先到[钱包页](https://aicentos.com/wallet)确认余额。

---

# Grok CLI

来源: https://docs.aicentos.com/clients/grok-cli

Language: zh-CN

> 在 Grok CLI 中使用 aicentos —— 通过环境变量或配置文件接入

Grok CLI 是一个命令行工具，使用 OpenAI 兼容接口，可以直接将自定义 API 地址作为其后端服务接入。

## 准备工作

需要先安装 Node.js 18+ 和 npm。

推荐从 Node.js 官方下载页安装：[https://nodejs.org/en/download](https://nodejs.org/en/download)

* macOS/Windows：下载并安装 LTS 版本
* Linux：按发行版方式安装

macOS 用户也可以使用 Homebrew：

```bash
brew install node
```

安装完成后确认：

```bash
node -v
npm -v
```

## 安装 Grok CLI

使用 npm 全局安装：

```bash
npm install -g @vibe-kit/grok-cli
```

安装完成后验证：

```bash
grok --version
```

## 配置接入

Grok CLI 提供三种配置方式，优先级为：命令行参数 > 环境变量 > 配置文件。

### 方式一：环境变量（推荐）

设置以下环境变量：

```bash
export GROK_BASE_URL="https://aicentos.com/v1"
export GROK_API_KEY="your_api_key_here"
```

临时测试直接在当前 shell 执行 export 即可。永久生效需将上述语句加入 `~/.zshrc` 或 `~/.bashrc`，然后执行 `source ~/.zshrc` 使其生效。

### 方式二：配置文件

编辑 `~/.grok/user-settings.json`：

```json
{
  "apiKey": "your_api_key_here",
  "baseURL": "https://aicentos.com/v1",
  "defaultModel": "gpt-4o"
}
```

### 方式三：命令行参数

启动时通过参数指定：

```bash
grok --base-url https://aicentos.com/v1
```

## 启动使用

配置完成后，直接运行：

```bash
grok
```

启动后在 Grok CLI 中发起对话，如果能正常收到回复，说明接入成功。

## 验证与排查

如果遇到鉴权错误，请检查：

* `GROK_API_KEY` 是否正确
* `GROK_BASE_URL` / `baseURL` 是否指向正确的服务地址（需要带 `/v1` 后缀）

确认配置无误后重新启动即可。

## 注意事项

* Grok CLI 使用 OpenAI 兼容接口，配置简单直接
* 三种配置方式可以灵活选择，推荐使用环境变量方式
* API 地址必须包含 `/v1` 后缀
* 支持自定义默认模型

## 相关链接

* 官方文档：[https://docs.aicentos.com/clients/grok-cli.html](https://docs.aicentos.com/clients/grok-cli.html)

---

# Hermes Agent

来源: https://docs.aicentos.com/clients/hermes-agent

Language: zh-CN

> 在 Hermes Agent 中使用 aicentos —— 通过环境变量指定 OpenAI 兼容端点

Hermes Agent 通过环境变量读取模型服务的连接信息。把 Base URL 指向 aicentos，就能让 Agent 的所有推理请求走 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Hermes Agent 创建一个专用 Key（建议命名 `hermes-agent`，方便追踪用量）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)
* 文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

## 需要填写的配置

| 字段                | 值                         |
| ----------------- | ------------------------- |
| OPENAI\_BASE\_URL | `https://aicentos.com/v1` |
| OPENAI\_API\_KEY  | 控制台创建的 Key                |
| Model             | 控制台「模型广场」中的模型名            |

## 配置步骤

在运行 Agent 的同一个 shell 中设置：

```bash
export OPENAI_BASE_URL="https://aicentos.com/v1"
export OPENAI_API_KEY="sk-你的Key"
export OPENAI_MODEL="gpt-4o"
```

然后按平时的方式启动 Hermes Agent。永久生效请把上面的 `export` 写进 `~/.zshrc` 或 `~/.bashrc`，并重新 `source` 一次。

如果 Hermes Agent 提供了自己的配置文件，也可以在其中指定 base\_url / api\_key / model，效果等价；两者同时存在时以其自身优先级为准（通常环境变量更高）。

## 测试

启动后触发一次最简单的推理（例如让它回答一个常识问题），确认能收到回复。再检查控制台用量页面，确认请求确实记在了你给 Hermes Agent 建的那个 Key 上。

## 注意事项

* 环境变量必须在启动 Agent 的那个 shell 会话中可见，写到别的 shell 里不会生效。
* 如果你用 Docker 部署，记得把变量通过 `-e` 或 compose 的 `environment` 传进去，不要只写在宿主机上。
* Base URL 只填到 `/v1`。
* 部分 Agent 框架会优先读 `OPENAI_API_BASE`，若上面的变量不生效，补一个同名不同拼写的变量再试。
* 建议为 Agent 单独建 Key，便于按项目统计用量。

---

# Hindsight

来源: https://docs.aicentos.com/clients/hindsight

Language: zh-CN

> 给 Hindsight 记忆服务配 aicentos 的模型 —— 四个环境变量搞定，OpenAI 兼容

Hindsight 是开源的 agent 记忆系统，提供自托管服务、HTTP / MCP 接口、SDK 和 CLI。它自己不是聊天客户端，但**记忆提炼要用一个 LLM**，那个 LLM 可以指向 aicentos。

## 准备工作

先在控制台为 Hindsight 建一个专用 Key（建议命名 `hindsight`）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

Hindsight 服务端需要 PostgreSQL 14 及以上。它自带的 `pg0` 只适合开发，生产环境请接自己的实例。

```bash
pip install hindsight-api
```

## 需要填写的配置

| 环境变量                         | 值                         |
| ---------------------------- | ------------------------- |
| `HINDSIGHT_API_LLM_PROVIDER` | `openai`                  |
| `HINDSIGHT_API_LLM_BASE_URL` | `https://aicentos.com/v1` |
| `HINDSIGHT_API_LLM_API_KEY`  | 控制台创建的 Key                |
| `HINDSIGHT_API_LLM_MODEL`    | 控制台「模型广场」中的模型名            |

## 配置步骤

写进启动环境即可，不需要改代码：

```bash
export HINDSIGHT_API_LLM_PROVIDER="openai"
export HINDSIGHT_API_LLM_BASE_URL="https://aicentos.com/v1"
export HINDSIGHT_API_LLM_API_KEY="sk-你的-API-Key"
export HINDSIGHT_API_LLM_MODEL="你的模型名"

hindsight-api
```

用 Docker 部署时把这些变量放进 compose 的 `environment`。注意官方镜像不含 `llama.cpp`，别指望在容器里跑本地模型。

## 测试

```bash
curl -fsSL https://hindsight.vectorize.io/get-cli | bash
hindsight health
```

服务起来后写入一条记忆、再检索回来，能走通说明 LLM 调用正常。也可以直接看控制台用量：Hindsight 每提炼一次记忆都会产生一条请求。

## 注意事项

* `BASE_URL` 必须以 `/v1` 结尾，且上游要能服务 `/chat/completions`；写成 `https://aicentos.com` 会 404。
* 没配 LLM Key 时服务会拒绝启动，这是它的强制校验，不是 Key 填错。
* 记忆提炼是后台批处理，用量会随记忆条数增长，建议给 Hindsight 单独一个 Key 便于观察。
* `HINDSIGHT_API_LLM_PROVIDER` 填 `openai` 表示走 OpenAI 兼容协议，不是指只能用 OpenAI 模型。

## 相关链接

* [Hindsight 模型配置](https://hindsight.vectorize.io/developer/models)
* [hindsight 仓库](https://github.com/vectorize-io/hindsight)

---

# Jcode

来源: https://docs.aicentos.com/clients/jcode

Language: zh-CN

> 在 Jcode 中使用 aicentos —— 通过配置文件指定 OpenAI 兼容端点

Jcode 支持通过配置文件指定 OpenAI 兼容的 API 服务。把 Base URL 指向 aicentos、填入 API Key，即可在 Jcode 里使用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Jcode 创建一个专用 Key（建议命名 `jcode`，方便追踪用量）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)
* 文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| Provider | OpenAI Compatible         |
| Base URL | `https://aicentos.com/v1` |
| API Key  | 控制台创建的 Key                |
| Model    | 控制台「模型广场」中的模型名            |

## 配置步骤

* 打开 Jcode 的配置文件（通常位于用户配置目录下，形如 `~/.jcode/config.json`）。
* 新增一个 OpenAI 兼容的 provider 条目。
* `baseURL` / `baseUrl` 填：`https://aicentos.com/v1`
* `apiKey` 填控制台创建的 Key。
* `model` 填控制台「模型广场」中的模型名（参考 [支持的模型](https://docs.aicentos.com/billing/models-list)）。
* 保存后重启 Jcode 使配置生效。

参考结构：

```json
{
  "provider": "openai",
  "baseUrl": "https://aicentos.com/v1",
  "apiKey": "sk-你的Key",
  "model": "gpt-4o"
}
```

如果你的版本把配置放在 `~/.config/jcode/config.json`，改这个路径下的同名文件即可。

## 测试

重启后新建一个会话，发送一句简单提示词，能正常返回即接入成功。

## 注意事项

* 配置项命名（`baseUrl` / `base_url`）在不同版本间可能不同，以你本地配置模板中的字段名为准。
* Base URL 只填到 `/v1`，不要补成完整接口路径。
* 若 Jcode 版本不提供自定义 Base URL 入口，则该版本无法接入第三方端点，请改用其他支持自定义 Base URL 的客户端。
* Key 不要提交进版本库，必要时用环境变量引用。

---

# Junie

来源: https://docs.aicentos.com/clients/junie

Language: zh-CN

> 在 Junie CLI 中通过自定义模型 Profile 接入 aicentos

Junie 是 JetBrains 的编码代理，分为 IDE 插件和 Junie CLI 两种形态。**只有 Junie CLI 支持指向自定义端点**：它通过 `$JUNIE_HOME/models/` 下的 JSON profile 接入任意 OpenAI 兼容服务。IDE 插件目前不能指向自定义端点。

## 准备工作

先在控制台「API Key」页面为 Junie 创建一个专用 Key（建议命名 `junie-cli`）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

## 需要填写的配置

| 字段                             | 值                                          |
| ------------------------------ | ------------------------------------------ |
| `baseUrl`                      | `https://aicentos.com/v1/chat/completions` |
| `apiType`                      | `OpenAICompletion`                         |
| `apiKey`                       | 控制台创建的 Key（支持 `${ENV_VAR}` 引用）             |
| `id`                           | 控制台「模型广场」中的模型名                             |
| `displayName` / `providerName` | 自定义，例如 `aicentos`                          |

注意：Junie 的 profile 与多数客户端相反，`baseUrl` 需要填**完整端点**，必须以 `/chat/completions` 结尾，Junie 不会自动补路径。

## 配置步骤

* 创建 profile 文件（文件名去掉 `.json` 就是 profile 标识符）：
  * 用户级：`~/.junie/models/aicentos.json`（`$JUNIE_HOME` 默认是 `~/.junie`）
  * 项目级：`<项目根>/.junie/models/aicentos.json`（需项目已被信任）
* 写入以下内容：

```json
{
  "id": "gpt-5",
  "baseUrl": "https://aicentos.com/v1/chat/completions",
  "apiType": "OpenAICompletion",
  "apiKey": "${AICENTOS_API_KEY}",
  "displayName": "aicentos GPT",
  "providerName": "aicentos",
  "fasterModel": { "id": "gpt-5-mini" }
}
```

* 导出环境变量：

```bash
export AICENTOS_API_KEY="sk-你的aicentos密钥"
```

* 启动时指定 profile，或在交互界面里用 `/model` 选择：

```bash
junie --model custom:aicentos
```

## 测试

启动后先用一句简单提示词轻量测试，确认能正常返回结果再正式使用 agentic 工作流。

## 注意事项

* **JetBrains IDE 插件不支持自定义端点**，这套 profile 只在 Junie CLI 里生效。
* `baseUrl` 必须是完整端点（含 `/v1/chat/completions`），这与很多只需填 Base URL 的客户端不同。
* `apiKey` 与 `extraHeaders` 中的 `${VAR}` 在加载 profile 时解析；环境变量未设置会导致 profile 加载失败。
* 项目级 profile 受项目信任限制，未信任的项目会报 `Unknown custom model profile`。
* 小模型难以胜任 Junie 的多步工具调用与长上下文任务，建议选能力较强的模型。
* 更多说明见文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

---

# Kilo CLI

来源: https://docs.aicentos.com/clients/kilo-cli

Language: zh-CN

> 在 Kilo 命令行工具中通过配置文件接入 aicentos

Kilo CLI 通过一份 JSON / JSONC 配置文件声明 Provider 与模型，支持用 `@ai-sdk/openai-compatible` 指向任意 OpenAI 兼容端点，因此可以直接接入 aicentos。

## 准备工作

先在控制台「API Key」页面为命令行创建一个专用 Key（建议命名 `kilo-cli`）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

同时确认已全局安装 Kilo CLI：

```bash
npm install -g @kilocode/cli
```

## 需要填写的配置

| 字段                               | 值                                      |
| -------------------------------- | -------------------------------------- |
| Provider 包（`npm`）                | `@ai-sdk/openai-compatible`            |
| `options.baseURL`                | `https://aicentos.com/v1`              |
| `options.apiKey`                 | 控制台创建的 Key（可用 `{env:VAR}` 引用）          |
| 模型引用（顶层 `model`）                 | `provider/model` 形式，如 `aicentos/gpt-5` |
| `limit.context` / `limit.output` | 按所选模型填写                                |

## 配置步骤

* 新建或编辑全局配置文件：
  * `~/.config/kilo/kilo.json`（或 `kilo.jsonc`）；设置了 `XDG_CONFIG_HOME` 时以该目录为准。
  * 项目级 `./kilo.jsonc` 会覆盖全局配置的同名项。
* 写入以下内容：

```json
{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "aicentos/gpt-5",
  "provider": {
    "aicentos": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "aicentos",
      "options": {
        "baseURL": "https://aicentos.com/v1",
        "apiKey": "{env:AICENTOS_API_KEY}"
      },
      "models": {
        "gpt-5": {
          "name": "GPT-5",
          "limit": { "context": 128000, "output": 16384 }
        }
      }
    }
  }
}
```

* 导出环境变量：

```bash
export AICENTOS_API_KEY="sk-你的aicentos密钥"
```

* 在项目目录下运行 `kilo`，或在交互界面里用 `/model` 切换模型。

## 测试

启动后先用一句简单提示词轻量测试，确认能正常返回结果再正式使用。

## 注意事项

* `options.baseURL` 只填到 `https://aicentos.com/v1`，不要补成完整的 `/v1/chat/completions`。
* `{env:VAR}` 这套环境变量替换语法**只在全局配置文件中生效**；项目级 `kilo.jsonc` 出于安全考虑不会解析 `{env:...}`。
* 自定义模型必须显式声明 `limit.context` 与 `limit.output`，否则上下文长度按 0 处理，自动压缩会失效。
* 如果网关不提供 `/v1/models` 列表接口，自动探测模型会失败，按上面的写法手动声明即可。
* 更多说明见文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

---

# Kilo Code

来源: https://docs.aicentos.com/clients/kilo-code

Language: zh-CN

> 在 Kilo Code（VS Code 扩展）新建 Custom Provider，填入 aicentos 的 Base URL 与 API Key 接入

Kilo Code 官方支持 OpenAI Compatible provider，可直接对接当前服务。

## 安装

官方安装页：[https://marketplace.visualstudio.com/items?itemName=kilocode.kilo-code](https://marketplace.visualstudio.com/items?itemName=kilocode.kilo-code)

如果你使用 VS Code，最直接的安装方式是：

```bash
code --install-extension kilocode.kilo-code
```

如果你使用 Windsurf、VSCodium 或 Open VSX 兼容环境，可按 Kilo 官方文档使用对应扩展市场版本安装。

## 打开设置

在 Kilo Code 面板中点击设置按钮，进入 provider 配置。

## 需要填写的配置

将 API Provider 设为 OpenAI Compatible，然后填写：

* Base URL：[https://aicentos.com/v1](https://aicentos.com/v1)
* API Key：你的 codex\_... 或 sk-... 等 Key
* Model ID：gpt-5-codex-mini

如果模型列表没有自动出现该模型，也可以直接手动输入。

## 测试

保存后直接发起一个新任务，确认 Kilo Code 可以正常连接并返回内容。

## 注意事项

* Kilo Code 官方文档使用 OpenAI Compatible provider 配置
* Kilo Code 额外支持填写完整 endpoint URL，但对当前服务没有必要
* 这里建议直接使用 Base URL，不要额外补成完整 /chat/completions 路径
* 参考官方文档：[https://kilo.ai/docs/ai-providers/openai-compatible](https://kilo.ai/docs/ai-providers/openai-compatible)

---

# Kilo

来源: https://docs.aicentos.com/clients/kilo

Language: zh-CN

> 在 Kilo 中通过自定义 OpenAI 兼容 Provider 接入 aicentos

Kilo 支持自定义 Provider，可以把对话与 Agent 请求指向任意 OpenAI 兼容端点。只需在设置里新增一个 Custom Provider，填入 aicentos 的 Base URL 和 Key 即可。

## 准备工作

先在控制台「API Key」页面为 Kilo 创建一个专用 Key（建议命名 `kilo`）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

## 需要填写的配置

| 字段                | 值                                    |
| ----------------- | ------------------------------------ |
| Provider ID / 名称  | 自定义，例如 `aicentos`                    |
| API 类型            | OpenAI Compatible (Chat Completions) |
| Base URL          | `https://aicentos.com/v1`            |
| API Key           | 控制台创建的 Key                           |
| Model ID          | 控制台「模型广场」中的模型名                       |
| Context Window    | 按所选模型填写                              |
| Max Output Tokens | 按所选模型填写                              |

## 配置步骤

* 打开 Kilo 的设置面板（齿轮图标）。
* 进入 **Providers**，拉到列表最底部，选择 **Custom provider**（自定义 Provider）。
* Provider ID 和 Display name 随意填，例如 `aicentos`。
* API 类型选择 **OpenAI Compatible (Chat Completions)**。
* Base URL 填入 `https://aicentos.com/v1`。
* 填入在控制台创建的 API Key。
* 手动添加 Model ID，填写控制台中的模型名。
* 保存后，在模型选择器中选中该 Provider 下的模型。

## 测试

保存设置后新建一个任务，先用一句简单提示词轻量测试，确认能正常返回内容再正式使用 Agent 模式。

## 注意事项

* 如果网关不提供 `/v1/models` 列表接口，自动探测模型会失败，手动填写 Model ID 即可。
* Base URL 只填到 `https://aicentos.com/v1`，不要补成完整的 `/v1/chat/completions`。
* 自定义模型建议显式设置 Context Window 与 Max Output Tokens；缺失会让上下文长度按 0 处理，导致自动压缩失效、对话无限增长。
* 官方文档：[https://kilo.ai/docs/ai-providers/openai-compatible](https://kilo.ai/docs/ai-providers/openai-compatible)
* 更多说明见文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

---

# Kimchi

来源: https://docs.aicentos.com/clients/kimchi

Language: zh-CN

> 在 Kimchi 里接入 aicentos —— 用 llmEndpoint 改推理地址，附能力边界说明

Kimchi 是终端编码代理，也提供 VS Code 扩展和 Studio 桌面端。它的配置里有一个 `llmEndpoint` 字段，默认指向 `https://llm.kimchi.dev`，改掉它就能把推理请求发到别处。

需要提前说明：**官方文档只把 `llmEndpoint` 描述为推理地址，没有承诺它可以指向任意第三方 OpenAI 兼容网关**。下面的做法在社区里可用，但属于「按字段语义配置」，不是官方支持的 BYOK 路径，升级后可能失效。

## 准备工作

先在控制台为 Kimchi 建一个专用 Key（建议命名 `kimchi`），再安装 CLI：

```bash
brew install getkimchi/tap/kimchi
```

或者用安装脚本：

```bash
curl -fsSL https://github.com/getkimchi/kimchi/releases/latest/download/install.sh | bash
```

## 需要填写的配置

| 字段            | 值                         |
| ------------- | ------------------------- |
| `llmEndpoint` | `https://aicentos.com/v1` |
| `apiKey`      | 控制台创建的 Key                |
| 模型            | 控制台「模型广场」中的模型名            |

## 配置步骤

配置文件在 `~/.config/kimchi/config.json`，也可以放项目级 `.kimchi/config.json` 覆盖：

```json
{
  "apiKey": "sk-你的-API-Key",
  "llmEndpoint": "https://aicentos.com/v1"
}
```

自定义模型登记在 `models.json`，格式与 vLLM、LM Studio 那类自建 provider 相同。字段规范官方没完整公开，建议先用默认模型跑通，再考虑加自定义条目。

改完重新启动 `kimchi`。

## 测试

启动后在会话里发一句提示词。若报 401，先确认 Key 没有多余空格；若报 404，检查 `llmEndpoint` 是否只写到 `/v1`。

再回控制台看用量——**这是关键一步**：如果用量没有增长，说明请求根本没走 `llmEndpoint`，而是回落到默认端点，此时这条路对当前版本不成立。

## 注意事项

* Kimchi 需要登录自己的账号，`apiKey` 与账号登录态是两件事，别只做一半。
* 外部模型默认按 `standard` 档处理、`vision: false`，多模态模型在这里不会带图。
* 默认模型由它自己的 harness 自动挑选，你可能没法直接指定 aicentos 上的某个模型名。
* 官方未把这条路写进文档，属于「能用但不保证」，生产环境请准备回退方案。

## 相关链接

* [Kimchi CLI 文档](https://docs.kimchi.dev/docs/kimchi-cli)
* [kimchi 仓库](https://github.com/getkimchi/kimchi)

---

# Kimi

来源: https://docs.aicentos.com/clients/kimi

Language: zh-CN

> 在 Kimi Code CLI 中使用 aicentos —— 通过 config.toml 注册 OpenAI 兼容 provider

Kimi Code CLI 允许把任意 OpenAI 兼容服务注册成 provider。把 `base_url` 指向 aicentos、填入 API Key，就能在终端界面里直接调用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Kimi Code 创建一个专用 Key（建议命名 `kimi-cli`，方便追踪用量）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)
* 文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

配置文件默认位于 `~/.kimi/config.toml`，首次运行 Kimi Code 时会自动创建。

## 需要填写的配置

| 字段          | 值                                    |
| ----------- | ------------------------------------ |
| provider 类型 | `openai_legacy`（Chat Completions 协议） |
| base\_url   | `https://aicentos.com/v1`            |
| api\_key    | 控制台创建的 Key                           |
| model       | 控制台「模型广场」中的模型名                       |

如果 aicentos 侧走的是 Responses 协议，把类型换成 `openai_responses` 即可。

## 配置步骤

打开 `~/.kimi/config.toml`，追加一个自定义 provider 和一个模型别名：

```toml
default_model = "aicentos-gpt-4o"

[providers.aicentos]
type = "openai_legacy"
base_url = "https://aicentos.com/v1"
api_key = "sk-你的Key"

[models.aicentos-gpt-4o]
provider = "aicentos"
model = "gpt-4o"
max_context_size = 128000
```

* provider 名（`aicentos`）和模型别名（`aicentos-gpt-4o`）都可以自定义，`default_model` 里写的是别名，不是服务端模型 ID。
* 别名里如果带 `.`（例如 `gpt-4.1`），TOML 里必须加引号：`[models."gpt-4.1"]`，否则 `.` 会被当成表的分隔符。
* 不想手写 TOML 的话，在 TUI 里输入 `/provider` 打开供应商管理器，在 `[ Add New Platform ]` 一行回车，按向导添加。

也可以只走环境变量（对 `openai_legacy` / `openai_responses` 类型生效）：

```bash
export OPENAI_BASE_URL="https://aicentos.com/v1"
export OPENAI_API_KEY="sk-你的Key"
```

## 测试

启动 `kimi`，在 TUI 里发送一句简单提示词，能正常返回即接入成功。用 `/model` 确认当前选中的是刚才配置的别名。

## 注意事项

* provider 凭证按 `api_key` 字段 > `[providers.<name>.env]` 子表 > 启动报错 的顺序解析；除 `openai_legacy` / `openai_responses` 外，配置文件里的凭证不会从 shell 环境变量自动补齐。
* `type = "kimi"` 是给 Moonshot 官方端点用的，接入 aicentos 请用 `openai_legacy` 或 `openai_responses`。
* `max_context_size` 不要填低于模型实际窗口的值，填小了会提前触发上下文压缩。
* Base URL 只填到 `/v1`，不要补成 `/v1/chat/completions` 完整路径。
* 模型名以控制台「模型广场」为准（参考 [支持的模型](https://docs.aicentos.com/billing/models-list)）。

---

# Kiro

来源: https://docs.aicentos.com/clients/kiro

Language: zh-CN

> Kiro 目前不支持自定义 Base URL —— 说明限制原因与可行的替代方案

**Kiro 目前不支持自定义 Base URL，无法直接接入 aicentos。**

Kiro 是 AWS 推出的 agentic IDE（基于 Code OSS），它的模型统一走自带服务，底层为 Amazon Bedrock。官方没有开放「自定义模型端点」或「自带 API Key（BYOK）」的配置入口，社区的相关功能请求也仍未实现。

## 准备工作

无需为 Kiro 创建 aicentos 的 API Key —— 当前版本没有可以填入自定义 Key 的地方。

参考信息：

* 控制台：[https://aicentos.com](https://aicentos.com)
* 文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

如果你在其他客户端已经接入，可先确认该客户端是否支持自定义端点。

## 需要填写的配置

| 字段       | 值                  |
| -------- | ------------------ |
| Base URL | 无此配置项              |
| API Key  | 无此配置项              |
| 模型       | 只能从 Kiro 内置模型列表中选择 |

## 配置步骤

无法配置。Kiro 的设置里只有模型切换（`/model` 命令或模型选择器）和自定义 Agent 的 `model` 字段，而 `model` 只会匹配 Kiro 服务端返回的可用模型 ID，不能指向外部端点。

## 替代方案

Kiro 不支持自定义端点，因此有以下几条路可选：

* **使用原生支持自定义 Base URL 的客户端**：例如 Cursor、Windsurf、Cline、Roo Code、Zed Agent 等，均可直接填入 `https://aicentos.com/v1`。参见「客户端接入」下的其他文档。
* **在 Kiro 里沿用内置模型**：Kiro 内置模型由 AWS 提供，与 aicentos 无关，无法合并计费。
* **等待官方支持 BYOM / BYOK**：可在 Kiro 官方仓库的功能请求中关注进展，目前尚未落地。
* **企业内网网关场景**：即使部署了内部 LLM 代理，Kiro 也无法配置指向它，同样需要等待官方支持。

不建议使用修改 hosts、安装自签名证书或对 IDE 打补丁之类的非官方绕过手段 —— 这类做法会破坏 Kiro 的更新机制，也存在安全与合规风险。

## 测试

无自定义端点可测试。若想验证 aicentos 的连通性，可用任意支持自定义 Base URL 的客户端，或直接调用：

```bash
curl https://aicentos.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{"model":"gpt-5","messages":[{"role":"user","content":"hi"}],"stream":false}'
```

## 注意事项

* 再次强调：**Kiro 当前版本不支持自定义 Base URL，无法接入 aicentos**。
* 本文档会随 Kiro 官方能力变化而更新。
* 官方文档：[https://kiro.dev/docs](https://kiro.dev/docs)

---

# LM Studio

来源: https://docs.aicentos.com/clients/lm-studio

Language: zh-CN

> LM Studio 是本地推理服务端而不是客户端 —— 说明它的正确角色与替代做法

LM Studio 常被当成「又一个聊天客户端」，其实方向是反的：它是**本地模型运行器**，对外暴露一个 OpenAI 兼容接口（默认 `http://localhost:1234/v1`），让别人来连它。它没有「填一个远程 Base URL」的入口，所以无法作为客户端接入 aicentos。

## 为什么不能直接接入

* 官方定位是 `Serve local models on OpenAI-like endpoints`，服务端角色，不是消费方。
* 桌面端、`lms` CLI 里都没有第三方 provider 的端点配置项。
* 它的云能力（LM Studio Secure Cloud、LM Link）是官方托管的算力通道，不接受自定义第三方端点。

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| API Key  | 控制台创建的 Key                |
| Base URL | `https://aicentos.com/v1` |
| 模型       | 控制台「模型广场」中的模型名            |

上表是 aicentos 侧的通用参数，供下面的替代方案使用。

## 替代方案

### 方案一：反过来用——让客户端连 LM Studio

如果你想跑本地模型，保持 LM Studio 当服务端，把 [Cherry Studio](https://docs.aicentos.com/clients/cherry-studio)、[Chatbox](https://docs.aicentos.com/clients/chatbox)、[Cline](https://docs.aicentos.com/clients/cline) 的 Base URL 填成 `http://localhost:1234/v1`。这条链路和 aicentos 无关，但它是 LM Studio 的正确用法。

### 方案二：要 aicentos 的模型，就换前端

[Cherry Studio](https://docs.aicentos.com/clients/cherry-studio)、[Chatbox](https://docs.aicentos.com/clients/chatbox)、[LobeChat](https://docs.aicentos.com/clients/lobechat) 都是桌面聊天客户端，支持多 provider 并存：一条填 aicentos，一条填本地 LM Studio，同一个界面里切换。

### 方案三：本地与云端混用

用 Cherry Studio 这类客户端同时挂两个 provider，简单任务走本地、复杂任务走 aicentos，按需切换即可。

## 测试

把 LM Studio 当服务端时，先 `lms server start`，再用 `curl http://localhost:1234/v1/models` 确认接口活着，然后在客户端里发一句提示词。

## 注意事项

* 别在 LM Studio 里找 Base URL 输入框，它只显示自己监听的地址。
* 本地模型的上下文与速度受本机显存限制，长上下文任务建议走 aicentos。
* 两个方向别混淆：**服务端填端口，客户端填端点**。

## 相关链接

* [LM Studio OpenAI 兼容接口](https://lmstudio.ai/docs/api/openai-api)
* [lms CLI](https://github.com/lmstudio-ai/lms)

---

# LobeChat

来源: https://docs.aicentos.com/clients/lobechat

Language: zh-CN

> 在 LobeChat 中使用 aicentos —— 通过自定义 OpenAI 兼容设置接入

LobeChat 是一款开源 AI 聊天平台，支持 OpenAI 兼容接口，可通过设置面板直接对接当前服务。

## 打开设置

点击左下角\*\*设置（Settings）**图标，进入**语言模型（Language Model）\*\*页。

## 选择 OpenAI 提供商

在提供商列表中点击 **OpenAI**，展开配置面板。

## 需要填写的配置

在配置面板中填写以下信息：

* **API Key（apiKey）**：你的 `codex_...` 或 `sk-...` 等 Key
* **API 代理地址（baseURL）**：`https://aicentos.com/v1`

## 选择模型并验证

在模型下拉框中选择，或手动输入 `gpt-5-codex-mini`。发起一次对话，确认有正常返回即可。

## 注意事项

* API 代理地址需填写包含 `/v1` 的服务根路径，即 `https://aicentos.com/v1`
* LobeChat 支持同时配置多个提供商并按会话切换
* 自托管版本可通过环境变量 `OPENAI_API_KEY` 和 `OPENAI_PROXY_URL` 完成配置，详见官方环境变量文档

## 相关链接

* 官方文档：[https://lobehub.com/docs/usage/providers/openai](https://lobehub.com/docs/usage/providers/openai)

---

# MiMo Code

来源: https://docs.aicentos.com/clients/mimo-code

Language: zh-CN

> 在 MiMo Code 中使用 aicentos —— 通过兼容层接入 OpenAI 兼容端点

MiMo Code 支持在配置里指定 OpenAI 兼容的 `base_url`。把它指向 aicentos 并填入 API Key，就能让 MiMo Code 走 aicentos 的模型。

## 准备工作

先在控制台「API Key」页面为 MiMo Code 创建一个专用 Key（建议命名 `mimo-code`，方便追踪用量）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)
* 文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

MiMo Code 是 CLI 工具，常见安装方式是 npm 全局安装；如果你拿到的发布包是 tarball，解压后把可执行文件放进 `PATH` 即可。

```bash
npm install -g mimo-code
mimo --version
```

## 需要填写的配置

| 字段        | 值                         |
| --------- | ------------------------- |
| API Key   | 控制台创建的 Key                |
| base\_url | `https://aicentos.com/v1` |
| model     | 控制台「模型广场」中的模型名            |

## 配置步骤

推荐用环境变量，兼容性最好：

```bash
export MIMO_BASE_URL="https://aicentos.com/v1"
export MIMO_API_KEY="sk-你的Key"
export AICENTOS_API_KEY="$MIMO_API_KEY"
export MIMO_MODEL="gpt-4o"
```

永久生效写入 `~/.zshrc` 或 `~/.bashrc` 后执行 `source ~/.zshrc`。

如果偏好配置文件，编辑 `~/.mimo/config.json`：

```json
{
  "baseUrl": "https://aicentos.com/v1",
  "apiKey": "sk-你的Key",
  "model": "gpt-4o"
}
```

注意不同版本对配置项命名（`base_url` / `baseUrl`）与环境变量前缀（`MIMO_` / `MIMOCODE_`）可能不同。如果上面的变量名不生效，用 `mimo --help` 或官方文档确认当前版本实际读取的名字，不要反复试。

## 测试

配置后直接运行 `mimo`，发一句简单提示词。若报鉴权错误，优先检查环境变量名是否被当前版本识别、`base_url` 是否只写到 `/v1`、Key 是否有多余空格。

## 注意事项

* 部分版本在启动时会把 `base_url` 与内置的官方端点做校验，如果发现配置被忽略，改走环境变量方式通常能绕过。
* Base URL 只填到 `/v1`。
* 建议先用 `curl https://aicentos.com/v1/models -H "Authorization: Bearer $AICENTOS_API_KEY"` 确认模型可见，再填模型名。
* 环境变量与配置文件同时存在时，各版本优先级不一致，建议只保留一种配置方式。

---

# MiniMax Code

来源: https://docs.aicentos.com/clients/minimax-code

Language: zh-CN

> 在 MiniMax Code（mcode）里接入 aicentos —— 用 provider add 加一个 OpenAI 兼容 provider

MiniMax Code 是 MiniMax 官方的编码 CLI（命令 `mcode`），自带 TUI、headless 执行、ACP 和 TypeScript SDK。它支持 BYOK：可以用 `mcode provider add` 挂任意 OpenAI 兼容端点。

## 准备工作

先在控制台为 MiniMax Code 建一个专用 Key（建议命名 `minimax-code`），然后安装：

```bash
curl -fsSL https://filecdn.minimax.chat/public/install.sh | bash
```

也可以走 npm：

```bash
npm install -g @minimax-ai/code@latest
mcode --version
```

## 需要填写的配置

| 字段              | 值                         |
| --------------- | ------------------------- |
| provider 名      | 自取，例如 `aicentos`          |
| `--base-url`    | `https://aicentos.com/v1` |
| `--api-format`  | `openai-completions`      |
| `--model`       | 控制台「模型广场」中的模型名            |
| `--api-key-env` | `MCODE_PROVIDER_API_KEY`  |

## 配置步骤

一条命令注册并切过去：

```bash
export MCODE_PROVIDER_API_KEY="sk-你的-API-Key"

mcode provider add \
  --name aicentos \
  --base-url https://aicentos.com/v1 \
  --api-format openai-completions \
  --model 你的模型名 \
  --api-key-env MCODE_PROVIDER_API_KEY \
  --use
```

`--use` 表示注册完立刻切到这个 provider。它会把配置写进当前 profile 的 `config.yaml`（默认数据目录 `~/.minimax`）的 `custom_provider` 段，等价写法：

```yaml
custom_provider:
  aicentos:
    options:
      apiKey: sk-你的-API-Key
      baseURL: https://aicentos.com/v1
    models:
      你的模型名: {}
```

注意这里的键是 `baseURL`（大写 URL），不是 `base-url`。

## 测试

```bash
mcode exec "用一句话自我介绍"
```

headless 能返回即说明配置生效。再进 TUI 跑一轮真实任务，最后回控制台核对用量。

## 注意事项

* 自定义模型要显式给上下文与输出上限（`--context-limit`、`--output-limit`），否则它按默认值裁剪，长文件容易被截断。
* 一键安装脚本不支持 Alpine / musl，这类环境改用 npm 安装。
* 想走 Anthropic 兼容协议做中转时，请求里仍会附带 `x-api-key`，上游若只认 `Authorization` 需要自己加一层转换。
* provider 是**按 profile** 存的，切换 profile 后要重新确认当前生效的是哪一条。

## 相关链接

* [MiniMax Code 快速开始](https://agent.minimax.io/docs/cli/quick-start)
* [minimax-code 仓库](https://github.com/MiniMax-AI/minimax-code)

---

# Mux

来源: https://docs.aicentos.com/clients/mux

Language: zh-CN

> 在 Mux 中使用 aicentos —— 添加自定义 OpenAI 兼容 provider

Mux 支持添加自定义 OpenAI 兼容 provider。把 Base URL 指向 aicentos，即可在 Mux 的会话中使用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Mux 创建一个专用 Key（建议命名 `mux`，方便追踪用量）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)
* 文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

## 需要填写的配置

| 字段          | 值                         |
| ----------- | ------------------------- |
| Provider 类型 | OpenAI Compatible         |
| Base URL    | `https://aicentos.com/v1` |
| API Key     | 控制台创建的 Key                |
| Model       | 控制台「模型广场」中的模型名            |

## 配置步骤

* 打开 Mux 设置，进入 Providers / Models 区域。
* 选择添加自定义 provider，类型选 **OpenAI Compatible**。
* 填入 API Key。
* Base URL 填：`https://aicentos.com/v1`
* Model 填入控制台「模型广场」中的模型名（参考 [支持的模型](https://docs.aicentos.com/billing/models-list)）。
* 保存，并把它设为当前会话使用的 provider。

## 测试

新建一个会话，发送一句简单提示词。能正常返回即接入成功。如果模型列表没有自动出现你填的模型，手动输入 Model ID 再试一次。

## 注意事项

* Base URL 只填到 `/v1`，不要补成 `/v1/chat/completions` 完整路径。
* 不同版本的设置项名称可能略有差异，但 OpenAI 兼容配置始终围绕 Base URL、API Key、Model 三个字段。
* 如果 Base URL 填错、Key 带多余空格或余额不足，通常表现为 401 / 403 / 402 错误，逐一核对即可。
* 若你的 Mux 版本只提供固定的几家公司选项、无法自定义 Base URL，说明该版本不支持第三方端点，此时请改用其他支持自定义 Base URL 的客户端。

---

# NativeTavern

来源: https://docs.aicentos.com/clients/nativetavern

Language: zh-CN

> 在 NativeTavern 中接入 aicentos 的 OpenAI 兼容接口，填入 Base URL 与 API Key 即可使用

# NativeTavern

NativeTavern 是 SillyTavern 的移动端原生应用版本，支持 iOS 和 Android 平台，可以通过 OpenAI 兼容接口接入自定义 API。

## 安装应用

从对应平台的应用商店下载安装 NativeTavern：

* iOS: App Store
* Android: Google Play

## 配置 API 连接

1. 打开 NativeTavern 应用
2. 进入 **设置** 或 **Settings**
3. 选择 **API Configuration**
4. 选择 API 类型为 **OpenAI** 或 **OpenAI Compatible**

## 需要填写的配置

在配置页面中填写：

* **API URL**: `https://aicentos.com/v1`
* **API Key**: 填写你的 API Key（如 `codex_...` 或 `sk-...`）
* **Model**: 选择或输入模型 ID（如 `gpt-6-astra`）

## 测试连接

1. 保存设置后返回主界面
2. 创建或选择一个角色
3. 发送消息测试连接是否正常

## 注意事项

* 移动端应用可能需要稳定的网络连接
* API URL 只需填写到 `/v1`，不需要完整路径
* 支持大部分 SillyTavern 的功能特性

## 相关链接

NativeTavern 是 SillyTavern 生态的一部分，更多信息可访问 SillyTavern 社区。

---

# NextChat

来源: https://docs.aicentos.com/clients/nextchat

Language: zh-CN

> 在 NextChat 中使用 aicentos —— 通过自定义 OpenAI 兼容设置接入

NextChat 是一款广泛使用的开源 ChatGPT Web 客户端，支持自定义 OpenAI 兼容接口。

## UI 界面配置 - 打开设置

点击左下角\*\*设置（Settings）\*\*图标

## UI 界面配置 - 启用自定义接口

在设置面板中找到**自定义接口**开关，打开后出现输入框

## UI 界面配置 - 填写连接信息

填写以下信息：

| 字段             | 填写内容                            |
| -------------- | ------------------------------- |
| OpenAI API Key | 你的 `codex_...` 或 `sk-...` 等 Key |
| API 代理 URL     | `https://aicentos.com/v1`       |

## UI 界面配置 - 验证

保存后，发起对话验证是否正常返回

## 自托管部署配置

对于自托管实例，通过环境变量配置：

```bash
OPENAI_API_KEY=codex_your_api_key
BASE_URL=https://aicentos.com/v1
```

配置后重启服务即生效。

## 自定义模型

在设置面板的\*\*模型（Model）\*\*下拉框中，可手动输入 `gpt-5-codex-mini` 或其他可用模型名。

自托管版本还可通过 `CUSTOM_MODELS` 环境变量预置模型列表，例如：

```bash
CUSTOM_MODELS=gpt-5-codex-mini
```

## 注意事项

* API 代理 URL 填写包含 `/v1` 的服务根路径，即 `https://aicentos.com/v1`
* 可用模型以 `GET /v1/models` 返回列表为准

## 相关链接

* GitHub：[https://github.com/ChatGPTNextWeb/NextChat](https://github.com/ChatGPTNextWeb/NextChat)

---

# Oh My Pi

来源: https://docs.aicentos.com/clients/oh-my-pi

Language: zh-CN

> 在 Oh My Pi（omp）里接入 aicentos —— models.yml 加一个 openai-completions provider

Oh My Pi 是 Pi 的分支，用 Rust 重写了核心，命令是 `omp`。它通过 `~/.omp/agent/models.yml` 定义 provider，字段 `baseUrl` / `api` / `apiKey` 写清楚就能指向 aicentos。

## 准备工作

先在控制台为 Oh My Pi 建一个专用 Key（建议命名 `oh-my-pi`）。

运行时需要 bun 1.4.4 及以上：

```bash
curl -fsSL https://omp.sh/install | sh
```

也可以用 Homebrew 或 npm 分发：

```bash
brew install can1357/tap/omp
# 或
bun install -g @oh-my-pi/pi-coding-agent
```

## 需要填写的配置

| 字段            | 值                         |
| ------------- | ------------------------- |
| provider 名    | 自取，例如 `aicentos`          |
| `baseUrl`     | `https://aicentos.com/v1` |
| `api`         | `openai-completions`      |
| `apiKey`      | 控制台创建的 Key                |
| `models[].id` | 控制台「模型广场」中的模型名            |

## 配置步骤

编辑 `~/.omp/agent/models.yml`：

```yaml
providers:
  aicentos:
    baseUrl: https://aicentos.com/v1
    api: openai-completions
    apiKey: sk-你的-API-Key
    models:
      - id: 你的模型名
        contextWindow: 128000
```

在 `~/.omp/agent/config.yml` 里把它设为默认：

```yaml
modelRoles:
  default: aicentos/你的模型名
```

不想把 Key 写进文件时，把 `apiKey` 换成环境变量引用，并在启动前 `export AICENTOS_API_KEY="sk-你的-API-Key"`。

## 测试

```bash
omp models aicentos
```

能列出刚配的模型即说明 provider 认到了。再进 TUI 发一句话确认能返回，最后回控制台核对用量。

## 注意事项

* `api` 必须是 `openai-completions`（或其它它认识的协议名），写 `openai` 会被当成未知协议。
* 它默认关闭了大量工具，接入成功但「什么都不能干」时先看工具开关，不是端点问题。
* 打开仓库即加载项目级配置与钩子，接入前确认仓库可信。
* Alpine 环境需要额外装 `libstdc++`、`libgcc`。

## 相关链接

* [Oh My Pi provider 文档](https://omp.sh/docs/providers)
* [oh-my-pi 仓库](https://github.com/can1357/oh-my-pi)

---

# OpenClaw

来源: https://docs.aicentos.com/clients/openclaw

Language: zh-CN

> 在 OpenClaw 中使用 aicentos —— 通过自定义 Provider 接入

OpenClaw 是一个 AI 编程助手命令行工具，支持通过自定义 Provider 接入 OpenAI 兼容的 API 服务。官方推荐使用 `openclaw onboard` 向导完成配置，也可以手动编写配置文件。

## 准备工作

确保系统满足以下要求：

* Node.js 22+ 版本
* macOS / Linux / Windows 系统
* 如果从源码构建，需要额外安装 pnpm

### 安装 Node.js

**macOS（使用 Homebrew）：**

```bash
brew install node
```

**其他系统：**

访问 Node.js 官网下载 LTS 版本：[https://nodejs.org/en/download](https://nodejs.org/en/download)

### 验证安装

```bash
node -v
npm -v
```

**注意：** Windows 用户建议在 WSL2 环境中运行 OpenClaw。

## 安装 OpenClaw

使用官方安装脚本（推荐）：

### macOS / Linux

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

### Windows PowerShell

```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```

安装脚本会自动检测并补装缺失的依赖。如果你已经自己管理 Node 环境，也可以使用 `npm` 或 `pnpm` 安装方式（详见官方文档）。

## 启动配置向导

运行向导命令：

```bash
openclaw onboard
```

在向导中依次填写以下信息：

* **Provider 类型**：选择 `Custom Provider`
* **Compatibility**：选择 `OpenAI-compatible`
* **Base URL**：`https://aicentos.com/v1`
* **API Key**：填写你的 API Key
* **Model ID**：参考控制台「模型广场」中的模型名
* **Endpoint ID**：建议填写 `aicentos`

**注意：** API Key 直接填明文即可，不需要额外改成环境变量 `OPENAI_API_KEY`。

## 设置默认模型

完成向导后，将默认模型设置为：

```text
aicentos/gpt-4o
```

这样后续使用时会自动使用配置好的模型。

## 手动配置（可选）

如果不使用向导，可以直接编写 OpenClaw 的 provider 配置文件：

```json
{
  "models": {
    "providers": {
      "aicentos": {
        "baseUrl": "https://aicentos.com/v1",
        "apiKey": "your_api_key_here",
        "api": "openai-completions",
        "models": [
          { "id": "gpt-4o", "name": "gpt-4o" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "aicentos/gpt-4o" }
    }
  }
}
```

配置中可以直接写 API Key 明文，也可以使用环境变量引用（如果你更偏好 SecretRef 方式）。

## 验证配置

检查模型状态以确认接入成功：

```bash
openclaw models list
openclaw models status
```

如果能看到 `aicentos/gpt-4o` 并且状态显示正常，说明接入配置成功。

## 注意事项

* OpenClaw 官方支持自定义 Provider 功能，可选择 OpenAI-compatible 或 Anthropic-compatible 模式
* 对当前服务，推荐优先使用 OpenAI-compatible 模式
* 直接填写 API Key 是默认做法；环境变量引用只是可选方案
* 如果希望使用工具自动写入配置，可以考虑使用 `cc-switch` 工具
* 官方文档还提供了其他安装和配置方式，可根据实际需求选择

## 相关链接

* 官方文档：[https://docs.openclaw.ai/install/index](https://docs.openclaw.ai/install/index)

---

# OpenCode

来源: https://docs.aicentos.com/clients/opencode

Language: zh-CN

> 在 OpenCode 中使用 aicentos —— 通过配置文件接入自定义 provider

OpenCode 支持自定义 provider，可以通过配置文件的方式接入 Codex Proxy 服务。

## 准备工作

OpenCode 官网提供官方安装脚本，也提供 npm、bun、brew 等安装方式。

* 如果你直接使用官方安装脚本，通常不需要先手动配置 npm
* 如果你准备走 npm 安装，请先安装 Node.js 与 npm
* 如果你准备走 bun 安装，则需要先安装 bun

### 安装 Node.js（npm 方式）

Node.js 官方下载页是：[https://nodejs.org/en/download](https://nodejs.org/en/download)

* macOS / Windows：下载并安装 LTS 版本
* Linux：按该页面提供的发行版方式安装

如果你在 macOS 上已经安装了 Homebrew，也可以直接执行：

```bash
brew install node
```

这会同时安装 Node.js 和 npm。

建议先按你选择的安装方式确认对应命令可用。例如 npm 方式可先检查：

```bash
node -v
npm -v
```

**注意：** 如果你在 Windows 上使用命令行环境，官方目前建议优先在 WSL 中使用。

## 安装

推荐直接使用 OpenCode 官网提供的安装命令：

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

OpenCode 官网同时提供 npm、bun、brew 等安装方式。

## 设置 API Key

使用 OpenCode 自己的连接或鉴权方式：

```bash
opencode auth login
```

或者在交互界面里运行 /connect，把这个服务作为自定义 provider 保存。

如果你更习惯环境变量，让 opencode.json 读取官方通用变量名即可，例如：

```bash
export OPENAI_API_KEY="your_api_key_here"
```

## 配置 opencode.json

在项目根目录或全局配置目录中创建 opencode.json：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aicentos": {
      "npm": "@ai-sdk/openai",
      "name": "aicentos",
      "options": {
        "baseURL": "https://aicentos.com/v1",
        "apiKey": "{env:OPENAI_API_KEY}"
      },
      "models": {
        "gpt-4o": {
          "name": "gpt-4o"
        }
      }
    }
  },
  "model": "aicentos/gpt-4o"
}
```

## 测试

启动 OpenCode 后，执行：

```
/models
```

看到 aicentos 下的模型即可。

## 注意事项

* 推荐顺序：先手动配置文件（opencode.json），再环境变量，最后才是 cc-switch 工具（[https://github.com/farion1231/cc-switch/releases）](https://github.com/farion1231/cc-switch/releases）)
* 如果你走 /v1/responses，OpenCode 官方文档建议使用 @ai-sdk/openai
* 如果你的接入只支持 /v1/chat/completions，才改用 @ai-sdk/openai-compatible
* 不需要额外定义 CODEX\_PROXY\_API\_KEY 这类项目私有变量

## 相关链接

* 官方网站：[https://opencode.ai/](https://opencode.ai/)

---

# OpenCodeReview

来源: https://docs.aicentos.com/clients/opencodereview

Language: zh-CN

> 在 OpenCodeReview（OCR）中使用 aicentos —— 通过自定义 provider 接入代码审查

OpenCodeReview（命令名 `ocr`）是阿里巴巴开源的 AI 代码审查 CLI：读取 Git diff 后调用大模型给出审查意见。它内置了 OpenAI 兼容 provider，也支持自定义 OpenAI 兼容网关，可以把请求转到 aicentos。

## 准备工作

在 aicentos 控制台创建一个专用 Key（建议命名 `ocr-ci`，方便追踪用量）。OCR 只支持 OpenAI / Anthropic 两种协议，这里走 OpenAI 的 Chat Completions 路径。代码审查依赖模型的 **function calling** 能力，请选择支持工具调用的模型。

## 需要填写的配置

| 字段       | 值                                   |
| -------- | ----------------------------------- |
| provider | `openai`（内置，覆盖其 URL）或自定义 provider   |
| protocol | `openai`（Chat Completions）          |
| URL      | `https://aicentos.com/v1`           |
| API Key  | 控制台创建的 Key                          |
| 模型       | 控制台「模型广场」中的模型名，需支持 function calling |

## 配置步骤

* 安装 CLI（需要 Node.js，或 macOS 上用 Homebrew）：

  ```bash
  npm install -g open-code-review
  ```

* 用非交互命令写入配置，最终落在 `~/.opencodereview/config.json`：

  ```bash
  ocr config set provider                   openai
  ocr config set model                      claude-sonnet-5
  ocr config set providers.openai.url       https://aicentos.com/v1
  ocr config set providers.openai.api_key   your_api_key_here
  ```

* 如果偏好图形引导，直接运行 `ocr config provider` 与 `ocr config model`，在 TUI 里选 provider、填 Key、挑模型，走完会自动跑一次连通性检查。

## 测试

先单独验证端点：

```bash
ocr llm test
```

通过后，在任意 Git 仓库里执行一次真实审查：

```bash
ocr review
```

## 注意事项

* URL 只填到 `/v1`，不要补成完整的 `/chat/completions`。
* 配置 resolver 需要 **URL、Key、模型** 三件套齐全；只 `export` 环境变量不够，缺失的部分仍要写进 config.json，否则返回 401。
* 也可以用环境变量临时覆盖，优先级最高：`OCR_LLM_URL` / `OCR_LLM_TOKEN` / `OCR_LLM_MODEL`。
* 内置 provider 的字段是 `providers.<name>.url`，自定义 provider 在 `custom_providers.<name>.url`，两个 map 不要写混。
* 账户余额不足时表现为 401 / 403，先到[钱包页](https://aicentos.com/wallet)确认余额。
* 官方仓库：`https://github.com/alibaba/open-code-review`

---

# Orca

来源: https://docs.aicentos.com/clients/orca

Language: zh-CN

> 在 Orca 中使用 aicentos —— 添加 OpenAI 兼容自定义端点

Orca 支持配置自定义的 OpenAI 兼容服务。把 Base URL 指向 aicentos、填入 API Key，即可在 Orca 中使用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Orca 创建一个专用 Key（建议命名 `orca`，方便追踪用量）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)
* 文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

## 需要填写的配置

| 字段          | 值                         |
| ----------- | ------------------------- |
| Provider 类型 | OpenAI Compatible         |
| Base URL    | `https://aicentos.com/v1` |
| API Key     | 控制台创建的 Key                |
| Model       | 控制台「模型广场」中的模型名            |

## 配置步骤

* 打开 Orca 的设置页面，进入模型 / Provider 配置区域。
* 新增一个 provider，类型选择 OpenAI 兼容（OpenAI Compatible / Custom OpenAI）。
* Base URL 填：`https://aicentos.com/v1`
* API Key 填控制台创建的 Key。
* Model 填控制台「模型广场」中的模型名（参考 [支持的模型](https://docs.aicentos.com/billing/models-list)）。
* 保存并设为默认模型。

## 测试

新建一个对话发送一句简单提示词，确认能正常返回。若模型下拉列表为空，改为手动输入 Model ID。

## 注意事项

* Base URL 只填到 `/v1`，不要补成 `/v1/chat/completions` 完整路径。
* 保存后如果设置没有立即生效，重启一次 Orca。
* 若你的 Orca 版本只支持内置的官方 provider、没有自定义 Base URL 入口，则该版本无法接入第三方端点，请改用其他支持自定义 Base URL 的客户端。
* 常见的连接失败原因：Base URL 写错、Key 有前后空格、模型名不存在、账户余额不足。

---

# Paseo

来源: https://docs.aicentos.com/clients/paseo

Language: zh-CN

> 在 Paseo 里接入 aicentos —— 它不直连模型，要在底层 CLI 或 provider env 里配

Paseo 是编排层：桌面端、移动端、Web 和 `paseo` CLI 都在，但**它自己不带 agent**，只负责运行你已安装并登录好的编码 CLI（Claude Code、Codex、OpenCode、Pi 等）。所以「在 Paseo 里接入 aicentos」实际上是让被托管的那个 CLI 走 aicentos。

## 准备工作

先装 Paseo，并至少准备一个底层 CLI：

```bash
npm install -g @getpaseo/cli
paseo
```

桌面端与移动端从官网下载。注意 Docker 镜像不含任何 agent CLI，容器部署要自己装。

## 需要填写的配置

Paseo 的 provider 定义在 `~/.paseo/config.json` 的 `agents.providers.<id>`，字段是 `extends`、`label`、`env`、`models`。**它支持的是给底层 CLI 注入环境变量**，官方示例都是 Anthropic 兼容协议：

| 字段                       | 值                      |
| ------------------------ | ---------------------- |
| `extends`                | 底层 CLI，例如 `claude`     |
| `env.ANTHROPIC_BASE_URL` | `https://aicentos.com` |
| `env.ANTHROPIC_API_KEY`  | 控制台创建的 Key             |
| `models`                 | 控制台「模型广场」中的模型名         |

## 配置步骤

编辑 `~/.paseo/config.json`：

```json
{
  "agents": {
    "providers": {
      "aicentos-claude": {
        "extends": "claude",
        "label": "aicentos",
        "env": {
          "ANTHROPIC_BASE_URL": "https://aicentos.com",
          "ANTHROPIC_API_KEY": "sk-你的-API-Key"
        }
      }
    }
  }
}
```

改完重载：

```bash
paseo reload
```

然后在 Paseo 里把会话的 provider 选成 `aicentos`。

如果你托管的是 OpenAI 协议的 CLI（例如 Codex），把 `env` 换成对应 CLI 自己的变量（`OPENAI_BASE_URL`、`OPENAI_API_KEY`），Base URL 用 `https://aicentos.com/v1`。

## 测试

```bash
paseo run --provider aicentos-claude "用一句话自我介绍"
```

能返回即通。也可以直接在桌面端新建会话、看模型标签是否显示你配的 provider。

## 注意事项

* **Paseo 本身没有模型配置**。找不到 Base URL 输入框是正常的，去底层 CLI 或 `env` 里找。
* 官方文档只给了 Anthropic 兼容的字段示例，OpenAI 兼容端点的写法没有明文规定，按底层 CLI 的变量名来写、以实测为准。
* `env` 会覆盖底层 CLI 已保存的登录态，配错会导致原本能用的会话也失败，建议新开一个 provider 而不是改默认那条。
* 必须先完成底层 CLI 的认证，Paseo 不代你登录。

## 相关链接

* [Paseo 自定义 provider 文档](https://paseo.sh/docs/custom-providers)
* [paseo 仓库](https://github.com/getpaseo/paseo)

---

# Pi

来源: https://docs.aicentos.com/clients/pi

Language: zh-CN

> 在 Pi 中使用 aicentos —— 配置自定义 OpenAI 兼容端点

Pi 支持指定自定义的 OpenAI 兼容 API 地址。把 Base URL 指向 aicentos、填入 API Key，即可在 Pi 里使用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Pi 创建一个专用 Key（建议命名 `pi`，方便追踪用量）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)
* 文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| Provider | OpenAI Compatible         |
| Base URL | `https://aicentos.com/v1` |
| API Key  | 控制台创建的 Key                |
| Model    | 控制台「模型广场」中的模型名            |

## 配置步骤

* 打开 Pi 的设置，找到 API / 模型配置区域。
* 选择自定义 OpenAI 兼容 provider。
* Base URL 填：`https://aicentos.com/v1`
* API Key 填控制台创建的 Key。
* Model 填控制台「模型广场」中的模型名（参考 [支持的模型](https://docs.aicentos.com/billing/models-list)）。
* 保存，并在会话里选中该模型。

## 测试

发起一轮简单对话，确认能正常返回。用 `/model` 或设置页确认当前模型确实来自 aicentos，而不是内置的默认 provider。

## 注意事项

* Base URL 只填到 `/v1`，不要写成完整接口路径。
* 如果 Pi 同时保留了内置 provider，注意切换回你新建的这条，否则请求不会经过 aicentos。
* 若你的 Pi 版本不提供自定义 Base URL，则无法接入第三方端点，请改用其他支持自定义 Base URL 的客户端。
* 建议为该客户端单独建 Key，便于在控制台按 Key 区分用量。

---

# Prime Agent

来源: https://docs.aicentos.com/clients/prime-agent

Language: zh-CN

> 在 Prime Agent 里接入 aicentos —— 目前只能走 API-key provider，端点字段官方未公开

Prime Agent 是 Prime Intellect 开源的终端编码代理（Rust 实现，MIT 许可），定位是「可自我改进的 RLM harness」。它支持用 API Key 接入外部模型，但**自定义 Base URL 的字段官方没有公开文档**，所以下面分「已确认可用」和「需要自己验证」两段写。

## 准备工作

先在控制台为 Prime Agent 建一个专用 Key（建议命名 `prime-agent`）。

```bash
curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh
```

Windows：

```powershell
irm https://app.primeintellect.ai/prime-agent/install.ps1 | iex
```

## 需要填写的配置

| 字段       | 值                                 |
| -------- | --------------------------------- |
| 认证方式     | 首次启动 `/login`，选 API-key provider  |
| API Key  | 控制台创建的 Key                        |
| Base URL | `https://aicentos.com/v1`（字段名待核实） |
| 模型       | 控制台「模型广场」中的模型名                    |

## 配置步骤

第一次启动执行 `/login`，选择用 API Key 而不是订阅的 provider。这一步是官方文档明确写了的路径。

它已知的配置文件是 `models.json`，官方只公开了模型覆盖的写法：

```json
{
  "providers": {
    "你的provider": {
      "modelOverrides": {
        "你的模型名": { "contextWindow": 128000 }
      }
    }
  }
}
```

`modelOverrides` 只改模型参数，**不是端点定义**。要换端点，需要在 `/login` 选到的 provider 里找到端点字段——官方仓库 README 没有给出字段名，建议先看启动后生成的配置文件里有哪些键，再照着填，不要凭猜。

## 测试

```bash
prime-agent
```

在会话里发一句提示词。若返回鉴权错误，说明 provider 没选对；若能返回但模型名不对，说明端点和模型是分开配的，回去检查 `models.json`。

## 注意事项

* **它不是安全沙箱**，以你的用户权限执行模型生成的 Python 和命令，别在有生产凭证的机器上跑陌生任务。
* 默认带遥测，`PRIME_AGENT_TELEMETRY=0` 可关闭。
* 企业网络需要自定义 CA 时用 `NODE_EXTRA_CA_CERTS`。
* 端点字段官方未公开，属于「需要自己摸」的状态。如果摸不通，改用字段明确的 [Oh My Pi](https://docs.aicentos.com/clients/oh-my-pi) 或 [Gajae Code](https://docs.aicentos.com/clients/gajae-code)。

## 相关链接

* [prime-agent 仓库](https://github.com/PrimeIntellect-ai/prime-agent)

---

# Qwen

来源: https://docs.aicentos.com/clients/qwen

Language: zh-CN

> 在 Qwen Code 中使用 aicentos —— 通过 settings.json 配置 OpenAI 兼容 provider

Qwen Code 支持通过 `settings.json` 里的 `modelProviders` 注册任意 OpenAI 兼容端点。把 `baseUrl` 指向 aicentos，就能在 Qwen Code 里使用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Qwen Code 创建一个专用 Key（建议命名 `qwen-code`，方便追踪用量）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)
* 文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

Qwen Code 需要 Node.js 20+，用 npm 全局安装：

```bash
npm install -g @qwen-code/qwen-code
qwen --version
```

## 需要填写的配置

| 字段      | 值                         |
| ------- | ------------------------- |
| auth 类型 | `openai`（OpenAI 兼容协议）     |
| baseUrl | `https://aicentos.com/v1` |
| envKey  | 存放 Key 的环境变量名（可自定义）       |
| 模型 id   | 控制台「模型广场」中的模型名            |

## 配置步骤

编辑 `~/.qwen/settings.json`：

```json
{
  "env": {
    "AICENTOS_API_KEY": "sk-你的Key"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "baseUrl": "https://aicentos.com/v1",
        "envKey": "AICENTOS_API_KEY"
      }
    ]
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "gpt-4o"
  }
}
```

* `id` 是实际发给服务端的模型 ID，必须和控制台里的模型名一致。
* `modelProviders` 里不写明文 Key，`envKey` 只是"去哪个环境变量取密钥"的引用。
* 密钥优先级：系统环境变量 > `.env` 文件（`~/.qwen/.env`）> `settings.json` 的 `env` 块。
* 如果 aicentos 侧走 Responses 协议，给该模型加 `"wireApi": "responses"`；不写默认走 Chat Completions。

也可以完全不改配置文件，直接用环境变量：

```bash
export OPENAI_BASE_URL="https://aicentos.com/v1"
export OPENAI_API_KEY="sk-你的Key"
export OPENAI_MODEL="gpt-4o"
```

## 测试

启动 `qwen`，用 `/about` 确认当前 endpoint 和模型是否正确，再发一句简单提示词。配置了多个 provider 条目时，可以用 `/model` 切换。

## 注意事项

* 全局配置放 `~/.qwen/settings.json`，项目级配置放项目根目录的 `.qwen/settings.json`，后者优先级更高。
* `security.auth.selectedType` 必须是 `openai`，否则不会走自定义端点。
* 不要把明文 Key 提交进版本库，优先用 `~/.qwen/.env` 或系统环境变量。
* `wireApi` 只是本地路由元数据，不会随请求体发出去；改成 `responses` 前先确认 aicentos 侧支持 `/v1/responses`。
* Base URL 只填到 `/v1`，不要补成完整接口路径。

---

# Reasonix

来源: https://docs.aicentos.com/clients/reasonix

Language: zh-CN

> 在 Reasonix 中使用 aicentos —— 通过 config.toml 自定义 provider 接入

Reasonix 是一个本地编码 Agent（CLI/TUI、桌面端、浏览器 UI、以及编辑器 ACP 四种入口共用同一个引擎）。它没有内置 aicentos provider，但可以往 `~/.reasonix/config.toml` 里加一条 OpenAI 兼容的 `[[providers]]` 记录，把请求转到 aicentos。

## 准备工作

在 aicentos 控制台创建一个专用 Key（建议命名 `reasonix-cli`）。Reasonix 的 provider 密钥存在它自己的全局 `.env` 里，不读 shell 环境变量。

## 需要填写的配置

| 字段            | 值                          |
| ------------- | -------------------------- |
| name          | `aicentos`（本地 provider ID） |
| kind          | `openai`（Chat Completions） |
| base\_url     | `https://aicentos.com/v1`  |
| api\_key\_env | `AICENTOS_API_KEY`         |
| models        | 控制台「模型广场」中的模型名             |

## 配置步骤

* 安装 Reasonix（npm 或 macOS 的 Homebrew）：

  ```bash
  npm i -g reasonix
  ```

* 把 Key 写进 Reasonix 全局 `.env`：

  ```bash
  # macOS / Linux
  echo 'AICENTOS_API_KEY=your_api_key_here' >> ~/.reasonix/.env

  # Windows：%APPDATA%\reasonix\.env
  ```

* 编辑 `~/.reasonix/config.toml`，合并下面这段（不要删掉已有的其它 provider）：

  ```toml
  default_model = "aicentos"

  [[providers]]
  name          = "aicentos"
  kind          = "openai"
  base_url      = "https://aicentos.com/v1"
  models        = ["claude-sonnet-5", "deepseek-v4-pro", "qwen3-coder-plus"]
  default       = "claude-sonnet-5"
  api_key_env   = "AICENTOS_API_KEY"
  context_window = 200000
  ```

* 进入项目目录启动：

  ```bash
  reasonix
  ```

  也可以先用一次性任务验证：`reasonix run "用一句话说明当前目录是什么项目"`。桌面端则走 **Settings → Model → Access → Add model service → Custom provider**。

## 测试

启动后发一句简单提示词，确认能正常流式返回。会话内可用 `/model` 切换模型。

## 注意事项

* `base_url` 只填到 `/v1`，Reasonix 会自行拼接 `/chat/completions`。
* Key 必须写在 `~/.reasonix/.env`；`export` 到 shell 或项目 `.env` 都不会被识别为 provider 密钥。
* `kind` 选 `openai`；`anthropic` 原生类型对应 Anthropic Messages 端点，不适合这里。
* `default_model` 填的是 provider 的 `name`（`aicentos`），不是模型名。
* 如果桌面端自定义 provider 表单要求填完整地址，填 `https://aicentos.com/v1/chat/completions`。
* 项目地址：`https://github.com/esengine/DeepSeek-Reasonix`

---

# Roo Code

来源: https://docs.aicentos.com/clients/roo-code

Language: zh-CN

> 在 Roo Code（VS Code 扩展）新增 OpenAI Compatible 配置，填入 aicentos 的 Base URL 与 Key 即可使用

Roo Code 官方支持 OpenAI Compatible provider，可直接接入当前服务。

## 安装

官方安装页：[https://roocode.com/extension](https://roocode.com/extension)

如果你使用 VS Code 或兼容分支，最直接的安装方式是：

```bash
code --install-extension RooVeterinaryInc.roo-cline
```

你也可以在扩展市场中直接搜索 `Roo Code` 安装官方插件。

## 打开 provider 配置

在 Roo Code 面板中打开设置页，进入模型 provider 配置。

## 需要填写的配置

将 `API Provider` 设为 `OpenAI Compatible`，然后填写：

* Base URL：`https://aicentos.com/v1`
* API Key：你的 `codex_...` 或 `sk-...` 等 Key
* Model ID：`gpt-5-codex-mini`

如果模型下拉里没列出该模型，可以直接手动输入模型名。

## 测试

保存后发起一个新任务，确认 Roo Code 可以正常连通并开始回复。

## 注意事项

* Roo Code 官方文档要求使用 `OpenAI Compatible` provider
* Roo Code 对 OpenAI 兼容 provider 依赖模型支持原生 tool calling
* 对当前服务，Base URL 直接填写 `https://aicentos.com/v1` 即可
* 参考官方文档：[https://docs.roocode.com/providers/openai-compatible](https://docs.roocode.com/providers/openai-compatible)

---

# Senpi (OmO Native)

来源: https://docs.aicentos.com/clients/senpi

Language: zh-CN

> 在 Senpi / OmO 里接入 aicentos —— 配置目录与 openai-compatible provider 的位置

Senpi 是 `pi-mono` 的 fork，npm 包名 `@code-yeongyu/senpi`，可执行文件叫 `senpi`。它同时是 oh-my-openagent（简称 OmO）的运行时，所以「OmO Native」指的是跑在 senpi harness 上的那一套。

## 准备工作

```bash
curl -fsSL https://get.omo.dev/install.sh | bash
omo
```

也可以用 bun 装：

```bash
bun add -g omo-ai
```

项目自述 experimental，官方原话是不要押在生产流水线上。

## 需要填写的配置

配置目录是 `~/.omo/agent/`，可用 `OMO_CODING_AGENT_DIR` 覆盖；旧的 `SENPI_*` 变量仍然兼容。

| 文件              | 作用                      |
| --------------- | ----------------------- |
| `models.json`   | provider 定义（端点、协议、模型列表） |
| `auth.json`     | 密钥                      |
| `settings.json` | 默认模型等偏好                 |

senpi 本体另有一套：`~/.senpi/agent/settings.json`，以及项目级 `.senpi/settings.json`。

| 字段          | 值                           |
| ----------- | --------------------------- |
| provider 协议 | `@ai-sdk/openai-compatible` |
| Base URL    | `https://aicentos.com/v1`   |
| API Key     | 控制台创建的 Key                  |
| 模型          | 控制台「模型广场」中的模型名              |

## 配置步骤

在 `~/.omo/agent/models.json` 里加一个 provider，协议选 OpenAI 兼容那一类（文档给的映射是 `npm: @ai-sdk/openai-compatible`）：

```json
{
  "providers": {
    "aicentos": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://aicentos.com/v1",
        "apiKey": "sk-你的-API-Key"
      },
      "models": {
        "你的模型名": {}
      }
    }
  }
}
```

密钥也可以单独放 `auth.json`，不写进 `models.json`。然后把默认模型写进 `settings.json`。

## 测试

启动 `omo` 或 `senpi`，在模型选择器里确认出现 `aicentos` 下的模型，发一句话确认能返回。

## 注意事项

* 两个配置目录别混：OmO 侧在 `~/.omo/agent/`，senpi 侧在 `~/.senpi/agent/`，改错地方不生效。
* 项目级 `.senpi/settings.json` 会覆盖全局设置，排查问题时先看项目目录。
* 官方文档只给了迁移映射，没有给完整的字面配置片段，上面的结构按 Pi 系约定整理，字段名请以 `omo.dev/docs` 当前版本核对。
* experimental 项目，升级后配置结构可能变。

## 相关链接

* [OmO 文档](https://omo.dev/docs)
* [senpi 仓库](https://github.com/code-yeongyu/senpi)
* [oh-my-openagent 仓库](https://github.com/code-yeongyu/oh-my-openagent)

---

# SillyTavern

来源: https://docs.aicentos.com/clients/sillytavern

Language: zh-CN

> 在 SillyTavern 中添加 aicentos 作为 OpenAI 兼容后端，填入 Base URL 与 API Key 即可使用全部模型

# SillyTavern

SillyTavern 是一个流行的角色扮演聊天应用，支持多种 AI 模型后端。通过配置 OpenAI 兼容 API，可以接入当前服务。

## 打开 API 连接设置

1. 启动 SillyTavern 应用
2. 点击顶部的 API 连接图标
3. 选择 **Chat Completion (OpenAI Compatible)**

## 配置连接信息

在 API 设置面板中填写：

* **API Type**: 选择 `OpenAI`
* **Chat Completion Source**: 选择 `OpenAI` 或 `OpenAI Compatible`
* **API URL**: `https://aicentos.com/v1`
* **API Key**: 填写你的 API Key（如 `codex_...` 或 `sk-...`）
* **Model**: 选择或填写模型 ID（如 `gpt-6-astra`）

## 测试连接

1. 点击 **Connect** 按钮
2. 如果连接成功，状态会显示为绿色
3. 可以开始与角色聊天

## 注意事项

* API URL 填写到 `/v1` 即可，不需要完整的 `/v1/chat/completions` 路径
* 支持流式响应，建议在高级设置中启用
* 可以在模型下拉菜单中手动输入模型 ID

## 官方文档

访问 [SillyTavern 官方文档](https://docs.sillytavern.app/) 了解更多配置选项。

---

# TavernAI

来源: https://docs.aicentos.com/clients/tavernai

Language: zh-CN

> 在 TavernAI 中配置 aicentos 的 OpenAI 兼容接口，填入 Base URL 与 API Key 开始对话

# TavernAI

TavernAI 是一个角色扮演聊天应用，支持通过 OpenAI 兼容接口连接到自定义 API 服务。

## 打开设置

1. 启动 TavernAI 应用
2. 点击右上角的设置图标
3. 找到 **API Settings** 或 **AI Configuration** 部分

## 配置 API 连接

在 API 设置中填写：

* **API Type**: 选择 `OpenAI`
* **API Endpoint**: `https://aicentos.com/v1`
* **API Key**: 填写你的 API Key（如 `codex_...` 或 `sk-...`）
* **Model**: 填写模型 ID（如 `gpt-6-astra`）

## 保存并测试

1. 点击 **Save** 保存设置
2. 返回聊天界面
3. 发送一条消息测试连接

## 注意事项

* 不同版本的 TavernAI 界面可能略有差异
* 确保 API Endpoint 填写到 `/v1` 结尾
* 如果连接失败，检查 API Key 是否正确

## 相关链接

TavernAI 是社区项目，可在 GitHub 上找到相关文档和支持。

---

# Trae

来源: https://docs.aicentos.com/clients/trae

Language: zh-CN

> 在 Trae 的 AI / Model 设置添加自定义 OpenAI 兼容服务，Base URL 指向 aicentos 并填入 API Key

本文档说明如何在 Trae 中使用自定义 OpenAI 兼容配置接入当前服务。Trae 各版本的设置入口可能会变化，因此这里不绑定单一菜单路径，而是说明你需要找到的关键配置项。

## 打开 AI / Model 设置

在 Trae 设置中查找以下关键词对应的配置区域：

* AI
* Models
* Provider
* OpenAI
* Custom

如果当前版本支持自定义 OpenAI 兼容接入，通常会提供模型提供方、API Key 和 Base URL 之类的输入项。

## 需要填写的配置

按当前服务填写：

* Base URL：[https://aicentos.com/v1](https://aicentos.com/v1)
* API Key：你的 codex\_... 或 sk-... 等 Key
* Model ID：以 GET /v1/models 返回结果为准；如果只是先测连通性，可先试 gpt-6-astra

## 测试

保存后新建一个对话、编辑任务或 Agent 任务，确认 Trae 可以正常发起请求并返回内容。

## 注意事项

* 这里填写的是 OpenAI 兼容 Base URL，不要额外补成 /chat/completions 或 /responses 的完整路径
* 如果你当前版本只能选择官方内置模型，或者只能填写官方 OpenAI Key 而不能改 Base URL，那么它不能直接接入当前网关
* 最稳妥的做法，是先用 GET /v1/models 确认可见模型，再回到 Trae 里填写 Model ID

---

# Unsloth

来源: https://docs.aicentos.com/clients/unsloth

Language: zh-CN

> Unsloth 是微调与本地推理框架，不是聊天客户端 —— 说明它接不了 aicentos 的原因

Unsloth 是开源的模型微调与本地推理框架，附带桌面 App 和 Unsloth Studio（浏览器界面）。它的 `Connections` 面板看起来像「模型供应商设置」，但**只能填本地或自建端点，云端供应商是一份固定名单**，没有「任意 OpenAI 兼容 URL」这一项，因此无法把推理请求指向 aicentos。

## 为什么不能直接接入

* Studio 的 `Settings → Connections → Add Provider` 里可选的是 llama.cpp、vLLM、Ollama 这类**本地/自建服务**，填的 Base URL 形如 `http://localhost:8000/v1`。
* 云端方向是一份固定清单（OpenAI、Anthropic、OpenRouter、ChatGPT/Codex）+ API Key，没有自定义端点入口。
* 官方文档里「remote OpenAI-compatible endpoint」指的是**你自己部署的**推理服务，不是第三方聚合网关。
* 方向上它也偏服务端：Unsloth 自己对外提供 OpenAI 兼容 API，是给别人连的。

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| API Key  | 控制台创建的 Key                |
| Base URL | `https://aicentos.com/v1` |
| 模型       | 控制台「模型广场」中的模型名            |

上表是 aicentos 侧的通用参数，供下面的替代方案使用。

## 替代方案

### 方案一：训练归训练，聊天归聊天

用 Unsloth 做微调和本地推理，用 [Cherry Studio](https://docs.aicentos.com/clients/cherry-studio)、[Chatbox](https://docs.aicentos.com/clients/chatbox) 这类客户端接 aicentos 做日常对话。两者互不干扰。

### 方案二：本地起服务，前端接它

Unsloth 暴露的是 OpenAI 兼容接口。`unsloth` 服务起在本地后，把客户端的 Base URL 填成它的地址（例如 `http://localhost:8000/v1`），和填 aicentos 是同一套操作。

### 方案三：要对比效果就换前端

想比较「本地微调模型」和「aicentos 上的通用模型」，用一个支持多 provider 并存的客户端最省事，同界面切换。

## 测试

本地服务起来后先 `curl http://localhost:8000/v1/models` 确认接口活着，再在客户端里发一句提示词。

## 注意事项

* 别把 Studio 的 `Connections` 当成 BYOK 面板，它管的是本地运行时。
* 本地推理吃硬件，长上下文和大批量任务建议走 aicentos。
* 官方文档没有「用第三方 API 生成训练数据」的流程说明，别按这个思路规划流水线。

## 相关链接

* [Unsloth Connections 文档](https://unsloth.ai/docs/integrations/connections)
* [unsloth 仓库](https://github.com/unslothai/unsloth)

---

# Warp

来源: https://docs.aicentos.com/clients/warp

Language: zh-CN

> 在 Warp 中接入 aicentos —— 通过自定义推理端点驱动 Warp Agent

Warp 是终端形态的 Agent 开发环境。它支持 **Custom inference endpoint**：只要对方实现了 OpenAI Chat Completions 接口，就能把 Warp Agent 的模型调用转过去。把端点指向 aicentos，即可用自己账号下的模型驱动 Warp 的 Agent。

## 准备工作

* 把 Warp 更新到包含自定义推理端点的版本（旧版只有 BYOK，不能改 Base URL）。
* 在 aicentos 控制台创建一个专用 Key（建议命名 `warp-terminal`）。
* 确认要用的模型支持 **工具调用（function calling）**，Warp Agent 依赖它来读写文件、执行命令。

## 需要填写的配置

| 字段            | 值                           |
| ------------- | --------------------------- |
| Endpoint name | `aicentos`（自定义，用于在模型选择器里标识） |
| Endpoint URL  | `https://aicentos.com/v1`   |
| API Key       | 控制台创建的 Key                  |
| Model name    | 控制台「模型广场」中的模型 ID            |
| Model alias   | 可选，模型选择器里显示的名字              |

## 配置步骤

* 打开 Warp 设置，搜索 `inference endpoint`，或进入 **Settings → AI**。
* 在 **Custom inference** 区域点击 **Add custom model** / **Add destination**。
* 在弹窗中填写 Endpoint name、Endpoint URL（`https://aicentos.com/v1`）、API Key。
* 在 **Model name** 处填入模型 ID，点 **Add model** 添加更多；可另填 alias 方便识别。
* 保存后，自定义模型会出现在 Warp 的模型选择器中，标识为你的端点名称。

## 测试

在 Warp 里选中刚添加的模型，发一句简单提问（例如「列出当前目录的文件并解释项目结构」）确认能正常返回。自定义端点模型会显示在 agent 模式、工具栏与 ambient agent 的选择器里。

## 注意事项

* Endpoint URL 填 OpenAI 兼容根路径（能拼出 `/v1/chat/completions`），不要写成完整的 `/v1/chat/completions`。
* 端点必须能从**公网**访问：Warp 的请求经它的服务端转发，`localhost`、内网地址会被拒绝。`aicentos.com` 是公网 HTTPS 地址，可直接使用。
* API Key 与端点信息存在**本地设备**的安全存储中，Warp 服务端只在请求时即时使用、不做留存。
* 走自定义端点的请求**不消耗 Warp 的 AI credits**，费用由 aicentos 侧按用量计费；但 Business / Enterprise 方案下本地区 Agent 运行仍会消耗平台 credits。
* 若报 `400 invalid model format`，说明你的网关要求 `provider/model_id` 形式；以控制台给出的模型 ID 为准，必要时按该格式补前缀。
* 自定义端点目前无法单独声明上下文窗口，超长会话可能被提前压缩。
* 官方文档：`https://docs.warp.dev/agent-platform/inference/custom-inference-endpoint/`

---

# Windsurf

来源: https://docs.aicentos.com/clients/windsurf

Language: zh-CN

> 在 Windsurf 确认版本支持自定义 Base URL 后，填入 aicentos 的端点与 API Key 接入

本文档说明如何在 Windsurf 中使用自定义 OpenAI 兼容配置接入当前服务。Windsurf 不同版本的 BYOK 和自定义模型配置能力并不完全一样，所以这里区分两种情况说明。

## 先确认你的版本是否支持自定义 Base URL

在 Windsurf 的模型、订阅或 AI 设置中，查找类似这些入口：

* `Models`
* `BYOK`
* `OpenAI`
* `Custom`
* `Base URL`

如果你只能填写官方 API Key，但没有可编辑的 Base URL，那么这个版本通常只能走官方支持的 BYOK 模式，不能直接改到当前网关。

## 填写自定义连接信息

如果你的版本提供自定义 OpenAI 兼容配置，则填写：

* Base URL：`https://aicentos.com/v1`
* API Key：你的 `codex_...` 或 `sk-...` 等 Key
* Model ID：以 `GET /v1/models` 返回结果为准；如果只是先测连通性，可先试 `gpt-6-astra`

## 测试

保存设置后，新建一个 Cascade 对话或编码任务，确认能正常返回结果。

## 注意事项

* Base URL 应填写 `https://aicentos.com/v1`
* 不要写成完整的 `/v1/chat/completions` 或 `/v1/responses` 路径
* 如果当前版本只开放官方 BYOK、没有自定义 Base URL，就不能直接接这个网关
* Windsurf 官方模型说明页：`https://docs.windsurf.com/windsurf/models`

---

# WorkBuddy

来源: https://docs.aicentos.com/clients/workbuddy

Language: zh-CN

> 在 WorkBuddy 中使用 aicentos —— 通过自定义 OpenAI 兼容配置接入

WorkBuddy 支持配置自定义的 OpenAI 兼容模型。把 Base URL 指向 aicentos、填入 API Key，即可让 WorkBuddy 使用 aicentos 接入的模型。

## 准备工作

在 aicentos 控制台创建一个专用 Key（建议命名 `workbuddy`，方便追踪用量）。

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| Provider | `OpenAI Compatible`       |
| API Key  | 控制台创建的 Key                |
| Base URL | `https://aicentos.com/v1` |
| Model ID | 控制台「模型广场」中的模型名            |

## 配置步骤

* 打开 WorkBuddy 的模型 / AI 设置。
* 把 Provider 设为 **OpenAI Compatible**（或「自定义」）。
* 填入在 aicentos 控制台创建的 API Key。
* 把 Base URL 设为：`https://aicentos.com/v1`
* 填入模型 ID（参考[支持的模型](https://docs.aicentos.com/billing/models-list)），必要时手动输入。
* 保存设置。

## 测试

保存后新建一个对话，发一句简单提示词，确认可以正常连接并返回内容。

## 注意事项

* Base URL 只填到 `/v1`，不要补成完整的 `/chat/completions` 路径。
* 如果当前版本没有可编辑的 Base URL、只能填官方 Key，则无法直接接入此网关，需改用支持自定义端点的客户端。
* 建议先用 `GET /v1/models` 确认可见模型，再回到 WorkBuddy 里填写 Model ID。
* 账户余额不足时请求会失败，先到[钱包页](https://aicentos.com/wallet)确认余额。

---

# ZCode

来源: https://docs.aicentos.com/clients/zcode

Language: zh-CN

> 在 ZCode 中使用 aicentos —— 通过自定义 OpenAI 兼容配置接入

ZCode 支持自定义的 OpenAI 兼容模型配置。把 Base URL 指向 aicentos、填入 API Key，就能在 ZCode 的对话与编码任务中使用 aicentos 接入的模型。

## 准备工作

在 aicentos 控制台创建一个专用 Key（建议命名 `zcode`，方便追踪用量）。

## 需要填写的配置

| 字段       | 值                         |
| -------- | ------------------------- |
| Provider | `OpenAI Compatible`       |
| API Key  | 控制台创建的 Key                |
| Base URL | `https://aicentos.com/v1` |
| Model ID | 控制台「模型广场」中的模型名            |

## 配置步骤

* 打开 ZCode 设置，进入模型 / AI 配置区域。
* 找到 Provider 相关选项，选择 **OpenAI Compatible**（或「自定义 OpenAI」）。
* 填入在 aicentos 控制台创建的 API Key。
* 把 Base URL 设为：`https://aicentos.com/v1`
* 填入模型 ID（参考[支持的模型](https://docs.aicentos.com/billing/models-list)）；下拉列表没有目标模型时直接手动输入。
* 保存设置，如提供 **Verify** 按钮则先点一次。

## 测试

新建一个对话或编码任务，发一句简单提示词，确认能正常返回内容。

## 注意事项

* Base URL 只填到 `/v1`，不要补成完整的 `/chat/completions` 或 `/v1/responses` 路径。
* 如果当前版本只能选择官方内置模型、没有可编辑的 Base URL，则不能直接接入此网关，此时只能改用支持自定义端点的客户端。
* 建议先用 `GET /v1/models` 确认可见模型，再回到 ZCode 里填写 Model ID。
* 账户余额不足时请求会失败，先到[钱包页](https://aicentos.com/wallet)确认余额。

---

# Zed Agent

来源: https://docs.aicentos.com/clients/zed-agent

Language: zh-CN

> 在 Zed 的 Agent Panel 中通过 OpenAI 兼容 Provider 接入 aicentos

Zed 内置了 OpenAI 兼容的 Provider 类型，在 `settings.json` 里声明端点、模型和上下文长度，就能让 Agent Panel 使用 aicentos 接入的模型。

## 准备工作

先在控制台「API Key」页面为 Zed 创建一个专用 Key（建议命名 `zed-agent`）。

* 控制台：[https://aicentos.com](https://aicentos.com)
* 创建 Key：[https://aicentos.com/keys](https://aicentos.com/keys)
* 钱包充值：[https://aicentos.com/wallet](https://aicentos.com/wallet)

Zed 不会把 API Key 写进 `settings.json`，而是读取同名环境变量：Provider ID 会转成大写蛇形再加 `_API_KEY` 后缀。所以 Provider ID 定为 `aicentos` 时，环境变量名就是 `AICENTOS_API_KEY`。

## 需要填写的配置

| 字段                              | 值                         |
| ------------------------------- | ------------------------- |
| Provider ID                     | 自定义，例如 `aicentos`         |
| `api_url`                       | `https://aicentos.com/v1` |
| `available_models[].name`       | 控制台「模型广场」中的模型名            |
| `available_models[].max_tokens` | 模型的上下文窗口                  |
| API Key                         | 环境变量 `AICENTOS_API_KEY`   |

## 配置步骤

* 打开 Zed 的 `settings.json`（命令面板执行 `zed: open settings`）。
* 加入 `language_models.openai_compatible` 配置：

```json
{
  "language_models": {
    "openai_compatible": {
      "aicentos": {
        "api_url": "https://aicentos.com/v1",
        "available_models": [
          {
            "name": "gpt-5",
            "display_name": "GPT-5 (aicentos)",
            "max_tokens": 128000,
            "max_output_tokens": 16384,
            "capabilities": {
              "tools": true,
              "images": false,
              "chat_completions": true
            }
          }
        ]
      }
    }
  }
}
```

* 导出环境变量（写入 `~/.zshrc` 后重新加载）：

```bash
export AICENTOS_API_KEY="sk-你的aicentos密钥"
```

* 打开 Agent Panel，在模型下拉框中选择该 Provider 下的模型。

也可以在 Agent 设置里点击 **Add Provider**，通过图形界面填写 Provider 名称、API URL、模型 ID 和上下文窗口。

## 测试

配置完成后，在 Agent Panel 新建一个对话，先用一句简单提示词轻量测试，确认能正常返回再正式使用工具调用。

## 注意事项

* `api_url` 只填到 `https://aicentos.com/v1`，不要补成完整的 `/chat/completions`；Zed 会自行拼接。
* API Key 不能直接写在 `settings.json` 里，必须用环境变量（或通过 Provider 设置界面存入系统 keychain）；非空环境变量优先于 keychain。
* `max_tokens` 是上下文窗口，建议按模型实际值填写；缺失会导致上下文管理异常。
* 工具调用默认开启（`capabilities.tools`），图片输入和并行工具调用默认关闭，需要时再手动打开。
* 官方文档：[https://zed.dev/docs/ai/llm-providers](https://zed.dev/docs/ai/llm-providers)
* 更多说明见文档站：[https://docs.aicentos.com](https://docs.aicentos.com)

---

# 合同与对公结算

来源: https://docs.aicentos.com/enterprise/billing-contract

Language: zh-CN

> 合同签署、对公转账、对账单与发票开具

## 合同

支持签署企业间合同，线上完成合同签订。合同可约定企业分组、额度、结算周期、对账方式与数据留存等事项。

* **合同是商务约束**：服务范围、付款方式、责任划分
* **赔付型 SLA 是技术承诺**：未达标需赔付，上游冗余与自动故障转移能力托底

实时可用性数据以[状态监控](https://docs.aicentos.com/status)公开为准，**可作为合同附件的事实依据**。

## 对公转账

* 由客服人工受理，对公账户信息在合同签署后提供
* 到账后完成入账，额度实时生效

## 私有化部署的结算

[私有化部署](https://docs.aicentos.com/enterprise/deployment)是可选项，费用单独计算：按项目评估交付范围、许可形式与运维分工，写入合同；模型调用部分仍按量计费。具体口径以合同约定为准。

## 对账单

* 控制台可自助查询全部用量明细，见[用量查询与对账](https://docs.aicentos.com/enterprise/usage-audit)
* 需要正式对账单文件的，由客服按合同约定周期人工整理提供

## 发票

**签订合同的企业客户可开具发票。** 具体票种、开票周期与所需信息，在商务沟通中确认。

开票主体与合同主体一致，在签约环节一并确认；计费说明中的口径与此一致，见[计费说明](https://docs.aicentos.com/billing/pricing)。

---

# 私有化部署

来源: https://docs.aicentos.com/enterprise/deployment

Language: zh-CN

> 把接入网关部署到你自己的环境：调用明细与审计记录全部留在你的边界内

如果合规要求数据不能离开自有环境，或需要长期留存调用明细与审计记录，我们可以把模型接入网关**部署到你自己的服务器或私有云**。业务数据、调用明细、审计记录全部落在你的边界内。私有化是可选项，交付费用单独计算；模型调用部分仍按量计费，见[合同与对公结算](https://docs.aicentos.com/enterprise/billing-contract)。

## 这个形态解决什么

| 诉求          | 私有化部署                                         |
| ----------- | --------------------------------------------- |
| 明细与审计数据不出边界 | 调用明细与审计记录写入**你自己的数据库**，平台侧不接收                 |
| 长期留存与自定义周期  | 保留策略由你设定，支持独立日志库（含 ClickHouse），可配置为不自动清理      |
| 内部审计可检索     | 审计覆盖登录、安全、操作、令牌四类事件，可按用户 / 密钥 / 时间 / 请求 ID 检索 |
| 接入内部系统      | 日志库对你开放，可自行接入 BI、SIEM 或备份流程                   |
| 源码可审计       | 网关基于开源实现（AGPL-3.0），代码公开可查，不存在无法验证的黑盒          |

## 部署形态

| 项    | 说明                                                |
| ---- | ------------------------------------------------- |
| 位置   | 你的内网或私有云                                          |
| 组件   | 网关服务 + 数据库（PostgreSQL / MySQL）+ 缓存（Redis）；日志可独立建库 |
| 交付物  | 容器镜像与编排文件、配置模板、部署说明                               |
| 上游接入 | 渠道与上游连接方式在交付方案中确认                                 |
| 运维   | 部署与日常运维由你或我们按方案分担                                 |

## 部署后可自行配置的能力

私有化不只是“数据留在本地”，也意味着**配置权交到你手里**。以下都是网关本身具备、在公有云形态下由平台统一设定的能力，私有化后由你的管理员自行决定：

| 配置项   | 可自行设定的内容                             |
| ----- | ------------------------------------ |
| 上游渠道  | 接入你自有的上游渠道与密钥，配置渠道分组与可用模型范围          |
| 路由与重试 | 渠道路由策略、失败重试规则、渠道健康检查与自动停用 / 恢复阈值     |
| 认证方式  | 密码登录、OIDC 单点登录、Passkey，以及二次验证的强制策略   |
| 成员与准入 | 自行创建成员账号、分配角色与细粒度权限；用单点登录返回的属性设定准入条件 |
| 请求防护  | 用户级与密钥级的速率限制阈值、请求来源校验规则              |
| 计费与定价 | 模型定价、分组倍率与额度规则，用于内部的成本分摊             |

**这些都是可配置项，交付时不代表已替你配好**，具体开到什么程度、由谁运维，在交付方案中约定。

## 数据边界

```
你的程序  →  你部署的网关  →  上游模型厂商
              ↑
        明细与审计在这里写入你的数据库
```

* 调用明细与审计记录**只写入你的数据库**，平台侧不接收、不存储这部分数据
* 我们不接入你的数据库，也无法远程读取其中的内容
* 请求内容会转发到上游，其数据留存政策按厂商官方条款执行

## 与公有云形态的对照

|         | 公有云（aicentos.com） | 私有化部署            |
| ------- | ----------------- | ---------------- |
| 网关位置    | 平台侧               | 你的环境             |
| 明细与审计记录 | 平台侧数据库，留存可合同约定    | 你的数据库，策略自行设定     |
| 明细导出    | 控制台查询，正式对账单走人工    | 直连你自己的数据库，导出方式自定 |
| 成员账号管理  | 主账号 + 成员密钥 + 分组   | 完整成员账号体系，自行创建与管理 |
| 单点登录    | 未开放               | 对接你自有的身份提供方      |
| 运维责任    | 我们负责              | 按交付方案分担          |
| 模型与上游更新 | 平台维护，你无需改动        | 按交付方案约定          |

## 许可与源码

网关基于 **AGPL-3.0** 开源实现交付。这一点对你有利：**部署在你环境里的代码是可审计的**，任何一方都无法在其中隐藏未声明的数据外发行为。分发与源码提供按该许可证要求执行，具体形式在交付方案中说明。

## 下一步

* 私有化按项目评估，需要先明确规模、合规要求与网络条件，见[合作与开通流程](https://docs.aicentos.com/enterprise/onboarding)
* 交付不改变合同与结算方式，见[合同与对公结算](https://docs.aicentos.com/enterprise/billing-contract)
* 安全口径见[数据安全与合规](https://docs.aicentos.com/enterprise/security-compliance)

---

# 企业级服务

来源: https://docs.aicentos.com/enterprise

Language: zh-CN

> 面向团队的合同与对公结算、多成员密钥治理、可用性透明度，以及私有化部署

aicentos 是面向生产环境的模型接入网关。除自助控制台外，我们为有**合同与对公结算**、**多成员密钥治理**、**可用性可核查**、**数据不出自有边界**需求的团队提供对公合作通道。

## 企业最关心的事

| 关心的事          | 我们的做法                                                                                            | 你可以自己验证                                                          |
| ------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| 稳不稳           | 自建官方账号池，直连官方 API、多账号兜底自动切换，机制见[上游冗余与可用性](https://docs.aicentos.com/enterprise/pool-verification) | [状态监控](https://docs.aicentos.com/status)公开每个模型的实时与历史可用率          |
| 贵不贵           | 倍率对照官方原价公开列示，没有黑箱定价与隐藏倍率                                                                         | [官方定价对照](https://docs.aicentos.com/billing/official-pricing)     |
| 会不会中途消失       | 公司主体对接、可签合同、对公转账、签约后可开发票                                                                         | [合同与对公结算](https://docs.aicentos.com/enterprise/billing-contract) |
| 数据能不能不出边界     | 支持私有化部署，网关与明细审计部署到你自有环境                                                                          | [私有化部署](https://docs.aicentos.com/enterprise/deployment)         |
| 能不能接我们自己的账号体系 | 私有化部署支持单点登录对接自有身份提供方，准入按组织与角色属性自动判定                                                              | [团队协作与权限](https://docs.aicentos.com/enterprise/organization)     |

## 安全与合规

* **全站 HTTPS 加密传输**，HTTP 请求强制跳转，不提供明文入口
* 用量日志只保存**元数据**（模型、token 数、耗时、渠道、请求 ID 等），不保存请求与响应的正文
* 独立记录**操作与访问审计**（登录 / 安全 / 操作 / 令牌四类），与用量日志分开保留；密钥以指纹形式记录，不保存明文
* 每个 API 密钥可独立限制**额度上限、可用模型、来源 IP、有效期**；密钥可随时吊销重发，互不影响
* 私有化部署可**对接你自有的身份提供方**（单点登录），成员准入按组织与角色属性自动判定；账号侧支持二次验证、Passkey 与会话吊销
* 数据不能离开自有环境时，可[私有化部署](https://docs.aicentos.com/enterprise/deployment)，明细与审计记录全部留在你的数据库
* 请求内容的合规责任由调用方承担，我们按上游厂商与当地法规要求配合处理

详见[数据安全与合规](https://docs.aicentos.com/enterprise/security-compliance)。

## 从哪开始

* **先试用**：[快速开始](https://docs.aicentos.com/quickstart)在线注册即可，无需合同，自助能力（密钥管控、用量查询、状态监控）与对公客户完全一致
* **要对公合作**：阅读[合作与开通流程](https://docs.aicentos.com/enterprise/onboarding)，或直接[联系客服](https://docs.aicentos.com/enterprise/support)
* **先看清边界**：[服务模式与能力边界](https://docs.aicentos.com/enterprise/overview)用一张表说明哪些自助、哪些找客服、哪些暂时不做
* **数据不能出内网**：[私有化部署](https://docs.aicentos.com/enterprise/deployment)把网关与明细审计部署到你自己的环境

---

# 接入与集成

来源: https://docs.aicentos.com/enterprise/integration

Language: zh-CN

> 协议兼容、Base URL 与网络层要求

## 协议兼容

| 协议           | Base URL                  | 典型客户端                    |
| ------------ | ------------------------- | ------------------------ |
| OpenAI 兼容    | `https://aicentos.com/v1` | Codex、Cursor 等 OpenAI 生态 |
| Anthropic 兼容 | `https://aicentos.com`    | Claude Code 等            |
| Gemini 原生    | `https://aicentos.com`    | Gemini CLI 等             |

认证统一使用 API 密钥（`Authorization: Bearer <API Key>`；Gemini 原生按其密钥参数传递）。

**这是接入流程里最容易出错的一步**：OpenAI 兼容生态要带 `/v1` 前缀；Anthropic / Gemini 只填根地址，请求路径由客户端自行拼接，不需要手动追加 `/v1/messages`。各客户端的具体填法见[客户端接入](https://docs.aicentos.com/clients/claude-code)。

## 网络要求

* **出站**：你的服务只要能访问 `https://aicentos.com` 即可，无需开放额外端口，也无需配置任何上游厂商地址
* **入站白名单**：API 密钥支持绑定 IP 白名单，只允许指定来源调用
* **内网环境**：可将 aicentos 配置为统一出口，上游连接由平台侧完成，内网只需放通对 `aicentos.com` 的访问

## 私有化部署的接入

采用[私有化部署](https://docs.aicentos.com/enterprise/deployment)时，Base URL 换为你部署的网关地址，协议与认证方式与上表完全一致，客户端配置只需改地址。上游连接方式与网络策略在交付方案中确认。

接入侧有两条相互独立的认证链路，企业客户容易混在一起，这里说清楚：

* **程序调用**走 **API 密钥**，与部署形态无关
* **人员登录控制台**走**账号认证**；私有化部署可对接你自有的身份提供方实现单点登录，见[团队协作与权限](https://docs.aicentos.com/enterprise/organization)

单点登录只作用于人员登录，不改变 API 的调用与鉴权方式——程序侧仍使用密钥，密钥的额度与白名单策略照常生效。

## 多环境建议

* 测试与生产分别签发密钥，独立设置额度与白名单
* 不要把上游地址写进代码——你只需要 aicentos 的地址，上游切换对调用方是透明的

---

# 合作与开通流程

来源: https://docs.aicentos.com/enterprise/onboarding

Language: zh-CN

> 从需求沟通到企业分组开通的完整流程，以及每个环节由谁完成

流程里需要你做的事很少——大部分环节由我们推进，你确认结果即可。

## 流程

| 步骤 | 内容                                                     | 谁来做       |
| -- | ------------------------------------------------------ | --------- |
| 1  | 联系客服，说明团队规模、目标模型与预计用量                                  | 你（约 5 分钟） |
| 2  | 确认分组、额度与结算方式                                           | 双方        |
| 3  | 签署合同                                                   | 双方，线下完成   |
| 4  | 对公转账（账户信息在合同签署后提供）                                     | 你         |
| 5  | 到账后入账，开通 `enterprise-*` 分组与成员密钥                        | 我们        |
| 6  | 技术对接，按[快速开始](https://docs.aicentos.com/quickstart)完成接入 | 双方，有专人跟进  |

各环节的实际耗时与细节以商务沟通为准——不同规模与合规要求的团队差异较大，我们不做统一承诺以免误导。

## 你需要准备的

只有三项：

1. 公司主体名称与联系人
2. 预计用量规模
3. 需要接入的模型范围

合同文本、账户信息、对接文档由我们提供，不需要你预先准备材料。

如需开具发票，另需提供开票信息（企业名称、税号等）——这项在签约环节一并提供即可，不影响流程推进。

## 如果要求私有化部署

部署到你自有环境的需求，流程与对公合作一致，但会多一个**评估环节**：

| 步骤 | 内容                         | 谁来做 |
| -- | -------------------------- | --- |
| 1  | 说明部署环境：网络条件、服务器或私有云位置、合规要求 | 你   |
| 2  | 确定部署范围、上游接入方式与运维分工         | 双方  |
| 3  | 签署合同，明确交付物、许可形式与责任边界       | 双方  |
| 4  | 交付部署并上线，含明细与审计的留存配置        | 双方  |
| 5  | 如需单点登录，对接你自有的身份提供方并设定准入条件  | 双方  |

单点登录为可选项，不接入也可以使用本地账号密码登录。身份与权限的具体范围见[团队协作与权限](https://docs.aicentos.com/enterprise/organization)。

交付形态与数据边界见[私有化部署](https://docs.aicentos.com/enterprise/deployment)。

## 只想先试用

不需要走对公流程。[在线注册](https://aicentos.com/)并充值即可使用，自助能力（密钥管控、用量查询、状态监控）与对公客户完全一致。后续要升级为对公合作，已有余额与密钥不受影响，不需要迁移。

---

# 团队协作与权限

来源: https://docs.aicentos.com/enterprise/organization

Language: zh-CN

> 用分组与成员密钥组织团队，以及当前可用的权限层级

## 公有云形态

公有云下的团队组织方式是 **“主账号 + 成员密钥 + 分组”**，这套组合可以覆盖大多数团队的隔离与成本归集需求：

* 为每个成员或每个项目签发独立 API 密钥，用量与日志按密钥区分，成本可直接归因到人
* 通过**分组**控制密钥可用的模型池与计费倍率
* 需要企业分组（`enterprise-china` / `enterprise-claude` / `enterprise-codex` / `enterprise-gemini`）时，[联系客服](https://docs.aicentos.com/enterprise/support)申请开通

密钥本身的多维管控（额度上限、模型白名单、IP 白名单、有效期）见[数据安全与合规](https://docs.aicentos.com/enterprise/security-compliance)。

## 权限层级

控制台账号分四级，能力逐级放开：

| 角色     | 适用场景             |
| ------ | ---------------- |
| Root   | 账号所有者，全部管理权限     |
| Admin  | 管理员，负责渠道与用户管理    |
| Common | 普通用户，创建密钥并调用 API |
| Guest  | 只读预览             |

## 私有化部署形态

采用[私有化部署](https://docs.aicentos.com/enterprise/deployment)时，成员账号体系是完整的：账号由你自行创建与管理，角色层级与上表一致，并可对每个成员单独设定配额与细粒度权限。审计查询权限可单独授予某个账号，用于给财务或合规岗开通只读视图。

### 单点登录

私有化部署支持对接你自有的身份提供方（OIDC 标准，可通过 Discovery 自动获取端点）。成员用你的账号体系登录，无需在网关侧另建一套密码。

登录准入可以按身份提供方返回的属性设定条件，例如**限定某个组织、某个角色，或满足特定属性的账号才允许登录**。条件支持等于、包含、数值范围等组合判断，不满足时返回自定义的提示信息。

这一条实际替代了“成员审批流”：人员能否进入由规则自动判定，**不需要人工逐个审批，规则调整也不必等排期**——人员入职、转岗、离职由你的账号体系驱动，权限跟着组织变动走。

### 组织边界

一个部署实例对应一个组织边界，实例内的成员与权限由你管理。

如果需要在**同一实例内划分多个互不可见的组织**（例如集团下多家子公司共用一套部署、彼此数据不可见），当前不支持，需要按实例分别部署来评估。

## 暂不支持

* 跨成员的统一配额池
* 同一实例内划分多个互不可见的组织（需要时按实例评估）

完整的能力清单见[服务模式与能力边界](https://docs.aicentos.com/enterprise/overview)。

---

# 服务模式与能力边界

来源: https://docs.aicentos.com/enterprise/overview

Language: zh-CN

> 哪些在控制台自助、哪些联系客服，以及各项能力在公有云与私有化部署下的差异

企业合作中的每一件事，只有两种交付形态：**控制台自助**，或**联系客服人工处理**。下表是完整对照，先把话说清楚，省掉来回确认的成本。

## 服务模式对照

| 事项                                      | 控制台自助 | 联系客服 |
| --------------------------------------- | ----- | ---- |
| 注册、充值、余额与账单查询                           | ✅     |      |
| 创建与管理 API 密钥（额度 / 模型白名单 / IP 白名单 / 有效期） | ✅     |      |
| 查询用量与调用明细                               | ✅     |      |
| 查询操作与访问审计记录                             | ✅     |      |
| 查看模型可用率、延迟与历史                           | ✅     |      |
| 对公转账                                    |       | ✅    |
| 合同签署                                    |       | ✅    |
| 专项额度与配置调整                               |       | ✅    |
| 正式对账单文件                                 |       | ✅    |
| 私有化部署评估                                 |       | ✅    |
| 发票（签约企业客户）                              |       | ✅    |

## 能力现状

**部署形态会改变能力上限**，所以下表把公有云与私有化部署分列对照。私有化的交付方式见[私有化部署](https://docs.aicentos.com/enterprise/deployment)。

| 能力                                     | 公有云       | 私有化部署     | 说明                                                         |
| -------------------------------------- | --------- | --------- | ---------------------------------------------------------- |
| 密钥多维管控（额度 / 模型白名单 / IP 白名单 / 有效期）      | ✅ 已有      | ✅ 已有      | 控制台自助                                                      |
| 四级账号角色（Guest / Common / Admin / Root）  | ✅ 已有      | ✅ 已有      | 两种形态一致                                                     |
| 成员账号体系（创建 / 停用 / 批量操作 / 配额 / 细粒度权限）    | ⚠️ 部分     | ✅ 完整      | 公有云下以“主账号 + 成员密钥 + 分组”承接；私有化后账号由你自行创建与管理                   |
| 单点登录（SSO / OIDC）                       | ✖ 未开放     | ✅ 支持      | 对接你自有的身份提供方；可按其返回的组织、角色等属性设定准入条件                           |
| 组织架构与成员审批流                             | ✖ 暂不支持    | ⚠️ 单实例单租户 | 一个部署实例对应一个组织边界，实例内做成员与权限管理；同一实例内划分多个互不可见的组织当前不支持           |
| 跨成员统一配额池                               | ✖ 暂不支持    | ✖ 暂不支持    | 配额按成员 / 密钥单独设定                                             |
| 用量与审计数据自助导出                            | ✖ 暂不支持    | ✅ 数据在你的库中 | 公有云下正式对账单走人工；私有化后明细与审计写入你的数据库，可用 SQL、BI 或备份流程自行导出          |
| 操作与访问审计（登录 / 安全 / 操作 / 令牌四类）           | ✅ 已有      | ✅ 已有      | 独立于用量日志保留，查询权限可单独授予                                        |
| 用量多维查询（用户 / 密钥 / 模型 / 时间 / 渠道 / 请求 ID） | ✅ 已有      | ✅ 已有      | 控制台自助                                                      |
| 渠道级自动故障转移（失败重试换渠道、优先级分层、自动停用与恢复）       | ✅ 已有      | ✅ 已有      | 平台内建；私有化后路由与重试策略可自行配置                                      |
| 二次验证与会话吊销（动态口令、备份码、改密后会话失效）            | ✅ 已有      | ✅ 已有      | 控制台自助；私有化后可设为强制                                            |
| Passkey 通行密钥登录（WebAuthn）               | ✖ 未开放     | ✅ 支持      | 不依赖密码，私有化后可按需启用                                            |
| 速率限制与请求防护（用户级 / 密钥级限流、SSRF 防护）         | ⚠️ 平台统一策略 | ✅ 可自配     | 私有化部署下阈值由你设定                                               |
| 全模型实时探活与公开可用率                          | ✅ 已有      | —         | 公有云提供[状态监控](https://docs.aicentos.com/status)；私有化后按需自行部署监控 |
| 私有化部署（网关与明细审计部署到你自有环境）                 | —         | ✅ 可交付     | 数据留在你的数据库，按项目评估                                            |

上表标注“暂不支持”或“部分支持”的能力，如果有明确需求，欢迎告知具体场景——真实的业务需求是我们排期的依据。

## 关于发票

签订合同的企业客户可以开具发票，票种、开票周期与所需信息在商务沟通中确认，详见[合同与对公结算](https://docs.aicentos.com/enterprise/billing-contract)。

开票主体与合同主体一致，建议在[合作与开通流程](https://docs.aicentos.com/enterprise/onboarding)初期就一并说明，避免签完再补。

---

# 上游冗余与可用性

来源: https://docs.aicentos.com/enterprise/pool-verification

Language: zh-CN

> 上游如何组池、故障如何自动切换，以及可用性数据在哪自行核查

## 上游怎么组池

aicentos 的上游是平台**自建的官方账号池**：全部直连厂商官方 API，按模型家族分配，同一个模型通常同时挂在多个账号之下做兜底。

* **单家异常自动切换**：某条上游返回失败时，请求自动重试到下一家，不需要你改任何配置
* **优先级与权重**：稳定、低延迟的上游排在前，按权重分流
* **自动隔离与恢复**：持续失败的上游自动停用，恢复正常后自动重新纳入
* **跨分组重试**：`auto` 分组可在分组之间重试，进一步降低单点失败的影响

这套机制是平台内建的，默认作用于你的全部请求，无需额外开通。

## 可用性可以自己查

上游全部为厂商官方 API 直连；账号池的具体规模与账号明细属于内部运营信息，不对外披露。但**可用性不需要靠名单来相信**：

* [状态监控](https://docs.aicentos.com/status)：每个在测模型的 1 小时 / 24 小时 / 7 天可用率、响应延迟、端点 PING，全部来自真实探测，可随时自行核对
* [官方定价对照](https://docs.aicentos.com/billing/official-pricing)：倍率对照官方原价列示，价格透明度同样可自行核算

## 关于“模型真实性”

有一点必须说清楚：上游是官方 API 直连，但**中转层无法向调用方提供“原厂鉴定”**——响应里没有可用于验证来源的水印，任何转发型网关在技术上都无法向第三方证明返回结果的归属，这是架构决定的边界。我们能承诺并公开的是上游形态（自建官方账号池 + 多账号冗余）与真实探测数据。

如果你的采购或合规要求必须由厂商主体直接提供 SLA 与赔付，建议直接使用官方渠道。如果你要的是**稳定的可用性、透明的价格、可自行核查的数据**，这里展示的都是真实探测结果。

---

# 数据安全与合规

来源: https://docs.aicentos.com/enterprise/security-compliance

Language: zh-CN

> 传输加密、部署形态与数据边界、日志记录范围、密钥治理与责任边界

数据安全是这个产品的第一要求。本页说明数据如何流动、平台记录什么、双方的合规边界在哪——按可核查的事实写，不做无法验证的承诺。

## 数据流向

请求只经过两个环节：

```
你的程序  →  aicentos 网关  →  上游模型厂商
```

* **aicentos 网关**：负责鉴权、路由、计费与故障切换，是数据经过的唯一中间环节
* **上游模型厂商**：推理最终由上游完成，其数据留存政策按其官方条款执行，这部分不由我们控制

平台上没有第三方数据接收方，我们不将调用数据用于转售或二次分发。

## 部署形态与数据边界

提供两种部署形态，数据边界不同，按你的合规要求选择：

|           | 公有云（aicentos.com） | [私有化部署](https://docs.aicentos.com/enterprise/deployment) |
| --------- | ----------------- | -------------------------------------------------------- |
| 网关位置      | 平台侧               | 你的内网或私有云                                                 |
| 调用明细与审计记录 | 平台侧数据库，留存可合同约定    | 你的数据库，我们不接收、不存储                                          |
| 留存策略      | 平台策略              | 由你自行设定                                                   |
| 身份认证      | 平台账号体系            | 可对接你自有的身份提供方（OIDC 单点登录）                                  |

无论哪种形态，请求内容都会在转发到上游时还原为原文，详见下文传输加密。私有化部署把**平台侧的留存降到零**，适合要求数据不离开自有边界的场景。

## 传输加密

* **全站 HTTPS（TLS）加密传输**：控制台、文档站、状态站均强制 HTTPS，HTTP 请求自动跳转，不提供明文入口
* API 调用同样只经 HTTPS 传输，不提供明文端口

把措辞说准确：aicentos 是**转发型网关**，请求需要在上游还原为原文才能完成调用，因此这里不是“端到端加密”——那是点对点直连才成立的模型。我们在**传输链路上加密**，并把**存储侧的数据范围压到最小**，这是这种架构下真实能做到的上限。把做不到的说成做得到，对你没有价值。

## 平台记录什么

用量日志只保存**元数据**，用于计费、路由归因与故障排查：

| 记录项                                 | 用途          |
| ----------------------------------- | ----------- |
| 模型、分组、渠道                            | 计费与路由归因     |
| prompt / completion token 数、耗时、是否流式 | 计费与性能分析     |
| API 密钥标识、调用方 IP                     | 权限追溯与风控     |
| 请求 ID、上游请求 ID                       | 故障定位与对账     |
| 错误信息                                | 故障排查与上游质量评估 |

**请求与响应的正文内容不写入日志**，控制台也不提供按对话内容检索的能力。

除用量日志外，系统还独立记录**操作与访问审计**（登录、安全、操作、令牌四类事件），用于回答“谁在何时用哪个密钥做了什么”；审计同样不包含调用内容，且**独立于用量日志的清理策略保留**。密钥以指纹形式记录，不保存明文。详见[明细查询与审计](https://docs.aicentos.com/enterprise/usage-audit)。

需要约定特定的日志保留周期或删除策略，可在合同中单独写明。

## 身份与访问控制

除密钥管控外，账号侧的访问控制包括：

* **登录方式**：密码登录；私有化部署可对接你自有的身份提供方（OIDC 标准）实现单点登录
* **Passkey**：基于 WebAuthn 的通行密钥登录，不依赖密码；公有云暂未开放，私有化部署可启用
* **二次验证**：支持动态口令与一次性备份码，可按你的安全要求设为强制
* **会话吊销**：密码或权限发生变更后，该账号的所有已登录会话立即失效，需重新登录
* **权限最小化**：管理权限可细分到具体功能项，审计查询权限可单独授予——给财务或合规岗开只读视图，不涉及其他管理功能

单点登录的准入条件可按身份提供方返回的组织、角色等属性设定，人员的进入与退出由你的账号体系驱动，见[团队协作与权限](https://docs.aicentos.com/enterprise/organization)。

## 密钥治理

每个 API 密钥可独立配置、随时吊销：

* **额度上限**：控制成本，也限定意外泄露后的损失上限
* **模型白名单**：只放开该业务确实需要的模型
* **IP 白名单**：限定调用来源
* **有效期**：临时授权到期自动失效

密钥可随时吊销并重新签发，单个密钥泄露不影响其他密钥。

## 责任边界

* 请求内容与生成内容的合规性由调用方负责；我们按上游厂商与当地法规要求配合处理
* 如需 NDA 或更详细的安全口径，可通过[服务与支持](https://docs.aicentos.com/enterprise/support)沟通

## 接入侧建议

* 不要把 API 密钥写进前端代码或公开仓库
* 为密钥设置有效期与 IP 白名单，缩小意外泄露的影响面
* 测试与生产环境使用不同密钥，分别设置额度

---

# 服务与支持

来源: https://docs.aicentos.com/enterprise/support

Language: zh-CN

> 联系方式、响应方式与故障自查入口

## 联系我们

* 邮箱：[aicentos@88.cn](mailto:aicentos@88.cn)
* 微信：点击**页面左下角的“客服”悬浮按钮**，扫码或搜索微信号 `dext7r`

企业合作与故障问题优先使用邮箱，便于留档与跟进。

## 响应方式

| 场景         | 怎么处理                                                                                |
| ---------- | ----------------------------------------------------------------------------------- |
| 对公合作、合同与结算 | 邮箱沟通，按工作时段回复                                                                        |
| 怀疑服务异常     | 先查[状态监控](https://docs.aicentos.com/status)：每个模型的可用率、延迟、端点 PING 都在上面，多数“是不是挂了”当场就有答案 |
| 确认是平台侧故障   | 邮箱告知，我们跟进后回复处理结果                                                                    |
| 对接与通报方式    | 对公客户可在合同中约定具体的对接人与通报方式                                                              |

## 私有化部署的支持范围

[私有化部署](https://docs.aicentos.com/enterprise/deployment)的部署实施与上线由双方按交付方案推进；上线后的运维分工、响应时效与升级方式在合同中约定——不同客户的网络与合规条件差异较大，我们不做统一承诺。

## 自助排查

状态页公开每个在测模型的 1 小时 / 24 小时 / 7 天可用率、响应延迟与端点 PING。先查状态页通常比等人回复更快，也能立刻区分“自己的网络问题”和“平台侧问题”。

## 我们承诺什么、不承诺什么

* ✅ 工作时段内回复邮件
* ✖ 不承诺 7×24 专属人工值守
* ✖ 不提供电话支持

完整的服务边界见[服务模式与能力边界](https://docs.aicentos.com/enterprise/overview)。

---

# 明细查询与审计

来源: https://docs.aicentos.com/enterprise/usage-audit

Language: zh-CN

> 调用明细的查询维度、审计记录覆盖的事件范围，以及导出与留存方式

## 调用明细

控制台可按以下维度查询每一笔调用：用户 / API 密钥、模型与分组、时间范围、渠道、请求 ID 与上游请求 ID。每笔调用的 token 数与费用逐条可追溯，可按密钥做成本归因。

## 审计记录

除用量之外，系统**独立记录操作与访问审计**，覆盖四类事件：

| 类别 | 覆盖事件                     |
| -- | ------------------------ |
| 登录 | 登录、登出、二次验证               |
| 安全 | 密钥、密码、权限相关变更             |
| 操作 | 管理端写操作（新增接口自动留痕，不依赖人工埋点） |
| 令牌 | API 密钥的签发与使用             |

每条记录包含：**谁**（账号，以及事件发生时的角色）、**何时**、**从哪个 IP**、**使用哪个密钥**、**调用了哪个接口**、**成功与否**、请求 ID。

密钥以**指纹**形式记录，不保存密钥明文。

有一点需要说清楚：**审计记录的是操作与访问行为，不包含调用内容**。请求与响应的正文不写入任何日志表——上面的字段能回答“谁在什么时候用哪个密钥做了什么事”，不能回答“这次调用说了什么”。

## 留存

**审计记录独立于用量日志的清理策略保留**：用量日志可能按周期清理，审计记录不受影响，适合需要长期留档的场景。

需要自定义留存周期、或把记录同步到内部审计系统，可在合同中约定，采用[私有化部署](https://docs.aicentos.com/enterprise/deployment)时留存策略完全由你设定。

## 权限

* 审计查询权限可**单独授予某个账号**，用于给财务或合规岗开通只读审计视图，不涉及其他管理功能
* 每个成员也可以查询自己名下的调用记录

## 导出与对接

导出的能力取决于部署形态：

|          | 公有云（aicentos.com）           | [私有化部署](https://docs.aicentos.com/enterprise/deployment) |
| -------- | --------------------------- | -------------------------------------------------------- |
| 控制台查询与检索 | ✅ 自助                        | ✅ 自助                                                     |
| 导出为文件    | ✖ 目前不提供自助导出，正式对账单由客服按合同周期整理 | ✅ 明细与审计在你的数据库，可用 SQL、BI 或备份流程自行导出                        |
| 对接内部系统   | 需人工配合                       | ✅ 直接对接 SIEM、数据仓库或报表平台                                    |

如果你需要把用量或审计记录定期落到内部系统，私有化是更合适的形态——数据本来就在你的库里，不需要经过我们。

公有云形态下如确有导出需求，可在商务沟通中说明，见[服务与支持](https://docs.aicentos.com/enterprise/support)。

## 与合同的关系

对公客户的账单口径以合同约定为准，见[合同与对公结算](https://docs.aicentos.com/enterprise/billing-contract)。

---

# 数据与隐私

来源: https://docs.aicentos.com/faq/data-privacy

Language: zh-CN

> 请求内容会不会被保存、日志记录什么、数据留在哪里、私人使用与合规场景的边界

## 数据与隐私

**结论：网关只做转发与计费，不保存对话正文，也不把调用数据用于转售或二次分发；数据要求不出自有边界时，可以私有化部署。**

## 请求内容会被保存吗？

不会。请求与响应的正文**不写入日志**，控制台也不提供按对话内容检索的能力。

## 平台到底记录什么？

用量日志只保存元数据，用于计费、路由归因与故障排查：

| 记录项                                 | 用途          |
| ----------------------------------- | ----------- |
| 模型、分组、渠道                            | 计费与路由归因     |
| prompt / completion token 数、耗时、是否流式 | 计费与性能分析     |
| API 密钥标识、调用方 IP                     | 权限追溯与风控     |
| 请求 ID、上游请求 ID                       | 故障定位与对账     |
| 错误信息                                | 故障排查与上游质量评估 |

此外独立记录操作与访问审计（登录、安全、操作、令牌四类事件），同样不包含调用内容。密钥以指纹形式记录，不保存明文。

## 数据会流向哪些第三方？

只有上游模型厂商。请求链路是：

```
你的程序  →  aicentos 网关  →  上游模型厂商
```

上游厂商的数据留存政策按其官方条款执行，这部分不由平台控制。平台上没有其他第三方数据接收方。

## 数据会存在哪里？

取决于部署形态：

|           | 公有云（aicentos.com） | 私有化部署           |
| --------- | ----------------- | --------------- |
| 网关位置      | 平台侧               | 你的内网或私有云        |
| 调用明细与审计记录 | 平台侧数据库，留存可合同约定    | 你的数据库，平台不接收、不存储 |
| 留存策略      | 平台策略              | 由你自行设定          |

数据不能离开自有环境时，选[私有化部署](https://docs.aicentos.com/enterprise/deployment)；要求数据留存的周期与删除策略，也可以在合同中单独写明。

## 能约定日志留存周期或删除策略吗？

可以。签约客户可在合同中约定特定的保留周期或删除策略，具体通过[服务与支持](https://docs.aicentos.com/enterprise/support)沟通。

## 我用它做私人用途，内容会被看到吗？

正文不落日志、不用于训练或转售，这是架构层面的默认设置，不区分客户类型。但请注意：**请求仍会经过上游厂商**，其政策按官方条款执行；如果内容敏感程度高到不能离开自有环境，应选择私有化部署。

## 更完整的说明在哪？

* 数据流向、传输加密、日志字段与责任边界：[数据安全与合规](https://docs.aicentos.com/enterprise/security-compliance)
* 审计记录的范围与查询方式：[明细查询与审计](https://docs.aicentos.com/enterprise/usage-audit)
* 密钥治理的具体能力：[数据安全与合规](https://docs.aicentos.com/enterprise/security-compliance)的"密钥治理"一节

---

# 常见问题

来源: https://docs.aicentos.com/faq

Language: zh-CN

> API 中转安全吗、和官方 API 有什么区别、怎么验证稳定性、数据怎么处理 —— aicentos 的高频问题集中回答

这里集中回答接入前后最常被问到的问题。每个问题先给结论，再给可以自行核对的入口。

## aicentos 是什么

aicentos 是面向开发者的 AI API 中转聚合平台。你用一组 API Key 统一调用 OpenAI、Anthropic、Google、xAI、DeepSeek、阿里通义、智谱、Moonshot、MiniMax 等厂商的大模型，兼容 OpenAI、Anthropic、Gemini 三种主流协议。

完整背景见 [aicentos 介绍](https://docs.aicentos.com/introduction)。

## API 中转安全吗

**结论：传输链路加密、正文不写日志、密钥可控可吊销；但它不是端到端加密，也不提供“原厂鉴定”。**

* 全站 HTTPS，不提供明文入口
* 用量日志只保存元数据（模型、token 数、耗时、渠道、请求 ID），不保存请求与响应正文
* 每个密钥可单独设置额度上限、模型白名单、IP 白名单与有效期

细节、边界和做不到的部分写在[API 中转安全吗](https://docs.aicentos.com/faq/security)。

## 和官方 API 有什么区别

**结论：接口格式与官方一致，差别在接入方式、计费与治理能力。**

* 协议兼容：OpenAI 兼容格式用 `https://aicentos.com/v1`，Anthropic 格式用根地址 `https://aicentos.com`，Gemini 用 `/v1beta` 原生端点
* 计费：人民币预充值 + 按量计费，无需海外信用卡
* 治理：一个控制台统一管理密钥、余额、用量与日志
* 上游：自建官方账号池，直连厂商官方 API，多账号兜底、失败自动切换

完整对照见[和官方 API 有什么区别](https://docs.aicentos.com/faq/vs-official)。如果你的采购或合规要求必须由厂商主体直接提供 SLA 与赔付，建议直接使用官方渠道。

## 稳定性与可用率怎么验证

**结论：不用相信宣传，[状态监控](https://docs.aicentos.com/status)公开每个在测模型的 1 小时 / 24 小时 / 7 天可用率、响应延迟与端点 PING，数据来自真实探测。**

连续多次巡检失败的模型会被自动禁用并暂时移出面板；上游下架的模型也不再显示。查看方式与判读方法见[稳定性与可用率如何验证](https://docs.aicentos.com/faq/stability)。

## 数据与隐私怎么处理

**结论：网关只做转发与计费，不保存对话正文；数据不能离开自有环境时可选私有化部署。**

两种部署形态的数据边界不同：公有云下调用明细留在平台侧，私有化部署下明细与审计全部写入你自己的数据库。详见[数据与隐私](https://docs.aicentos.com/faq/data-privacy)。

## 怎么判断一个中转服务值不值得选

不针对任何具体服务，给一份可执行的核查清单：

1. **可用性能不能自己查**：有没有公开的、带时间窗口的可用率与延迟数据，而不是一张宣传图
2. **计费口径透不透明**：单价、分组倍率、按次计费的模型是否逐项列出
3. **密钥治理到不到位**：额度上限、模型白名单、IP 白名单、有效期、即时吊销是否齐全
4. **数据边界说不说得清**：日志记什么、不记什么，能否约定留存周期
5. **主体与合同**：能否签合同、对公转账、开发票
6. **承诺是否留有余地**：把"做不到"的部分也写出来的服务，通常比全是形容词的更可信

aicentos 在这几项上的具体做法，分别见[稳定性与可用率如何验证](https://docs.aicentos.com/faq/stability)、[计费](https://docs.aicentos.com/billing/pricing)、[数据安全与合规](https://docs.aicentos.com/enterprise/security-compliance)、[合同与对公结算](https://docs.aicentos.com/enterprise/billing-contract)。

## 同一个 Key 能在多个客户端里用吗

可以。同一个 API Key 可以填进 Claude Code、Cursor、Cline、Cherry Studio 等任意客户端，客户端之间互不影响。想按项目区分成本，建议分别创建密钥，并给每个密钥设置独立额度。

69 款客户端的配置教程见[客户端接入](https://docs.aicentos.com/clients/claude-code)。

## 注册和计费从哪里开始

注册即送 ¥1 体验额度，无需先充值即可跑通第一个请求；余额永不过期，充值走支付宝。三步接入见[快速开始](https://docs.aicentos.com/quickstart)，计费口径见[计费](https://docs.aicentos.com/billing/pricing)。

## 还有问题没回答

* 想自己核对模型清单与价格：[模型定价页](https://aicentos.com/pricing)实时显示
* 企业合作、合同、发票与私有化部署：[企业级服务](https://docs.aicentos.com/enterprise)
* 直接联系：[服务与支持](https://docs.aicentos.com/enterprise/support)

---

# API 中转安全吗

来源: https://docs.aicentos.com/faq/security

Language: zh-CN

> aicentos 的传输加密、日志范围、密钥治理与责任边界 —— 哪些做得到、哪些做不到，逐条说清楚

## API 中转安全吗？

**结论：在"转发型网关"这个架构下，能做到的安全措施都做了，但它的安全上限不等于端到端加密，也不提供可核验的"原厂鉴定"。** 下面按可核查的事实逐条说明。

## 请求经过哪些环节？

只有两个环节：

```
你的程序  →  aicentos 网关  →  上游模型厂商
```

网关负责鉴权、路由、计费与故障切换；推理由上游厂商完成。平台上没有第三方数据接收方，不将调用数据用于转售或二次分发。

## 传输是加密的吗？

是。控制台、文档站、状态站与 API 调用全部强制 HTTPS，HTTP 请求自动跳转，不提供明文端口。

## 它是不是端到端加密？

**不是，也不应该是这个说法。** aicentos 是转发型网关，请求必须在上游还原为原文才能完成调用；端到端加密是点对点直连才成立的模型。真实情况是：**传输链路加密，存储侧的数据范围压到最小**。

## 平台日志会保存我的对话内容吗？

不会。用量日志只保存元数据：模型、分组、渠道、prompt / completion token 数、耗时、是否流式、密钥标识、调用方 IP、请求 ID 与错误信息。**请求与响应的正文不写入日志**，控制台也不提供按对话内容检索的能力。

密钥以指纹形式记录，不保存明文。此外系统独立记录操作与访问审计（登录 / 安全 / 操作 / 令牌四类事件），同样不包含调用内容。

## 密钥泄露了怎么办？

每个密钥可独立配置、随时吊销：

* **额度上限**：限定意外泄露后的损失上限
* **模型白名单**：只放开业务确实需要的模型
* **IP 白名单**：限定调用来源
* **有效期**：临时授权到期自动失效

单个密钥吊销不影响其他密钥。建议测试与生产环境使用不同密钥。

## 请求内容的合规责任在谁？

请求内容与生成内容的合规性由调用方负责；平台按上游厂商与当地法规要求配合处理。需要 NDA 或更详细的安全口径，可通过[服务与支持](https://docs.aicentos.com/enterprise/support)沟通。

## 想让数据完全不离开自有环境呢？

可以选择[私有化部署](https://docs.aicentos.com/enterprise/deployment)：网关、调用明细与审计记录全部部署在你自己的服务器或私有云，平台侧不接收数据。私有化形态下留存策略由你设定，也可启用 Passkey 与自有身份提供方的单点登录。

## 哪些是我该自己核对的？

* 完整的日志字段与责任边界：[数据安全与合规](https://docs.aicentos.com/enterprise/security-compliance)
* 两种部署形态的数据边界对照：同上页的"部署形态与数据边界"
* 密钥治理与审计查询方式：[明细查询与审计](https://docs.aicentos.com/enterprise/usage-audit)

---

# 稳定性与可用率如何验证

来源: https://docs.aicentos.com/faq/stability

Language: zh-CN

> 状态监控怎么看、可用率与延迟怎么读、上游故障如何自动切换 —— 不靠宣传，自己核对

## 稳定性与可用率如何验证？

**结论：不看宣传，看数据。[状态监控](https://docs.aicentos.com/status)公开每个在测模型的可用率、响应延迟与端点 PING，全部来自真实探测，可随时自行核对。**

## 状态页能看到什么？

* 每个在测模型的 **1 小时 / 24 小时 / 7 天可用率**
* **响应延迟**与**端点 PING**
* 检测历史，可按模型查看

面板只展示**当前在测**的模型：连续多次巡检失败的模型会被自动禁用、暂时移出列表；上游已下架的模型也不再显示。所以"面板上找不到某个模型"本身就是一条信息。

## 为什么要按三个时间窗口看？

* **1 小时**：看当下是否抖动，排查"是不是现在挂了"
* **24 小时**：看白天高峰的整体表现，最有参考价值
* **7 天**：看偶发故障频率，判断是不是长期问题

只看单点数值容易被一次偶发故障误导，三个窗口一起看才接近真实体验。

## 可用率数字该怎么读？

* **99.9% 与 99% 的差距不小**：按 24 小时算，99.9% 约等于 1.4 分钟不可用，99% 约等于 14 分钟
* **可用率要配合延迟一起看**：响应正常但延迟翻倍，业务侧一样会超时
* **看分模型而不是看全站**：一个模型故障不代表全站故障，反之亦然

我们自己也在用同一套数据排查问题：怀疑服务异常时先查状态页，多数"是不是挂了"当场就有答案。

## 上游故障会自动切换吗？

会。上游是平台自建的官方账号池，同一模型挂多个账号兜底，机制是平台内建的、默认作用于全部请求，无需额外开通：

* **单家异常自动切换**：请求失败自动重试到下一家，不需要改配置
* **优先级与权重**：稳定、低延迟的上游排在前
* **自动隔离与恢复**：持续失败的上游自动停用，恢复后自动纳入
* **跨分组重试**：`auto` 分组可在分组之间重试

细节见[上游冗余与可用性](https://docs.aicentos.com/enterprise/pool-verification)。

## 怎么区分是我这边的问题还是平台的问题？

1. 打开[状态监控](https://docs.aicentos.com/status)，看目标模型的可用率与延迟是否正常
2. 正常 → 先检查自己的密钥、余额、IP 白名单与网络
3. 异常 → 属于平台侧或上游侧问题，等待自动恢复，或[联系支持](https://docs.aicentos.com/enterprise/support)跟进

常见的报错含义见[错误处理](https://docs.aicentos.com/billing/errors)。

## 数据从哪来、多久更新一次？

监控服务独立于文档站运行，数据来源为自建的健康巡检服务（`status.aicentos.com`）。若文档站上的面板长时间无数据，可直接访问原站确认。

## 企业采购时能把这些写进合同吗？

可以。实时可用性数据公开，可作为合同的附件事实依据；是否约定赔付型 SLA 属于商务条款，在[合同与对公结算](https://docs.aicentos.com/enterprise/billing-contract)中确认。

---

# 和官方 API 有什么区别

来源: https://docs.aicentos.com/faq/vs-official

Language: zh-CN

> 接口格式、计费方式、密钥治理与故障转移 —— aicentos 与直连官方 API 的逐项对照

## 和官方 API 有什么区别？

**结论：接口格式与官方保持一致，已有的 SDK 和客户端不用改代码；差别在接入方式、计费、治理能力与上游形态。**

## 接口格式一样吗？

一样。已接入的协议：

| 协议                              | Base URL                      |
| ------------------------------- | ----------------------------- |
| OpenAI 兼容（SDK / Codex 等）        | `https://aicentos.com/v1`     |
| Anthropic Messages（Claude 原生格式） | `https://aicentos.com`        |
| Gemini 原生格式                     | `https://aicentos.com/v1beta` |

`model` 字段填模型 ID，其余参数与官方一致。已有的 OpenAI / Claude 项目，把 Base URL 换掉即可运行，不必改业务代码。

## 计费方式有什么不同？

* 官方是外币结算、通常需要海外信用卡；aicentos 是**人民币预充值 + 按量计费**，支付宝充值
* 计费公式：`(输入 Tokens × 输入单价 + 输出 Tokens × 输出单价) × 分组倍率`
* 图像、视频等多媒体模型可能按次计费，以模型定价页说明为准
* 注册即送 ¥1 体验额度，余额永不过期，余额不退现
* 签约企业客户可开发票

单价与倍率以[模型定价页](https://aicentos.com/pricing)实时显示为准；官方参考价对照见[官方定价参考](https://docs.aicentos.com/billing/official-pricing)。

## 治理能力上多了什么？

直连官方时，每个厂商的密钥与账单要分开管；通过 aicentos 集中到一处：

* 一组 Key 调用多家厂商的模型，切换只改 `model` 参数
* 每个密钥独立设置额度上限、模型白名单、IP 白名单、有效期
* 统一查看用量、日志与扣费明细
* 可以签合同、对公转账、开发票

## 上游是不是原来的厂商？

是。上游是平台自建的官方账号池：全部直连厂商官方 API，同一模型挂多个账号做兜底。某条上游失败时请求自动重试到下一个账号，持续失败的上游自动停用、恢复后自动纳入。机制见[上游冗余与可用性](https://docs.aicentos.com/enterprise/pool-verification)。

需要说明的是：**中转层无法向调用方提供"原厂鉴定"**——响应里没有可用于验证来源的水印，这不是直连与否的问题，而是任何转发型网关在技术上都无法向第三方证明的事。我们能承诺并公开的是上游形态（官方 API 直连 + 多账号冗余）与真实探测数据。

## 什么时候应该直接用官方？

* 你的合规或采购要求必须原厂直连、不接受任何中间层
* 你需要官方独有的功能、配额合同或企业协议
* 你要的是原厂 SLA 与赔付主体

这些场景建议直接使用官方渠道。

## 什么时候中转更合适？

* 海外账号与信用卡不便，但要用多个厂商的模型
* 需要在一个控制台里统一计费、额度管控与使用审计
* 需要按项目、按成员签发密钥并分别核算成本

服务边界与能力清单见[服务模式与能力边界](https://docs.aicentos.com/enterprise/overview)。

---

# aicentos 介绍

来源: https://docs.aicentos.com/introduction

Language: zh-CN

> 一个 API 接入所有大模型 —— OpenAI、Anthropic、Google、xAI 等主流厂商聚合

**aicentos** 是面向开发者的 AI API 中转聚合平台。一个 API Key，统一调用 OpenAI、Anthropic、Google、xAI、DeepSeek 等主流厂商的大模型。

aicentos 官网

## 我们解决什么问题

接 LLM 麻烦在哪？账号要分别注册、Key 要分别管、计费要分别看、SDK 要分别接。aicentos 把这些拍平。

| 痛点     | 传统做法              | aicentos           |
| ------ | ----------------- | ------------------ |
| 多模型切换  | 改 SDK、改 URL、改 Key | **改一个 `model` 参数** |
| 海外账号   | 信用卡 / 海外手机号       | **注册即送 ¥1，支付宝充值**  |
| 接口规范   | 每家一套              | **统一 OpenAI 兼容协议** |
| 计费透明   | 各家后台分开看           | **统一账单与用量日志**      |
| Key 管控 | 无细粒度权限            | **额度、模型白名单、IP 限制** |

控制台把密钥、余额、用量、日志都收在一处：

控制台概览

## 核心特性

### 多厂商模型接入

OpenAI、Anthropic、Google、xAI、阿里通义、DeepSeek、智谱、Moonshot、MiniMax **统一接入**，覆盖聊天、推理、代码、图像、视频与嵌入。新模型上线后陆续适配，原有 SDK 调用方式不变。

完整清单见[支持的模型](https://docs.aicentos.com/billing/models-list)。

### 可用性可查

每个模型都有独立的健康巡检。你可以在[模型状态监控](https://docs.aicentos.com/status)看到各模型的 1 小时 / 24 小时 / 7 天可用率、响应延迟与端点 PING，接入前先确认目标模型当前状态。

### 安全可靠

API 密钥支持**额度上限、可用模型白名单、IP 限制、过期时间**等多维管控，可为不同项目、不同成员分别签发，便于成本归集与权限回收。

### 开发者友好

完全兼容 **OpenAI 协议**。已有的 OpenAI / Codex 项目把 `base_url` 换成 `https://aicentos.com/v1` 即可运行；Claude / Anthropic 等其他协议统一使用根地址 `https://aicentos.com`，**0 行代码迁移**。

## 适合谁

* 想用 **Claude / GPT / Gemini** 但海外账号和信用卡麻烦的开发者
* 在 **多个 LLM 间频繁切换** 做对比的研究者 / Agent 开发者
* 需要 **统一计费 / 额度管控 / 使用审计** 的团队
* 国内访问海外 API **延迟高 / 不稳定** 的工程师

## 平台数据

| 指标    |          数值 |
| ----- | ----------: |
| 注册赠送  | **¥1 体验额度** |
| 余额有效期 |    **永不过期** |

## 下一步

* [快速开始](https://docs.aicentos.com/quickstart) — 三步接入，跑通第一个请求
* [支持的模型](https://docs.aicentos.com/billing/models-list) — 查看已接入的模型清单
* [模型状态监控](https://docs.aicentos.com/status) — 查看各模型实时可用率
* [计费](https://docs.aicentos.com/billing/pricing) — 了解充值与按量计费

---

# Nano Banana 2 图像生成

来源: https://docs.aicentos.com/nano-banana2

Language: zh-CN

> 通过 aicentos 调用 gemini-3.1-flash-image-preview（Nano Banana 2）生成图像 —— Gemini 原生格式与 OpenAI 兼容格式示例

本文给出通过 aicentos 调用 **Nano Banana 2**（`gemini-3.1-flash-image-preview`）生成图像的请求示例，支持 **Gemini 原生格式**和 **OpenAI 兼容格式**两种入参。

通过 `imageConfig` 可指定画面比例（`aspectRatio`）与分辨率（`imageSize`，如 `2K`、`4K`）。

## Gemini 原生格式

生成 1:1 尺寸 4K 图，请求示例：

```bash
export AICENTOS_API_KEY="sk-替换我"

curl --location --request POST 'https://aicentos.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent' \
--header "x-goog-api-key: $AICENTOS_API_KEY" \
--header 'content-type: application/json' \
--header 'Accept: */*' \
--data-raw '{
  "contents": [
    {
      "parts": [
        {
          "text": "复古宣传海报风格，突出中文文字，背景为红黄放射状图案。画面中心位置有一位美丽的年轻女性，以精致复古风格绘制，面带微笑，气质优雅，具有亲和力。主题是最新 AI 绘画服务的广告促销，4K 分辨率\n"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "image"
    ],
    "imageConfig": {
      "aspectRatio": "1:1",
      "imageSize": "4K"
    }
  }
}'
```

## OpenAI 兼容格式

生成 9:16 尺寸 2K 图，请求示例：

```bash
export AICENTOS_API_KEY="sk-替换我"

curl --location --request POST 'https://aicentos.com/v1/chat/completions' \
--header "Authorization: Bearer $AICENTOS_API_KEY" \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "model": "gemini-3.1-flash-image-preview",
    "extra_body": {
        "imageConfig": {
            "aspectRatio": "9:16",
            "imageSize": "2K"
        }
    },
    "messages": [
        {
            "role": "system",
            "content": "{\"imageConfig\": {\"aspectRatio\": \"9:16\", \"imageSize\": \"2K\"}}"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "画一个马年大吉"
                }
            ]
        }
    ],
    "max_tokens": 4096,
    "temperature": 0.8
}'
```

## 参数说明

* `aspectRatio`：画面比例，如 `1:1`、`9:16`、`16:9`。
* `imageSize`：分辨率，如 `2K`、`4K`。
* Gemini 原生格式用 `x-goog-api-key` 鉴权，OpenAI 兼容格式用 `Authorization: Bearer` 鉴权。
* OpenAI 兼容格式下，`imageConfig` 既可放在 `extra_body`，也可放进 `system` 消息的 JSON 中。
* 把示例中的 `sk-替换我` 换成你在 aicentos 控制台创建的 API Key。

---

# 快速开始

来源: https://docs.aicentos.com/quickstart

Language: zh-CN

> 三步接入：注册账户 → 创建 API 密钥 → 在客户端填上 Base URL 和 Key

三步接入：**注册账户 → 创建 API 密钥 → 在客户端填上 Base URL 和 Key**。

## 步骤 1：注册账户

打开 [aicentos.com](https://aicentos.com/)，点右上角「**开始使用**」进入注册页：

注册页面

填写**用户名**和**密码**，勾选用户协议后点「创建账户」。注册即送 **¥1** 体验额度，无需先充值即可调用。

## 步骤 2：创建 API 密钥

登录后进入控制台，左侧导航点「**API 密钥**」，再点右上角「**创建 API 密钥**」：

API 密钥页面

在弹窗里填写配置后点「保存更改」：

创建 API 密钥

| 字段   | 说明                                 |
| ---- | ---------------------------------- |
| 名称   | 自定义，便于区分多个项目。建议按用途分别创建，方便成本归集与权限回收 |
| 分组   | 选择走哪个上游分组，可留空使用默认                  |
| 过期时间 | 支持「永不过期」或指定 1 小时 / 1 天 / 1 个月      |
| 数量   | 一次性创建多个密钥，名称会自动追加随机后缀              |
| 无限配额 | 关闭后可设置该密钥的额度上限                     |

创建完成后密钥会出现在列表里，形如 `sk-xxxxxxxxxxxx`，默认打码显示：

密钥已创建

密钥列表支持按名称和密钥搜索，可以查看分组、额度、可用模型、IP 限制等，也能随时编辑或删除：

密钥列表

> **密钥只在创建时完整显示一次**，请立即复制并妥善保存。不要硬编码到前端代码或提交到公开仓库。

## 步骤 3：在客户端填上 Base URL 和 Key

### 先选对 Base URL

这是最容易出错的一步 —— **不同协议用的地址不同**：

| 使用场景                               | Base URL                  |
| ---------------------------------- | ------------------------- |
| Codex / OpenAI 兼容格式                | `https://aicentos.com/v1` |
| Claude Code / Anthropic 格式，以及其它客户端 | `https://aicentos.com`    |

> **Anthropic 协议只填根地址**，不要手动追加 `/v1/messages`，客户端会自动拼接。

控制台「API 密钥」页右上角的「**API 地址**」下拉里也能直接查和复制：

API 地址

### 验证连通性

用 curl 跑一条最小请求，确认 Key 与网络可用：

```bash
export AICENTOS_API_KEY="sk-你的密钥"

curl https://aicentos.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'
```

也可以先请求模型列表。只要返回 JSON，就说明密钥和 Base URL 都可用：

```bash
export AICENTOS_API_KEY="sk-你的密钥"

curl https://aicentos.com/v1/models \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

### Python（OpenAI SDK）

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AICENTOS_API_KEY"],
    base_url="https://aicentos.com/v1",
)

resp = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(resp.choices[0].message.content)
```

### Node.js（OpenAI SDK）

示例用的是 ESM 语法，文件名需为 `.mjs`，或在 `package.json` 里加 `"type": "module"`：

```js
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.AICENTOS_API_KEY,
  baseURL: 'https://aicentos.com/v1',
});

const resp = await client.chat.completions.create({
  model: 'gemini-3.8-flash',
  messages: [{ role: 'user', content: '用一句话介绍你自己' }],
});

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

### 常见客户端

* [接入 Claude Code](https://docs.aicentos.com/claude-code) — CC Switch 一键导入或手动配置
* [接入 Codex](https://docs.aicentos.com/codex) — 图形化配置或手写 config.toml
* [接入 Cursor](https://docs.aicentos.com/cursor) — 自定义 OpenAI 兼容设置
* [接入 Cherry Studio](https://docs.aicentos.com/cherry-studio) — 添加 OpenAI 兼容服务商

## 充值

注册赠送的额度用完后，进控制台左侧「**钱包**」充值：

钱包

充值档位与优惠（**充 ¥100 起有折扣，实付低于充值金额**）：

| 充值金额                 | 优惠     | 实付     |
| -------------------- | ------ | ------ |
| ¥1 / ¥10 / ¥20 / ¥50 | 无      | 原价     |
| ¥100                 | 1% OFF | ¥99    |
| ¥500                 | 2% OFF | ¥490   |
| ¥1,000               | 3% OFF | ¥970   |
| ¥10,000              | 5% OFF | ¥9,500 |

也可以自定义金额，或使用兑换码兑换额度。

付款方式

* **付款方式**：支付宝、微信、对公转账
* **额度永不过期**，按 token 实际消耗扣费
* 有推荐奖励：邀请链接注册后双方都可获得奖励，可随时转入余额

## 查看用量

控制台左侧「**数据看板**」查看消耗明细：

控制台概览

可以看到当前余额、总用量、API 请求数，以及分模型的调用趋势：

数据看板

## 不用写代码先试试

控制台顶部的「**聊天**」里有一个内置游乐场，可以直接选模型、发消息，边聊边调提示词：

游乐场

## 下一步

* 在 [游乐场](https://aicentos.com/playground) 里直接在浏览器测试模型，无需写代码
* 浏览 [支持的模型](https://docs.aicentos.com/billing/models-list) — 看支持哪些 LLM
* 看 [错误处理](https://docs.aicentos.com/billing/errors) — 排查 401、余额不足等问题
* 了解 [计费规则](https://docs.aicentos.com/billing/pricing) — 按量计费与余额预警

---

# 模型状态监控

来源: https://docs.aicentos.com/status

Language: zh-CN

> 实时查看各模型接口的可用性、延迟与端点 PING



---

# Veo 视频生成

来源: https://docs.aicentos.com/veo-video

Language: zh-CN

> 通过 aicentos 调用 Google Veo 视频生成模型 —— 文生视频、图生视频、首尾帧、参考图

本文面向开发者，说明如何通过 aicentos 调用 Google Veo 视频生成模型。接口为 OpenAI 视频 API 兼容格式（OpenAI Videos API），下游接入时渠道类型使用 `openai` 即可。

## 模型能力说明

按视频生成时长（秒）计费。具体单价以 aicentos 控制台为准，最终扣费以系统实际扣费记录为准。

### 官方能力与 aicentos 开放口径

| 模型                              | 支持秒数  | 支持分辨率         | 画面比例      | 音频    | 说明                                       |
| ------------------------------- | ----- | ------------- | --------- | ----- | ---------------------------------------- |
| `veo-3.1-generate-preview`      | 4、6、8 | 720p、1080p、4k | 16:9、9:16 | 原生带音频 | 1080p 和 4k 仅支持 8 秒；用参考图、首尾帧等图片能力时建议 8 秒。 |
| `veo-3.1-fast-generate-preview` | 4、6、8 | 720p、1080p、4k | 16:9、9:16 | 原生带音频 | 1080p 和 4k 仅支持 8 秒；用参考图、首尾帧等图片能力时建议 8 秒。 |

参考文档：

* [Google Gemini API Veo 视频生成](https://ai.google.dev/gemini-api/video)
* [Veo 参考图说明](https://ai.google.dev/gemini-api/video#reference_images)
* [Veo 首尾帧说明](https://ai.google.dev/gemini-api/video#first_and_last_frame)
* [Veo 画面比例说明](https://ai.google.dev/gemini-api/video#aspect_ratio)

### 画面比例

| 模型                              | 16:9 横屏 | 9:16 竖屏 | 默认比例 | 建议                   |
| ------------------------------- | ------- | ------- | ---- | -------------------- |
| `veo-3.1-generate-preview`      | 支持      | 支持      | 16:9 | 4K 必须用 8 秒；视频扩展暂不开放。 |
| `veo-3.1-fast-generate-preview` | 支持      | 支持      | 16:9 | 4K 必须用 8 秒；视频扩展暂不开放。 |

请求中可以通过 `metadata.aspectRatio` 或表单字段 `aspectRatio` 指定比例：

```bash
{
  "metadata": {
    "aspectRatio": "9:16"
  }
}
```

如果没有显式传 `aspectRatio`，系统会优先根据 `size` 推导比例，例如 `1280x720` 推导为 16:9、`720x1280` 推导为 9:16。如果 `size` 也未传，上游默认使用 16:9。

### 音频说明

| 模型                              | 官方音频能力 | 支持 generateAudio | 建议                                    |
| ------------------------------- | ------ | ---------------- | ------------------------------------- |
| `veo-3.1-generate-preview`      | 原生带音频  | 不支持              | 不要传 `generateAudio`，需要声音效果请写进 prompt。 |
| `veo-3.1-fast-generate-preview` | 原生带音频  | 不支持              | 不要传 `generateAudio`，需要声音效果请写进 prompt。 |

Veo 3.1 系列是原生带音频的视频模型，但当前 Gemini API 的 Veo 参数表没有开放 `generateAudio` 作为可控参数。传入该字段可能会被上游返回 `INVALID_ARGUMENT`。

如果希望控制音频内容，可以在 prompt 中描述对白、环境音、音效或音乐风格，例如：

```bash
黄昏海边的灯塔，海浪轻拍礁石，远处有低沉的风声和海鸟声，电影级光影，稳定运镜
```

## 图片输入能力

| 能力         | Google 官方 Veo 能力                   | aicentos 接口支持 | 说明                                                                                                |
| ---------- | ---------------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
| 单张初始图生成视频  | 支持                                 | 支持            | 使用 `input_reference` 上传 1 张图片，作为视频起始画面。                                                           |
| 首尾帧生成 / 插帧 | Veo 3.1 系列支持 image + lastFrame     | 支持            | 首帧用 `input_reference`，尾帧用 `last_frame` 或 `lastFrame`。建议 Veo 3.1 系列、8 秒。                           |
| 多张参考图      | Veo 3.1 系列支持最多 3 张 referenceImages | 支持            | 用 `reference_image`、`reference_images` 或 `referenceImages` 上传，`referenceType` 仅支持 `asset`。建议 8 秒。 |
| 视频扩展       | Veo 3.1 / Fast 支持扩展已有 Veo 视频       | 暂不支持          | 当前 aicentos 接口没有开放官方 video 输入。                                                                    |

* 图片 MIME 类型支持 `image/jpeg`、`image/png`、`image/webp`。推荐传文件或 Base64，不建议直接传远程图片 URL。
* 参考图模式注意：当前上游在参考图场景不支持 `negativePrompt`，传入后可能返回 `Negative prompt is not supported in your use case`。参考图请求请不要传 `negativePrompt`。
* 实现说明：Gemini API 的 Veo `predictLongRunning` 图片入参使用 `bytesBase64Encoded` + `mimeType`，不是普通 `generateContent` 的 `inlineData`。aicentos 会把 multipart 上传的图片转换成上游需要的格式。

## 计费规则

* 按视频生成时长计费，单位为秒。请使用上表中模型支持的秒数，不建议传任意秒数。
* 如果请求未指定视频时长，系统默认按 8 秒计费。
* 秒数识别优先级：`metadata.durationSeconds` > `duration` > `seconds` > 默认 8 秒。
* 分辨率识别优先级：`metadata.resolution` > `size` > 默认 720p。
* 720p / 1080p / 4K 按相同规则计费，不因分辨率单独加价。
* `aspectRatio` 只控制横屏或竖屏，不单独加价。
* 4K 只支持 8 秒。
* 具体单价以 aicentos 控制台为准。

## 接口说明

当前推荐使用这 3 个接口：

| 用途   | 方法   | 路径                             |
| ---- | ---- | ------------------------------ |
| 创建任务 | POST | `/v1/videos`                   |
| 查询状态 | GET  | `/v1/videos/{task_id}`         |
| 下载结果 | GET  | `/v1/videos/{task_id}/content` |

如果希望查询时直接拿到结果地址，也可以使用：

| 用途        | 方法  | 路径                                |
| --------- | --- | --------------------------------- |
| 查询状态和结果地址 | GET | `/v1/video/generations/{task_id}` |

### 鉴权

```bash
export BASE_URL="https://aicentos.com"
export AICENTOS_API_KEY="sk-xxxxxx"
```

所有请求都带：

```bash
-H "Authorization: Bearer $AICENTOS_API_KEY"
```

### 创建文生视频任务

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "黄昏海边的灯塔，镜头缓慢推进，海浪轻拍礁石，电影级光影，稳定运镜",
    "seconds": "8",
    "size": "1280x720",
    "metadata": {
      "negativePrompt": "blurry, watermark, distorted, low quality",
      "resolution": "720p",
      "aspectRatio": "16:9",
      "seed": 20260401
    }
  }'
```

典型返回：

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1775025000
}
```

### 创建首帧图生视频任务

当前图生视频推荐使用 `multipart/form-data`，首帧图片字段名必须是 `input_reference`。

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=让画面中的女孩转头看向镜头，微风吹动头发，背景城市灯光轻微虚化，镜头平稳推进" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, deformed hands" \
  -F "seed=20260401"
```

### 创建首尾帧任务

首尾帧需要同时提供首帧和尾帧。首帧用 `input_reference`，尾帧用 `last_frame` 或 `lastFrame`。

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=从第一张女孩画面自然过渡到最后一张男孩画面，镜头平稳推进，城市灯光虚化，发丝和衣服有轻微风动，过渡自然真实" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "last_frame=@./last-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, distorted face, deformed hands" \
  -F "seed=20260402"
```

### 创建参考图任务

参考图任务只支持 Veo 3.1 系列，最多 3 张，且 `referenceType` 仅支持 `asset`。字段名可用 `reference_image`、`reference_images` 或 `referenceImages`。参考图任务不要传 `negativePrompt`。

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=参考两张图片中的人物外观和城市夜景氛围，生成一段电影感双人街头镜头，镜头平稳推进，背景灯光轻微虚化，人物自然看向镜头" \
  -F "reference_image=@./ref-1.png;type=image/png" \
  -F "reference_image=@./ref-2.png;type=image/png" \
  -F "reference_type=asset" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "seed=20260403"
```

JSON / Base64 也支持：

```bash
{
  "model": "veo-3.1-generate-preview",
  "prompt": "使用参考图中的产品外观生成广告镜头",
  "duration": 8,
  "metadata": {
    "resolution": "720p",
    "aspectRatio": "16:9",
    "referenceImages": [
      {
        "image": {
          "bytesBase64Encoded": "BASE64_IMAGE",
          "mimeType": "image/png"
        },
        "referenceType": "asset"
      }
    ]
  }
}
```

### 查询任务状态

先把创建接口返回的 `id` 或 `task_id` 保存下来：

```bash
export TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

然后查询状态：

```bash
curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

处理中时，典型返回：

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1775025000
}
```

完成后，典型返回：

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1775025000,
  "completed_at": 1775025068
}
```

### 查询任务状态和结果地址

如果想在查询时直接拿到可下载地址，可以调用：

```bash
curl -X GET "$BASE_URL/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

典型返回：

```bash
{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "url": "https://aicentos.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
  }
}
```

### 下载视频结果

任务完成后，直接下载：

```bash
curl -L "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -o veo-result.mp4
```

## 状态说明

`GET /v1/videos/{task_id}` 返回的状态主要有：

| 状态            | 说明  |
| ------------- | --- |
| `queued`      | 已排队 |
| `in_progress` | 生成中 |
| `completed`   | 已完成 |
| `failed`      | 失败  |

`GET /v1/video/generations/{task_id}` 返回的状态主要有：

| 状态           | 说明  |
| ------------ | --- |
| `queued`     | 已排队 |
| `processing` | 生成中 |
| `succeeded`  | 已成功 |
| `failed`     | 失败  |

## 接入注意事项

* `prompt` 必填。
* 图生视频时，图片字段名必须是 `input_reference`。
* 首尾帧任务必须同时提供首帧和尾帧，首帧用 `input_reference`，尾帧用 `last_frame` 或 `lastFrame`。
* 参考图任务只支持 Veo 3.1 系列，最多 3 张，且必须 8 秒。
* 参考图任务不要传 `negativePrompt`。
* 当前 Gemini 图生视频不建议直接传远程图片 URL，推荐传文件或 Base64。
* 建议轮询 `GET /v1/videos/{task_id}`，等 `status=completed` 后再下载。
* Veo 3.1 系列可以传 4、6、8 秒；当使用 1080p 或 4k 时必须传 8 秒。- 横屏使用 `aspectRatio=16:9`，竖屏使用 `aspectRatio=9:16`；如果不传，默认按 16:9 处理。
* 不要传 `generateAudio` 参数。Veo 3.1 系列是原生带音频的视频模型，但当前 Gemini API 不支持通过 `generateAudio` 参数开关音频；传入该字段可能会被上游返回 `INVALID_ARGUMENT`。
* 如需控制音频内容，请在 prompt 中描述对白、环境音、音效或音乐风格。
* 官方 Veo 3.1 支持视频扩展，但当前 aicentos 接口暂未开放官方 video 输入。