Codexが使う社内CLIを作る前に決めること

3行まとめ

Args

入力。

Output

出力。

Dry-run

確認。

Audit

記録。

Codexが使うCLIは、実行前に入力と結果を固定します。

• Codexに社内操作を任せるなら、自然言語の依頼ではなく、再現可能なCLIへ寄せます。
• CLIは、引数、stdout、stderr、exit code、dry-run、監査ログを先に固定します。
• read、write、delete、adminを同じ入口に混ぜず、操作ごとに認証と承認を分けます。

Codexに社内APIやlog source、export、team scriptを使わせたい場面は増えます。毎回「このAPIを叩いて」「このログを見て」「このCSVを出して」と説明するより、チーム用のCLIを用意した方が、作業は安定します。

ただし、CLIを作れば安全になるわけではありません。引数が曖昧、出力が人間向けだけ、dry-runがない、secretをstdoutへ出す、失敗時のexit codeが揺れる。こうしたCLIは、AIにとっても人間にとっても危ない入口になります。

この記事では、OpenAI公式のCodex Use Casesにある「Create a CLI Codex can use」をもとに、2026年6月1日時点の情報として整理します。Codexのuse casesやpermissionsは更新され得るため、導入時は最新docsと自社の権限運用を確認してください。

この記事でわかること

Target

対象。

Interface

型。

Permission

権限。

Logs

証跡。

CLIは便利な近道ではなく、権限を小さくする入口です。

• Codexから使わせるCLIの対象を分ける方法
• 引数、stdout、stderr、exit codeを固定する理由
• write系操作にdry-runを入れる考え方
• read、write、delete、adminの権限境界
• AGENTS.mdやskillへ使い方を残す方法
• 監査ログに残すべき項目

この記事は、MCP serverの作り方そのものではありません。既存の社内API、log source、export、team scriptを、Codexから安全に呼べるCLIへ寄せる話です。MCPのToolやResource設計を知りたい場合は、公開済み記事のTypeScriptで最小MCPサーバーを作る前に見ることが近いです。

前提知識

項目	内容	見方
Use Cases		CLI作成。
Features		作業入口。
Permissions		権限。
AGENTS.md		使い方。
Skills		再利用。

社内操作は、自然言語ではなく再現可能なcommandへ寄せます。

OpenAI公式のCodex Use Casesでは、API、log source、export、team scriptのために、Codexが使えるcomposable commandを作る用途が紹介されています。これは、すべてを自然言語で説明する代わりに、再現可能な操作単位を用意する考え方です。

Codex app featuresやpermissions、AGENTS.mdのdocsも関係します。CLIはrepoの中に置かれることもあれば、社内toolとして呼ばれることもあります。どちらの場合も、何を読めるか、何を書けるか、外部へ何を送るか、secretをどう扱うかを分けます。

Codex Use Casesで見る位置づけ

用途	この記事での扱い
Create a CLI Codex can use	API、log、export、team scriptの入口を作る
Run verified operations	繰り返し操作を検証可能にする
Save workflows as skills	再利用する手順を残す
Kick off coding tasks from Slack	会話からscoped taskへつなぐ
Permissions	読み取り、書き込み、外部通信を分ける

MCPとの違い

MCPは、agentへtoolやresourceを渡すprotocolです。CLIは、shellから実行できるcommandです。どちらもAIが使う入口になり得ますが、運用の粒度が違います。

最初からMCPを作る前に、CLIで操作を安定させるのは有効です。引数、出力、dry-run、監査ログが決まったCLIは、後からMCP tool化する時にも設計の土台になります。

CLI化する対象を4種類に分ける

項目	内容	見方
API		取得や更新。
Logs		調査。
Export		出力。
Script		定型作業。

対象を分けると、read/writeの境界を決めやすくなります。

CLI化する対象は、API、log source、export、team scriptに分けます。対象によって、必要な権限、出力形式、失敗時の扱いが違うからです。

APIは取得や更新を行います。log sourceは調査に使います。exportはCSVやJSONを出します。team scriptは日次確認やrelease前チェックなど、チーム固有の手順をまとめます。

API

API向けCLIでは、readとwriteを分けます。たとえば、issue一覧を読むcommandと、issueへlabelを付けるcommandは別にします。

Codexに使わせるなら、read系から始めます。write系はdry-run、確認、監査ログを入れてから開きます。

log source

log source向けCLIでは、検索条件と出力制限を決めます。期間、service、environment、request id、user id、error codeなどです。

ログには個人情報やsecretに近い情報が混ざることがあります。Codexへ渡す出力は、必要な範囲へ絞り、maskやredactionを入れます。

export

export向けCLIでは、出力形式、保存先、件数制限、列定義を固定します。CSV、JSONL、Markdown tableなど、用途に合わせます。

Codexが後続処理をするなら、機械可読なJSONやJSONLが扱いやすいです。人間向けの装飾はstderrやsummaryへ分けます。

team script

team scriptは、チーム固有の手順です。release前確認、incident sweep、daily report、QA checklist、billing checkなどがあります。

属人化している手順ほど、CLI化の価値があります。ただし、承認が必要な手順は、自動実行と人間確認を分けます。

command interfaceを固定する

1. 1Args

   明示。

2. 2Stdout

   機械可読。

3. 3Stderr

   人間向け。

4. 4Exit

   結果。

Codexが迷わないように、出力とexit codeを安定させます。

CLIのinterfaceは、args、stdout、stderr、exit codeで固定します。Codexが使うCLIは、毎回同じ形で結果を読めることが大事です。

人間が手元で使うCLIなら多少の揺れは許せます。しかし、AIが次の判断に使うなら、出力形式と失敗の表現を安定させます。

args

argsは明示的にします。自由文のpromptではなく、--project、--env、--from、--to、--format、--dry-run のように分けます。

曖昧なdefaultは避けます。特にenvironmentは、production、preview、staging、developmentを明示させます。

stdout

stdoutは、後続処理に使う情報を出します。JSONやJSONLのような機械可読形式が向いています。

人間向けの説明やprogress barをstdoutへ混ぜると、Codexがparseしにくくなります。summaryや注意書きはstderrへ分けるか、JSON内の明示フィールドにします。

exit code

exit codeは、成功、入力エラー、認証エラー、権限エラー、対象なし、外部API失敗を分けます。

すべてを0で返すCLIは、AIにとって危険です。失敗なのに成功扱いで次へ進むことがあります。

dry-runを先に作る

Preview

何が起きるか。

Diff

変更差分。

Confirm

承認。

No write

書かない。

write系CLIは、まずdry-runで結果を見られるようにします。

write系CLIでは、dry-runを先に作ります。何が起きるかを表示し、副作用を起こさない入口です。

dry-runは飾りではありません。実際のwrite pathに近いところまで確認し、最後の更新だけ止める設計にします。

preview

previewでは、変更対象、変更前、変更後、影響範囲を出します。たとえば、付与するlabel、更新するstatus、export対象、通知先などです。

Codexには、dry-run結果を読ませてから、実行してよいかを人間へ確認させます。

confirm

confirmは、人間承認の入口です。CLI側で --yes を要求する、承認IDを要求する、PRやticketのURLを要求する、といった方法があります。

AIが勝手にwriteできる状態にしないことが大事です。少なくとも初期導入では、writeやdeleteは人間承認を挟みます。

no side effect

dry-runは副作用を起こしません。外部通知、DB更新、file upload、ticket更新、課金、deploy、deleteをしないことを保証します。

もしdry-runでも外部APIへreadを行うなら、その通信先と送信dataを記録します。

権限と認証を分ける

項目	内容	見方
Read		取得。
Write		更新。
Delete		削除。
Admin		管理。

同じCLIでも、操作ごとに認証と承認を分けます。

CLIの権限は、read、write、destructive、adminに分けます。同じbinaryに複数操作を入れる場合でも、認証と承認は分けます。

最初はread-onlyから始めます。writeはdry-runと監査ログができてから。deleteやadminは、別commandや別credentialにします。

read

readは、情報を取得する操作です。issue一覧、log検索、user設定の確認、deployment statusの取得などです。

readでも機密情報を含む場合があります。取得範囲、mask、件数制限、保存先を決めます。

write

writeは、状態を変える操作です。label追加、status更新、コメント投稿、export生成、report送信などです。

writeでは、dry-run、承認、監査ログ、rollbackの有無を確認します。特に外部通知や顧客向け送信は慎重に扱います。

destructive

destructiveは、削除、失効、上書き、deploy rollback、課金変更などです。初期導入ではCodexに直接渡さない方が安全です。

必要な場合は、別credential、別command、承認ID、対象確認、二段階実行を入れます。

secretを出力しない

CLIは、secretをstdoutにもstderrにも出しません。token、API key、cookie、authorization header、署名付きURL、個人情報をmaskします。

失敗時のerror messageにも注意します。外部APIのraw responseをそのまま出すと、secretや内部情報が漏れることがあります。

Codexに渡す使い方

項目	内容	見方
Examples		例。
Defaults		初期値。
Limits		禁止。
Report		報告型。

CLIの使い方は、AGENTS.mdやskillへ短く残します。

CodexへCLIを渡す時は、examples、safe defaults、limits、report formatを用意します。AGENTS.mdやskillに短く残すと、繰り返し使いやすくなります。

CLIそのものが安全でも、使い方が曖昧なら危険です。どの場面で使うか、どの場面では使わないかを書きます。

examples

examplesは、実際に使うcommandを載せます。read、dry-run、writeの順で示します。

例は短くします。長すぎる例は、Codexがどこを変えればよいか判断しにくくなります。

safe defaults

safe defaultsは、何も指定しない時に安全側へ倒す設定です。productionをdefaultにしない、件数制限を入れる、writeはdry-runをdefaultにする、などです。

defaultが危険なCLIは、AIにも人間にも危険です。

AGENTS.md

AGENTS.mdには、CLIの用途、禁止操作、実行例、確認方法、報告形式を書きます。

たとえば、「このCLIはread-only調査に使う」「writeはdry-run結果を貼って承認後に実行する」「delete系は使わない」といった形です。

監査ログを残す

1. 1Who

   実行者。

2. 2What

   操作。

3. 3When

   時刻。

4. 4Result

   結果。

CLI実行は、成功だけでなく失敗と未実行も記録します。

監査ログには、who、what、when、resultを残します。成功だけでなく、失敗、dry-run、未実行も記録します。

AIが使うCLIでは、後から「何を見て、何を変えたか」を追えることが重要です。作業が速くなっても、追跡できなければ運用に乗りません。

who

whoは、実行主体です。人間のaccount、service account、CI job、Codex task id、PR URLなどを残します。

個人tokenを使うと、責任範囲と失効が曖昧になります。可能なら用途別credentialを検討します。

what

whatは、実行した操作です。command、args、対象resource、dry-runか本実行か、承認IDを残します。

secretを含むargsはmaskします。ログを残すためにsecretを露出してはいけません。

result

resultは、成功、失敗、変更なし、対象なし、未承認、partial failureを分けます。

Codexには、最後にresultとnext actionを報告させます。失敗した場合は、retryしてよい失敗か、人間確認が必要な失敗かを分けます。

よくある失敗

Free text

曖昧。

No dry-run

即実行。

Secrets

漏れる。

No logs

追えない。

便利なCLIほど、失敗時に追える形へ寄せます。

よくある失敗は、自由文をそのまま引数にする、stdoutへ人間向け説明を混ぜる、dry-runがない、secretを出す、exit codeが全部0、監査ログがないことです。

もう1つは、readとwriteを同じ感覚で扱うことです。read-onlyのCLIで便利だったからといって、writeやdeleteまで同じcredentialで開くと、事故時の影響範囲が広がります。

CLIは、Codexを強くする道具です。だからこそ、便利さより先に、入力、出力、権限、記録を固めます。

FAQ

項目	内容	見方
MCP?		必要なら別。
JSON?		出力向き。
Delete?		承認必須。
Secrets?		非表示。

迷ったら、Codexに渡してよい操作かどうかへ戻します。

CLIではなくMCPにした方がよいですか？

最初からMCPが向く場合もあります。ただ、既存scriptや社内APIの入口を整える段階では、CLIで引数、出力、dry-runを安定させる方が始めやすいことがあります。

出力はJSONにすべきですか？

Codexが後続処理に使うならJSONやJSONLが向いています。人間向けの表や文章はsummaryとして別に出すか、JSON内のfieldとして明示します。

delete系commandも渡してよいですか？

初期導入では避ける方が安全です。必要なら別command、別credential、dry-run、承認ID、監査ログ、対象確認を必須にします。

secretはどこで扱いますか？

CLI側で安全なcredential storeや環境変数から読みます。ただし、stdout、stderr、audit log、error messageへ出さないようにします。Codexにsecret値を読ませない設計を優先します。

参照した主な情報源

• https://developers.openai.com/codex/explore/
• https://developers.openai.com/codex/use-cases
• https://developers.openai.com/codex/app/features
• https://developers.openai.com/codex/permissions
• https://developers.openai.com/codex/guides/agents-md

次に読むなら

更新履歴

1. 2026.06.01

   初版。

Codexのuse casesやpermissionsは、導入時に公式docsで見直します。

• 2026年6月1日: OpenAI公式Codex docsを確認して初版を作成しました。