2
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@K9i-0(K9i - Kota Hayashi)

Codex App ServerでスマホからCodexを操作しよう

2
Posted at

はじめに

最近、Codexを日常の開発で使う人がかなり増えてきた印象があります。

自分の観測範囲では、モデル性能、利用量、Codex Appの進化などを理由に、Claude CodeからCodexへ移行したり、併用し始めたりする人が増えています。背景については、以前こちらの記事にまとめました。

Claude CodeユーザーのためのCodex入門

CodexはローカルのターミナルやCodex Appで使うだけでも十分便利です。ただ、実際に長めのタスクを任せていると、途中で人間の判断が必要になる場面がよくあります。

  • コマンド実行の承認
  • ファイル編集の確認
  • Codexからの質問への回答
  • 生成されたdiffの確認
  • 途中で方向修正したいときの追加指示

PCの前にいるときは問題ありません。ただ、少し離席しただけでCodexが承認待ちで止まっていることがあります。

散歩中に進捗だけ見たい。ゲームのマッチング待ちやロード中に承認だけ返したい。ソファでだらっとしながら、Codexに「次これお願い」と投げたい。

そういう細かい隙間時間でCodexを止めずに進めたくて、Codexをスマホから操作するためのアプリ CC Pocket を作っています。

この記事では、まずCC Pocketの使い方を紹介し、そのあとで内部的に Codex App Server をどう使っているか、単にApp Serverを呼ぶだけでなくスマホで扱いやすくするために何をしているかを紹介します。

CC PocketでCodexをスマホから使う

CC Pocket は、CodexのセッションをiPhone、iPad、Android、macOSから操作するためのアプリです。

Codex自体は自分のMacやLinuxマシン上で動かし、スマホは操作画面として使います。

スマホ / macOS の CC Pocket
  <-> 自分のMac/Linux上の Bridge Server
  <-> Codex App Server
  <-> Codex

コードやgitリポジトリは、自分の開発マシン上に残ります。CC Pocketは、Bridge Server経由で codex app-server と通信し、スマホからCodexに指示を送ったり、承認したり、diffを確認したりするためのクライアントです。

CC Pocketの画面イメージ

導入手順

1. Codex CLIを使える状態にしておく

この記事はCodexユーザー向けなので、Codex CLI自体のインストール手順は省きます。

CC PocketはCodexの別実装ではありません。手元のCodex CLIを使います。開発マシン上で codex を起動でき、ログインや認証が済んでいる状態にしておいてください。

Codex CLIがChatGPTログインで使える状態なら、CC Pocket経由のCodex操作も基本的にはChatGPTサブスク側のCodex利用枠で動きます。Codex CLIをAPIキーで使っている場合は、その設定に従います。

2. Bridge Serverを起動する

同じマシンで、CC PocketのBridge Serverを起動します。

npx @ccpocket/bridge@latest

Bridge Serverは、自分のマシン上で codex app-server を起動し、スマホアプリとCodexの間を中継します。

起動すると、ターミナルにQRコードが表示されます。

3. CC Pocketをインストールする

スマホにCC Pocketをインストールします。

4. QRコードをスキャンして接続する

CC Pocketを開き、Bridge Serverが表示したQRコードをスキャンします。

同じWi-Fi内であれば、この手順だけで接続できることが多いです。接続できたら、プロジェクトを選び、Codexを選択してセッションを開始します。

外出先から使うならTailscale

同じWi-Fi内で使うだけなら、Bridge ServerのQRコード接続で十分です。

外出先からもスマホでCodexを操作したい場合は、Tailscale を使うのがおすすめです。

Tailscaleは、自分の端末同士を安全なプライベートネットワークでつなぐためのサービスです。ポート開放や固定IPを用意しなくても、Macとスマホを同じプライベートネットワークに参加させて接続できます。

詳しくは公式ドキュメントが分かりやすいです。

CC Pocketで使う場合の流れは次の通りです。

  1. Codexを動かすMacまたはLinuxマシンにTailscaleを入れる
  2. スマホにもTailscaleを入れる
  3. 両方を同じtailnetに参加させる
  4. Bridge Serverを起動して、表示されたQRコードをCC Pocketで読み取る

基本的にはTailscaleの場合もQRコード読み取りで接続できます。

うまく自動検出できない場合や、手動で接続先を指定したい場合だけ、CC Pocketから ws://<host-tailscale-ip>:8765 を入力します。

たとえばホストマシンのTailscale IPが 100.101.102.103 なら、次のように入力します。

ws://100.101.102.103:8765

これで、自宅やオフィスのMac上で動いているCodexを、外出先のスマホから操作できます。

常用する場合は、Bridge Serverをサービス化できます。

npx @ccpocket/bridge@latest setup

macOSではlaunchd、Linuxではsystemdを使って、Bridge Serverをバックグラウンドで起動できます。

また、CC Pocketには保存済みマシンに対してBridge Serverの起動、停止、更新を行う導線があります。setup で常駐化しておくと、普段はターミナルを開きっぱなしにせず、必要に応じてアプリ側からBridge Serverを更新しやすくなります。

CC PocketでのCodex App Serverの使い方

Codex App Serverは、Codexのリッチクライアントを作るためのインターフェースです。

CC PocketのBridge Serverでは、Codexセッションを開始するときに内部的に次のような形でCodex App Serverを起動します。

codex app-server --listen stdio://

Bridge Serverは、このApp ServerとJSON-RPCで通信します。

CC Pocket側で主に使っているのは、たとえば次のような機能です。

App Server側の役割 CC Pocketでの使い道
thread開始/再開 アプリからCodexセッションを開始・再開する
ストリーミングイベント Codexの出力や思考中の状態をチャットUIへ反映する
承認リクエスト コマンド実行やファイル変更をスマホの承認UIに変換する
会話履歴 Recent Sessionsやセッション復元に使う
モデル/設定情報 Codexのモデル、sandbox、approval policyなどのUIに反映する

重要なのは、CC PocketがCodexを再実装しているわけではないことです。Codexの実行や認証、会話管理はCodex CLI/App Server側に寄せ、CC Pocketは「モバイルで扱いやすい操作面」を作ることに集中しています。

スマホで使いやすくするためにやっていること

App Serverを使えばCodexのイベントや承認リクエストは取れます。ただ、スマホで本当に欲しいのは「今すぐ判断すべきこと」だけが分かる画面です。

CC Pocketでは、コマンド承認、ファイル変更、質問、diff確認をスマホ向けのUIに整理しています。たとえば散歩中に見るなら、長いログ全部ではなく「このコマンドを許可してよいか」がすぐ分かるほうが大事です。

もう1つ重要なのが、通信が不安定でも破綻しないことです。スマホではスリープ復帰、地下鉄、Tailscaleの再接続が普通に起きます。そこでBridge Serverを状態の正とし、アプリ側は直前のtimelineをキャッシュして、再接続後に差分で追いつくようにしています。

macOS版のCC Pocketは、もともとはサブマシンからメインの開発マシンを操作するために作り始めました。そこから完成度が上がってきて、今はスマホ版と組み合わせたCodex操作にもかなり向いています。

基本的には、スマホだけでもCodexに指示し、承認し、diffを見て、開発を進められるように作っています。その上で、Macの広い画面で作業したい場面もあります。

同じBridge Serverにつながっていれば、スマホとmacOS版を行き来できます。

  1. macOS版でCodexに大きめの実装を依頼する
  2. 席を離れる
  3. iPhoneで同じセッションを開いて続きを進める
  4. 戻ってきたらmacOS版でdiffを広い画面で確認する

スマホで完結してもいいし、必要なときだけMacに戻ってもいい。同じBridge Serverを中心にしておくと、その切り替えがかなりスムーズになります。

iPadやmacOSでセッション一覧とチャットを並べて使う画面

オフライン中に入力した内容も、雑に再送すると別端末からの入力と順序がぶつかる可能性があります。そのため、CC Pocketでは入力ごとにIDと履歴位置を持たせ、Bridge側で衝突を検出できるようにしています。失敗した入力は消さずに残し、編集して再送できるようにしています。

Claude Codeでも使える

この記事ではCodexを中心に紹介しましたが、CC PocketはClaude Codeにも対応しています。ただし、今回のApp Serverの話はCodex側の仕組みです。

注意点

  • Bridge Serverはプロジェクト、シェル、git、Codexにアクセスできる場所で動くので、インターネットに直接公開せず、Tailscaleなどを使うのがおすすめです。
  • CC PocketはCodexの操作画面なので、開発マシン上で codex が使える状態にしておく必要があります。
  • CC PocketはOpenAIやAnthropicの公式アプリではありません。

まとめ

Codex App Serverのおかげで、Codexのリッチクライアントを作りやすくなっています。ただ、スマホで使いやすくするには、承認UI、通信断への耐性、複数クライアントでの同期なども必要です。

まず試すだけなら、流れはシンプルです。

  1. 開発マシンでCodex CLIを使える状態にしておく
  2. npx @ccpocket/bridge@latest でBridge Serverを起動する
  3. スマホにCC Pocketを入れてQRコードで接続する
  4. 外出先から使うなら、MacとスマホをTailscaleに参加させた上で同じQRコード接続を使う

Codex App Serverで何か作ってみたい人にも、スマホからCodexを操作したい人にも、参考になればうれしいです。

リンク

2
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?