theo status / theo verify - Theo API Docs

兩個命令覆蓋的檢查範圍相同，但精細程度不同——theo status 面向人類使用者，theo verify 面向腳本。

`theo status`

theo status

人類可讀的連接與健康檢查。它會針對配置的 baseUrl 調用 theo.verify()，同時探測另一個主機（裸域名 vs www），以捕獲裸域名重定向導致的 401 陷阱——這是首次使用時出現 401 的頭號原因。

示例輸出（健康狀態）

[theo] API key: theo_sk_live_a1b...
[theo] Base URL: https://www.hitheo.ai

[theo] ✓ Status: healthy
[theo] Version: 2026-03-28
[theo] Models available: 14
[theo] Round-trip: 186ms

[theo] ✓ Authentication OK

示例輸出（裸域名重定向導致的 401）

[theo] API key: theo_sk_live_a1b...
[theo] Base URL: https://hitheo.ai

[theo] ❌ Verification failed against https://hitheo.ai
[theo]   Reason: Theo API error 401: Invalid API key
[theo]   Hint: Authentication failed. Confirm your API key starts with `theo_sk_` …

[theo] Retrying against the canonical host https://www.hitheo.ai...
[theo] ✓ https://www.hitheo.ai responded with auth in 172ms.

[theo] ⚠  Your configured baseUrl appears to be a redirect target that drops the
[theo]    Authorization header. Update your SDK config:
[theo]      new Theo({ apiKey, baseUrl: "https://www.hitheo.ai" })
[theo]    or unset THEO_BASE_URL to use the SDK default.

關於此問題產生原因的完整背景說明，請參閱 401 故障排查。

`theo verify`

theo verify

同一診斷的機器可讀版本。它會輸出 JSON，並在 authenticated 為 false 時以 1 退出，因此你可以據此在 CI 中設置門禁。

{
  "healthy": true,
  "authenticated": true,
  "baseUrl": "https://www.hitheo.ai",
  "latencyMs": 186,
  "modelCount": 14,
  "version": "2026-03-28"
}

腳本化使用

if ! theo verify > /tmp/theo.json; then
  echo "Theo API unreachable or key invalid:"
  jq -r '.error, .hint' /tmp/theo.json
  exit 1
fi

同一診斷也可以通過 SDK 中的 theo.verify() 以編程方式調用。