Codex桌面应用设置功能完全指南

Codex 桌面应用设置功能完全指南

基于 Codex 官方手册整理，涵盖 App Settings 面板所有功能项及其底层配置。
打开方式：应用菜单 → Settings，或快捷键 Cmd + ,（macOS）/ Ctrl + ,（Windows）。

1. General（通用）

通用设置控制 Codex 应用的基础行为。

设置项	说明
文件打开位置	选择在哪个应用中打开文件（如 VS Code、默认编辑器等）
命令输出显示量	控制线程中命令输出展示的多少（简洁 / 完整）
终端标签打开位置	设置终端标签页默认打开在哪里
多行提示需 Cmd+Enter	开启后，发送多行 prompt 需要按 Cmd+Enter（避免误触发送）
运行时阻止休眠	当线程运行时，防止系统进入睡眠状态

适用场景： 如果你习惯在 VS Code 中查看文件改动，可以把文件打开位置设为 VS Code。如果跑长任务时屏幕总是休眠，开启"阻止休眠"。

2. Profile（个人资料）

个人资料页面展示你的使用数据和账户信息。

2.1 活动洞察

• Lifetime tokens：累计使用的 token 总量
• Peak tokens：单次任务的峰值 token 消耗
• Streaks：连续使用天数
• 最长任务：历史耗时最长的单次任务
• Token 活动趋势：token 消耗的时间线图

2.2 个人信息

可以修改：

• 头像
• 显示名称
• 用户名

还可以保存一张带有使用数据的 Profile Card（个人名片），在消费者 ChatGPT 计划下可以分享。

2.3 邀请功能

• 个人计划用户：Invite a friend（邀请好友）
• Business 工作区用户：Invite a coworker（邀请同事）

具体的邀请奖励、限额和资格见官方定价页面。

3. Keyboard Shortcuts（键盘快捷键）

打开快捷键面板可以：

• 查看所有命令的当前快捷键绑定
• 自定义快捷键：点击某个命令，输入新的组合键
• 重置为默认：将自定义的快捷键恢复默认
• 搜索快捷键：支持按命令名搜索，或切换到按键搜索模式（按一个组合键反查绑定的命令）

常用快捷键速查：

快捷键	功能
Cmd + ,	打开设置
Cmd + K	打开命令面板
Cmd + J	切换集成终端
Ctrl + M	语音输入（按住说话）
Ctrl + L	清空终端

4. Notifications（通知）

控制 Codex 桌面通知的行为：

• 任务完成通知：选择何时显示 turn 完成通知
• 通知权限：设置是否允许应用请求系统通知权限

开启后，当 Codex 在后台 完成任务时，系统会弹出桌面通知，无需一直盯着应用。

5. Agent Configuration（Agent 配置）

Codex app 中的 Agent 与 CLI、IDE 扩展共享同一套配置。可以在应用内通过 UI 控件调整常用设置，也可以直接编辑 config.toml 进行高级配置。

5.1 沙盒模式（Sandbox Mode）

决定 Codex 执行命令时的文件和网络访问边界：

模式	说明
read-only	只能读取文件，不能编辑或执行命令（除非逐一审批）
workspace-write	默认模式。可读写工作区内文件，可在工作区边界内运行常规命令
danger-full-access	完全无限制。移除文件和网络边界，仅在你清楚风险时使用

5.2 审批策略（Approval Policy）

控制 Codex 何时暂停并请求你的许可：

策略	说明
untrusted	运行非信任命令前都会询问
on-request	在沙盒内自由工作，超出边界时询问
never	永不询问，直接执行

还支持 granular（细粒度）审批策略，可以按类别单独控制：

approval_policy = { granular = {
  sandbox_approval = true,
  rules = true,
  mcp_elicitations = true,
  request_permissions = false,
  skill_approval = false
} }

5.3 审批审阅者（Approvals Reviewer）

• user：审批请求直接呈现给你（默认）
• auto_review：符合条件的审批请求由审阅 Agent 自动处理

5.4 权限配置文件（Permission Profiles）

支持命名的权限配置文件，可以精细定义文件系统和网络访问：

• 内置配置文件：:read-only、:workspace、:danger-full-access
• 自定义配置文件：在 config.toml 中用 [permissions.] 表定义

示例：

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"github.com" = "allow"

5.5 Shell 环境策略

控制 Codex 向子进程传递哪些环境变量：

[shell_environment_policy]
inherit = "core"          # none | core | all
set = { MY_FLAG = "1" }  # 额外设置的环境变量
exclude = ["AWS_*", "AZURE_*"]  # 排除的变量（支持通配符）
include_only = ["PATH", "HOME"]  # 仅保留的变量

5.6 网络搜索模式

模式	说明
cached（默认）	从 OpenAI 维护的缓存索引中返回结果，减少外部内容注入风险
live	实时从网络获取最新数据（等同于 --search）
disabled	关闭网络搜索工具

web_search = "cached"

5.7 推理力度（Reasoning Effort）

控制模型在支持推理时投入多少"思考"：

model_reasoning_effort = "high"  # low | medium | high | xhigh

5.8 日志目录

log_dir = "/absolute/path/to/codex-logs"

5.9 功能开关（Feature Flags）

在 [features] 表中切换可选和实验性功能：

功能键	默认值	成熟度	说明
apps	false	实验性	ChatGPT Apps/connectors 支持
codex_git_commit	false	实验性	Codex 生成的 git 提交和归因
hooks	true	稳定	生命周期钩子
fast_mode	true	稳定	Fast 模式（service_tier = “fast”）
memories	false	稳定	记忆功能
multi_agent	true	稳定	子 Agent 协作工具
personality	true	稳定	个性化选择控件
shell_snapshot	true	稳定	快照 shell 环境加速重复命令
shell_tool	true	稳定	默认 shell 工具
unified_exec	true（Windows 除外）	稳定	统一 PTY 执行工具
undo	false	稳定	基于 git ghost 快照的撤销功能

启用方式：

[features]
memories = true
shell_snapshot = true

或通过 CLI：codex --enable memories

6. Appearance（外观）

自定义 Codex 应用的视觉风格：

• 基础主题：选择亮色/暗色/跟随系统
• 强调色（Accent）：调整主题强调色
• 背景色（Background）：自定义背景颜色
• 前景色（Foreground）：自定义文字/前景颜色
• UI 字体：设置界面使用的字体
• 代码字体：设置代码块使用的字体
• 分享主题：可以将自定义主题分享给朋友

7. Codex Pets（Codex 宠物）

可选的动画伴侣，在 Codex 工作时陪伴你。

启用与管理

• 在 Settings → Appearance → Pets 中选择内置宠物
• 也可以通过 refresh custom pets 从本地 Codex home 加载自定义宠物
• 在输入框中输入 /pet 可以切换宠物
• 在设置中使用 Wake Pet / Tuck Away Pet 唤醒或收起
• 快捷键 Cmd+K → 运行 Wake Pet / Tuck Away Pet 命令

浮动覆盖层

宠物浮动覆盖层会在你使用其他应用时保持可见，显示：

• 当前活跃线程
• Codex 状态（运行中 / 等待输入 / 准备审阅）
• 简短的进度提示

创建自定义宠物

$skill-installer hatch-pet

然后：

$hatch-pet create a new pet inspired by my recent projects

8. Git（Git 设置）

标准化 Git 操作和生成内容：

设置项	说明
分支命名规范	统一 Codex 创建分支时的命名格式
是否使用 force push	控制 Codex 是否执行强制推送
Commit message 提示	设置 Codex 生成 commit message 时使用的提示模板
PR 描述提示	设置 Codex 生成 Pull Request 描述时使用的提示模板

9. Integrations & MCP（集成与 MCP）

MCP（Model Context Protocol）是 Codex 连接外部工具和数据源的标准方式。

9.1 管理 MCP 服务器

• 推荐服务器：启用 Codex 推荐的 MCP 服务器（如 Context7、Figma、GitHub 等）
• 自定义服务器：添加自己的 MCP 服务器
• OAuth 认证：如果服务器需要 OAuth，应用会自动启动认证流程

9.2 配置方式

MCP 配置存储在 config.toml 中，App、CLI 和 IDE 共享：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

9.3 服务器类型

• STDIO 服务器：以本地进程运行，配置 command、args、env、cwd
• Streamable HTTP 服务器：通过 URL 访问，支持 Bearer token 和 OAuth 认证

9.4 常用 MCP 服务器

• OpenAI Docs MCP：搜索和阅读 OpenAI 开发者文档
• Context7：连接最新的开发者文档
• Figma：访问 Figma 设计文件
• Playwright：控制和检查浏览器
• Chrome Developer Tools：控制和检查 Chrome
• Sentry：访问 Sentry 日志
• GitHub：管理 PR、Issues 等（超越 git 命令的能力）

9.5 工具审批控制

可以对每个 MCP 服务器的工具设置审批模式：

[mcp_servers.chrome_devtools]
default_tools_approval_mode = "prompt"  # auto | prompt | approve

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"

10. Browser（浏览器）

管理 Codex 的浏览器能力：

10.1 内置浏览器插件

• 安装或启用捆绑的 Browser 插件
• 管理允许和阻止的网站列表
• Codex 使用网站前会先询问（除非你已允许）
• 移除被阻止的网站后，Codex 下次会再次询问

10.2 Chrome 扩展

设置 Codex Chrome 扩展，让 Codex 使用你的 Chrome 配置文件（已登录的会话、扩展等）。

10.3 开发者模式

开启 Enable full CDP access 可以让 Codex 使用 Chrome DevTools Protocol 进行：

• 性能分析
• 深层浏览器调试

注意：如果你的组织已禁用 CDP 完全访问，则无法在本地启用。

10.4 浏览器使用场景

• 预览：本地开发服务器的实时预览
• 评论：在页面上标记具体元素，让 Codex 处理反馈
• Browser Use：让 Codex 直接操作页面（适用于本地开发服务器和文件预览）

11. Computer Use（计算机控制）

Computer Use 让 Codex 可以操作 macOS 或 Windows 桌面应用——看屏幕、点击、输入。

设置项

• 桌面应用访问权限：回顾和管理 Codex 对桌面应用的控制权限
• 系统级权限：在 macOS 上，通过系统偏好设置 → 隐私与安全 → 屏幕录制 / 辅助功能 来撤销权限

适用场景

• 测试桌面应用
• 检查浏览器或模拟器流程
• 操作没有 API/插件的数据源
• 修改应用设置
• 复现 GUI 相关的 bug

因为 Computer Use 可以影响项目工作区之外的应用和系统状态，建议保持任务范围窄，并在继续前审阅权限提示。

12. Personalization（个性化）

选择 Codex 的默认交流风格：

选项	说明
Friendly	友好、温暖的交流风格
Pragmatic	务实、简洁、直奔主题
None	禁用个性化指令

可以随时更改。配置方式：

personality = "friendly"

运行时可以通过 /personality 命令切换。

自定义指令

可以添加自己的自定义指令（Custom Instructions）。编辑自定义指令会更新你个人 AGENTS.md 中的指令部分。这些指令会在每次会话中自动注入，塑造 Codex 的行为方式。

13. Context-aware Suggestions（上下文感知建议）

开启后，当你启动或返回 Codex 时，会自动浮现：

• 后续建议：基于之前工作的后续操作推荐
• 任务恢复：可能需要继续的任务

帮助你快速接续上下文，减少"我上次做到哪了"的困扰。

14. Memories（记忆）

Memories 让 Codex 将之前线程中有用的上下文带入到未来的工作中。

14.1 启用

• 在 App 设置中开启
• 或在 config.toml 中设置：

[features]
memories = true

在 EEA、英国和瑞士地区，必须手动启用后才会使用或生成记忆。

14.2 工作原理

启用后，Codex 会：

• 从符合条件的历史线程中提取有用的上下文
• 跳过活跃或短暂的会话
• 自动脱敏生成的记忆字段中的敏感信息
• 在后台异步更新（不是每个线程结束时立即更新）

可以记住的内容：

• 稳定的偏好设置
• 重复的工作流
• 技术栈信息
• 项目规范
• 已知的坑和注意事项

14.3 存储位置

记忆文件存储在 ~/.codex/memories/ 下，包括摘要、持久条目、近期输入和历史线程的佐证。

14.4 线程级控制

使用 /memories 命令可以控制当前线程的记忆行为：

• 当前线程是否使用已有记忆
• 当前线程是否可以作为未来记忆的生成来源

14.5 高级配置

[memories]
generate_memories = true           # 是否允许新线程作为记忆生成输入
use_memories = true                # 是否将已有记忆注入未来会话
disable_on_external_context = true # 使用了 MCP/搜索的线程不参与记忆生成
min_rate_limit_remaining_percent = 20  # 最低剩余配额百分比才开始生成
extract_model = "gpt-5.4-mini"    # 每线程记忆提取使用的模型
consolidation_model = "gpt-5.5"   # 全局记忆整合使用的模型

15. Archived Threads（已归档线程）

归档区域列出所有已归档的聊天记录，包含：

• 归档日期
• 项目上下文

使用 Unarchive 可以恢复一个线程到活跃列表。

附录 A：沙盒与权限体系

沙盒的作用

沙盒是 Codex 自主工作的技术边界。它不是限制 Codex 的能力，而是定义"在这个范围内可以自由行动，超出范围需要审批"。

沙盒减少"审批疲劳"：低风险命令在边界内自动执行，不需要逐一确认。

平台实现

平台	实现方式
macOS	内置 Seatbelt 框架，开箱即用
Windows	原生 Windows 沙盒（PowerShell）或 WSL2 的 Linux 实现
Linux / WSL2	需要安装 bubblewrap（sudo apt install bubblewrap）

可写根目录（Writable Roots）

如果 Codex 需要操作多个目录：

[sandbox_workspace_write]
writable_roots = ["/Users/YOU/.pyenv/shims", "/Users/YOU/shared-lib"]
network_access = false  # 是否允许网络访问
exclude_tmpdir_env_var = false  # 是否允许 $TMPDIR
exclude_slash_tmp = false       # 是否允许 /tmp

权限配置文件详解

权限配置文件提供更精细的文件系统和网络控制：

文件系统权限：read、write、deny 三级

• 更具体的条目覆盖更宽泛的条目
• deny > write > read

网络权限：

[permissions.my-profile.network]
enabled = true

[permissions.my-profile.network.domains]
"example.com" = "allow"
"*.example.com" = "allow"
"ads.example.com" = "deny"
"localhost" = "allow"

还支持 Unix socket 代&理配置（如 Docker socket）。

附录 B：模型选择与配置

推荐模型

模型	适用场景
gpt-5.5	首选。复杂编码、Computer Use、知识工作和研究流程
gpt-5.4-mini	快速、低成本选项，适合轻量编码和子 Agent
gpt-5.3-codex-spark	研究预览，面向近实时代码迭代（仅 Pro 用户）

配置默认模型

model = "gpt-5.5"

临时切换模型

• CLI：/model 命令或 codex -m gpt-5.5
• IDE：输入框下方的模型选择器
• App：在创建线程时选择

自定义模型提供商

model = "gpt-5.4"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

支持的提供商类型：

• OpenAI（内置）
• Amazon Bedrock（内置）
• Ollama / LM Studio（本地）
• Azure
• Mistral
• 任何兼容 Chat Completions / Responses API 的提供商

推理与表达控制

model_reasoning_effort = "high"
model_reasoning_summary = "none"
model_verbosity = "low"
model_context_window = 128000

附录 C：Hooks（生命周期钩子）

Hooks 让你将自己的脚本注入到 Codex 的 Agent 循环中。

支持的事件

事件	触发时机
SessionStart	会话启动/恢复/清理/压缩时
PreToolUse	工具调用前
PermissionRequest	权限请求时
PostToolUse	工具调用后
UserPromptSubmit	用户提交 prompt 时
PreCompact / PostCompact	上下文压缩前后
SubagentStart / SubagentStop	子 Agent 启动/停止时
Stop	任务停止时

配置方式

支持 hooks.json 或 config.toml 中的内联 [hooks] 表：

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

放置位置（按优先级排列常用位置）

1. ~/.codex/hooks.json（用户级）
2. ~/.codex/config.toml（用户级内联）
3. /.codex/hooks.json（项目级，需信任项目）
4. /.codex/config.toml（项目级内联）

信任机制

非托管的命令钩子需要在运行前审查和信任。使用 /hooks 命令可以查看、审查和信任钩子。

典型用例

• 将会话发送到自定义日志/分析引擎
• 扫描 prompt 防止意外粘贴 API Key
• 自动摘要会话创建持久记忆
• 在 turn 结束时运行自定义校验
• 在特定目录下定制 prompt 行为

附录 D：Rules（命令规则）

Rules 控制哪些命令可以在沙盒外运行（实验性功能）。

创建规则

在 ~/.codex/rules/ 目录下创建 .rules 文件：

prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",  # allow | prompt | forbidden
    justification = "Viewing PRs is allowed with approval",
    match = [
        "gh pr view 7888",
        "gh pr view --repo openai/codex",
    ],
    not_match = [
        "gh pr --repo openai/codex view 7888",
    ],
)

规则字段

字段	说明
pattern（必填）	命令前缀匹配列表
decision	allow（直接放行）/ prompt（提示确认）/ forbidden（阻止）
justification	规则原因（可选）
match / not_match	内联单元测试（可选）

当多条规则匹配时，最严格的决定生效：forbidden > prompt > allow。

测试规则

codex execpolicy check --pretty 
  --rules ~/.codex/rules/default.rules 
  -- gh pr view 7888 --json title,body,comments

Shell 复合命令处理

Codex 会安全地拆分简单的 shell 复合命令（如 git add . && rm -rf /），分别对每条命令应用规则，最严格结果生效。对于使用高级 shell 特性（重定向、变量替换等）的命令，则保守地作为整体处理。

附录 E：Plugins（插件）

插件将 Skills、App 集成和 MCP 服务器打包成可复用的工作流。

插件目录

• App 中：打开 Plugins 浏览和安装
• CLI 中：运行 /plugins

插件分类

• Curated by OpenAI：OpenAI 精选插件
• Shared with you：工作区其他成员分享的插件
• Created by you：你自己创建的插件

常见插件

• Codex Security：扫描代码安全漏洞
• Gmail：读取和管理 Gmail
• Google Drive：操作 Drive、Docs、Sheets、Slides
• Slack：汇总频道或起草回复
• Sites：创建和部署托管网站

安装与使用

1. 在插件目录中搜索或浏览
2. 点击安装
3. 如需外部应用认证，按提示完成
4. 在新线程中直接使用（自然语言描述或 @plugin-name 显式调用）

管理插件

卸载：在插件详情页选择 Uninstall plugin

禁用（不卸载）：

[plugins."gmail@openai-curated"]
enabled = false

附录 F：Automations（自动化）

自动化让你在后台定期运行重复任务。

类型

类型	说明
独立自动化	按计划启动全新运行，结果出现在 Triage 收件箱
项目自动化	可以跨多个项目运行
线程自动化	心跳式的定期唤醒，保留线程上下文

运行环境

• Git 仓库中可选择在本地项目或 worktree 中运行
• 非版本控制项目在本地项目目录直接运行
• 可以自定义模型和推理力度

调度

• 预设频率（每日、每周等）
• 自定义 cron 表达式
• 线程自动化支持分钟级间隔

安全模型

• 自动化使用你的默认沙盒设置
• read-only 模式下需要修改文件的工具调用会失败
• full access 模式下后台自动化风险较高
• 可以使用 Rules 选择性允许特定命令

与 Skills 结合

自动化可以使用 Codex 的所有插件和 Skills。在自动化 prompt 中用 $skill-name 显式触发。

管理

• 所有自动化及其运行结果在侧边栏的 Automations 面板查看
• Triage 区域作为收件箱，展示有发现的自动化运行
• 可以从普通线程中让 Codex 创建或更新自动化

附录 G：配置文件层级与优先级

Codex 从多个位置读取配置，优先级从高到低：

1. CLI 标志和 --config 覆盖（最高优先级）
2. 项目配置文件：.codex/config.toml，从项目根到当前目录（最近的生效；仅信任的项目）
3. Profile 文件：--profile profile-name 选择的 ~/.codex/profile-name.config.toml
4. 用户配置：~/.codex/config.toml
5. 系统配置：/etc/codex/config.toml（Unix）
6. 内置默认值（最低优先级）

配置文件位置

文件	位置	说明
config.toml	~/.codex/	用户级配置
auth.json	~/.codex/	文件存储的凭证（如使用 keyring 则不存在）
history.jsonl	~/.codex/	历史持久化（如启用）
hooks.json	~/.codex/ 或 /.codex/	生命周期钩子
rules/*.rules	~/.codex/rules/ 或 /.codex/rules/	命令规则
memories/	~/.codex/	记忆文件
AGENTS.md	~/.codex/ 或仓库根/子目录	项目指导

项目配置的安全限制

项目级 .codex/config.toml 不能覆盖以下设置（安全考虑）：

• openai_base_url
• chatgpt_base_url
• model_provider / model_providers
• notify
• profile / profiles
• otel

这些设置只能在用户级 ~/.codex/config.toml 中设置。

认证方式

方式	说明
ChatGPT 登录	默认方式，使用订阅额度，遵循 ChatGPT 工作区权限和数据策略
API Key	按用量计费，适用于 CI/CD 等程序化场景
Access Token	企业自动化的非交互式认证（ChatGPT Enterprise）

凭证存储：

cli_auth_credentials_store = "keyring"  # file | keyring | auto