Codex AGENTS.md | 全域說明與專案覆蓋 | 智能體設定

Codex 會在開始任何工作前讀取 AGENTS.md 檔案。通過把全域指導和專案級覆蓋層疊起來，你就能在每次開啟任意儲存庫時，都從一致的工作預期開始。

Codex 如何發現這些指導

Codex 啟動時會整理出一條本次執行要使用的指令鏈。這個過程每次執行都會重新執行；在終端介面（TUI）中，通常就是每次新建會話時重新建置。查詢順序如下：

全域層： 先檢查 Codex 主目錄（預設是 ~/.codex，也可以通過 CODEX_HOME 指定）。如果存在 AGENTS.override.md，就使用它；否則再讀取 AGENTS.md。這一層只會採用找到的第一個非空檔案。
專案層： 然後從專案根目錄（通常是 Git 根目錄）一路檢查到當前工作目錄。如果沒有找到專案根，就只檢查當前目錄。沿途每一級目錄都會按 AGENTS.override.md、AGENTS.md、project_doc_fallback_filenames 中定義的備用檔名這一順序查詢；每個目錄最多隻會納入一個檔案。
合併順序： 最後，Codex 會按“從根到當前目錄”的順序把這些檔案拼接起來。越靠近當前目錄的檔案越靠後，因此會覆蓋前面更通用的說明。

空檔案會被跳過。合併後的總大小一旦達到 project_doc_max_bytes 設定的上限（預設 32 KiB），Codex 就不會再繼續加入更多檔案。關於這些參數，參見專案指令發現。如果觸到上限，可以調大限制，或把指令拆到更深一層的目錄中。

建立全域指導

在 Codex 主目錄中建立持久預設值，這樣每個儲存庫都會繼承你的工作約定。

確保目錄存在：
```
mkdir -p ~/.codex
```

建立 ~/.codex/AGENTS.md，寫入可複用偏好：

# ~/.codex/AGENTS.md

## 工作约定

- 修改 JavaScript 文件后，始终运行 `npm test`。
- 安装依赖时优先使用 `pnpm`。
- 添加新的生产依赖前先征求确认。

在任意目錄執行 Codex，確認它已載入該檔案：
```
codex --ask-for-approval never "Summarize the current instructions."
```
預期結果：Codex 會在給出工作建議前，先引用 ~/.codex/AGENTS.md 中的條目。

當你需要臨時性的全域覆蓋，而又不想刪除基礎檔案時，可以使用 ~/.codex/AGENTS.override.md。刪除這個覆蓋檔案後，就會恢復共享指導。

分層組織專案說明

儲存庫級檔案可以讓 Codex 感知專案規範，同時繼續繼承你的全域預設值。

在儲存庫根目錄新增一個 AGENTS.md，寫入基礎約定：

# AGENTS.md

## 仓库通用约定

- 在创建 pull request 前运行 `npm run lint`。
- 修改行为时，在 `docs/` 中记录对外公共工具的变化。

當某些團隊需要不同規則時，在巢狀目錄中新增覆蓋檔案。例如在 services/payments/ 下建立 AGENTS.override.md：

# services/payments/AGENTS.override.md

## 支付服务规则

- 使用 `make test-payments`，不要使用 `npm test`。
- 轮换 API key 前，必须先通知安全频道。

從 payments 目錄啟動 Codex：
```
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
```
預期結果：Codex 會先報告全域檔案，再報告儲存庫根目錄 AGENTS.md，最後報告 payments 目錄下的覆蓋檔案。

Codex 的搜尋會在到達當前目錄時停止，因此應把覆蓋檔案儘量放在靠近專門化工作的地方。

新增全域檔案和 payments 專屬覆蓋檔案後，儲存庫結構範例如下：

AGENTS.md 儲存庫通用約定
services/
- payments/
  
  AGENTS.md 因為存在覆蓋檔案，所以會被忽略
  
  AGENTS.override.md 支付服務規則
  
  README.md
- search/

新增程式碼審查規則

要使用 GitHub 中的 Codex 程式碼審查，請在最靠近規則所轄程式碼的 AGENTS.md 中新增 ## Code Review Rules 章節。儲存庫級檢查放在根目錄檔案中，服務專屬檢查則放在巢狀檔案中。

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

規則應簡潔說明需要標記的行為，以及安全做法或例外；格式和 lint 檢查交給 CI。設定方法和規則編寫建議參見自定義 Codex 的審查重點。

自定義備用檔名

如果你的儲存庫已經在使用其他檔名（例如 TEAM_GUIDE.md），你可以把它加入備用列表，讓 Codex 也把它當作說明檔案。

編輯你的 Codex 設定：

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

重啟 Codex，或者執行一條新的命令，讓更新後的設定被載入。

這樣一來，Codex 就會按以下順序檢查每個目錄：AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。不在這個列表中的檔名不會參與說明檔案發現。更大的位元組上限則允許合併更多指導內容後再截斷。

設定好備用列表後，Codex 會把這些替代檔案也視作說明檔案：

TEAM_GUIDE.md 通過備用列表發現
.agents.md 根目錄中的備用檔案
support/
- AGENTS.override.md 覆蓋備用檔案中的指導
- playbooks/

如果你希望使用不同設定檔，例如某個專案專用的自動化賬號，可以設定 CODEX_HOME 環境變數：

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

預期結果：輸出會列出相對於自定義 .codex 目錄的檔案路徑。

驗證你的設定

在儲存庫根目錄執行 codex --ask-for-approval never "Summarize the current instructions."。正常情況下，Codex 會按優先順序複述全域和專案級指導。
使用 codex --cd subdir --ask-for-approval never "Show which instruction files are active."，確認巢狀目錄中的覆蓋檔案是否成功覆蓋了更上層規則。
如果你需要審計 Codex 實際載入了哪些說明檔案，可以用 codex -c log_dir=./.codex-log 啟用明文 TUI 日誌並檢視 ./.codex-log/codex-tui.log，或者在開啟會話日誌時檢查最近的 session-*.jsonl。
如果說明看起來像是舊的，請在目標目錄裡重啟 Codex。Codex 會在每次執行時重新建置指令鏈，在 TUI 中則是在每次會話開始時重建，所以沒有需要手工清理的快取。

排查發現問題

什麼都沒有載入： 檢查你是否位於目標儲存庫內，並確認 codex status 顯示的工作區根目錄符合預期；同時確認說明檔案不是空檔案。
出現了錯誤指導： 優先檢查目錄樹更高層，或 Codex 主目錄下，是否存在 AGENTS.override.md。
Codex 忽略了備用檔名： 檢查 project_doc_fallback_filenames 是否拼寫正確，並在修改設定後重新啟動 Codex。
指令被截斷： 提高 project_doc_max_bytes，或把大檔案拆到更深層的目錄中。
設定檔混淆： 先執行 echo $CODEX_HOME，確認 Codex 實際讀取的是哪個主目錄。

下一步

來源：</zh-TW/docs/agent-configuration/agents-md> 更新時間：2026-07-10（UTC）

最近搜尋

建議搜尋

文件導覽

使用 AGENTS.md 編寫自定義說明