Claude Code 出現 Request timed out：API_TIMEOUT_MS 與代理設定排查

Wokey Team · 2026-09-24

簡短回答： Request timed out 表示 Claude Code 在期限內沒有收到 API 的回應，期限預設是 10 分鐘（API_TIMEOUT_MS=600000）。透過閘道連線時，常見原因不是模型太慢。更多時候是中間有東西把串流回應壓住了，或把安靜太久的連線切斷了。這可能是本機代理、公司網路，或是閘道本身。先用 curl 確認串流是一段一段到達的，再決定要不要調高逾時。

你看到的是哪一種

前四種來自 Claude Code 本身；後兩種來自伺服器。

Wokey 的逾時錯誤

Wokey 的逾時錯誤一律是標準錯誤格式的 504。code 告訴你請求卡在哪裡：

例如：

{"error":{"code":"upstream_gateway_timeout","message":"Upstream gateway timed out before producing a response.","type":"invalid_request_error"}}

如果逾時發生在回覆已經開始串流之後，它會以串流內的 error 事件送達，而不是 HTTP 504。

長時間沒有輸出時，例如模型長時間思考，Wokey 會定期在串流中寫入 SSE 註解來保持連線：

: wokey-transport-keepalive-v1

用戶端會忽略註解行。用 curl 測試時看到它，表示連線還活著，模型仍在處理。

排查步驟

1. 用 curl 確認串流是一段一段到達的。

curl -N https://api.wokey.ai/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":300,"stream":true,"messages":[{"role":"user","content":"Count from 1 to 60"}]}'

-N 會關閉 curl 自己的緩衝。

• event: 和 data: 行隨到隨捲動： 整條路徑都沒問題。
• 等了很久才一次全部出現： 中間有東西在緩衝回應，Claude Code 走這條路徑很容易逾時。

2. 檢查本機代理。 Claude Code 會遵循 HTTPS_PROXY 和系統代理設定。TUN 模式、規則式代理和公司閘道都可能緩衝串流回應或切斷閒置連線。如果你的網路能直接連到 api.wokey.ai，把這個網域排除在代理之外再試一次。如果一定要用代理，換一個節點比較看看。

3. 調高逾時。 確認路徑沒問題、請求確實很長之後，在 ~/.claude/settings.json 的 env 區塊調高上限：

{
  "env": {
    "API_TIMEOUT_MS": "1200000"
  }
}

• API_TIMEOUT_MS 是每個請求的逾時，單位是毫秒。預設是 600000（10 分鐘）。
• 如果你網路上的代理會等回應完成才放行，Claude Code 的錯誤訊息建議也一併調高 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS。
• 串流中途停住的偵測由 CLAUDE_STREAM_IDLE_TIMEOUT_MS 控制。低於 5 分鐘的值會被提高到 5 分鐘，上限是 30 分鐘。

4. 縮小上下文。 上下文越大，上傳越慢，第一個 token 也越晚出現。執行 /compact 壓縮工作階段，或開一個新的。

5. 如果收到 408。 408 表示請求內容在上傳途中停止送達，閘道放棄等待。它幾乎只會在不穩定的網路上傳送非常大的上下文時出現。單純重試通常就會成功。如果一直發生，照步驟 2 檢查代理，再用 /compact 縮小請求。

Codex 的逾時

Codex 的串流閒置逾時預設是 300000 ms（5 分鐘）。觸發時會看到 idle timeout waiting for SSE 或 stream disconnected before completion，自動重試時會顯示 Reconnecting... n/max。這些設定寫在 provider 表格中：

[model_providers.wokey]
name = "Wokey"
base_url = "https://api.wokey.ai"
env_key = "WOKEY_API_KEY"
wire_api = "responses"
stream_idle_timeout_ms = 600000
stream_max_retries = 10

stream_max_retries 預設是 5，request_max_retries 預設是 4，兩者上限都是 100。完整設定請見 Codex config.toml 設定指南。