文章目录Codex CLI 使用教程安装部署与终端命令实战指南一、引言二、Codex CLI 是什么三、安装部署3.1 环境要求3.2 安装方式3.3 验证安装3.4 身份认证四、快速上手第一次运行4.1 进入项目目录启动4.2 让 Codex 理解项目上下文AGENTS.md五、核心配置config.toml5.1 配置文件位置5.2 基础配置示例5.3 Profile多套配置一键切换5.4 MCP 服务器配置六、终端命令大全6.1 基础命令6.2 非交互模式脚本与 CI 场景6.3 TUI 内部斜杠命令七、沙箱与审批模式详解7.1 沙箱模式sandbox_mode7.2 审批策略approval_policy八、进阶实战8.1 用 Profile 区分个人沙盒与生产项目8.2 自定义斜杠命令8.3 结合 MCP 扩展能力边界九、常见问题速查表十、总结Codex CLI 使用教程安装部署与终端命令实战指南一、引言亲爱的朋友们创作不容易若对您有帮助的话请点赞收藏加关注哦您的关注是我持续创作的动力谢谢大家有问题请私信或联系邮箱jasonai.fngmail.com同样是终端里跑 AI 编程助手很多人卡在第一步——装错包名、认证方式选错、沙箱权限配置不对导致工具一会儿什么都不敢做、一会儿又权限开太大。OpenAI 的 Codex CLI 作为终端优先terminal-first的编码 Agent安装本身很简单但真正决定使用体验的是后面这些配置细节config.toml怎么写、沙箱模式怎么选、AGENTS.md 怎么发挥作用。本文聚焦工程落地从安装部署、身份认证到核心配置文件、终端命令速查、沙箱与审批模式详解给出一套可以直接照做的使用指南。二、Codex CLI 是什么Codex CLI 是 OpenAI 推出的终端优先编码 Agent直接在命令行里运行可以读写本地文件、执行 shell 命令、跑测试核心定位类似住在你终端里的编程搭档。它支持交互式 TUI终端界面对话模式也支持非交互模式用于脚本和 CI 场景同时原生支持 MCPModel Context Protocol协议扩展外部工具能力。三、安装部署3.1 环境要求项目要求Node.js建议 18 及以上版本部分教程建议 22以保证兼容性npm8 及以上版本账号OpenAI 账号ChatGPT 订阅登录或 API Key 均可新账号通常有一定免费额度# 检查环境版本node--versionnpm--version3.2 安装方式方式一npm 全局安装推荐npminstall-gopenai/codex踩坑提醒包名必须是openai/codex带 scope而不是codex——后者是 2012 年就存在的一个无关 npm 包装错包会导致命令完全不可用。方式二HomebrewMac 用户brewinstallcodex方式三国内网络环境优化若 npm 安装速度慢可切换淘宝镜像源npminstall-gopenai/codex--registryhttps://registry.npmmirror.com3.3 验证安装codex--version能正常输出版本号即安装成功。3.4 身份认证Codex CLI 支持两种认证方式# 方式一浏览器登录 ChatGPT 账号推荐个人用户codex auth# 方式二使用 API Key推荐脚本/CI 场景exportOPENAI_API_KEYsk-your-api-key两种方式二选一即可codex auth会打开浏览器完成 OAuth 登录登录态会保存在本地配置目录不需要每次都重新认证。四、快速上手第一次运行4.1 进入项目目录启动cdyour-project codex首次运行会进入交互式 TUI 界面直接用自然语言描述需求即可例如 帮我看看这个项目的目录结构并总结主要模块4.2 让 Codex 理解项目上下文AGENTS.md在项目根目录创建AGENTS.md文件写清楚项目背景、技术栈、编码规范Codex 每次启动都会读取它作为项目指令——作用类似其他编码 Agent 里的项目说明文件# AGENTS.md ## 项目说明 这是一个基于 FastAPI 的后端服务使用 PostgreSQL 数据库。 ## 编码规范 - 使用 Python 类型注解 - 所有接口需要编写对应的 pytest 测试用例 - 禁止直接修改 migrations/ 目录下的历史迁移文件 ## 常用命令 - 运行测试pytest tests/ - 启动服务uvicorn main:app --reload五、核心配置config.toml5.1 配置文件位置Codex CLI 的全局配置文件默认位于~/.codex/config.toml5.2 基础配置示例# ~/.codex/config.toml # 默认模型 model gpt-5.3-codex # 沙箱模式控制文件系统与网络访问权限 sandbox_mode workspace-write # 审批策略控制何时需要人工确认 approval_policy on-request5.3 Profile多套配置一键切换一个config.toml可以声明多个 profile把模型、沙箱、审批策略打包成一套预设通过--profile参数或环境变量切换适合个人电脑随便跑和生产项目严格审批两种场景来回切换[profiles.relaxed] model gpt-5.3-codex sandbox_mode workspace-write approval_policy never [profiles.strict] model gpt-5.3-codex sandbox_mode read-only approval_policy untrusted# 使用指定 profile 启动codex--profilestrict# 或用环境变量指定exportCODEX_PROFILEstrict codex5.4 MCP 服务器配置通过[mcp_servers.NAME]声明外部工具服务器支持 STDIO 和 HTTP 两种接入方式# STDIO 类型 MCP 服务器 [mcp_servers.filesystem] command npx args [-y, modelcontextprotocol/server-filesystem, /path/to/allowed/dir] # HTTP 类型 MCP 服务器 [mcp_servers.internal_api] url https://internal.example.com/mcp bearer_token_env_var INTERNAL_MCP_TOKEN配置完成后Codex 启动时会自动加载这些外部工具服务器扩展其可调用的能力边界。六、终端命令大全6.1 基础命令命令说明codex启动交互式 TUIcodex --version查看版本号codex auth浏览器登录 ChatGPT 账号codex --profile name使用指定 profile 启动codex exec 任务描述非交互模式脚本/CI 场景使用codex resume交互式会话选择器恢复历史会话codex resume --last恢复最近一次会话codex resume SESSION_ID恢复指定会话 IDnpm update -g openai/codex升级到最新版本npm uninstall -g openai/codex卸载6.2 非交互模式脚本与 CI 场景codex exec用于不打开 TUI 界面直接执行任务运行过程中进度信息输出到 stderr最终结果输出到 stdout方便脚本采集# 执行一次性任务codexexec审查这次改动是否存在竞态条件# 基于上一次 exec 会话继续追问codexexecresume--last修复你刚才发现的竞态条件问题这个模式特别适合接入 CI 流水线比如在 PR 提交后自动跑一次代码审查。6.3 TUI 内部斜杠命令进入交互式界面后输入/触发内置命令菜单命令功能/model切换当前使用的模型/permissions即/approvals切换审批权限预设如 Auto / Read Only/status查看当前会话状态/usage查看用量统计/diff查看当前改动的 diff/review触发代码审查工作流/compact压缩对话上下文释放 token 空间/new开启新会话/resume恢复历史会话/fork从当前会话分叉出一个新会话/import导入外部内容到当前会话/delete删除指定会话七、沙箱与审批模式详解Codex CLI 的安全模型由两个维度共同决定沙箱模式控制能碰什么审批策略控制什么时候要问你。7.1 沙箱模式sandbox_mode模式权限范围适用场景read-only只能读取文件不能写入或联网代码审查、只读分析类任务workspace-write可以在项目工作目录内读写文件网络访问受限日常开发最常用的模式danger-full-access完全权限文件系统和网络不受限制高度信任场景需谨慎使用7.2 审批策略approval_policy策略行为untrusted几乎所有操作都需要人工确认on-failure命令执行失败时才要求确认on-request模型主动判断是否需要请求确认never完全自动执行不打断询问实用建议日常个人项目用workspace-writeon-request组合兼顾效率和安全涉及生产环境或重要代码库时切到read-onlyuntrusted组合先看它想做什么再决定要不要放权。八、进阶实战8.1 用 Profile 区分个人沙盒与生产项目结合第五章的 profile 配置实际使用中可以这样划分# 个人练习项目效率优先codex--profilerelaxed# 涉及生产代码的项目安全优先codex--profilestrict8.2 自定义斜杠命令除了内置的斜杠命令Codex 支持团队或个人自定义可复用的提示词命令把高频重复的指令比如按团队规范生成 PR 描述固化成一个命令输入/加命令名即可触发不需要每次重新描述完整要求。8.3 结合 MCP 扩展能力边界通过 MCP 协议接入的外部工具服务器如文件系统访问、内部 API可以让 Codex 在原生文件读写和命令执行能力之外进一步对接企业内部系统这是把 Codex 从通用编码助手变成贴合具体工作流的 Agent的关键手段。九、常见问题速查表问题原因解决方案codex: command not found全局安装路径未加入 PATH或装错了包确认安装的是openai/codex而非codex检查 npm 全局 bin 路径是否在 PATH 中安装速度极慢或超时国内网络访问 npm 官方源不稳定使用淘宝镜像--registryhttps://registry.npmmirror.com认证后仍提示未登录登录态缓存异常或 API Key 未正确导出重新执行codex auth或检查echo $OPENAI_API_KEY是否有输出每次操作都要手动确认效率很低approval_policy设置为untrusted日常场景切换为on-request或使用宽松 profile模型执行了不该做的操作sandbox_mode设置过于宽松收紧为read-only或workspace-write避免使用danger-full-access项目相关背景每次都要重新说明未创建 AGENTS.md在项目根目录添加 AGENTS.md写清楚项目背景与规范长会话响应变慢、上下文混乱上下文积累过多使用/compact压缩上下文或/new开启新会话十、总结维度核心要点安装npm install -g openai/codex注意包名 scope国内可用淘宝镜像认证codex auth浏览器登录或OPENAI_API_KEY环境变量二选一项目上下文AGENTS.md 提供项目背景与规范每次启动自动加载核心配置~/.codex/config.toml设置 model / sandbox_mode / approval_policyprofile 支持多套预设切换命令体系交互式codex 非交互codex exec脚本/CI TUI 内/斜杠命令安全模型沙箱模式决定能碰什么审批策略决定何时要问两者组合按场景灵活切换扩展能力MCP 协议接入外部工具服务器自定义斜杠命令固化高频操作Codex CLI 的安装本身只是几行命令的事真正拉开使用体验差距的是配置习惯——按项目风险等级用好 profile 和沙箱/审批组合把 AGENTS.md 写扎实把高频操作沉淀成自定义命令才能让它从一个能跑的工具变成真正提效的终端搭档。参考资料CLI – Codex | OpenAI DevelopersQuickstart – Codex | OpenAI DevelopersConfiguration Reference – Codex | OpenAI DevelopersCommand line options – Codex CLI | OpenAI DevelopersSlash commands in Codex CLI | OpenAI DevelopersNon-interactive mode – Codex | OpenAI Developersopenai/codex - npm
