Claude Media
Claude Code SSH接続ガイド — リモートサーバーでの認証と設定
Claude Codeチュートリアル

Claude Code SSH接続ガイド — リモートサーバーでの認証と設定

Claude DesktopのSSHセッション機能と、ターミナルからclaudeコマンドを直接使う場合の認証手順を、ヘッドレスサーバー向けのトークン発行まで含めて解説します。

読了目安 約13分

要点

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

この記事はDesktopのSSHセッション機能の設定から、ターミナル単体で認証を通す手順、ブラウザが一切使えないヘッドレスサーバー向けのトークン発行までを順番に扱います。

Claude DesktopのSSHセッション機能を使う

Claude DesktopのCodeタブは、セッションの実行環境としてLocal(手元のマシン)・Cloud(Anthropicのクラウド)に加えてSSHを選べます。SSHを選ぶと、あなたが管理するクラウドVMや自社サーバー、dev container上でClaude Codeを動かしつつ、インターフェースは手元のDesktopアプリのまま使えます。

接続を追加するには、セッション開始前の環境ドロップダウンで+ Add SSH connectionを選びます。ダイアログで入力するのは次の4項目です。

項目内容
Name内容接続の分かりやすい名前
SSH Host内容user@hostname、または ~/.ssh/config に定義したホスト名
SSH Port内容空欄なら22番、SSH設定にポート指定があればそれに従う
Identity File内容秘密鍵のパス(例: ~/.ssh/id_rsa)。空欄ならデフォルトの鍵かSSH設定を使う

追加した接続は環境ドロップダウンに表示され、選ぶだけでそのマシン上のセッションが始まります。リモートマシンはLinuxかmacOSである必要があり、初回接続時にDesktopがClaude Codeを自動でインストールします。接続後は権限モード・Connectors・Plugins・MCPサーバーがひととおり使えます。

個人用のSkillsだけは挙動が異なる点に注意してください。~/.claude/skills/ はローカルセッションでは手元のマシンのものが適用されますが、SSHセッションではリモートホストのホームディレクトリの ~/.claude/skills/ が読み込まれます。手元に置いたSkillsは自動では反映されません。

チームで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",
      "startDirectory": "~/projects"
    }
  ]
}

id / name / sshHost は必須、sshPort / sshIdentityFile / startDirectory は任意です。ユーザー自身が追加した接続も、保存先は同じ形式で自分の ~/.claude/settings.json に書き込まれます。

接続できるホストを制限したい場合は sshHostAllowlist をmanaged settingsに追加します。*.devboxes.example.com のようなワイルドカードパターンで許可範囲を指定でき、空配列にすればSSHセッション自体を無効化できます。この設定はDesktopアプリだけが読み、CLIやIDE拡張には効きません。Bashツールから実行する生の ssh コマンドも制限しないため、ネットワーク境界そのものを固めたい場合は組織のネットワーク制御と組み合わせます。

ターミナルから直接 claude を使う場合の認証

Desktopアプリを使わず、SSH接続先のターミナルで直接 claude コマンドを実行する運用も一般的です。この場合は実行そのものよりも初回ログインでつまずきます。

ssh user@remote-server
claude

Claude Codeは初回起動時にブラウザを開いてOAuthログインを行い、ローカルのコールバックサーバーが結果を受け取る仕組みです。SSH接続先で実行すると、ブラウザはリモート側で開こうとして失敗するか、開けてもそのブラウザからリモートマシンのコールバックサーバーへ戻る経路がありません。

結果として、ブラウザ上ではサインインが完了しているのに、ターミナル側はログイン待ちのまま止まって見えます。実際にはブラウザの画面にログインコードが表示されているはずなので、それを探します。ブラウザが自動で開かない、または違うマシンで表示されてしまう場合は、c キーを押してURLをクリップボードにコピーし、手元のローカルマシンのブラウザに貼り付けて開きます。サインインが終わるとブラウザの画面にログインコードが表示されるので、それをコピーしてターミナルの Paste code here if prompted プロンプトに貼り付けます。

貼り付け操作がプロンプトに反応しない場合は、ターミナルソフト側の代替ペーストショートカット(Windows Terminalなら右クリックやShift+Insertなど)を試します。それでも反応しないときは claude auth login を使います。このコマンドは標準入力からコードを読み込む形式なので、貼り付け操作がうまく届かない環境でも確実に完了できます。

claude auth login

ブラウザが一切開けないヘッドレスサーバー向けの認証

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

  1. ANTHROPIC_API_KEY を環境変数として設定する。Claude Consoleで発行したAPIキーを使う方法で、ブラウザ操作は一切不要です。非対話モード(-p フラグ)ではこのキーが常に優先して使われます
  2. claude setup-token で長期のOAuthトークンを発行する。Claude Pro / Max / Team / Enterpriseのサブスクリプションをそのまま使いたい場合の方法です。ただしこのコマンド自体はブラウザでの承認フローを要求するので、ブラウザが使えるローカル環境や踏み台サーバーで一度だけ実行し、出力された1年間有効なトークンを対象サーバーの CLAUDE_CODE_OAUTH_TOKEN として設定します
# ブラウザが使える環境で一度だけ実行
claude setup-token
 
# 出力されたトークンをヘッドレスサーバー側で設定
export CLAUDE_CODE_OAUTH_TOKEN=your-token

claude setup-token で発行したトークンはモデルへのリクエストにしか使えません。Remote Controlセッションの確立やclaude.aiコネクタの取得はできない点に注意してください。また、起動を高速化する --bare モードはこのトークンを読まないため、--bare を使うスクリプトでは ANTHROPIC_API_KEY か apiKeyHelper に切り替える必要があります。

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

Claude Code本体のログインとは別に、個々のMCPサーバーがOAuth認証を要求することがあります。/mcp パネルを開かずCLIから完結させたい場合は claude mcp login に --no-browser を付けます(v2.1.186以降で利用できます)。

claude mcp login sentry --no-browser

ブラウザを開く代わりに認可URLをそのまま表示するので、ローカルのブラウザで開いてリダイレクト先のURLをコピーし、プロンプトに貼り付けます。MCPサーバーごとの認証の仕組みはリモートMCPのOAuth認証で詳しく扱っています。

接続の切断と設定の置き場所に注意する

ターミナルで直接 claude を使う運用で見落としやすいのが、環境変数や設定ファイルをどちらのマシンに置くかです。ANTHROPIC_API_KEY やプロキシ設定をSSHの接続元(手元のマシン)のシェルに設定しても、Claude Codeが実際に動くのはリモート側のプロセスなので反映されません。設定は必ずSSH先のシェルプロファイルか、リモート側の settings.json に置きます。

社内プロキシを経由してしかインターネットに出られないリモートサーバーでは、HTTPS_PROXY や NO_PROXY もリモート側で設定します。Claude Codeは標準的なプロキシ環境変数に従いますが、SOCKSプロキシには対応していません。到達させる必要があるのは主に api.anthropic.com(推論・認証)と claude.ai / platform.claude.com(OAuthログイン)です。

SSH接続そのものが切れた場合、ターミナルで直接動かしていた対話セッションは中断されます。長時間の作業を切断に強くしたいなら、Claude Code自体の機能ではなく tmux や screen でセッションを維持し、その中で claude を起動しておくのが実務上の定番です。SSHを切って再接続しても、tmux attach で同じ会話に戻れます。Desktopアプリ経由のSSHセッションであれば、接続が切れても会話履歴はDesktop側のセッションとして残ります。

SSH越しでのコピー&ペーストと画像の扱い(ターミナル運用の場合)

ターミナルで直接使っている場合、認証以外にも細かい癖があります。tmuxの中でSSH接続している場合、/copy やマウス選択によるコピーがローカルのクリップボードまで届かないことがあります。届かないときは /copy で w キーを押すと、選択範囲をクリップボード経由ではなく直接ファイルに書き出せるので、ローカル側で scp して確認する運用に切り替えられます。

画像をリモートセッションに渡したいときも同様で、SSH越しのクリップボード貼り付けはそもそも届きません。画像は scp でリモートサーバーに転送してから、ファイルパスを @ 参照で渡す方法が確実です。

ターミナル側の見え方に違和感が出たときは、まずSSH経由であること自体が原因になっていないかを切り分けます。ローカル実行では起きない表示や入力の細かい不具合が、SSH越しやtmux併用という組み合わせに固有の症状として過去に報告されてきた経緯があり、公式のリリースノートでも個別に修正が続いています。最新版へのアップデートで直っている可能性があるので、claude update を試してから他の原因を疑うと切り分けが早くなります。

Desktop SSH・ターミナルSSH・Remote Control・self-hosted環境の使い分け

毎回SSHで入って claude を起動する運用が面倒に感じたら、目的次第で他の手段も検討できます。

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

ターミナルでの手動運用は準備がいちばん簡単ですが、切断への弱さと認証のやり直しが手間になりやすい構成です。GUIでの差分レビューやファイル添付を活かしたいならDesktopのSSHセッション、頻繁に同じサーバーへ入り直すならRemote Controlやself-hosted環境への移行も検討する価値があります。クラウドセッションを自社ネットワーク内で完結させたい組織規模の要件なら、Claude Code self-hosted-runnerとはが扱うself-hosted環境のほうが適しています。

よくあるつまずき

  • ブラウザでサインインしたのにターミナルが進まない: ブラウザの画面に表示されたログインコードを見落としています。それをコピーして Paste code here if prompted に貼り付けます
  • コードを貼り付けても反応しない: ターミナルのペースト設定がプロンプトに届いていません。ターミナル側の代替ペーストショートカットを試すか、標準入力からの貼り付けに対応した claude auth login を使います
  • 設定したはずの環境変数が効かない: 接続元のマシンに設定していないか確認します。Claude Codeが動くのはSSH先のマシンなので、設定もそちらに置きます
  • --bare で起動したらログインが要求される: --bare は CLAUDE_CODE_OAUTH_TOKEN を読みません。ANTHROPIC_API_KEY に切り替えます
  • SSHが切れるたびに会話が消える: ターミナル運用で tmux や screen の中で claude を起動しておらず、SSHセッションと一緒に対話セッションも終了しています
  • DesktopのSSHセッションで自作Skillsが効かない: 個人Skillsはリモートホストの ~/.claude/skills/ から読み込まれます。手元のマシンに置いただけでは反映されません
  • DesktopでSSH接続先を選べない: 組織が sshHostAllowlist を設定している場合、許可パターンに一致しないホストは選択肢に出ません。管理者にホストの追加を依頼します

まとめ

Desktopアプリを使うなら、SSHセッション機能でホスト情報を登録するだけでGUIごとリモート開発に切り替えられます。ターミナルだけで完結させたい場合につまずくのはほぼ認証だけで、「ブラウザのコードをターミナルに貼る」手順を覚えておけば解決します。ブラウザが一切使えないヘッドレスサーバーでは ANTHROPIC_API_KEY か、ローカルで発行した長期OAuthトークンのどちらかに倒してください。

よくある質問

Desktopアプリが無くても、SSH越しにClaude Codeを使えますか

使えます。SSH接続先のターミナルで直接 claude コマンドを実行するだけです。Desktopアプリのウィンドウが必要なのはGUIでの差分レビューやConnectors・Pluginsの操作パネルを使いたいときで、CLI単体でも認証も含めて完結します。

SSH先でも claude mcp login の --no-browser は使えますか

使えます(v2.1.186以降)。ブラウザを開く代わりに認可URLを表示するので、ローカルのブラウザで開いてリダイレクト先のURLを貼り付ける流れで完了します。Claude Code本体のログインとは別に、MCPサーバーごとの認証で使うオプションです。

claude setup-token はSSH先のサーバーでそのまま実行できますか

ブラウザでの承認が必要なため、ヘッドレスなSSH先だけでは完結しません。ブラウザが使えるローカル環境や踏み台マシンで一度実行してトークンを取り出し、対象のサーバーには発行済みのトークンを環境変数として設定する運用にします。

プロキシ配下のSSHサーバーでも動きますか

動きます。HTTPS_PROXY などの標準的なプロキシ環境変数を、接続元ではなくSSH先のマシンで設定してください。SOCKSプロキシは非対応です。

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

関連する記事

Claude Code をもっと見る →