PaseoでLinux上のCodexをMacから遠隔操作する（導入編：paseoコマンドが通らない時の対処法）

Linuxで動かしているCodexを、Macから操作したい。開発環境や依存ライブラリはLinuxに置いたまま、手元のMacは操作画面として使う。そんな構成を試すために、Paseoを導入してみました。

ところが、最初につまずいたのはリモート接続ではなく、Linux側の paseo コマンドでした。npmでのインストールは正常終了したのに、シェルからは「見つからない」と言われます。Macまでの道のりを考える前に、同じマシンの中でコマンドが迷子になっていました。

今回は、Paseoに期待していることと、導入時にどこまで確認できたかをまとめます。先に書いておくと、作業はコマンドの配置確認とPATHの修正方針を整理したところまでです。daemonの起動やMacからの接続は、これから試す段階です。

Paseoで「実行するマシン」と「操作する端末」を分けたい

Paseoは、CodexやClaude Codeなどのコーディングエージェントを、別のPCやスマートフォンから操作できるオープンソースのツールです。Paseo自体がAIモデルを提供するのではなく、既存のエージェントを起動・管理する役割を担います。

知ったきっかけは、Paseoを2か月ほど運用している方の体験談でした。特に惹かれたのが、エージェントの実行環境と操作端末を分けられる点です。

時間のかかる作業は常時起動のLinuxに任せ、Macやスマホから進捗を確認したり、必要な承認や追加指示を出したりする。これができれば、操作端末に開発環境一式を持ち歩かずに済みます。引っ越すのは操作画面だけで、依存ライブラリまで荷造りする必要はありません。

複数のエージェントをまとめて扱えることもPaseoの特徴ですが、今回はまずCodexをMacから操作するところに絞ります。目指している構成はこうです。

[ Mac ]
  └─ Paseo Desktop
       │
       ▼
[ Linux ]
  ├─ Paseo daemon
  └─ Codex CLI

MacにPaseo Desktopを入れるだけでは、Linux側のCodexは操作できません。接続先となるLinuxにもPaseoを入れ、daemonを動かす必要があります。

そこで、まずは普段Codexを動かしているLinuxの専用ユーザー、codex で作業を始めました。

Linux側の導入手順と、コマンドが見つからない原因の切り分け

1. npmでPaseo CLIをインストールする

Paseo CLIはnpmで配布されているので、次のコマンドを実行しました。

npm install -g @getpaseo/cli

結果は正常終了です。

added 37 packages, and changed 286 packages in 4s

途中で npm warn deprecated uuid@9.0.1 という警告は出ましたが、これは依存パッケージの非推奨警告です。少なくとも、今回のインストールを失敗させるものではありませんでした。

ここまでエラーがなければ、次はコマンドを呼び出して確認するだけ。のはずでした。

2. バージョンを確認すると、コマンドが見つからない

インストール後、次を実行しました。

paseo --version

返ってきたのはこちらです。

Command 'paseo' not found

npmでは成功しているのに、シェルからは見つからない。この時点では、パッケージが入っていないのか、コマンドへのリンクがないのか、検索先の問題なのかを分けて考える必要があります。

PATHの問題を疑いつつ、いきなり設定を変える前に、まずはnpmがどこへインストールしたのかを確認しました。

npm prefix -g
npm root -g
npm list -g @getpaseo/cli --depth=0

出力は次のとおりです。

/home/codex/.local/node-v24.11.0-linux-x64
/home/codex/.local/node-v24.11.0-linux-x64/lib/node_modules
/home/codex/.local/node-v24.11.0-linux-x64/lib
└── @getpaseo/cli@0.9.2

少なくとも、npm上では @getpaseo/cli@0.9.2 がインストールされています。ここにあるバージョンは、今回の作業で確認したものです。

3. 実行ファイルへのリンクを確認する

次に、グローバルインストール先の bin ディレクトリを確認しました。

ls -l "$(npm prefix -g)/bin/paseo"

確認できたリンクは次のとおりです。

/home/codex/.local/node-v24.11.0-linux-x64/bin/paseo
    -> ../lib/node_modules/@getpaseo/cli/bin/paseo

パッケージだけでなく、paseo を呼び出すためのシンボリックリンクも作成されていました。

ここまでで確認できたのは、「npmにはパッケージが登録されている」「想定した場所にコマンドへのリンクがある」「それでもシェルからは見つからない」という状態です。再インストールを繰り返すより、シェルがその場所を探しに行けているかを調べるほうが筋がよさそうです。

今回はNode.jsの配置先がポイントだった

今回の環境では、Node.jsをシステム共通の場所ではなく、次のユーザーディレクトリに配置していました。

/home/codex/.local/node-v24.11.0-linux-x64/

そのため、このnpmでグローバルインストールしたコマンドも、同じ配置先の bin ディレクトリに作成されています。

/home/codex/.local/node-v24.11.0-linux-x64/bin

シェルは、$PATH に登録されているディレクトリからコマンドを探します。ファイルが存在していても、その置き場所が検索対象に入っていなければ、名前だけでは呼び出せません。

npm install -g の「グローバル」は、シェルの検索範囲まで自動で広げてくれるという意味ではないわけです。

今回の出力からは、この bin ディレクトリが現在のシェルのPATHに含まれていない可能性が高いと考えています。ただ、記録として確認できているのは配置先とリンクの存在までで、PATH追加後にコマンドが動くところまでは検証していません。

次に試すのは、PATHの追加と再確認

Bashを使っている今回の環境では、次の設定を .bashrc に追記して読み込み直す方針です。以下はまだ実行後の動作を確認していない、次の作業です。

echo 'export PATH="$HOME/.local/node-v24.11.0-linux-x64/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

そのうえで、もう一度バージョンを確認します。

paseo --version

ここでバージョンが表示されれば、少なくとも現在のBashからPaseo CLIを呼び出せることが確認できます。まだ見つからない場合は、PATHの反映状況やリンク先を引き続き確認することになります。

同じ症状で調べる場合も、上のパスをそのままコピーするのではなく、自分の環境の npm prefix -g の結果を基準にするのがよさそうです。今回のパスにはNode.jsのバージョンも含まれているので、配置が変われば設定先も変わります。

Macからの接続は、Linux側の起動を確認してから

Linux側でPaseo CLIを呼び出せるようになり、daemonが起動したら、次はMac側を準備する予定です。

MacにはGUIクライアントのPaseo Desktopを導入します。予定しているインストールコマンドはこちらです。

brew install --cask paseo

接続はSSHを使う構成を考えています。

[ Mac ]
  └─ Paseo Desktop
       │ (SSH)
       ▼
[ Linux ]
  └─ Paseo daemon
       └─ Codex CLI

この接続方法や具体的な設定は、まだ今回の環境では確認していません。まずLinux側を起動できる状態にしてから、Macとの接続、Codexの操作へと順番に進めるつもりです。

接続できた後も、確認したいのは「画面が開くか」だけではありません。意図した作業ディレクトリでセッションを扱えるか、端末を切り替えた後も作業を続けられるかが、今回の目的に直結します。

参考資料には、利用者から再接続の遅延や、既存Codexセッションを取り込んだ際のワークスペースの紐づけに関する報告もありました。自分の環境で起きた問題ではありませんが、導入後に試す項目としては覚えておきたいところです。まずは検証用のプロジェクトで一連の操作を確かめてから、普段の作業へ広げようと考えています。

まとめ

今回確認できたのは、LinuxにPaseo CLIがインストールされ、実行用のリンクも作られているところまでです。paseo が見つからない症状については、独自の場所に配置したNode.jsの bin ディレクトリと、シェルのPATHの関係が有力な原因候補になりました。

コマンドが見つからないときは、まず npm prefix -g で配置先を調べ、その配下の bin にコマンドがあるかを確認する。今回はこの切り分けで、再インストールではなくPATHの確認へ進めました。

Paseoで実現したいのは、Linuxに実行環境を残したまま、Macから必要な操作だけを行うことです。まだ遠隔操作には届いていませんが、次に確認する場所ははっきりしました。まずはLinuxのシェルに paseo を見つけてもらうところから、続きを進めます。