Codex 核心概念：Agent、Sandbox、Approval、AGENTS.md、Memory 與 Chronicle

本文主要面向剛開始使用 Codex 的開發(fā)者。本文不講安裝流程，重點解釋幾個最容易混淆的核心概念：Codex 到底是什么、為什么會被權(quán)限攔住、什么時候需要審批、項目規(guī)則應該寫在哪里，以及 Memory / Chronicle 適合解決什么問題。

1. 背景

很多開發(fā)者第一次使用 Codex 時，會遇到類似情況：

• 讓它改文件，它提示權(quán)限不夠；
• 讓它聯(lián)網(wǎng)查資料，它停下來請求確認；
• 讓它處理項目外的文件，它無法直接訪問；
• 讓它按團隊習慣寫代碼，它沒有完全遵守項目約定。

這些行為看起來像“不穩(wěn)定”，實際大多和 Codex 的幾個基礎機制有關：

• Agent：Codex 是能執(zhí)行任務的編程代理，不只是聊天機器人；
• Sandbox：限制 Codex 能讀寫哪些文件、能執(zhí)行哪些操作；
• Approval：控制高風險或越界操作是否需要用戶確認；
• AGENTS.md：給 Codex 的項目級規(guī)則說明；
• Memory：用于保存?zhèn)€人偏好和長期經(jīng)驗；
• Chronicle：用于增強當前屏幕和任務上下文。

理解這些概念后，再使用 Codex 做代碼修改、測試修復、項目分析，會更容易判斷問題出在哪里。

2. Codex 為什么不是普通聊天機器人

普通聊天機器人通常負責“回答問題”。你問它一段代碼怎么寫，它給你一段代碼；你問某個報錯可能是什么原因，它給你幾個排查方向。

Codex 的定位更接近編程代理，也就是 Agent。

它的工作方式不是只回答，而是可以圍繞一個目標完成閉環(huán)：

1. 讀取項目文件；
2. 分析代碼和報錯；
3. 修改相關文件；
4. 執(zhí)行命令或測試；
5. 根據(jù)結(jié)果繼續(xù)調(diào)整；
6. 最后給出變更說明。

可以把區(qū)別理解成：

因此，Codex 的關鍵價值不只是“會生成代碼”，而是能在代碼庫里完成從分析到驗證的任務閉環(huán)。

3. Agent：從回答問題到執(zhí)行任務

Agent 可以理解為“帶目標執(zhí)行能力的助手”。

當你給 Codex 一個任務時，它通常會經(jīng)歷這樣的過程：

理解目標 -> 讀取上下文 -> 執(zhí)行動作 -> 查看結(jié)果 -> 繼續(xù)修正

這和普通問答最大的區(qū)別是：Codex 會動手。

例如你輸入：

修復當前項目里失敗的單元測試。

一個典型的 Agent 流程可能是：

1. 先查看測試失敗輸出；
2. 找到相關測試文件；
3. 閱讀被測代碼；
4. 修改最小必要代碼；
5. 重新運行測試；
6. 如果仍失敗，繼續(xù)分析；
7. 最后說明修改了什么。

這也是為什么 Codex 需要權(quán)限控制。它不僅能給建議，還可能真正修改文件、執(zhí)行命令。如果沒有邊界，風險會比普通聊天機器人高得多。

4. Sandbox：限制 Codex 的操作邊界

Sandbox 可以理解為 Codex 的操作圍欄。它決定 Codex 能訪問哪里、能不能寫文件、能不能執(zhí)行某些命令。

常見沙箱模式可以這樣理解：

如果 Codex 無法修改文件，先不要直接判斷它“沒執(zhí)行”。更合理的排查順序是：

1. 當前是不是 read-only；
2. 要修改的文件是否在工作區(qū)內(nèi)；
3. 命令是否需要訪問工作區(qū)外資源；
4. 是否需要聯(lián)網(wǎng)或訪問系統(tǒng)級路徑。

對大多數(shù)日常開發(fā)任務來說，workspace-write 是比較合適的默認選擇。

5. Approval：控制高風險操作是否需要確認

Sandbox 和 Approval 容易被混在一起，但它們解決的是兩個問題。

• Sandbox：這件事能不能做；
• Approval：做之前要不要問用戶。

例如，當前環(huán)境是只讀模式，Codex 想創(chuàng)建一個文件：

1. Sandbox 先判斷：寫文件超出了只讀模式；
2. Approval 再判斷：是否允許請求用戶授權(quán)；
3. 如果需要確認，Codex 會停下來說明原因；
4. 用戶確認后，Codex 才能繼續(xù)。

比較穩(wěn)妥的日常組合是：

workspace-write + on-request

這個組合的含義是：

• 工作區(qū)內(nèi)的普通讀寫可以正常進行；
• 涉及聯(lián)網(wǎng)、工作區(qū)外路徑、高風險命令時，先請求確認；
• 既不會每一步都打斷，也不會完全放開權(quán)限。

不建議在不熟悉的項目里直接使用高權(quán)限模式，尤其是項目中包含 .env、密鑰、生產(chǎn)配置、客戶數(shù)據(jù)時。

6. AGENTS.md：項目級規(guī)則應該寫在這里

AGENTS.md 可以理解為給 Codex 的項目入職手冊。

項目里的很多約定不適合每次都在對話里重復，例如：

• 使用什么包管理工具；
• 修改代碼后運行什么測試；
• 新增模塊放在哪個目錄；
• 命名規(guī)范是什么；
• 哪些文件不能修改。

這些內(nèi)容適合沉淀到 AGENTS.md。

一個簡單示例：

# Project Instructions
## Build and Test
- After changing Kotlin code, run the related module tests.
- Do not modify `.env`, signing files, or CI configuration unless explicitly requested.
## Structure
- New Android screens should be placed under the matching feature module.
- ViewModel classes must end with `ViewModel`.

AGENTS.md 不需要寫得很長。重點是具體、可執(zhí)行、可驗證。

推薦寫入：

不推薦寫入：

• 大段背景介紹；
• 與項目無關的個人偏好；
• 模糊規(guī)則，例如“代碼要優(yōu)雅”；
• 密鑰、token、賬號密碼。

如果 Codex 經(jīng)常犯同一個項目級錯誤，不要只在對話里糾正一次，更應該把規(guī)則補進 AGENTS.md。

7. Memory 與 Chronicle：長期記憶和當前上下文

Memory 和 Chronicle 都和上下文有關，但適用范圍不同。

可以按下面方式區(qū)分：

關鍵規(guī)則應該放在 AGENTS.md，而不是只依賴 Memory。

原因是：

• AGENTS.md 跟項目走；
• Memory 更像個人習慣補充；
• 項目協(xié)作中，規(guī)則應該明確、可見、可審查。

Chronicle 能增強 Codex 對當前工作狀態(tài)的理解，但也意味著它可能接觸更多屏幕上下文。處理包含密鑰、客戶數(shù)據(jù)、內(nèi)部文檔的場景時，需要謹慎開啟。

8. 最小實驗：觀察沙箱如何攔截寫文件

下面用一個最小實驗觀察 Sandbox 和 Approval 的效果。

創(chuàng)建一個空目錄并啟動 Codex：

mkdir -p ~/codex-demo
cd ~/codex-demo
codex

Windows PowerShell 可以使用：

mkdir ~/codex-demo
cd ~/codex-demo
codex

進入 Codex 后，切換到只讀或最嚴格權(quán)限模式：

/permissions

然后輸入：

幫我新建一個 hello.txt，里面寫一行 hello codex。

如果當前是只讀模式，創(chuàng)建文件會被攔截，因為這是寫操作。此時你應該能看到 Codex 說明它需要更高權(quán)限，或者請求你確認。

再切換到工作區(qū)可寫模式，讓它重新創(chuàng)建文件。如果文件位于當前工作區(qū)內(nèi)，這次應該可以正常完成。

這個實驗可以幫助你直觀看到：

• Sandbox 如何限制寫文件；
• Approval 如何在越界操作前介入；
• 同一個任務在不同權(quán)限模式下行為不同。

9. 實際使用建議

使用 Codex 時，可以按下面順序檢查：

如果你發(fā)現(xiàn) Codex “不聽話”，可以優(yōu)先排查：

1. 是否權(quán)限不足；
2. 是否任務超出了工作區(qū)；
3. 是否沒有寫清項目規(guī)則；
4. 是否把長期偏好和項目約束混在一起；
5. 是否要求它執(zhí)行了需要審批的操作。

10. 總結(jié)

Codex 的核心不是“更會聊天”，而是能圍繞代碼庫完成任務閉環(huán)。

這也決定了使用它之前必須理解邊界：

• Agent 決定它能執(zhí)行任務；
• Sandbox 決定它能碰哪里；
• Approval 決定越界時是否詢問；
• AGENTS.md 承載項目規(guī)則；
• Memory 承載個人偏好；
• Chronicle 增強當前上下文。

一句話總結(jié)：邊界越清楚，自動化越可靠。

以上就是Codex 不聽話?一文帶你搞懂5大Codex的核心概念的詳細內(nèi)容，更多關于Codex核心概念介紹的資料請關注腳本之家其它相關文章！

最新評論