一份可以直接复制并按需改写的完整 config.toml 示例
把这份示例配置当作起点来使用。它包含了 Codex 会从 config.toml 中读取的大部分键，同时给出了默认行为、推荐值以及简短说明。
如果你想看解释和背景说明，可参考：
下面这段配置可以作为参考。只把你需要的键和章节复制到 ~/.codex/config.toml（或者项目级的 .codex/config.toml）中，再按你的环境做调整。
# Codex 示例配置（config.toml） # # 这份文件列出了 Codex 会从 config.toml 中读取的主要键， # 并附带默认行为、推荐示例和简要说明。按需调整即可。 # # 注意 # - 在 TOML 中，根级键必须写在各个 table 之前。 # - 默认值为“未设置”的可选键，会以带注释的形式展示并附加说明。 # - MCP servers、配置档案文件和 model providers 都只是示例，可按需删除或修改。 ################################################################################ # 核心模型选择 ################################################################################ # Codex 使用的主模型。多数用户的推荐示例："gpt-5.5"。 model = "gpt-5.5" # 支持 personality 的模型使用的沟通风格。可选值：none | friendly | pragmatic # personality = "pragmatic" # /review 使用的可选模型覆盖值。默认：未设置（沿用当前 session 模型）。 # review_model = "gpt-5.5" # 从 [model_providers] 中选择的提供方 ID。默认："openai"。 model_provider = "openai" # --oss 会话使用的默认 OSS provider。未设置时，Codex 会提示选择。默认：未设置。 # oss_provider = "ollama" # 偏好的 service tier。内建示例包括 fast | flex；模型目录还可以提供更多值。 # service_tier = "flex" # 可选的手动模型元数据。未设置时，Codex 会使用模型或预设默认值。 # model_context_window = 128000 # tokens；默认：按模型自动决定 # model_auto_compact_token_limit = 64000 # tokens；未设置时使用模型默认值 # tool_output_token_limit = 12000 # 每次工具输出在历史中保留的 token 数 # model_catalog_json = "/absolute/path/to/models.json" # 仅启动时生效的 model catalog 覆盖 # background_terminal_max_timeout = 300000 # ms；空 write_stdin 轮询的最大等待时间（默认 5 分钟） # log_dir = "/absolute/path/to/codex-logs" # Codex 日志目录；显式设置会启用 codex-tui.log；默认 "$CODEX_HOME/log" # sqlite_home = "/absolute/path/to/codex-state" # SQLite 运行时状态目录（可选） ################################################################################ # 推理与 Verbosity（适用于 Responses API 模型） ################################################################################ # 推理强度：minimal | low | medium | high | xhigh # model_reasoning_effort = "medium" # Codex 运行在 plan mode 时使用的可选覆盖值：none | minimal | low | medium | high | xhigh # plan_mode_reasoning_effort = "high" # 推理摘要：auto | concise | detailed | none # model_reasoning_summary = "auto" # GPT-5 系列（Responses API）的输出详细程度：low | medium | high # model_verbosity = "medium" # 强制开启或关闭当前模型的 reasoning summaries。 # model_supports_reasoning_summaries = true ################################################################################ # 指令覆盖 ################################################################################ # 会在 AGENTS.md 之前注入的额外用户指令。默认：未设置。 # developer_instructions = "" # 历史压缩提示词的内联覆盖值。默认：未设置。 # compact_prompt = "" # 覆盖默认 commit co-author trailer。只有在启用 [features].codex_git_commit 时才会生效。 # 启用但未设置时，Codex 会使用 "Codex <noreply@openai.com>"。设为 "" 可禁用。 # commit_attribution = "Jane Doe <jane@example.com>" # 用文件路径覆盖内建基础指令。默认：未设置。 # model_instructions_file = "/absolute/or/relative/path/to/instructions.txt" # 从文件加载压缩提示词覆盖值。默认：未设置。 # experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt" ################################################################################ # Notifications ################################################################################ # 外部通知程序（argv 数组）。未设置时：禁用。 # notify = ["notify-send", "Codex"] ################################################################################ # Approval 与 Sandbox ################################################################################ # 何时请求命令 approval： # - untrusted：只有已知安全的只读命令会自动运行，其他都会提示 # - on-request：由模型决定何时提示（默认） # - never：永不提示（风险较高） # - { granular = { ... } }：按类别允许或自动拒绝指定提示 approval_policy = "on-request" # 由谁来审核符合条件的审批提示：user（默认）| auto_review # approvals_reviewer = "user" # 细粒度策略示例： # approval_policy = { granular = { # sandbox_approval = true, # rules = true, # mcp_elicitations = true, # request_permissions = false, # skill_approval = false # } } # 当基于 shell 的工具请求 `login = true` 时，是否允许 login-shell 语义。 # 默认：true。设为 false 会强制使用非 login shell，并拒绝显式 login-shell 请求。 allow_login_shell = true # 工具调用使用的文件系统 / 网络沙箱策略： # - read-only（默认） # - workspace-write # - danger-full-access（无 sandbox；风险极高） sandbox_mode = "read-only" # 默认应用的命名权限配置档案。内建值包括： # :read-only | :workspace | :danger-full-access # 只有在同时定义 [permissions.workspace] 时，才使用 "workspace" 这类自定义名称。 # default_permissions = ":workspace" ################################################################################ # Authentication 与 Login ################################################################################ # CLI 登录凭据保存位置：file（默认）| keyring | auto cli_auth_credentials_store = "file" # ChatGPT 登录流程使用的 base URL（不是 OpenAI API URL）。 chatgpt_base_url = "https://chatgpt.com/backend-api/" # 内建 OpenAI provider 的可选 base URL 覆盖值。 # openai_base_url = "https://us.api.openai.com/v1" # 将 ChatGPT 登录限制到某个固定 workspace id。默认：未设置。 # forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000" # 当 Codex 原本会自动选择登录方式时，强制指定登录机制。默认：未设置。 # 可选值：chatgpt | api # forced_login_method = "chatgpt" # MCP OAuth 凭据的首选存储位置：auto（默认）| file | keyring mcp_oauth_credentials_store = "auto" # MCP OAuth callback 的固定端口：1-65535。默认：未设置。 # mcp_oauth_callback_port = 4321 # MCP OAuth 登录的可选 redirect URI 覆盖值（例如远程 devbox ingress）。 # Codex 会在 OAuth 登录前追加服务器专属 callback ID，因此请在提供方处注册完整派生 URI，而不是只注册基础 host 或未追加后缀的 path。 # 支持自定义 callback path。`mcp_oauth_callback_port` 仍控制监听端口。 # mcp_oauth_callback_url = "https://devbox.example.internal/callback" ################################################################################ # 项目文档控制 ################################################################################ # 从 AGENTS.md 中最多嵌入到第一轮指令里的字节数。默认：32768 project_doc_max_bytes = 32768 # 当某一层目录缺少 AGENTS.md 时，要按顺序尝试的回退文件名。默认：[] project_doc_fallback_filenames = [] # 向父目录搜索项目根时使用的标记文件名。默认：[".git"] # project_root_markers = [".git"] ################################################################################ # History 与 File Opener ################################################################################ # 可点击 citation 使用的 URI scheme：vscode（默认）| vscode-insiders | windsurf | cursor | none file_opener = "vscode" ################################################################################ # UI、通知与杂项 ################################################################################ # 压制输出中的内部 reasoning 事件。默认：false hide_agent_reasoning = false # 当模型提供 raw reasoning 时，是否显示。默认：false show_raw_agent_reasoning = false # 禁用 TUI 中的 burst-paste 检测。默认：false disable_paste_burst = false # 记录 Windows onboarding 是否已确认（仅 Windows）。默认：false windows_wsl_setup_acknowledged = false # 启动时检查更新。默认：true check_for_update_on_startup = true ################################################################################ # Web Search ################################################################################ # Web search 模式：disabled | cached | live。默认："cached" # `cached` 通过 Web 搜索缓存返回结果（OpenAI 维护的索引）。 # cached 返回预索引结果；live 则会抓取最新网页数据。 # 若使用 `--yolo` 或其他完全访问沙箱设置，Web 搜索默认切到 `live`。 web_search = "cached" # 配置档案是 CODEX_HOME 下的独立文件。 # # 示例：~/.codex/ci.config.toml，通过 codex --profile ci 选择。 # 压制启用了“开发中”功能开关时显示的警告。 # suppress_unstable_features_warning = true ################################################################################ # 智能体（多智能体角色与限制） ################################################################################ [agents] # 同时打开的智能体对话线程上限。默认：6 # max_threads = 6 # 允许的嵌套生成深度。根 session 从深度 0 开始。默认：1 # max_depth = 1 # spawn_agents_on_csv 作业里每个 worker 的默认超时。未设置时工具默认 1800 秒。 # job_max_runtime_seconds = 1800 # [agents.reviewer] # description = "Find correctness, security, and test risks in code." # config_file = "./agents/reviewer.toml" # 相对于定义该角色的 config.toml # nickname_candidates = ["Athena", "Ada"] ################################################################################ # 技能（按技能覆盖） ################################################################################ # 在不删除技能的前提下，将其禁用或重新启用。 [[skills.config]] # path = "/path/to/skill/SKILL.md" # enabled = false ################################################################################ # Sandbox 设置（tables） ################################################################################ # 仅在 sandbox_mode = "workspace-write" 时使用的额外设置。 [sandbox_workspace_write] # 除工作区（cwd）外的额外可写根目录。默认：[] writable_roots = [] # 是否允许 sandbox 内向外联网。默认：false network_access = false # 是否把 $TMPDIR 排除出可写根目录。默认：false exclude_tmpdir_env_var = false # 是否把 /tmp 排除出可写根目录。默认：false exclude_slash_tmp = false ################################################################################ # 子进程使用的 Shell Environment Policy（table） ################################################################################ [shell_environment_policy] # inherit：all（默认）| core | none inherit = "all" # 是否跳过对名称包含 KEY/SECRET/TOKEN 的默认过滤（大小写不敏感）。默认：false ignore_default_excludes = false # 要移除的不区分大小写 glob pattern，例如 "AWS_*"、"AZURE_*"。默认：[] exclude = [] # 显式键值覆盖（优先级最高）。默认：{} set = {} # 白名单；若非空，则只保留匹配到的变量。默认：[] include_only = [] # 实验性：通过用户 shell profile 运行。默认：false experimental_use_profile = false ################################################################################ # Sandboxed networking 设置 ################################################################################ # 配置沙箱化网络规则前，需要先启用这个功能。 # [features.network_proxy] # enabled = true # domains = { "api.openai.com" = "allow", "example.com" = "deny" } # # 精确主机只匹配自身。 # "*.example.com" 只匹配子域名；"**.example.com" 同时匹配 apex 和子域名。 # "*" 会允许任何未被 deny 的公共主机，因此应优先使用更窄的规则。 # `allow_local_binding = false` 默认会阻止 loopback 和私有目的地。 # 如果只需要一个本地目标，请添加精确本地 IP literal 或 `localhost` allow 规则；只有确实需要更宽的本地访问时才设为 true。 # # 启用此配置档案前，先设置 `default_permissions = "workspace"`。 # 会继承此配置档案的 `:workspace_roots` 文件系统规则的额外工作区根目录示例。 # [permissions.workspace.workspace_roots] # "~/code/app" = true # "~/code/shared-lib" = true # # 文件系统配置档案示例。对精确路径或 glob pattern 使用 `"deny"` 可以拒绝读取。 # 在需要预展开 glob 匹配的平台上，使用 `**` 这类无界 pattern 时请设置 # glob_scan_max_depth。 # [permissions.workspace.filesystem] # glob_scan_max_depth = 3 # ":workspace_roots" = { "." = "write", "**/*.env" = "deny" } # "/absolute/path/to/secrets" = "deny" # # [permissions.workspace.network] # enabled = true # proxy_url = "http://127.0.0.1:43128" # admin_url = "http://127.0.0.1:43129" # enable_socks5 = false # socks_url = "http://127.0.0.1:43130" # enable_socks5_udp = false # allow_upstream_proxy = false # dangerously_allow_non_loopback_proxy = false # dangerously_allow_non_loopback_admin = false # dangerously_allow_all_unix_sockets = false # mode = "limited" # limited | full # allow_local_binding = false # # [permissions.workspace.network.domains] # "api.openai.com" = "allow" # "example.com" = "deny" # # [permissions.workspace.network.unix_sockets] # "/var/run/docker.sock" = "allow" ################################################################################ # History（table） ################################################################################ [history] # save-all（默认）| none persistence = "save-all" # history 文件最大字节数；超过后会裁剪最旧条目。示例：5242880 # max_bytes = 5242880 ################################################################################ # UI、通知与杂项（tables） ################################################################################ [tui] # 来自 TUI 的桌面通知：布尔值，或只启用部分事件。默认：true # 示例：false | ["agent-turn-complete", "approval-requested"] notifications = false # 终端提醒使用的通知机制：auto | osc9 | bel。默认："auto" # notification_method = "auto" # 通知触发条件：unfocused（默认）| always # notification_condition = "unfocused" # 是否启用 welcome / status / spinner 动画。默认：true animations = true # 是否在 welcome screen 中显示 onboarding tooltips。默认：true show_tooltips = true # 控制 alternate screen 使用方式（在 Zellij 中，auto 会跳过以保留 scrollback）。 # alternate_screen = "auto" # 底部状态栏项的有序列表。未设置时，Codex 默认使用： # ["model-with-reasoning", "context-remaining", "current-dir"]。 # 设为 [] 则隐藏底栏。 # status_line = ["model", "context-remaining", "git-branch"] # 终端窗口 / 标签标题项的有序列表。未设置时，Codex 默认使用： # ["spinner", "project"]。设为 [] 则清空标题。 # 可选值包括 app-name、project、spinner、status、thread、git-branch、model、 # 和 task-progress。 # terminal_title = ["spinner", "project"] # 语法高亮主题（kebab-case）。可在 TUI 中用 /theme 预览并保存。 # 也可以把自定义 .tmTheme 文件放到 $CODEX_HOME/themes 下。 # theme = "catppuccin-mocha" # 自定义快捷键绑定。部分 composer 动作会回退到匹配的 [tui.keymap.global] 绑定。 # 使用 [] 可以解除某个动作绑定。 # [tui.keymap.global] # open_transcript = "ctrl-t" # open_external_editor = [] # # [tui.keymap.composer] # submit = ["enter", "ctrl-m"] # # [tui.keymap.chat] # interrupt_turn = "f12" # 以 model slug 为键的内部 tooltip 状态。通常由 Codex 自己管理。 # [tui.model_availability_nux] # "gpt-5.4" = 1 # 为当前机器启用或禁用分析数据上报。未设置时，Codex 使用默认行为。 [analytics] enabled = true # 是否允许用户通过 `/feedback` 提交反馈。默认：true [feedback] enabled = true # 产品内通知（大多由 Codex 自动设置）。 [notice] # hide_full_access_warning = true # hide_world_writable_warning = true # hide_rate_limit_model_nudge = true # hide_gpt5_1_migration_prompt = true # "hide_gpt-5.1-codex-max_migration_prompt" = true # model_migrations = { "gpt-5.3-codex" = "gpt-5.4" } ################################################################################ # 集中式 Feature Flags（推荐） ################################################################################ [features] # 将这个 table 留空即可使用默认值。设置显式布尔值则表示手动启用 / 禁用。 # shell_tool = true # apps = false # hooks = false # codex_git_commit = false # unified_exec = true # shell_snapshot = true # multi_agent = true # personality = true # network_proxy = false # fast_mode = true # enable_request_compression = true # skill_mcp_dependency_install = true # prevent_idle_sleep = false # Code mode namespaces。该功能仍在开发中，默认关闭。 # # [features.code_mode] # enabled = true # excluded_tool_namespaces = ["mcp__codex_apps"] # direct_only_tool_namespaces = ["mcp__history"] # Rollout budget 跟踪。该功能仍在开发中，默认关闭。 # 启用后必须设置 limit_tokens。 # 可选的 reminder_interval_tokens 默认是 limit_tokens 的 10%。 # token 权重默认都是 1.0。 # # [features.rollout_budget] # enabled = true # limit_tokens = 100000 # reminder_interval_tokens = 10000 # sampling_token_weight = 1.0 # prefill_token_weight = 1.0 ################################################################################ # 记忆（Memories 表） ################################################################################ # 使用 [features].memories 启用记忆，再在这里调整记忆行为。 # [memories] # generate_memories = true # use_memories = true # disable_on_external_context = false # 旧别名：no_memories_if_mcp_or_web_search ################################################################################ # 生命周期钩子可以在这里内联配置，也可以放在同级 hooks.json 中。 ################################################################################ # [hooks] # [[hooks.PreToolUse]] # matcher = "^Bash$" # # [[hooks.PreToolUse.hooks]] # type = "command" # command = 'python3 "/absolute/path/to/pre_tool_use_policy.py"' # timeout = 30 # statusMessage = "Checking Bash command" ################################################################################ # 在这个 table 下定义 MCP servers。留空则表示禁用。 ################################################################################ [mcp_servers] # --- 示例：STDIO transport --- # [mcp_servers.docs] # enabled = true # 可选；默认 true # required = true # 可选；若无法初始化则启动 / 恢复失败 # command = "docs-server" # 必填 # args = ["--port", "4000"] # 可选 # env = { "API_KEY" = "value" } # 可选，按原样复制的键值对 # env_vars = ["ANOTHER_SECRET"] # 可选：从父环境转发这些变量 # env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }] # cwd = "/path/to/server" # 可选的工作目录覆盖 # experimental_environment = "remote" # 实验性：通过远程 executor 运行 stdio # startup_timeout_sec = 10.0 # 可选；默认 10.0 秒 # # startup_timeout_ms = 10000 # 可选：启动超时的毫秒别名 # tool_timeout_sec = 60.0 # 可选；默认 60.0 秒 # enabled_tools = ["search", "summarize"] # 可选 allow-list # disabled_tools = ["slow-tool"] # 可选 deny-list（在 allow-list 之后应用） # scopes = ["read:docs"] # 可选 OAuth scopes # oauth_resource = "https://docs.example.com/" # 可选 OAuth resource # --- 示例：Streamable HTTP transport --- # [mcp_servers.github] # enabled = true # 可选；默认 true # required = true # 可选；若无法初始化则启动 / 恢复失败 # url = "https://github-mcp.example.com/mcp" # 必填 # bearer_token_env_var = "GITHUB_TOKEN" # 可选；Authorization: Bearer <token> # http_headers = { "X-Example" = "value" } # 可选静态 headers # env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选：从环境变量填充的 headers # startup_timeout_sec = 10.0 # 可选 # tool_timeout_sec = 60.0 # 可选 # enabled_tools = ["list_issues"] # 可选 allow-list # disabled_tools = ["delete_issue"] # 可选 deny-list # scopes = ["repo"] # 可选 OAuth scopes ################################################################################ # Model Providers ################################################################################ # 内建 provider 包括： # - openai # - ollama # - lmstudio # - amazon-bedrock # # 自定义提供方 ID 不能复用这些内建保留名称。 [model_providers] # --- 示例：内建 Amazon Bedrock provider 选项 --- # model_provider = "amazon-bedrock" # model = "<bedrock-model-id>" # [model_providers.amazon-bedrock.aws] # profile = "default" # region = "eu-central-1" # --- 示例：带显式 base URL 或 headers 的 OpenAI data residency --- # [model_providers.openaidr] # name = "OpenAI Data Residency" # base_url = "https://us.api.openai.com/v1" # 示例中的 'us' 为域名前缀 # wire_api = "responses" # 当前唯一支持值 # # requires_openai_auth = true # 仅用于由 OpenAI auth 支撑的 provider # # request_max_retries = 4 # 默认 4；最大 100 # # stream_max_retries = 5 # 默认 5；最大 100 # # stream_idle_timeout_ms = 300000 # 默认 300_000（5 分钟） # # supports_websockets = true # 可选 # # experimental_bearer_token = "sk-example" # 可选；仅开发用途 # # http_headers = { "X-Example" = "value" } # # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" } # --- 示例：Azure / OpenAI 兼容 provider --- # [model_providers.azure] # name = "Azure" # base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai" # wire_api = "responses" # query_params = { api-version = "2025-04-01-preview" } # env_key = "AZURE_OPENAI_API_KEY" # env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment" # # supports_websockets = false # --- 示例：本地 OSS（例如兼容 Ollama）--- # [model_providers.local_ollama] # name = "Ollama" # base_url = "http://localhost:11434/v1" # wire_api = "responses" # --- 示例：通过外部凭据助手获取 bearer token --- # [model_providers.proxy] # name = "OpenAI using LLM proxy" # base_url = "https://proxy.example.com/v1" # wire_api = "responses" # # [model_providers.proxy.auth] # command = "/usr/local/bin/fetch-codex-token" # args = ["--audience", "codex"] # timeout_ms = 5000 # refresh_interval_ms = 300000 # # cwd = "/path/to/credential-helper" ################################################################################ # Apps / Connectors ################################################################################ # 可选的按 app 控制。 [apps] # [_default] 会作用于所有 app，除非被单个 app 覆盖。 # [apps._default] # enabled = true # destructive_enabled = true # open_world_enabled = true # approvals_reviewer = "user" # user | auto_review # default_tools_approval_mode = "auto" # auto | prompt | approve # # [apps.google_drive] # enabled = false # destructive_enabled = false # 阻止该 app 中带 destructive_hint 的工具 # default_tools_enabled = true # approvals_reviewer = "auto_review" # default_tools_approval_mode = "prompt" # auto | prompt | approve # # [apps.google_drive.tools."files/delete"] # enabled = false # approval_mode = "approve" # 可选：允许对可安装的 connector 或插件给出工具建议。 # [tool_suggest] # discoverables = [ # { type = "connector", id = "gmail" }, # { type = "plugin", id = "figma@openai-curated" }, # ] # disabled_tools = [ # { type = "plugin", id = "slack@openai-curated" }, # { type = "connector", id = "connector_googlecalendar" }, # ] ################################################################################ # Config Profiles（独立文件） ################################################################################ # 如需创建配置档案，请把覆盖值放进 $CODEX_HOME 下的独立配置档案文件。 # # 通过 codex --profile ci 选择。 # # 例如，CI 配置档案可以放在 $CODEX_HOME/ci.config.toml： # # model = "gpt-5.4" # approval_policy = "on-request" ################################################################################ # Projects（信任级别） ################################################################################ [projects] # 把特定 worktree 标记为 trusted 或 untrusted。 # [projects."/absolute/path/to/project"] # trust_level = "trusted" # 或 "untrusted" ################################################################################ # Tools ################################################################################ [tools] # view_image = true ################################################################################ # OpenTelemetry（OTEL）- 默认关闭 ################################################################################ [otel] # 是否在日志中包含用户提示词文本。默认：false log_user_prompt = false # 应用于 telemetry 的环境标签。默认："dev" environment = "dev" # Exporter：none（默认）| otlp-http | otlp-grpc exporter = "none" # Trace exporter：none（默认）| otlp-http | otlp-grpc trace_exporter = "none" # Metrics exporter：none | statsig | otlp-http | otlp-grpc metrics_exporter = "statsig" # OTLP/HTTP exporter 配置示例 # [otel.exporter."otlp-http"] # endpoint = "https://otel.example.com/v1/logs" # protocol = "binary" # "binary" | "json" # [otel.exporter."otlp-http".headers] # "x-otlp-api-key" = "${OTLP_TOKEN}" # [otel.exporter."otlp-http".tls] # ca-certificate = "certs/otel-ca.pem" # client-certificate = "/etc/codex/certs/client.pem" # client-private-key = "/etc/codex/certs/client-key.pem" # OTLP/gRPC trace exporter 配置示例 # [otel.trace_exporter."otlp-grpc"] # endpoint = "https://otel.example.com:4317" # headers = { "x-otlp-meta" = "abc123" } ################################################################################ # Windows ################################################################################ [windows] # 原生 Windows sandbox 模式（仅 Windows）：unelevated | elevated sandbox = "unelevated"