# aicentos 文件

> aicentos 是面向開發者與企業的 AI API 中轉聚合平台。一組 API Key 統一調用 OpenAI、Anthropic、Google、xAI 等主流大模型，上游為自建官方帳號池、直連廠商官方 API，多帳號兜底自動容錯切換，可用率即時公開，支援對公合約與私有化部署。

本文彙整已提供繁體中文翻譯的文件，每篇附原頁面網址。

[文件目錄](https://docs.aicentos.com/zh-TW/llms.txt)

# 原生 Claude 格式

來源: https://docs.aicentos.com/zh-TW/api/chat/claude

Language: zh-TW

聊天（Chat）

`POST /messages`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## 請求主體

`application/json`

TypeScript 型別定義

在 TypeScript 中使用 request body 型別

## 回應主體

###

`application/json`

###

`application/json`

###

`application/json`

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

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

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

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

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

---

# Gemini 文字聊天

來源: https://docs.aicentos.com/zh-TW/api/chat/gemini/text

Language: zh-TW

聊天（Chat）原生 Gemini 格式

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

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## Path 參數

model\*string

## 請求主體

`application/json`

TypeScript 型別定義

在 TypeScript 中使用 request body 型別

## 回應主體

###

`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 "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{    "contents": [      {        "role": "user",        "parts": [          {            "text": "用一句話介紹你自己"          }        ]      }    ]  }'
```

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

---

# ChatCompletions 格式

來源: https://docs.aicentos.com/zh-TW/api/chat/openai/chat-completions

Language: zh-TW

聊天（Chat）原生 OpenAI 格式

`POST /chat/completions`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## 請求主體

`application/json`

TypeScript 型別定義

在 TypeScript 中使用 request body 型別

## 回應主體

###

`application/json`

###

`application/json`

###

`application/json`

###

`application/json`

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

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

```bash
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 0,
  "model": "string",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "system",
        "content": "string",
        "name": "string"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}
```

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

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

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

---

# Responses 格式

來源: https://docs.aicentos.com/zh-TW/api/chat/openai/responses

Language: zh-TW

聊天（Chat）原生 OpenAI 格式

`POST /responses`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## 請求主體

`application/json`

TypeScript 型別定義

在 TypeScript 中使用 request body 型別

## 回應主體

###

`application/json`

###

`application/json`

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

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

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

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

---

# Gemini 原生格式

來源: https://docs.aicentos.com/zh-TW/api/images/nano-banana/gemini

Language: zh-TW

圖像（Images）Nano Banana

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

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## 請求主體

`application/json`

TypeScript 型別定義

在 TypeScript 中使用 request body 型別

## 回應主體

###

`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 "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{    "contents": [      {        "role": "user",        "parts": [          {            "text": "一隻穿太空衣的水豚漂浮在太空裡"          }        ]      }    ],    "generationConfig": {      "responseModalities": [        "IMAGE"      ]    }  }'
```

```bash
{
  "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/zh-TW/api/images/openai/edits

Language: zh-TW

圖像（Images）原生 OpenAI 格式

`POST /images/edits`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## 請求主體

`multipart/form-data`

TypeScript 型別定義

在 TypeScript 中使用 request body 型別

## 回應主體

###

`application/json`

```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="[    \"string\"  ]" \
  -F prompt="string"
```

```bash
{
  "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/zh-TW/api/images/openai/generations

Language: zh-TW

圖像（Images）原生 OpenAI 格式

`POST /images/generations`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## 請求主體

`application/json`

TypeScript 型別定義

在 TypeScript 中使用 request body 型別

## 回應主體

###

`application/json`

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

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

```bash
{
  "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,
    "input_tokens_details": {
      "text_tokens": 0,
      "image_tokens": 0
    },
    "output_tokens_details": {
      "text_tokens": 0,
      "image_tokens": 0
    }
  }
}
```

---

# 原生 Gemini 格式

來源: https://docs.aicentos.com/zh-TW/api/models/gemini

Language: zh-TW

模型（Models）

`GET /v1beta/models`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## 回應主體

###

`application/json`

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

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

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

---

# 原生 OpenAI 格式

來源: https://docs.aicentos.com/zh-TW/api/models/openai

Language: zh-TW

模型（Models）

`GET /models`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## 回應主體

###

`application/json`

###

`application/json`

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

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

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

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

---

# Dreamina · 建立影片

來源: https://docs.aicentos.com/zh-TW/api/videos/dreamina/create

Language: zh-TW

> 提交即夢（Dreamina）影片生成任務，回傳任務 ID 與初始狀態

影片（Videos）即夢格式

`POST /videos`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## 請求主體

`application/json`

TypeScript 型別定義

在 TypeScript 中使用 request body 型別

## 回應主體

###

`application/json`

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

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

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

---

# Dreamina · 取得影片任務狀態

來源: https://docs.aicentos.com/zh-TW/api/videos/dreamina/get-task

Language: zh-TW

> 依任務 ID 查詢即夢（Dreamina）影片生成進度與結果

影片（Videos）即夢格式

`GET /videos/{task_id}`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## Path 參數

task\_id\*string

## 回應主體

###

`application/json`

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

curl -X GET "https://aicentos.com/v1/videos/string" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

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

---

# Sora · 建立影片

來源: https://docs.aicentos.com/zh-TW/api/videos/sora/create

Language: zh-TW

> 提交 Sora 影片生成任務，回傳任務 ID 與初始狀態，後續用任務 ID 查詢進度

影片（Videos）Veo（OpenAI 相容）

`POST /videos`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## 請求主體

`application/json`

TypeScript 型別定義

在 TypeScript 中使用 request body 型別

## 回應主體

###

`application/json`

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

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

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

---

# Sora · 取得影片內容

來源: https://docs.aicentos.com/zh-TW/api/videos/sora/get-content

Language: zh-TW

> 任務完成後依任務 ID 取得 Sora 生成的影片檔案位址

影片（Videos）Veo（OpenAI 相容）

`GET /videos/{task_id}/content`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## Path 參數

task\_id\*string

## 回應主體

###

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

curl -X GET "https://aicentos.com/v1/videos/string/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

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

---

# Sora · 取得影片任務狀態

來源: https://docs.aicentos.com/zh-TW/api/videos/sora/get-task

Language: zh-TW

> 依任務 ID 查詢 Sora 影片生成進度，取得狀態與失敗原因

影片（Videos）Veo（OpenAI 相容）

`GET /videos/{task_id}`

## 驗證

將 API Key 存入環境變數 `AICENTOS_API_KEY`；shell 範例會將其值展開至 `Authorization: Bearer` 標頭。

在控制台「權杖管理」取得的 API 金鑰

位置：`header`

## Path 參數

task\_id\*string

## 回應主體

###

`application/json`

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

curl -X GET "https://aicentos.com/v1/videos/string" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

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

---

# 錯誤

來源: https://docs.aicentos.com/zh-TW/billing/errors

Language: zh-TW

> 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 金鑰缺失 / 錯誤 / 已被撤銷      |
| `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/zh-TW/billing/pricing#%E9%A4%98%E9%A1%8D%E9%A0%90%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/zh-TW/billing/models-list

Language: zh-TW

> 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/zh-TW/billing/official-pricing

Language: zh-TW

> 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/zh-TW/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/zh-TW/billing/pricing)

---

# 計費

來源: https://docs.aicentos.com/zh-TW/billing/pricing

Language: zh-TW

> 儲值與按量計費 —— 支付寶儲值、按 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/zh-TW/quickstart) — 三步接入，跑通第一個請求
* [支援的模型](https://docs.aicentos.com/zh-TW/billing/models-list) — 查看模型清單
* [錯誤處理](https://docs.aicentos.com/zh-TW/billing/errors) — 排查餘額不足等報錯

---

# Amp

來源: https://docs.aicentos.com/zh-TW/clients/amp

Language: zh-TW

> 在 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/zh-TW/api/chat/claude)）與 OpenAI 相容介面（見 [Chat Completions](https://docs.aicentos.com/zh-TW/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/zh-TW/clients/antigravity-cli

Language: zh-TW

> 在 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/zh-TW/clients/antigravity

Language: zh-TW

> 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/zh-TW/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/zh-TW/clients/cursor)、[Windsurf](https://docs.aicentos.com/zh-TW/clients/windsurf) 等支援自訂 Base URL 的用戶端。
* Antigravity CLI 與桌面 IDE 是兩套設定，CLI 的端點覆蓋不會影響 IDE。
* 使用任何第三方分支或代理前，請自行評估其安全性與後續維護情況。

## 相關連結

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

---

# Augment Code

來源: https://docs.aicentos.com/zh-TW/clients/augment-code

Language: zh-TW

> 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/zh-TW/clients/craft-agent)、[Gajae Code](https://docs.aicentos.com/zh-TW/clients/gajae-code)、[Oh My Pi](https://docs.aicentos.com/zh-TW/clients/oh-my-pi) 都是終端機編碼代理，設定裡能直接寫 `baseUrl`。

### 方案二：留在 VS Code，換外掛

[Cline](https://docs.aicentos.com/zh-TW/clients/cline)、[Roo Code](https://docs.aicentos.com/zh-TW/clients/roo-code)、[Kilo](https://docs.aicentos.com/zh-TW/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/zh-TW/clients/cc-switch

Language: zh-TW

> 從 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/zh-TW/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/zh-TW/billing/models-list) — 查看完整模型清單與 ID
* [計費](https://docs.aicentos.com/zh-TW/billing/pricing) — 瞭解儲值與按量計費

---

# Chatbot UI

來源: https://docs.aicentos.com/zh-TW/clients/chatbot-ui

Language: zh-TW

> 在 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/zh-TW/clients/chatbox

Language: zh-TW

> 在 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/zh-TW/clients/cherry-studio

Language: zh-TW

> 在 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/zh-TW/quickstart)。

## 設定步驟

* 開啟 Cherry Studio 設定，進入**模型服務 / 供應商管理**。
* 新增一個 **OpenAI 相容**供應商。
* 供應商名稱填 `aicentos`。
* 填入 API Key 與 API 位址 `https://aicentos.com/v1`。
* 儲存設定，若有「檢測 / 測試連線」按鈕可點擊驗證。

### 新增模型

如果沒有自動識別到模型，可手動新增模型名稱。

>

模型名稱要完整複製，大小寫、連字號、日期後綴都不能改動，以 [模型廣場](https://aicentos.com/pricing) / [支援的模型](https://docs.aicentos.com/zh-TW/billing/models-list) 中的為準。

## 測試與排查

傳送一條測試訊息確認連通，例如：

```bash
你好，請用一句話介紹你自己。
```

常見問題：

* **驗證錯誤**：檢查 API Key 是否有多餘空格。
* **逾時**：檢查網路或服務狀態。
* **模型不可用**：使用控制台中的完整模型名稱。
* **對話失敗**：確認已選中 aicentos 這個供應商。

---

# Claude Code

來源: https://docs.aicentos.com/zh-TW/clients/claude-code

Language: zh-TW

> 從零安裝 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` 按 Enter 開啟終端機，執行：

```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/zh-TW/quickstart)。

## 第三步：設定接入

下面提供兩種方式：**用 CC Switch 一鍵管理**（推薦），或**自己手動設定**。

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

如果你需要在多套 Provider、多個 CLI 工具之間頻繁切換，推薦用 CC Switch 集中管理設定，不必反覆改環境變數。

詳見 [接入 CC Switch →](https://docs.aicentos.com/zh-TW/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/zh-TW/billing/models-list)。

## 常用指令

| 指令                        | 用途                                      |
| ------------------------- | --------------------------------------- |
| `/add-dir`                | 新增額外的工作目錄                               |
| `/resume`                 | 回到歷史對話                                  |
| `/clear`                  | 清除對話歷史                                  |
| `/compact [instructions]` | 壓縮對話，可選擇性地提供重點指令                        |
| `/config`                 | 查看 / 修改設定                               |
| `/cost`                   | 顯示 token 使用統計                           |
| `/doctor`                 | 檢查 Claude Code 安裝的健康狀況                  |
| `/help`                   | 取得使用說明                                  |
| `/init`                   | 使用 CLAUDE.md 指南初始化專案                    |
| `/login`                  | 切換 Anthropic 帳號                         |
| `/logout`                 | 從 Anthropic 帳號登出                        |
| `/mcp`                    | 管理 MCP 伺服器連線與 OAuth 身分驗證                |
| `/memory`                 | 編輯 CLAUDE.md 記憶檔案                       |
| `/model`                  | 選擇或更改 AI 模型                             |
| `/permissions`            | 查看或更新權限                                 |
| `/pr_comments`            | 查看 Pull Request 評論                      |
| `/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

### 準備

只需要兩樣東西：

* **一支 Android 手機**（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，等出現命令提示字元（一行 `~ $`），把下面這行**整行**複製進去按 Enter：

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

>

這是中國大陸專用鏡像，國外使用者用 `. <(curl -L git.io/linux.sh)`。

跑完之後會跳出一個**圖形選單**，長這樣：

tmoe 主選單

用音量鍵上下選、按 Enter 確定（或直接點螢幕）。

### 第二步：裝 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) 回饋。

## 注意事項

* 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/zh-TW/clients/cline

Language: zh-TW

> 在 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/zh-TW/clients/codebuddy

Language: zh-TW

> 在 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/zh-TW/clients/codebuff

Language: zh-TW

> 在 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/zh-TW/clients/codex-cli

Language: zh-TW

> 在 Codex CLI 中使用 aicentos —— 手動設定 config.toml 的 model_providers

Codex CLI 是 OpenAI 官方的命令列編碼代理，透過 `~/.codex/config.toml` 定義模型供應商。把自訂 provider 指向 aicentos，即可在終端機裡使用 aicentos 接入的模型。

如果你更想用圖形化方式管理多套設定，也可以走 [CC Switch](https://docs.aicentos.com/zh-TW/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/zh-TW/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/zh-TW/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/zh-TW/clients/codex)

---

# Codex++

來源: https://docs.aicentos.com/zh-TW/clients/codex-plus

Language: zh-TW

> 用 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/zh-TW/billing/models-list) 為準，要完整複製模型名稱。
* **上游協定沒選對**：必須是 **chat completions**。
* **Base URL 不對**：填 `https://aicentos.com`，首尾別帶空格或多餘路徑。
* **提示 401 / 無權限**：檢查 Key 是否複製完整，以及 Key 的分組是否包含你要用的模型；餘額請到 [錢包](https://aicentos.com/wallet) 查看。

---

# Codex

來源: https://docs.aicentos.com/zh-TW/clients/codex

Language: zh-TW

> 在 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/zh-TW/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/zh-TW/billing/models-list)。

### 啟動 Codex

```bash
codex
```

發一條簡單請求，確認 Provider 正常運作。

## 排查問題

請求失敗時，對照 Codex 終端機輸出和控制台用量日誌排查。常見原因：

* 模型名稱寫錯（以模型廣場為準）。
* Base URL 格式不對（只填到 `/v1`，不要多加路徑）。
* 環境變數沒被目前終端機讀取（重開終端機或 `source` 設定檔）。

---

# Command Code

來源: https://docs.aicentos.com/zh-TW/clients/command-code

Language: zh-TW

> 在 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/zh-TW/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/zh-TW/clients/copilot

Language: zh-TW

> 在 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/zh-TW/clients/craft-agent

Language: zh-TW

> 在 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/zh-TW/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/zh-TW/clients/crush

Language: zh-TW

> 在 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/zh-TW/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/zh-TW/clients/cursor

Language: zh-TW

> 在 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/zh-TW/billing/models-list)）。
* 儲存並點擊 **Verify**，或直接新建一個對話測試。

## 測試

儲存後，先用一句簡單提示詞輕量測試一下，確認通了再正式使用 Composer / Chat。

## 注意事項

* 自訂 API Key 通常只對標準對話模型生效。
* **Tab 補全**和部分 **Agent** 能力可能仍走 Cursor 自帶服務。
* Verify 失敗時，檢查：Base URL 是否正確（只填到 `/v1`）、Key 是否有多餘空格、模型是否可用、帳戶餘額是否充足、是否已選中自訂 OpenAI Provider。

---

# Devin CLI

來源: https://docs.aicentos.com/zh-TW/clients/devin-cli

Language: zh-TW

> 在 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/zh-TW/clients/devin-desktop

Language: zh-TW

> 在 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/zh-TW/clients/droid

Language: zh-TW

> 在 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/zh-TW/clients/dsh

Language: zh-TW

> 在 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 掃碼確認，QR code 約 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/zh-TW/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/zh-TW/billing/models-list)

---

# Freebuff

來源: https://docs.aicentos.com/zh-TW/clients/freebuff

Language: zh-TW

> 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/zh-TW/clients/claude-code)、[Codex CLI](https://docs.aicentos.com/zh-TW/clients/codex-cli)）。

## 需要填寫的設定

| 欄位       | 值                         |
| -------- | ------------------------- |
| API Key  | 控制台建立的 Key                |
| Base URL | `https://aicentos.com/v1` |
| 模型       | 控制台「模型廣場」中的模型名            |

上表是 aicentos 側的通用參數，供下面的替代方案使用。

## 替代方案

* 要終端機編碼代理：[Craft Agent](https://docs.aicentos.com/zh-TW/clients/craft-agent)、[Gajae Code](https://docs.aicentos.com/zh-TW/clients/gajae-code)、[Oh My Pi](https://docs.aicentos.com/zh-TW/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/zh-TW/clients/fx

Language: zh-TW

> 在 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/zh-TW/clients/gajae-code

Language: zh-TW

> 在 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/zh-TW/clients/gemini-cli

Language: zh-TW

> 在 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/zh-TW/clients/goose

Language: zh-TW

> 在 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/zh-TW/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/zh-TW/clients/grok-build

Language: zh-TW

> 在 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/zh-TW/clients/grok-cli

Language: zh-TW

> 在 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/zh-TW/clients/hermes-agent

Language: zh-TW

> 在 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/zh-TW/clients/hindsight

Language: zh-TW

> 為 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/zh-TW/clients/jcode

Language: zh-TW

> 在 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/zh-TW/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/zh-TW/clients/junie

Language: zh-TW

> 在 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/zh-TW/clients/kilo-cli

Language: zh-TW

> 在 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/zh-TW/clients/kilo-code

Language: zh-TW

> 在 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/zh-TW/clients/kilo

Language: zh-TW

> 在 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/zh-TW/clients/kimchi

Language: zh-TW

> 在 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/zh-TW/clients/kimi

Language: zh-TW

> 在 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 ]` 一行按 Enter，按精靈指示新增。

也可以只走環境變數（對 `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/zh-TW/billing/models-list)）。

---

# Kiro

來源: https://docs.aicentos.com/zh-TW/clients/kiro

Language: zh-TW

> 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/zh-TW/clients/lm-studio

Language: zh-TW

> 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/zh-TW/clients/cherry-studio)、[Chatbox](https://docs.aicentos.com/zh-TW/clients/chatbox)、[Cline](https://docs.aicentos.com/zh-TW/clients/cline) 的 Base URL 填成 `http://localhost:1234/v1`。這條鏈路和 aicentos 無關，但它是 LM Studio 的正確用法。

### 方案二：要 aicentos 的模型，就換前端

[Cherry Studio](https://docs.aicentos.com/zh-TW/clients/cherry-studio)、[Chatbox](https://docs.aicentos.com/zh-TW/clients/chatbox)、[LobeChat](https://docs.aicentos.com/zh-TW/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/zh-TW/clients/lobechat

Language: zh-TW

> 在 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/zh-TW/clients/mimo-code

Language: zh-TW

> 在 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/zh-TW/clients/minimax-code

Language: zh-TW

> 在 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/zh-TW/clients/mux

Language: zh-TW

> 在 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/zh-TW/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/zh-TW/clients/nativetavern

Language: zh-TW

> 在 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/zh-TW/clients/nextchat

Language: zh-TW

> 在 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/zh-TW/clients/oh-my-pi

Language: zh-TW

> 在 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/zh-TW/clients/openclaw

Language: zh-TW

> 在 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/zh-TW/clients/opencode

Language: zh-TW

> 在 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/zh-TW/clients/opencodereview

Language: zh-TW

> 在 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/zh-TW/clients/orca

Language: zh-TW

> 在 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/zh-TW/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/zh-TW/clients/paseo

Language: zh-TW

> 在 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/zh-TW/clients/pi

Language: zh-TW

> 在 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/zh-TW/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/zh-TW/clients/prime-agent

Language: zh-TW

> 在 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/zh-TW/clients/oh-my-pi) 或 [Gajae Code](https://docs.aicentos.com/zh-TW/clients/gajae-code)。

## 相關連結

* [prime-agent 儲存庫](https://github.com/PrimeIntellect-ai/prime-agent)

---

# Qwen

來源: https://docs.aicentos.com/zh-TW/clients/qwen

Language: zh-TW

> 在 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/zh-TW/clients/reasonix

Language: zh-TW

> 在 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/zh-TW/clients/roo-code

Language: zh-TW

> 在 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/zh-TW/clients/senpi

Language: zh-TW

> 在 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/zh-TW/clients/sillytavern

Language: zh-TW

> 在 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/zh-TW/clients/tavernai

Language: zh-TW

> 在 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/zh-TW/clients/trae

Language: zh-TW

> 在 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/zh-TW/clients/unsloth

Language: zh-TW

> 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/zh-TW/clients/cherry-studio)、[Chatbox](https://docs.aicentos.com/zh-TW/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/zh-TW/clients/warp

Language: zh-TW

> 在 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/zh-TW/clients/windsurf

Language: zh-TW

> 在 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/zh-TW/clients/workbuddy

Language: zh-TW

> 在 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/zh-TW/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/zh-TW/clients/zcode

Language: zh-TW

> 在 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/zh-TW/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/zh-TW/clients/zed-agent

Language: zh-TW

> 在 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)

---

# aicentos 介紹

來源: https://docs.aicentos.com/zh-TW/introduction

Language: zh-TW

> 一個 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/zh-TW/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/zh-TW/quickstart) — 三步接入，跑通第一個請求
* [支援的模型](https://docs.aicentos.com/zh-TW/billing/models-list) — 查看已接入的模型清單
* [模型狀態監控](https://docs.aicentos.com/status) — 查看各模型即時可用率
* [計費](https://docs.aicentos.com/zh-TW/billing/pricing) — 瞭解儲值與按量計費

---

# Nano Banana 2 圖像生成

來源: https://docs.aicentos.com/zh-TW/nano-banana2

Language: zh-TW

> 透過 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 金鑰。

---

# 快速開始

來源: https://docs.aicentos.com/zh-TW/quickstart

Language: zh-TW

> 三步接入：註冊帳號 → 建立 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/zh-TW/claude-code) — CC Switch 一鍵匯入或手動設定
* [接入 Codex](https://docs.aicentos.com/zh-TW/codex) — 圖形化設定或手寫 config.toml
* [接入 Cursor](https://docs.aicentos.com/zh-TW/cursor) — 自訂 OpenAI 相容設定
* [接入 Cherry Studio](https://docs.aicentos.com/zh-TW/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/zh-TW/billing/models-list) — 看支援哪些 LLM
* 看 [錯誤處理](https://docs.aicentos.com/zh-TW/billing/errors) — 排查 401、餘額不足等問題
* 瞭解 [計費規則](https://docs.aicentos.com/zh-TW/billing/pricing) — 按量計費與餘額預警

---

# 模型狀態監控

來源: https://docs.aicentos.com/zh-TW/status

Language: zh-TW

> 即時查看各模型介面的可用性、延遲與端點 PING

即時監控面板目前僅在[中文狀態頁](https://docs.aicentos.com/status)提供。

---

# Veo 影片生成

來源: https://docs.aicentos.com/zh-TW/veo-video

Language: zh-TW

> 透過 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 輸入。