> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

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

## 接入条件

* 已安装 Node.js、npm、`curl` 和 Python 3。以下终端命令适用于 Bash 或 zsh，Windows 用户可在 WSL 中执行。
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。
* 已在 [StepFun 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 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：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npm install -g @openai/codex@0.154.0
```

检查安装版本：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex --version
```

预期输出为 `codex-cli 0.154.0`。

## 配置 Step Plan

### 确定配置目录

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

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME"
export CODEX_HOME="$(cd "$CODEX_HOME" && pwd)"
```

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

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export CODEX_HOME="$HOME/.codex-step-plan"
mkdir -p "$CODEX_HOME"
```

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

### 添加 Provider

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

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[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 的终端中设置环境变量：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEP_API_KEY="YOUR_STEP_API_KEY"
```

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

```dotenv theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
STEP_API_KEY=YOUR_STEP_API_KEY
```

设置文件权限：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
chmod 600 "$CODEX_HOME/.env"
```

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

### 创建模型目录

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

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
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"
```

2. 确认文件非空：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
test -s "$CODEX_HOME/default.md" && wc -c "$CODEX_HOME/default.md"
```

3. 生成 `$CODEX_HOME/step-catalog.json`：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
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`。首次创建时可执行以下命令；文件已存在时，请合并配置，保留其他设置。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
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` 是绝对路径：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
cat "$CODEX_HOME/step.config.toml"
```

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

## 启动 Codex CLI

1. 确认所需文件存在：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
ls "$CODEX_HOME"/config.toml \
   "$CODEX_HOME"/step.config.toml \
   "$CODEX_HOME"/step-catalog.json
```

2. 在项目目录中启动：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex --profile step
```

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

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

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex resume --profile step YOUR_SESSION_ID
```

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

## 接入 StepSearch MCP

[StepSearch](/docs/zh/step-plan/integrations/search-mcp) 提供 `web_search` 和 `web_fetch`，用于联网搜索与网页内容获取。需要这些能力时，可通过 Step Plan 端点接入。

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

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex mcp add step-search \
  --url https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp \
  --bearer-token-env-var STEP_API_KEY
```

2. 检查注册结果：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex mcp list
```

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

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

## 验证接入

### 验证对话

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

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
codex exec --profile step --sandbox read-only "请只回复 OK。" < /dev/null
```

### 验证工具调用

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

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

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

## 常见问题

<AccordionGroup>
  <Accordion title="Q: 启动后要求登录 ChatGPT 怎么办？">
    核对 `CODEX_HOME`、`step.config.toml` 中的 `model_provider = "stepfun"`，以及启动命令是否包含 `--profile step`。确认用户级 `config.toml` 中存在对应 Provider，且 API Key 已通过环境变量或 `.env` 提供。使用独立配置目录时，在当前终端重新设置 `CODEX_HOME` 后启动。
  </Accordion>

  <Accordion title="Q: /model 中没有 Step 模型或出现 Model metadata not found 怎么办？">
    检查所选 profile 的 `model_catalog_json` 是否指向有效的绝对路径，以及目录中的模型 ID 是否正确。修改后重启 Codex；若仍显示旧列表，退出 Codex，移除当前 `CODEX_HOME` 下的 `models_cache.json` 后重试。
  </Accordion>

  <Accordion title="Q: 模型目录报 missing field 怎么办？">
    模型目录缺少当前 Codex 版本要求的字段。使用与目标版本匹配的结构重新生成 `step-catalog.json`，并确认 `default.md` 下载成功且非空。不要将其他版本的精简目录直接用于当前版本。
  </Accordion>

  <Accordion title="Q: 连接失败、持续重连或返回 401 怎么办？">
    查看完整错误信息，检查网络连接、API Key 状态与模型权限。`base_url` 使用 `https://api.stepfun.com/step_plan/v1`，`wire_api` 使用 `responses`；确认 `env_key` 与实际环境变量名称一致，且密钥属于所用端点对应的账号。
  </Accordion>

  <Accordion title="Q: codex exec 一直等待标准输入怎么办？">
    如果输出停留在 `Reading additional input from stdin...`，且无需通过标准输入提供内容，在命令末尾添加 `< /dev/null`。
  </Accordion>

  <Accordion title="Q: 回复为空或返回 incomplete 怎么办？">
    检查服务端返回状态、错误详情与 Token 用量。推理消耗和输出预算不足都可能影响正文生成；确认具体原因后，再使用目标客户端版本与服务端支持的参数调整。
  </Accordion>

  <Accordion title="Q: MCP 已注册，但会话中没有搜索工具怎么办？">
    核对注册与启动时的 `CODEX_HOME` 是否一致，并检查 `STEP_API_KEY`。通过 `codex mcp list` 检查配置，重启交互会话后用 `/mcp` 检查连接状态。若在 `codex exec` 中使用，也需单独确认该运行方式实际加载并调用了工具。
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.