一、安装 Codex
请根据实际环境类型安装 Codex，详情请参见 Codex 安装。如果已安装 Codex，可跳过此步骤。
二、获取 API Key
1. 进入 API Key 管理 页面，单击创建 API Key。操作详情请参见 创建 API Key。
注意：在设置可访问范围时，如果选择“限定范围”，则需要确保勾选 Hy3。
2. 创建完成后，请你务必复制并妥善保管 API Key，在后续配置到工具的流程中将会使用该信息。
三、配置模型设置
1. 打开 Codex，单击左下角设置，进入配置页面后单击右侧打开 config.toml，以系统默认编辑器打开配置文件。
2. 在打开的 config.toml 顶部写入以下内容（若已有其他内容，将以下配置段添加至文件开头即可）。
model_provider = "hy3-tokenhub"model = "hy3"disable_response_storage = true# Hy3 不兼容 Responses API 的 web_search 工具，需禁用；换用支持联网搜索的模型（如 deepseek-v4-pro）时删除本行web_search = "disabled"[model_providers.hy3-tokenhub]name = "Hy3 via tokenhub"base_url = "https://tokenhub.tencentmaas.com/v1"env_key = "HY3_API_KEY"wire_api = "responses"
3. 打开终端，运行以下命令注入 API Key。
# macOS系统launchctl setenv HY3_API_KEY "你的 API Key"# Windows系统setx HY3_API_KEY "你的 API Key"
四、确认模型是否生效
完全退出 Codex（仅关闭窗口无效），再重新启动。启动后将自动读取刚才注入的 Key 及 config.toml 配置。
在主界面输入框输入测试消息，若模型正常返回响应（如 Hello! How can I help you today?），则表示接入成功。
五、Codex 提示 “Model metadata for hy3 not found. Defaulting to fallback metadata”，是否说明 Hy3 模型在 Codex 中不被支持或能力受限？
不是。Hy3 通过 Codex 开放的自定义模型 Provider（custom model provider）机制接入，这是 Codex 提供的标准接入能力，按文档配置即可使用。
·该提示来源于 Codex 的模型元数据机制：Codex 内置模型目录仅包含其自有模型，通过自定义 Provider 接入的模型不在该目录内，Codex 会采用默认的上下文窗口估算值并输出此提示。这不影响 Hy3 在 Codex 中的正常对话与工具调用，模型能力完整可用。
·如需使用更精确的上下文窗口，可通过 Codex 提供的配置项自主指定：在 config.toml 中增加一行设置 model_context_window = 实际上下文窗口值，即可调整窗口估算；如需完整指定模型元数据，可使用 model_catalog_json 指向本地模型目录文件，具体配置方式请参见 Codex 示例配置。