GUI Codex の実際の設定や調整そのものは、Codex 自身に頼んだほうが正確に進めやすい場面が少なくありません。ただ、使い始めたばかりの時期ほど、「何を触れば変わるのか」が分からないまま不安になりやすいものです。そんなときに、「どこに何のファイルがあり、どのタイミングで効くのか」だけでも見えていると、挙動が変わった理由を追いやすくなりますし、修正を頼むときも意図を伝えやすくなります。
GUI Codex を使い始めた直後は、設定まわりの名前が似て見えて混乱しやすいものです。AGENTS.md も config.toml も挙動に関わるため同じ種類の設定ファイルに見えますし、Skills や SKILL.md も「追加の設定」のように受け取りやすいからです。実際には役割がかなり違うのですが、最初のうちはその違いが画面上からは見えにくく、どこを見ても正しそうに見えてしまいます。
最初は全部同じ『設定ファイル』に見えてしまって大丈夫です。まずは役割の違いだけつかめば、かなり整理しやすくなります。
とくに最初につまずきやすいのが AGENTS.md でしょう。~/.codex/AGENTS.md のような全体の共通基盤がありつつ、実際の運用では workspace など、より局所に置かれた AGENTS.md が優先されるため、「どれがいちばん強く効くのか」が見えにくくなりやすいからです。ここで一度混乱すると、「設定を変えたのに反映されない」「効いている場所を間違えていた」という感覚になりやすく、自分の理解不足のように感じてしまうかもしれません。
ただ、実際にはそれぞれの責務はかなりはっきり分かれています。まず把握したいのは、GUI Codexの設定 は一枚岩ではなく、「行動ルールを決める層」「機能を呼び出す層」「実行環境の既定値を持つ層」に分かれているということです。
この違いを先に整理しておくと、挙動を変えたいときにどのファイルを触るべきか判断しやすくなります。逆にここが曖昧なまま触り始めると、ルールを変えたいのに skill を見に行ったり、環境設定を変えたいのに AGENTS.md を編集したりして、原因の切り分けが難しくなります。
GUI Codexの仕組みを理解する前に押さえたい全体像
GUI Codex は、ひとつの設定ファイルだけで動きが決まる道具ではありません。大まかに見ると、まず上位のシステム指示やユーザーの依頼があり、その下に AGENTS.md のような行動ルールが重なり、さらに Skills や plugin が「何を呼び出せるか」を増やし、config.toml が既定モデルや権限、機能のオンオフといった土台を支えています。
そのため、初心者が最初にやりがちな「とりあえず設定ファイルを一つ探して直す」という探し方では、どこが原因かをつかみにくくなります。たとえば口調や判断方針を変えたいのに config.toml を見ても答えは出ませんし、逆に plugin の有効化を変えたいのに AGENTS.md を編集しても期待した変化は起きません。最初に必要なのは暗記よりも、「いま困っていることはどの層の話なのか」をゆるく見分ける感覚です。
GUI Codexは何を読みながら動くのか
実務目線で整理すると、GUI Codex はだいたい次の順で「何に従うか」を決めています。最初にあるのはシステムや開発者レベルの強い指示で、その次にユーザーがこの会話で明示した依頼があります。そのうえで、AGENTS.md が行動ルールを補い、Skills や plugin が使える能力を足し、config.toml がモデルや権限などの既定値を与えます。
ここで大事なのは、すべてのファイルが同じ意味で「設定」ではないことです。AGENTS.md は「どう振る舞うか」を決めるファイルであり、config.toml は「どんな環境で走るか」の既定値を持つファイルです。個々の SKILL.md は、その skill を呼んだときに何をどの順で行うかを定義する実行仕様で、日常会話のすべてを統治する憲法ではありません。
読み込まれるタイミングも違います。~/.codex/AGENTS.md や workspace 側の AGENTS.md は、その場の振る舞い方に継続的に効きやすい一方、個別の SKILL.md は skill が必要だと判断されたターンで参照されます。config.toml はセッションの土台となる既定値を支えるため、もっと低いレイヤーで効いています。
初学者が最初に混乱しやすい三つのレイヤー
初学者が混線しやすいのは、名前が近いのに責務が違うものが並んでいるからです。代表的なのは AGENTS.md、Skills、config.toml の三層です。どれも「Codex の挙動に関わる」という点では同じですが、変えられる範囲と効き方はかなり違います。ここを分けて読めるようになるだけで、「いま見ているものはルールなのか、機能なのか、環境なのか」が判断しやすくなります。
- AGENTS.md は『どう振る舞うか』を決めるルール層
- Skills は『何ができるか』を増やす機能層
- config.toml は model や権限などの既定値を持つ環境層
第一に、AGENTS.md はルールレイヤーです。応答の姿勢、優先順位、禁止事項、ブラウザ選定の前提など、「この環境ではこう動く」という運用上の憲法に近い役割を持ちます。第二に、Skills は機能レイヤーで、「表計算を触る」「スライドを作る」「特定のワークフローを回す」といった専門能力を追加します。第三に、config.toml は環境レイヤーで、既定モデル、権限、機能フラグ、plugin の有効化などを持ちます。
この三つを分けて見られるようになると、変更の相談も具体的になります。たとえば「返答の進め方を変えたい」なら AGENTS.md を確認し、「特定の専門動作を追加したい」なら skill や plugin を見て、「モデルや trust_level を変えたい」なら config.toml を見る、という流れで迷いにくくなります。
AGENTS.mdとは何か
AGENTS.md は、Codex に対して「この環境ではどう振る舞うべきか」を定めるファイルです。単なるメモや推奨事項ではなく、優先順位や禁止事項まで含めた実行条件として扱われます。今回の環境でも ~/.codex/AGENTS.md に、グローバル指示としての位置づけや、より局所の AGENTS.md を優先する原則が明記されています。
初心者がここで混乱しやすいのは、AGENTS.md を「ただのプロンプト集」や「口調設定」だと思ってしまうからです。実際にはもっと広く、ブラウザ操作の既定手段、ローカル plugin の扱い、サブエージェントの委任原則、指示の優先順位まで含んでいます。つまり、Codex の返答文だけでなく、どのツールを優先し、何を勝手にやってよいかにも影響します。想像していたより効く範囲が広いので、最初に戸惑うのは自然です。
AGENTS.mdが決めるものと決めないもの
AGENTS.md が決めるのは、あくまで行動ルールです。たとえば「不要な質問をしない」「ブラウザ作業では特定の手順を優先する」「局所ルールがあればそちらを優先する」といった運用判断はここで決まります。どの情報を先に確認し、どこまでを正確な事実として扱うか、といった姿勢に効いてくるのが AGENTS.md です。
| AGENTS.md が担うこと | 別レイヤーが担うこと |
|---|---|
| 返答方針やツール選択、確認の優先順位 | model や sandbox の既定値は config.toml |
| その場で従う運用ルール | 個別機能の手順は SKILL.md |
一方で、AGENTS.md は万能ではありません。model 名や sandbox の既定値、plugin の enabled 状態、workspace ごとの trust 設定といった低レイヤーの実行環境は、通常 config.toml 側の仕事です。同じように、特定 skill の内部手順までは AGENTS.md ではなく、その skill の SKILL.md が受け持ちます。
この切り分けを意識すると、「どこを直しても変わらない」状態を減らせます。行動ルールを変えたいのに config.toml をいじっても筋が悪いですし、plugin のインストール構造を変えたいのに AGENTS.md に書き足しても、実体が変わるわけではありません。
グローバルAGENTS.mdとworkspaceごとのAGENTS.mdの優先順位
ここが最初に混乱しやすい核心です。~/.codex/AGENTS.md は全体の共通基盤ですが、workspace ごとに AGENTS.md が置かれているなら、実運用ではより局所の AGENTS.md が優先されます。つまり、グローバルな憲法が土台にあり、その上にローカルルールが重なる構造です。最初にこの順番を知らないと、グローバルを読んで安心したあとで、実際の挙動が workspace 側に引っぱられていて戸惑いやすくなります。
じぴ子ここは『どちらが正しいか』ではなく、『この場所ではどちらが優先されるか』で見ると整理しやすいです。
このとき「グローバルがあるならローカルは不要」でもなければ、「ローカルがあるならグローバルは無効」でもありません。イメージとしては、まず全体の共通前提を ~/.codex/AGENTS.md で与え、その workspace でだけ必要な上書きや追加条件を局所 AGENTS.md で載せる形です。競合した場合は、より局所のものが優先されます。ここを腹落ちさせておくと、「どちらが間違いか」ではなく「どちらがこの場所で優先されるか」で見られるようになります。
ここを「上書き」という一語だけで理解すると、どこまで入れ替わるのかが見えにくくなります。実際には、上位のシステム指示やユーザー要求はそのまま残り、AGENTS.md 同士の競合でだけ局所優先が効く、という順序で捉えると混乱しにくくなります。
SkillsとSKILL.mdは何を担うのか
Skills は、Codex に追加の専門能力を持たせるための仕組みです。たとえば表計算、スライド、ブラウザ操作、記事制作フローのように、「この種類の依頼ではこう動く」という専門手順をまとめて提供します。そして、その実体として置かれているのが各 skill ディレクトリの SKILL.md です。
この環境でも ~/.codex/skills/.../SKILL.md や ~/.agents/skills/.../SKILL.md のように、skill ごとに個別ファイルが存在しています。逆に言うと、初心者が想像しがちな「全部の skill をまとめた一枚の SKILLS.md が中枢にある」という構造ではありません。少なくとも今回確認した構成では、実際に効いているのは個別の SKILL.md です。
Skillsは機能の呼び出し単位でありAGENTS.mdの代替ではない
ここも誤解しやすい点です。Skills は便利ですが、AGENTS.md の代わりではありません。AGENTS.md が「どう振る舞うか」を定めるのに対し、Skills は「何ができるか」「そのタスクではどう進めるか」を定めます。似たように見えて、責務の軸が違います。
たとえば、スプレッドシート編集用の skill があれば、表の読み書きや計算、整形の手順を詳しく持てます。しかし、その skill があるからといって、会話全体の優先順位や確認方針まで自由に決められるわけではありません。そこは依然として上位指示や AGENTS.md の統治下にあります。
この違いを知らないと、「skill を入れたのに返答の基本姿勢が変わらない」「AGENTS.md に書いたのに特定機能が増えない」といったすれ違いが起きます。Skills は能力追加、AGENTS.md は行動規範だと切り分けておくと理解しやすくなります。
pluginとskillの接続関係をどう読むか
plugin は、skills や MCP、追加メタデータを束ねる配布単位として理解すると分かりやすくなります。たとえばこの環境では、~/.agents/plugins/marketplace.json に local plugin の入口があり、./plugins/structci のような相対パスで plugin が登録されています。実体側には .codex-plugin/plugin.json があり、その中で skills: "./plugin-skills/" のように skill 群への入口が定義されています。
つまり、plugin は「箱」、skill は「箱の中の個別能力」です。GUI 上では plugin 名が先に見えやすいため、初心者は plugin を直接使っている感覚になりがちですが、実際の実行ではその plugin が公開している skill やツールが呼ばれます。
この構造を知っておくと、どこを見ればよいかが整理できます。plugin 自体が見えているのに期待した動作をしないなら、plugin.json や marketplace 側の登録を見るべきです。plugin は見えていても特定の振る舞いが変なら、次は配下の SKILL.md を見ます。ここを混同しないだけで、探す順番がかなり安定し、「どこから見ればいいのか分からない」状態から抜けやすくなります。
config.tomlはどの設定を持つのか
config.toml は、GUI Codex の実行環境に近い既定値をまとめる場所です。この環境では ~/.codex/config.toml があり、既定 model、reasoning effort、sandbox mode、feature フラグ、plugin の enabled 状態、project ごとの trust_level などが入っています。見た目の印象よりも、かなり土台寄りの設定を持つファイルだと考えたほうが実態に近いでしょう。
ここで重要なのは、config.toml は「なんでも書ける万能設定」ではないことです。たとえば会話の敬体ルールやブラウザ選定方針は、通常 AGENTS.md の責務です。逆に「この plugin を使える状態にするか」「この workspace を trusted とするか」「既定の model を何にするか」といった項目は、config.toml のほうが向いています。
実行環境や動作方針の既定値が入る場所
config.toml は「環境の初期値を置く場所」と捉えると分かりやすくなります。実際に見ると、model = "gpt-5.4" のような既定 model、sandbox_mode = "danger-full-access" のような権限関連、[features] や [plugins."..."] のような機能や plugin のオンオフが並んでいます。さらに [projects."..."] では、特定のパスを trusted として扱う設定も持てます。
こうした項目は、会話の内容に応じて毎回変わるものではなく、環境の前提として広く効く設定です。だからこそ、ここを変えると複数の workspace や複数ターンに影響が及ぶことがあります。軽い気持ちで直したつもりでも、あとから別の場所で挙動が変わって驚くことがあるので、最初は「ここは影響範囲が広い層だ」と知っておくだけでも十分助けになります。
AGENTS.mdやskill定義と責務が重ならない理由
config.toml、AGENTS.md、SKILL.md が別れているのは、役割が違うものを同じ場所に詰め込まないためです。もし全部を一つのファイルに寄せてしまうと、モデル設定と会話ルールと専門機能の実装手順が混ざり、変更理由も不具合の原因も追いにくくなります。
分かりやすく言えば、config.toml は土台、AGENTS.md は運用ルール、SKILL.md は個別能力の手順書です。どれか一つで全部を肩代わりしないからこそ、問題が起きたときに「どの層で起きているか」を切り分けやすくなります。この責務分離が見えるようになると、設定全体も整理して理解しやすくなります。
初学者向けに整理するとGUI Codexはどう動くのか
ここまでの話を、実際の動きとして一本につなげると理解しやすくなります。Codex はまず最上位の強い指示を前提にし、そのあとユーザーの依頼を受け取り、必要に応じて AGENTS.md のルールを参照し、さらに該当する Skills や plugin の手順を使い、最後に config.toml が支える環境の中で実行されます。
この順序で考えると、「なぜその判断になったのか」を追いやすくなります。たとえば plugin が有効でも、上位ルールで使い方に制約があれば、そのまま自由には動きません。逆に AGENTS.md で強いルールがあっても、そもそも plugin や skill が存在しなければ、その機能自体は使えません。
まず上位指示を読み次に局所ルールを読む流れ
初心者が実際に確認するときは、まず上位から順に見るのが安全です。最初に意識したいのは、この会話で何を頼んでいるかと、もっと上位に固定された強い制約がないかです。そのうえで AGENTS.md を見て、グローバル基盤とローカル上書きのどちらが効いているかを確かめます。順番を決めずに見始めると情報量の多さに押されやすいので、確認順があるだけでもかなり楽になります。
そのあとで、必要なら skill や plugin を見ます。ここで初めて「なぜその能力が呼ばれたのか」「なぜこの手順で進めているのか」が読みやすくなります。いきなり config.toml から入ると、環境の初期値は分かっても、今このターンでの判断理由までは追いにくいことが多いでしょう。
迷ったときに確認する順番
迷ったときの確認順は、簡単に固定しておくと便利です。順番を決めて見るだけで、どこから手を付ければよいかがかなり分かりやすくなります。
まずは返答方針を変えたいのか、機能を増やしたいのか、実行環境を変えたいのかをはっきりさせます。ここが曖昧だと、見るべきファイルも散らばりやすくなります。
次に、それが AGENTS.md の話なのか、SKILL.md や plugin の話なのか、config.toml の話なのかを分けます。層が分かるだけで確認先はかなり絞れます。
- 返答方針や優先順位が気になるなら AGENTS.md
- 特定作業の手順や機能が気になるなら SKILL.md や plugin
- model や権限、enabled 状態が気になるなら config.toml
もし返答の方針や優先順位が気になるなら AGENTS.md、特定作業の専門手順が気になるなら SKILL.md、plugin が見えるかや既定 model が気になるなら config.toml と marketplace 周辺、という順に見れば十分です。全部を一度に理解しようとするより、現象に対応する層を見つけるほうが現実的です。
GUI Codexで設定を触るときの実践的なコツ
設定を理解したあとに大事なのは、変更を小さく保つことです。初心者ほど、混乱した勢いで複数ファイルを同時に触りたくなりますが、それをやると「何が効いたのか」が途端に分からなくなります。とくに AGENTS.md と config.toml はどちらも影響範囲が広いため、同時変更は避けたほうが安全です。急いでいるときほど一気に直したくなりますが、あとで見返したときに自分を助けてくれるのは、小さく分けた変更です。
また、Codex に実際の変更作業を頼む場合でも、どの層を触るつもりなのかだけは自分で言えるようにしておくと話が早くなります。「workspace の AGENTS.md を直したい」「~/.codex/config.toml で plugin の enabled を見たい」「この plugin 配下の SKILL.md を確認したい」と言えるだけで、依頼の精度はかなり上がります。
いきなり全部変えず責務ごとに編集する
たとえば、口調や確認の細かさを変えたいなら、まず AGENTS.md だけを見るべきです。モデルや権限を変えたいなら config.toml だけに絞ったほうが分かりやすいです。plugin 開発や skill の動線を直したいときだけ、plugin 側の plugin.json や SKILL.md に入る、という順番が壊れにくい進め方です。
この「責務ごとに一枚ずつ触る」という姿勢は、初心者ほど効きます。変更の結果を観察しやすくなりますし、Codex に修正を頼むときも「どの層の話か」がすぐ共有できるからです。設定理解は、全部を暗記することより、責務ごとの切り分けを身につけることのほうが重要です。全部を知ってから触る必要はなく、「今の困りごとはこの層らしい」と分かるだけでも十分前に進めます。
名前が似た要素をどう読み分けるか
設定を触る前に意識したいのは、名前が似ているものを同じ種類として読まないことです。読者がまず見分けたいのは、「今見ているものが実在するファイルなのか」「機能のまとまりを指す概念なのか」「その場の挙動にいつ効くのか」という三点です。ここが曖昧なまま進むと、AGENTS.md と config.toml と Skills が頭の中で同列になり、何を変えるべきか判断しにくくなります。
もうひとつ大切なのは、実在するパスと概念上の分類を混ぜないことです。たとえば ~/.codex/AGENTS.md や ~/.codex/config.toml は実在パスとして確認できますが、Skills は能力のまとまりを指す概念名です。その一方で SKILL.md は各 skill の実体ファイルであり、plugin はそれらを束ねる単位です。この違いを意識して読むだけで、「どこにある何が今の挙動に効いているのか」をかなり追いやすくなります。
まとめ
GUI Codex を理解するときは、AGENTS.md、Skills、config.toml を同じ「設定ファイル」として並べてしまわないことが出発点になります。AGENTS.md は行動ルール、Skills と SKILL.md は機能と手順、config.toml は実行環境の既定値です。この役割差が見えるだけで、どこを編集すれば何が変わるかを判断しやすくなります。
とくに初心者は、まず AGENTS.md の優先順位から押さえると全体像がつかみやすくなります。そのうえで、「能力の話なら Skills」「環境の話なら config.toml」と切り分けていけば、GUI Codex の構成は急に見通しがよくなります。最初から全部を正確に説明できる必要はありません。どこで迷いやすいかを知り、見る順番が分かるだけでも、GUI Codex はかなり扱いやすくなります。
GUI Codex の設定でよくある質問
