Codex CLIログの場所と診断手順：doctor→TUI・SQLiteの順で確認¶
対象: Codexの障害をログとdoctorで切り分けたい人
codex doctor --summary
codex doctor --json > codex-doctor.json
先にdoctorで、実行中のCodex、設定、認証の有無、ネットワーク、ログ・状態DBの実パスを確認する。~/.codex/log/codex-tui.logが必ず存在するとは限らないため、固定パスを前提にしない。
この記事のポイント¶
- ログを探す前に
codex doctorで障害の層を決める - TUIログ、SQLiteログ、セッションJSONLを別物として扱う
- 公開Issueにはrawログではなく伏字済み要約を載せる
どこを見ればよいか¶
Codexの診断情報は、役割が違う4種類に分かれる。
| 情報 | まず使う方法 | 分かること | 公開時の注意 |
|---|---|---|---|
| 健全性レポート | codex doctor --summary | 設定、認証、ネットワーク、stateの大分類 | JSON全文にはローカルパスが含まれ得る |
| TUIテキストログ | doctorが示すlog dir | 直前の警告・エラー | プロンプトやコマンドが含まれ得る |
| SQLiteログDB | doctorが示すlog DB | 内部の構造化ログ | raw DBを公開しない |
| セッションJSONL | $CODEX_HOME/sessions/ | 会話、ツール呼び出し、結果 | 会話・コード・パスを含むため原則非公開 |
auth.jsonは診断ログではない。トークンを含む認証資材なので、内容を表示・コピー・添付しない。
手順1：doctorで障害の層を決める¶
画面で読む¶
codex doctor --summary
最初は個々のログ行より、次の分類を見る。
- installation / runtime: PATH重複、実行中バイナリ、更新経路
- config: 読み込んだ
CODEX_HOMEとconfig.toml - auth: 認証が構成されているか。トークン自体は見ない
- network / websocket: HTTP到達性とWebSocket handshake
- sandbox: 承認・ファイル・ネットワーク境界
- state: state DB、log DB、rollout fileの整合性
- MCP: 設定ファイル上の静的な不整合
たとえばWebSocketだけ失敗してHTTP到達性が成功するなら、認証ファイル削除よりVPN、IPv6、プロキシ、WebSocket経路を先に疑う。
JSONは保存後に必要部分だけ抜く¶
codex doctor --json > codex-doctor.json
--jsonに対応していない古いCLIではエラーになる。その場合は先にcodex --versionを記録し、CLIの更新可否を確認する。
JSONは機械可読だが、完全匿名とは限らない。公式Issueでも、raw JSONではなくローカルユーザー名、パス、プロジェクト名、state locationを伏せた要約を共有する例がある。1
手順2：実際のログ場所をdoctorから読む¶
Codexのログ保存方式は、インストール経路や機能構成で変わる。環境によっては次の両方、または片方だけがある。
$CODEX_HOME/log/codex-tui.log
<sqlite home>/logs_2.sqlite
codex doctor --jsonのconfig.loadやstate.pathsに、log dir、log DB、sqlite homeが出る。log dirがmissingでも、logs_2.sqliteが正常なら「ログが一切ない」とは限らない。
テキストログが存在する場合だけ、末尾と対象文字列を読む。
tail -n 120 "$CODEX_HOME/log/codex-tui.log"
rg -n -i 'error|warn|reconnect|401|403|timeout|mcp' \
"$CODEX_HOME/log/codex-tui.log" | tail -n 80
CODEX_HOMEを設定していない環境では、doctorが示した実パスに置き換える。
SQLiteログDBは内部スキーマが変わり得る。独自SQLを固定手順として記事や運用へ埋め込まず、まずdoctorのDB integrity結果と、エラー画面の文字列を使う。raw DBをGitHub Issueへ添付しない。
手順3：エラー文字列で分岐する¶
| doctor / 画面の手掛かり | 次に確認するもの |
|---|---|
HTTP 401 / auth failed | codex login状態、アカウント、時刻ずれ。auth.json本文は見ない |
| WebSocket handshake failed | VPN、proxy、IPv4/IPv6、再接続記事 |
Network access is restricted | workspace sandboxのnetwork設定 |
missing field sandboxPolicy | Browser / Computer Useとnode_replの版互換性 |
| MCP command/env/cwd warning | 対象MCPの実行ファイル、環境変数、cwd |
failed to initialize sqlite state runtime | DBエラーコード、パスがWindows/WSLをまたいでいないか |
| PATHに複数Codex | 実行中バイナリと更新先の不一致 |
ログ例を想像でエラーへ当てはめない。画面に出た正確な1行とdoctorの分類が一致するかを先に確認する。
公開Issueに載せる最小セット¶
次のテンプレートで十分なことが多い。
## Environment
- Codex version: `<codex --version>`
- Surface: CLI / Desktop / IDE extension
- OS: `<OS and version>`
- Install method: npm / Homebrew / standalone / Store
## Exact error
`<one exact error message>`
## Reproduction
1. ...
2. ...
3. ...
## Doctor summary (redacted)
- installation: ...
- config: ...
- auth: configured / not configured
- network HTTP: ...
- WebSocket: ...
- state DB: ...
## Already tried
- ...
添付しないもの¶
auth.json、APIキー、Cookie、認証ヘッダーlogs_2.sqliteそのもの- セッションJSONLそのもの
.codex/CODEX_HOME全体のzip.env、SSH鍵、クラウド資格情報- 未確認のTUIログ全文
公式Codex Issueでも、SQLiteログとセッションファイルにはプロンプト、ローカルパス、コマンド履歴、プロジェクト名、ツール出力が入り得ると注意されている。2
よくある誤診¶
doctorが成功したのでDesktopも正常¶
ターミナルのCLIとDesktop同梱app-serverが別バイナリなら、CLIだけ正常なことがある。Desktop固有障害ではAboutのビルド番号も記録する。
codex-tui.logがないのでログがない¶
構造化ログがlogs_2.sqliteへ保存されている場合がある。doctorのstate.pathsを確認する。
401なのでauth.jsonを削除する¶
認証ファイルの削除は状態を失う変更だ。まずcodex loginの状態、doctorのauth分類、システム時刻、正確なHTTPエラーを確認する。
/feedbackの出力は常に同じ¶
スラッシュコマンドや出力形式は変わる。存在しない固定フィールドや架空のRequest ID例を診断手順の前提にしない。
まとめ¶
- 最初は
codex doctor --summary、共有用には--jsonの必要部分だけを伏字して使う - ログの実パスは固定せず、doctorの
log dirとlog DBを読む - TUIログ、SQLite DB、セッションJSONL、認証ファイルを同じものとして扱わない
- rawログやDBを公開せず、正確なエラー1行とdoctor要約をIssueへ載せる