客户端集成

Codex CLI 集成指南

配置开源本地终端代码智能生成与重构工具 Codex，通过覆盖 API 映射基址与模型参数，重定向至 tflow 统一入口。

什么是 Codex CLI？

Codex CLI 是一个终端本地命令行智能工具，专为终端下的快速代码片段生成、Shell 命令解释以及跨文件重构而设计。通过在本地配置文件中注册自定义提供商属性，可以轻松将其底层的 API 适配器对接到 tflow 中，利用网关的高并发与多渠道融合能力提供稳定的生成效果。

快速开始 (Quick Start)

仅需四步，即可将本地 Codex CLI 与 tflow 极速绑定。

1安装 Codex CLI

请参考 Codex CLI GitHub 官方仓库的安装说明，在您的本地系统终端中安装该命令行辅助工具。

2配置 config.toml

打开或创建您的 Codex 全局本地配置文件，默认路径通常为：~/.codex/config.toml

将默认模型提供商覆盖为 `tflow`，并指定自定义地址与密钥关联：

config.toml

# ~/.codex/config.toml
model_provider = "tflow"
model = "deepseek-v4-pro"
model_reasoning_effort = "high"       # 推理模型的思考深度控制 (low, medium, high, xhigh)
show_raw_agent_reasoning = true       # 是否在终端中显示推理模型的 Thinking 过程
personality = "pragmatic"             # 智能体性格预设 (如 pragmatic, helpful)

[model_providers.tflow]
name = "tflow"
base_url = "https://tflow.ai-links.com/v1"
env_key = "TFLOW_API_KEY"

3导出系统密钥变量

在当前终端中或者写入您的 Shell Profile（如 ~/.zshrc、~/.bash_profile），导出刚才在 `config.toml` 中配置的关联环境变量密钥：

terminal.sh

export TFLOW_API_KEY="sk-your-key"

设置完成后在终端执行一次 source ~/.zshrc 使其生效。

说明： Codex 在启动时会自动读取我们在 `env_key` 里指定的系统环境变量名（默认为 `TFLOW_API_KEY`）的键值，请确保此环境变量已成功注入。

4运行并启动 Codex

打开您的系统终端，进入到具体的开发工程项目目录中，运行 Codex CLI：

terminal.sh

# 进入项目目录并启动 Codex CLI
cd /path/to/your/project
codex

此时 Codex 将完全对接至 tflow 并启动终端智能交互或监听，后续所有的补全与生成流量都将经过您的 tflow 网关。

配置参考与安全控制

了解 Codex CLI 核心参数及其高级安全功能特征。

配置项	描述	示例 / 可选项
model_provider	指定发送模型请求的自定义提供商配置组	"tflow"
model	调用的目标模型标识（支持在网关后台重映射）	"deepseek-v4-pro"
model_reasoning_effort	针对推理模型的思考深度（如 OpenAI o1/o3-mini 模型）	"low", "medium", "high", "xhigh"
show_raw_agent_reasoning	是否在终端中显示推理型模型的完整思考链路	true \| false
personality	设置智能体的交互性格特征预设	"pragmatic", "helpful"

项目安全与信任级别 (Project Trust Levels)

由于 Codex CLI 作为自主智能体会执行测试运行、重构和自动命令等高权限操作，它支持按项目目录路径进行隔离与授权控制：

config.toml (追加配置)

# ~/.codex/config.toml 中追加项目安全沙盒控制
[projects."/path/to/trusted/project"]
trust_level = "trusted"     # 授信项目：允许自动运行命令、自由修改文件

[projects."/path/to/untrusted/project"]
trust_level = "untrusted"   # 非授信项目：敏感操作（运行脚本、修改关键文件）强制弹窗确认

trusted (授信级别)

Agent 具有完整的本地系统执行权限（包括自动测试运行、脚本执行、代码写入）。

untrusted (限制级别)

Agent 的部分文件读写、指令执行等动作将受限，并在尝试关键行为时要求用户确认。

常见问题与诊断

报错：API 密钥验证失败或未设置

请务必检查 `config.toml` 中配置的 env_key 字段是否与您在终端中导出的环境变量名称完全一致。例如，如果您将 env_key 指定为 `TFLOW_API_KEY`，那么您执行的导出指令必须是 export TFLOW_API_KEY="..."。

模型请求返回空或者报错 "Model Not Found"

这是因为 Codex CLI 内部默认的配置模型在网关后台未能匹配。请在 `config.toml` 中配置合适的模型标识，或者在后台添加模型路由转发别名，将其映射到您在网关中的有效模型服务上。