Claude Media
Claude CodeのBashツールとシェル起動設定 — zsh/bash/PowerShellの違い

Claude CodeのBashツールとシェル起動設定 — zsh/bash/PowerShellの違い

ClaudeのBashツールは、使用中のシェルがzshでもbashでも起動ファイルを読み込みます。PowerShellは読み込みません。違いと環境変数の引き継ぎ方、確認プロンプトの理由を示します。

ClaudeのBashツールは、Claude Codeがシェルコマンドを実行するための道具です。セッション開始時にシェルの起動ファイルを読み込み、そこで定義したエイリアスや関数をBashコマンドに反映します。ただしこの挙動はシェルによって差があり、PowerShellツールはプロファイルを読み込みません。起動ファイルへの書き込みには確認プロンプトが挟まる仕様もあり、知らずに依頼すると「なぜ止まるのか」で戸惑いがちです。この記事ではzsh・bash・PowerShellそれぞれの初期設定の扱いと、環境変数を引き継ぐ実用的な方法をまとめます。

zsh・bash・PowerShellで何が違うのか

Claude Codeに「Bash」という別のシェルがあるわけではありません。Bashツールは、使っているシェル(zshやbash)の設定を引き継いでコマンドを動かす実行口の名前です。PowerShellは別のツールとして用意されています。違いは次の表のとおりです。

項目zsh・bash(Bashツール)PowerShellツール
読み込む起動ファイルzsh・bash(Bashツール)zshは~/.zshrc、bashは~/.bashrc、それ以外は~/.profilePowerShellツールプロファイル($PROFILE)は読み込まない
エイリアス・関数zsh・bash(Bashツール)セッション開始時に取り込み、全コマンドで使えるPowerShellツール$PROFILEの定義は見えない
環境変数の持ち越しzsh・bash(Bashツール)CLAUDE_ENV_FILEの中身を毎回実行PowerShellツールv2.1.296以降。ファイルは実行せず、全行が単純な代入のときだけ値をコピー(1行でも例外があれば何も渡らない)
有効にする条件zsh・bash(Bashツール)既定で使えるPowerShellツール環境で決まる(下の節)

PowerShellがCLAUDE_ENV_FILEをどう扱うかは、後半の「セッションをまたいで環境変数を持ち越す方法」で触れます。APIのBashツールを探している場合は、Bashツールの実装解説が該当します。

Claude Codeがシェル起動ファイルを読み込む仕組み

セッションを開始すると、Claude Codeは使用しているシェルに応じて~/.zshrc・~/.bashrc・~/.profileのいずれかをソースします。読み込んだ結果として得られるエイリアス・関数・シェルオプションを、以降のBashツール呼び出しすべてに適用する仕組みです。

取り込みはセッション開始時の1回だけで、その結果をすべてのBashコマンドに適用します。毎回のコマンドで読み直すわけではないため、起動ファイルを途中で編集しても、取り込み直しは前提にできません。反映は次のセッションからと考えて設計します。自作CLIの補完を例にした確認手順はシェル補完の作り方にあります。

つまずきの大半は、Bashコマンドをまたいで残るものと消えるものを取り違えることです。Bashツールは各コマンドを別プロセスで実行します。

持ち越し

Bashコマンドをまたいで残るもの・消えるもの

  • 残る: エイリアスと関数

    起動ファイルで定義したものは、セッション開始時に取り込まれ、全コマンドで使えます。

  • 残る: cdの結果

    cdで移動した先は、プロジェクトのディレクトリか--add-dirで追加したディレクトリの内側なら次のコマンドにも引き継がれます。外へ出るとShell cwd was reset to <dir>が付いてプロジェクトに戻ります。

  • 消える: exportした環境変数

    あるコマンドでexport FOO=barしても、次のコマンドでは見えません。「さっき設定したのに効かない」の主因です。

cdの引き継ぎを止めたいときはCLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1を設定します。設定すると、Bashコマンドは毎回プロジェクトのディレクトリから始まります。

PowerShellツールではプロファイルが読み込まれない

PowerShellツールが使えるかどうかは、環境で決まります。WindowsでGit Bashが無ければ自動で有効になります。Git BashがあるWindowsでは、claude.aiとConsoleのアカウントなら既定で有効です。Amazon Bedrock・Google Cloud・Microsoft Foundry経由のセッションではCLAUDE_CODE_USE_POWERSHELL_TOOL=1が要ります。macOS・Linux・WSLでも同じ=1で使え、その場合はpwshがPATH上に必要です。

export CLAUDE_CODE_USE_POWERSHELL_TOOL=1

settings.jsonのenvキーで恒久化することもできます。

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"
  }
}

このPowerShellツールはプレビュー中で、PowerShellプロファイル($PROFILE)を読み込みません。zsh・bashが起動ファイルを自動でソースするのとは対照的です。$PROFILEで定義した関数やエイリアスは、Claude CodeのPowerShellコマンドからは見えないと考えて設計します。

実行ポリシーの扱いにも注意点があります。Claude CodeはPowerShellを-ExecutionPolicy Bypass付きで起動しますが、これはプロセス単位の指定にとどまり、グループポリシーのMachinePolicy/UserPolicyは上書きしません。マシンの実効ポリシーに従わせたい場合はCLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1を設定します。対話コマンド(!から始まる入力。キー操作はショートカット一覧にあります)を既定でPowerShellに通すには、settings.jsonのdefaultShellを"powershell"にします。

セッションをまたいで環境変数を持ち越す方法

venvやcondaのアクティベートはexportベースで環境変数を書き換えるため、起動ファイルの自動読み込みでは解決せず、Bashコマンドをまたぐと消えます。持ち越す経路は3つあります。

選び方

環境変数を持ち越す3つの経路

  1. 1

    起動前にアクティベートする

    Claude Codeを起動するシェルでvenvやcondaを有効にしておきます。最も単純で、セッション全体に効きます。

  2. 2

    CLAUDE_ENV_FILEを指定する

    起動前にexport文を書いたシェルスクリプトのパスをCLAUDE_ENV_FILEに設定します。その中身はBashコマンドの実行直前に同じシェルプロセスで毎回実行され、値がコマンドをまたいで持ち越されます。

  3. 3

    フックで動的に書き出す

    値がセッションの状況で変わるなら、フックがCLAUDE_ENV_FILEへ書き出します。

CLAUDE_ENV_FILEはSessionStart・Setup・CwdChanged・FileChangedの各フックからも動的に書き込めます。次はセッション開始時に環境変数を追記するフックの例です。

#!/bin/bash
 
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi
 
exit 0

PowerShellツールにも、Claude Code v2.1.296以降はCLAUDE_ENV_FILEの変数が渡ります。ただしPowerShellはこのファイルを実行しません。全行がexport NAME=valueのような単純な代入か空行・コメントのときだけ、値を環境へコピーします。上の例のexport PATH="$PATH:./node_modules/.bin"のように$PATHを含む行が1行でもあれば、PowerShellコマンドには1つも渡りません。Bashコマンドには全部渡ります。

Windowsでは、値に/か\を含む変数もPowerShellに渡りません。サンドボックス下のPowerShellコマンドには、一切渡りません。渡らないときはclaude --debugにSession environment is not all plain assignmentsと出ます。

追記(>>)を使っているのは、他のフックが書いた変数を上書きしないためです。nvmのようにコマンドを何本も実行して環境を作る場合は、実行前後のexport -pをcomm -13で突き合わせ、増えた分だけを書き出す形も使えます。

このスクリプトの書き出しは、Claude Codeを介さない素のbashで確認できます(v2.1.285のインストール環境で、モデルを呼ばずに実行)。

: > env.sh
CLAUDE_ENV_FILE=$PWD/env.sh bash hook.sh; echo "exit=$?"
cat env.sh
bash -c 'export FOO=bar'; bash -c 'echo "FOO=[${FOO}]"'
bash -c 'source ./env.sh; echo "NODE_ENV=${NODE_ENV}"'
exit=0
export NODE_ENV=production
export PATH="$PATH:./node_modules/.bin"
FOO=[]
NODE_ENV=production

FOO=[]は、別プロセスのexportが消える様子です。env.shを読み込んだ側ではNODE_ENVが見えます。CLAUDE_ENV_FILEが効く仕組みは、この動きを毎回のコマンド前に自動で行うものと考えると分かりやすくなります。

claude --helpには、--bareが「フック(settingsとプラグインで定義したもの)を飛ばす」最小モードと書かれています。フックでCLAUDE_ENV_FILEへ書く構成は、このモードではフックごと飛ぶため書き出しも行われない可能性があります。書き出しの有無は、フックを含めた構成で起動し、CLAUDE_ENV_FILEの中身を見れば確かめられます。ディレクトリを移動するたびに環境を切り替えたい場合はCwdChangedフックが使えます。cdのたびに発火するため、direnvのようなディレクトリ単位の環境管理と相性が良い仕組みです。ただしCwdChangedとFileChangedのフックがCLAUDE_ENV_FILEに書いた値は、次のCwdChangedで消去されます。

CI・自動化で環境を固定したい場合も、起動ファイルやプロファイルには頼らず、CLAUDE_ENV_FILEへフックから明示的に書くほうが再現しやすくなります。venvやcondaを例にした書き方はCLAUDE_ENV_FILEの解説にあります。

起動ファイルへの書き込みで確認プロンプトが出る理由

Claude Codeはv2.1.160で、.zshenv・.zlogin・.bash_loginなどのシェル起動ファイルと~/.config/git/への書き込み前に確認プロンプトを挟む変更を入れました。理由は明確で、起動ファイルは新しいシェルを開くたびに自動実行されるため、意図しない内容が混じると気づかないままコマンドが実行され続けるリスクがあるためです。

このプロンプトは個別の設定ではなく、Claude Codeが常に保護する「保護ファイル」の一部です。zsh・bash系の起動ファイルはまとめて対象に入っています。

保護対象具体例
bash起動ファイル具体例.bashrc .bash_profile .bash_login .bash_aliases .bash_logout
zsh起動ファイル具体例.zshrc .zprofile .zshenv .zlogin .zlogout
その他のシェル系具体例.profile .envrc
Git設定具体例.gitconfig .gitmodules(ディレクトリでは.config/git)
ビルド・パッケージ管理系具体例.npmrc .yarnrc bunfig.toml .bazelrc .pre-commit-config.yaml など
Claude Codeの設定具体例.mcp.json .claude.json .claude/(ディレクトリ)

これらへの書き込みは、権限モードによって扱いが変わります。

権限モード保護ファイルへの書き込み
default / acceptEdits保護ファイルへの書き込み確認プロンプトが出る
plan保護ファイルへの書き込みbypass permissionsが使える対話ターミナルなら許可。それ以外はauto modeが使えれば分類器、使えなければプロンプト
auto(auto mode)保護ファイルへの書き込み分類器の判定に回る(--restrictedで起動したセッションは、分類器も承認できない)
dontAsk保護ファイルへの書き込み拒否される
bypassPermissions保護ファイルへの書き込み無条件に許可

acceptEditsモードでも保護対象は自動承認されません。settings.jsonのpermissions.allowにルールを書いても、この保護チェックはallowルールの評価より先に走るため無効です。つまりEdit(.bashrc)のようなallowルールを足しても、default/acceptEditsではプロンプトが出続けます。なお、v2.1.160では同時に、acceptEditsが.npmrcや.pre-commit-config.yamlなど、コード実行につながるビルド系の設定ファイルの書き込み前にも確認を挟むようになりました。

この保護リストにPowerShellプロファイル($PROFILE)は含まれていません。もっとも、Claude CodeのPowerShellツール自体がプロファイルを読み込まない仕様なので、書き込んでも次回セッションの起動には影響しません。

Windows側のシェル設定はこれまでどう変わったか

WindowsのBashツールとPowerShellツールは、公式changelogを追うと段階的に整備されてきた経緯があります。過去の記憶のまま設定を触ると、現行版とずれることがあります。

あゆみ

WindowsのシェルまわりとClaude Codeの版

  1. v2.1.84PowerShellツールが登場

    オプトインのプレビューとして追加されました。

  2. v2.1.111Windowsで環境ファイルが有効に

    WindowsのCLAUDE_ENV_FILEとSessionStartフックの環境ファイルが、それまで何もしない状態から実際に効くようになりました。

  3. v2.1.120Git Bashが不要に

    Git Bashが無い環境では、PowerShellをシェルツールとして使います。

  4. v2.1.143実行ポリシーの既定が変わる

    PowerShellに-ExecutionPolicy Bypassを既定で付けるようになりました(戻す設定はCLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1)。同じ版で、Bedrock・Vertex・Foundryの利用者にWindowsで既定有効にもなりました。現行の公式docsは、Git BashがあるWindowsのBedrock等ではCLAUDE_CODE_USE_POWERSHELL_TOOL=1が要ると説明しているため、この点は版の変遷で記述が変わっています。

  5. v2.1.160起動ファイルへの書き込みに確認

    .zshenv・.zlogin・.bash_loginと~/.config/git/への書き込み前にプロンプトが出るようになりました。

特にv2.1.120以降は、Git Bashを入れていないWindows環境でもClaude Codeがそのまま動くようになった点が大きな変化です。Git Bashを前提にした古い手順を参照していると、今は不要な手間を踏むことになります。v2.1.269ではCLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHERが加わりました。バックグラウンドPowerShellコマンドを次プロセスへ引き継ぐcmd.exeランチャーを、これで無効化できます。

よくあるつまずき

  • 起動ファイルの編集依頼が毎回止まる: 都度承認するか、変更内容を先に見せてもらってから承認する運用にします。
  • PowerShellのエイリアスが効かない: 頻用する関数はプロジェクトのスクリプトに置き換えると、プロファイルに頼らず動きます。
  • WindowsでBashツールとPowerShellツールが両方動く状態になり挙動が読めない: Git Bash導入環境では、アカウントの種類(claude.ai・Console、またはBedrock等)でPowerShellツールの既定が分かれるため、どちらが使われるか意識が必要です。CLAUDE_CODE_USE_POWERSHELL_TOOLを明示的に0か1に固定すると挙動が安定します。
  • CLAUDE_ENV_FILEを編集したらBashコマンドが何も出力しなくなった: ファイルの末尾を#で始まるコメント行にすると、コマンドの標準出力が空になる不具合がv2.1.107以前にありました。v2.1.108で修正済みですが、古いバージョンを使っている場合はコメント行の位置を疑う価値があります。Windowsで.bashrcがあるとBashコマンドが実行できなくなる不具合も過去にありました(v2.1.27とv2.1.30で修正)。CLAUDE_ENV_FILE側の疑いが外れた場合はClaude CodeがWindowsでstdoutを取得できない原因と対処法も確認してください。

まとめ

PowerShellを使うなら、$PROFILEに置いた関数やエイリアスに頼らない構成にしておくのが前提です。起動ファイルの編集依頼で止まるのは保護ファイルの仕様で、権限モードごとの扱いはClaude Codeセキュリティ・権限ガイドで確認できます。環境変数とフックの組み合わせはClaude Code設定ガイド、フックの書き方はClaude Code Hooksの設定方法にまとめてあります。

参照した一次ソース

この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。

  1. code.claude.com/docs/en/tools-reference
  2. code.claude.com/docs/en/permission-modes
  3. code.claude.com/docs/en/hooks
  4. code.claude.com/docs/en/env-vars
  5. code.claude.com/docs/en/permissions
  6. code.claude.com/docs/en/changelog
この記事を共有:XはてブLinkedIn