🤖

Codexで「低介入ハーネス」を作る - その4:Codexのコンテキスト

に公開
AI
Agent
Harness
Codex
tech

今回はCodexのコンテキストについて調べます。

Status

Codex CLI では/statusでコンテキスト残量・トークン使用量を数字で確認できます。

Context window

Context window: 94% left (26K used / 258K)

ChatGPTと違い、Context windowの利用状況を確認できます。
これは1セッション内で、モデルが一度に保持・参照できる文脈量です。

ここに入るのは、ユーザー入力だけではありません。

  • AGENTS.md
  • ユーザー指示
  • Codexの応答
  • 読んだファイル内容
  • shell実行結果
  • tool callの結果
  • 作業履歴

5h limit

5h limit: 100% left (resets 16:21)

これは 直近5時間単位のCodex利用枠です。

公式のCodex pricingでも、local messages と cloud tasks は five-hour window を共有すると説明されています。つまり、CLIでのローカル利用やクラウドタスクの利用は、この5時間枠の消費対象になります。

意味としては、
今の5時間枠では、まだ100%残っている。16:21にリセットされる。

5h limit = 短期的な利用回数・利用量の上限
と考えるのが良さそうです。

Weekly limit

Weekly limit: 100% left (resets 22:21 on 29 Apr)

これは 週単位のCodex利用枠です。
5時間枠より長いスパンの上限です。公式にも、5時間枠に加えて weekly limits が適用される場合があると書かれています。

意味としては、
今週分の利用枠がまだ100%残っている。4月29日 22:21 にリセットされる。

https://developers.openai.com/codex/pricing?utm_source=chatgpt.com

statusline

/statuslineは、Codex CLI の 画面下部フッターに常時表示する情報を設定するコマンドです。

/statusはその場で状態を一覧表示するコマンドですが/statuslineは 常に見える監視用表示を作るものです。

表示例

Codex agent loop

/statusはコンテキスト使用量を数字で観測する方法です。
なぜその数字が増えるのかは、agent loopという仕組みを紐解くと理解できます。

1. User Input

ユーザーが Codex に依頼を出す。
例：READMEを更新して、このエラーを直して など。

2. Model Inference

Model Inference は、Codexが与えられた文脈を読んで次に何をするべきかを判断する工程です。

もう少し具体化すると、Codex はここで以下を判断しています。

判断対象 例
ユーザーは何を求めているか バグ修正か、調査か、説明か
どの情報を使うべきか 会話履歴、AGENTS.md、リポジトリ内のファイル、エラー内容
すぐ返答すべきか 「これは仕様です」と説明する
ツールを呼ぶべきか ファイルを読む、検索する、テストを実行する
追加で確認すべきか 破壊的変更、認証情報、曖昧なスコープなど
次の一手は何か ls する、README.md を読む、修正する、テストする

たとえば、ユーザーがこう言ったとします。

READMEをプロジェクト内容に合わせて更新して

このとき Model Inference では、Codex がだいたいこう判断します。

READMEを直接編集する前に、まずリポジトリの構成や既存READMEを確認する必要がある。
だからまずファイル一覧を見て、README.mdを読むためにツールを呼ぶ。

その結果、Tool Calls に進みます。

ユーザーがこう言った場合。

このプロジェクトの目的を一言で説明して

既に十分な文脈があれば、ツールを呼ばずに Agent Response に進むかもしれません。

人間の介入を減らすには、Model Inference に入る文脈を整える必要があります。

公式ドキュメント上も、Codex は単にユーザー入力だけを見ているわけではありません。プロンプトには、関連ファイル、画像、IDEで開いているファイル、選択範囲などの文脈を含めるべきだと説明されています。

ここでプロンプトという用語が出てきたので掘り下げます。

Prompts

公式では以下のように書かれています。

You interact with Codex by sending prompts (user messages) that describe what you want it to do.

ここで公式は、プロンプトを単なる「命令文」とは言っていません。
prompts (user messages) と書いています。

つまり Codex におけるプロンプトは、広い意味では ユーザーがCodexに渡す作業依頼メッセージです。
これはChatGPTに質問する感覚と似ていますが、Codexの場合はより実務寄りです。なぜなら、次の文で説明されるように、Codexはモデル出力をもとにファイルを読んだり、編集したり、ツールを呼んだりするからです。

この文の中心はここです。

describe what you want it to do

つまり、Codexに渡すプロンプトでは、まず Codexに何をしてほしいのか を説明する必要があります。

悪い例は、こういうものです。

このプロジェクト見て

これだと、Codexは「何を見ればいいのか」「何を成果物にすればいいのか」「変更していいのか」「調査だけなのか」が曖昧です。

少し良くすると、こうです。

このプロジェクトの構成を確認して、READMEに書くべき概要を提案してください。
まだファイルは変更しないでください。

さらにCodex向けにすると、こうです。

このリポジトリの構成を把握し、README.mdに追記すべき概要案を作る。

Constraints:
- まだファイルは変更しない
- 既存ファイルを読んで根拠を示す
- 不明点は assumptions として記録する

Done when:
- READMEに入れる概要案が提示されている
- 参照したファイルが列挙されている

ここで重要なのは、Codexへのプロンプトは「お願い」ではなく、作業単位の定義に近いということです。

1. ユーザーがプロンプトを送る
2. モデルを呼び出す

公式文では it calls the model と書かれています。
Codex本体が全部をハードコードで判断しているのではなく、モデルに現在の状況を渡して、次の行動を判断させる構造です。

このときモデルに入るのは、ざっくり言うとこういう情報です。

  • ユーザーのプロンプト
  • スレッド内の過去のやり取り
  • 関連ファイルの情報
  • AGENTS.md などの指示
  • 直前のツール実行結果
  • これまでに何をしたか
  • まだ何をする必要があるか

公式でも、Codexは作業しながらファイル内容、ツール出力、これまで行ったこと・今後やるべきことの記録からコンテキストを集める、と説明されています。

3. Tool Calls

Tool Calls は、Codex が「考える」から「実際に作業する」へ移る部分です。
ざっくり言うと、Tool Calls は次のようなものです。

Codex が、自分の判断に基づいて外部操作を実行するための呼び出し

Tool Call の種類 何をするか
ファイル読み取り README.md や AGENTS.md を読む
ファイル編集 コードや Markdown を変更する
シェル実行 npm test、ls、grep などを実行する
検索 リポジトリ内や場合によってはWebを調べる
MCP ツール 外部サービス・独自ツールと連携する
パッチ適用 差分としてファイルを更新する

つまり、Codex がリポジトリを調査したり、変更したり、検証したりするための手足です。

4. Agent Response

Codex が「もうツールを呼ばず、いったんユーザーに制御を返す」と判断した最終出力です。

Agent Response には、だいたい次のような内容が含まれます。

内容 例
実施内容 README.md を更新しました
変更ファイル AGENTS.md, PLAN.md を修正
検証結果 npm test は成功しました
未解決事項 外部APIキーがないためデプロイ検証は未実施です
次の提案 次は EVALUATION.md に評価基準を追加できます
ユーザー判断依頼 この方針で進めるか確認してください

ただし重要なのは、Agent Response そのものが成果物のすべてではないことです。

たとえば Codex がファイルを編集した場合、主な成果物はこのメッセージではなく

  • 実際に変更されたファイル
  • git diff
  • 実行されたテスト結果
  • ログに残された記録

です。
Agent Response は、これらをユーザーに要約して返す役割です。

Agent Response は「停止条件」でもある

ここが重要です。
Agent Response が返るということは、Codex の中では一旦、

  • ツールを呼び続ける必要はない
  • 人間に戻すべきタイミング
  • このターンの作業は完了または保留

と判断されたということです。

公式のドキュメントでも、Codex は「モデルを呼ぶ → モデル出力に従って file reads / file edits / tool calls などを行う」ループを、タスク完了またはキャンセルまで続けると説明されています。

Agent Response の質を見るポイント

低介入ハーネスの実験としては、Agent Response を単なる文章としてではなく、Codex の自律性を評価する証拠として見るとよさそうです。

見るべき観点はこの辺りです

観点 良い Agent Response 悪い Agent Response
実施内容 何をやったか明確 「完了しました」だけ
根拠 読んだファイル・実行結果がある 根拠が曖昧
検証 git diff やテスト結果に触れる 検証なし
未実施理由 制約やブロック理由が明確 できなかった理由が不明
介入要求 A/B/C判断に絞る D/E作業を人間に投げる
次の一手 小さく具体的 大きく曖昧

まとめ

今回は、/statusで見えるContext windowを起点に、Codexの文脈がどのように使われ、増えていくのかを整理しました。コンテキストは最初のプロンプトだけではなく、AGENTS.md、会話履歴、読んだファイル、tool callの結果、作業履歴などがagent loopを通じて追加されていきます。つまりCodexの挙動を理解するには、単発の指示ではなく、ループ全体で文脈が形成される過程を見る必要があります。

Discussion