---
title: "SSH でリモートノードを操作する"
description: "OcHub Desktop から WSL、開発マシン、ヘッドレスサーバーの接続切り替えと Gateway 操作を行います。"
version: "ja"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ochub.org/ja/llms.txt
> Use this file to discover all available pages before exploring further.

# SSH でリモートノードを操作する

Remote Nodes を使うと、デスクトップ環境のないマシン上の OcHub 状態を 1 台の
OcHub Desktop から操作できます。リモート側に必要なのは OpenSSH だけです。
`ochcli` が未インストールなら、確認後に Desktop から SSH 経由で導入できます。
AI コーディングツール、設定、認証情報はリモート環境に残ります。

特に **WSL、Linux 開発マシン、リモートワークステーション**で便利です。API
エンドポイントを変えるたびに SSH ログインして設定ファイルを探す代わりに、OcHub で
対象マシンを選び、リモート側にすでに存在する接続へ切り替えられます。

## リモートノードを使う理由

実行環境と認証情報の境界を保ちながら、1 つの画面から操作できます。

- 開発マシン上の Claude Code、Codex、OpenCode などを手作業で編集せず切り替える。
- 接続前にオンライン状態、`ochcli` バージョン、プラットフォームを確認する。
- 適用前に、どのリモート設定が変更されるかをプレビューする。
- リモート OcHub Gateway の起動・停止と診断を行う。
- 既存の OpenSSH エイリアス、SSH Agent、ProxyJump、Keychain、ハードウェアキーを使う。

OcHub を閉じてもツールがローカルへ移動することはありません。切り替えは**選択した
リモートノード上**のネイティブ設定を書き換えるため、ツールはその後もリモートで動作します。

## 現在リモート管理できるもの

現在の Remote Nodes は次をサポートします。

| 領域 | リモートで利用できる機能 |
| --- | --- |
| ノード | 状態、ホスト名、OS、アーキテクチャ、Node ID、`ochcli` バージョン、Owner、アプリ |
| 接続 | 既存接続の一覧、現在値、切り替えプレビュー、適用 |
| Provider | 通常のアプリ画面で一覧、作成、編集、削除、複製、並べ替え、切り替え、診断 |
| MCP | 一覧、作成/編集、削除、アプリ別の有効化、インポート、同期 |
| Skills | 一覧、検索、検出、インストール、削除、更新、アプリ別の有効化、リポジトリ管理 |
| Usage | サマリー、トレンド、Provider/モデル集計、リクエスト詳細、同期、料金設定 |
| Sessions | 一覧、全文表示、メタデータ/本文検索、全文 index の構築・保守・削除、session 削除 |
| Network / Settings | remote proxy の表示・変更・test、app、backup policy、session index、data directory、cc-switch migration |
| Sync / Backup | WebDAV/S3 の設定・test・upload/download、backup 管理、remote path での SQL import/export |
| Tools / Update | remote CLI tool の確認・install・update、environment conflict、Claude/Codex/OpenClaw/Hermes の保守、node version の確認、direct download または desktop relay による署名済み OcHub update |
| Gateway / Station | Gateway の状態・起動停止・接続情報。Provider import、Station の作成・編集・probe・model discovery・remote app への適用 |
| 診断 | Doctor と SSH 診断 |
| 監査 | 最近のリモート操作記録 |

workspace selector は既存の product page 全体に作用します。database、tool config、
session、path、network request は選択中 node のものです。一方、desktop language、
tray/login、theme、「Finder で開く」などは意図的に操作側 computer に残ります。

OcHub は任意の Shell 実行や自動 Gateway tunnel を提供しません。古い node とは広告済み
capability の範囲で接続できますが、完全な workspace には新しい remote `ochcli` が必要です。
CLI がない場合や古い場合は理由を明示し、接続行から managed version を install / upgrade できます。

## 必要条件

次を準備してください。

- 操作側コンピューターに OcHub Desktop `0.4.22` 以降。
- 操作側で system `ssh` と `ssh-keyscan` が利用可能。
- リモート側で到達可能な OpenSSH Server が稼働。
- リモート user の home directory が書き込み可能であること。Desktop から managed
  `ochcli` を install するか、既存の manual installation を利用できます。
- 対話的なパスワード入力なしで成功する SSH key または Agent 認証。OcHub は
  `BatchMode=yes` を使用します。
- 接続を切り替える場合、リモート OcHub DB に少なくとも 1 つ Provider が存在。

操作側から、OcHub と同じ経路を先にテストします。

```sh
ssh -V
ssh -o BatchMode=yes devbox ochcli remote probe
```

`devbox` は SSH エイリアスに置き換えます。2 番目のコマンドはパスワードや
passphrase を要求せず、node、runtime、version、policy、capability を返す必要があります。

## リモートへ ochcli をインストールする

通常は事前に SSH login して install する必要はありません。後述の手順で SSH node を
追加し、「OcHub CLI がインストールされていません」と表示されたら **Install** を選びます。
OcHub は OS と CPU を検出し、Desktop 側で公式 executable を download・署名検証して、
host key 確認済み SSH 経由で upload します。`sudo` は使わず、current SSH user の directory
だけに書き込み、新しい port も開きません。完了後は Owner を起動し、実際の remote protocol
で version を確認して stable absolute path を保存します。

古い CLI、実行権限のない CLI、architecture が違う CLI では同じ action が **Upgrade** として
表示されます。Desktop が release を取得できない場合や platform が未対応の場合だけ、以下の
manual fallback を使ってください。

[最新リリース](https://github.com/OcHub-team/OcHub/releases/latest)からリモート環境用の
headless CLI archive をダウンロードします。実行ファイルは `ochcli` ひとつです。
Linux または WSL では managed node としてインストールします。

```sh
tar -xzf OcHub_*_linux_x86_64_cli.tar.gz
chmod +x ochcli
./ochcli node install

ochcli version
ochcli node status
ochcli remote probe
```

installer は user-owned directory に version を保持し、stable な `current` entry を
atomic に切り替え、`~/.local/bin/ochcli` を公開します。利用可能なら launchd または
systemd user service を登録します。systemd のない WSL では background owner を使い、
WSL restart 後は次の SSH session が再起動します。

非対話 SSH の `PATH` に `~/.local/bin` を含めてください。node 追加時に managed
`ochcli` の絶対 path を指定する方法も「ochcli not found」の確実な対処です。

ツールに既存の実設定がある場合は、接続前にリモート OcHub DB へインポートします。

```sh
ochcli app list
ochcli provider import-live --app codex
ochcli provider list --app codex
```

`codex` は対象 App ID に変更します。追加の接続を作成する場合は
`ochcli provider add --help` を使います。Secret はデスクトップ経由ではなく
リモートマシン上で入力してください。

2 つ目の daemon binary は不要です。同じ managed `ochcli` が persistent Owner を
実行し、通常の最初の Remote Nodes session が必要に応じて起動します。

## SSH 接続を準備する

**操作側コンピューター**の SSH config に具体的な alias を追加します。

```text
Host devbox
HostName 192.0.2.40
User alice
Port 22
IdentityFile ~/.ssh/id_ed25519
ServerAliveInterval 30
```

OcHub は `~/.ssh/config` とその `Include` を読みます。Windows では WSL 内の
`/home/<user>/.ssh/config` ではなく、`%USERPROFILE%\.ssh\config` です。具体的な
`Host` alias は追加ダイアログに表示されます。wildcard だけの block は既定値として
使われますが、独立したマシンとしては表示されません。

ProxyJump、SSH Agent、system keychain、ControlMaster、hardware key は system
OpenSSH が処理します。OcHub を開く前に次が成功することを確認してください。

```sh
ssh -o BatchMode=yes devbox ochcli remote probe
```

## ノードを追加して接続する

1. OcHub sidebar で **Remote nodes** を開きます。
2. **Add** を選びます。操作側の SSH config から具体的な alias が一覧になります。
3. alias を選んで **Add**、または左下の **Add manually** を選びます。
4. 手動追加では表示名、SSH target、key scan 用の実 hostname/IP、port、リモート
   `ochcli` path を入力します。
5. OcHub が `ssh-keyscan` を実行し、key type と SHA256 fingerprint を表示します。
   cloud console や管理者など信頼できる経路と照合します。
6. 一致した場合だけ **Trust and connect** を選びます。

承認した key は private permission の
`~/.ochub/ssh/known_hosts` に保存されます。通常の
`~/.ssh/known_hosts` も引き続き利用されます。OcHub が
`StrictHostKeyChecking=no` を暗黙に使うことはありません。

接続一覧には online 状態、`ochcli` version、platform、最終接続時刻が表示されます。
sidebar 上部の workspace selector で **This Mac** と保存済み remote node を切り替えます。

失敗は CLI 未インストール、node/Desktop の upgrade 必須、SSH authentication、host key
変更、timeout、system library 非互換などの分類で表示されます。**Details** には対処方法、
SSH exit code、raw diagnostics が表示され、長い生エラーは接続行に出ません。自動復旧できる
CLI 問題には **Install** または **Upgrade** も表示されます。

選択中 node が offline、SSH handshake timeout、または capability negotiation 失敗に
なった場合、各 page はその node の cache を直ちに消去し、remote write を無効にします。
OcHub が **This Mac で同じ操作を自動実行することはありません**。Provider、gateway、
settings、sync、tools、update を続ける前に node を再接続してください。

workspace 切り替え後、page 内の path は**選択中 node の path**です。Tools の
`/srv/backup/OcHub.sql`、Settings の data directory、sync/backup file は remote で
解決され、操作側の `HOME` は使いません。file picker、web/Finder を開く操作、
desktop preference は local のままです。

## リモートノードを 1 click で更新する

node が managed update capability を広告すると、接続行に `ochcli` version と update
action が表示されます。OcHub は node version と target platform を取得し、署名済み
`headless.json` release manifest を確認します。dialog では次を選べます。

- **Automatic**：node が対象 release asset へ到達できれば direct download、できなければ
  desktop relay。
- **Download on node**：remote node 自身が署名済み executable を download。
- **Relay through this computer**：Desktop が対象 binary を download・verify し、SSH
  経由で node へ stream。

relay でも desktop だけを信用しません。node が expected Node ID、target、byte count、
SHA-256、release signature を再検証します。どちらも stable `current` entry を atomic
に切り替え、Owner を restart して version を health check します。失敗時は previous
version を自動復元します。node 上で手動 rollback もできます。

```sh
ochcli --yes node rollback
```

update install は policy で既定有効です。無効にする場合は
`allowUpdateInstall = false` を設定して再接続してください。managed updater より前の node は接続行の **Upgrade** で最初の
managed install を実行できます。以後は direct/relay update dialog を使います。managed
install と self-update は現在 macOS と Linux（WSL を含む）をサポートします。

## リモートの Provider を切り替える

1. workspace selector または Remote Nodes 一覧から対象 node を選びます。
2. 接続後、変更するリモート App を選びます。
3. 既存 Provider の **Preview switch** を選びます。
4. target node、SSH alias、current provider、target provider、config path、revision を確認します。
5. **Apply change** を選びます。
6. refresh するか、リモートのツールから短い request を送り、新しい接続を確認します。

適用直前に revision がもう一度確認されます。preview 後にツールや別 process が設定を
変更した場合、最新状態を上書きせず apply が拒否されます。node を refresh し、
現在値を確認してから新しい preview を作成してください。

mutation には idempotency key と remote operation journal もあります。apply 中に
SSH が切断された場合は、再接続後に **Recent operations** を確認してから再試行します。
同じ write を盲目的に二重実行せず、保存済み結果を返せます。

## Gateway と診断を操作する

接続した node page には remote Gateway 状態が表示されます。起動するとリモート Owner
上で動作し、停止はその node だけに影響します。WSL や開発マシン上の AI tool が同じ
machine の loopback Gateway を使う構成に適しています。

SSH control session は Gateway を操作側へ自動公開しません。操作側からアクセスする
必要がある場合は、remote port を確認して別の明示的な tunnel を作成します。

```sh
ssh -N -L 8765:127.0.0.1:<remote-port> devbox
```

**Run diagnostics** は remote `ochcli doctor` と SSH session diagnostics をまとめます。
Recent operations は actor、time、operation ID、outcome を表示しますが、Provider
Secret をデスクトップへコピーしません。

## WSL の設定例

Windows 上の OcHub Desktop から WSL distribution を操作する場合：

1. WSL 内で OpenSSH Server をインストールして起動します。

```sh
   sudo apt update
   sudo apt install openssh-server
   sudo service ssh start
```

   systemd が有効なら最後の代わりに
   `sudo systemctl enable --now ssh` を使えます。

2. 前述の手順で WSL 内へ単一の `ochcli` を `ochcli node install` でインストールします。
3. Windows から WSL Linux user への key 認証を設定します。
4. alias を **Windows** の
   `%USERPROFILE%\.ssh\config` に追加します。

```text
   Host wsl-dev
   HostName 127.0.0.1
   User <your-wsl-user>
   Port 22
   IdentityFile ~/.ssh/id_ed25519
```

5. PowerShell でテストします。

```powershell
   ssh -o BatchMode=yes wsl-dev ochcli remote probe
```

6. OcHub の Remote Nodes dialog から `wsl-dev` を追加します。

Windows 側が port 22 を使用中なら WSL `sshd` を別 port にし、alias も合わせます。
WSL distribution または `sshd` が停止中なら node は offline になります。OcHub は
Windows OpenSSH を使い、`wsl.exe` を自動起動しません。

Claude Code や Codex は Linux path、credential、session、process を含めて WSL 内に
置いたまま、Provider の切り替えだけを desktop の 2 click で行えるようになります。

## セキュリティとリモートポリシー

Remote Nodes は HTTP/TCP の管理 listener を追加しません。SSH が transport encryption、
host authentication、user authentication を提供し、OcHub は SSH process の stdin/stdout
上で allowlist 済みの `ochcli remote serve --stdio` protocol を動かします。request は
typed operation であり、shell command string ではありません。

既定 policy は status、diagnostics、Provider switching（新しい secret を含む）、
Gateway lifecycle、update install を許可します。backup restore は無効です。
remote node で確認します。

```sh
ochcli remote policy show
ochcli remote policy validate
```

任意の policy file は `~/.ochub/remote.toml` です。read-only node の例：

```toml
schemaVersion = 1
enabled = true
allowWrite = false
allowGatewayLifecycle = false
allowBackupRestore = false
allowUpdateInstall = false
```

`enabled = false` で Remote Nodes session を拒否できます。通常の SSH account は Unix
user と同じ権限を持ちます。policy が強い認可境界になるのは SSH key を OcHub forced
command に制限した場合だけです。構成例と protocol の詳細は
[Remote Nodes design and security model](https://github.com/OcHub-team/OcHub/blob/main/docs/REMOTE-NODES-DESIGN.md)
を参照してください。

desktop から database restore または SQL/cc-switch import を行う場合は、
remote policy で backup restore を明示的に有効にします。update install は既定有効ですが、
設定に明示することもできます。

```toml
allowBackupRestore = true
allowUpdateInstall = true
```

desktop editor は暗号化 SSH session 経由で live secret を読み、local workspace と同じ
編集体験になります。変更していない mask placeholder は remote の元値を保持し、
`******` を書き戻しません。policy の変更は次の SSH control session から有効です。

## トラブルシューティングと現在の制限

| 症状 | 確認すること |
| --- | --- |
| Add に alias がない | 操作側 SSH config に具体的な `Host name` を置き、`Include` を確認するか Add manually を使う |
| Permission denied または prompt | key を SSH Agent へ追加し、`ssh -o BatchMode=yes <alias> ochcli remote probe` を成功させる |
| `ochcli: command not found` | 接続行の **Install** を選ぶ。または非対話 SSH の `PATH` に `~/.local/bin` を加えるか、絶対 path を指定する |
| Host Key が変わった | 停止し、信頼できる経路で新 fingerprint を確認してから `known_hosts` の旧記録を置き換える |
| WSL node が offline | distribution と `sshd` を起動し、Windows alias、localhost forwarding、port を確認する |
| 接続できるが Provider がない | remote で `ochcli provider import-live --app <app>` または Provider add を実行する |
| node version が古いと表示される | **Upgrade** で最初の managed install を実行する。以後の update は `allowUpdateInstall = false` でない限り有効 |
| desktop relay が選択された | node が対象 release asset へ到達できないため、Desktop が verify 後に SSH で安全に転送している |
| protocol/version error | Desktop と remote `ochcli` を更新して再接続する |
| Gateway が desktop から見えない | Gateway は remote 上にあるため remote tool を使うか、別の SSH tunnel を作成する |

OcHub から node を削除しても、消えるのは操作側の接続記録だけです。リモートの
Provider、tool config、`~/.ochub`、daemon、Gateway data は削除されません。

Source: https://docs.ochub.org/ja/guides/remote-nodes/index.mdx