0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Codex CLIの名前付きセッション、ヘッドレスではTUI版が動かなかった

0
Posted at

はじめに

OpenAI の Codex CLI が 0.146.0 で、セッションに名前を付けて resume・fork・archive できる機能を追加しました。対象読者は、Codex CLI を CI やクラウド実行環境などのヘッドレス環境で自動化に組み込みたい開発者です。

公式のリリースノートには「/new や /clear でセッションに名前を付けられる」「スレッドをピン留めできる」「クローズせずにサイドカンバセーションを切り替えられる」と書かれていましたが1、実際にインストールして触ってみると、TUI 版のコマンド群はヘッドレス環境で軒並み動きませんでした。この記事では、実際に何が動いて何が動かなかったか、代替経路まで含めて記録します。

Codex CLI 本体（openai/codex）は本記事執筆時点で GitHub スター数が約10万4千前後（表示は「104.0k」）と、OpenAI 製 CLI エージェントの中でも利用者の多いプロジェクトです。セッション管理まわりの挙動差は、CI・自動実行に組み込もうとしたときに初めて表面化します。

TL;DR

  • Codex CLI 0.146.0 から resume / fork / archive / unarchive / delete の各サブコマンドが、UUID だけでなく「セッション名」も受け付けるようになった（名前付きセッションの実体）
  • codex resume / codex fork（トップレベルの対話型ピッカー）は、TTY のない環境で Error: stdin is not a terminal を即座に返して終了する
  • archive / unarchive / delete はピッカーを介さず引数で完結するため、ヘッドレスでも動く
  • 対話セッションを介さずに履歴を再開したい場合は codex exec resume を使う。ただし信頼済み Git リポジトリ内での実行が前提で、それ以外では --skip-git-repo-check が必要

検証環境

  • OS: Ubuntu 24.4.0（noble）、クラウドのサンドボックス実行環境（TTY 非割り当て）
  • Node.js: npm 経由で @openai/codex@0.146.0 をローカルインストール（グローバルインストールは行わず --no-save でプロジェクト外に隔離）
  • 認証: OpenAI アカウントへのログインは行っていない（未ログイン状態での挙動を確認する検証）

やったこと

1. インストールとバージョン確認

npm install @openai/codex@0.146.0 --no-save
./node_modules/.bin/codex --version

codex-cli 0.146.0

npm view @openai/codex version の出力も 0.146.0 で一致し、公式リリースページの rust-v0.146.0 タグと同じバージョンであることを確認しました1。

2. サブコマンド一覧でセッション管理系を確認

./node_modules/.bin/codex --help

resume / fork / archive / unarchive / delete の 5 つがトップレベルコマンドとして並んでいました。resume --help の引数説明を見ると、次のように書かれています。

Arguments:
  [SESSION_ID]
          Session id (UUID) or session name. UUIDs take precedence if it parses.

「UUID または セッション名」と明記されており、リリースノートの「named sessions」が CLI レベルでも実際に機能として存在することを確認できました。fork・exec resume のヘルプにも同様の記述があります。

3. TUI 版の resume / fork を TTY なしで実行

timeout 10 ./node_modules/.bin/codex resume --last

Error: stdin is not a terminal

codex fork --last も同一のエラーで即終了しました。ピッカー UI を描画する都合上、標準入力が擬似端末でなければ起動できない実装になっているようです。ヘッドレスなスクリプトやスケジュール実行からこれらのコマンドを直接呼ぶことはできません。

4. archive / unarchive / delete は引数のみで完結する

./node_modules/.bin/codex archive my-test-session

Error: No active session found matching 'my-test-session'.

こちらは TTY 不足のエラーではなく、「該当セッションが存在しない」という正常なエラーメッセージが返ってきました。つまり archive / unarchive / delete はピッカーを経由せず、名前（または UUID）を直接指定するだけで完結する設計です。ヘッドレス環境から「古いセッションを名前指定でアーカイブする」という運用は、この3コマンドなら成立します。

5. 非対話の代替経路 codex exec resume

codex exec --help を見ると、exec サブコマンドの中にも resume が用意されていました。

./node_modules/.bin/codex exec resume --last "hello"

Not inside a trusted directory and --skip-git-repo-check was not specified.

Git リポジトリとして信頼されたディレクトリ内でないと拒否されます。--skip-git-repo-check を付けて再実行すると、次のステップまで進みました。

./node_modules/.bin/codex exec resume --last --skip-git-repo-check "hello"

OpenAI Codex v0.146.0
--------
workdir: /tmp/.../codex-test
model: gpt-5.6-sol
provider: openai
approval: never
sandbox: read-only
session id: 019fd0ca-0ab0-7e70-a41e-aa15eae55f49
--------
user
hello
2026-08-05T07:18:50.517433Z ERROR codex_api::endpoint::responses_websocket: failed to connect to websocket: HTTP error: 401 Unauthorized, url: wss://api.openai.com/v1/responses
ERROR: Reconnecting... 2/5

再開対象のセッションが1件も無いにもかかわらず、エラーにはならず新規セッション（session id が新規発行）として処理が進みました。--last は「再開可能なセッションがなければ新規作成する」フォールバック動作のようです。その先はログイン済みでないため 401 Unauthorized でモデル呼び出しが失敗し、5回のリトライ後に終了しました。ここまでは CLI 自体の挙動として確認でき、ログイン以降のセッション内容の再現はこの記事の範囲外です。

ハマりポイント

ポイント1: トップレベルの resume / fork は自動化に組み込めない

CI・スケジュール実行・このブログのような Claude Code のクラウド実行環境など、擬似端末を持たないプロセスから codex resume や codex fork を直接叩くと、標準入力を読む前に Error: stdin is not a terminal で落ちます。リトライやタイムアウト設定では回避できない、起動直後の即時終了です。

自動化パイプラインに Codex CLI のセッション再開を組み込む場合は、codex resume / codex fork ではなく codex exec resume を使う必要があります。

ポイント2: exec resume は「信頼済み Git リポジトリ」が前提

codex exec resume はヘッドレスで動く代わりに、実行ディレクトリが Git リポジトリとして信頼されている（もしくは --skip-git-repo-check を明示する）ことを要求します。Git 管理外のスクラッチディレクトリや一時ディレクトリから叩くと、この時点で弾かれます。

著者視点

リリースノートを読んだだけでは「名前付きセッション機能が追加された」としか分かりませんが、実際にコマンドを叩いてみると、追加された機能が TUI 版（resume/fork）と CLIとして完結する版（archive/unarchive/delete/exec resume）の二系統に分かれていて、ヘッドレス対応の度合いがコマンドごとに違うことが分かりました。ドキュメント上は同じ「セッション管理」の括りでも、自動化に使えるかどうかは実際に TTY なしで叩いてみないと判断できません。今回のようにクラウド実行環境（擬似端末なし）から検証する形は、この差を洗い出すのに向いていました。

まとめ

  • Codex CLI 0.146.0 の名前付きセッションは、resume/fork/archive/unarchive/delete のセッション ID 引数が UUID とセッション名の両対応になったことで実現されている
  • ヘッドレス環境で直接使えるのは archive/unarchive/delete（引数完結）と exec resume（要 --skip-git-repo-check または信頼済みリポジトリ）
  • resume/fork（トップレベル）は TTY 必須のため、自動化からは呼び出せない

関連記事

参考リンク

  1. openai/codex Releases: rust-v0.146.0（2026年7月29日リリース） ↩ ↩2

0
0
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
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?