Codex CLI

Codex CLI 支持通过用户级 config.toml 配置自定义模型供应商。HiLinkup 作为 OpenAI 兼容服务时，使用 https://api.hilinkup.com/v1 和 Responses 协议。

Codex 官方配置说明：~/.codex/config.toml 是用户级配置；--profile hilinkup 会加载 ~/.codex/config.toml，再叠加 ~/.codex/hilinkup.config.toml；Provider 相关配置应放在用户级配置或 profile 中，不应放在项目级 .codex/config.toml。

本页示例模型使用 HiLinkup 平台上的中国模型 aliyun/kimi-k3。实际代码模型请以 /v1/models 和控制台展示为准。

Codex 只使用 Responses

当前 Codex CLI 自定义供应商的 wire_api 只支持 responses，省略时默认值也为 responses。

不要配置 wire_api = "chat"。该值不是当前 Codex 支持的协议，也不能把只支持 Chat Completions 的模型直接用于 Codex。请先确认目标模型和 HiLinkup 渠道支持 POST /v1/responses。

先确认 API 可用

先在终端验证 API Key 和模型列表。

macOS / Linux
Windows PowerShell

export HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY"

curl https://api.hilinkup.com/v1/models \
  -H "Authorization: Bearer $HILINKUP_API_KEY"

$env:HILINKUP_API_KEY = "YOUR_HILINKUP_API_KEY"

curl.exe https://api.hilinkup.com/v1/models `
  -H "Authorization: Bearer $env:HILINKUP_API_KEY"

从返回的 data[].id 中选择模型。下面示例使用 aliyun/kimi-k3。

方法一：编辑用户级配置文件

这是推荐方式。配置保存后，以后直接运行 codex 即可。

macOS
Linux
Windows PowerShell

打开配置文件：

mkdir -p ~/.codex
nano ~/.codex/config.toml

粘贴以下内容：

model = "aliyun/kimi-k3"
model_provider = "hilinkup"

[model_providers.hilinkup]
name = "HiLinkup"
base_url = "https://api.hilinkup.com/v1"
env_key = "HILINKUP_API_KEY"
wire_api = "responses"
request_max_retries = 2
stream_max_retries = 5
stream_idle_timeout_ms = 300000

保存：按 Ctrl + O，回车，再按 Ctrl + X 退出。
保存 API Key：

nano ~/.zshrc

在文件末尾添加：

export HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY"

保存退出后执行：

source ~/.zshrc

打开配置文件：

mkdir -p ~/.codex
nano ~/.codex/config.toml

粘贴以下内容：

model = "aliyun/kimi-k3"
model_provider = "hilinkup"

[model_providers.hilinkup]
name = "HiLinkup"
base_url = "https://api.hilinkup.com/v1"
env_key = "HILINKUP_API_KEY"
wire_api = "responses"
request_max_retries = 2
stream_max_retries = 5
stream_idle_timeout_ms = 300000

保存：按 Ctrl + O，回车，再按 Ctrl + X 退出。
保存 API Key。bash 用户编辑：

nano ~/.bashrc

zsh 用户编辑：

nano ~/.zshrc

添加：

export HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY"

保存退出后执行对应命令：

source ~/.bashrc

或：

source ~/.zshrc

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"

打开配置文件：

notepad "$env:USERPROFILE\.codex\config.toml"

粘贴以下内容并保存：

model = "aliyun/kimi-k3"
model_provider = "hilinkup"

[model_providers.hilinkup]
name = "HiLinkup"
base_url = "https://api.hilinkup.com/v1"
env_key = "HILINKUP_API_KEY"
wire_api = "responses"
request_max_retries = 2
stream_max_retries = 5
stream_idle_timeout_ms = 300000

设置用户级环境变量：

[Environment]::SetEnvironmentVariable(
  "HILINKUP_API_KEY",
  "YOUR_HILINKUP_API_KEY",
  "User"
)

关闭并重新打开 PowerShell，或者在当前窗口临时设置：

$env:HILINKUP_API_KEY = "YOUR_HILINKUP_API_KEY"

方法二：创建独立 profile

如果你不想把默认 Codex 配置切到 HiLinkup，可以创建 hilinkup profile。运行时使用 codex --profile hilinkup。

macOS / Linux
Windows PowerShell

mkdir -p ~/.codex
nano ~/.codex/hilinkup.config.toml

粘贴：

model = "aliyun/kimi-k3"
model_provider = "hilinkup"

[model_providers.hilinkup]
name = "HiLinkup"
base_url = "https://api.hilinkup.com/v1"
env_key = "HILINKUP_API_KEY"
wire_api = "responses"

启动：

export HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY"
codex --profile hilinkup

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\hilinkup.config.toml"

粘贴：

model = "aliyun/kimi-k3"
model_provider = "hilinkup"

[model_providers.hilinkup]
name = "HiLinkup"
base_url = "https://api.hilinkup.com/v1"
env_key = "HILINKUP_API_KEY"
wire_api = "responses"

启动：

$env:HILINKUP_API_KEY = "YOUR_HILINKUP_API_KEY"
codex --profile hilinkup

方法三：临时命令行配置

适合首次验证，不改任何配置文件。

macOS / Linux
Windows PowerShell

HILINKUP_API_KEY="YOUR_HILINKUP_API_KEY" \
codex \
  -c model='"aliyun/kimi-k3"' \
  -c model_provider='"hilinkup"' \
  -c model_providers.hilinkup.name='"HiLinkup"' \
  -c model_providers.hilinkup.base_url='"https://api.hilinkup.com/v1"' \
  -c model_providers.hilinkup.env_key='"HILINKUP_API_KEY"' \
  -c model_providers.hilinkup.wire_api='"responses"'

$env:HILINKUP_API_KEY = "YOUR_HILINKUP_API_KEY"

codex `
  -c model='"aliyun/kimi-k3"' `
  -c model_provider='"hilinkup"' `
  -c model_providers.hilinkup.name='"HiLinkup"' `
  -c model_providers.hilinkup.base_url='"https://api.hilinkup.com/v1"' `
  -c model_providers.hilinkup.env_key='"HILINKUP_API_KEY"' `
  -c model_providers.hilinkup.wire_api='"responses"'

-c 的值按 TOML 解析，所以字符串值外面需要带引号。PowerShell 中换行符是反引号 `，不要替换成反斜杠。

验证

检查配置是否能解析

codex doctor

执行只读任务

codex exec --profile hilinkup "只读取当前目录，列出项目结构，不要修改文件。"

再测试完整 Agent 流程

在临时分支中让 Codex 修改一个小文件，并检查 diff。不要一开始就让它执行大范围重构。

常见问题

配置后仍然没有走 HiLinkup

检查 model_provider = "hilinkup" 是否设置在当前生效的配置层。使用 --profile hilinkup 时，文件名必须是 ~/.codex/hilinkup.config.toml，Windows 下对应 %USERPROFILE%\.codex\hilinkup.config.toml。

提示找不到 API Key

确认 env_key = "HILINKUP_API_KEY"，并且启动 Codex 的同一个 shell 中能读取该变量。macOS/Linux 执行 echo $HILINKUP_API_KEY；Windows PowerShell 执行 echo $env:HILINKUP_API_KEY。

Responses 路径不通

Codex 的自定义 provider 只使用 Responses。先用 Responses 页面里的 cURL 验证 https://api.hilinkup.com/v1/responses。如果模型只支持 Chat Completions，请更换为支持 Responses 的模型；不要把 wire_api 改成 "chat"。

不要把 provider 写到项目级 .codex/config.toml

Codex 官方文档说明项目级 .codex/config.toml 不能覆盖 model_provider 和 model_providers 等 Provider 鉴权相关配置。请把这些配置写到用户级 ~/.codex/config.toml 或 ~/.codex/hilinkup.config.toml。

不要覆盖内置 openai provider

不要写 [model_providers.openai]。openai 是保留 ID；自定义供应商请使用 hilinkup、hilinkup-prod 这类新 ID。

接入总览

开发工具

聊天客户端

应用框架

Codex 只使用 Responses

先确认 API 可用

方法一：编辑用户级配置文件

方法二：创建独立 profile

方法三：临时命令行配置

验证

常见问题

​Codex 只使用 Responses

​先确认 API 可用

​方法一：编辑用户级配置文件

​方法二：创建独立 profile

​方法三：临时命令行配置

​验证

​常见问题

Codex 只使用 Responses

先确认 API 可用

方法一：编辑用户级配置文件

方法二：创建独立 profile

方法三：临时命令行配置

验证

常见问题