Claude Media
Claude Code Desktopで環境変数を設定する手順とexportが効かないとき
Claude CodeTips

Claude Code Desktopで環境変数を設定する手順とexportが効かないとき

Desktopでは、環境変数の置き場が保存済みローカル環境、ローカル環境エディタ、settings.jsonの3つに分かれます。zshrcのexportが効かない切り分けと、上書きできない変数もまとめます。

読了目安 約9分

Claude Code Desktopで環境変数を渡す場所は3つあります。保存済みのローカル環境、歯車アイコンから開くローカル環境エディタ、~/.claude/settings.jsonのenvキーです。届く先がそれぞれ違うため、置き場所を間違えると「設定したのに効かない」状態になります。

~/.zshrcにexportしたのに値が届かないときは、新しいセッション、Desktopの再起動、保存済み環境に古い値が残っていないか、の順で確かめます。詳しい切り分けは後半の節にあります。

変数を置ける3つの場所と、届く範囲

置き場所ごとに、届く先が違います。

置き場所ローカルセッションプレビューの開発サーバー備考
保存済みローカル環境ローカルセッションその環境から始めたセッションだけプレビューの開発サーバー届かない備考最新のレイアウトで使える
ローカル環境エディタローカルセッション届く(Desktopが自分で設定する変数を除く)プレビューの開発サーバーDesktopの再起動後に届く備考暗号化して手元に保存される
~/.claude/settings.jsonのenvローカルセッションすべてのローカルセッションプレビューの開発サーバー届かない備考起動環境に同名の変数があると無視される

開発サーバーには、保存済みローカル環境の変数もsettings.jsonのenvも届きません。開発サーバーに渡す変数は、ローカル環境エディタかシェルの環境変数に置くことになります。

保存済みローカル環境に変数を入れる

特定のプロジェクトだけに渡したい変数は、保存済みローカル環境に入れるのが基本です。

手順

保存済みローカル環境で変数を設定する

  1. 1

    環境のフォームを開く

    新規に作るなら、環境セレクタのメニュー下部にある「New environment」を選び、「Local」タブへ進みます。すでにある環境を直すなら、「Local」の下の保存済み環境にカーソルを合わせ、歯車アイコンから「Edit environment」を開きます。

  2. 2

    変数を書く

    「Environment variables」を選び、1行に1つKEY=valueの形で入力して「Done」を押します。

  3. 3

    環境を保存する

    「Create environment」または「Save」を押します。

その環境から始めたセッションだけが、この変数を受け取ります。別の環境や、環境を選ばずに始めたセッションには届きません。

たとえば拡張思考を切りたいときは、MAX_THINKING_TOKENS=0をここに書きます。ドキュメントによると、Anthropic APIでは思考がオフになります。ただしOpus 5.5、Sonnet 5.5、Haiku 5.5、Fableの各モデルは常に拡張思考を使うため、この変数では止まりません。

セレクタがプロンプト欄の上にある場合は、保存済みローカル環境のない旧レイアウトです。次の節のエディタを使います。見分け方は「レイアウトで使える機能が変わる」の節にあります。

ローカル環境エディタで全ローカルセッションに渡す

環境を選ばずに、手元のすべてのローカルセッションへ変数を渡したいなら、ローカル環境エディタを使います。開くのは、保存済み環境ではなく自分のコンピューターの項目にある歯車です。

  • プロンプト欄の下にセレクタがある場合: 「Local」の下の最初の項目(自分のコンピューター)にカーソルを合わせ、歯車アイコンが出たら押します
  • プロンプト欄の上にセレクタがある場合: 「Local」にカーソルを合わせて歯車アイコンを押します

下側のセレクタで歯車が出ないときは、エディタが使えない状態です。ローカルセッション向けなら保存済みローカル環境かsettings.json、開発サーバー向けなら次の節の方法で渡します。

エディタでも1行に1つKEY=valueと書き、「Save changes」で保存します。保存した変数は暗号化されて手元のマシンに置かれます。

ここで保存した変数は開発サーバーにも渡せますが、Desktopを再起動するまでは届きません。

settings.jsonのenvは「先に入っていた変数」に負ける

すべてのローカルセッションに渡す方法はもう1つ、~/.claude/settings.jsonのenvキーです。

{
  "env": {
    "MY_SERVICE_URL": "https://example.internal"
  }
}

ただし、Desktopがセッションを起動する時点の環境にその変数がすでにあると、envの値は無視されます。Desktopが組み立てる起動環境のほうが優先されるためです。どの変数が無視されたかは、デバッグログに名前が出ます。

仕組みの全体はClaude Code設定ガイドにあります。envに書いた値はプレーンテキストでファイルに残るので、秘密の値はエディタか保存済み環境に入れるほうが安全です。

上書きできない変数がある

API_TIMEOUT_MSやANTHROPIC_BASE_URLを設定しても何も変わらないとき、原因はDesktopがこれらを自分で設定していることです。

Desktopが自分で設定する変数は、シェルプロファイル、Windowsのユーザー・システム環境変数、ローカル環境エディタ、保存済み環境のどこに書いても、ローカルセッションではDesktopの値が使われます。settings.jsonのenvに移しても、先ほどの優先順位で無視されます。

  • API_TIMEOUT_MS: ローカルセッションには900000(15分)が入ります。もっと長くしたいなら、Claude Code CLIを入れ、シェルで変数を設定して端末からclaudeを動かします
  • ANTHROPIC_BASE_URL: Claudeアカウントでサインインしていると、AnthropicのAPIホストが入ります。ゲートウェイを使うなら、Desktopのサードパーティ推論の設定を使います

ドキュメントは「ほかにもある」と書いていますが、一覧は載せていません。上の2つ以外の変数が反映されないときは、先に述べたデバッグログで無視された変数名を確かめるのが近道です。

次の変数は専用の手順がある

変数によっては、保存済み環境へ入れる以外の手順が決まっています。

変数・対象手順
PATH手順通常のターミナルでコマンドが動くか確かめ、シェルプロファイルのPATH設定を見てDesktopを再起動する。WindowsではDesktopがPowerShellプロファイルを読まないため、ユーザーまたはシステムの環境変数にPATHを設定して再起動する
claude_desktop_config.jsonのMCPサーバー用の変数手順Desktopを終了し、そのサーバーのenvブロックに書いて開き直す
CLAUDE_CONFIG_DIR、CLAUDE_CODE_TMPDIR手順開発サーバー向けの置き場(次の節)のいずれかに設定し、Desktopを終了して開き直す

PATHが通らない症状はClaude Code Desktopのトラブルシューティングにも出てきます。

開発サーバーに秘密を渡す

プレビューの開発サーバーに秘密の値を渡したいときは、launch.jsonのenvに書かないでください。このファイルはリポジトリにコミットされるためです。代わりに次のどれかに置き、Desktopを再起動します。

  • macOSとLinux: シェルプロファイルでexportする
  • Windows: ユーザーまたはシステムの環境変数に追加する
  • どのOSでも: ローカル環境エディタに保存する(開けるなら)

保存済み環境や~/.claude/settings.jsonに入れた変数は、開発サーバーには渡りません。

exportが効かない原因を切り分ける

対象はmacOSとLinuxで、~/.zshrcや~/.bashrcにexportした変数がClaudeの実行するコマンドに届かない、または値が違う場合です。

Claudeに確認させるときは、値そのものを出さずに有無だけ見るのが安全です。

bash で test -n "$MY_VAR" && echo set || echo unset を実行して

ここでunsetなら、下の問いを上から順に試します。

切り分け

exportした値が届かないときの切り分け

  1. Q新しいセッションで同じコマンドを試したか?
    答えがいいえのとき

    新しいセッションを始め、同じコマンドを実行させます。

    答えがはい
  2. QDesktopを終了して開き直したか?
    答えがいいえのとき

    Desktopを終了し、開き直してから新しいセッションを始めます。

    答えがはい
  3. Q同じ変数を保存済み環境やエディタにも入れていないか?
    答えがいいえ(入れている)

    保存した側の値で届いています。値を直し、新しいセッションを始めます。

    答えがはい

保存済みローカル環境に移す

変数を保存済みローカル環境に入れ、その環境から新しいセッションを始めます。

3つ目の問いは見落としやすい箇所です。シェルでは正しい値をexportしていても、エディタや保存済み環境に古い値が残っていると、そちらが使われてしまいます。値が「ない」のではなく「違う」ときは、先にここを疑います。

PATH、CLAUDE_CONFIG_DIR、API_TIMEOUT_MSは、保存済み環境に移す手順の対象外です。前の節で見た、それぞれ専用の手順に従います。

バージョンが古いと、exportは届かない

v2.1.304より前のClaude Codeは、exportした変数をコマンドに渡しません。上の手順を尽くしても届かないなら、セッションが動かしているバージョンを確かめます。

/status

ローカルセッションで/statusを実行し、「Claude Code」の行を読みます。Codeタブのローカルセッションは、端末のclaudeとは別のコピーを動かします。Desktopが更新を管理するので、バージョン番号も別です。更新は、macOSなら「Claude > Check for Updates…」、Windowsなら「Help > Check for Updates…」から行い、そのあと新しいセッションを始めます。

レイアウトで使える機能が変わる

保存済みローカル環境が使えるかどうかは、画面のレイアウトで決まります。新しいセッションで、プロンプト欄の下に環境セレクタがあれば現行のレイアウトです。ない場合は旧レイアウトで、次のいずれかが原因です。

  • Desktopがv2.37337.0より古い
  • サードパーティプロバイダーで、セッションが自分のコンピューターで動いている。この場合、現行のレイアウトにはClaude Desktop v3.1623.0以降が必要
  • サードパーティプロバイダーで、セッションが組織のインフラで動いている。この場合は更新しても旧レイアウトのまま

旧レイアウトでは、保存済みのローカル環境もSSH環境も作れません。変数はローカル環境エディタに入れます。組織が自動更新を止めていると「Check for Updates…」自体が隠れるので、管理者にバージョンを確認します。

置き場所の選び方

  • 特定のプロジェクトだけに渡す: 保存済みローカル環境
  • 手元のすべてのローカルセッションに渡す: ローカル環境エディタ。settings.jsonのenvは、同名の変数が起動環境にないときだけ効く
  • 開発サーバーに秘密を渡す: シェルプロファイル、Windowsの環境変数、またはエディタ。保存後はDesktopを再起動する
  • direnvの.envrcをClaudeのコマンドに渡したい: Desktopの設定ではなくフックで渡す。direnvの設定記事に手順がある

exportが効かない症状の多くは、「どの経路で変数が届くか」の取り違えから来ます。シェルのexportは起動時に読まれる経路、エディタと保存済み環境はDesktopが管理する経路、と分けて考えると、どこを直せばよいかが見えてきます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →