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

# 疑難排解

> 按症狀排查安裝、授權、額度、裝置和帳單問題。

# 疑難排解

先看基礎狀態,不要反覆重裝,也不要把憑據貼到任何地方:

```bash theme={null}
recodex status
recodex doctor
```

`doctor` 會逐項回報客戶端安裝、託管設定、登入、憑據、網關、訂閱與 Codex 可用性 —— 大多數問題看它一眼就知道卡在哪一環。

## 裝不上 / 找不到

### 找不到 `recodex`

一鍵安裝腳本會把它加進 PATH,但**已經打開的終端讀不到** —— 新開一個終端再試:

```bash theme={null}
recodex version
```

### `install check` 或 `doctor` 說沒裝 Codex,但我明明裝了

先確認官方 Codex 客戶端確實在。如果你是從\*\*應用商店(MSIX)\*\*裝的,它不在 `Programs` 目錄下,而在 `C:\Program Files\WindowsApps\` —— ReCodex 會去登錄檔查這類安裝,`recodex install check` 應當能認出來。

若仍報未安裝,把 `recodex doctor --json` 的輸出發給客服。

### macOS 提示「無法驗證開發者」或「已損毀」

安裝包是 ad-hoc 簽名的(我們還沒有 Apple 開發者帳號做公證),瀏覽器下載會給它打上隔離屬性。

在 Finder 裡**右鍵點 ReCodex → 打開**,或執行:

```bash theme={null}
xattr -dr com.apple.quarantine /Applications/ReCodex.app
```

## 登入相關

### `recodex login` 一直等在那裡

* **瀏覽器沒打開**:用終端裡顯示的驗證地址手動打開。
* **提示裝置數已達上限**:每個帳號最多 3 台。命令列會列出目前裝置讓你選一台撤銷;桌面端會提示你去[裝置管理](https://recodex.dev/dashboard/devices)撤銷。撤銷之後**不用重新登入**,輪詢會自己走通。
* **已經批准了但還在等**:檢查網路,然後重新發起一次。

### 桌面端登入成功了,左下角還是官方帳號

側邊欄那個名字會**立刻**變過來。如果沒變,點一次面板裡的「重新整理額度」。

但**官方 Codex 真正用上你的帳號需要重新啟動一次** —— 那個行程在你登入之前就啟動了,讀不到新寫入的設定。面板上點「立即重新啟動生效」即可。

### `status` 說已登入,但 `account` / `usage` 報錯

說明這台裝置在伺服器端被登出了(比如你在別處撤銷了它)。重新 `recodex login` 即可。

<Note>
  新版本的 `status` 會直接顯示「憑據已失效」,而不是照本機檔案說「已登入」。
</Note>

## 切回官方 ChatGPT 之後

### 歷史對話打不開,提示 `Model provider recodex not found`

**升級到最新版即可**。舊版本在切回官方模式時會把 ReCodex 的 provider 定義整塊刪掉,而 Codex 把每個工作階段當時用的 provider 記在工作階段檔案裡 —— 定義沒了,舊對話就解析不到。

新版本只摘掉預設選擇、保留定義:新對話走官方帳號,歷史對話照常打開。

## Codex 報錯

### 401 / 憑據過期

通常重新 `recodex login` 即可。Windows 上還要注意:登入寫入的 `RECODEX_KEY` 對**已打開的**終端不可見,新開一個終端再試。

### 403

可能來自訂閱狀態、綁定關係或上游帳號,**不要一律理解成封號**。先跑 `recodex doctor`,它會區分是訂閱問題還是設定問題。

### 429 或額度耗盡

表示觸發了頻率或用量視窗限制。看一眼額度:

```bash theme={null}
recodex usage --refresh
```

等視窗恢復即可,不要連續重試。

### 感覺變慢

換個網關試試:

```bash theme={null}
recodex gateways        # 看各線路延遲
recodex gateways auto   # 自動選最快的
```

## 額度顯示

### 顯示「資料可能不是最新的」

額度是伺服器快照,不是即時值。超過 5 分鐘沒更新就會這麼標註,同時客戶端會在背景自動補一次重新整理;你也可以手動點「重新整理額度」立刻更新。

### 看不到 5 小時視窗

近 5 小時沒有用量時,上游不會回傳這個視窗,所以介面上不顯示。這是正常的,不是掉資料。

## 設定衝突

```bash theme={null}
recodex doctor --fix
```

`--fix` 只處理能安全自動修復的項。如果報告 `config.toml` 有重複鍵,先備份,再刪掉你手工加的、與 ReCodex 託管區塊重複的欄位。

<Note>
  ReCodex 只動 `# >>> recodex managed block` 標記之間的內容,你自己的設定不會被覆蓋。
</Note>

## 付款成功但訂閱不可用

確認訂單不是處理中,重新整理帳單與訂閱頁並重新登入。仍未生效時提交訂單號、付款時間和頁面狀態 —— **不要**提交支付密碼或完整付款憑證。

## 收集脫敏診斷

```bash theme={null}
recodex doctor --json
recodex logs --limit 50
```

兩者都是脫敏的(日誌只含命令名、結果、版本、系統)。發送前仍建議掃一眼有沒有專案名或檔案路徑。

## 還是不行

提交支援請求時帶上:發生時間(到分鐘)、作業系統、`recodex version` 的輸出、`doctor --json` 的結果,以及最短重現步驟。

<Warning>
  不要發送原始金鑰、裝置授權碼、密碼、資料庫連線字串或未脫敏日誌。ReCodex 客服不會向你索取這些。
</Warning>


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