把重複使用的工具設定保存下來

前幾篇已在 AGENTS.md 寫下可修改範圍、禁止操作與沙箱（Sandbox）規則，這些規則會讓 Codex 了解專案要求。開發者若希望每次啟動都採用固定沙箱、批准政策、網路限制與環境變數篩選，就需要使用 Codex 設定檔（Configuration File）。

本機 Codex 的個人設定放在 ~/.codex/config.toml。Codex CLI 與整合開發環境（Integrated Development Environment, IDE）會共用這些設定。信任的儲存庫也可以在儲存庫中加入 .codex/config.toml，保存只適用於該專案或子目錄的設定。

設定 Profile 是一份具名設定。啟動 Codex 時輸入 --profile，就能在個人預設值上疊加該任務需要的設定。補測試與更新文件可以使用不同 Profile，開發者不用每次重新輸入一串旗標，也能從 /status 確認目前採用的工作方式。

AGENTS.md、config 與 Profile 各自管理一層

AGENTS.md 適合記錄專案內長期有效的規則，例如目錄責任、測試命令、程式風格、禁止修改區域及完成條件。Codex 進入儲存庫後會讀取這些指示，並在規劃與修改時遵守它們。

config.toml 控制工具如何運作，例如批准政策、檔案系統權限、命令的網路權限、搜尋模式與環境變數傳遞。這些設定會直接影響本機命令可存取的資源。若專案規則禁止讀取 .env，設定檔也可以透過 deny 規則施加技術限制。

設定 Profile 用來選擇某一種任務姿態，例如 test-task 或 docs-task。Profile 可以指定要啟用哪一個權限 Profile。test-task 允許寫入程式與測試目錄，docs-task 只開放文件路徑。命令名稱與驗證步驟仍由 AGENTS.md、Codex 命令規則及本次提示詞（Prompt）共同限制。

先看懂設定的套用順序

Codex config 的優先順序，從高到低依序是命令列旗標與 --config、專案 .codex/config.toml、透過 --profile 選取的設定檔、個人 ~/.codex/config.toml、組織提供的預設值、系統設定與內建預設值。

同一個鍵出現在多層時，較高層的值會生效。例如個人設定採用 approval_policy = "on-request"，命令列若加入 --ask-for-approval never，該次工作階段會使用命令列的設定值。組織另外施加的必要條件仍可能禁止寬鬆設定，讓個人層無法解除管理限制。

專案設定只有在儲存庫被信任時才會載入。Codex 會從專案根目錄走到目前工作目錄，依序載入沿途的 .codex/config.toml，距離目前目錄較近的設定優先。

遇到結果和預期不一致時，可輸入 /debug-config 查看載入層次，再用 /status 檢查有效模型、批准政策與可寫入位置。

設定 Profile 與權限 Profile 名稱相近

設定 Profile 是位於 ~/.codex/ 的獨立 TOML 檔。例如 ~/.codex/test-task.config.toml 對應 codex --profile test-task。 每一個 Profile 都要使用獨立檔案，並把設定鍵直接放在頂層。

權限 Profile（Permission Profile）則定義本機命令可以讀寫哪些路徑，以及是否能存取網路。它寫在 [permissions.<名稱>] 下，再由 default_permissions 選取。

內建值包含唯讀的 :read-only、可寫入工作區的 :workspace，以及移除本機沙箱限制的 :danger-full-access。

本篇會在個人 config.toml 定義 test-task 與 docs-task 兩組權限，再建立同名的設定 Profile 選用它們。相同名稱能讓用途清楚可辨，兩者仍是不同設定層。權限 Profile 目前屬於測試功能，之後 Codex 的版本更新後應重新核對可用語法與實際邊界。

在個人 config 定義兩種權限範圍

先開啟 ~/.codex/config.toml。若檔案已存在，保留原有模型、登入及其他設定，只加入本篇需要的批准政策與權限區塊。權限 Profile 不會和舊式 sandbox_mode、sandbox_workspace_write 組合使用，因此要先確認載入的其他設定層沒有這些鍵。

approval_policy = "on-request"
web_search = "disabled"

[permissions.test-task]
description = "修改程式與測試，使用既有本機測試命令，禁止網路。"

[permissions.test-task.filesystem]
":minimal" = "read"
":tmpdir" = "write"

[permissions.test-task.filesystem.":workspace_roots"]
"." = "read"
"src" = "write"
"test" = "write"
"fixtures" = "read"
".env" = "deny"
".env.*" = "deny"

[permissions.test-task.network]
enabled = false

[permissions.docs-task]
description = "只更新專案文件，禁止網路。"

[permissions.docs-task.filesystem]
":minimal" = "read"
":tmpdir" = "write"

[permissions.docs-task.filesystem.":workspace_roots"]
"." = "read"
"README.md" = "write"
"docs" = "write"
".env" = "deny"
".env.*" = "deny"

[permissions.docs-task.network]
enabled = false

test-task 可以讀取整個工作區，寫入範圍限於 src/ 與 test/，fixtures/ 維持唯讀。docs-task 只允許修改 README.md 與 docs/。兩組都禁止讀取常見環境檔，也關閉命令的網路存取。實際目錄名稱應和專案的結構一致。

建立 test-task 與 docs-task 設定 Profile

接著在 ~/.codex/ 建立兩個獨立檔案。設定 Profile 只放相對於個人預設值需要改變的內容。這次各自選取同名權限 Profile，批准政策保持 on-request，讓超出技術邊界的要求停下來交給使用者判斷。

~/.codex/test-task.config.toml 的內容如下：

default_permissions = "test-task"
approval_policy = "on-request"
web_search = "disabled"

~/.codex/docs-task.config.toml 的內容如下：

default_permissions = "docs-task"
approval_policy = "on-request"
web_search = "disabled"

Profile 沒有另外指定模型，代表兩種任務都沿用個人 config.toml 的模型設定。目前並不開放網路、連接器或正式環境。若 config.toml 原有 sandbox_mode，應先停止並選擇一套權限機制，避免舊式 Sandbox 設定使 default_permissions 無法生效。

先驗證設定有沒有正確載入

進入 codex-hands-on 儲存庫後，先用 test-task Profile 啟動 Codex。開啟工作階段後輸入 /debug-config，確認個人設定與 test-task.config.toml 都已載入。接著輸入 /status，核對目前權限名稱、批准政策及工作區位置。

codex --profile test-task

結束該工作階段，再使用 docs-task Profile 重複檢查。兩次啟動都不需要先修改任何檔案。若 Codex 顯示無法辨識的鍵、找不到 Profile，或實際權限仍採用舊式 sandbox_mode，先依啟動畫面與 /debug-config 找出設定來源。

codex --profile docs-task

也可以加上 --strict-config 啟動，讓無法辨識的設定鍵直接造成錯誤。這項檢查適合在第一次建立或升級版本後使用，可以避免拼錯的鍵被略過，導致工作階段採用與預期不同的預設值。

用 test-task Profile 執行補測試任務

使用 test-task 開啟同一個儲存庫後，先要求 Codex 讀取 AGENTS.md，再處理一個範圍固定的測試任務。我們繼續沿用標籤統計功能，補上同一筆議題中重複標籤只能計算一次的測試。任務允許修改 test/，先不改 src/，也不安裝套件。

請先讀取 AGENTS.md 與標籤統計相關測試，確認目前測試命令及 fixture 使用方式。

只新增一個測試案例：同一筆議題的 labels 為 bug、bug、security 時，bug 應計算 1 次，security 應計算 1 次。

本輪只修改直接相關的 test/ 檔案，不修改 src/、fixtures/、README.md、套件、設定與部署檔案。使用既有資料結構建立測試資料，不連線網路。

完成後執行直接相關測試，顯示 git diff 與測試結果。
若目前實作無法通過新測試，保留失敗結果並說明原因，不修改產品程式。

這次執行用來確認 test-task 能讀取程式、修改測試及執行既有命令。若 Codex 嘗試修改 README.md 或 .env，檔案系統權限應阻止寫入或讀取。若測試需要下載套件，網路權限也應阻止命令直接連線。

用 docs-task Profile 執行文件任務

保留前一個工作階段的測試差異，先完成審查或依專案流程回復，使工作目錄回到可辨識狀態。接著使用 codex --profile docs-task 啟動新工作階段，執行一個只更新 README 的任務。

請先讀取 AGENTS.md、README.md 與現有標籤統計測試，確認目前支援的行為。

只修改 README.md，在既有命令列使用說明中補上一個重複標籤的輸入範例，並寫明同一筆議題中的相同標籤只計算一次。

不要修改 src/、test/、fixtures/、套件、設定或部署檔案，不要執行安裝、網路與發布命令。完成後只顯示 git diff -- README.md，並說明文件內容引用了哪一個現有測試作為依據。

docs-task 可以讀取測試取得證據，寫入位置則限於 README.md 與 docs/。Codex 若發現程式行為與文件描述不一致，應回報差異，不能直接修改 src/ 或 test/。這個停點能讓文件任務維持單一責任。

檢查兩次任務是否真的使用不同邊界

兩個任務完成後，分別保存 /status 摘要、實際修改檔案、執行命令及未完成項目。test-task Profile 的差異應只出現在 test/。docs-task Profile 的差異應只出現在 README.md。任何超出範圍的修改都要先確認設定是否載入，以及提示詞與 AGENTS.md 是否存在衝突。

設定檔固定技術邊界，AGENTS.md 提供專案命令與工作規則，提示詞則描述當次目標。三層內容一致時，Codex 就可以在允許範圍內連續執行。其中一層較嚴格時，工作應停在較小的邊界內。

Profile 不能取代差異審查與測試結果，完成後仍要由開發者確認產出。

Profile 適合保存會重複使用的任務姿態。新增 Profile 前，先確認它是否對應穩定且常用的工作，例如補測試、文件維護或唯讀審查。

設定內容改變時，也要重新執行 /debug-config、/status 與一個低風險任務，確認名稱、權限與實際行為仍然一致。

參考資料：

• Codex 設定基礎