Codex 小白入門：從安裝到插件、MCP、Skills，一篇把配置講明白

最近老粉絲群里有不少同學一直催我：能不能出一篇 Codex 的基礎(chǔ)教程，不要只講“很強”“很好用”，而是把安裝、配置、插件、Skills、MCP、記憶、連接 App 這些東西一次講清楚。我理解這個需求。

我這邊也有一些AI Coding（SDD Agent AI工具等） 和 Node技術(shù)交流交流群，感興趣的可以加微信 ikoala520  進群，一起學習，共同進步。

因為新手用 Codex 最大的問題，往往不是不會提問，而是不知道 Codex 的“幾層配置”分別管什么。你可能已經(jīng)裝好了 Codex，也能讓它改代碼、寫文章、解釋報錯，但一看到 config.toml、AGENTS.md、MCP、Plugins、Skills、Memory，腦子里馬上變成一團線。這篇文章就解決這件事。

我不會把它寫成官方文檔翻譯，也不會一上來堆一堆參數(shù)。我們按一個小白真正上手的順序來：先裝起來，再讓 Codex 懂你的項目，然后一點點接上插件、MCP、Skills、記憶和 App。

先說明一下：Codex 更新很快。本文寫作時，我本機驗證的 CLI 版本是 codex-cli 0.140.0-alpha.2，時間是 2026 年 6 月 14 日。具體命令以你本機的 codex --help 和官方文檔為準。本文重點講方法和配置思路，命令只是幫你建立第一套可運行的骨架。

你先記住一句話

Codex 不是只有一個聊天框。

更準確地說，它像一個可以被你配置的工作臺：

很多新手一開始容易犯的錯，是把所有東西都塞進 prompt。

比如你每次都對 Codex 說：“請先閱讀項目結(jié)構(gòu)，遵守我們的代碼規(guī)范，運行測試，不要亂改文件，寫完給我總結(jié)。”

這當然能用，但很累。更好的方式是把長期規(guī)則沉淀到 AGENTS.md，把默認行為放到 config.toml，把重復(fù)工作流寫成 Skill，把外部能力交給 MCP 和插件。

這樣 Codex 才會從“一個會回答問題的窗口”，變成“一個適合你工作流的助手”。

第一步：先把 Codex 裝起來

Codex 現(xiàn)在有幾種常見使用方式。

如果你是小白，我建議從 Codex Desktop App + CLI 這套組合開始。桌面 App 適合看插件、連接 App、管理線程；CLI 適合進入具體項目干活。

1. Codex Desktop App 怎么安裝

桌面 App 的官方入口是：

https://developers.openai.com/codex/app

如果你想直接下載安裝包，也可以按系統(tǒng)選擇：

• macOS Apple Silicon：下載 Codex.dmg
• macOS Intel：下載 Codex-latest-x64.dmg
• Windows：通過 Microsoft App Installer 安裝

對應(yīng)直達地址如下：

macOS Apple Silicon:
https://persistent.oaistatic.com/codex-app-prod/Codex.dmg

macOS Intel:
https://persistent.oaistatic.com/codex-app-prod/Codex-latest-x64.dmg

Windows:
https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi

macOS 安裝步驟很簡單：

1. 先確認自己的芯片類型。點左上角蘋果圖標，選擇“關(guān)于本機”，看芯片是 Apple Silicon 還是 Intel。
2. 下載對應(yīng)的 .dmg 文件。
3. 雙擊打開安裝包，把 Codex 拖到 Applications / 應(yīng)用程序。
4. 打開 Codex App，按提示登錄 OpenAI 賬號。
5. 如果 macOS 提示安全確認，在系統(tǒng)設(shè)置里允許打開。

Windows 安裝步驟也類似：

1. 打開 Windows 下載地址。
2. 按 Microsoft Store / App Installer 的提示安裝。
3. 安裝完成后啟動 Codex。
4. 登錄 OpenAI 賬號。
5. 在 App 里檢查插件、連接器和本地工作區(qū)權(quán)限。

如果你已經(jīng)裝了 CLI，也可以在終端里運行：

codex app

這個命令會啟動 Codex Desktop App。如果本機還沒裝 App，它會引導你去安裝。

2. Codex CLI 怎么安裝

CLI 的官方入口是：

https://developers.openai.com/codex/cli

現(xiàn)在更推薦用官方 standalone installer。macOS / Linux 可以這樣安裝：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows PowerShell 可以這樣安裝：

irm https://chatgpt.com/codex/install.ps1 | iex

如果你習慣用包管理器，也可以選下面幾種方式：

# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex

如果你想手動下載二進制文件，可以去 GitHub Releases：

https://github.com/openai/codex/releases

裝好 CLI 以后，先跑這幾個命令：

codex --version
codex login
codex doctor

codex login 用來登錄賬號。

codex doctor 用來檢查本地安裝、配置、認證和運行時健康狀態(tài)。新手遇到“為什么不能用”“為什么工具不生效”“為什么 MCP 連接不上”時，先跑它，比直接猜原因靠譜。

你還可以看完整命令：

codex --help

我本機看到的常用命令包括：

你不用一開始全記住。小白階段只要記?。?/p>

codex
codex login
codex doctor
codex --help

夠用了。

第二步：理解AGENTS.md

如果只能先學一個配置文件，我建議先學 AGENTS.md。

它的作用很簡單：告訴 Codex，這個項目該怎么工作。

比如項目怎么啟動、怎么測試、代碼風格是什么、哪些目錄不要亂動、提交前要跑什么命令、回答時要注意什么。你可以把它理解成“寫給 AI 同事看的項目說明書”。

一個最小版本可以這樣寫：

# AGENTS.md

## Project overview

This is a Next.js project. The main app is in `apps/web`.

## Common commands

- Install dependencies: `pnpm install`
- Start dev server: `pnpm dev`
- Run typecheck: `pnpm typecheck`
- Run tests: `pnpm test`

## Coding rules

- Follow existing file structure and naming style.
- Prefer small, focused changes.
- Do not rewrite unrelated files.
- Do not add new dependencies unless necessary.

## Verification

Before saying the task is complete, run the relevant check:

- UI changes: run `pnpm typecheck`
- Logic changes: run related tests
- Large changes: run `pnpm test`

If a command was not run, say it clearly.

這里最關(guān)鍵的不是寫得多，而是寫得準。

我建議你在 AGENTS.md 里優(yōu)先放四類內(nèi)容：

有的小伙伴可能會問：這些東西為什么不直接寫在 prompt 里？

因為 prompt 是臨時的，AGENTS.md 是長期的。你今天讓 Codex 改登錄，明天讓它改列表，后天讓它寫測試，這些任務(wù)都應(yīng)該遵守同一套項目規(guī)矩。把規(guī)矩寫進 AGENTS.md，后面就不用每次重復(fù)念一遍。

第三步：理解config.toml

AGENTS.md 管“項目規(guī)矩”，config.toml 管“Codex 自己怎么運行”。

最常見的位置是：

~/.codex/config.toml

它通常用來配置模型、沙箱、審批策略、MCP、profile、環(huán)境變量策略等內(nèi)容。

你也可以臨時覆蓋配置。比如 CLI 幫助里可以看到這種寫法：

codex -c model=\"o3\"
codex -c 'sandbox_permissions=[\"disk-full-read-access\"]'
codex -c shell_environment_policy.inherit=all

這說明一個重要思路：config.toml 是長期默認值，-c 是本次臨時覆蓋。

小白階段，不建議一上來改很多。你可以先理解這幾個配置方向：

舉個偏保守的理解方式：

# ~/.codex/config.toml

# 示例：按你賬號和當前 Codex 版本可用模型調(diào)整
model = "o3"

# 新手建議不要急著開到最高權(quán)限。
# 真正需要全權(quán)限時，再在可信項目里單獨開啟。
sandbox_mode = "workspace-write"

# 是否需要人工確認，取決于你的使用場景。
# 日常交互可以保守一點，自動化腳本可以更明確地限制。
approval_policy = "on-request"

不同版本字段可能會有變化。如果你打開后發(fā)現(xiàn)字段名不一樣，不要慌，先看：

codex --help
codex doctor

以及你當前 Codex 版本對應(yīng)的官方文檔。

這里有一個很實用的經(jīng)驗：別把新手配置成 danger-full-access 起步。

danger-full-access 很強，但也意味著 Codex 執(zhí)行命令時擁有非常大的文件系統(tǒng)權(quán)限。它適合你非常信任當前工作區(qū)、并且知道自己在做什么的場景。剛開始用的時候，先用較保守的沙箱和審批策略，熟悉之后再逐步放開。

第四步：Plugins 是什么

很多人聽到插件，以為就是“多一個按鈕”。

在 Codex 里，插件更像一個能力包。一個插件里可能包含：

• 一個或多個 Skills
• MCP server 配置
• App / Connector 能力
• 腳本、資源、模板
• 插件自己的說明和元數(shù)據(jù)

你可以用命令查看插件相關(guān)能力：

codex plugin --help

常見子命令包括：

codex plugin list
codex plugin add <plugin>
codex plugin remove <plugin>
codex plugin marketplace list

安裝插件時，命令形態(tài)大概是：

codex plugin add sample@debug
codex plugin add sample --marketplace debug

如果你使用桌面 App，也可以在插件入口里搜索、安裝、啟用。

小白階段，我不建議你一口氣裝一堆插件。你可以按工作流選：

插件的價值，不是“看起來很高級”，而是讓 Codex 能接觸真實材料、調(diào)用真實工具、交付真實文件。

比如你裝了 GitHub 相關(guān)插件后，它不只是告訴你“應(yīng)該怎么 review”，而是可以讀取 PR、看評論、查 CI、給出修改建議。你裝了 Presentations，它不只是寫 PPT 文案，而是能生成真正的演示稿文件。

這就是插件和普通 prompt 的差別。

第五步：Skills 是什么

Skills 很適合小白理解成：把一套固定做事方法寫成文件。

比如你經(jīng)常寫公眾號文章，每次都要經(jīng)歷：

1. 定選題
2. 查資料
3. 搭大綱
4. 寫初稿
5. 做配圖
6. 預(yù)覽
7. 改節(jié)奏

如果每次都在 prompt 里說一遍，很麻煩。你可以把這套流程寫成一個 SKILL.md，以后只要任務(wù)匹配，Codex 就能按這個方法走。

Codex 的Skills 的位置在 ，注意是在這里~/.codex/skills

一個 Skill 通常長這樣：

---
name: ai-article-writer
description: Use when writing long-form AI technical articles.
---

# AI Article Writer

## Workflow

1. Clarify the target reader and article angle.
2. Collect reliable references.
3. Propose title options and outline.
4. Draft the article in Markdown.
5. Add diagrams when useful.
6. Render a local preview.
7. Review readability before final delivery.

注意，Skill 不是單純的 prompt 模板。

它更像一套“操作規(guī)程”。好的 Skill 會告訴 Codex：

那 Skill 和 AGENTS.md 有什么區(qū)別？

很簡單：

比如“這個項目用 pnpm，不要用 npm”，應(yīng)該放 AGENTS.md。

比如“寫公眾號文章前必須先做選題定位，再寫大綱”，應(yīng)該放 Skill。

第六步：MCP 是什么

MCP 全稱是 Model Context Protocol。你可以先不用記英文，只要記住它解決的問題：

讓 Codex 通過標準協(xié)議連接外部工具和數(shù)據(jù)源。

比如：

在 CLI 里可以用：

codex mcp --help

我本機看到的常用子命令包括：

codex mcp list
codex mcp get <name>
codex mcp add <name> --url <url>
codex mcp add <name> -- <command>
codex mcp remove <name>
codex mcp login <name>
codex mcp logout <name>

添加 MCP server 有兩種常見方式。

第一種是 HTTP 方式：

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

第二種是本地命令方式：

codex mcp add my-tool -- node server.js

如果需要環(huán)境變量，也可以看到類似這種形式：

codex mcp add my-tool --env API_KEY=$MY_TOOL_API_KEY -- node server.js

實際使用時，不建議把真實密鑰直接寫在命令里。更好的方式是放在環(huán)境變量中，或者使用 Codex / MCP 支持的安全配置方式。

如果以上cli你都不喜歡，也可以通過codex桌面端安裝和使用mcp

小白理解 MCP，可以抓住一個判斷標準：

凡是 Codex 需要讀取外部系統(tǒng)、調(diào)用外部工具、訪問實時數(shù)據(jù)，就優(yōu)先想 MCP 或 App Connector。

不要讓模型憑記憶回答你的私有數(shù)據(jù)。

比如你問：“我們項目最近哪個 PR 沒過 CI？”

這類問題不應(yīng)該讓 Codex 猜，也不應(yīng)該讓你復(fù)制粘貼一堆網(wǎng)頁內(nèi)容。更合理的方式是接 GitHub，然后讓 Codex 直接讀取真實 PR 和檢查結(jié)果。

第七步：Memory 記憶功能怎么用

Memory 很容易被誤解。

它不是讓 Codex 記住所有事實，也不是你的私人數(shù)據(jù)庫。它更適合記住長期偏好和穩(wěn)定習慣。

適合放進 Memory 的內(nèi)容：

不適合放進 Memory 的內(nèi)容：

一句話：Memory 記偏好，不記事實；記習慣，不記機密。

如果你希望 Codex 長期記住“我寫文章喜歡實戰(zhàn)風格”，放 Memory 很合適。

如果你希望 Codex 知道“這個項目怎么啟動”，放 AGENTS.md 更合適。

如果你希望 Codex 知道“GitHub 上這個 PR 當前是否通過 CI”，那應(yīng)該接 GitHub App 或 MCP。

第八步：怎么連接 App，讓 Codex 真正操作起來

Codex 的強大，不只是能寫答案，而是能連接真實工具。

常見 App / Connector 包括：

這里要分清楚兩個概念：

舉個例子，你要讓 Codex 看 GitHub PR，有幾種可能：

• 通過 GitHub 插件
• 通過 GitHub App / Connector
• 通過 MCP server
• 通過 gh CLI

它們不是互斥的。實際工作中，Codex 往往會優(yōu)先使用當前環(huán)境里已經(jīng)可用、權(quán)限合適、最穩(wěn)定的入口。

小白階段，你只要記住一個安全原則：讀取可以更自動，寫入必須謹慎。 比如讀取 PR、總結(jié)郵件、打開網(wǎng)頁，一般風險較低。

但發(fā)送郵件、提交表單、刪除文件、發(fā)布文章、改權(quán)限、付款、發(fā)消息，這些動作一定要讓 Codex 先停下來給你確認。把 AI 當成有人監(jiān)督的助手，而不是完全放飛的機器人。

小白第一次配置，按這個順序來

別一開始就追求“全配滿”。

更好的順序是：

你可以按下面這套路線走：

1. 安裝 Codex，完成登錄。
2. 運行 codex doctor，確認環(huán)境正常。
3. 在項目根目錄寫一個簡單的 AGENTS.md。
4. 只改必要的 config.toml，先別開太多高權(quán)限。
5. 先接一個最常用的插件，比如 GitHub 或 Browser。
6. 如果你經(jīng)常重復(fù)某類任務(wù)，再寫 Skill。
7. 需要外部數(shù)據(jù)時，再配置 MCP。
8. 最后再考慮把長期偏好放進 Memory。

這套順序的好處是，你每一步都能驗證。

很多人一上來裝十幾個插件、配五六個 MCP、寫一大堆全局規(guī)則，最后出問題時根本不知道是哪一層壞了。小白階段最重要的不是炫技，而是能定位問題。

給你一套基礎(chǔ)配置模板

下面這套模板可以作為起點，不建議無腦復(fù)制到所有項目里，但你可以按自己的項目改。

1. 項目根目錄AGENTS.md

# AGENTS.md

## Project overview

Briefly describe what this project does and where the main code lives.

## Common commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Typecheck: `pnpm typecheck`
- Test: `pnpm test`
- Build: `pnpm build`

## Working rules

- Read existing code before editing.
- Keep changes focused on the requested task.
- Do not rewrite unrelated files.
- Follow existing naming and style.
- Ask before adding new dependencies.

## Verification

Before marking work complete:

- Run the most relevant check.
- If checks cannot run, explain why.
- Do not claim tests passed unless they were actually run.

2. 全局config.toml

# ~/.codex/config.toml

# Pick the model you normally want Codex to use.
# 示例：按你賬號和當前 Codex 版本可用模型調(diào)整
model = "o3"

# Conservative default for local coding work.
sandbox_mode = "workspace-write"

# Let Codex ask when it needs permission for sensitive operations.
approval_policy = "on-request"

# You can add MCP servers below when needed.
# [mcp_servers.example]
# command = "node"
# args = ["server.js"]

如果你的 Codex 版本提示字段不識別，先不要硬改，跑：

codex doctor
codex --help

再根據(jù)當前版本調(diào)整。

3. 一個最小 Skill 模板

---
name: project-review
description: Use when reviewing a feature implementation before merge.
---

# Project Review

## Workflow

1. Read the requirement or issue.
2. Inspect changed files.
3. Look for bugs, regressions, missing tests, and risky assumptions.
4. Run or recommend relevant verification commands.
5. Report findings first, then summarize.

## Output

- Findings with file references.
- Test gaps.
- Suggested next steps.

4. MCP 添加命令模板

# HTTP MCP server
codex mcp add <name> --url <server-url>

# Local stdio MCP server
codex mcp add <name> -- <command> <args>

# Check configured MCP servers
codex mcp list

這里最重要的是 <name> 要起得清楚，比如 github、docs、postgres-readonly，不要叫 test1、abc。后面排查問題時，清楚的名字會救命。

常見坑

1. 把AGENTS.md寫成散文

AGENTS.md 不是給人看的項目宣傳稿，而是給 Codex 執(zhí)行任務(wù)時用的操作說明。少寫愿景，多寫命令、約束和驗收方式。

2. 一開始就開最高權(quán)限

新手剛開始不要追求“無確認自動跑完”。AI 工具越能操作真實系統(tǒng)，越要有邊界。先用保守權(quán)限跑通工作流，再根據(jù)需要放開。

3. MCP 配好了但忘了驗證

配完 MCP 后，先跑：

codex mcp list
codex doctor

能列出來只是第一步，真正任務(wù)里能不能調(diào)用，還要看認證、網(wǎng)絡(luò)、權(quán)限和 server 本身是否正常。

4. 插件裝太多

插件不是越多越好。你真正需要的是工作流。

如果你每天都寫代碼，先把 GitHub、Browser 這類接好。如果你每天寫文章，先把 Documents、Browser、圖片生成或預(yù)覽流程跑通。裝一堆不用的插件，只會讓你更困惑。

5. 把 Memory 當事實庫

Memory 適合記偏好，不適合記實時事實。項目狀態(tài)、PR 狀態(tài)、數(shù)據(jù)庫數(shù)據(jù)、新聞變化，都應(yīng)該從真實來源讀取。

6. 不區(qū)分“讀”和“寫”

讓 Codex 讀取資料、總結(jié)內(nèi)容、檢查頁面，風險通常較低。

讓 Codex 發(fā)送郵件、發(fā)布文章、刪除文件、提交表單、改權(quán)限，風險就高很多。涉及外部副作用的動作，最好都讓它先停下來確認。

我自己的建議

如果你剛開始用 Codex，我建議先別急著研究所有高級配置。

第一周只做三件事：

1. 每個項目補一個 AGENTS.md。
2. 學會用 codex doctor 排查問題。
3. 只接一個你最需要的插件或 App。

等你發(fā)現(xiàn)某個任務(wù)每周都在重復(fù)，比如寫文章、review PR、整理周報、做 PPT、查數(shù)據(jù)，再把它沉淀成 Skill 或插件工作流。

Codex 真正厲害的地方，不是你一次 prompt 寫得多華麗，而是你能把自己的工作方式一點點沉淀下來。今天寫進 AGENTS.md 的項目規(guī)則，明天接上的 GitHub，后天固化成 Skill 的寫作流程，都會讓它越來越像你的工作臺。

對小白來說，最好的入門路線不是“學完所有概念再開始用”，而是先跑起來，再把反復(fù)出現(xiàn)的問題放到正確的位置。

這篇文章你如果只記住一張圖，就記住前面的七層配置地圖：

臨時需求放對話，項目規(guī)則放 AGENTS.md，運行默認值放 config.toml，重復(fù)流程放 Skills，外部能力交給 Plugins、MCP 和 Apps，個人偏好再放進 Memory。

把這幾層分清楚，Codex 就不再是一堆陌生名詞，而是一套你能慢慢搭起來的 AI 工作系統(tǒng)。

我這邊也有一些AI Coding（SDD Agent AI工具等） 和 Node技術(shù)交流交流群，感興趣的可以加我微 ikoala520  進群，一起學習，共同進步。

以上就是Codex小白入門指南：從安裝到插件、MCP、Skills的詳細內(nèi)容，更多關(guān)于Codex小白入門指南的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論