OpenAI Codex高级配置教程：Profiles、沙箱权限、MCP、OTel遥测全解析

资源分享助手

287人浏览 · 2026-06-13 02:01:20

资源分享助手 · 2026-06-13 02:01:20 发布

OpenAI Codex高级配置教程：Profiles、沙箱权限、MCP、OTel遥测全解析

文章标签：

OpenAI Codex Codex配置教程 config.toml MCP Server AI编程助手 Ollama Azure OpenAI OpenTelemetry AI Agent 开发效率工具

codex客户端下载：https://codexdown.cn/

在这里插入图片描述

对于很多开发者来说，安装好 OpenAI Codex 后就已经可以正常使用了。但如果你希望在团队协作、企业开发、本地模型接入、多环境切换、安全控制等场景下发挥 Codex 的全部能力，那么高级配置是必须掌握的内容。

本文将系统讲解 Codex 高级配置文件 config.toml 的核心能力，包括：

配置档案（Profiles）
模型与提供方管理
项目级配置
MCP Server 接入
生命周期 Hooks
沙箱与审批策略
Shell 环境隔离
OpenTelemetry 遥测
通知系统
历史记录管理

让你真正把 Codex 打造成符合自己工作流的 AI 开发助手。

一、Codex配置文件位置

默认情况下，Codex 会把所有配置存放在：

~/.codex

目录中。

常见文件：

文件	作用
config.toml	主配置文件
auth.json	认证信息
history.jsonl	历史会话
logs	日志目录
cache	缓存目录

目录结构：

~/.codex
├── config.toml
├── auth.json
├── history.jsonl
├── logs
└── cache

二、Profiles配置档案

如果你有多个开发场景：

日常开发
代码审查
AI测试
本地模型

可以使用 Profiles。

例如：

# ~/.codex/deep-review.config.toml

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"

启动：

codex --profile deep-review

执行：

codex exec --profile deep-review "review this change"

这样就不需要频繁修改主配置文件。

三、CLI临时覆盖配置

有时候只想临时修改参数。

例如：

codex --model gpt-5.4

或者：

codex --config model='"gpt-5.4"'

修改网络权限：

codex --config sandbox_workspace_write.network_access=true

修改环境变量白名单：

codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

说明：

–config 使用 TOML 语法，不是 JSON。

四、项目级配置

除了全局配置：

~/.codex/config.toml

Codex 还支持项目配置：

project/
└── .codex/
    └── config.toml

例如：

model = "gpt-5.5"
approval_policy = "on-request"

这样进入项目后自动生效。

配置优先级

CLI参数
↓
项目配置
↓
Profile配置
↓
用户配置
↓
默认配置

离当前工作目录最近的配置优先级最高。

五、生命周期Hooks

Hooks类似 Git Hook。

可在工具执行前后运行脚本。

例如：

[[hooks.PreToolUse]]

matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"

command = '''
python3 pre_tool_use_policy.py
'''

执行 Bash 前：

Codex
 ↓
Hook检查
 ↓
允许执行

用途：

安全审计
命令过滤
自动日志记录
CI检查

六、自定义项目根目录

默认情况下：

.git

会被视为项目根目录。

可以修改：

project_root_markers = [
    ".git",
    ".hg",
    ".sl"
]

支持：

Git
Mercurial
Sapling

甚至：

project_root_markers = []

关闭自动查找。

七、自定义模型提供方

很多用户会接入：

OpenAI Proxy
OneAPI
NewAPI
FastGPT
SiliconFlow
DeepSeek Gateway

配置方式：

model = "gpt-5.5"

model_provider = "proxy"

[model_providers.proxy]

name = "LLM Proxy"

base_url = "https://proxy.example.com/v1"

env_key = "OPENAI_API_KEY"

添加请求头

[model_providers.proxy]

http_headers = {
  "X-Source" = "Codex"
}

命令式认证

适用于企业SSO。

[model_providers.proxy.auth]

command = "/usr/local/bin/get-token"

timeout_ms = 5000

refresh_interval_ms = 300000

每隔5分钟自动刷新Token。

八、Amazon Bedrock接入

配置：

model_provider = "amazon-bedrock"

model = "anthropic.claude"

[model_providers.amazon-bedrock.aws]

profile = "default"

region = "eu-central-1"

支持：

Claude
Nova
Llama
Titan

等 Bedrock 模型。

九、本地大模型模式（OSS）

Codex 可以直接连接：

Ollama
LM Studio

配置：

oss_provider = "ollama"

启动：

codex --oss

即可使用本地模型。

十、Azure OpenAI配置

Azure用户：

[model_providers.azure]

name = "Azure"

base_url = "https://xxx.openai.azure.com/openai"

env_key = "AZURE_OPENAI_API_KEY"

query_params = {
  api-version = "2025-04-01-preview"
}

wire_api = "responses"

十一、模型推理参数

控制推理强度

model_reasoning_effort = "high"

可选：

low
medium
high
xhigh

控制回答长度

model_verbosity = "low"

可选：

low
medium
high

上下文长度

model_context_window = 128000

128K上下文。

十二、审批与沙箱

这是企业环境最重要的配置之一。

例如：

approval_policy = "untrusted"

sandbox_mode = "workspace-write"

含义：

配置	说明
never	不审批
on-request	请求审批
untrusted	未信任环境审批

工作区写权限

[sandbox_workspace_write]

writable_roots = [
  "/Users/me/project"
]

network_access = false

禁止联网：

network_access = false

允许联网：

network_access = true

危险模式

sandbox_mode = "danger-full-access"

此模式拥有全部权限。

建议仅在：

Docker
虚拟机
隔离环境

中使用。

十三、Shell环境变量隔离

很多公司会在环境变量中存储：

AWS_KEY
TOKEN
SECRET

可以限制传递：

[shell_environment_policy]

inherit = "none"

include_only = [
  "PATH",
  "HOME"
]

进一步屏蔽：

exclude = [
  "AWS_*",
  "AZURE_*"
]

提高安全性。

十四、MCP Server支持

Codex 已完整支持 MCP。

可接入：

Context7
Browser MCP
GitHub MCP
PostgreSQL MCP
Notion MCP
Figma MCP

统一配置：

[mcp_servers.xxx]

实现：

Codex
 ↓
MCP
 ↓
外部工具

让 AI 直接访问业务系统。

十五、OpenTelemetry监控

企业环境非常实用。

开启：

[otel]

environment = "production"

exporter = "otlp-http"

上传到：

Grafana
Jaeger
Datadog
Elastic

监控内容

包括：

API请求
Token消耗
Tool调用
审批记录
SSE事件
WebSocket事件

例如：

codex.api_request

codex.tool.call

codex.websocket.event

codex.turn.token_usage

十六、关闭匿名统计

如果你不希望上传匿名指标：

[analytics]

enabled = false

即可关闭。

十七、通知系统

当任务完成时：

notify = [
  "python3",
  "/path/notify.py"
]

Codex会调用：

notification = json.loads(sys.argv[1])

可用于：

企业微信通知
钉钉通知
飞书通知
Webhook通知

十八、历史记录管理

默认：

~/.codex/history.jsonl

保存所有会话。

关闭：

[history]

persistence = "none"

限制大小：

[history]

max_bytes = 104857600

即：

100MB

十九、VSCode可点击文件链接

配置：

file_opener = "vscode"

支持：

vscode
cursor
windsurf
vscode-insiders

例如：

src/main.py:42

自动变成：

vscode://file/src/main.py:42

点击即可跳转。

二十、TUI终端界面配置

Codex TUI支持：

[tui]

常见配置：

[tui]

notifications = true

notification_method = "auto"

notification_condition = "unfocused"

animations = false

alternate_screen = "never"

show_tooltips = false

适合：