Codex 是 OpenAI 的 AI 编程智能体及其客户端，它通过 ONES MCP 以授权身份读取和操作 ONES 数据。本文围绕 Codex 的 config.toml 配置，说明远程直连与 ONES 手册中 npx mcp-remote 代理示例的对应关系、接入前提、验证与排查顺序。内容依据 ONES 国内版公有云产品手册与 Codex 官方 MCP 文档整理，未做目标环境实测，代理与直连的选择需按客户端实际版本验证。
要点总览（TL;DR）
- Codex 的 MCP 服务写在用户级或受信项目级的 config.toml 中，远程直连与 mcp-remote 代理是同一入口下的两种写法，不能混填进同一个服务定义。
- ONES 国内版手册给出的 Codex 示例走 npx mcp-remote 代理，需要本地 Node.js 与 npx；Codex 官方支持远程 MCP 与 OAuth，但直连在 ONES 端点上的可用性需在目标环境验证。
- 接入前从个人中心已授权 MCP 客户端页面复制团队 MCP 地址，路径为 /mcp，OAuth 地址不能替代 MCP 地址。
- 配置成功不等于业务调用成功：先完成 OAuth 授权、检查连接与工具列表，再用一次只读调用核对返回数据。
- 验收看四项：连接状态、工具列表、只读调用结果、权限边界；桌面、CLI、IDE 的配置位置与界面一致性需按实际版本确认。
config.toml 里的两种写法分别对应什么
Codex 的 MCP 服务配置写在 config.toml 中，可以放在用户级，也可以放在受信项目级。这是 Codex 侧的配置入口，决定客户端启动时加载哪些 MCP 服务、用什么方式连接。当前桌面、CLI、IDE 各自的配置适用范围以厂商文档为准，不同界面读取的配置位置可能不同，动手前先确认自己使用的客户端形态。
在这个入口下，存在两种连接形态。第一种是 Codex 官方支持的远程 MCP 加 OAuth：把 ONES 团队 MCP 端点直接交给 Codex，由 Codex 发起远程连接并完成 OAuth 授权。第二种是 ONES 国内版手册给出的 Codex 示例：通过 npx mcp-remote 启动一个本地代理进程，由代理把请求转发到 ONES 端点。两种写法都落在 config.toml 里，但承担的角色不同。
| 要素 | 远程直连 | mcp-remote 代理示例 |
|---|---|---|
| 配置位置 | 用户级或受信项目级 config.toml | 用户级或受信项目级 config.toml |
| 端点交给谁 | 直接交给 Codex | 交给 mcp-remote，由它转发 |
| 认证方式 | OAuth | 按示例配置，经代理完成授权 |
| 本地运行环境 | 不依赖本地 Node.js 代理 | 需要本地 Node.js 与 npx |
| 依据来源 | Codex 官方 MCP 文档 | ONES 国内版配置手册 |
两种写法对应同一份 config.toml 的不同条目，不能把代理命令和直连端点混填进同一个服务定义。混填的典型后果是客户端既启动代理又尝试直连，连接状态反复失败。选定一种方式后，把另一种方式的字段清掉或另起一个服务名，避免同一端点被重复声明。
接入前要准备的端点、凭据与运行环境
接入准备分服务端与客户端两侧。服务端侧，从个人中心的已授权 MCP 客户端页面复制团队 MCP 服务器地址。服务端路径为 /mcp，OAuth 地址不能替代 MCP 地址，两者填错位置会表现为授权页面能打开但工具列表为空或连接直接失败。
凭据侧，ONES MCP 支持 OAuth 和手工 Token 两种授权方式。手工 Token 可通过 X-ONES-MCP-Token 或 Authorization Bearer 携带，凭据绑定用户与团队，需使用 ONES 提供的管理入口获取。选择 OAuth 时，首次连接会跳转授权，完成后回到客户端；选择手工 Token 时，按所选携带方式写入配置的请求头字段。
运行环境侧，代理方式需要本地安装 Node.js，并能通过 npx 拉取 mcp-remote。远程直连是否适用于当前 Codex 版本，需在目标环境另行验证，资料未给出直连在 ONES 端点上的实测结论。
权限侧，可见工具及可操作数据受授权范围、用户权限、许可和团队能力共同限制。工具出现在列表中不保证能操作任意对象；部分相似工作项和知识检索工具还依赖 Assistant 及可用的嵌入模型或检索能力，不能假定所有账户连接后立即获得全部语义能力。
- 端点：个人中心已授权 MCP 客户端页面复制的团队 MCP 服务器地址，路径为 /mcp
- 凭据：OAuth 授权，或手工 Token 配合 X-ONES-MCP-Token / Authorization Bearer
- 环境：代理方式需 Node.js 与 npx；直连方式按版本验证
- 权限：授权范围、用户权限、许可、团队能力共同决定工具与数据范围
mcp-remote 示例与远程直连的字段映射
ONES 手册的 Codex 示例采用 npx mcp-remote 连接，示例中的要素可以逐项对应到 config.toml 的服务定义：启动命令落到命令字段，mcp-remote 及其参数落到参数列表，团队 MCP 端点作为参数传入代理，认证按示例要求配置。代理方式下，端点经 mcp-remote 转发，Codex 本身看到的是一个本地启动的进程。
远程直连时，端点直接交给 Codex，认证走 OAuth，不再需要命令与参数启动代理。此时保留的是服务名、端点地址与 OAuth 相关设置，替换掉的是代理命令、npx 参数和代理侧的认证参数。下面两段配置为示意，用于说明字段位置，不作为逐字官方原文，字段名与生效范围请按客户端实际版本核对。
代理方式示意：
[mcp_servers.ones]
command = "npx"
args = ["-y", "mcp-remote", "<团队 MCP 端点>"]
远程直连示意：
[mcp_servers.ones]
url = "<团队 MCP 端点>"
两段示意共用同一个服务名，实际使用时只保留其中一种。若需要在同一份 config.toml 中保留两种方式做对比，应使用不同服务名，并在验证完成后删除不用的那条，避免客户端重复加载同一端点。字段名、是否支持 url 直写、OAuth 是否由客户端自动发起，均以所用 Codex 版本的官方文档为准。
首次授权、连接检查与只读验证
填入当前团队端点后完成 OAuth 授权，再回到客户端检查连接状态与工具列表。这一步确认的是配置被正确读取、授权流程走通、服务端返回了工具发现结果。工具数量以连接后的实际发现结果为准，手册与官网公布的数量不完全一致，实际列表取决于团队与授权，不宜按固定数量判断成功与否。
配置成功不等于业务调用已成功。授权通过、工具列表出现，只说明连接层可用；能否读取具体工作项、能否执行工作流，还取决于用户权限、字段必填规则与团队能力。验证时应选一次只读调用，例如查询待办或查询某个工作项详情，观察返回内容是否与 ONES 中的实际数据一致。
- 在 config.toml 中写入选定方式的配置，确认端点无多余空格
- 启动客户端，触发 OAuth 授权并完成登录
- 检查连接状态，确认服务显示已连接
- 查看工具列表，确认出现预期工具
- 执行一次只读调用，例如查询待办或工作项详情，核对返回数据
- 记录通过判据：连接状态正常、工具列表非空、只读调用返回真实数据
只读验证通过后，再按需尝试手册示例中的其他动作，如推进工作项、拆分子任务、登记工时或检索知识库。执行前确认目标工具的字段、权限和团队能力均已满足。该 MCP 服务暂不支持删除操作，验证动作应避开删除类预期。
连接失败与重复配置的排查顺序
排查按从环境到配置、从连接层到业务层的顺序推进，避免在权限问题上反复改配置。代理方式下，先检查 Node.js 与 npx 是否可用、端点是否带多余空格、网络是否可达；这三项是手册给出的排查起点，仅适用于使用该代理方式的配置。
| 现象 | 优先检查 | 处理方向 |
|---|---|---|
| 客户端启动后服务未加载 | config.toml 位置与语法 | 确认写在用户级或受信项目级，检查服务名与字段拼写 |
| 代理进程启动失败 | Node.js、npx、网络 | 补齐运行环境，确认能拉取 mcp-remote |
| 授权页打不开或回调失败 | 端点是否为 /mcp 地址 | OAuth 地址不能替代 MCP 地址，回到个人中心重新复制 |
| 连接成功但工具列表为空 | 授权范围与团队能力 | 确认授权范围覆盖所需工具，检查许可与团队配置 |
| 工具存在但调用报错 | 用户权限与字段规则 | 区分权限不足与必填字段缺失，按返回信息定位 |
| 连接状态反复变化 | 是否存在重复配置 | 用户级与项目级同时声明同一端点时保留一处 |
用户级与项目级配置同时存在时，需要明确以哪一处为准。项目级配置适合随项目分发的固定端点，用户级适合个人常用端点；同一服务名在两处重复声明容易造成加载顺序不确定，处置方式是只保留一处，或在项目级使用不同服务名并明确用途。
授权范围不足与工具缺失要分开判断。工具未出现在列表中，可能是授权范围未覆盖、许可未开通或团队能力未启用；工具出现但调用失败，更多指向用户对具体对象的权限或字段必填规则。两类问题的修复位置不同，先看列表再看调用结果，能减少无效改动。
验收标准与仍需确认的范围
验收以可观察结果为准，四项条件同时满足才算接通：连接状态显示正常；工具列表按当前团队与授权返回；一次只读调用返回与 ONES 一致的真实数据；调用范围落在授权与权限边界内，未越权访问其他团队或对象。
- 连接状态：客户端中该服务显示已连接
- 工具列表：与团队授权相符，数量以实际发现为准
- 只读调用：查询待办或工作项详情返回真实数据
- 权限边界：仅能操作授权范围内的对象
仍需在目标环境确认的事项包括：选用代理还是直接 HTTP，并验证授权与只读调用；远程直连在所用 Codex 版本上是否可用；桌面、CLI、IDE 三种形态的配置位置与界面是否一致。本文不承诺三种形态与两种方式完全等效，也不承诺跨版本界面相同。
本次结论以 ONES 国内版公有云产品手册与 Codex 官方 MCP 文档为限，未做目标环境实测。私有部署场景需按文内条件另行核对端点与网络。资料未覆盖的版本差异，应在实际客户端中按上述验收清单逐项确认后再投入日常使用。
常见问题
Codex 的 config.toml 里已经写了 mcp-remote 代理，还能再写一条远程直连吗？
可以写，但要分开处理。两种写法对应同一份 config.toml 的不同条目，不能把代理命令和直连端点混填进同一个服务定义，否则客户端可能既启动代理又尝试直连，连接状态反复失败。若确实要保留两种方式做对比，应使用不同服务名，并在验证完成后删除不用的那条，避免同一端点被重复加载。实际字段名与是否支持直写端点，以所用 Codex 版本的官方文档为准。
使用手工 Token 时，凭据应该放在哪里？
ONES MCP 支持 OAuth 和手工 Token 两种授权方式。手工 Token 可通过 X-ONES-MCP-Token 或 Authorization Bearer 携带，凭据需使用 ONES 提供的管理入口获取，并绑定用户与团队。选择 OAuth 时，首次连接会跳转授权，完成后回到客户端；选择手工 Token 时，按所选携带方式写入配置的请求头字段。凭据与团队绑定，换团队或换用户时需要重新确认。
连接显示成功、工具列表也有内容，为什么调用还是报错？
连接层可用与业务调用可用是两件事。可见工具及可操作数据受授权范围、用户权限、许可和团队能力共同限制，工具出现在列表中不保证能操作任意对象。调用报错时先区分是权限不足还是字段必填规则未满足，再按返回信息定位。另外，部分相似工作项和知识检索工具依赖 Assistant 及可用的嵌入模型或检索能力，这类工具在条件不满足时表现也会不同。
验证接通时可以用删除类操作来测试吗？
不建议。所读 MCP 概述明确该服务暂不支持删除操作，这一限制只针对该 MCP 服务，不代表 REST API 也无删除能力。验证应选只读动作，例如查询待办或查询某个工作项详情，核对返回内容与 ONES 中的实际数据是否一致。只读验证通过后，再按需尝试推进工作项、拆分子任务、登记工时或检索知识库等动作，执行前确认目标工具的字段、权限和团队能力均已满足。
代理方式连接失败，应该先查什么？
按从环境到配置的顺序推进。代理方式下，先检查 Node.js 与 npx 是否可用、端点是否带多余空格、网络是否可达，这三项是手册给出的排查起点，仅适用于使用该代理方式的配置。若授权页打不开或回调失败，检查填入的是否为 /mcp 地址，OAuth 地址不能替代 MCP 地址。若连接成功但工具列表为空，转向授权范围、许可与团队能力排查，避免在环境问题上反复改动。
官方参考资料
- Model Context Protocol（OpenAI）
- MCP 服务概述（ONES）
- MCP 配置与使用（ONES）
