手把手教学在 Codex 中安装 Agent 工具包本教程介绍如何把远程 MCP 服务agent-toolkit接入 Codex使 Codex 可以调用 Agent 工具包提供的能力。本文以 Codex CLI 为例Codex 桌面版的配置逻辑基本一致。如果你的菜单或命令提示略有不同请以当前版本为准。接入信息项目内容客户端Codex CLI / Codex 桌面版配置文件~/.codex/config.tomlMCP 地址https://agent-toolkit.app.baizhi.cloud/mcp传输方式HTTP / Streamable HTTP鉴权方式Bearer Token 环境变量服务名称agent-toolkitMCP 地址必须以/mcp结尾。不要把教程中的占位密钥sk_******直接写入配置。1. 准备 API KeyAgent 工具包是远程 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-toolkitURLhttps://agent-toolkit.app.baizhi.cloud/mcpBearer token environment variableAGENT_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 或 LinuxexportAGENT_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 Bashcodex mcp listWindows PowerShellcodex mcp listWindows CMDcodex mcp list列表中应该能看到agent-toolkit。如果服务状态正常说明配置已经被 Codex 识别。4. 方式三手动编辑配置文件如果你更习惯直接修改配置也可以编辑 Codex 的配置文件~/.codex/config.tomlWindows 用户通常可以在资源管理器地址栏中打开%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 全程直飞GJ802113:00—16:30约 2,131 元GJ802217:30—23:05约 2,773 元约 4,904 元时间和价格平衡推荐优先比较C 低价去程 直飞返程MF8596、MF843约 1,395 元约 6 小时 50 分GJ8022约 2,773 元约 4,168 元去程较累适合预算优先D 最快直飞JD41908:35—11:45约 2,803 元JD42012: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 服务配置正确并重新启动会话不必重复安装。