初心者のトラブルシューティング

Codex 学習目次に戻る

目標と使い方

図の01は症状記録、02は最小確認1つ、03は原因修正後の元操作の再実行です。毎回すぐ再試行せず、入力・状態・利用可能環境を保存して問題を絞ります。

最初に：症状と最後の成功操作を記録

時刻・プラットフォーム・版・現在場所・正確な命令／操作・期待・エラー原文を記録します。関係情報だけを共有しアカウント・私有パス・鍵を遮蔽します。導入後に命令がなければ導入結果、別 run が動けばタスク名・ホストを残します。赤字だけに切り取らず、直前の命令と場所を含めます。次の判断を左右するためです。

# Troubleshooting record
- Time and timezone:
- Surface: desktop / CLI / IDE / mobile / web
- OS and app or CLI version:
- Working folder or execution host (redacted if shared):
- Exact command or UI action:
- Expected result:
- Actual error and exit status:
- Last successful action:
- One change attempted:
- Result after that change:
- Files or settings to restore:

導入・ログイン・プラットフォーム入口

codex がない: CLI 導入

PowerShell が阻止: Windows CLI

macOS／Linux の導入場所違い: macOS · Linux／WSL

ログイン後も無権限: アカウント・利用量

デスクトップ・携帯の操作がない: プラットフォーム選択

同じ PC の Windows・WSL・コンテナー・遠隔も認証や設定を共有するとは限らず、失敗環境を識別します。

Windows は Get-Command codex、macOS／Linux は command -v codex で実行ファイルを確認します。複数導入は記録し、直ちに版削除やシステム全体のセキュリティ方針を変えません。ChatGPT 認証・API 鍵・組織制限を分け、再導入で利用枠は増えません。サービス異常は公式ステータスページを時刻・項目と照合し、全体正常でも自分のネットワーク・権限正常とは断定しません。

作業場所・MD・設定

編集が画面に出ない: パス · ブラウザー

AGENTS.md が効かない: 規則範囲

README を永久規則扱い: 文書役割

TOML 解析失敗: 設定トラブルシューティング

再開で古い結論: セッション · 引き継ぎ

1条件ずつ変え、復旧後は必要変更を残して自分の診断識別マーカーを除き、全設定をインターネット上の雛形で上書きしません。

再現実習：正しいフォルダーを見つける

新規 path-trouble に空 project・other を作り、project だけに下記 marker.md を置きます。other から端末を開き、わざと marker.md を読んでファイル欠如を再現します。Codex や正式変更は不要です。現在地・一覧を調べ、明確な相対パスで読み、project に cd して元の読取を再実行します。

# Correct folder: PATH-PRACTICE-1

Get-Content -LiteralPath .\marker.md
Get-Location
Get-ChildItem
Get-Content -LiteralPath ..\project\marker.md
Set-Location -LiteralPath ..\project
Get-Content -LiteralPath .\marker.md

cat ./marker.md
pwd
ls
cat ../project/marker.md
cd ../project
cat ./marker.md

最初は失敗、後2回は同じ PATH-PRACTICE-1 で、内容ではなく操作場所を修正したと分かります。元場所に戻り教材は残せばよく、再帰削除は不要です。Codex でも先に根ディレクトリ・指定ファイルの存在を報告させてプロジェクト違いを判断します。同名タスク・別 worktree・携帯の古い内容は同じディレクトリの証拠ではありません。

PowerShell の Get-Content は cmdlet なので $? を直後に保存します。$LASTEXITCODE は主に codex や node などの外部実行ファイル用です。経路演習後の project から、下では不在の other/marker.md と本物を順に読みます。PowerShell は False、True、shell は非ゼロ、0 を期待します。他の命令で状態を上書きする前に保存します。

Get-Content -LiteralPath ..\other\marker.md
$practiceReadOk = $?
$practiceReadOk
Get-Content -LiteralPath .\marker.md
$practiceReadOk = $?
$practiceReadOk

cat ../other/marker.md
practice_read_exit=$?
printf '%s\n' "$practice_read_exit"
cat ./marker.md
practice_read_exit=$?
printf '%s\n' "$practice_read_exit"

正確な定義は PowerShell 自動変数を参照します。二回の読取りは marker を変更しません。予期しない編集は別途調べ、経路修正と原文保持を引継ぎで分けます。

ツール・遠隔・自動化

Skill 可視だが誤動作: スキル検証

導入 Plugin が読めない: プラグイントラブルシューティング

MCP 設定済みでツールなし: MCP トラブルシューティング

携帯の旧資料: 遠隔設定 · デバイス間の引き継ぎ

エージェント完了報告と結果衝突: 品質 · 統合

予約タイムアウト・重複: 復旧

JSON 回答あり・プロセス失敗: JSON／JSONL

症状に関わる層を扱い、プラグイン導入と出典アカウントの読取権限を分けます。

トラブルシューティングを終えて作業に戻る

修正後に元失敗操作と隣接挙動を検証します。Completed 修正後は Active、設定変更後は以前の正常項目、MCP 再接続後は緑アイコンだけでなく架空文書の実読取です。症状・原因・単一修正・検証を issue-notes.md に記録し、引き継ぎは最小入力と試行手順を渡します。未解決ならそう記し、利用可能状態と次に取る証拠を残します。

自分の暫定識別マーカー・設定を戻し、必要修正・バックアップ・記録を保持します。トラブルシューティングを理由に全設定消去・セッション削除・機密公開はしません。索引を最初から全実施する必要はなく症状の1行を選びます。各編の上下から学習目次へ戻り、機能・命令・MD 名で次を探せます。プラットフォームの非対応・未開放は導入障害と分けます。

Codex 学習目次に戻る

詳しい説明を読む

Symptom to One check to Retry

• AIツール
• チュートリアル
• Codex