PaseoでClaude CodeとCodexをスマホから遠隔操作する：MacセットアップとAndroidペアリングの落とし穴

2026年7月、GitHub スター 1 万超のオープンソース Paseo が話題になった（2026年8月16日時点では約 1.4 万）。

原文: "Orchestrate coding agents from your desk and your phone"
日本語訳: 「デスクでもスマホでも、コーディングエージェントを指揮する」（公式サイト）

つまり CLI 型コーディング AI（Claude Code / Codex / Cursor エージェント等）を一つの司令塔から遠隔監視・指示できる、という位置づけだ。

本稿は Mac セットアップと、Android ネイティブアプリのペアリングで実際に詰まった原因を、一次情報と手元検証（Paseo 0.1.105、2026-07-10 リリース）に基づいて整理する。2026年8月16日時点の GitHub / Homebrew cask 最新は 0.4.0。手順の骨格は同じだが、CLI の正式コマンド名とリレー既定値が変わっている箇所は本文で注記する。

結論

確認項目	Paseoの位置づけ	今日やること
何を解決するか	CLI 型コーディングエージェントを「1つの司令塔」から遠隔監視・指示	Mac にデスクトップ版＋デーモンを入れ、プロジェクトを1つ登録する
リモート接続	公式リレー（relay.paseo.sh）経由。同一 Wi‑Fi は不要。新規インストールではリレーがオフ	paseo daemon pair --relay で有効化してからペアリング
スマホ連携	QR またはペアリング URL。Web 版（app.paseo.sh）も使える	URL は先頭から末尾まで全文を貼る。途中切れはタイムアウトの原因
Cursor 連携	IDE 丸ごとではなく、ACP 経由の Cursor エージェント	デスク作業は Cursor IDE、外出先監視は Paseo、と役割分担する

Paseo は Cursor や VS Code の代替ではない。「エージェント実行 OS」 として足すと相性がよい。

Paseoとは：デスクとスマホをつなぐ「エージェント司令塔」

上のスクリーンショットが Paseo の全体像だ。

左の Sessions で複数リポジトリを横断し、中央の Orchestrator でエージェントにタスクを分解・実行させ、下段の Terminal で npm run dev などを確認し、右の Changes で差分をレビューする——この4面が1画面に収まる。

Mac / Web / iOS / Android / CLI から同じワークスペースにアクセスできる設計で、対応エージェントは Claude Code・Codex・Cursor・Gemini CLI など 30 以上（公式 agents 一覧、2026年8月16日確認）。

アーキテクチャは次の3層に分かれる（公式サイト / GitHub より）。

• ホスト Mac（または Linux）: デスクトップアプリ＋ローカルデーモン（既定 127.0.0.1:6767）
• リレー: 暗号化 WebSocket（wss://relay.paseo.sh）。メタデータのみ中継側が把握し、コード本文は暗号化される設計
• クライアント: iOS / Android ネイティブアプリ、Web（app.paseo.sh）、CLI（paseo コマンド）

対応エージェントは Claude Code、Codex、Copilot、OpenCode など CLI 型が中心。
Cursor は ACP（Agent Client Protocol） 経由でエージェントとして追加できる。

ライセンスは AGPL-3.0。セルフホストも可能だが、多くのユーザーは公式リレーを使う想定だ。

Mac セットアップ（検証環境: 0.1.105）

今日 brew install --cask paseo すると 0.4.0 が入る（2026年8月16日、Homebrew cask 確認）。以下の画面ログは 0.1.105 のものだ。

インストール

Homebrew cask が手早い。

brew install --cask paseo

初回はアプリを起動すればデーモンが立ち上がる（Getting started）。0.1.105 では paseo onboard も動いたが、現行 CLI リファレンスには載っていない。

デーモン状態の確認

paseo daemon status

0.1.105 の検証では paseo status でも同じ系統の出力を得た。現行ドキュメントの正式名は paseo daemon status だ。

正常時はおおよそ次のように表示される（0.1.105 検証ログより）。

Local Daemon      running
Connected Daemon  reachable
Listen            127.0.0.1:6767
Relay             wss://relay.paseo.sh:443

running かつ reachable でなければ、ペアリング前にここを直す。

Mac 版 Paseo の設定で「終了後もデーモンを動かす」を有効にしておくと、外出先からの再接続が安定しやすい。

プロジェクト登録

1. Paseo を開く
2. 「プロジェクトを追加」→ リポジトリのディレクトリパスを入力
3. ワークスペースを作成 → エージェント（Claude / Codex / Cursor 等）を選択
4. チャットで指示 → 背後で CLI エージェントが動作

CLI からエージェント一覧・起動も可能。

paseo ls
paseo run "READMEの誤字を直して"

スマホペアリング：QR と URL 貼り付け

記事冒頭のイメージ図のとおり、Paseo の本質は Mac 上のデーモンとスマホをリレー（relay.paseo.sh）で暗号化接続する ことだ。

ペアリングが通れば、外出先からエージェントの進捗確認・追加指示・ターミナル閲覧が可能になる。

Mac 側：ペアリング QR を出す

GUI（0.1.105 / 日本語 UI）: 歯車 → 接続 → デバイスをペアリング
現行ドキュメント: Settings → 対象ホスト → Pair Device（Getting started）

CLI:

paseo daemon pair

新規インストールではリレーがオフのため、QR が出ない／RELAY_DISABLED になることがある（CLI ドキュメント）。その場合は次で明示的に有効化する。

paseo daemon pair --relay

ターミナルに QR と、次の形式の URL が表示される。

https://app.paseo.sh/#offer=<base64トークン>

QR は短時間で無効になることがある。 デーモン再起動後は必ず新しい QR を出し直す。

スマホ側：推奨手順

1. Paseo アプリ内の「QRコードをスキャン」を使う（OS 標準カメラだけだと Web に飛ぶだけの場合がある）
2. スキャン後 10〜20 秒待つ（すぐアプリを閉じない）
3. 左上メニューにホスト名（例: YushinoMacBook-Pro.local）が出れば成功

URL 貼り付けを使う場合

Android アプリの「ペアリングリンクを貼り付け」でも接続できる。ここが最大の落とし穴だ。

NG（末尾だけ）:

iFzZW8uc2g6NDQzliwidXNIVGxzljp0cnVlfX0

OK（https:// から全文）:

https://app.paseo.sh/#offer=eyJ2IjoyLCJzZXJ2ZXJJZCI6InNydl9...（省略）...InVlfX0

貼り付け欄の先頭が https://app.paseo.sh/#offer=eyJ になっているか必ず確認する。
途中切れだと Android 側で Connection timed out になりやすい（手元検証）。

ブラウザは開けるのにアプリだけ失敗する理由

経路	挙動
Chrome 等でペアリング URL を開く	Web 版 Paseo が起動 → リレー経由で接続
Android ネイティブに URL を貼る	アプリがトークンを解析してネイティブセッションを確立

ブラウザで問題なく開けるのは正常。
ネイティブアプリは完全な offer トークンが必要だ。

ネイティブが不安定なときの回避策: スマホの Chrome で https://app.paseo.sh/#offer=... を開き、Web 版で Mac 上のエージェントを操作する。外出先からの監視・指示だけなら実用上十分な場合が多い。

Cursor を Paseo で使うとき

Paseo 上の Cursor は Cursor IDE そのものではなく、Cursor エージェント（ACP） だ。

ツール	役割
Cursor IDE	デスクでのコーディング（従来通り）
Paseo	エージェントの遠隔監視・追加指示・ターミナル確認

Mac 側の ~/.paseo/config.json では、Cursor プロバイダが次のように定義される（検証環境）。

"cursor": {
  "extends": "acp",
  "command": ["cursor-agent", "acp"]
}

ワークスペース作成時に Cursor が一覧に出ない場合は、cursor-agent acp が PATH 上で動くかを先に確認する。

実装チェックリスト

Mac ホスト

• brew install --cask paseo 後、paseo daemon status で Daemon running を確認
• リレーがオフなら paseo daemon pair --relay で有効化
• 使うリポジトリをプロジェクトとして1つ登録
• Claude Code / Codex が Providers に available と出るか確認
• ペアリング前に Mac をスリープさせない（蓋を閉めない）

スマホ連携

• paseo daemon pair（必要なら --relay）で新しい QR を出す
• Paseo アプリ内スキャナを使う（標準カメラだけに頼らない）
• URL 貼り付け時は https://app.paseo.sh/#offer= から末尾まで全文
• VPN / プライベート DNS を一時オフして再試行
• Android は Paseo のバッテリー最適化を無効化

運用

• デスク = Cursor IDE、外出先 = Paseo、と役割を分ける
• ネイティブが詰まったら Web 版 app.paseo.sh で代替

失敗パターン

パターン1: ペアリング URL を途中で切って貼る
→ 対策: ターミナルの paseo daemon pair 出力を Google Keep 等経由でスマホに送り、1文字も欠けず貼る。先頭の https:// を確認。

パターン2: QR スキャン後すぐアプリを閉じる
→ 対策: スキャン後20秒ほど前面で待つ。Mac ログではリレー接続後15秒以内に握手（hello）が来ないと Closing connection due to missing hello となるケースがある（手元検証）。

パターン3: デーモン再起動後に古い QR を使う
→ 対策: 必ず QR を出し直す。再起動前の offer は無効。

パターン4: ブラウザは動くがネイティブだけタイムアウト
→ 対策: まず Web 版で運用を開始。ネイティブはアプリ更新・バッテリー設定・VPN オフを確認してから再ペアリング。

パターン5: Cursor IDE と Paseo の Cursor を混同する
→ 対策: Paseo 上は ACP エージェント。IDE の代替ではない。

パターン6: 新規インストールでリレーがオフのままペアリングする
→ 対策: 現行 CLI は新規インストールのリレー既定をオフにしている。paseo daemon pair --relay で同意してから QR / offer URL を出す。

参考リンク

• Paseo 公式
• Paseo GitHub（getpaseo/paseo）
• Paseo Getting started
• Paseo CLI
• Paseo 対応エージェント一覧
• Paseo Web クライアント
• GIGAZINE: Paseo レビュー（2026-07-05）
• Paseo - Remote Coding Agents（App Store）
• Paseo - Claude Code & Codex（Google Play）

この記事を書いた人✏️@YushiYamamoto
ITPRODX.com代表 / AIアーキテクト
Next.js / TypeScript / n8nを活用した自律型アーキテクチャ設計を専門としています。
日々の自動化の検証結果や、ビジネス側の視点（ROI等）に関するより深い考察は、以下の公式サイトおよびnoteで発信しています。