使用 Codex 接入宝塔 MCP
将宝塔 MCP 接入 Codex 后，可以直接在 Codex 中查询服务器状态，并按需调用网站、数据库、安全等宝塔面板能力。
本文从获取 MCP 安装提示词开始介绍。尚未安装【宝塔 MCP 服务】或未完成端口、HTTPS 等准备工作的用户，请先参考宝塔 MCP 安装指引。
安装提示词可能包含 MCP 服务地址、Token 或其他授权信息。请仅将提示词发送给可信的 Codex 任务，不要粘贴到公开聊天、工单或代码仓库。文中的地址和执行结果仅为示例，请勿照抄。
开始前准备
开始配置前，请确认：
- 【宝塔 MCP 服务】已安装并处于“运行正常”状态
- 宝塔面板防火墙和云服务器安全组已放行 MCP 服务端口
- MCP 服务的 HTTPS 状态正常
- 已安装并登录 Codex 客户端
1. 获取 MCP 安装提示词
- 登录宝塔面板，进入【软件商店】
- 打开【宝塔 MCP 服务】的设置页面
- 进入【接入与体验】
- 点击【配置 IP 白名单】，添加 Codex 当前使用的公网出口 IP
- 复制页面生成的 MCP 安装提示词
Codex 的公网出口 IP 可能会随网络环境变化。如果后续出现 403 ip denied，请根据IP 白名单错误中的方法重新配置。
2. 将安装提示词发送给 Codex
在 Codex 中新建任务，将刚才复制的安装提示词完整粘贴到输入框并发送。Codex 会读取提示词中的安装文档，并按照文档完成 MCP 和相关 Skills 配置。
部分环境中，Codex 可能需要通过终端下载安装文档，并请求执行授权。授权前请核对下载地址、目标文件和命令内容；确认与当前宝塔 MCP 配置一致后，再允许执行。
如果 Codex 无法读取安装文档，应先检查下载地址和网络连通性。不要关闭 HTTPS 证书校验，也不要为了绕过错误执行来源不明的命令。
3. 处理 IP 白名单错误
出现 403 ip denied
如果配置过程中出现以下错误，表示宝塔 MCP 服务拒绝了当前来源 IP：
MCP request failed with HTTP 403: {"status": false, "msg": "ip denied"}
此时按以下步骤处理：
- 返回【宝塔 MCP 服务】的【接入与体验】页面
- 点击【配置 IP 白名单】
- 将 Codex 当前使用的公网出口 IP 加入白名单
- 保存配置后，回到 Codex 并发送“已放通，请重新验证”
不要将白名单长期设置为允许任意来源。完成测试后，应只保留实际使用的可信 IP。
4. 确认配置完成
Codex 重新验证后，应返回类似结果：
- MCP
initialize成功 tools/list成功，且未出现401或403- Bearer Token 认证通过
- Codex 已识别宝塔 MCP 和相关 Skills
截图中的工具和 Skills 数量仅为当次环境的结果，实际数量以当前宝塔 MCP 版本为准。
为确保新配置生效，建议重启 Codex 客户端，然后新建一个任务。也可以在 Codex 中输入 /mcp，确认宝塔 MCP 服务已连接。
Codex 默认将 MCP 配置保存在
~/.codex/config.toml。配置采用 Streamable HTTP 和 Bearer Token 认证；请勿公开配置中的 Token。更多配置说明可参考 OpenAI 官方 MCP 文档。
5. 执行首次只读验证
在新任务中发送一条只读指令，例如：
查看服务器当前状态，只读取 CPU、内存、磁盘、系统负载和服务运行情况，不要修改任何配置。
如果 Codex 能返回服务器资源和服务状态，说明宝塔 MCP 已成功接入。
首次验证通过后，再根据实际需要逐步尝试其他操作。涉及删除文件、修改防火墙、重启服务等高风险操作时，应仔细核对 Codex 的操作计划并保留人工确认。
常见问题
Codex 无法下载或读取安装文档
确认安装提示词中的下载地址完整且未过期，并检查 Codex 所在网络能否访问宝塔面板。如果 Codex 请求改用终端下载，请先核对域名或 IP、端口和目标文件，再决定是否授权。
配置成功后看不到宝塔 MCP 工具
重启 Codex 客户端并新建任务，然后输入 /mcp 检查连接状态。当前任务如果早于 MCP 配置创建，可能不会加载新增工具。
授权信息可能已经泄露
立即在【宝塔 MCP 服务】中重新生成授权信息，并删除聊天记录、日志或仓库中暴露的旧 Token。重新复制安装提示词，在 Codex 中更新配置后再次验证。