> ## 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/models) |
| `model not found`、模型名立即报错 | 模型名拼写错误 | 从 [模型表](/zh/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/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/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/setup/codex)，或重新运行工具。Cursor、Cline、Chatbox 在 Settings 中修改 API Key 字段。

### 多次运行安装命令有问题吗

没有。命令设计为可重复运行：旧配置存为 `.bak.<时间>`，CLI 升级到最新，shell rc 中的旧 Key 行被替换。

### 命令会把我的 Key 发到别处吗

不会。你在自己电脑上把 Key 粘进命令，命令只写环境变量和本地配置文件。整条命令都展示在页面上，运行前可逐行阅读。

### 全部移除

见 [Codex](/zh/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.