示例配置
将此示例配置作为起点。它包含 Codex 从 config.toml 读取的大多数键,以及默认行为、适用时的推荐值和简短说明。
如需了解说明和指南,请参阅:
请参考下面的代码片段。仅将所需的键和部分复制到 ~/.codex/config.toml(或项目范围的 .codex/config.toml)中,然后根据你的设置调整值。
# Codex 示例配置(config.toml)# # 此文件列出了 Codex 从 config.toml 读取的主要键,以及默认行为、# 推荐示例和简要说明。请根据需要进行调整。# # 注意事项# - 在 TOML 中,根键必须出现在表之前。# - 默认值为“未设置”的可选键会以注释形式显示,并附有说明。# - MCP 服务器、配置文件和模型提供商仅为示例;请删除或编辑。################################################################################
# 核心模型选择################################################################################
# Codex 使用的主要模型。大多数用户的推荐示例:“gpt-5.6”。model = "gpt-5.6"
# 支持的模型所使用的沟通风格。允许的值:none | friendly | pragmatic# personality = "pragmatic"# /review 使用的可选模型覆盖值。默认:未设置(使用当前会话模型)。# review_model = "gpt-5.6"# 从 [model_providers] 中选择的提供商 ID。默认:“openai”。model_provider = "openai"
# --oss 会话的默认 OSS 提供商。未设置时,Codex 会提示你选择。默认:未设置。# oss_provider = "ollama"# 首选服务层级。使用 fast,或使用当前模型支持的其他层级。# service_tier = "fast"# 可选的手动模型元数据。未设置时,Codex 使用模型或预设的默认值。# model_context_window = 128000 # 令牌;默认:根据模型自动确定# model_auto_compact_token_limit = 64000 # 令牌;未设置时使用模型默认值# model_auto_compact_token_limit_scope = "total" # total | body_after_prefix;默认:total# tool_output_token_limit = 12000 # 每个工具输出中存储的令牌数# model_catalog_json = "/absolute/path/to/models.json" # 可选,仅在启动时覆盖模型目录# background_terminal_max_timeout = 300000 # 毫秒;write_stdin 空轮询的最大窗口(默认 5 分钟)# log_dir = "/absolute/path/to/codex-logs" # 日志目录;显式设置后启用 codex-tui.log;默认:“$CODEX_HOME/log”# sqlite_home = "/absolute/path/to/codex-state" # 可选,使用 SQLite 的运行时状态目录################################################################################
# 推理与详细程度(支持 Responses API 的模型)################################################################################
# 推理力度:minimal | low | medium | high | xhigh# model_reasoning_effort = "medium"# Codex 在计划模式下运行时使用的可选覆盖值: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"# 强制启用或禁用当前模型的推理摘要。# model_supports_reasoning_summaries = true################################################################################
# 指令覆盖################################################################################
# 注入到 AGENTS.md 之前的其他用户指令。默认:未设置。# developer_instructions = ""# 历史压缩提示词的内联覆盖值。默认:未设置。# compact_prompt = ""# 使用文件路径覆盖内置基础指令。# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"# 从文件加载压缩提示词覆盖值。# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"################################################################################
# 通知################################################################################
# 外部通知程序(argv 数组)。未设置时:禁用。# notify = ["notify-send", "Codex"]################################################################################
# 审批与沙箱################################################################################
# 何时请求命令审批:# - 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` 时,允许使用登录 shell 语义。# 默认:true。设置为 false 可强制使用非登录 shell,并拒绝显式的登录 shell 请求。allow_login_shell = true
# 工具调用的文件系统/网络沙箱策略:# - read-only(默认)# - workspace-write# - danger-full-access(无沙箱;风险极高)sandbox_mode = "read-only"
# 默认应用的命名权限配置。内置配置:# :read-only | :workspace | :danger-full-access# 只有同时定义 [permissions.workspace] 时,才能使用诸如 "workspace" 这样的自定义名称。# default_permissions = ":workspace"################################################################################
# 身份验证与登录################################################################################
# CLI 登录凭据的持久化位置:file(默认)| keyring | autocli_auth_credentials_store = "file"
# ChatGPT 身份验证流程的基础 URL(不是 OpenAI API)。chatgpt_base_url = "https://chatgpt.com/backend-api/"
# 内置 OpenAI 提供商的可选基础 URL 覆盖值。# openai_base_url = "https://us.api.openai.com/v1"# 将 ChatGPT 登录限制到特定的工作区 ID。默认:未设置。# forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"# 当 Codex 通常会自动选择登录机制时,强制使用指定机制。默认:未设置。# 允许的值:chatgpt | api# forced_login_method = "chatgpt"# MCP OAuth 凭据的首选存储位置:auto(默认)| file | keyringmcp_oauth_credentials_store = "auto"
# MCP OAuth 回调使用的可选固定端口:1-65535。默认:未设置。# mcp_oauth_callback_port = 4321# MCP OAuth 登录的可选重定向 URI 覆盖值(例如远程 devbox 的入口)。# Codex 会在 OAuth 登录前追加服务器专用的回调 ID。# 请向提供商注册完整的派生 URI,而不仅是基础主机或未附加 ID 的路径。# 支持自定义回调路径。`mcp_oauth_callback_port` 仍控制监听端口。# mcp_oauth_callback_url = "https://devbox.example.internal/callback"################################################################################
# 项目文档控制################################################################################
# 从 AGENTS.md 嵌入首轮指令的最大字节数。默认:32768project_doc_max_bytes = 32768
# 当某个目录层级缺少 AGENTS.md 时按顺序使用的备用文件名。默认:[]project_doc_fallback_filenames = []
# 搜索父目录时用于标记项目根目录的文件名。默认:[".git"]# project_root_markers = [".git"]################################################################################
# 历史记录与文件打开器################################################################################
# 可点击引用的 URI 方案:vscode(默认)| vscode-insiders | windsurf | cursor | nonefile_opener = "vscode"
################################################################################
# 界面、通知及其他################################################################################
# 禁止在输出中显示内部推理事件。默认:falsehide_agent_reasoning = false
# 在可用时显示原始推理内容。默认:falseshow_raw_agent_reasoning = false
# 禁用 TUI 中的连续粘贴检测。默认:falsedisable_paste_burst = false
# 记录 Windows 新手引导确认状态(仅限 Windows)。默认:falsewindows_wsl_setup_acknowledged = false
# 启动时检查更新。默认:truecheck_for_update_on_startup = true
################################################################################
# Web 搜索################################################################################
# Web 搜索模式:disabled | cached | indexed | live。默认:"cached"# cached 从 Web 搜索缓存(由 OpenAI 维护的索引)提供结果。# cached 返回预先建立索引的结果;indexed 通过搜索索引控制外部 Web 访问;# live 获取最新数据。# 如果使用 --yolo 或其他完全访问权限的沙箱设置,Web 搜索默认为 live。web_search = "cached"
# 配置配置文件是 CODEX_HOME 下的独立文件。# 示例:~/.codex/ci.config.toml,使用 codex --profile ci 选择。# 禁止显示启用开发中功能标志时出现的警告。# suppress_unstable_features_warning = true################################################################################
# Agent(多 Agent 角色与限制)################################################################################
[agents]
# 启用或禁用多 Agent 工具。默认:true# enabled = true# 可同时打开的已生成 Agent 线程的最大数量,不包括主线程。未设置时由 Codex 选择默认值。# max_concurrent_threads_per_session = 6# 已生成 Agent 的默认模型。显式指定的生成模型优先级更高。# default_subagent_model = "gpt-5.6-terra"# 已生成 Agent 的默认推理力度。显式指定的生成推理力度优先级更高。# default_subagent_reasoning_effort = "high"# Agent 轮次中断时,记录一条模型可见消息。默认:true# interrupt_message = true# [agents.reviewer]# description = "查找代码中的正确性、安全性和测试风险。"# config_file = "./agents/reviewer.toml" # 相对于定义该配置的 config.toml################################################################################
# 技能(按技能覆盖)################################################################################
# 禁用或重新启用特定技能,而无需删除该技能。[[skills.config]]
# path = "/path/to/skill/SKILL.md"# enabled = false################################################################################
# 沙箱设置(表)################################################################################
# 仅在 sandbox_mode = "workspace-write" 时使用的其他设置。[sandbox_workspace_write]
# 除工作区(当前工作目录)之外的其他可写根目录。默认:[]writable_roots = []
# 允许沙箱内的出站网络访问。默认:falsenetwork_access = false
# 将 $TMPDIR 排除在可写根目录之外。默认:falseexclude_tmpdir_env_var = false
# 将 /tmp 排除在可写根目录之外。默认:falseexclude_slash_tmp = false
################################################################################
# 已沙箱化的网络设置################################################################################
# 在配置已沙箱化的网络规则前启用此功能。# [features.network_proxy]# enabled = true# domains = { "api.openai.com" = "allow", "example.com" = "deny" }# # 精确主机仅匹配其自身。# "\*.example.com" 仅匹配子域名;"\*\*.example.com" 匹配顶级域名及其子域名。# "\*" 允许任何未被拒绝的公共主机,因此应尽可能使用限定范围的规则。# `allow_local_binding = false` 默认阻止环回地址和私有目标。# 为一个目标添加精确的本地 IP 字面量或 `localhost` 允许规则;只有在需要更广泛的本地访问时,才将其设置为 true。# # 启用此配置文件前设置 `default_permissions = "workspace"`。# 继承此配置文件 `:workspace_roots` 文件系统规则的其他工作区根目录示例。# [permissions.workspace.workspace_roots]# "~/code/app" = true# "~/code/shared-lib" = true# # 文件系统配置示例。使用 `"deny"` 拒绝读取精确路径或# glob 模式。在需要预先展开 glob 匹配项的平台上,使用无界模式(如 `\*\*`)时设置# 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]
# save-all(默认)| nonepersistence = "save-all"
# 历史记录文件的最大字节数;超出后会删除最早的条目。示例:5242880# max_bytes = 5242880################################################################################
# 界面、通知及其他(表)################################################################################
[tui]
# TUI 的桌面通知:布尔值或筛选列表。默认:true# 示例:false | ["agent-turn-complete", "approval-requested"]notifications = false
# 终端提醒的通知机制:auto | osc9 | bel。默认:"auto"# notification_method = "auto"# 通知触发时机:unfocused(默认)| always# notification_condition = "unfocused"# 启用欢迎页、状态和微调器动画。默认:trueanimations = true
# 在欢迎屏幕中显示新手引导工具提示。默认:trueshow_tooltips = true
# 控制备用屏幕的使用(在 Zellij 中,auto 会跳过备用屏幕以保留滚屏内容)。# alternate_screen = "auto"# 页脚状态栏项目 ID 的有序列表。未设置时,Codex 使用:# ["model-with-reasoning", "context-remaining", "current-dir"]。# 设置为 [] 可隐藏页脚。# status_line = ["model", "context-remaining", "git-branch"]# 终端窗口/标签页标题项目 ID 的有序列表。未设置时,Codex 使用:# ["spinner", "project"]。设置为 [] 可清除标题。# 可用 ID 包括 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"# 自定义按键绑定。选定的编辑器操作会回退到匹配的 [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"# 按模型 slug 保存的内部工具提示状态。通常由 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" }################################################################################
# 集中式功能标志(推荐)################################################################################
[features]
# 将此表留空以接受默认值。设置显式布尔值可选择启用或退出功能。# shell_tool = true# apps = true# hooks = false# unified_exec = true# shell_snapshot = true# multi_agent = true# remote_plugin = true# personality = true# network_proxy = false# fast_mode = true# enable_request_compression = true# skill_mcp_dependency_install = true# prevent_idle_sleep = false# Code 模式命名空间。此功能正在开发中,默认关闭。# [features.code_mode]# enabled = true# excluded_tool_namespaces = ["mcp__codex_apps"]# direct_only_tool_namespaces = ["mcp__history"]# 发布预算跟踪。此功能正在开发中,默认关闭。# 启用后必须设置 limit_tokens。# 可选的 reminder_interval_tokens 默认为 limit_tokens 的 10%。# 令牌权重默认为 1.0。# [features.rollout_budget]# enabled = true# limit_tokens = 100000# reminder_interval_tokens = 10000# sampling_token_weight = 1.0# prefill_token_weight = 1.0################################################################################
# 记忆(表)################################################################################
# 使用 [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"################################################################################
# 在此表下定义 MCP 服务器。留空可禁用。################################################################################
[mcp_servers]
# --- 示例:STDIO 传输 ---# [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" # 实验性:通过远程执行器运行 stdio# startup_timeout_sec = 10.0 # 可选;默认 10.0 秒# startup_timeout_ms = 10000 # 可选的启动超时别名(毫秒)# tool_timeout_sec = 60.0 # 可选;默认 60.0 秒# enabled_tools = ["search", "summarize"] # 可选允许列表# disabled_tools = ["slow-tool"] # 可选拒绝列表(在允许列表之后应用)# scopes = ["read:docs"] # 可选 OAuth 作用域# oauth_resource = "https://docs.example.com/" # 可选 OAuth 资源# --- 示例:可流式传输的 HTTP 传输 ---# [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" } # 可选静态标头# env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选,从环境变量填充的标头# startup_timeout_sec = 10.0 # 可选# tool_timeout_sec = 60.0 # 可选# enabled_tools = ["list_issues"] # 可选允许列表# disabled_tools = ["delete_issue"] # 可选拒绝列表# scopes = ["repo"] # 可选 OAuth 作用域################################################################################
# 模型提供商################################################################################
# 内置提供商包括:# - openai# - ollama# - lmstudio# - amazon-bedrock# 这些 ID 已被保留。自定义提供商请使用其他 ID。[model_providers]
# --- 示例:内置 Amazon Bedrock 提供商选项 ---# model_provider = "amazon-bedrock"# model = "<bedrock-model-id>"# [model_providers.amazon-bedrock.aws]# profile = "default"# region = "eu-central-1"# --- 示例:使用显式基础 URL 或标头的 OpenAI 数据驻留 ---# [model_providers.openaidr]# name = "OpenAI Data Residency"# base_url = "https://us.api.openai.com/v1" # 使用 'us' 域名前缀的示例# wire_api = "responses" # 唯一支持的值# requires_openai_auth = true # 仅用于由 OpenAI 身份验证支持的提供商# 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" # 可选,仅供开发使用的直接 bearer token# http_headers = { "X-Example" = "value" }# env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }# --- 示例:Azure/OpenAI 兼容提供商 ---# [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# --- 示例:由命令提供 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# --- 示例:本地 OSS(例如兼容 Ollama 的提供商)---# [model_providers.local_ollama]# name = "Ollama"# base_url = "http://localhost:11434/v1"# wire_api = "responses"################################################################################
# 应用/连接器################################################################################
# 可选的按应用控制项。[apps]
# [_default] 适用于所有应用,除非按应用覆盖。# [apps._default]# enabled = true# destructive_enabled = true# open_world_enabled = true# approvals_reviewer = "user" # user | auto_review# default_tools_approval_mode = "auto" # auto | prompt | writes | approve# # [apps.google_drive]# enabled = false# destructive_enabled = false # 阻止此应用中带有破坏性提示的工具# default_tools_enabled = true# approvals_reviewer = "auto_review"# default_tools_approval_mode = "prompt" # auto | prompt | writes | approve# # [apps.google_drive.tools."files/delete"]# enabled = false# approval_mode = "approve"# 可选的工具建议允许列表,用于指定 Codex 可以建议安装的连接器或插件。# [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" },# ]################################################################################
# 配置配置文件(独立文件)################################################################################
# 如需创建配置配置文件,请将覆盖值放入 $CODEX_HOME 下的独立配置文件中。# 使用 codex --profile ci 选择该配置文件。# 例如,CI 配置文件可以位于 $CODEX_HOME/ci.config.toml:# model = "gpt-5.4"# approval_policy = "on-request"# sandbox_mode = "read-only"# service_tier = "fast" # 或其他受支持的服务层级 ID# oss_provider = "ollama"# model_reasoning_effort = "medium"# plan_mode_reasoning_effort = "high"# model_reasoning_summary = "auto"# model_verbosity = "medium"# personality = "pragmatic" # 或 "friendly" 或 "none"# chatgpt_base_url = "https://chatgpt.com/backend-api/"# model_catalog_json = "./models.json"# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"# experimental_compact_prompt_file = "./compact_prompt.txt"# tools_view_image = true# features = { unified_exec = false }################################################################################
# 项目(信任级别)################################################################################
[projects]
# 将特定工作树标记为受信任或不受信任。# [projects."/absolute/path/to/project"]# trust_level = "trusted" # 或 "untrusted"################################################################################
# 工具################################################################################
[tools]
# view_image = true################################################################################
# OpenTelemetry(OTEL)——默认禁用################################################################################
[otel]
# 将用户提示词文本包含在日志中。默认:falselog_user_prompt = false
# 应用于遥测的环境标签。默认:"dev"environment = "dev"
# 导出器:none(默认)| otlp-http | otlp-grpcexporter = "none"
# 跟踪导出器:none(默认)| otlp-http | otlp-grpctrace_exporter = "none"
# 指标导出器:none | statsig | otlp-http | otlp-grpcmetrics_exporter = "statsig"
# OTLP/HTTP 导出器配置示例# [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 跟踪导出器配置示例# [otel.trace_exporter."otlp-grpc"]# endpoint = "https://otel.example.com:4317"# headers = { "x-otlp-meta" = "abc123" }################################################################################
# Windows################################################################################
[windows]
# 原生 Windows 沙箱模式(仅限 Windows):unelevated | elevatedsandbox = "unelevated"