トラブルシューティング
よくある症状と、切り分けのための確認ポイントをまとめます。
関連: pages/guides/faq.md(よくある失敗の一覧)
プラグイン
コマンドやスキルが表示されない
- インストール直後なら
/reload-pluginsを実行する。 - コマンドは名前空間付きである。
/review-localではなく/river-review:review-localと入力する。 claude plugin listでriver-reviewが導入済みかを確認する。無効化されている場合はclaude plugin enable river-review@river-review-marketplaceで有効化する。- Codex 向けの配布定義(
.codex-plugin/plugin.json)はskillsを宣言し、commandsを宣言していない。スラッシュコマンドは Codex 向けの配布物に含まれない。詳細は コマンド・エージェント・スキル を参照する。 - Codex で導入済み・有効なのにスキルが使えない場合は、スキル一覧の予算超過を疑う。導入しているスキルが多いと、Codex はモデルに渡すスキル一覧を予算内に切り詰め、名前順で後ろにある
river-review:*が一覧から落ちることがある。リポジトリの外でcodex debug prompt-input testを実行し、river-review:で始まるスキルが出るかを確かめる。出ない場合は、使っていないプラグインを外すか、予算を上げる。予算を上げるときは、まずcodex -c skills.max_context_tokens=10000 debug prompt-input testで出ることを確かめる(公式ドキュメントでは、明示する値の上限は 10,000 トークン)。確かめたら~/.codex/config.tomlの[skills]にmax_context_tokensを設定する。codex-cli 0.160.1 で確認した挙動である。
導入済みの版が古い
claude plugin marketplace update river-review-marketplace でマーケットプレイスを更新してから claude plugin update river-review@river-review-marketplace を実行します。更新の反映には再起動が必要です。最新の版は GitHub Releases で確認できます。
編集したファイルが勝手に整形される
PostToolUse hook がプロジェクトの prettier で変更ファイルを整形しています。挙動と止め方は 更新・無効化・アンインストール を参照してください。
CLI(river run)
まず最初に(事前診断)
原因の切り分けが難しい場合は、まず river doctor . を実行して「設定の不足」や「差分取得の失敗」を確認してください。
OpenAI API key が見つからない
- 症状(例):
LLM: OPENAI_API_KEY (or RIVER_OPENAI_API_KEY) not setRiver Review doctorのOpenAI (review): not set
- 対応:
OPENAI_API_KEYまたはRIVER_OPENAI_API_KEYを環境変数で設定すること- 外部送信を避けたい場合は
--dry-runを利用すること
Git リポジトリとして認識されない
- 症状:
Not a git repository: ... - 対応:
- Git 管理下のディレクトリで実行すること
- 必要なら
git init/git clone ...
スキル定義の読み込み/検証に失敗する
- 症状:
Skill configuration error: ... - 対応:
npm run skills:validateを実行してエラー詳細を確認すること- スキルスキーマの詳細は
pages/reference/skill-schema-reference.mdを参照すること
ルール(.river/rules.md)が読めない
- 症状: rules ファイル読み込みエラー
- 対応:
.river/rules.mdの存在と読み取り権限を確認すること(不要なら削除して無効化できる)
何がスキップされたのか分からない
- 対応:
river run . --debugを付けて、選択されたスキルとスキップ理由の出力を確認すること
ローカル実行でファイルが検出されない
- 対応:
git statusやgit diffで差分を確認することriver run . --debugで対象ファイル・ハンクのプレビューを確認すること
レート制限エラー
- 対応:
- OpenAI 側のレート制限に達していないか確認すること
- しばらく待ってから再実行すること
- 必要に応じて
--dry-runでプロンプト/スキル選択のみ確認すること
GitHub Actions
レビューが実行されない / 権限エラー
permissionsが不足している可能性がある(例:pull-requests: write)OPENAI_API_KEYなどの Secrets が正しく設定されているか確認すること
差分が検出されない
actions/checkoutのfetch-depth: 0を推奨する(merge-base を安定して取得するため)