1. 为什么要在 codex 里接一个 wiki MCP本地知识库维护最烦的不是写文档而是文档散落在 Confluence、语雀、飞书或自建 wiki 里每次让 codex 帮忙改一段内容都得手动复制页面正文、改完再粘回去。codex 本身只能看到你当前工作目录里的文件它不知道公司 wiki 上那篇《发布流程》写了什么也没法直接帮你把更新推回去。MCPModel Context Protocol就是解决这个断层的东西。你可以把它理解成给 codex 装了一个「外接工具接口」codex 通过 config.toml 声明一个 MCP server这个 server 负责跟 wiki 系统对话codex 只需要调用confluence_search、confluence_get_page、confluence_update_page这类工具名就能读取和编辑 wiki 页面。整个过程 codex 不直接碰 wiki 的 API而是把请求交给 MCP server 转发。这篇面向的是本地知识库维护场景你有一台开发机装了 codex CLI想让 codex 稳定地读 wiki、改 wiki。核心动作就三件——在 config.toml 里声明 MCP server、把 TaoToken 的统一 Key/API 通道接进去、跑一次读取加一次编辑做验证。适合第一次接触 codex MCP 的同学也适合之前配过但一直调不通、想搞清楚 config.toml 骨架到底长什么样的人。我试过用命令行codex mcp add一条条加参数配到后面环境变量一多就容易漏后来改成直接维护 config.toml结构清晰、可复制、可版本管理排障也方便。下面按这个思路走。2. TaoToken 前置统一 Key 与 API 通道在写 config.toml 之前先把「codex 调用模型」和「MCP server 访问 wiki」这两条链路分开看。codex 本身要能跑起来需要一个模型 API 通道MCP server 要能访问 wiki需要 wiki 的凭证。这两件事互不干扰但都建议走统一入口管理避免 Key 散落在各个 shell 配置里。TaoToken 在这里承担的是模型 API 统一通道的角色。你可以在官网注册后拿到一个统一 Keycodex 的模型请求走https://taotoken.net/api这个 API 地址不用在 config.toml 里为每个模型单独配 base_url。具体操作路径打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号进入控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteKey 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档参考 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite拿到 Key 之后codex 的模型通道就固定了。MCP server 那边用的是 wiki 自己的 TokenAtlassian API Token 或自建 Confluence 的 PAT两者不要混。很多人配错就是把 TaoToken 的 Key 填进了CONFLUENCE_API_TOKEN结果 401。注意API Token、PAT、TaoToken Key 都是密码级信息。不要写进博客、截图、Git 仓库或群聊。config.toml 如果提交到仓库建议用环境变量引用而不是明文。如果你后面要做长期编码或 Agent 任务可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续性的代码协作场景。单纯验证模型对话能力的话模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。3. config.toml 骨架声明 wiki MCP servercodex 的 MCP 配置有两种写法命令行codex mcp add和直接编辑 config.toml。命令行适合快速试config.toml 适合长期维护。config.toml 一般在~/.codex/config.tomlWindows 是%USERPROFILE%\.codex\config.toml。先看一个最小可用的骨架声明一个名为wiki的 MCP server通过 Docker 启动mcp-atlassian# ~/.codex/config.toml [mcp_servers.wiki] command docker args [ 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 ] [mcp_servers.wiki.env] CONFLUENCE_URL https://your-company.atlassian.net/wiki CONFLUENCE_USERNAME your.emailcompany.com CONFLUENCE_API_TOKEN your_api_token READ_ONLY_MODE true ENABLED_TOOLS confluence_search,confluence_get_page,confluence_get_comments这个骨架的关键点[mcp_servers.wiki]里的wiki是你在 codex 里调用时用的名字后面提问说「用 wiki MCP 搜索」就是它。command docker表示 codex 通过 Docker 启动这个 server好处是不用在本机装 Python 依赖。args里的-e CONFLUENCE_URL这种写法是「把环境变量名传进容器」真正的值在[mcp_servers.wiki.env]里定义codex 启动容器时会把这些值注入。READ_ONLY_MODE true是新人必须保留的。它让 MCP server 只开放读工具codex 就算想改也改不了避免误操作把 wiki 页面覆盖。等你确认读取稳定了再考虑开写。ENABLED_TOOLS是白名单只放你需要的工具。只读阶段放confluence_search、confluence_get_page、confluence_get_comments就够了。写阶段再加confluence_create_page、confluence_update_page。如果你用的是自建 ConfluenceServer / Data Center把认证字段换成 PAT[mcp_servers.wiki.env] CONFLUENCE_URL https://confluence.your-company.com CONFLUENCE_PERSONAL_TOKEN your_personal_access_token READ_ONLY_MODE true ENABLED_TOOLS confluence_search,confluence_get_page,confluence_get_comments对应args里的-e也要把CONFLUENCE_USERNAME、CONFLUENCE_API_TOKEN换成CONFLUENCE_PERSONAL_TOKEN。这一步最容易漏漏了容器里拿不到变量server 启动就报认证失败。4. 把 TaoToken 通道接进 codex 模型配置MCP server 配好了但 codex 自己还得能调模型。codex 的模型配置也在 config.toml 里跟 MCP 是并列的段落。把 TaoToken 的统一 Key 和 API 地址接进去# ~/.codex/config.toml model gpt-4o model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY然后在 shell 里设置环境变量PowerShell 示例$env:TAOTOKEN_API_KEY 你的 TaoToken KeymacOS / Linuxexport TAOTOKEN_API_KEY你的 TaoToken Key这样 codex 的模型请求走 TaoToken 的 API 地址MCP server 的 wiki 请求走 Confluence 自己的地址两条链路各管各的。env_key的好处是 Key 不写进 config.tomlconfig.toml 可以安全地放进 dotfiles 仓库。注意base_url用https://taotoken.net/api不要加多余路径。env_key的名字要和 shell 里设置的环境变量名一致大小写敏感。配完之后先验证 codex 本身能跑codex --help codex mcp listcodex mcp list应该能看到wiki这一条状态是 enabled。如果看不到说明 config.toml 的[mcp_servers.wiki]段落没被解析检查 TOML 语法——常见错误是args数组里少了逗号或者env段落缩进错了。5. 验证动作一次读取 一次编辑配置对不对跑一次读取和一次编辑就知道。先拉镜像只需一次docker pull ghcr.io/sooperset/mcp-atlassian:latest然后进入 codex 会话cd D:\your-project codex5.1 读取验证在 codex 里输入请用 wiki MCP 搜索 Confluence 中和「发布流程」相关的页面返回前 5 条的标题、空间和链接不要修改任何页面。预期结果codex 调用confluence_search返回一个列表每条包含标题、空间 Key、页面链接。如果返回空先确认关键词是否太偏或者账号有没有目标空间权限。再测一次读取具体页面请用 wiki MCP 查找标题为「研发环境搭建」的 Confluence 页面读取正文并总结主要步骤不要修改页面。这一步验证的是confluence_get_page。如果搜索能出结果但读取报错多半是页面 ID 解析或权限问题。5.2 编辑验证编辑验证要先把READ_ONLY_MODE改成false并在ENABLED_TOOLS里加上写工具[mcp_servers.wiki.env] CONFLUENCE_URL https://your-company.atlassian.net/wiki CONFLUENCE_USERNAME your.emailcompany.com CONFLUENCE_API_TOKEN your_api_token READ_ONLY_MODE false ENABLED_TOOLS confluence_search,confluence_get_page,confluence_update_page改完重启 codex 会话。然后让 codex 做一个最小编辑——在页面末尾追加一行请用 wiki MCP 找到标题为「研发环境搭建」的页面在正文末尾追加一行「最后更新由 codex 维护」然后保存。保存前先把修改后的完整正文给我确认。预期结果codex 先调confluence_get_page拿到正文展示修改后的版本你确认后它调confluence_update_page写回。去 wiki 页面刷新能看到新增的那一行。注意编辑验证建议用测试页面不要拿生产文档试。confluence_update_page是覆盖式更新传错正文会把原内容冲掉。让 codex 先展示 diff 再确认是必须保留的习惯。6. 本篇常见错排查配 codex wiki MCP 踩的坑比较集中列几个高频的。报错codex.ps1 cannot be loaded because running scripts is disabledWindows PowerShell 执行策略拦截了codex.ps1。最简单的处理是把命令里的codex换成codex.cmdcodex.cmd mcp listdocker: command not found或docker 不是内部或外部命令Docker Desktop 没装或者装了但终端没重启。装好 Docker Desktop启动等 Engine 运行关掉 PowerShell 重开再执行docker --version。codex mcp list里有 wiki但调用时报连接失败先看配置详情codex mcp get wiki重点检查command是不是dockerargs里有没有ghcr.io/sooperset/mcp-atlassian:latestenv里CONFLUENCE_URL、CONFLUENCE_USERNAME、CONFLUENCE_API_TOKEN是否齐全。如果command是空的说明 config.toml 段落没解析成功删掉重建。认证失败 401 / UnauthorizedAtlassian Cloud 场景CONFLUENCE_USERNAME必须是登录邮箱不是昵称CONFLUENCE_API_TOKEN是 API Token不是登录密码Token 复制时别带空格。自建场景确认用的是CONFLUENCE_PERSONAL_TOKEN而不是CONFLUENCE_API_TOKENPAT 有没有过期。搜索返回空可能原因关键词太泛、账号没目标空间权限、CONFLUENCE_SPACES_FILTER限制了空间、页面标题和正文不含搜索词。可以让 codex 换关键词多试请用 wiki MCP 搜索 Confluence关键词分别尝试「发布」「上线」「部署」汇总最相关的页面。编辑写不进去检查READ_ONLY_MODE是不是还是trueENABLED_TOOLS里有没有confluence_update_page。改完 config.toml 必须重启 codex 会话配置不会热加载。内网自签证书导致连接失败自建 Confluence 用自签证书时可以加CONFLUENCE_SSL_VERIFYfalse但会降低证书校验安全性只在确认是自签证书导致失败时用。对应在args里加-e CONFLUENCE_SSL_VERIFYenv里加CONFLUENCE_SSL_VERIFY false。7. 后续接入与排障入口config.toml 骨架跑通之后日常维护就是改ENABLED_TOOLS和READ_ONLY_MODE两个字段。只读阶段稳定运行一两周再考虑开写工具。团队协作的话建议约定默认只读需要写页面时让 codex 先生成草稿人确认后再调写工具删除类工具不要开放。如果你在接入过程中遇到 Key 或通道问题排障和接入相关的入口在这里API Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite模型对话验证https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite长期编码 / Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteClaude Code 相关的接入参考在 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite Anthropic 通道说明在 https://taotoken.net/anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentanthropicutm_campaignrewrite 。最后留一个实用习惯config.toml 里所有敏感值都用env_key或环境变量引用不要明文。这样你的 dotfiles 可以放心提交换机器时只需要重新设置环境变量MCP 配置和模型通道配置都能直接复用。
