Claude Media
Claude CodeをSSH接続で使う方法 — Desktopとターミナルの設定と認証

Claude CodeをSSH接続で使う方法 — Desktopとターミナルの設定と認証

Claude CodeをSSH接続で使う2つの方法を紹介します。DesktopのSSHセッションの設定、リモート側の要件、ターミナル直接実行のログインとヘッドレス向けトークン発行まで扱います。

要点

Claude CodeをSSH越しのリモートサーバーで使う方法は2つあります。Claude DesktopアプリのSSHセッション機能は、ダイアログにホスト情報を入れるだけで、リモートにClaude Codeが自動でインストールされます。ターミナルだけで済ませたい場合は、SSH接続先で直接 claude を実行しますが、初回ログインでブラウザのコールバックが届かない問題に当たります。

この記事は、Desktopの設定、ターミナル単体での認証、ブラウザが使えないサーバーでのトークン発行の順に進みます。後半では、SSH先で認証がどの資格情報に決まるかを、v2.1.286の claude auth status の出力で確かめます。

Claude DesktopのSSHセッションで入る

Claude DesktopのCodeタブでは、セッションの実行環境にLocal(手元のマシン)・Cloud(Anthropicのクラウド)・SSHを選べます。SSHを選ぶと、自分で管理するクラウドVMや自社サーバー、dev containerでClaude Codeが動きます。画面は手元のDesktopアプリのままです。

接続を追加するには、セッション開始前に環境セレクタの下部にあるNew environmentを開き、SSHタブのHostリストでAdd SSH connection…を選びます。入力する項目は次の5つです。

項目内容
Name内容接続の分かりやすい名前
SSH Host内容user@hostname、または ~/.ssh/config に定義したホスト名
SSH Port内容空欄なら22番、SSH設定にポート指定があればそれに従う
SSH key(任意)内容秘密鍵のパス(例: ~/.ssh/id_ed25519)。空欄ならSSH設定かSSHエージェントを使う
Worktree folder内容新しいセッションがworktreeを作るリモート側のフォルダ(例: ~/worktrees)。空欄ならリモートの既定

接続を追加したら、リモート側のフォルダを選んでCreate environmentを押します。接続とフォルダは保存済みの環境として残り、次回からはそこを選ぶだけで始められます。リモートマシンはLinux・macOS・Windowsのいずれかで、初回接続時にDesktopがClaude Codeを自動でインストールします。接続後は権限モード・Connectors・Plugins・MCPサーバーを使えます。

つながらないときにリモート側で確かめること

ログイン後に接続が失敗するなら、リモートがLinuxかmacOSの場合、次の条件を満たしているかを見ます。リモートがWindowsなら、Desktop v2.31226.0以降とMicrosoftのOpenSSH Serverが要ります。SSHサーバーが起動するシェルは cmd.exe・Windows PowerShell 5.1・Git Bashのいずれかです。

  • SFTP: SSHサーバーがSFTPサブシステムを提供している必要があります。手元のターミナルから同じホストへ sftp で入り、sftp> のプロンプトが出れば問題ありません
  • インストール先: DesktopはホームディレクトリのClaude Code用フォルダ(~/.claude/remote/)にヘルパーとClaude Codeを置いて実行します。noexec でマウントされたファイルシステムは使えず、ユーザーごとに1GB程度の空きが要ります
  • シェル: アカウントのシェルが、SSH経由で送られるコマンドを実行できること(Bash・Zsh・sh なら問題ありません)
  • MaxSessions 1: sshd_config が MaxSessions 1 のサーバーには、macOS・Linuxの手元ならDesktop v3.1623.0以降で接続できます。Windowsの手元ではDesktopがOpenSSHクライアント経由で接続する設定にします
  • ネットワーク: Claude Codeはリモート側から通信するため、リモートマシンから必要なホストへ出られる必要があります。Linuxで社内プロキシやCA証明書が要るときは、シェルのプロファイルではなくリモートの ~/.claude/settings.json の env に書きます

SSHセッションには、ローカルと違う点がいくつかあります。

  • 個人用のSkillsは、手元ではなくリモートホストの ~/.claude/skills/ から読み込まれます。手元に置いたSkillsは自動では反映されません
  • 「Claude Code on the Web」への引き継ぎ(ローカルセッションをクラウドで続ける機能)は、SSHセッションでは使えません
  • ファイルペインとサイドチャットは、ローカルと同じようにSSHセッションでも使えます。サイドチャットはアプリが保存しないので、アプリを終了すると戻れません

Windows版のクライアントからSSHセッションを使う場合は、SSHバイナリのパス解決に起因する接続失敗が報告されています。エラーが出たら参照してください。

チームでSSH接続を配布・制限する

管理者は sshConfigs をmanaged settingsに追加して、チームメンバーの環境ドロップダウンに接続先を自動配布できます。配られた接続はmanaged扱いになり、ユーザーは選べても編集・削除はできません。

{
  "sshConfigs": [
    {
      "id": "shared-dev-vm",
      "name": "Shared Dev VM",
      "sshHost": "user@dev.example.com",
      "sshPort": 22,
      "sshIdentityFile": "~/.ssh/id_ed25519"
    }
  ]
}

id / name / sshHost は必須で、sshPort / sshIdentityFile は任意です。ユーザーがダイアログで追加した接続も、同じ形式で自分の ~/.claude/settings.json に保存されます。

接続先を絞りたいときは、sshHostAllowlist をmanaged settingsに追加します。設定の詳細はsshHostAllowlistの記事にあります。ここでは、運用で効く仕様だけ押さえます。

  • 照合は ~/.ssh/config を解決した後のホスト名に対して行われます。内部では ssh -G で解決するので、Host の別名や ProxyJump、ProxyCommand を使っていても、解決後の HostName が許可パターンに合えば通ります
  • パターンは大文字小文字を区別せず、*.example.com は example.com 自体とサブドメインの両方に一致します
  • * は全ホストに一致し、*.example.com 形式以外のパターンは完全一致です。空配列にするとSSHセッション自体が無効になります
  • 値を読むのはmanaged settingsだけで、ユーザー設定やプロジェクト設定に書いても無視されます

この設定を読むのはDesktopアプリだけです。CLIやIDE拡張は読まず、Bashツールから実行する生の ssh コマンドも制限しません。接続できるホストを絞るだけで、ネットワークの出口を塞ぐ設定ではないため、強い境界が必要なら組織のネットワーク制御と組み合わせます。

SSH先で直接 claude を使うとログインが止まる

Desktopを使わず、SSH接続先のターミナルで直接 claude を実行する運用もあります。この場合は、実行よりも初回ログインでつまずきます。

ssh user@remote-server
claude

Claude Codeは初回起動でブラウザを開き、ローカルのコールバックサーバーでOAuthの結果を受け取ります。SSH先では、ブラウザがリモート側で開こうとして失敗するか、開けても手元のブラウザからリモートのコールバックサーバーへ戻る経路がありません。ブラウザ上ではサインインが済んでいるのに、ターミナルはログイン待ちのまま止まって見えます。

抜ける手順は次の流れです。

手順

SSH先でログインを完了する

  1. 1

    URLを手元のブラウザで開く

    ブラウザが自動で開かない、または別のマシンで開いてしまう場合は、ログインプロンプトで c キーを押します。OAuthのURLがクリップボードにコピーされるので、手元のマシンのブラウザに貼り付けます。URLが折り返されて狭いSSH端末でクリックできないときにも効きます。

  2. 2

    表示されたログインコードをコピーする

    サインインが終わると、リダイレクトされる代わりにブラウザにログインコードが出ます。ターミナルが進まないときは、まずこの画面にコードが出ていないかを確かめます。

  3. 3

    プロンプトに貼り付ける

    ターミナルの Paste code here if prompted にコードを貼ります。

  4. 4

    貼り付けが効かないとき

    ターミナルソフトの別の貼り付けショートカット(Windows Terminalなら右クリックやShift+Insertが例に挙がっています)を試します。それでも反応しなければ claude auth login を実行します。このコマンドは貼り付けたコードを標準入力から読むので、対話プロンプトに貼り付けが届かない環境でも完了できます。

claude auth login には、SSH先でもそのまま使えるオプションがあります。v2.1.286の --help では次のとおりです。

claude auth login --help
Options:
  --claudeai       Use Claude subscription (default)
  --console        Use Anthropic Console (API usage billing) instead of Claude
                   subscription
  --email <email>  Pre-populate email address on the login page
  --sso            Force SSO login flow

Claude Consoleのアカウントで入りたいときは --console を付けます。この場合の課金はサブスクリプションではなく、APIの従量課金です。組織がSSOを求めるなら --sso で強制できます。

なお、リモートがmacOSのときは別の落とし穴があります。macOSではログインがKeychainに保存されますが、SSHセッションではKeychainがロックされていて書き込みを拒否されることがあります。その場合、Claude Codeはログインを ~/.claude/.credentials.json(ファイルモード0600)に保存します。Linuxと同じ保存先で、暗号化されない平文です。Consoleログインで作るAPIキーは、Keychainに書けるようになるまで失敗します。claude doctor を実行すると、書き込めないときは macOS Keychain is not writable で始まる警告が出ます。

ブラウザが開けないサーバーでは何を使うか

CI専用サーバーや、ディスプレイもブラウザも無いヘッドレスなLinuxホストでは、対話的なOAuthログインを毎回行うのは現実的ではありません。選択肢は2つあります。

2択

ヘッドレスサーバーの認証手段

  • APIキー(ANTHROPIC_API_KEY)

    Claude Consoleで発行したキーを環境変数に設定します。ブラウザ操作は要りません。課金はAPIの従量課金で、非対話モード(-p)ではキーがあれば常に使われます。

  • 長期トークン(CLAUDE_CODE_OAUTH_TOKEN)

    Pro / Max / Team / Enterpriseのサブスクリプションをそのまま使う方法です。claude setup-token は承認にブラウザを使うので、ブラウザのあるマシンで一度だけ実行します。出力された1年有効のトークンを、対象サーバーに設定します。

トークンは claude setup-token が画面に出すだけで、どこにも保存されません。コピーして、使いたいマシンの環境変数に自分で設定します。

# ブラウザが使える環境で一度だけ実行
claude setup-token
 
# 出力されたトークンをヘッドレスサーバー側で設定
export CLAUDE_CODE_OAUTH_TOKEN=your-token

このトークンは、モデルへのリクエストにしか使えません。Remote Controlセッションの確立と、claude.aiコネクタの取得はできません。ローカルで設定したMCPサーバーは使えます。また、起動を速くする --bare モードはこのトークンを読みません。--bare を使うスクリプトでは、ANTHROPIC_API_KEY か apiKeyHelper に切り替えます。

SSH先で実際にどの資格情報が使われるか

APIキーとトークンとログインが同じマシンに混在すると、どれが選ばれるかが分かりにくくなります。公式の優先順位は7段あります。SSH運用に関わる部分は、上から ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY、apiKeyHelper です。続いて CLAUDE_CODE_OAUTH_TOKEN、/login のサブスクリプションの順です。v2.1.286の claude auth status --text で、環境変数をダミー値にして確かめました。サブスクリプションでログイン済みのマシンで実行し、モデルは呼んでいません。

# ANTHROPIC_API_KEY だけを設定
ANTHROPIC_API_KEY=dummy claude auth status --text
Auth token: claude.ai · not in use
API key: ANTHROPIC_API_KEY
# CLAUDE_CODE_OAUTH_TOKEN だけを設定
CLAUDE_CODE_OAUTH_TOKEN=dummy claude auth status --text
Auth token: CLAUDE_CODE_OAUTH_TOKEN
# 両方を設定
ANTHROPIC_API_KEY=dummy CLAUDE_CODE_OAUTH_TOKEN=dummy claude auth status --text
Auth token: CLAUDE_CODE_OAUTH_TOKEN · not in use
API key: ANTHROPIC_API_KEY

APIキーがあるとサブスクリプションのログインは not in use になり、両方あるとトークンも not in use です。公式の優先順位と同じ並びです。SSH先のシェルプロファイルに古いAPIキーが残っていると、サブスクリプションの枠ではなくAPI課金の側で動く可能性があります。対話モードではAPIキーの使用を一度確認するプロンプトが出ますが、-p では存在するだけで使われます。SSH先で認証の挙動が想定と違うときは、まず claude auth status --text を実行します。

MCPサーバーだけをSSH越しに認証する

Claude Code本体のログインとは別に、個々のMCPサーバーがOAuth認証を要求することがあります。/mcp パネルを開かずにCLIから済ませるには、claude mcp login に --no-browser を付けます。v2.1.186以降で使え、v2.1.286の --help には次の説明があります。

--no-browser  Print the authorization URL instead of opening a browser (for
              SSH/headless sessions — paste the redirect URL back when
              prompted)
claude mcp login sentry --no-browser

SSH接続中は、ローカルにブラウザが無いことをコマンドが検出し、認可URLの表示に切り替わります。--no-browser を付けると、ブラウザがある環境でもURL表示を強制できます。手元のブラウザで開いて承認し、リダイレクト先のURLをプロンプトに貼り付けて完了です。貼り付けには対話端末が要るので、ssh -t で接続します。ssh host claude mcp login ... のようにコマンド付きで入ると、貼り付けで詰まります。v2.1.202では、SSH越しで折り返したURLが1本のハイパーリンクとして出力されるように直っています。MCPサーバーごとの認証の仕組みはリモートMCPのOAuth認証で扱っています。

設定の置き場所・プロキシ・切断

ターミナルで直接使う運用で見落としやすいのは、環境変数や設定ファイルをどちらのマシンに置くかです。VS Code拡張をSSH接続先のウィンドウで使う場合も同じで、証明書ファイルの保存と ~/.claude/settings.json の編集は、手元ではなく接続先のマシンで行います。

くらべる

環境変数をどこに置くか

効かない

接続元(手元のマシン)

ANTHROPIC_API_KEY やプロキシ設定を、手元のシェルに書いても反映されません。Claude Codeが動くのはSSH先のプロセスで、手元の環境変数は引き継がれないためです。

効く

SSH先

SSH先のシェルプロファイルか、リモート側の settings.json に置きます。HTTPS_PROXY や NO_PROXY も同じです。ただしDesktopから開くSSHセッションはプロファイルの変数を受け取らないため、settings.json の env に書きます(DesktopのSSHセッションでプロキシと社内CAを通す設定)。

プロキシ経由でしか外に出られないサーバーでは、HTTPS_PROXY を設定します。標準的なプロキシ環境変数には従いますが、SOCKSプロキシには対応していません。許可リストに入れるホストは、認証と推論だけなら api.anthropic.com、claude.ai、claude.com、platform.claude.com です。ネイティブインストーラと自動更新は downloads.claude.ai を使い、claude.aiのコネクタは mcp-proxy.anthropic.com を経由します。npmでインストールするなら、さらに registry.npmjs.org が要ります。

SSH接続が切れると、ターミナルで直接動かしていた対話セッションは中断されます。長時間の作業には、Claude Code自体の機能ではなく tmux や screen を使います。セッションを維持したまま claude を起動しておけば、再接続して tmux attach で同じ会話に戻れます。

Remote Controlも同じです。Remote Controlは claude を起動したマシン上のプロセスで動くため、SSH先で起動して切断すると、セッションはオフラインになります。公式にも、切断後に残すなら tmux か screen の中で起動するよう書かれています。

コピーと画像をSSH越しで扱う

認証のほかにも、ターミナル運用には癖があります。tmuxの中でSSH接続していると、/copy やマウス選択がローカルのクリップボードまで届かないことがあります。/copy のピッカーで w を押すと、選択範囲をクリップボードではなくファイルに書き出せます。/copy の説明に「SSH越しで便利」と書かれている機能です。ローカルへは scp で取ってきます。

画像も同様に、SSH越しのクリップボード貼り付けは届きません。画像は scp でサーバーに送り、ファイルパスを @ で参照させる方法が確実です。

表示や入力の違和感が出たときは、SSH経由やtmux併用が原因になっていないかを先に切り分けます。ローカルでは起きない症状がSSH越しに限って報告され、リリースごとに個別に直されてきました。まず claude update で最新版にして、他の原因はそれから疑います。

4つの入り方をどう選ぶか

毎回SSHで入って claude を起動する運用が面倒なら、目的別に別の手段があります。

手段実行場所向く用途
DesktopのSSHセッション実行場所接続先のリモートサーバー向く用途GUIで差分レビューやConnectors・Pluginsも使いながら開発したいとき
ターミナルで直接 claude実行場所接続先のリモートサーバー向く用途既存サーバーに入って手早く作業したいとき、GUIが不要なとき
Remote Control実行場所claude を起動したマシン(SSH先でも可)向く用途外出先のスマートフォンやブラウザから同じセッションを続けたいとき
self-hosted環境実行場所自社インフラのrunner向く用途claude.aiから始めたクラウドセッションを、自社ネットワーク内に閉じたい組織

ターミナルでの手動運用は準備が最も簡単です。反面、切断への弱さと認証のやり直しが手間になります。Desktopなら差分レビューやファイル添付を活かせます。クラウドセッションを自社ネットワーク内で完結させたい組織の要件には、Claude Code self-hosted-runnerとはが扱うself-hosted環境が合います。

症状から原因を探す

  • ブラウザでサインインしたのにターミナルが進まない: ブラウザに出たログインコードを確認します。コピーして Paste code here if prompted に貼ります
  • 貼り付けても反応しない: 貼り付けがプロンプトに届いていません。claude auth login に切り替えます
  • 設定したはずの環境変数が効かない: 接続元に設定していないか確認します。設定はSSH先に置きます
  • --bare で起動すると認証が通らない: --bare は CLAUDE_CODE_OAUTH_TOKEN を読みません。ANTHROPIC_API_KEY に切り替えます
  • SSHが切れるたびに会話が消える: tmux や screen の外で claude を起動しています
  • claude.aiコネクタやRemote Controlだけが使えない: claude setup-token のトークンで動いていると、この2つは使えません。claude auth login でclaude.aiのログインに切り替えます。メッセージに ANTHROPIC_API_KEY や ANTHROPIC_AUTH_TOKEN が出るなら、シェル環境か settings.json の env から外します
  • DesktopでSSH接続先を選べない: 組織が sshHostAllowlist を設定していて、許可パターンに合わないホストには接続できません。管理者にホストの追加を頼みます

まとめ

GUIでの差分レビューが要るならDesktopのSSHセッション、手早く入るだけならターミナル直接、と目的で決まります。ターミナルで詰まるのは、ほぼ認証だけです。ブラウザが無いサーバーでは、サブスクリプションの枠を使うならトークン、APIの従量課金でよければAPIキーを選び、迷ったら claude auth status --text で今効いている資格情報を確かめてください。

参照した一次ソース

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

  1. code.claude.com/docs/en/desktop
  2. code.claude.com/docs/en/troubleshoot-install
  3. code.claude.com/docs/en/authentication
  4. code.claude.com/docs/en/network-config
  5. code.claude.com/docs/en/remote-control
  6. code.claude.com/docs/en/cli-reference
  7. code.claude.com/docs/en/commands
  8. code.claude.com/docs/en/vs-code
この記事を共有:XはてブLinkedIn