gacのトラブルシューティング

May 18, 2026 · View on GitHub

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | हिन्दी | Tiếng Việt | Français | Русский | Español | Português | Norsk | Svenska | Deutsch | Nederlands | Italiano

このガイドでは、gacのインストール、設定、実行に関する一般的な問題と解決策について説明します。

目次

1. セットアップの問題

問題: uvx コマンドが見つからない

  • astral.sh/uv の手順に従って uv をインストール
  • uv がインストールされて $PATH にあることを確認
  • インストール後にターミナルを再起動

2. 設定の問題

問題: gacがAPIキーやモデルを見つけられない

  • 新しい場合、uvx gac init を実行して対話的にプロバイダー、モデル、APIキーを設定
  • .gac.env または環境変数が正しく設定されていることを確認
  • uvx gac --log-level=debug を実行してどの設定ファイルが読み込まれているかを確認し、設定問題をデバッグ
  • 変数名のタイプミスを確認（例: GAC_GROQ_API_KEY）

問題: ユーザーレベル $HOME/.gac.env の変更が反映されない

  • OS用の正しいファイルを編集していることを確認:
    • macOS/Linux: $HOME/.gac.env（通常 /Users/<your-username>/.gac.env または /home/<your-username>/.gac.env）
    • Windows: $HOME/.gac.env（通常 C:\Users\<your-username>\.gac.env または %USERPROFILE% を使用）
  • uvx gac --log-level=debug を実行してユーザーレベル設定が読み込まれていることを確認
  • 環境変数をリロードするためにターミナルを再起動するか、シェルを再実行
  • まだ動作しない場合、タイプミスとファイル権限を確認

問題: プロジェクトレベル .gac.env の変更が反映されない

  • プロジェクトのルートディレクトリ（.git フォルダの隣）に .gac.env ファイルが含まれていることを確認
  • uvx gac --log-level=debug を実行してプロジェクトレベル設定が読み込まれていることを確認
  • .gac.env を編集した場合、環境変数をリロードするためにターミナルを再起動するか、シェルを再実行
  • まだ動作しない場合、タイプミスとファイル権限を確認

問題: コミットメッセージの言語を設定または変更できない

  • uvx gac language（または uvx gac lang）を実行して25以上の対応言語から対話的に選択
  • -l <language> フラグを使用して単一コミットの言語を上書き（例: uvx gac -l zh-CN, uvx gac -l Japanese）
  • uvx gac config show で現在の言語設定を確認
  • 言語設定は .gac.env ファイルの GAC_LANGUAGE に保存されます

3. プロバイダー/APIエラー

問題: 認証またはAPIエラー

  • 選択したモデル用の正しいAPIキーが設定されていることを確認（例: ANTHROPIC_API_KEY, GROQ_API_KEY）
  • APIキーとプロバイダーアカウントステータスを再確認
  • OllamaとLM Studioの場合、API URLがローカルインスタンスと一致することを確認。APIキーは認証を有効にした場合にのみ必要です。
  • Claude Codeのトークン有効期限の場合：uvx gac authを実行して素早く再認証してトークンを更新します。ブラウザが自動的にOAuthのために開きます。
  • ChatGPT OAuth トークン有効期限の場合：uvx gac auth chatgpt loginを実行して再認証します。ブラウザが自動的に OAuth のために開きます。
  • その他のClaude Code OAuthの問題については、包括的なトラブルシューティングについてClaude Code設定ガイドを参照してください。
  • その他の ChatGPT OAuth の問題については、包括的なトラブルシューティングについて ChatGPT OAuth 設定ガイド を参照してください。
  • GitHub Copilot セッショントークンの有効期限の場合：Device Flow で再認証するには uvx gac auth copilot login を実行します。セッショントークンはキャッシュされた OAuth トークンから自動的に更新されます。
  • その他の GitHub Copilot の問題については、包括的なトラブルシューティングについて GitHub Copilot 設定ガイド を参照してください。

問題: モデルが利用できないまたはサポートされていない

  • Streamlakeはモデル名の代わりに推論エンドポイントIDを使用します。コンソールからエンドポイントIDを確認してください。
  • モデル名が正しく、プロバイダーでサポートされていることを確認
  • 利用可能なモデルについてはプロバイダードキュメントを確認

4. コミットグループ化の問題

問題: --group フラグが期待通りに動作しない

  • --group フラグは自動的にステージされた変更を分析し、複数の論理的コミットを作成できます
  • --group を使用しても、LLMはステージされた変更のセットに対して単一のコミットが理にかなうと判断する場合があります
  • これは意図的な動作です - LLMは数量だけでなく論理的関係に基づいて変更をグループ化します
  • 最良の結果のために複数の無関係な変更（例: バグ修正 + 機能追加）をステージしていることを確認
  • uvx gac --show-prompt を使用してLLMが見ているものをデバッグ

問題: コミットが誤ってグループ化されている、または期待通りにグループ化されていない

  • グループ化はLLMの変更分析によって決定されます
  • LLMは変更が論理的に関連していると判断した場合、単一のコミットを作成する場合があります
  • グループ化ロジックを導くために -h "ヒント" でヒントを追加してみてください（例: -h "バグ修正をリファクタリングから分離"）
  • 確定前に生成されたグループを確認
  • グループ化がユースケースでうまく機能しない場合、代わりに変更を別々にコミットしてください

5. セキュリティと秘密検出

重要: 秘密スキャンはAI API呼び出しが行われる前に実行されます。秘密が検出された場合、ワークフローは直ちに中止され、API呼び出しは行われません。スキャナーは正規表現ベースのパターンマッチング（LLMではない）を使用するため、スキャンは高速で完全にローカルで実行されます — 秘密検出のためにコードがAIモデルに送信されることはありません。

問題: 偽陽性: 秘密スキャンが非秘密を検出

  • セキュリティスキャナーはAPIキー、トークン、パスワードに似た正規表現パターンを探します
  • サンプルコード、テストフィクスチャ、またはプレースホルダーキー付きのドキュメントをコミットする場合、偽陽性が見られる場合があります
  • 変更が安全であると確信している場合、--skip-secret-scan を使用してスキャンをバイパス
  • テスト/サンプルファイルをコミットから除外するか、明確にマークされたプレースホルダーを使用することを検討

問題: 秘密スキャンが実際の秘密を検出しない

  • スキャナーは正規表現ベースのパターンマッチング（LLMではない）を使用し、すべての秘密タイプをキャッチできない場合があります
  • コミット前に git diff --staged でステージされた変更を常に確認
  • 包括的な保護のために git-secrets や gitleaks などの追加のセキュリティツールの使用を検討
  • 見逃されたパターンを問題として報告して検出の改善に協力

問題: 秘密スキャンを永続的に無効化する必要がある

  • .gac.env ファイルで GAC_SKIP_SECRET_SCAN=true を設定
  • uvx gac config set GAC_SKIP_SECRET_SCAN true を使用
  • 注意: 他のセキュリティ対策が適切されている場合にのみ無効化してください

6. Pre-commitとLefthookフックの問題

問題: Pre-commitまたはlefthookフックが失敗し、コミットをブロック

  • uvx gac --no-verify を使用して一時的にすべてのpre-commitとlefthookフックをスキップ
  • フックが失敗している根本的な問題を修正
  • フックが厳しすぎる場合、.pre-commit-config.yaml または .lefthook.yml でpre-commitフックを設定して調整することを検討

問題: Pre-commitまたはlefthookフックが時間がかかりすぎるか、ワークフローに干渉

  • uvx gac --no-verify を使用して一時的にすべてのpre-commitとlefthookフックをスキップ
  • ワークフローのためにあまり攻撃的でないように .pre-commit-config.yaml または .lefthook.yml でpre-commitフックを設定することを検討
  • パフォーマンスを最適化するためにフック設定を確認

7. 一般的なワークフローの問題

問題: コミットする変更がない / 何もステージされていない

  • gacはコミットメッセージを生成するためにステージされた変更を必要とします
  • git add <files> で変更をステージするか、uvx gac -a ですべての変更を自動的にステージ
  • git status を使用して変更されたファイルを確認
  • uvx gac diff を使用して変更のフィルタリングされたビューを確認

問題: コミットメッセージが期待通りでない

  • 対話的フィードバックシステムを使用: r で再生成、e で編集（インプレース TUI、または GAC_EDITOR で外部エディタ）、または自然言語フィードバックを提供
  • -h "あなたのヒント" でLLMを導くコンテキストを追加
  • より単純なメッセージに -o、より詳細なメッセージに -v を使用
  • --show-prompt を使用してLLMが受信している情報を確認

問題: gacが遅すぎる

  • uvx gac -y を使用して確認プロンプトをスキップ
  • uvx gac -q を使用して出力が少ない静默モードを使用
  • 定期的なコミットにより高速/安価なモデルを検討
  • フックが速度を落としている場合、uvx gac --no-verify を使用してフックをスキップ

問題: メッセージ生成後に編集またはフィードバックができない

  • プロンプトで e と入力して編集モードに入る（vi/emacs キーバインドのインプレース TUI、お好みのエディタを使うには GAC_EDITOR を設定）
  • フィードバックなしで再生成するには r と入力
  • またはフィードバックを直接入力（例: "もっと短くして", "バグ修正に集中"）
  • 空入力でEnterを押すとプロンプトを再表示

8. 一般的なデバッグ

  • uvx gac init を使用して設定を対話的にリセットまたは更新
  • uvx gac --log-level=debug を使用して詳細なデバッグ出力とログを取得
  • uvx gac --show-prompt を使用してLLMに送信されるプロンプトを確認
  • uvx gac --help を使用して利用可能なすべてのコマンドラインフラグを確認
  • uvx gac config show を使用して現在のすべての設定値を確認
  • エラーメッセージとスタックトレースのログを確認
  • 機能、例、クイックスタートについてはメインの README.md を確認

まだ解決しない？

  • GitHubリポジトリ で既存の問題を検索するか、新しい問題を開く
  • OS、Pythonバージョン、gacバージョン、プロバイダー、エラー出力について詳細を含める
  • 提供する詳細が多いほど、問題の解決が迅速になります

さらにヘルプを得る場所