權限決定 Codex 能把任務做到哪裡

Codex 接到任務後，會先讀取專案，再修改檔案、執行測試及查看差異。這些動作各自需要不同權限。權限界線如果沒有先寫清楚，代理人遇到安裝套件、存取網路或建立 Git 提交時，開發者就得臨時判斷，任務也可能在不合適的位置中斷。

權限模型可以分成五類：可讀取範圍、可寫入範圍、可直接執行的命令、需要人工批准的命令，以及禁止操作。

這五類共同回答一個問題：Codex 在目前任務中可以自主前進到哪一步，遇到哪些邊界必須停下來，將決定權交還給開發者。

今天繼續沿用 codex-hands-on 專案，在根目錄的 AGENTS.md 加入一份權限規則。這次練習只修改這個檔案，不安裝套件、不建立提交，也不變更 Codex 的全域設定。

完成後，我們可以透過安全的查詢與模擬要求，確認這份規則是否足以引導後續工作。

沙箱與批准分別控制不同關卡

Codex 沙箱（Sandbox）是執行環境的技術邊界，會限制代理人能讀寫哪些位置、能否存取網路，以及 Git、套件管理器與測試程序可以碰到哪些資源。批准政策（Approval Policy）則決定 Codex 何時停下來，要求使用者同意跨越目前邊界的動作。

常用的 workspace-write 模式允許 Codex 在工作區內讀取檔案、修改檔案，並執行一般本機命令。寫入工作區外或使用網路時，會觸發批准。read-only 適合探索與審查，檔案修改及部分命令需要批准。danger-full-access 會移除檔案系統與網路的沙箱限制，這次練習不需要使用。

在 Codex CLI 中，可以輸入 /permissions 查看或選擇目前的權限設定。畫面顯示的是這次工作階段實際採用的邊界。

AGENTS.md 記錄團隊希望 Codex 遵守的操作規則；沙箱、批准政策與命令規則則施加技術限制。兩層內容需要互相配合，敏感目錄仍要由環境權限保護。

讀取權限也需要清楚界線

讀取是 Codex 理解專案的第一步。原始碼、測試、README、套件描述檔與版本控制差異，可以開放讀取，讓代理人建立足夠脈絡。

工作區外的個人目錄、憑證存放處、正式環境設定與資料匯出檔，不應納入一般開發任務的可讀範圍。

「不修改祕密檔案」仍允許代理人看到內容，因此不足以保護金鑰。若 .env、私鑰或雲端憑證含有敏感資料，應透過沙箱、檔案權限或隔離環境阻止讀取。提示與 AGENTS.md 可以補上「不得讀取、輸出或摘要祕密」的規則，降低代理人主動搜尋敏感內容的機率。

本篇範例允許讀取儲存庫內的程式碼、測試與文件，同時禁止讀取 .env*、secrets/、私鑰及工作區外路徑。若測試必須使用環境變數，應由受控環境注入測試專用值，不要要求 Codex 開啟正式環境的憑證檔案。

寫入範圍要對應任務責任

寫入權限決定 Codex 可以留下哪些變更。任務處理應用程式與測試時，可以將 src/、test/ 設為可修改目錄。文件任務則明確加入 README.md。範圍要依儲存庫實際結構調整，避免使用「修改需要的所有檔案」這類邊界不清的描述。

有些檔案位於工作區內，仍適合列為禁止修改。例如 .github/workflows/ 會影響自動化流程，部署設定會影響發布環境，鎖定檔則可能一次改變大量相依套件。

這些檔案若需要調整，可以先由 Codex 說明原因、預計差異與驗證方式，再等待開發者針對該次任務授權。

本篇只授權修改根目錄的 AGENTS.md，因為固定任務是補上權限規則。範例內列出的 src/ 與 test/，是日後一般開發任務可採用的範圍，並不代表這次可以順便修改程式。任務範圍與長期規則同時存在時，較窄的限制應優先套用。

命令依副作用分成三個層級

命令是否能直接執行，可以依它會改變什麼來判斷。git status、git diff 與既有測試命令只讀取專案，或只產生暫時測試輸出，適合列為可直接執行。

即使是常見命令，也要使用專案已定義的參數，避免測試腳本暗中連接正式服務。

安裝或更新相依套件、執行資料庫遷移、建立 Git commit、推送遠端與存取網路，會改變共享狀態、外部資源或相依版本，適合先取得人工批准。

批准要求應包含預計執行的完整命令、原因、影響範圍與回復方法，讓使用者能根據具體內容判斷。

刪除大量檔案、強制推送、改寫共享 Git 歷史、讀取祕密及部署正式環境，可直接列為禁止操作。若專案日後需要其中某項能力，應建立獨立流程與較小的授權範圍，不能把一次批准解讀成長期許可。Codex 的命令規則也可以針對命令前綴設定允許、詢問或禁止。

在 AGENTS.md 補上固定權限規則

先在 codex-hands-on 根目錄開啟既有 AGENTS.md，保留前面章節建立的專案說明、測試命令與程式風格。找到適合位置加入 ## Permissions。若已有同名章節，就更新原章節，避免留下兩套互相衝突的規則。

將以下內容加入檔案。若練習專案的測試指令與範例不同，請把 npm test 換成 AGENTS.md 先前已確認的實際命令。其餘權限保持固定，這次不要延伸修改原始碼、測試或設定檔。

## Permissions

**Read:** Repository source, tests, documentation, package metadata, and Git diffs.

**Write:** `src/`, `test/`, and `README.md` only when the task explicitly requires them. Update `AGENTS.md` only for a requested rules change.

**Run without approval:** `git status`, `git diff`, `git log`, and the documented local test command `npm test`.

**Ask for approval:** Installing or updating dependencies, changing a lockfile, running migrations, accessing the network, creating a commit, or pushing to a remote.

**Do not:** Read or print `.env*`, `secrets/`, private keys, or credentials; modify deployment and CI configuration; deploy or publish; access production data; force-push; rewrite shared Git history; or run destructive deletion commands.

**Scope:** Stay inside the repository. Preserve unrelated user changes and report any required action that falls outside these rules.

若專案既有 AGENTS.md 使用中文，可以改用以下版本。權限範圍與英文版相同，兩個版本擇一加入即可，避免同一份檔案重複維護兩套規則。

## 權限規則

**可讀取：** 儲存庫內的原始碼、測試、文件、套件描述檔與 Git 差異。

**可修改：** 任務有明確要求時，才能修改 `src/`、`test/` 與 `README.md`；只有在任務要求調整專案規則時，才能修改 `AGENTS.md`。

**可直接執行：** `git status`、`git diff`、`git log`，以及文件記載的本機測試命令 `npm test`。

**需人工批准：** 安裝或更新相依套件、修改鎖定檔、執行資料庫遷移、存取網路、建立 Git commit 或推送至遠端。

**禁止操作：** 讀取或輸出 `.env*`、`secrets/`、私鑰與憑證；修改部署及持續整合設定。部署、發布或存取正式環境資料；強制推送、改寫共享 Git 歷史，或執行破壞性刪除命令。

**操作範圍：** 限於目前儲存庫。保留與任務無關的使用者修改；遇到超出規則的必要動作時，先停止並回報。

中文版保留 Read、Write 等分類的完整含義，也讓團隊成員能直接閱讀。命令、路徑與檔名仍使用原始格式，減少翻譯後的解讀差異。

完成後執行 git diff -- AGENTS.md，確認只有預定章節改變，並檢查路徑、測試命令與專案現況一致。

用一個提示詞讓 Codex 執行修改

這次任務可以交給 Codex 完成。先要求它讀取現有規則與專案結構，避免直接貼入不相符的路徑。提示要明確限制單一檔案，並要求修改後只顯示差異與檢查結果，不建立提交。

請先讀取根目錄 AGENTS.md、專案目錄結構與 package.json 中的 scripts，確認目前的原始碼目錄、測試目錄及本機測試命令。

只修改根目錄 AGENTS.md，新增或更新 Permissions 章節，明確寫出：可讀取範圍、可修改範圍、可直接執行命令、需人工批准命令與禁止操作。

禁止讀取或輸出 .env、secrets、私鑰與憑證。不要修改其他檔案，不要安裝套件、建立 commit、連線外部服務或執行任何禁止操作。

完成後執行 git diff -- AGENTS.md，說明每條規則的作用，並列出你未執行的驗證。若實際路徑或測試命令無法確認，先停下來回報。

Codex 若發現 package.json 不存在，應停下來說明無法確認 npm test，不應憑空建立檔案。若工作目錄已有其他變更，也只能保留它們，並將差異限制在 AGENTS.md。

這能同時檢查代理人是否理解任務授權與既有使用者修改的邊界。

驗證規則能否產生可預期行為

先閱讀 git diff -- AGENTS.md，確認五類權限都有明確動詞與目標。像「安全的命令可以執行」仍有解讀空間，改成實際命令名稱後，Codex 才能穩定判斷。禁止項目也要寫出路徑或行為，避免只留下「不要做危險操作」這類抽象句子。

接著開一個新的 Codex 工作階段，請它摘要 AGENTS.md 的權限規則，並說明 git status、npm install、讀取 .env、修改 src/ 各屬於哪一類。

這一步只做分類，不要求代理人安裝套件或讀取敏感檔案。回答應將 git status 判定為可直接執行，將安裝套件判定為需批准，並拒絕讀取 .env。

最後要求 Codex 執行 git status 與 git diff -- AGENTS.md，確認安全命令能正常工作。再請它「提出安裝套件的命令與影響，先不要執行」，觀察它是否停在批准點。

若環境的 /permissions 顯示較嚴格限制，Codex 仍應遵守技術邊界。若環境較寬鬆，AGENTS.md 中的禁止規則仍要被遵守。

批准是一個有內容的決策點

批准不宜只看畫面上的命令名稱。開發者需要確認完整參數、工作目錄、預計寫入位置、網路目標，以及失敗後會留下哪些狀態。

以 npm install 為例，它會修改鎖定檔、下載外部內容，並執行套件腳本，因此應先確認要加入的版本與驗證方式。

一次批准只對當下顯示的動作成立。後續若命令改了參數、目標目錄或遠端位置，Codex 應重新提出請求。

開發者若無法從批准資訊判斷影響，可以拒絕並要求代理人拆小命令、先顯示唯讀檢查結果，或提供不需要擴大權限的處理方案。

完成本篇後，AGENTS.md 會留下一份團隊可閱讀的操作約定，工作階段的沙箱與批准設定則提供可執行的邊界。

每次開始任務時，先確認兩者是否一致，再讓 Codex 讀取、修改及驗證。這能讓代理人在安全範圍內連續工作，也讓超出範圍的動作停在清楚的人工決策點。