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

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

1. 背景

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

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

這些行為看起來像“不穩(wěn)定”，實(shí)際大多和 Codex 的幾個(gè)基礎(chǔ)機(jī)制有關(guān)：

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

理解這些概念后，再使用 Codex 做代碼修改、測(cè)試修復(fù)、項(xiàng)目分析，會(huì)更容易判斷問題出在哪里。

2. Codex 為什么不是普通聊天機(jī)器人

普通聊天機(jī)器人通常負(fù)責(zé)“回答問題”。你問它一段代碼怎么寫，它給你一段代碼；你問某個(gè)報(bào)錯(cuò)可能是什么原因，它給你幾個(gè)排查方向。

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

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

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

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

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

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

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

當(dāng)你給 Codex 一個(gè)任務(wù)時(shí)，它通常會(huì)經(jīng)歷這樣的過程：

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

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

例如你輸入：

修復(fù)當(dāng)前項(xiàng)目里失敗的單元測(cè)試。

一個(gè)典型的 Agent 流程可能是：

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

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

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

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

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

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

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

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

5. Approval：控制高風(fēng)險(xiǎn)操作是否需要確認(rèn)

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

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

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

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

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

workspace-write + on-request

這個(gè)組合的含義是：

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

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

6. AGENTS.md：項(xiàng)目級(jí)規(guī)則應(yīng)該寫在這里

AGENTS.md 可以理解為給 Codex 的項(xiàng)目入職手冊(cè)。

項(xiàng)目里的很多約定不適合每次都在對(duì)話里重復(fù)，例如：

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

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

一個(gè)簡(jiǎn)單示例：

# 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ǎng)。重點(diǎn)是具體、可執(zhí)行、可驗(yàn)證。

推薦寫入：

不推薦寫入：

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

如果 Codex 經(jīng)常犯同一個(gè)項(xiàng)目級(jí)錯(cuò)誤，不要只在對(duì)話里糾正一次，更應(yīng)該把規(guī)則補(bǔ)進(jìn) AGENTS.md。

7. Memory 與 Chronicle：長(zhǎng)期記憶和當(dāng)前上下文

Memory 和 Chronicle 都和上下文有關(guān)，但適用范圍不同。

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

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

原因是：

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

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

8. 最小實(shí)驗(yàn)：觀察沙箱如何攔截寫文件

下面用一個(gè)最小實(shí)驗(yàn)觀察 Sandbox 和 Approval 的效果。

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

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

Windows PowerShell 可以使用：

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

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

/permissions

然后輸入：

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

如果當(dāng)前是只讀模式，創(chuàng)建文件會(huì)被攔截，因?yàn)檫@是寫操作。此時(shí)你應(yīng)該能看到 Codex 說明它需要更高權(quán)限，或者請(qǐng)求你確認(rèn)。

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

這個(gè)實(shí)驗(yàn)可以幫助你直觀看到：

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

9. 實(shí)際使用建議

使用 Codex 時(shí)，可以按下面順序檢查：

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

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

10. 總結(jié)

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

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

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

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

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

最新評(píng)論