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
claudeClaude Codeは初回起動でブラウザを開き、ローカルのコールバックサーバーでOAuthの結果を受け取ります。SSH先では、ブラウザがリモート側で開こうとして失敗するか、開けても手元のブラウザからリモートのコールバックサーバーへ戻る経路がありません。ブラウザ上ではサインインが済んでいるのに、ターミナルはログイン待ちのまま止まって見えます。
抜ける手順は次の流れです。
SSH先でログインを完了する
- 1
URLを手元のブラウザで開く
ブラウザが自動で開かない、または別のマシンで開いてしまう場合は、ログインプロンプトで
cキーを押します。OAuthのURLがクリップボードにコピーされるので、手元のマシンのブラウザに貼り付けます。URLが折り返されて狭いSSH端末でクリックできないときにも効きます。 - 2
表示されたログインコードをコピーする
サインインが終わると、リダイレクトされる代わりにブラウザにログインコードが出ます。ターミナルが進まないときは、まずこの画面にコードが出ていないかを確かめます。
- 3
プロンプトに貼り付ける
ターミナルの
Paste code here if promptedにコードを貼ります。 - 4
貼り付けが効かないとき
ターミナルソフトの別の貼り付けショートカット(Windows Terminalなら右クリックやShift+Insertが例に挙がっています)を試します。それでも反応しなければ
claude auth loginを実行します。このコマンドは貼り付けたコードを標準入力から読むので、対話プロンプトに貼り付けが届かない環境でも完了できます。
claude auth login には、SSH先でもそのまま使えるオプションがあります。v2.1.286の --help では次のとおりです。
claude auth login --helpOptions:
--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 flowClaude 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つあります。
ヘッドレスサーバーの認証手段
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 --textAuth token: claude.ai · not in use
API key: ANTHROPIC_API_KEY# CLAUDE_CODE_OAUTH_TOKEN だけを設定
CLAUDE_CODE_OAUTH_TOKEN=dummy claude auth status --textAuth token: CLAUDE_CODE_OAUTH_TOKEN# 両方を設定
ANTHROPIC_API_KEY=dummy CLAUDE_CODE_OAUTH_TOKEN=dummy claude auth status --textAuth token: CLAUDE_CODE_OAUTH_TOKEN · not in use
API key: ANTHROPIC_API_KEYAPIキーがあるとサブスクリプションのログインは 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-browserSSH接続中は、ローカルにブラウザが無いことをコマンドが検出し、認可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 で今効いている資格情報を確かめてください。
参照した一次ソース
この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。