# プロキシ経由のSSHアクセス
SUMMARY: LLMエージェントが生のSSH鍵ではなくSSHプロキシAPIを通じてリモートマシン上で安全にコマンドを実行する方法。

KEY CONTEXT:
LLMとして生のSSH秘密鍵を決して保持しない。SSHプロキシHTTP APIを使う：
1) POST /connect?target=<name> → session_id（永続、数時間生存）。
2) POST /<session_id>/exec {command, timeout} → exec_id。
3) GET /<session_id>/exec/<exec_id> → 完了時に出力。
4) ファイルのアップ/ダウンロードはcat/heredocではなくSFTPエンドポイントを使う。
ターゲットは事前登録された名前（例："vps1"）で、IPではない。資格情報が
生きるのはプロキシだけ。

プロキシ経由のSSHアクセス
エージェントはリモートマシンでコマンドを実行する必要があります — コンテナをデプロイ、ログを読む、設定を直す。生のSSH秘密鍵をLLMに渡すのは悪い考えです：鍵はコンテキストウィンドウ、ログ、トランスクリプトに入り込んでしまいます。SSHプロキシはこれを解決します：資格情報を保持するのはプロキシで、エージェントはHTTPだけを話します。
モデル
[CODE BLOCK]
プロキシはシンプルなRESTサーフェスで永続セッションを公開します：
| エンドポイント | 目的 |
|---|---|
|  | セッションを開く →  |
|   | コマンドを実行（非同期）→  |
|  | 出力をポーリング |
| SFTPエンドポイント | ファイルのアップ/ダウンロード、、、 |
認証はBearerトークンです — 使っている他のすべてのAPIと同じパターンです。
実行パターン
[CODE BLOCK]
運用規則
1. セッションを再利用する。 コマンドごとに接続すると資源を浪費し、レート制限に触れます。を保存し（例：）、再利用前にハートビートさせましょう。
2. ターゲットを名前で呼び、発見しない。 ターゲットは事前登録済みです（、…）。プロキシが唯一の信頼源です — エージェントコードにIPアドレスをハードコードしてはいけません。
3. ファイルにはシェルのcat/heredocよりSFTPを優先する。 を通じたバイナリデータのエスケープはペイロードを壊します。専用のアップ/ダウンロードエンドポイントを使いましょう。
4. コマンドをクォートする。 JSONボディは2回パースされます（HTTP + シェル）。リモートコマンドはシングルクォートで包み、1行に保ちましょう。
5. 監査を前提とする。 すべてのexecはプロキシの監査ログに残ります — 人間がすべて読むつもりで振る舞いましょう（実際に読めます）。
execを使うべきでないとき
- APIを持つ構造化された状態を読むとき（Docker、データベース、SynapseのMind API）— CLI出力の解析より常にAPIを優先します。
- 長時間の対話的プロセス。はタイムアウト付きのfire-and-forgetです。代わりにターゲット上で + 状態ファイルを使いましょう。
- 明示的な指示のない破壊的な操作すべて。プロキシが力を与えます — 許可を与えるのは人間です。
エラー回復
| 症状 | 修正 |
|---|---|
| connectで401 | トークン失効 — memory/settingsから読み直す。トランスクリプトからは絶対に |
| セッション404 | セッション失効（24h上限）— 再接続 |
| execタイムアウト | を上げるかコマンドを分割；ターゲットの負荷を確認 |
| ファイル内容の破損 | SFTPの代わりにを使った — SFTPエンドポイントに切り替え |