C
Claude Code Hackathon

トラブルシューティング

緊急時の対応フロー

参加者が困っている
    |
    +-- インストール系 → まず「ターミナルを新しく開き直して」と案内
    |   |
    |   +-- 直った → 続行
    |   +-- 直らない → PATHを手動追加（3分で完了）
    |       |
    |       +-- 直った → 続行
    |       +-- 直らない → winget方式に切り替え（5分で完了）
    |           |
    |           +-- 直った → 続行
    |           +-- 直らない → APIキー + 手動ダウンロード（最終手段）
    |
    +-- 認証系 → APIキー方式に切り替え（最速の解決策）
    |
    +-- ネットワーク系 → スマホのテザリングに切り替え
    |   （社内プロキシを回避）
    |
    +-- 実行時エラー → Esc / Ctrl+C で停止 → 指示を修正して再実行

トラブル1: claude コマンドが認識されない（最頻出）

症状:

claude : The term 'claude' is not recognized as the name of a cmdlet, function,
script file, or operable program.

原因: インストーラーが PATH 環境変数を自動設定しない既知の問題

Step 1: ターミナルの再起動

→ PowerShellウィンドウを完全に閉じる
→ 新しいPowerShellウィンドウを「管理者として実行」で開く
→ claude --version を実行

Step 2: claude.exe の存在確認

# claude.exe がどこにあるか確認
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

# 結果が True の場合 → PATHの問題。Step 3へ
# 結果が False の場合 → バイナリが作られていない。Step 4へ

Step 3: PATH を手動で追加

# 恒久的にPATHに追加（ユーザー環境変数）
[Environment]::SetEnvironmentVariable(
  "PATH",
  "$([Environment]::GetEnvironmentVariable('PATH', 'User'));$env:USERPROFILE\.local\bin",
  "User"
)

# 現在のセッションにも即座に反映
$env:PATH = "$env:PATH;$env:USERPROFILE\.local\bin"

# 確認
claude --version

コピペ用 → クイックコマンド集

Step 4: バイナリが存在しない場合 → wingetで再インストール

# winget でインストール（ネイティブインストーラーの代替）
winget install --id Anthropic.ClaudeCode

# Git も必要
winget install --id Git.Git -e --source winget

# ターミナルを再起動して確認
claude --version

Step 5: それでもダメ → 直接ダウンロード

# 手動でバイナリをダウンロード
$GCS_BUCKET = "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases"
$version = Invoke-RestMethod -Uri "$GCS_BUCKET/stable"
$downloadPath = "$env:USERPROFILE\Downloads\claude-installer.exe"
Invoke-WebRequest -Uri "$GCS_BUCKET/$version/win32-x64/claude.exe" -OutFile $downloadPath

# インストール実行
& $downloadPath install stable

# PATHを追加（Step 3参照）

トラブル2: ExecutionPolicy エラー

症状:

irm : Running scripts is disabled on this system.
File ... cannot be loaded because running scripts is disabled on this system.

原因: PowerShellのスクリプト実行ポリシーが Restricted に設定されている

対処:

# 現在のポリシー確認
Get-ExecutionPolicy

# ユーザースコープで変更（管理者権限不要）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 確認
Get-ExecutionPolicy
# → RemoteSigned と表示されればOK

# 再度インストールコマンドを実行
irm https://claude.ai/install.ps1 | iex

注意: 企業のグループポリシーで制限されている場合、ユーザースコープでも変更できないことがある。その場合は winget 方式に切り替える。

トラブル3: Git Bash で実行してしまった

症状:

Error: Raw mode is not supported on the current process.stdin

原因: Git Bash は Claude Code が必要とする TTY 機能をサポートしていない

対処:

→ Git Bash を閉じる
→ Windows PowerShell または Windows Terminal を使う
→ スタートメニュー → 「Terminal」で検索 → PowerShell タブで開く

参加者への説明: 「黒い画面」は何種類かあります。Claude Codeでは PowerShell（青い背景のもの）か Windows Terminal を使ってください。Git Bash（MINGW64 と表示されるもの）は使えません。

トラブル4: OAuth 認証が完了しない

症状A: ブラウザが自動で開かない

対処:
→ ターミナルに表示されたURLを `c` キーを押してコピー
→ ブラウザに手動で貼り付けてアクセス
→ 認証コードが表示されたらターミナルに貼り付け

症状B: 認証完了後に “OAuth error” が表示される

対処:
1. 認証情報をクリア
   Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
   Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

2. claude を再起動して再度ログイン

3. それでもダメなら APIキー方式に切り替え
   $env:ANTHROPIC_API_KEY = "sk-ant-xxxxx"
   claude

症状C: “OAuth account information not found in config” エラー

対処:
1. ブラウザのキャッシュ・Cookieをクリア
2. ブラウザのシークレットモードで認証を試す
3. ~/.claude フォルダを削除して再ログイン
4. 最終手段: APIキー方式に切り替え

当日のTip: OAuthトラブルが多発しそうな場合、最初から APIキー方式 を全員に配布するのが最も安全。

# APIキーを環境変数に設定
$env:ANTHROPIC_API_KEY = "sk-ant-api03-xxxxxxxx"
claude

トラブル5: プロキシ / ファイアウォール問題

症状:

Request timed out. Check your internet connection and proxy settings
Error: connect ETIMEDOUT
Unable to connect to Anthropic services

対処:

# まず接続テスト
Invoke-WebRequest -Uri "https://api.anthropic.com" -UseBasicParsing

# プロキシが必要な場合、環境変数を設定
$env:HTTPS_PROXY = "http://your-proxy-server:port"
$env:HTTP_PROXY = "http://your-proxy-server:port"

必要なURLの許可リスト（IT部門に事前依頼）:

URL用途
claude.aiインストール・OAuth認証
api.anthropic.comAPI通信
storage.googleapis.comインストーラーダウンロード
console.anthropic.comConsole認証
sentry.ioエラーレポーティング（任意）

トラブル6: winget が使えない / 見つからない

症状:

winget : The term 'winget' is not recognized...

対処:

1. Microsoft Store → 「App Installer（アプリ インストーラー）」を検索 → 更新/インストール
2. PC再起動
3. 新しいPowerShellを開いて winget --version で確認

App Installer も入れられない場合:

→ ネイティブインストーラー（irm https://claude.ai/install.ps1 | iex）を使用
→ それもダメなら手動ダウンロード（トラブル1のStep 5参照）

トラブル7: Node.js 関連のエラー（npm方式の場合）

症状:

node : The term 'node' is not recognized...
npm ERR! code EACCES

対処: 現在はネイティブインストーラーが推奨（Node.js不要）。npm方式は非推奨。

→ まずネイティブインストーラーに切り替え
   irm https://claude.ai/install.ps1 | iex

→ 既にnpm版が入っている場合はマイグレーション
   claude install

トラブル8: claude doctor で問題が検出された

claude doctor

このコマンドはインストール方法、バージョン、環境をチェックして問題を表示してくれる。

よくある出力と対処:

出力対処
installMethod is native, but claude command not foundPATHの問題。トラブル1のStep 3を実行
Git not foundwinget install --id Git.Git -e --source winget
Node.js not foundネイティブ版では不要。npmからの移行が必要なら claude install
Outdated versionwinget upgrade Anthropic.ClaudeCode または再インストール

トラブル9: Claude Codeが途中でフリーズ・応答しない

対処:

1. Esc キーを押す（操作の中断）
2. Ctrl + C を押す（強制停止）
3. それでも止まらない場合 → ターミナルウィンドウを閉じる
4. 新しいターミナルを開いて claude を再実行
5. 長時間タスクの場合 → /compact でコンテキストを圧縮してからリトライ

トラブル10: コンソールウィンドウが一瞬点滅して消える

症状: claude 実行時にコマンドプロンプトの窓が一瞬開いて閉じる

原因: v2.1.27 で修正された既知の問題だが、古いバージョンでは発生する

対処:

# バージョン確認
claude --version

# 古い場合はアップデート
winget upgrade Anthropic.ClaudeCode

# または再インストール
irm https://claude.ai/install.ps1 | iex