herdrでSSH越しにCodexを使うとコピペできない問題の直し方｜OSC 52でクライアント側にコピーする

はじめに

herdr は、AIコーディングエージェント向けのターミナルワークスペースです。herdr --remote <SSH先> で、別のマシンで動いているherdrのセッションに手元から接続できます。

この構成でOpenAIのCodex CLIを使っていたところ、Codexでコピーしたはずのテキストを手元のMacで貼り付けられない問題が起きました。「コピーしました」と表示されるのに、手元のクリップボードは空のままです。

この記事では、原因と直し方を順に説明します。

対象読者

• herdrの --remote で、SSH先のマシンでCodexを動かしている方
• tmuxやzellijなどのマルチプレクサ越しに、CLIツールのコピーが効かなくて困っている方

結論

Codexが動いている側、つまりSSH先のマシンの ~/.zshrc に次を追加します。

# herdrのペインではOSC 52でコピーさせる
if [[ -n "$HERDR_PANE_ID" && -z "$SSH_CONNECTION" ]]; then
  export SSH_CONNECTION="herdr-remote"
fi

# herdrのペインではOSC 52でコピーさせる
if [[ -n "$HERDR_PANE_ID" && -z "$SSH_CONNECTION" ]]; then
  export SSH_CONNECTION="herdr-remote"
fi

新しいペインを開いてCodexを起動し直すと、Codexでコピーした内容が手元のクリップボードに入るようになります。

「SSH先」と「手元」がどちらか紛らわしいので、表にしておきます。

何が起きていたのか

Codexがコピー先を選ぶ仕組み

Codexのコピーには、大きく2つの方法があります。

OSC 52は、「このテキストをクリップボードに入れて」と端末アプリに頼むための仕組みです。SSHの向こう側のプログラムからでも、手元の端末アプリのクリップボードに書き込めます。

Codexは、環境変数 SSH_TTY または SSH_CONNECTION があるかどうかで、SSH越しかを判断しています。

herdrのペインの環境変数

herdrは、サーバーが常駐し、そこにクライアントが接続する作りです。ペインの中のシェルは、herdrサーバーが起動します。そのため、手元からSSHでつないでいても、ペインの中には SSH_TTY も SSH_CONNECTION もありません。

ペインの中で次を実行すると確かめられます。何も表示されなければ、この問題に当てはまります。

env | grep -E '^SSH_(TTY|CONNECTION)'

env | grep -E '^SSH_(TTY|CONNECTION)'

コピーが手元に届かなかった流れ

順に並べると、次のとおりです。

1. ペインにSSHの環境変数がない
2. Codexは「SSH越しではない」と判断する
3. Codexは、自分が動いているマシン（SSH先）のクリップボードに書き込む
4. 手元のクリップボードには何も入らない

コピー自体は成功していて、別のマシンのクリップボードに入っていました。

環境変数を足すと直る理由

SSH_CONNECTION を設定すると、Codexは「SSH越しだ」と判断してOSC 52を送るようになります。

herdrは、ペインから届いたOSC 52を受け取り、接続中のクライアント（手元）へ転送する仕組みを持っています。こうして、Codex → herdrサーバー → herdrクライアント → 手元のクリップボード、とテキストが届きます。

条件の $HERDR_PANE_ID は、herdrがペインに設定する環境変数です。これを目印にして、herdrのペインの中だけで設定が効くようにしています。

注意点

• 手元の端末アプリがOSC 52に対応している必要があります。Ghostty、WezTerm、kittyはそのままで対応しています。iTerm2は、設定の「Applications in terminal may access clipboard」をオンにしてください。
• SSH先のマシンの前に座ってherdrを直接使う場合もOSC 52になります。その場合もコピー先は使っている端末なので、通常は問題ありません。
• SSH_CONNECTION を見て動きを変えるツールはほかにもあります。設定後に気になる挙動があれば、この1行を疑ってください。

herdrの機能でコピーする方法

画面に表示されているテキストを選んでコピーするだけなら、herdr自身の機能も使えます。

• マウスで選ぶ：herdrの mouse_capture が有効なら、ドラッグで選んだ範囲をherdrがクライアント側のクリップボードへコピーします
• キーボードで選ぶ：herdrの copy_mode のキーバインドから選択します

Codexの「回答をまるごとコピー」のような機能を使いたいときは、先ほどの環境変数の設定が必要です。

まとめ

• herdrの --remote 越しにCodexでコピーすると、SSH先のクリップボードに入ってしまう
• 原因は、CodexがSSHの環境変数でコピー方法を選んでいて、herdrのペインにはその変数がないこと
• SSH先の ~/.zshrc で、herdrのペインのときだけ SSH_CONNECTION を設定すると、OSC 52で手元にコピーされる
• 手元の端末アプリのOSC 52対応も確認する