FAQ

配置與啟動

no valid LLM endpoint configured

no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL,
~/.opencodereview/config.json, or ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/ANTHROPIC_MODEL
must be set

OCR 走完整條端點解析鏈但沒找到完整的 (URL, token, model) 三元組。用 ocr config set llm.url … 等補齊，或匯出環境變數，然後 ocr llm test。

ocr llm test 回 401/403

token 缺 scope、過期或廠商不匹配。Anthropic 與 OpenAI 用不同 auth header 與 URL 格式——確認 llm.use_anthropic 與 URL 匹配。

not a git repository

ocr review 對目前目錄跑 git diff。不在 Git 工作樹內會提前退出。傳 --repo /path/to/repo。

"No tool calls parsed"（本地模型 / Ollama）

過濾與規則

我的檔案沒被評審

跑 ocr review --preview（無 LLM 成本）——輸出每個候選檔與被保留/丟棄的原因：

src/foo.go              modified
src/foo_test.go         modified  (excluded: user_exclude)
node_modules/lib.js     added     (excluded: default_path)
imgs/logo.png           binary    (excluded: unsupported_ext)

unsupported_ext → 加進 include；default_path → 加進 include（覆蓋測試檔排除）；user_exclude → 從 exclude 移除。

我的自訂規則沒觸發

跑 ocr rules check <file-path> 看匹配的層與 glob 模式。若層不對，多半是宣告順序——首條匹配生效，把更具體的規則前移。

評審

某檔顯示零評論——真的被評審了嗎？

開 Session Viewer 看該檔 main_task 泳道：有工具呼叫 + task_done 結束 → 乾淨評審；以錯誤卡片結束 → 偽裝成靜默的失敗。

評論的 start_line: 0 和 end_line: 0

OCR 無法把評論錨定到精確行——模型改寫了 existing_code 或 diff 格式異常。評論仍是真的，只是沒自動放置。多數 agent 整合讀 existing_code 自行定位。

"Max tool requests reached"

模型花了 30 輪工具呼叫沒調 task_done。到時的評論仍被收集。常見原因：模型不擅長遵從指令（換更強模型）、某工具持續報錯、檔案太大。用 --max-tools <n> 調整。

一些子 agent 失敗；運行仍以 0 退出

刻意為之。OCR 隔離 per-file 失敗——只要有成功的，聚合退出碼就是 0。看 JSON 的 warnings 陣列。

輸出與整合

--audience agent 仍有進度行

確認你看的不是 stderr。要屏蔽一切：ocr review --audience agent 2>/dev/null。

效能與成本

為什麼我的評審這麼貴？

• 檔案 ≥ 50 行時 plan 階段開啟——每檔多一次 LLM 呼叫。
• MAX_TOOL_REQUEST_TIMES = 30 很寬鬆。用滿輪數的模型產生更長對話。
• 記憶壓縮本身是一次 LLM 呼叫。

如何減少 LLM 呼叫？

• 加 include 清單，讓 OCR 不審你不關心的檔案。
• 調低 --concurrency。
• 傳 --background——充分的前期脈絡有時能省下 file_read/code_search 往返。

隱私與安全

OCR 會把我的程式碼發到別處嗎？

OCR 把你的 diff（及可選 read-tool 片段）發到你配置的 LLM 端點。其餘都不離開你的機器——會話 JSONL 與規則檔僅存於本地。遙測絕不導出 prompt 內容。

雜項

為什麼二進位叫 opencodereview 而 CLI 是 ocr？

Release 中的靜態二進位以專案命名（opencodereview）；NPM wrapper 為方便安裝為 ocr。

如何解除安裝？

npm uninstall -g @alibaba-group/open-code-review        # NPM install
sudo rm /usr/local/bin/ocr                              # binary install
rm -rf ~/.opencodereview                                # all state

📖 教學解說：FAQ 深度導讀

「零評論 ≠ 沒評審」的三種判讀

收到零評論時，不要猜——用三步診斷：

1. 看退出碼：0 = 正常完成（可能真的沒問題）；1 = 致命錯誤。
2. 看 warnings 陣列：JSON 輸出的 warnings 會列出失敗的子 agent。
3. 開 Session Viewer：看該檔 main_task 泳道——有工具呼叫 + task_done 結束 = 乾淨評審；以錯誤卡片結束 = 偽裝成靜默的失敗。

「No tool calls parsed」的根本原因

這不是設定問題——是模型問題。OCR 完全透過工具呼叫驅動評審。如果模型不支援原生 function calling（只在文字中描述工具呼叫），就永遠無法配合。解法：選有 tools 標籤的模型（如 qwen3、claude、gpt-4）。deepseek-r1 不行。

成本爆炸的三個隱藏殺手

三個讓評審變貴的隱藏因素：

1. Plan 階段：diff ≥ 50 行就多一次 LLM 呼叫。大檔案多，plan 成本疊加。
2. MAX_TOOL_REQUEST_TIMES = 30：很寬鬆。用滿輪數的模型（如不擅長遵從指令的）會產生巨量對話。
3. 記憶壓縮：超過 60% 預算觸發非同步壓縮，超過 80% 同步壓縮——每次壓縮是一次 LLM 呼叫。

解法：加 include 清單、傳 --background、調低 --concurrency。

延伸閱讀：設定 · 評審規則 · Session Viewer · 遙測