手把手教学：在 Codex 中安装 Agent 工具包-酒店常州论坛

手把手教学：在 Codex 中安装 Agent 工具包

本教程介绍如何把远程 MCP 服务agent-toolkit接入 Codex，使 Codex 可以调用 Agent 工具包提供的能力。

本文以 Codex CLI 为例，Codex 桌面版的配置逻辑基本一致。如果你的菜单或命令提示略有不同，请以当前版本为准。

接入信息

项目	内容
客户端	Codex CLI / Codex 桌面版
配置文件	`~/.codex/config.toml`
MCP 地址	`https://agent-toolkit.app.baizhi.cloud/mcp`
传输方式	HTTP / Streamable HTTP
鉴权方式	Bearer Token 环境变量
服务名称	`agent-toolkit`

MCP 地址必须以/mcp结尾。不要把教程中的占位密钥sk_******直接写入配置。

1. 准备 API Key

Agent 工具包是远程 MCP 服务，需要使用真实 API Key 才能连接并调用工具。

打开 Agent 工具包控制台的 API Key 页面。
创建一把新的 API Key。
根据使用场景选择合适的工具分组，例如航班查询、机场天气或其他旅行工具。
创建后立即复制密钥，并妥善保存。

后续配置时，把<你的 API Key>整段替换为真实密钥，不要保留尖括号。

2. 方式一：在 Codex Desktop 中配置 MCP

如果你使用的是 Codex Desktop，推荐直接在设置页面添加 MCP 服务，不需要手动编辑配置文件。

第 1 步：打开 Codex 设置

打开 Codex Desktop，点击右上角的设置按钮，进入 Codex 设置。在设置页面中找到MCP Servers或MCP 服务配置区域。

第 2 步：新增 MCP 服务

点击Add MCP Server、添加 MCP 服务或类似按钮，填写以下信息：

字段	填写内容
Name / 名称	`agent-toolkit`
URL	`https://agent-toolkit.app.baizhi.cloud/mcp`
Bearer token environment variable	`AGENT_TOOLKIT_API_KEY`

如果界面把认证方式单独列出，请选择Bearer Token，并填写环境变量名称AGENT_TOOLKIT_API_KEY，不要直接填写真实 API Key。

第 3 步：保存并启用

点击Save、保存或Enable。返回 MCP 服务列表后，确认agent-toolkit已出现并处于启用状态。

如果 Codex Desktop 提示需要重启或重新加载 MCP 服务，请按提示操作。

如果当前版本的 Codex Desktop 没有图形化的 MCP 配置入口，请使用下面的命令行方式或手动编辑config.toml。

3. 方式二：使用命令行添加 MCP

这是最简单、也更安全的配置方式。Codex 当前不支持在mcp add命令中使用--header，需要通过环境变量提供 Bearer Token。

第 1 步：设置 API Key 环境变量

Windows PowerShell 当前终端临时设置：

$env:AGENT_TOOLKIT_API_KEY ="<你的 API Key>"

如果希望以后打开的新终端也能使用，可以写入当前用户的环境变量：

[Environment]::SetEnvironmentVariable("AGENT_TOOLKIT_API_KEY","<你的 API Key>","User")

写入后请重新打开 Codex 或终端。不要在公开截图中显示真实密钥。

macOS 或 Linux：

exportAGENT_TOOLKIT_API_KEY="<你的 API Key>"

如需长期生效，可将这行命令加入 Shell 配置文件，例如~/.zshrc或~/.bashrc。

第 2 步：添加 MCP 服务

codex mcpaddagent-toolkit--urlhttps://agent-toolkit.app.baizhi.cloud/mcp --bearer-token-env-var AGENT_TOOLKIT_API_KEY

--bearer-token-env-var后面填写的是环境变量名称，不是 API Key 本身。Codex 调用服务时会读取该环境变量，并自动发送 Bearer Token。

查看已配置的 MCP 服务

macOS、Linux 或 Git Bash：

codex mcp list

Windows PowerShell：

codex mcp list

Windows CMD：

codex mcp list

列表中应该能看到agent-toolkit。如果服务状态正常，说明配置已经被 Codex 识别。

4. 方式三：手动编辑配置文件

如果你更习惯直接修改配置，也可以编辑 Codex 的配置文件：

~/.codex/config.toml

Windows 用户通常可以在资源管理器地址栏中打开：

%USERPROFILE%\.codex\config.toml

在文件中加入下面的配置：

[mcp_servers.agent-toolkit] url = "https://agent-toolkit.app.baizhi.cloud/mcp" bearer_token_env_var = "AGENT_TOOLKIT_API_KEY"

这里保存的是环境变量名称，不是 API Key。请先按照上一节设置AGENT_TOOLKIT_API_KEY。

如果配置文件中已经有其他 MCP 服务，只新增agent-toolkit相关段落，不要覆盖原有配置。

5. 在 Codex 中确认工具可用

完成配置后：

重启当前 Codex 会话；如果使用桌面版，重新打开一个任务或会话。
执行codex mcp list，确认列表中存在agent-toolkit。
在对话中直接描述旅行需求，观察 Codex 是否自动调用航班、机场和天气等工具。

旅行规划助手案例

下面这段提示词可以直接复制到 Codex 中测试：

我计划一个人从杭州去曼谷旅游。出发日期是 2026 年 10 月 1 日，返程日期是 2026 年 10 月 7 日，住宿优先考虑 Asok 附近。
请先联网查询杭州往返曼谷的航班，给我推荐 3 组方案：价格最低的可行方案、全程直飞方案、价格和时间比较平衡的方案。每组说明航班号、起飞和到达时间、飞行时间、是否中转以及参考价格，然后选出一组最适合的方案。
接着帮我整理一份简洁的曼谷旅行路线，只需要包含：出发前准备清单、去程和返程时间线、机场到酒店的交通方式和耗时、主要景点之间的交通方式和耗时，以及一张简洁的旅游路线图。景点可以包含大皇宫、卧佛寺、郑王庙、唐人街、Chatuchak 周末市场、Siam 商圈、美功铁路市场、丹嫩沙多水上市场、Talad Noi 和 ICONSIAM。
不需要每天详细的流水账，也不要写长篇旅游分析。请使用 Markdown 输出，航班和价格标注查询日期。选定一组航班后，全文统一使用这一组信息，不要混用其他航班。未来航班没有实际到达时间时，只写计划到达时间，不要编造实际数据。

结果

价格为 2026 年 9 月 29 日查询到的经济舱单程参考价，往返价格为去程和返程相加估算。国庆期间价格变化较快，最终以出票页面为准。

方案	去程	返程	预计往返	特点
A 低价实用	MF8596、MF843；约 1,395 元；约 6 小时 50 分	GJ8022；约 2,773 元；直飞	约 4,168 元	价格较低，但去程中转、凌晨抵达
B 全程直飞	GJ8021；13:00—16:30；约 2,131 元	GJ8022；17:30—23:05；约 2,773 元	约 4,904 元	时间和价格平衡，推荐优先比较
C 低价去程 + 直飞返程	MF8596、MF843；约 1,395 元；约 6 小时 50 分	GJ8022；约 2,773 元	约 4,168 元	去程较累，适合预算优先
D 最快直飞	JD419；08:35—11:45；约 2,803 元	JD420；12:50—17:50；约 4,533 元	约 7,336 元	全程直飞、时间最好，但最贵
E 极限低价	3U6934、3U3937；约 1,311 元；约 29 小时	3U3772、3U3178；约 2,372 元；约 28 小时	约 3,683 元	返程到 10 月 9 日，不适合 7 天计划

这个案例可能调用的工具

查询内容	可能调用的工具
确认城市或机场代码	`city_search`、`airport_search`
查询往返航班和价格	`flight_prices`
查询中转路线	`flight_transfers`
查询机场天气	`airport_weather`
搜索网页和补充旅行信息	`websearch_aisearch`、`web_extract`
生成路线图或配图	`image_generate_text_to_image`、`websearch_image_search_by_text`

执行时重点观察：

Codex 是否明确调用了agent-toolkitMCP 服务；
是否根据查询结果整理出完整方案，而不是只返回一个工具的原始数据；
是否能在航班、交通和路线图之间保持信息一致。

如果只想快速验证航班工具，也可以直接输入：“请查询 2026 年 10 月 1 日杭州到曼谷、10 月 7 日曼谷回杭州的航班和价格。”

6. 常见问题

现象	处理方式
`codex mcp add`找不到命令	确认 Codex CLI 已安装，并执行`codex --version`检查命令是否可用。
`codex mcp list`中没有服务	检查服务名是否为`agent-toolkit`，并确认命令执行没有报错。
服务显示失败或无法调用	检查`AGENT_TOOLKIT_API_KEY`是否已设置，并在同一终端执行`$env:AGENT_TOOLKIT_API_KEY`确认当前进程可读取；同时确认 URL 以`/mcp`结尾。
手动配置后无法读取	检查 TOML 段落名称和引号，并确认使用`bearer_token_env_var`，不要把 JSON 或`Authorization`请求头片段直接粘贴到`config.toml`。
已连接但看不到工具	重启 Codex 会话，再次运行`codex mcp list`，并在提示词中明确指定使用`agent-toolkit`。
覆盖了其他 MCP 服务	恢复`config.toml`，然后只补回`[mcp_servers.agent-toolkit]`相关配置。
API Key 泄露	立即在 Agent 工具包控制台作废旧密钥并重新生成，不要把密钥发到聊天、截图或公开仓库。

7. 安全建议

不要把 API Key 写进项目代码、提交到 Git 或发布到公开截图中。
不要把config.toml上传到公开仓库，其中可能包含可直接调用服务的密钥。
只为当前用途选择必要的工具权限，避免给不需要的工具开放额度。

完成以上步骤后，Codex 就可以通过远程 MCP 使用 Agent 工具包。以后如果工具清单发生变化，通常只需要保持 MCP 服务配置正确并重新启动会话，不必重复安装。

企业官网建设流程全解析