Codex CLI

Codex CLI 是 OpenAI 开源的终端编码 Agent，支持文件读取、代码修改和命令执行。通过自定义 Provider，可在本地项目中使用 Step Plan 模型完成开发任务。

接入条件

已安装 Node.js、npm、curl 和 Python 3。以下终端命令适用于 Bash 或 zsh，Windows 用户可在 WSL 中执行。
Step Plan 订阅有效、额度可用，且具备所用模型的调用权限。
已在 StepFun 开放平台密钥管理页面创建 API Key。

接入说明

Codex CLI 0.154.0 仅支持 Responses API，wire_api 使用 responses。Step Plan 提供 /step_plan/v1/responses，可直接连接，无需协议转换代理。
用户配置写入 $CODEX_HOME/config.toml，CODEX_HOME 默认为 ~/.codex。API Key 通过环境变量或该目录下的 .env 提供，不写入 config.toml。
Codex 的内置模型目录主要提供 OpenAI 模型元数据。本配置通过 model_catalog_json 声明 Step 模型名称、上下文窗口和输入能力，使其在 /model 中可选；模型目录只在 Step 专用 profile 中启用。

安装 Codex CLI

安装 Codex CLI 0.154.0：

npm install -g @openai/codex@0.154.0

检查安装版本：

codex --version

预期输出为 codex-cli 0.154.0。

配置 Step Plan

确定配置目录

在终端执行以下命令，保留已有的 CODEX_HOME 设置；未设置时使用默认目录：

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME"
export CODEX_HOME="$(cd "$CODEX_HOME" && pwd)"

如需与日常配置分开，改用独立目录后再继续配置：

export CODEX_HOME="$HOME/.codex-step-plan"
mkdir -p "$CODEX_HOME"

请在同一终端中完成后续配置与启动。以后使用独立配置目录时，也需先设置对应的 CODEX_HOME。

添加 Provider

编辑 $CODEX_HOME/config.toml，合并以下配置，保留其他设置。若已存在 [model_providers.stepfun]，更新该表即可。

[model_providers.stepfun]
name = "StepFun Step Plan"
base_url = "https://api.stepfun.com/step_plan/v1"
env_key = "STEP_API_KEY"
wire_api = "responses"

字段	说明
`model_providers.stepfun`	Provider 标识，后续通过 `model_provider = "stepfun"` 引用。
`base_url`	Step Plan 基础地址。Codex 自动追加 `/responses`，完整请求路径为 `/step_plan/v1/responses`。
`env_key`	提供 API Key 的环境变量名称，不是密钥本身。
`wire_api`	使用 Responses API，填写 `responses`。

Provider 定义必须放在用户级配置中。Codex 会忽略项目 .codex/config.toml 中的 model_provider 和 model_providers。自定义 Provider 也不能使用 openai、ollama、lmstudio 等保留标识。

设置 API Key

将 YOUR_STEP_API_KEY 替换为实际密钥，选择以下一种方式配置。在启动 Codex 的终端中设置环境变量：

export STEP_API_KEY="YOUR_STEP_API_KEY"

也可编辑 $CODEX_HOME/.env，添加或更新以下内容，由 Codex 启动时加载：

STEP_API_KEY=YOUR_STEP_API_KEY

设置文件权限：

chmod 600 "$CODEX_HOME/.env"

.env 以明文保存 API Key，请勿将该文件提交到代码仓库或分享给他人。

创建模型目录

下载与 Codex CLI 0.154.0 对应的默认 Agent 指令，作为模型目录中的 base_instructions：

curl -fsSL https://raw.githubusercontent.com/openai/codex/rust-v0.154.0/codex-rs/protocol/src/prompts/base_instructions/default.md \
  -o "$CODEX_HOME/default.md"

确认文件非空：

test -s "$CODEX_HOME/default.md" && wc -c "$CODEX_HOME/default.md"

生成 $CODEX_HOME/step-catalog.json：

python3 - <<'PY'
import json
import os

home = os.environ["CODEX_HOME"]

with open(os.path.join(home, "default.md"), encoding="utf-8") as instructions_file:
    base_instructions = instructions_file.read()

def entry(slug, name, description, context_window, input_modalities):
    return {
        "slug": slug,
        "display_name": name,
        "description": description,
        "context_window": context_window,
        "input_modalities": input_modalities,
        "base_instructions": base_instructions,
        "visibility": "list",
        "supported_in_api": True,
        "priority": 1,
        "availability_nux": None,
        "upgrade": None,
        "default_reasoning_level": "medium",
        "supported_reasoning_levels": [
            {"effort": "low", "description": "较低推理强度"},
            {"effort": "medium", "description": "中等推理强度（默认）"},
            {"effort": "high", "description": "较高推理强度"},
        ],
        "supports_reasoning_summaries": True,
        "default_reasoning_summary": "auto",
        "support_verbosity": False,
        "default_verbosity": None,
        "apply_patch_tool_type": "freeform",
        "web_search_tool_type": "text",
        "shell_type": "shell_command",
        "truncation_policy": {"mode": "tokens", "limit": 10000},
        "supports_parallel_tool_calls": False,
        "supports_image_detail_original": False,
        "effective_context_window_percent": 95,
        "experimental_supported_tools": [],
        "supports_search_tool": False,
    }

models = [
    entry("step-5-preview", "Step 5 Preview", "StepFun 1M 多模态", 1000000, ["text", "image"]),
    entry("step-3.7-flash", "Step 3.7 Flash", "StepFun 256K", 256000, ["text", "image"]),
    entry("step-3.5-flash", "Step 3.5 Flash", "StepFun 256K", 256000, ["text"]),
]

catalog_path = os.path.join(home, "step-catalog.json")

with open(catalog_path, "w", encoding="utf-8") as catalog_file:
    json.dump({"models": models}, catalog_file, ensure_ascii=False, indent=2)

print("已生成:", catalog_path)
print("模型:", [model["slug"] for model in models])
PY

生成结果应包含 step-5-preview、step-3.7-flash 和 step-3.5-flash。可按账号权限增删 entry(...) 条目。模型目录字段与 Codex 版本相关，升级后应按目标版本重新检查。

创建 Step 专用配置

新建 $CODEX_HOME/step.config.toml。首次创建时可执行以下命令；文件已存在时，请合并配置，保留其他设置。

cat > "$CODEX_HOME/step.config.toml" <<EOF
model = "step-5-preview"
model_provider = "stepfun"
model_catalog_json = "$CODEX_HOME/step-catalog.json"
web_search = "disabled"
EOF

检查配置，确认 model_catalog_json 是绝对路径：

cat "$CODEX_HOME/step.config.toml"

--profile step 会在基础 config.toml 之上加载 step.config.toml，并复用其中定义的 Provider。model_catalog_json 会替换启动时使用的模型目录，因此应保留在专用 profile 中。不带 --profile step 启动时，不加载该 profile。

启动 Codex CLI

确认所需文件存在：

ls "$CODEX_HOME"/config.toml \
   "$CODEX_HOME"/step.config.toml \
   "$CODEX_HOME"/step-catalog.json

codex --profile step

核对当前模型为 step-5-preview、Provider 为 stepfun。输入 /model，检查是否可以选择模型目录中的 Step 模型。

恢复此前使用 Step Provider 创建的会话时，继续指定相同的 profile，将 YOUR_SESSION_ID 替换为实际会话 ID：

codex resume --profile step YOUR_SESSION_ID

/model 切换当前 Provider 下的模型。需要使用其他 Provider 时，通过对应的 profile 启动独立会话。

接入 StepSearch MCP

StepSearch 提供 web_search 和 web_fetch，用于联网搜索与网页内容获取。需要这些能力时，可通过 Step Plan 端点接入。

确认已按前文配置 STEP_API_KEY，然后注册 MCP 服务：

codex mcp add step-search \
  --url https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp \
  --bearer-token-env-var STEP_API_KEY

检查注册结果：

codex mcp list

重新启动 codex --profile step，通过 /mcp 检查服务与工具是否已加载，再发起一次搜索或网页抓取任务，核对工具调用记录及返回结果。

codex mcp add 使用当前 CODEX_HOME，配置不只作用于 step profile。如需与日常 MCP 设置分开，请使用独立配置目录。Step 专用 profile 通过 web_search = "disabled" 关闭内置网页搜索，搜索工具由 StepSearch MCP 提供。

验证接入

验证对话

在交互会话中输入 请只回复 OK。，预期返回 OK。也可在项目目录中执行只读验证：

codex exec --profile step --sandbox read-only "请只回复 OK。" < /dev/null

验证工具调用

在独立测试目录中创建 README.md，内容为 Codex Step Plan test。从该目录启动 Codex，输入：

读取 README.md，创建 hello.py，使其打印 "Hello, world!"。
使用本机可用的 Python 解释器运行 hello.py，并报告执行命令和实际输出。
不要修改 README.md 或其他已有文件。

根据提示确认必要的操作权限，核对文件读取、创建和命令执行记录。确认 hello.py 实际生成，输出为 Hello, world!，且 README.md 未被修改。

常见问题

Q: 启动后要求登录 ChatGPT 怎么办？

核对 CODEX_HOME、step.config.toml 中的 model_provider = "stepfun"，以及启动命令是否包含 --profile step。确认用户级 config.toml 中存在对应 Provider，且 API Key 已通过环境变量或 .env 提供。使用独立配置目录时，在当前终端重新设置 CODEX_HOME 后启动。

Q: /model 中没有 Step 模型或出现 Model metadata not found 怎么办？

检查所选 profile 的 model_catalog_json 是否指向有效的绝对路径，以及目录中的模型 ID 是否正确。修改后重启 Codex；若仍显示旧列表，退出 Codex，移除当前 CODEX_HOME 下的 models_cache.json 后重试。

Q: 模型目录报 missing field 怎么办？

模型目录缺少当前 Codex 版本要求的字段。使用与目标版本匹配的结构重新生成 step-catalog.json，并确认 default.md 下载成功且非空。不要将其他版本的精简目录直接用于当前版本。

Q: 连接失败、持续重连或返回 401 怎么办？

查看完整错误信息，检查网络连接、API Key 状态与模型权限。base_url 使用 https://api.stepfun.com/step_plan/v1，wire_api 使用 responses；确认 env_key 与实际环境变量名称一致，且密钥属于所用端点对应的账号。

Q: codex exec 一直等待标准输入怎么办？

如果输出停留在 Reading additional input from stdin...，且无需通过标准输入提供内容，在命令末尾添加 < /dev/null。

Q: 回复为空或返回 incomplete 怎么办？

检查服务端返回状态、错误详情与 Token 用量。推理消耗和输出预算不足都可能影响正文生成；确认具体原因后，再使用目标客户端版本与服务端支持的参数调整。

Q: MCP 已注册，但会话中没有搜索工具怎么办？

核对注册与启动时的 CODEX_HOME 是否一致，并检查 STEP_API_KEY。通过 codex mcp list 检查配置，重启交互会话后用 /mcp 检查连接状态。若在 codex exec 中使用，也需单独确认该运行方式实际加载并调用了工具。

工具接入

迁移

文本与推理

请求与上下文

Agent 与工具

文件与知识

视觉理解

语音

图像生成与编辑

开发工具

示例与 Cookbook

错误与排障

接入条件

接入说明

安装 Codex CLI

配置 Step Plan

确定配置目录

添加 Provider

设置 API Key

创建模型目录

创建 Step 专用配置

启动 Codex CLI

接入 StepSearch MCP

验证接入

验证对话

验证工具调用

常见问题

​接入条件

​接入说明

​安装 Codex CLI

​配置 Step Plan

​确定配置目录

​添加 Provider

​设置 API Key

​创建模型目录

​创建 Step 专用配置

​启动 Codex CLI

​接入 StepSearch MCP

​验证接入

​验证对话

​验证工具调用

​常见问题

接入条件

接入说明

安装 Codex CLI

配置 Step Plan

确定配置目录

添加 Provider

设置 API Key

创建模型目录

创建 Step 专用配置

启动 Codex CLI

接入 StepSearch MCP

验证接入

验证对话

验证工具调用

常见问题