codex配置mcp并阅读/编辑wiki

郑..方..醒

859人浏览 · 2026-05-14 10:18:25

郑..方..醒 · 2026-05-14 10:18:25 发布

Codex 从 0 到 1 配置 Wiki MCP：以 Confluence 为例

本文面向第一次接触 Codex、MCP、Docker 的同学，目标是手把手完成一个 Wiki MCP 配置，让 Codex 可以查询 Confluence Wiki 文档。

示例环境：Windows + PowerShell + Docker Desktop。

如果你使用 macOS 或 Linux，大部分步骤一样，只需要把命令里的 codex.cmd 换成 codex。

安全提醒：API Token、Personal Access Token 都是密码级别的敏感信息。不要把真实 Token 发到博客、截图、Git 仓库、群聊里。本文里的 your_api_token、your.email@company.com 都是占位符。

一、MCP是什么
二、准备 Docker
三、拉取 Wiki MCP 镜像
四、准备 Confluence 账号和 Token
五、确认 Codex CLI 可用
六、添加 Wiki MCP 配置
七、检查配置是否成功
八、重启 Codex 并测试
九、自建 Confluence 的配置写法
十、限制可查询的 Wiki 空间
十一、后续开放写 Wiki 的方式
十二、常见问题
十三、完整命令模板

一、先理解要配置什么

MCP 可以理解成 Codex 连接外部系统的工具协议。配置好 Wiki MCP 以后，Codex 就可以通过工具去查询 Confluence 页面，而不是只依赖你手动复制粘贴文档内容。

本文使用的 MCP 服务是 mcp-atlassian，它支持连接 Atlassian Confluence 和 Jira。这里重点演示 Confluence Wiki 查询。

新人建议先配置只读模式：

READ_ONLY_MODE=true

这样 Codex 只能查文档，不能创建、更新、删除页面，风险更低。

二、准备 Docker

MCP 服务可以通过 npm、uvx、Docker 等方式启动。新人建议用 Docker，因为不用手动安装 Python 依赖，也不用处理虚拟环境。

1. 打开 Docker Desktop

先启动 Docker Desktop，等它显示 Docker Engine 已经运行。

2. 检查 Docker 命令

打开 PowerShell，执行：

docker --version

如果能看到类似输出，说明 Docker 命令可用：

Docker version 26.x.x, build xxxxxxx

继续执行：

docker ps

如果没有报错，说明 Docker Engine 正在运行。

如果提示 Docker 没启动，先打开 Docker Desktop，等待运行完成后再执行 docker ps。

三、拉取 Wiki MCP 镜像

执行下面的命令拉取镜像：

docker pull ghcr.io/sooperset/mcp-atlassian:latest

拉取完成后检查镜像：

docker images ghcr.io/sooperset/mcp-atlassian

能看到 ghcr.io/sooperset/mcp-atlassian 和 latest，说明镜像已经准备好。

说明：

docker pull 通常只需要执行一次。
后面 Codex 使用 Wiki MCP 时，会通过 Docker 临时启动这个镜像。
配置里会使用 --rm，表示容器退出后自动删除，避免留下很多临时容器。

四、准备 Confluence 账号和 Token

先判断你的 Confluence 是 Atlassian Cloud，还是公司自建 Confluence。

情况 A：Atlassian Cloud

Cloud 版地址通常长这样：

https://your-company.atlassian.net/wiki

需要准备 3 个值：

CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=你的 Atlassian 登录邮箱
CONFLUENCE_API_TOKEN=你的 Atlassian API Token

生成 API Token 的步骤：

打开 Atlassian Token 页面：https://id.atlassian.com/manage-profile/security/api-tokens
登录你的 Atlassian 账号。
点击 Create API token。
Label 填一个容易识别的名字，例如 codex-wiki-mcp。
点击创建。
复制生成出来的 Token，保存到自己的密码管理器或安全笔记里。

注意：Token 页面通常只显示一次。关闭后看不到明文，只能重新生成。

情况 B：公司自建 Confluence

自建版地址通常长这样：

https://confluence.your-company.com

自建版通常使用 Personal Access Token，简称 PAT。需要准备：

CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_PERSONAL_TOKEN=你的 Personal Access Token

PAT 一般在 Confluence 右上角头像 -> Profile / Personal settings -> Personal Access Tokens 里创建。不同公司版本页面名字可能略有差异，如果找不到，可以问管理员：“Confluence 的 Personal Access Token 在哪里生成？”

后面的主流程先按 Atlassian Cloud 写。自建版配置见第九节。

五、确认 Codex CLI 可用

在 PowerShell 执行：

codex.cmd --help

能看到 Codex CLI 帮助信息，说明 Codex CLI 可用。

Windows 上为什么建议用 `codex.cmd`

在 Windows PowerShell 里，如果直接执行 codex，有时会看到：

codex.ps1 cannot be loaded because running scripts is disabled on this system

这是 PowerShell 执行策略拦截了 codex.ps1。最简单的处理方式是使用：

codex.cmd

继续确认 MCP 子命令：

codex.cmd mcp --help

你应该能看到这些命令：

list
get
add
remove
login
logout

常用命令说明：

命令	作用
`codex.cmd mcp list`	查看已经配置的 MCP
`codex.cmd mcp get wiki`	查看某个 MCP 的详细配置
`codex.cmd mcp add wiki ...`	新增一个 MCP
`codex.cmd mcp remove wiki`	删除一个 MCP 配置

六、添加 Wiki MCP 配置

先把下面 3 个占位符替换成你自己的真实值：

https://your-company.atlassian.net/wiki
your.email@company.com
your_api_token

然后在 PowerShell 执行下面的命令。

注意：这是一条命令。为了方便阅读，这里拆成多行。PowerShell 里的换行符是反引号，也就是每行末尾的 `。

codex.cmd mcp add wiki `
  --env "CONFLUENCE_URL=https://your-company.atlassian.net/wiki" `
  --env "CONFLUENCE_USERNAME=your.email@company.com" `
  --env "CONFLUENCE_API_TOKEN=your_api_token" `
  --env "READ_ONLY_MODE=true" `
  --env "ENABLED_TOOLS=confluence_search,confluence_get_page,confluence_get_comments" `
  -- docker run -i --rm `
    -e CONFLUENCE_URL `
    -e CONFLUENCE_USERNAME `
    -e CONFLUENCE_API_TOKEN `
    -e READ_ONLY_MODE `
    -e ENABLED_TOOLS `
    ghcr.io/sooperset/mcp-atlassian:latest

这条命令的含义：

配置	说明
`codex.cmd mcp add wiki`	在 Codex 里新增一个名为 `wiki` 的 MCP
`--env "CONFLUENCE_URL=..."`	保存 Confluence 地址
`--env "CONFLUENCE_USERNAME=..."`	保存 Atlassian 登录邮箱
`--env "CONFLUENCE_API_TOKEN=..."`	保存 Atlassian API Token
`READ_ONLY_MODE=true`	只读模式，避免误改 Wiki
`ENABLED_TOOLS=...`	只开放搜索、读取页面、读取评论等工具
`-- docker run ...`	告诉 Codex 通过 Docker 启动 MCP 服务
`-e CONFLUENCE_URL`	把 Codex 配置中的环境变量传入 Docker 容器

如果你之前已经添加过一个错误的 wiki 配置，可以先删除：

codex.cmd mcp remove wiki

然后重新执行上面的 codex.cmd mcp add wiki ...。

七、检查配置是否成功

执行：

codex.cmd mcp list

正常情况下，你能看到一行名字叫 wiki 的记录，状态是 enabled。

继续执行：

codex.cmd mcp get wiki

重点检查这些信息：

Name: wiki
Command: docker
Args: run -i --rm ... ghcr.io/sooperset/mcp-atlassian:latest
Status: enabled

如果 Command 是空的，说明配置没有真正写好，建议删除后重建：

codex.cmd mcp remove wiki

八、重启 Codex 并测试

如果你正在一个 Codex 会话里，建议退出当前会话，再重新进入。

常见做法：

cd D:\your-project
codex.cmd

进入 Codex 后，可以这样测试：

请用 wiki MCP 搜索 Confluence 中和“发布流程”相关的页面，返回前 5 条的标题、空间和链接，不要修改任何页面。

也可以测试读取具体页面：

请用 wiki MCP 查找标题为“研发环境搭建”的 Confluence 页面，并总结主要步骤，不要修改页面。

如果公司 Wiki 空间很多，建议指定空间关键字：

请用 wiki MCP 在 DEV 空间里搜索“部署流程”，返回最相关的 5 篇文档。

九、自建 Confluence 的配置写法

如果你用的是公司自建 Confluence Server / Data Center，通常使用 CONFLUENCE_PERSONAL_TOKEN。

示例命令：

codex.cmd mcp add wiki `
  --env "CONFLUENCE_URL=https://confluence.your-company.com" `
  --env "CONFLUENCE_PERSONAL_TOKEN=your_personal_access_token" `
  --env "READ_ONLY_MODE=true" `
  --env "ENABLED_TOOLS=confluence_search,confluence_get_page,confluence_get_comments" `
  -- docker run -i --rm `
    -e CONFLUENCE_URL `
    -e CONFLUENCE_PERSONAL_TOKEN `
    -e READ_ONLY_MODE `
    -e ENABLED_TOOLS `
    ghcr.io/sooperset/mcp-atlassian:latest

如果公司 Confluence 使用内网自签证书，可能还需要关闭证书校验：

CONFLUENCE_SSL_VERIFY=false

对应命令里增加：

--env "CONFLUENCE_SSL_VERIFY=false"

Docker 参数里也增加：

-e CONFLUENCE_SSL_VERIFY

CONFLUENCE_SSL_VERIFY=false 会降低证书校验安全性，只有公司内网自签证书确实导致访问失败时再使用。

十、限制可查询的 Wiki 空间

如果公司 Wiki 很大，不限制空间会查出很多无关内容。可以通过 CONFLUENCE_SPACES_FILTER 限制空间。

例如只允许查 DEV 和 OPS 两个空间：

codex.cmd mcp add wiki `
  --env "CONFLUENCE_URL=https://your-company.atlassian.net/wiki" `
  --env "CONFLUENCE_USERNAME=your.email@company.com" `
  --env "CONFLUENCE_API_TOKEN=your_api_token" `
  --env "READ_ONLY_MODE=true" `
  --env "CONFLUENCE_SPACES_FILTER=DEV,OPS" `
  --env "ENABLED_TOOLS=confluence_search,confluence_get_page,confluence_get_comments" `
  -- docker run -i --rm `
    -e CONFLUENCE_URL `
    -e CONFLUENCE_USERNAME `
    -e CONFLUENCE_API_TOKEN `
    -e READ_ONLY_MODE `
    -e CONFLUENCE_SPACES_FILTER `
    -e ENABLED_TOOLS `
    ghcr.io/sooperset/mcp-atlassian:latest

空间 Key 不是空间中文名。Confluence 空间 URL 里通常能看到空间 Key，例如：

https://your-company.atlassian.net/wiki/spaces/DEV/pages/123456/xxx

这里的 DEV 就是空间 Key。

十一、后续开放写 Wiki 的方式

新人不建议一开始开放写操作。确认只读稳定后，如果确实希望 Codex 创建、更新 Wiki 页面，可以把：

READ_ONLY_MODE=true

改成：

READ_ONLY_MODE=false

同时 ENABLED_TOOLS 增加写工具，例如：

ENABLED_TOOLS=confluence_search,confluence_get_page,confluence_create_page,confluence_update_page

建议团队约定：

默认只读。
需要写页面时，让 Codex 先生成草稿。
人确认后再让 Codex 调用写工具。
不要开放删除类工具，除非非常确定需要。

十二、常见问题

1. `codex` 报 `ps1` 不能运行

报错类似：

codex.ps1 cannot be loaded because running scripts is disabled on this system

解决方式：把命令里的 codex 改成 codex.cmd。

codex.cmd mcp list

2. `docker` 不是内部或外部命令

说明 Docker 没安装，或者安装后没有重启终端。

处理步骤：

安装 Docker Desktop。
打开 Docker Desktop。
等 Docker 运行起来。
关闭 PowerShell，重新打开。
再执行：

docker --version

3. `codex.cmd mcp list` 里有 `wiki`，但不能用

先查看配置：

codex.cmd mcp get wiki

重点检查：

Command 是否是 docker。
Args 里是否有 ghcr.io/sooperset/mcp-atlassian:latest。
环境变量里是否有 CONFLUENCE_URL、CONFLUENCE_USERNAME、CONFLUENCE_API_TOKEN。
Token 是否过期，复制时是否少了一段。
Wiki 地址是否写成了正确的 /wiki 地址。

如果 Command 是空的，建议删除后重建：

codex.cmd mcp remove wiki

4. 认证失败，提示 401 或 Unauthorized

Atlassian Cloud 检查：

CONFLUENCE_USERNAME 必须是登录邮箱，不是昵称。
CONFLUENCE_API_TOKEN 是 API Token，不是登录密码。
Token 复制时不要多复制空格。
当前账号本身要有目标 Wiki 空间的访问权限。

自建 Confluence 检查：

是否应该用 CONFLUENCE_PERSONAL_TOKEN。
PAT 是否过期。
公司是否要求 VPN 或内网环境。
如果是自签证书，再考虑 CONFLUENCE_SSL_VERIFY=false。

5. 查不到文档

可能原因：

关键词太泛或太偏。
账号没有目标空间权限。
CONFLUENCE_SPACES_FILTER 限制了空间。
页面标题和正文不包含你搜索的词。
公司 Confluence 搜索索引延迟。

可以让 Codex 换关键词搜索：

请用 wiki MCP 搜索 Confluence，关键词分别尝试“发布”、“上线”、“部署”，汇总最相关的页面。

十三、完整命令模板

把下面 3 个值替换成你自己的信息：

https://your-company.atlassian.net/wiki
your.email@company.com
your_api_token

然后执行：

docker pull ghcr.io/sooperset/mcp-atlassian:latest

codex.cmd mcp add wiki `
  --env "CONFLUENCE_URL=https://your-company.atlassian.net/wiki" `
  --env "CONFLUENCE_USERNAME=your.email@company.com" `
  --env "CONFLUENCE_API_TOKEN=your_api_token" `
  --env "READ_ONLY_MODE=true" `
  --env "ENABLED_TOOLS=confluence_search,confluence_get_page,confluence_get_comments" `
  -- docker run -i --rm `
    -e CONFLUENCE_URL `
    -e CONFLUENCE_USERNAME `
    -e CONFLUENCE_API_TOKEN `
    -e READ_ONLY_MODE `
    -e ENABLED_TOOLS `
    ghcr.io/sooperset/mcp-atlassian:latest

codex.cmd mcp list
codex.cmd mcp get wiki

测试提问：

请用 wiki MCP 搜索 Confluence 中和“发布流程”相关的页面，返回前 5 条的标题、空间和链接，不要修改任何页面。

DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

腾讯的免费 DeepSeek V4.1 Flash，如何无缝衔接到你的工作流？

DeepSeek技术社区

DeepSeek 涨价了，你换了吗？——技术选型与迁移指南

DeepSeek涨价致月成本翻倍至48000元，缓存命中价最高涨300%。替代模型A、B月成本分别约36000元、30000元。建议个人开发者降本续用，中小团队评估迁移或混合方案，大型企业分步迁移并保留回滚预案。通过缓存复用、请求合并与模型分层调用，可降低40%成本。综合成本、能力与迁移难度，使用五维评分表决策更科学。

DeepSeek技术社区

社区教程拆解：AstrBot + NapCat 接 DeepSeek 的架构与排查链路

QQ 机器人接大模型，真正容易出问题的不是调用一次 Chat API，而是消息从 QQ 客户端到模型再回到 QQ 的每一段是否可观测。2026-09-14 发布的 CSDN 社区教程《QQ 机器人怎么接上 AI？用 AstrBot + NapCat 搭一套可扩展的 DeepSeek 助手》给出了一条可复现路径。需要先说明：它不是 AstrBot、NapCat 或 DeepSeek 的官方公告，而是