---
title: "使用 Codex 接入宝塔 MCP"
description: "介绍如何将宝塔 MCP 安装提示词交给 Codex，完成自动配置、IP 白名单排查、连接验证和首次只读调用。"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.bt.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Codex 接入宝塔 MCP

将宝塔 MCP 接入 Codex 后，可以直接在 Codex 中查询服务器状态，并按需调用网站、数据库、安全等宝塔面板能力。

本文从**获取 MCP 安装提示词**开始介绍。尚未安装【宝塔 MCP 服务】或未完成端口、HTTPS 等准备工作的用户，请先参考[宝塔 MCP 安装指引](/ai-ops/mcp/installation)。

:::warning 安全提示
安装提示词可能包含 MCP 服务地址、Token 或其他授权信息。请仅将提示词发送给可信的 Codex 任务，不要粘贴到公开聊天、工单或代码仓库。文中的地址和执行结果仅为示例，请勿照抄。
:::

## 开始前准备

开始配置前，请确认：

- 【宝塔 MCP 服务】已安装并处于“运行正常”状态
- 宝塔面板防火墙和云服务器安全组已放行 MCP 服务端口
- MCP 服务的 HTTPS 状态正常
- 已安装并登录 Codex 客户端

## 1. 获取 MCP 安装提示词

1. 登录宝塔面板，进入【软件商店】
2. 打开【宝塔 MCP 服务】的设置页面
3. 进入【接入与体验】
4. 点击【配置 IP 白名单】，添加 Codex 当前使用的公网出口 IP
5. 复制页面生成的 MCP 安装提示词

![在宝塔 MCP 服务中复制安装提示词](/img/ai-ops/agent/codex-mcp/copy-install-prompt.png)

:::tip
Codex 的公网出口 IP 可能会随网络环境变化。如果后续出现 `403 ip denied`，请根据[IP 白名单错误](#出现-403-ip-denied)中的方法重新配置。
:::

## 2. 将安装提示词发送给 Codex

在 Codex 中新建任务，将刚才复制的安装提示词完整粘贴到输入框并发送。Codex 会读取提示词中的安装文档，并按照文档完成 MCP 和相关 Skills 配置。

![将 MCP 安装提示词发送给 Codex](/img/ai-ops/agent/codex-mcp/run-install-prompt.png)

部分环境中，Codex 可能需要通过终端下载安装文档，并请求执行授权。授权前请核对下载地址、目标文件和命令内容；确认与当前宝塔 MCP 配置一致后，再允许执行。

![核对操作后授权 Codex 下载安装文档](/img/ai-ops/agent/codex-mcp/authorize-download.png)

:::warning
如果 Codex 无法读取安装文档，应先检查下载地址和网络连通性。不要关闭 HTTPS 证书校验，也不要为了绕过错误执行来源不明的命令。
:::

## 3. 处理 IP 白名单错误

### 出现 `403 ip denied`

如果配置过程中出现以下错误，表示宝塔 MCP 服务拒绝了当前来源 IP：

```text
MCP request failed with HTTP 403: {"status": false, "msg": "ip denied"}
```

此时按以下步骤处理：

1. 返回【宝塔 MCP 服务】的【接入与体验】页面
2. 点击【配置 IP 白名单】
3. 将 Codex 当前使用的公网出口 IP 加入白名单
4. 保存配置后，回到 Codex 并发送“已放通，请重新验证”

![Codex 提示 MCP 服务返回 403 ip denied](/img/ai-ops/agent/codex-mcp/ip-denied.png)

不要将白名单长期设置为允许任意来源。完成测试后，应只保留实际使用的可信 IP。

## 4. 确认配置完成

Codex 重新验证后，应返回类似结果：

- MCP `initialize` 成功
- `tools/list` 成功，且未出现 `401` 或 `403`
- Bearer Token 认证通过
- Codex 已识别宝塔 MCP 和相关 Skills

![Codex 完成宝塔 MCP 配置与连通性验证](/img/ai-ops/agent/codex-mcp/connection-verified.png)

截图中的工具和 Skills 数量仅为当次环境的结果，实际数量以当前宝塔 MCP 版本为准。

为确保新配置生效，建议重启 Codex 客户端，然后新建一个任务。也可以在 Codex 中输入 `/mcp`，确认宝塔 MCP 服务已连接。

> Codex 默认将 MCP 配置保存在 `~/.codex/config.toml`。配置采用 Streamable HTTP 和 Bearer Token 认证；请勿公开配置中的 Token。更多配置说明可参考 [OpenAI 官方 MCP 文档](https://developers.openai.com/codex/mcp)。

## 5. 执行首次只读验证

在新任务中发送一条只读指令，例如：

```text
查看服务器当前状态，只读取 CPU、内存、磁盘、系统负载和服务运行情况，不要修改任何配置。
```

如果 Codex 能返回服务器资源和服务状态，说明宝塔 MCP 已成功接入。

![通过 Codex 查询宝塔服务器状态](/img/ai-ops/agent/codex-mcp/server-status.png)

首次验证通过后，再根据实际需要逐步尝试其他操作。涉及删除文件、修改防火墙、重启服务等高风险操作时，应仔细核对 Codex 的操作计划并保留人工确认。

## 常见问题

### Codex 无法下载或读取安装文档

确认安装提示词中的下载地址完整且未过期，并检查 Codex 所在网络能否访问宝塔面板。如果 Codex 请求改用终端下载，请先核对域名或 IP、端口和目标文件，再决定是否授权。

### 配置成功后看不到宝塔 MCP 工具

重启 Codex 客户端并新建任务，然后输入 `/mcp` 检查连接状态。当前任务如果早于 MCP 配置创建，可能不会加载新增工具。

### 授权信息可能已经泄露

立即在【宝塔 MCP 服务】中重新生成授权信息，并删除聊天记录、日志或仓库中暴露的旧 Token。重新复制安装提示词，在 Codex 中更新配置后再次验证。

## 相关文档

- [宝塔 MCP 安装指引](/ai-ops/mcp/installation)
- [宝塔 MCP 介绍](/ai-ops/mcp)
- [使用 WorkBuddy 接入宝塔 MCP](/ai-ops/agent/panel-integration/workbuddy-mcp)
- [使用 Claude Code 接入宝塔 MCP](/ai-ops/agent/panel-integration/claude-code-mcp)
- [使用 TRAE 接入宝塔 MCP](/ai-ops/agent/panel-integration/trae-mcp)
- [使用 DeepSeek Harness 接入宝塔 MCP](/ai-ops/agent/panel-integration/deepseek-harness-mcp)
- [通过 Hermes 与 OpenClaw 消息通道接入宝塔 MCP](/ai-ops/agent/panel-integration/hermes-openclaw-mcp)
- [宝塔面板 Skill 安装与使用指引](/ai-ops/agent/panel-integration/skill-installation)
- [Agent 接入宝塔 MCP 与使用 Skills](/ai-ops/agent/panel-integration)

Source: https://docs.bt.cn/ai-ops/agent/panel-integration/codex-mcp/index.mdx