OpenAI Codexに大きな開発タスクを任せていると、途中で止まったり、テストが失敗したまま完了報告が返ってきたりします。そのたびに「続きを実装して」「テストが通るまで直して」と指示するのは手間がかかります。
この問題に対応するのが、CodexのGoalsです。/goalで達成したい結果を設定すると、Codexはその目標を保持したまま、複数のターンにわたって作業を続けます。ただし、無限に動き続ける機能ではありません。達成条件、検証方法、変更してはいけない範囲を決めておかないと、成果が出ないまま長く動いてしまいます。
この記事では、2026年10月時点の公式情報をもとに、Goalsの導入、/goalの操作、Planモードとの違い、テスト失敗を直させる実例、完了条件と停止条件の書き方、止まる原因と予算の考え方を解説します。実例のNode.jsコードは、実際に動かして失敗と成功を確認しています。
Codex Goalsとは
Goalsは、現在のチャットに継続的な目標を設定し、複数のターンにわたって追跡する機能です。通常のCodexは、指示された処理が一段落すると結果を報告して入力を待ちます。Goalsでは、目標を満たしたかを確認し、未達成なら作業を続けます。
たとえばテストの修正なら、「対象のテストがすべて成功するまで直す」という条件を設定します。失敗を調べて直し、再実行し、まだ失敗していれば次の原因を調べます。大事なのは、作業を何回実行したかではなく、達成条件を満たしたかで完了を判断することです。
「終わるまで続けて」と書くプロンプトとの違い
Goalsの目標は、チャットのスレッドに保持されます。公式ドキュメントでは、目標の状態はactive（実行中）、paused（一時停止）、complete（完了）、budget-limited（予算上限）のいずれかです。
自動継続が起きるのは、スレッドがアイドル状態で、目標がactiveで、予算の範囲内のときです。別のターンが実行中のとき、ユーザーの入力が待機しているとき、ほかの作業が残っているときは、続きません。また、継続ターンでツールの呼び出しが1回もなかった場合は、空回りを防ぐために、次の自動継続が抑制されます。
公式ドキュメントでは、目標を開始しても、より広いアクセスが与えられるわけではなく、サンドボックスと承認のポリシーはそのままで、判断が必要になると一時停止すると説明されています。
Planモード・AGENTS.md・GOALS.mdとの違い
似た名前の機能が多いので、役割を整理します。
/plan（Planモード）：コードを変える前に調べて、実装方法や手順を整理します。「どう実装するか」を扱います。Codexが作業している間は使えません。/goal：最終的に成立すべき状態を定義し、達成まで追跡します。「何が成立すれば完了か」を扱います。AGENTS.md：リポジトリで作業するときに守らせたい共通ルールです。個別のタスクではなく、プロジェクト全体の方針を書きます。GOALS.md：公式のCookbookで紹介されている、成果と成功条件、境界を書くための任意のファイルです。Codexに必須のファイルではなく、置いただけでGoalsが始まることもありません。
大きな変更では、まず/planで方針を確認し、合意した完了条件を/goalに登録する流れが使いやすくなります。AGENTS.mdに近い考え方は、Claude CodeのCLAUDE.mdと共通する部分が多く、置き場所や読み込みの基本はClaude CodeがCLAUDE.mdを読まない原因｜配置場所・優先順位・読み込み範囲を確認でも整理しています。
Goalsを使う準備
Goalsは、公式CookbookによるとCodex 0.128.0以降で使えます。設定リファレンスでは、features.goalsは安定版（Stable）で、既定で有効です。まずCodexを最新にします。
npm install -g @openai/codex@latest codex --version
/goalがスラッシュコマンドの一覧に出ない場合は、機能フラグを確認します。
codex features list codex features enable goals
[features] goals = true
/goalは、Codexの対話画面の中で入力するコマンドです。PowerShellやコマンドプロンプトにそのまま入力するものではありません。
cd my-project codex # 対話画面で /goal テストスイートをすべて成功させ、既存の動作を維持してください。
/goalの操作：確認・一時停止・再開・編集・解除
/goal：現在の目標を確認する/goal pause：実行中の目標を一時停止する/goal resume：一時停止した目標を再開する/goal edit：目標の内容を修正する/goal clear：目標を解除する
目標の本文は、空にできず、4,000文字までです。複雑な要件は、Markdownファイルに書いておき、目標からそのファイルを参照させると収まります。一時停止した目標を再開しても、予算の上限や権限の不足が原因で止まっていた場合は、それだけでは解決しません。
実践：テストの失敗をGoalsで直させる
実際に動くコードで、Goalsの使い方を確認します。題材は、API通信などで使う「リトライ処理」です。回数の数え方を間違えやすい処理なので、意図的に不具合を入れたコードを用意します。Node.jsの標準テスト機能だけを使うため、外部ライブラリは不要です。
不具合のあるコードとテストを用意する
export async function retry(task, maxAttempts = 3) {
for (let attempt = 0; attempt <= maxAttempts; attempt++) {
try {
return await task();
} catch (error) {
if (attempt === maxAttempts) {
throw error;
}
}
}
}
attemptが0から始まり、maxAttemptsと等しくなるまで続くので、maxAttemptsが3なら、4回実行されます。
import test from "node:test";
import assert from "node:assert/strict";
import { retry } from "./retry.mjs";
test("失敗しても最大3回までしか実行しない", async () => {
let calls = 0;
await assert.rejects(
retry(async () => {
calls++;
throw new Error("temporary failure");
}, 3),
/temporary failure/
);
assert.equal(calls, 3);
});
test("2回目に成功した結果を返す", async () => {
let calls = 0;
const value = await retry(async () => {
calls++;
if (calls === 1) {
throw new Error("temporary failure");
}
return "ok";
}, 3);
assert.equal(value, "ok");
assert.equal(calls, 2);
});
修正前のテスト結果
node --test retry.test.mjs
修正前は、2件のうち1件目のテストが失敗し、次のように表示されます（Node.jsで実行して確認しました）。
Expected values to be strictly equal: 4 !== 3
修正前に失敗を再現しておくと、Codexの変更が正しかったかを、客観的に判断できます。Codexに渡す前に、現在の状態をGitでコミットしておくと、変更を後から比較しやすくなります。
目標を設定する
/goal retry.mjs のリトライ回数の不具合を修正してください。完了条件は node --test retry.test.mjs の全テストが成功し、最大試行回数を超える呼び出しが発生しないことです。まず失敗を再現し、原因を特定して最小限の修正を行い、再テストしてください。失敗した場合は原因を再調査し、同じ修正を繰り返さずに別の方法を検討してください。retry.test.mjs の変更、テストの削除・skip、外部依存の追加は禁止します。異なる修正案を3回試しても解決しない場合は未解決として報告してください。コミットやpushは行わないでください。
この目標は、「バグを直す」だけでなく、検証方法（テストコマンド）、変更してはいけないもの（テストファイル）、あきらめる条件（3回試しても解決しない場合）、してはいけない操作（コミットとpush）を含んでいます。テストの変更を禁止しているのは、期待値を書き換えて見かけだけ成功させることを防ぐためです。
この指示はCodexへの作業上の制約で、実行回数を強制的に止める仕組みではありません。回数や費用を確実に制限したい場合は、実行側で管理する必要があります。
修正後のコード
export async function retry(task, maxAttempts = 3) {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
try {
return await task();
} catch (error) {
if (attempt === maxAttempts) {
throw error;
}
}
}
}
ループの開始値を1にすれば、maxAttempts回で止まります。この修正例で同じテストを実行し、2件とも成功することを確認しました。
tests 2 pass 2 fail 0
なお、これはサンプルコードの検証であり、Codexの修正能力を測ったものではありません。実際のAPI通信では、待機時間、タイムアウト、キャンセル、再試行してよいエラーの種類、冪等性なども考える必要があります。重要な条件は、最初から完了条件に含めてください。
完了条件の書き方：テスト成功だけにしない
公式の使い方ガイドでは、よい目標は「明確な成功条件と検証のループがあり、1回のプロンプトよりは大きく、終わりのない作業リストよりは小さい」ものとされています。また、目標を始める前に、Codexが「何をもって完了とするか」を知っている必要があるとも説明されています。
テストが通ったことだけを完了条件にすると、テストを消す、機能を一部削って通りやすくする、といった抜け道ができます。次のように、条件を組み合わせます。
- 対象のテストと、プロジェクト全体のテストの両方が成功する（
npm test、ビルド、型チェックなど、プロジェクトにあるもの） - テストの削除・skip・期待値の緩和を禁止する
- 変更してよい範囲（ディレクトリ）を限定する
- 既存の公開APIの入出力を変えない
完了後は、変更の中身も自分で確認します。
git status git diff --stat git diff --check git diff
git diffは、追跡済みファイルの未ステージの変更が中心です。新しく作られたファイルを見落とさないように、git statusも確認します。これらで分かるのは変更の内容であり、実装の正しさそのものではないので、テスト結果と合わせて判断してください。
終わらない・空回りを防ぐ書き方
目標が曖昧だと、新しい改善点を探し続けて完了を判定できません。
/goal このプロジェクトをできるだけ改善してください。
/goal src/api の例外処理を整理し、既存APIのレスポンス形式を維持したまま、関連テストと全体テストを成功させてください。変更範囲は src/api と対応するテストに限定します。外部APIの仕様変更が必要になった場合は実装せず停止して報告してください。
失敗した修正を繰り返させないために、次のような指示も有効です。
修正が失敗した場合は、直前の修正内容と失敗理由を確認してください。 前回と同じ仮説の変更を繰り返さず、新しい証拠が得られてから次の修正を行ってください。 2回連続で新しい検証結果や進展が得られない場合は、方針を見直してください。 別の方針でも改善しない場合は、成功と報告せず、試した内容と未解決の理由をまとめて停止してください。
認証情報の不足や外部サービスの停止のように、Codex自身では解決できない問題は、再試行しても解決しません。「失敗したら何度でも」とは書かず、人に確認する条件を決めておきます。
長時間実行の問題として報告されている例
GitHubのopenai/codexリポジトリには、Goalsに関する報告があります。2026年7月には、目標が37時間以上実行され、数百万トークンが使われた一方で、要求した成果物を作らず、仕様や計画の作成を繰り返したというバグ報告が出ています（#34657、Codex CLI 0.144.6、2026年10月時点でオープン）。個別の報告であり、すべての実行で起きるわけではありませんが、長く動くことと成果が出ることは別だと分かります。経過時間ではなく、成果物と検証結果で進捗を判断してください。
実務で使える目標の例
CIで断続的に失敗するテストを直す
/goal GitHub Actionsで断続的に失敗しているテストの原因を調査し、再現できた不具合を修正してください。既存のテストを削除・skipせず、関連テストを同条件で20回実行し、すべて成功することを確認してください。環境依存で修正できない場合は、再現条件と必要な環境情報を報告してください。GitHubへのpushは行わないでください。
20回連続で成功しても、失敗する確率が低いテストは、なくなったと断定できません。
パフォーマンスを基準値まで改善する
/goal checkout APIのp95レスポンス時間を、指定のベンチマーク環境で120ms未満に改善してください。既存の正常系・異常系テストはすべて成功させてください。計測条件を変更せず、変更前後の測定結果を比較してください。基準未達の場合は原因を調査して次の改善を試してください。測定できない場合は成功扱いにせず、理由を報告してください。
ベンチマークの条件を変えて数値だけを良くすることを、禁止しておくのがポイントです。
大きなリファクタリング
/goal src/services 配下の重複したデータ変換処理を共通化してください。公開APIの入出力仕様を変更せず、既存テストを維持してください。変更は小さな単位に分け、各段階で関連テストを実行してください。全体テストが成功し、想定外の変更がないことを確認できた時点で完了としてください。対象外の機能改善は行わないでください。
進捗をファイルに残す
長い作業では、途中で何が行われたかを確認できると安心です。リポジトリにdocs/goal-progress.mdのような進捗ファイルを作る方法があります。Goalsの必須ファイルではなく、任意の運用です。
# Goal Progress ## 目的 APIの例外処理を修正し、全テストを成功させる。 ## 現在の状態 関連テストは成功。全体テストは未検証。 ## 検証結果 node --test tests/api.test.mjs : PASS ## 残っている問題 統合テストで接続エラーが発生。原因を調査中。 ## 次の作業 統合テストの依存サービスと設定を確認する。
重要な検証が完了したら docs/goal-progress.md を更新してください。 推測ではなく、実際に実行したコマンドと確認できた結果を記録してください。 未解決の問題は、成功扱いにしないでください。
利用枠に達したり、実行環境が止まったりしても、記録があれば再開するときに状況を把握できます。別のセッションや、ほかの開発者に引き継ぐときにも役立ちます。
途中で止めた作業を再開する
codex resume codex resume --last
codex resume --lastは、現在のディレクトリの直近のチャットを再開します。ほかのディレクトリのセッションも対象にしたいときは、--allを付けます。Goalsはスレッドの状態なので、目標を設定したセッションを再開することが大切です。新しいチャットを作ると、前の目標が引き継がれるとは限りません。
また、目標の状態が保存されることと、作業が動き続けることは別です。PCの電源を切ったり、実行環境が止まったりすれば、ローカルのCodexは続きません。公式の長時間作業のガイドでは、デスクトップアプリで離席するなら、スリープ防止の設定（Mac）や、離席前の一時停止が案内されています。IDE拡張機能では、目標の実行中はワークスペースを開いたままにします。
複数の目標を並行して動かす
チャットごとに別の目標を設定できますが、同じファイルを複数のCodexが同時に変更すると競合します。Git Worktreeで作業ディレクトリを分けると、ブランチごとに作業を分離できます。
git worktree add ../project-fix -b fix/api-errors
ただし、共有のデータベース、外部API、同じ開発サーバーを触る場合は、ディレクトリを分けても競合します。コードだけでなく、外部リソースの共有状態にも注意してください。
Goalsが勝手に止まる原因
承認待ちで止まる
権限が必要なコマンドでは、Codexが確認を求めて止まります。確認を避けるために、--dangerously-bypass-approvals-and-sandboxのような強いフラグを安易に使うのはおすすめしません。公式の案内でも、専用のサンドボックスVMの中でない限り避けるよう書かれています。無人で動かすローカル作業では、--sandbox workspace-writeを勧めています。重要な操作は人の承認を残す構成にしてください。権限の考え方は、Claude CodeのClaude Codeのpermissions.allow・denyの違い｜安全な設定例でも整理しています。
予算の上限に達する
予算に達すると、Codexは実質的な作業をやめ、進捗と残っている問題、次にやるとよいことをまとめます。公式Cookbookにも、予算の上限に達したことは、目標を達成したこととは違うと明記されています。
なお、目標ごとのトークン予算をCLIで選べるようにする要望（#36590）は、2026年10月12日にクローズされました。メンテナーは、モデルに自然な言葉で「このトークン数までに抑えて」と頼む方法がすでに使える、と回答しています。専用のコマンドやUIがあるとは限らないので、バージョンごとの機能は最新の公式ドキュメントで確認してください。
達成できない状態になっている
必要な認証情報がない、テスト用の外部サービスに接続できない、といった場合は、同じ操作を繰り返さず、必要な情報を報告して止まるべきです。目標に、解決できない問題が起きたときの終了条件を書いておきます。
IssueやCIの自動処理との違い
Goalsは、現在のスレッドに設定した1つの達成目標を追跡する機能です。新しいIssueを検知して自動で処理する、定期的に実行する、といった「イベントの監視」や「スケジュール実行」は含まれていません。GitHub Issuesを継続的に処理したい場合は、GitHub Actionsなどの実行基盤から、Codexを呼び出す構成を別に設計する必要があります。非対話の実行では、セッションの継続方法、終了条件、実行時間の制限を、あらためて決めてください。Actionsとの連携の考え方は、Claude Code版のClaude Code GitHub Actions完全ガイド｜PRレビュー自動化・Issue実装・CI/CDパイプライン統合も参考になります。
AIに自動で作業させるときのリスク全般はClaude Code セキュリティ完全ガイド｜プロンプトインジェクション対策・権限設計・機密情報保護・監査ログで整理しています。
よくある質問
QGoalsは有料プランが必要ですか？
Aこの記事では、利用条件や料金の詳細は確認していません。利用できるプランや、利用枠の消費は、お使いの契約と公式ドキュメントで確認してください。長い目標は、利用量が増える可能性があります。
Q/goalが出てこないのはなぜですか？
ACodexのバージョンが0.128.0より古いか、features.goalsが無効になっている可能性があります。codex features listで確認し、codex features enable goalsで有効にして、Codexを再起動してください。
QPlanモードと一緒に使えますか？
A使えます。/planで方針を整理してから、完了条件を/goalに登録する流れが有効です。ただし、Codexが作業している間は/planは使えません。
QGOALS.mdを置かないとGoalsは使えませんか？
A使えます。GOALS.mdはCookbookで紹介されている任意のファイルで、Codexに必須ではありません。/goalの実行とは別のものです。
Q目標を達成する前に止まったら、成功とみなしてよいですか？
Aいけません。予算の上限に達しただけの場合や、承認待ちで止まった場合は、未達成です。テストの結果と差分を自分で確認してください。
まとめ
Codex Goalsは、/goalで設定した達成目標を保ち、複数のターンにわたって作業を続ける機能です。テストの修正、断続的な失敗の調査、性能改善、大きなリファクタリングのように、途中で次の判断が必要な作業に向いています。
一方で、使えば必ず完了する機能ではありません。目標が曖昧だったり、検証が足りなかったりすると、長く動いても成果が出ない可能性があります。達成条件、テスト方法、変更範囲、停止条件を決め、結果をコードとテストの記録で確認することが大切です。まずは今回のような小さなテスト修正から試して、実行と検証の動きを確認してみてください。
