MENU
  1. ホーム
  2. 開発ログ
  3. Codexの権限プロファイルでAGENTS.mdの読み込みに失敗した原因を調べる

Codexの権限プロファイルでAGENTS.mdの読み込みに失敗した原因を調べる

開発ログ

複数の開発プロジェクトを扱うため、Codexからアクセスできるフォルダを制限するPermission Profileを設定していました。

ところが、Codexのセッションを開始すると次のエラーが発生しました。

Bash
Error: Failed to start a fresh session through the app server:
thread/start failed during TUI bootstrap:
thread/start failed:
error creating thread:
Fatal error: Failed to initialize session:
failed to load AGENTS.md instructions for environment `local`:
アクセスが拒否されました。 (os error 5)
(code -32603)

表示上はAGENTS.mdの読み込みエラーなので、最初はファイルのアクセス権やパスを疑いました。

しかし調査を進めると、AGENTS.mdそのものではなく、Codexに設定していたPermission Profileが関係していました。

目次

結論：:workspaceを継承し、ワークスペース全体をreadにすると解決した

今回のエラーは、CodexのカスタムPermission Profileでワークスペースルートをdenyにしていたことが原因でした。

最終的には、カスタムProfileで:workspaceを継承し、ワークスペース全体をread、必要な管理フォルダと開発対象だけをwriteにすることで正常に起動しました。

カスタムPermission Profileでアクセス拒否が発生した

以下は、./codex/config.toml です

もともとは、ワークスペース内で指定したプロジェクトと管理フォルダだけを操作できるようにしていました。

TOML
approval_policy = "on-request"
default_permissions = "workspace-projects"

[permissions.workspace-projects]
description = "ワークスペース内の指定プロジェクトと管理フォルダだけを操作する"

[permissions.workspace-projects.filesystem]
":minimal" = "read"

[permissions.workspace-projects.filesystem.":workspace_roots"]

"." = "deny"

"AGENTS.md" = "read"
"Obsidian" = "write"
".out-of-code-insights" = "write"
"test-workspace" = "write"

"markdown-it-digit" = "write"
"vscode-markdown-digit" = "write"

意図としては単純です。

ワークスペース全体へのアクセスを禁止したうえで、必要なファイルやフォルダだけを個別に許可します。

Markdown
ワークスペース全体
└─ deny

許可する場所
├─ AGENTS.md              → read
├─ Obsidian               → write
├─ .out-of-code-insights  → write
├─ test-workspace         → write
├─ markdown-it-digit      → write
└─ vscode-markdown-digit  → write

しかし、この設定ではCodexのセッション初期化時点でAGENTS.mdの読み込みに失敗しました。

Permission Profileを一つずつ切り分ける

組み込みの:workspaceでは正常に起動した

まず、設定ファイルを変更せず、起動時だけPermission Profileを組み込みの:workspaceへ切り替えました。

Bash
codex -c 'default_permissions=":workspace"'

するとCodexは正常に起動しました。

ファイル参照に使う@にも反応したため、TUIだけでなくセッション作成やワークスペース認識も動作しています。

ここで、

Markdown
Codex自体
Windows
PowerShell
AGENTS.mdそのもの

よりも、カスタムPermission Profile側を疑うべきだと判断しました。

設定をすべて外すと正常に起動した

次に、Permission Profile関連の設定をすべてコメントアウトしました。

TOML
# approval_policy = "on-request"
# default_permissions = "workspace-projects"

# [permissions.workspace-projects]
# description = "ワークスペース内の指定プロジェクトと管理フォルダだけを操作する"

この状態でもCodexは正常に起動しました。

そこで、設定を少しずつ戻していきます。

空のカスタムPermission Profileでも失敗した

まず、最低限の設定だけを戻しました。

TOML
approval_policy = "on-request"
default_permissions = "workspace-projects"

[permissions.workspace-projects]
description = "ワークスペース内の指定プロジェクトと管理フォルダだけを操作する"

filesystemの設定はまだありません。

ところが、この状態でも同じエラーが発生しました。

Bash
failed to load AGENTS.md instructions
アクセスが拒否されました。 (os error 5)

つまり、

TOML
":minimal" = "read"

や、

TOML
"." = "deny"

を追加する前から問題が発生しています。

カスタムPermission Profileを定義して選択するだけでは、組み込みの:workspaceと同じ権限状態にはならないことが分かりました。

:workspaceを継承すると起動した

そこで、カスタムPermission Profileにextendsを追加しました。

TOML
approval_policy = "on-request"
default_permissions = "workspace-projects"

[permissions.workspace-projects]
description = "ワークスペース内の指定プロジェクトと管理フォルダだけを操作する"
extends = ":workspace"

これでCodexは正常に起動しました。

今回の構成では、カスタムProfileをゼロから定義するのではなく、

Markdown
:workspace
↓
workspace-projects
↓
必要な権限だけ変更

という形にする必要がありました。

ここで一つ目の問題を解決できました。

:minimal = "read"は問題なかった

続いて、以前使っていた最低限の読み取り権限を戻します。

TOML
[permissions.workspace-projects.filesystem]
":minimal" = "read"

全体は次の状態です。

TOML
approval_policy = "on-request"
default_permissions = "workspace-projects"

[permissions.workspace-projects]
description = "ワークスペース内の指定プロジェクトと管理フォルダだけを操作する"
extends = ":workspace"

[permissions.workspace-projects.filesystem]
":minimal" = "read"

この設定でも正常に起動しました。

したがって、今回のアクセス拒否については、

TOML
":minimal" = "read"

自体は原因ではありませんでした。

ワークスペース全体をdenyにすると再び失敗した

次に、元の設定にあったワークスペース全体のdenyを追加しました。

TOML
[permissions.workspace-projects.filesystem.":workspace_roots"]

"." = "deny"

すると、再び同じエラーが発生しました。

Bash
failed to load AGENTS.md instructions for environment `local`:
アクセスが拒否されました。 (os error 5)

ここまでの結果を整理すると、次のようになります。

Markdown
extends = ":workspace"
→ 成功

extends = ":workspace"
+ ":minimal" = "read"
→ 成功

extends = ":workspace"
+ ":minimal" = "read"
+ "." = "deny"
→ 失敗

つまり、

TOML
"." = "deny"

が二つ目の問題でした。

ワークスペースルート自体をdenyにすると、Codexがセッション初期化時に行うAGENTS.mdの探索までアクセス拒否の対象になっていると考えられます。

個別に、

TOML
"AGENTS.md" = "read"

を指定していても、今回のWindows環境では正常に初期化できませんでした。

denyではなくreadをデフォルトにする

そこで方針を変更しました。

これまでは、

Markdown
指定していない場所
→ deny

必要な場所
→ read / write

としていました。

これを、

Markdown
ワークスペース全体
→ read

変更が必要な場所
→ write

という構成にします。

設定は次のようになります。

TOML
[permissions.workspace-projects.filesystem.":workspace_roots"]

"." = "read"

"Obsidian" = "write"
".out-of-code-insights" = "write"
"test-workspace" = "write"

"markdown-it-digit" = "write"
"vscode-markdown-digit" = "write"

この状態ではCodexが正常に起動しました。

最終的なconfig.toml

最終的には、次の設定にしました。

TOML
# .codex/config.toml

approval_policy = "on-request"
default_permissions = "workspace-projects"

[permissions.workspace-projects]
description = "ワークスペース内の指定プロジェクトと管理フォルダだけを操作する"
extends = ":workspace"

[permissions.workspace-projects.filesystem]
":minimal" = "read"

[permissions.workspace-projects.filesystem.":workspace_roots"]

# ワークスペース全体はデフォルトで読み取り専用
"." = "read"

# ワークスペース管理
"Obsidian" = "write"
".out-of-code-insights" = "write"
"test-workspace" = "write"

# 開発対象
"markdown-it-digit" = "write"
"vscode-markdown-digit" = "write"

この構成では、

Markdown
必要最低限の領域
→ read

ワークスペース全体
→ read

管理用フォルダ
→ write

開発対象プロジェクト
→ write

となります。

指定していないファイルも参照はできますが、書き込み対象は必要なフォルダだけに限定できます。

今回の調査で分かったこと

AGENTS.mdのエラーでもAGENTS.mdが原因とは限らない

今回、特に時間がかかったのはエラーメッセージです。

Bash
failed to load AGENTS.md instructions

と表示されるため、最初はどうしても、

Markdown
AGENTS.mdのパス
AGENTS.mdのACL
文字コード
親フォルダ

などを疑います。

しかし実際には、Permission Profileによってファイルシステムへのアクセスが拒否され、その結果としてAGENTS.mdの探索処理が失敗していました。

つまり、

Markdown
AGENTS.mdを読み込めない

は表面上のエラーで、

Markdown
AGENTS.mdを探すために必要なファイルシステムアクセスが拒否された

というケースもあります。

Codexの初期化エラーを調査するときは、対象ファイルだけでなくSandboxやPermission Profileまで確認した方がよさそうです。

権限設定は一つずつ戻して確認する

今回の調査では、最終的に設定をほぼすべて外し、一つずつ戻す方法が最も有効でした。

Markdown
設定をすべて外す
↓
正常起動を確認

カスタムProfileだけ追加
↓
失敗

extends = ":workspace"を追加
↓
成功

:minimal = read
↓
成功

workspace root = deny
↓
失敗

workspace root = read
↓
成功

最初から複数の原因候補を追うより、正常に動く最小構成を作ってから設定を追加していく方が、Permission Profileのような複雑な設定では切り分けやすくなります。

まとめ

今回のAGENTS.md読み込みエラーは、AGENTS.md自体ではなく、CodexのPermission Profile設定が原因でした。

特に重要だったのは次の2点です。

Markdown
カスタムPermission Profile
→ extends = ":workspace" を設定する

ワークスペースルート
→ denyではなくreadを基本にする

最終的には、

Markdown
ワークスペース全体は読み取り可能
必要な管理フォルダと開発プロジェクトだけ書き込み可能

という構成に落ち着きました。

権限をできるだけ狭くしたい場合でも、Codex自身がセッション初期化時にワークスペースを探索することを考慮する必要があります。

今回のようにfailed to load AGENTS.mdとos error 5が同時に出た場合は、AGENTS.mdだけでなく、カスタムPermission Profileの継承設定とワークスペースルートのread権限も確認する価値があります。

この記事が参考になりましたら、
上記の「いいね」を押していただけると嬉しいです😄
今後の記事作りの励みになります！
開発ログ
Codex TOML Windows
目次