> ## 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.

# Lỗi thường gặp

> Triệu chứng → nguyên nhân → cách sửa, cộng câu hỏi hay gặp

## Bảng tra nhanh

| App báo | Gần như chắc là | Sửa |
| - | - | - |
| `401 Unauthorized`, `Invalid token` | Key sai, thiếu ký tự, hết hạn ngày, hoặc đã bị vô hiệu | Dán key vào [trang check](https://gpt.teamsoclo.site/check) |
| `404 Not Found` | Base URL thiếu `/v1` (hoặc thành `/v1/v1`) | Sửa Base URL |
| `No available channel for model ... under group ...` | Key gói này gọi model của gói kia | Dùng đúng model của gói, xem [Model và gói](/mo-hinh) |
| `model not found`, lỗi tên model ngay lập tức | Gõ sai tên model | Copy tên từ [bảng model](/mo-hinh) |
| `429 Too Many Requests` | Vượt số request mỗi phút của key | Chờ sang phút sau, giảm tần suất |
| `insufficient quota`, hết hạn mức | Key đã dùng hết token | Mua mã mới |
| Sửa cấu hình mà không có gì đổi | Chưa tắt hẳn app hoặc chưa mở terminal mới | Thoát hẳn rồi mở lại |

## Key và hạn mức

### Key sai hoặc thiếu ký tự

Lỗi phổ biến nhất không phải key hỏng mà là **copy hụt vài ký tự** ở đầu hoặc cuối khi bôi đen bằng chuột. Luôn dùng nút **Copy** trên trang đổi mã. Dán key vào [trang check](https://gpt.teamsoclo.site/check): trang báo hợp lệ thì key không phải vấn đề, lỗi nằm ở cấu hình app.

### Key hết hạn ngày

Mỗi gói có thời hạn tính từ lúc đổi mã (ghi trên sản phẩm). Hết hạn thì mọi request báo 401 dù còn hạn mức. Trang check hiển thị ngày hết hạn. Phần token chưa dùng không chuyển sang mã mới.

### Key hết quota

Đang chạy tốt thì đột nhiên mọi request lỗi kèm chữ *insufficient quota*. Xem còn bao nhiêu tại trang check. Hạn mức tụt nhanh bất thường thường do một agent đang tự đọc cả repo hoặc một hội thoại quá dài được gửi lại mỗi lượt.

### Mất key

Đổi lại đúng mã CDK đó tại [redeem.teamsoclo.site](https://redeem.teamsoclo.site), trang hiện lại key cũ. Không cấp key mới cho mã đã đổi.

### Một key dùng được mấy máy

Key không giới hạn số máy, nhưng **giới hạn số request mỗi phút** tính chung cho mọi máy dùng key đó. Chia sẻ key cho nhiều người thì họ giành nhau hạn mức và dễ đụng 429.

## Kết nối

### Quên /v1

Base URL đúng là `https://gpt.teamsoclo.site/v1`. Thiếu `/v1` thì request đi vào trang web thay vì API, app báo 404 hoặc "không kết nối được".

<Warning>
  Ngược lại cũng sai: vài app (Chatbox, một số bản Cline) tự thêm `/v1` phía sau. Đã điền đủ mà vẫn 404 thì thử bỏ `/v1`, địa chỉ thật có thể đang thành `/v1/v1`.
</Warning>

### Gọi model của gói khác

Thông báo `No available channel for model gpt-astra under group default` nghĩa là key gói GPT đang gọi model gói Astra (hoặc ngược lại). Mỗi key chỉ gọi được model của gói mình. Kiểm tra bằng:

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

### 429 Too Many Requests

Mỗi key có số request thành công tối đa mỗi phút theo gói. Vượt thì nhận 429 kèm dòng "đã đạt giới hạn request". Chờ sang phút sau là chạy lại. Chạy script hàng loạt thì thêm độ trễ giữa các lần gọi, hoặc mua thêm mã để chia tải.

### Câu trả lời bị cắt giữa chừng

Với câu hỏi cần suy nghĩ lâu, request không streaming có thể bị ngắt trước khi model trả chữ đầu tiên. Bật `stream: true`. Hầu hết app chat đã bật sẵn; gọi bằng code thì thêm tham số này.

### `Unsupported parameter: reasoning_effort`

Chỉ Chat Completions nhận `reasoning_effort` ở cấp gốc. Với Responses API dùng `"reasoning": {"effort": "high"}`. Codex tự lo phần này, bạn không cần chỉnh.

## Codex

### `codex: command not found` sau khi cài

npm đã cài xong nhưng terminal hiện tại chưa nạp lại PATH. **Mở terminal mới**. Vẫn không được thì xem thư mục bin của npm có trong PATH chưa:

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

Thư mục đó cộng `/bin` phải nằm trong `$PATH`.

### Codex vẫn đòi đăng nhập OpenAI

Biến môi trường `TEAMSOCLO_API_KEY` chưa tới được tiến trình Codex:

* Terminal: mở tab mới, kiểm tra `echo $TEAMSOCLO_API_KEY`.
* VS Code trên macOS: thoát hẳn bằng `Cmd + Q` rồi mở lại. Lệnh cài đã đặt biến cho app GUI bằng `launchctl`.
* VS Code trên Linux: mở VS Code từ terminal (`code .`), hoặc đăng xuất rồi đăng nhập lại.
* Windows: mở PowerShell hoặc VS Code **mới** sau khi chạy `setx`.

Kiểm tra `config.toml` có `requires_openai_auth = false` và `env_key = "TEAMSOCLO_API_KEY"`.

### Sửa config.toml mà Codex không đổi

Cấu hình chỉ được đọc lúc khởi động tiến trình. **Reload Window không đủ**, phải thoát hẳn VS Code (macOS `Cmd + Q`, Windows đóng hết cửa sổ và tiến trình chạy ngầm). Đây là lỗi bị hỏi nhiều nhất khi cài Codex.

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

Node cài bằng quyền hệ thống, thường gặp trên Linux. Đổi prefix npm:

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

Thêm dòng `export` vào `~/.bashrc` hoặc `~/.zshrc`. Về lâu dài nên cài Node qua nvm, xem [Bắt đầu](/bat-dau).

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

PowerShell chặn file `.ps1`, mà lệnh `codex` và `npm` khi gõ trong PowerShell đi qua shim `.ps1` của npm. Chạy một lần:

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

Rồi mở PowerShell mới. Hoặc gõ `codex.cmd`, `npm.cmd` thay cho `codex`, `npm`.

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

Codex đang chạy (CLI, extension hoặc app) nên npm không ghi đè được `codex.exe`. Đóng hết mọi thứ đang chạy Codex rồi chạy lại lệnh cài. Cấu hình đã được ghi xong trước bước này, chỉ phần nâng cấp CLI bị bỏ qua.

### Windows: file config lỗi encoding

Sửa file bằng PowerShell 5.1 với `Set-Content -Encoding UTF8` sẽ chèn BOM vào đầu file, Codex không đọc được. Dùng lại [lệnh cài đặt](/cai-dat/codex) (ghi UTF‑8 không BOM), hoặc lưu file bằng VS Code với encoding **UTF-8** (không phải UTF-8 with BOM).

### Khôi phục cấu hình cũ

Mỗi lần chạy lệnh cài, cấu hình cũ được sao lưu cạnh file mới:

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

Dùng tool thì chọn **Reset cấu hình**, tool tự khôi phục.

## Câu hỏi hay gặp

### Đổi key thì làm thế nào

Chạy lại [lệnh cài đặt Codex](/cai-dat/codex) với key mới, hoặc chạy lại tool. Với Cursor, Cline, Chatbox: sửa ô API Key trong Settings.

### Chạy lệnh cài nhiều lần có sao không

Không. Lệnh được thiết kế chạy lại an toàn: cấu hình cũ sao lưu thành `.bak.<thời gian>`, CLI nâng lên bản mới nhất, dòng key cũ trong shell rc được thay bằng dòng mới.

### Lệnh cài có gửi key đi đâu không

Không. Bạn dán key vào lệnh ngay trên máy mình; lệnh chỉ ghi vào biến môi trường và file cấu hình cục bộ. Toàn bộ nội dung lệnh hiển thị rõ trên trang, bạn đọc được từng dòng trước khi chạy.

### Gỡ hết cấu hình

Xem mục **Gỡ cấu hình** ở trang [Codex](/cai-dat/codex). Với app khác chỉ cần xoá key trong Settings của app.

## Vẫn không chạy

<Steps>
  <Step title="Key còn sống không">
    Dán key vào [trang check](https://gpt.teamsoclo.site/check). Báo lỗi ở đây thì vấn đề là key (sai, hết hạn ngày, hết hạn mức), không phải app.
  </Step>

  <Step title="Gọi thẳng bằng 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"}]}'
    ```

    Lệnh này chạy mà app không chạy thì lỗi ở cấu hình app.
  </Step>

  <Step title="Soi lại ba thứ trong app">
    Base URL có `/v1`, key dán đủ, tên model đúng gói. Ba thứ này gây ra gần hết số lỗi.
  </Step>

  <Step title="Liên hệ hỗ trợ">
    Gửi ảnh chụp lỗi và 4 ký tự cuối của key qua [t.me/teamsoclo](https://t.me/teamsoclo). Đừng gửi cả key.
  </Step>
</Steps>


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