# Codex (/docs/cookbook/coding-agents/codex)







把 Praxis 接入 Codex，在终端里用你的 Key 驱动 OpenAI 的编程智能体——改代码、跑命令、答问题。密钥只存环境变量，不落配置文件。

每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、配置与验证。

## 你将完成 [#你将完成]

* 在终端用 `codex` 命令调用 Praxis 的模型
* 完成标志：`codex exec "…"` 收到模型回复
* 预计耗时：**3–5 分钟**（不含 Node.js 安装）
* 支持协议：OpenAI Responses（Codex 原生协议）

## 前提 [#前提]

开始前逐项确认：

* **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，弹窗中**名称必填**，有效期默认 90 天（可改永久），点创建后弹窗会展示完整 Key 一次——立即复制保存；之后也随时可在 Key 列表行点复制图标（悬停行时出现）重新获取完整 Key。若弹窗长时间停在「创建中…」，刷新列表确认 Key 已生成即可，行内复制同样能拿到完整 Key。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。
* **Node.js 18 或更高**。终端运行 `node --version` 检查；没有就到 [nodejs.org](https://nodejs.org) 装 LTS 版。
* **安装 Codex CLI**：

  ```bash
  npm install -g @openai/codex
  ```

  期望：`codex --version` 输出 `codex-cli <版本号>`（本页以 0.162.1 为准）。

## 配置 [#配置]

**第 1 步：写配置文件**

创建 `~/.codex/config.toml`（Windows 为 `%USERPROFILE%\.codex\config.toml`）：

```toml
model = "deepseek-flash"
model_provider = "praxis"

[model_providers.praxis]
name = "Praxis"
base_url = "https://api.deepraxis.ai/openai/v1"
env_key = "PRAXIS_API_KEY"
wire_api = "responses"
```

三处说明：

* 密钥**不写进这个文件**——`env_key` 声明从环境变量 `PRAXIS_API_KEY` 读取，下一步设置。
* `wire_api` 必须是 `responses`：Codex 走的是 OpenAI Responses 协议，不是传统 chat completions。
* `model` 填目录内的模型 ID；`deepseek-flash` 是平台示例模型——便宜、快、中英文都好。

期望：文件保存后，下一次启动的 `codex` 命令即使用新配置（已开着的会话需退出重进）。

<img alt="终端里查看 ~/.codex/config.toml 的实际内容" src="__img0" />

**第 2 步：设置密钥环境变量**

macOS / Linux（WSL 同）：

```bash
export PRAXIS_API_KEY=sk-praxis-你的Key
```

想持久化就把这行加进 `~/.bashrc` 或 `~/.zshrc`。Windows PowerShell：`$env:PRAXIS_API_KEY="你的Key"`（或设置系统级环境变量后重开终端）。

期望：`echo $PRAXIS_API_KEY` 输出你的 Key（PowerShell 用 `echo $env:PRAXIS_API_KEY`）。

## 验证 [#验证]

进入一个代码项目目录（git 仓库），运行：

```bash
codex exec "用中文回复四个字：连接成功"
```

期望：回复正文包含 `连接成功`，末尾附 tokens used 统计——**收到回复即接入成功**。首次运行可能提示「Model metadata for deepseek-flash not found … Defaulting to fallback metadata」，这是自定义模型的正常回退提示，不影响使用。

<img alt="终端运行 codex exec 的真实输出" src="__img1" />

去掉 `exec` 直接运行 `codex`，进入交互式工作台（出现版本横幅与输入框即进入；本页不验证此项）。

也可以在命令行完成等价验证。先设置变量（不然照抄 curl 会得到 401）：

```bash
export PRAXIS_API_KEY=sk-praxis-你的Key
```

```bash
curl https://api.deepraxis.ai/openai/v1/responses \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-flash", "input": "你好", "max_output_tokens": 256}'
```

期望：HTTP 200 即接入成功。`output` 里 `type` 为 `text` 的块是回复文本——`deepseek-flash` 是推理模型，前面可能先带 `reasoning` 块，属正常。

> 上述命令为 macOS / Linux / WSL（bash）写法。Windows PowerShell 用户：上面的 `codex exec` 已成功即接入完成，可跳过；如需命令行验证，先 `$env:PRAXIS_API_KEY="你的Key"`，用 `curl.exe`（PowerShell 的 `curl` 是别名，语法不同），并把命令并成一行（去掉行尾 `\`）。

最后看一眼 [控制台 → 用量与费用](https://console.deepraxis.ai/usage)：刚才的调用已经记在账上——每一次调用都有账、可追溯。

## 常见问题 [#常见问题]

| 症状                                   | 原因                                           | 解法                                                      |
| ------------------------------------ | -------------------------------------------- | ------------------------------------------------------- |
| 提示 `Model metadata … not found`      | 自定义模型不在 Codex 内置元数据表里                        | 正常回退提示，直接用；不影响对话与工具调用                                   |
| 提示无效令牌 / 401                         | `PRAXIS_API_KEY` 未导出、复制不完整，或改完 shellrc 没重开终端 | `echo $PRAXIS_API_KEY` 检查；重新完整复制；重开终端让配置生效              |
| 报 `Not inside a trusted directory …` | 不在 git 仓库目录里运行                               | 进项目目录运行；或临时加 `--skip-git-repo-check`                    |
| 报 `unknown configuration field`      | Codex 版本较旧，不认识新配置键                           | `npm install -g @openai/codex` 升级后重试                    |
| 报模型不存在                               | 模型 ID 与目录不一致                                 | 到[控制台 → 模型](https://console.deepraxis.ai/models)复制确切 ID |

## 进阶 [#进阶]

* **查这段对话花了多少钱**：[控制台 → 用量与费用](https://console.deepraxis.ai/usage)，按次计费、无闲置费
* **换模型**：改 `config.toml` 的 `model`，或运行 `codex -m <模型ID>`。可选 `deepseek-flash`、`deepseek-v4-flash`。Codex 只能使用声明了 Responses 协议的模型；在[模型目录](https://console.deepraxis.ai/models)打开模型详情，确认支持协议包含 Responses 后再选择。
* **在项目里用**：`codex` 交互模式能读文件、改代码、执行命令，敏感动作会先征求你的确认

## 相关食谱 [#相关食谱]

* [Claude Code](/docs/cookbook/coding-agents/claude-code)（Anthropic 协议姊妹篇）· [Cline](/docs/cookbook/coding-agents/cline) · [OpenCode](/docs/cookbook/coding-agents/opencode)
* 偏好图形界面？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Chatbox](/docs/cookbook/chat-clients/chatbox)