故障排查

它說憑據被拒絕了

The model provider would not accept the request without credentials.
(status 401 Unauthorized)

要麼你選的那個 provider 沒有設金鑰,要麼設的那個對它無效。按順序查三件事:

1. 到底選中的是哪個 provider —— config.toml 裡的 model,或者輸入框裡的選單。 指向一個你從沒配過 provider 的模型,是最常見的原因。
2. env_key 指名的那個環境變量在 agent 執行的那個 shell 裡確實設了。桌面端是從它 保管金鑰的地方讀,不是從你的 shell 讀。
3. 這個金鑰屬於那一家。 一家的金鑰不是另一家的金鑰。

401 是特意不重試的:憑據不會因為再發一遍就變對。

模型清單是空的

模型面板和輸入框的選單都來自 provider 的 /v1/models。空清單意味著那個請求失敗了, 原因在 ~/.opencli/log 裡。

一個需要金鑰的 provider 在沒有金鑰時什麼都不返回,所以這條和上面的 401 通常是同一個問題。

它會回答,但從不碰我的文件

你的模型不調用工具。 這是最常見的失望,而且它不是設定錯誤 —— 有些模型就是不調。

測一下。五分鐘,一個固定任務。如果不過,那個模型就是 不適合幹這個,沒有任何設定能改變。

它用 grep 而不是好好讀文件

同一個根源的溫和版本:一個沒往 agent 方向訓練過的模型,即使面前擺著文件工具,也會伸手 去夠 shell。 介面上沒有任何東西能補上這個。

一次後臺執行說在等我

它的工作目錄不是產品已知的那幾種 —— 不在工作區、不在部門目錄裡、也不是你按名字授權 過的地方。

要麼在派發面板裡允許這個目錄,要麼把任務移動到一個部門。它被扣住而不是被執行, 是因為一次執行可以寫它目錄裡的任何東西。

一個定時任務從來沒跑過

兩種可能:

• OpenCLI 關著。 定時的活兒只在它開著時執行。
• 它被扣住了,如上。被扣住的任務出現在等你授權下面。

對話老是自己壓縮

如果它壓縮完立刻又要壓縮,那長度不是來自對話 —— 是來自每次請求都帶的固定部分,主要是 你那些連接器的工具描述。四個連接器可以在你開口之前就佔掉一萬 token。

它會說一次,而不是每一輪都再來一遍。把這次對話用不上的連接器關掉,就是解法。

桌面端打不開

macOS:執行 xattr -dr com.apple.quarantine /Applications/OpenCLI.app,或者右鍵 → 打開。

Windows:SmartScreen → More info → Run anyway。

如果還是不行,可能是下載不完整 —— 拿文件大小跟 release 頁面核對一下。

agent 做了什麼我沒看見

產物只列出用 agent 的文件編輯工具做的改動。 它執行的 shell 命令寫的文件 —— heredoc、指令碼、git checkout —— 是真實的改動,但不會出現在那裡。

在工作目錄裡跑 git status 才是可靠的答案。

我選了別的語言,介面還是英文

字典是在語言被選中時才去取的,所以有一瞬間會顯示英文。如果它一直是英文,說明那個 chunk 沒加載成功 —— 在桌面端的開發者工具裡看控制臺。

一句沒有翻譯的話永遠顯示英文,這是設計 —— 那是「翻譯還沒跟上」,不是故障。

日志在哪

~/.opencli/log

設定 → 關於 → 日志會打開那個目錄。報告問題時,失敗前後五十行幾乎總是夠了 —— 黏之前先檢查裡面有沒有金鑰。