> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teamsoclo.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 常見問題

> 現象 → 原因 → 解決，以及常見疑問

## 速查表

| 應用提示 | 幾乎可以確定是 | 解決 |
| - | - | - |
| `401 Unauthorized`、`Invalid token` | Key 錯誤、少字元、已過期或已停用 | 把 Key 粘到 [檢查頁](https://gpt.teamsoclo.site/check) |
| `404 Not Found` | Base URL 缺 `/v1`（或重複成 `/v1/v1`） | 修正 Base URL |
| `No available channel for model ... under group ...` | 用一個套餐的 Key 呼叫另一個套餐的模型 | 使用本套餐的模型，見 [模型](/zh-tw/models) |
| `model not found`、模型名立即報錯 | 模型名拼寫錯誤 | 從 [模型表](/zh-tw/models) 複製 |
| `429 Too Many Requests` | 超過 Key 的每分鐘請求上限 | 等下一分鐘，降低頻率 |
| `insufficient quota` | Key 的 Token 已用完 | 購買新 CDK |
| 改了配置但沒變化 | 應用未完全退出，或終端未重開 | 完全退出後重開 |

## Key 與額度

### Key 錯誤或不完整

最常見的不是 Key 壞了，而是滑鼠拖選時**首尾丟了幾個字元**。請始終用兌換頁的 **Copy** 按鈕。把 Key 粘到 [檢查頁](https://gpt.teamsoclo.site/check)：顯示有效則 Key 沒問題，問題在應用配置。

### Key 已過期

每個套餐都有從兌換起算的有效期（寫在商品上）。過期後即使有額度，所有請求也返回 401。檢查頁顯示到期時間。未用完的 Token 不會轉到新 CDK。

### 額度用完

一直正常，突然所有請求都報 *insufficient quota*。到檢查頁看剩餘。額度異常快速下降通常是某個 Agent 在讀整個倉庫，或超長對話每輪被重發。

### Key 丟失

到 [redeem.teamsoclo.site](https://redeem.teamsoclo.site) 再次兌換同一個 CDK，頁面會顯示原 Key。已兌換的 CDK 不會簽發新 Key。

### 一個 Key 能用幾臺電腦

沒有裝置數限制，但**每分鐘請求上限**由使用該 Key 的所有裝置共享。多人共用一個 Key 會互相搶額度，更容易碰到 429。

## 連線

### 漏了 /v1

正確的 Base URL 是 `https://gpt.teamsoclo.site/v1`。缺少 `/v1` 時請求打到網站而非 API，應用報 404 或“無法連線”。

<Warning>
  反過來也不行：部分應用（Chatbox、某些 Cline 版本）會自動追加 `/v1`。填了仍報 404 時試試去掉 `/v1`，實際地址可能變成了 `/v1/v1`。
</Warning>

### 呼叫了其他套餐的模型

`No available channel for model gpt-astra under group default` 表示 GPT Key 正在呼叫 Astra 模型（或反之）。每個 Key 只能呼叫本套餐的模型。驗證：

```bash theme={null}
curl https://gpt.teamsoclo.site/v1/models -H "Authorization: Bearer sk-xxx"
```

### 429 Too Many Requests

每個 Key 有按套餐設定的每分鐘成功請求上限，超過即返回 429 並提示“已達到請求數限制”。等到下一分鐘即可。批次指令碼請加延時，或再買一個 CDK 分擔負載。

### 回答中途被截斷

需要長時間思考的問題，非流式請求可能在第一個 Token 之前就被斷開。開啟 `stream: true`。大多數聊天應用已預設開啟；用程式碼呼叫時請加上。

### `Unsupported parameter: reasoning_effort`

只有 Chat Completions 接受頂層 `reasoning_effort`。Responses API 請使用 `"reasoning": {"effort": "high"}`。Codex 會自行處理。

## Codex

### 安裝後 `codex: command not found`

npm 已裝好但當前終端尚未重新載入 PATH。**新開一個終端**。仍不行則檢查 npm 的 bin 目錄是否在 PATH 中：

```bash theme={null}
npm config get prefix
```

該目錄加 `/bin` 必須在 `$PATH` 裡。

### Codex 仍要求登入 OpenAI

環境變數 `TEAMSOCLO_API_KEY` 沒有傳到 Codex 程序：

* 終端：新開標籤，檢查 `echo $TEAMSOCLO_API_KEY`。
* macOS 上的 VS Code：用 `Cmd + Q` 完全退出後重開。安裝命令已透過 `launchctl` 為圖形程式設定變數。
* Linux 上的 VS Code：從終端啟動（`code .`），或登出後重新登入。
* Windows：`setx` 之後**新開** PowerShell 或 VS Code。

確認 `config.toml` 含 `requires_openai_auth = false` 和 `env_key = "TEAMSOCLO_API_KEY"`。

### 改了 config.toml 但 Codex 沒變化

配置只在程序啟動時讀取。**Reload Window 不夠**，必須完全退出 VS Code（macOS `Cmd + Q`，Windows 關閉所有視窗及後臺程序）。這是 Codex 被問得最多的問題。

### npm install 報 `EACCES: permission denied`

Node 以系統許可權安裝，Linux 上常見。修改 npm 字首：

```bash theme={null}
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
```

把 `export` 行加入 `~/.bashrc` 或 `~/.zshrc`。長期建議用 nvm 安裝 Node，見 [開始使用](/zh-tw/getting-started)。

### Windows：`running scripts is disabled on this system`

PowerShell 禁止執行 `.ps1`，而在 PowerShell 中輸入的 `codex`、`npm` 會經過 npm 的 `.ps1` 墊片。執行一次：

```powershell theme={null}
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

然後新開 PowerShell。或改用 `codex.cmd`、`npm.cmd`。

### Windows：`EBUSY: resource busy or locked`

Codex 正在執行（CLI、擴充套件或 App），npm 無法覆蓋 `codex.exe`。關閉所有執行中的 Codex 後重新執行安裝命令。配置在此步驟之前已寫好，只是跳過了 CLI 升級。

### Windows：配置檔案編碼錯誤

用 PowerShell 5.1 的 `Set-Content -Encoding UTF8` 編輯會加上 BOM，Codex 無法讀取。重新執行 [安裝命令](/zh-tw/setup/codex)（寫入無 BOM 的 UTF‑8），或在 VS Code 中以 **UTF-8**（非 UTF-8 with BOM）儲存。

### 恢復舊配置

每次執行安裝命令，舊配置都會備份在新檔案旁：

```bash theme={null}
ls ~/.codex/*.bak.*
cp ~/.codex/config.toml.bak.20260925143000 ~/.codex/config.toml
```

使用工具時選擇 **Reset** 即自動恢復。

## 常見疑問

### 如何更換 Key

用新 Key 重新執行 [Codex 安裝命令](/zh-tw/setup/codex)，或重新執行工具。Cursor、Cline、Chatbox 在 Settings 中修改 API Key 欄位。

### 多次執行安裝命令有問題嗎

沒有。命令設計為可重複執行：舊配置存為 `.bak.<時間>`，CLI 升級到最新，shell rc 中的舊 Key 行被替換。

### 命令會把我的 Key 發到別處嗎

不會。你在自己電腦上把 Key 粘進命令，命令只寫環境變數和本地配置檔案。整條命令都展示在頁面上，執行前可逐行閱讀。

### 全部移除

見 [Codex](/zh-tw/setup/codex) 頁的**解除安裝**。其他應用只需在 Settings 中刪除 Key。

## 仍然不行

<Steps>
  <Step title="Key 是否有效">
    粘到 [檢查頁](https://gpt.teamsoclo.site/check)。這裡報錯說明問題在 Key（錯誤、過期、額度用完），而不是應用。
  </Step>

  <Step title="用 cURL 直接呼叫">
    ```bash theme={null}
    curl https://gpt.teamsoclo.site/v1/chat/completions \
      -H "Authorization: Bearer sk-xxx" \
      -H "Content-Type: application/json" \
      -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"hi"}]}'
    ```

    這條能跑而應用不能，問題就在應用配置。
  </Step>

  <Step title="複查應用裡的三項">
    Base URL 以 `/v1` 結尾、Key 完整、模型與套餐匹配。幾乎所有問題都出自這三項。
  </Step>

  <Step title="聯絡支援">
    把報錯截圖和 Key 的最後 4 位發到 [t.me/teamsoclo](https://t.me/teamsoclo)。不要傳送完整 Key。
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.