前言

• 海外官网
• 国内官网

安装

codex cli 安装

• brew 安装

# 安装
brew install --cask codex

# 升级
brew upgrade codex

# 查看帮助
codex --help

# 卸载
brew uninstall --cask codex

codex app 安装

• Codex App: 选择对应的安装包直接下载安装即可。

codex-cli 使用

• 启动

cd your-project
codex

• 基本使用

分类	操作	快捷键 / 指令	说明	适用场景
指令	Slash 命令	/xxx	调用内置命令（如 init、review 等）	快速触发预设能力
上下文	文件引用	@xxx	引入文件/代码作为上下文	分析指定文件
编辑	换行（Windows/Linux）	Ctrl + J	在输入框内换行（不发送）	编写多行 prompt
输入	粘贴图片（Windows/Linux）	Ctrl + V	粘贴剪贴板图片	贴报错截图
编辑	删除整行输入	Ctrl + U	清空当前输入行	快速重写 prompt
控制	中断当前输入	Ctrl + C	清空当前输入（一次）	输入错误时取消
控制	退出程序	Ctrl + C（连续两次）	退出 Claude Code ，相当于 /exit	结束 CLI
历史	搜索历史 prompt	Ctrl + R	类似 bash reverse search	快速复用旧 prompt
模式切换	模式切换	Shift+Tap	循环切换编辑模式与计划模式

• 认证和模型配置文件路径 ~/.codex /auth.json

CC-Switch

• 官网

安装

brew tap farion1231/ccswitch
brew install --cask cc-switch

# 升级
brew upgrade --cask cc-switch

# 卸载
brew uninstall --cask cc-switch

使用

• 然后在Application中找到 CC Switch 双击打开。
• 在顶部选择OpenAI
• 点击最右侧的+添加一个供应商，比如这里选择 MiniMax，根据提示只需要填入 APIKey 保存即可
• 如果添加了多个 供应商 ，需要选择激活哪个
• 之后再设置中，选择路由–本地路由–激活路由总开关–下面的路由启用中选择Codex
• 然后在终端打开 codex，输入 /model 选择我们刚刚创建的供应商即可。

codex 相关配置

权限配置

• 权限配置（Permissions Profiles）用于控制 Codex 在本地执行命令时对文件系统和网络的访问范围，实现最小权限原则。该功能目前仍处于 Beta 阶段。

1. 功能概述

• Codex 在执行代码生成、修改文件、运行命令等操作时，可能需要访问：

本地文件
项目目录
网络资源
本地服务（Docker、数据库等）

• Permissions Profile（权限配置文件）允许开发者精确控制这些能力，例如：

只允许读取代码
允许修改当前项目
禁止访问 .env
仅允许访问 GitHub 和 OpenAI API
禁止访问内部网络

• 从而降低 AI Agent 误操作和数据泄露风险。

2. 权限配置

• Codex 提供了三个内置权限模型：

配置	说明	场景
:read-only	只读模式，只允许读取文件	适合代码审查
:workspace	可读写当前工作区	适合日常开发
:danger-full-access	完全访问权限，不受限制	适合自动化任务或 CI 场景（需谨慎）

示例：config.toml

default_permissions = ":workspace"

可以定义自己的权限

default_permissions = "project-edit"

[permissions.project-edit]

• 文件系统权限

权限	含义
read	只读
write	可读写
deny	禁止访问

• Codex 支持若干内置路径

路径	含义
:root	整个文件系统
:minimal	运行常用工具所需最小路径
:workspace_roots	工作区目录
:tmpdir	临时目录

示例

# 表示允许读取整个系统
[permissions.audit.filesystem]

":root" = "read"

# 可以指定多个工作区
[permissions.project-edit.workspace_roots]

"~/code/app" = true
"~/code/shared-lib" = true

# 为工作区配置权限
[permissions.project-edit.filesystem.":workspace_roots"]
# . 表示工作区根目录
"." = "write"
".devcontainer" = "read"

# 对敏感文件进行显式拒绝
[permissions.project-edit.filesystem.":workspace_roots"]

"**/*.env" = "deny"

# 允许网络连接
[permissions.project-edit.network]

enabled = true

# 限制访问目标
[permissions.project-edit.network.domains]

"api.openai.com" = "allow"
"*.github.com" = "allow"
"tracking.example.com" = "deny"

模式	示例
精确域名	api.openai.com
子域名	*.github.com
主域+子域	**.github.com
全部	*

配置文件

• Codex 使用 TOML 格式配置文件。

配置级别	配置文件路径	作用范围	是否默认加载	说明
用户级（User-level）	~/.codex/config.toml	当前用户所有 Codex 会话	是	存放个人默认配置，例如模型、审批策略、权限配置等。
项目级（Project-level）	<project>/.codex/config.toml	当前项目（仓库）	仅 Trusted 项目	用于覆盖用户级配置，实现项目专属设置。
系统级（System-level）	/etc/codex/config.toml	当前机器所有用户	是	通常由管理员统一配置组织级默认策略。

• 当在多个作用域中配置相同的设置时，更具体的作用域优先（高 → 低）：

CLI 参数
↓
Profile 配置
↓
项目级 .codex/config.toml
↓
用户级 ~/.codex/config.toml
↓
系统级 /etc/codex/config.toml
↓
内置默认值

• 示例目录

~
├── .codex
│   └── config.toml          # 用户级配置
│
└── workspace
    ├── project-a
    │   └── .codex
    │       └── config.toml  # project-a 项目配置
    │
    └── project-b
        └── .codex
            └── config.toml  # project-b 项目配置

内置命令

• 命令汇总

命令	功能说明（Purpose）	适用场景（When to use it）
/permissions	设置 Codex 在无需询问用户的情况下可执行的操作权限。	在会话过程中动态放宽或收紧审批策略，例如在 Auto 和 Read Only 模式之间切换。
/ide	将当前 IDE 的上下文（打开文件、选中内容等）加入对话。	希望 Codex 获取编辑器上下文，而无需手动描述当前打开的文件。
/keymap	重新映射 TUI（终端界面）快捷键。	查看、修改并保存自定义快捷键配置到 config.toml。
/vim	切换 Composer 编辑器的 Vim 模式。	在 Vim 编辑习惯与默认编辑模式之间切换。
/sandbox-add-read-dir	为沙箱增加额外目录的只读权限（仅 Windows）。	当命令需要访问当前工作区之外的目录时使用。
/agent	切换当前活动 Agent 线程。	查看或继续处理由子 Agent 创建的任务线程。
/apps	浏览可用应用（Connectors）并插入到提示词中。	在提示中附加应用（如 $app-slug）供 Codex 使用。
/plugins	浏览已安装和可发现的插件。	查看插件能力、安装推荐插件或管理插件可用性。
/hooks	查看和管理生命周期 Hook。	检查 Hook 配置、信任新 Hook 或禁用 Hook。
/clear	清空终端并开始新的聊天。	希望同时重置界面和会话内容时使用。
/compact	压缩当前会话内容以节省上下文 Token。	长时间会话后保留关键信息并减少上下文占用。
/copy	复制最近一次完整输出。	快速获取最新回复或执行计划，无需手动选择文本。
/diff	显示当前 Git Diff（包含未跟踪文件）。	在提交或测试前查看 Codex 修改的内容。
/exit	退出 CLI（等同于 /quit）。	离开当前 Codex 会话。
/experimental	开启或关闭实验性功能。	启用子 Agent 等实验功能。
/approve	批准一次被自动审查拒绝的操作重试。	自动审查器拒绝某命令后重新尝试执行。
/memories	配置记忆功能的使用和生成。	控制是否启用记忆注入或自动生成记忆。
/skills	浏览并使用 Skills。	为特定任务选择更合适的技能增强效果。
/feedback	向 Codex 维护团队发送日志和反馈。	报告问题或提交诊断信息。
/init	在当前目录生成 AGENTS.md 模板。	为仓库或子目录建立长期有效的 Agent 指令。
/logout	登出 Codex。	在共享机器上清除本地登录凭据。
/mcp	查看已配置的 MCP（Model Context Protocol）工具。	检查当前会话可调用的外部工具及其配置。
/mention	向会话附加文件或目录。	指定 Codex 接下来要分析的文件或目录。
/model	选择当前使用的模型及推理强度。	在轻量模型和高推理模型之间切换。
/fast	切换当前模型的 Fast 服务层。	启用或关闭模型的快速模式，或查看当前状态。
/plan	进入规划模式，并可附带提示词。	希望先生成执行计划，再开始实施任务。
/goal	设置、暂停、恢复、查看或清除任务目标。	为长期任务设定持续跟踪的目标。
/personality	选择回复风格。	调整回复为简洁、详细或协作式风格。
/ps	查看后台终端及其最近输出。	监控长时间运行的后台任务。
/stop	停止所有后台终端任务。	取消当前会话启动的后台工作。
/fork	将当前会话分叉为新线程。	尝试新方案，同时保留原会话记录。
/side	创建临时侧边会话。	提出额外问题而不影响主会话上下文。
/raw	切换原始滚动输出模式。	查看长输出时获得更适合复制和选择的显示效果。
/resume	恢复之前保存的会话。	继续之前的 CLI 工作。
/new	在同一 CLI 会话中开启新对话。	重置聊天上下文但保留当前仓库环境。
/quit	退出 CLI。	立即结束当前会话。
/review	让 Codex 审查当前工作区变更。	在代码修改完成后进行代码评审。
/status	显示当前会话状态和 Token 使用情况。	查看模型、权限策略、上下文容量等信息。
/debug-config	输出配置层级及策略诊断信息。	排查配置覆盖关系、权限限制等问题。
/statusline	交互式配置状态栏显示项。	自定义底部状态栏展示内容并保存配置。
/title	交互式配置终端标题显示项。	自定义窗口标题显示项目、分支、模型等信息。
/theme	选择语法高亮主题。	预览并保存终端代码高亮主题。

• 常用命令分类

分类	相关命令
权限与安全	/permissions、/approve、/sandbox-add-read-dir
模型与性能	/model、/fast、/personality
会话管理	/new、/resume、/fork、/side、/clear、/compact
文件与代码	/mention、/diff、/review、/copy
Agent 与自动化	/agent、/goal、/plan、/skills
扩展能力	/apps、/plugins、/mcp
配置与调试	/status、/debug-config、/keymap、/theme、/statusline、/title
系统管理	/hooks、/memories、/feedback、/logout
后台任务	/ps、/stop
退出相关	/exit、/quit

Tools

• 1. 终端与系统操作类

Tool	功能	使用时机	关键约束
exec_command	执行 Shell 命令	需要运行脚本、编译代码、查看文件、调用 CLI 工具时	可指定工作目录、TTY、输出长度；敏感命令需 require_escalated
write_stdin	向已运行进程写入输入	与交互式命令持续通信时（如 REPL、SSH、数据库客户端）	必须提供 session_id；只能操作已存在会话

• 2. MCP（Model Context Protocol）资源类

Tool	功能	使用时机	关键约束
list_mcp_resources	列出 MCP Server 提供的资源	需要发现可读取资源时	可按 Server 过滤；支持分页 Cursor
list_mcp_resource_templates	列出参数化资源模板	需要动态生成资源 URI 时	返回模板而非实际资源
read_mcp_resource	读取 MCP 资源内容	已获得资源 URI 后读取数据	URI 必须来自 list_mcp_resources

• 3. 任务规划与执行管理类

Tool	功能	使用时机	关键约束
update_plan	更新任务计划	多步骤任务执行过程中	同时只能有一个 in_progress
get_goal	查看当前 Goal 状态	查询任务目标、预算、剩余额度	仅读取
create_goal	创建 Goal	用户明确要求长期任务时	已存在 Goal 时会失败
update_goal	更新 Goal 状态	任务完成或确实阻塞时	只能设为 complete 或 blocked
request_user_input	请求用户补充信息	Plan 模式下需要决策或补充参数时	最多 3 个问题；仅 Plan Mode 可用

• 4. 文件编辑类

Tool	功能	使用时机	关键约束
apply_patch	修改文件内容	代码修复、批量替换、补丁应用	使用 Unified Diff 格式；FREEFORM 输入

• 5. 图像处理类

Tool	功能	使用时机	关键约束
view_image	查看本地图片	需要分析截图、UI、图表、照片时	文件必须存在于本地文件系统

• 6. 工具发现与扩展类

Tool	功能	使用时机	关键约束
tool_search	搜索可用 Tool/MCP/Connector	不确定有哪些工具可解决当前任务时	返回工具集合而非直接执行

开启 web_search

默认情况下，codex不支持联网搜索，不过实际上codex已经自带了这个功能，只是默认没有开启，开启方式有两种

• 1.命令启动时开启

codex --search

• 2.配置文件开启

# ~/.codex/config.toml

# web_search = "cached"  # default; serves results from the web search cache
web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"