MCP 客户端接入

如何让 Codex 操作你的纯血鸿蒙手机(MCP 接入教程)

详解如何给 Codex 配置 xiaobei-harmony-mcp 的 TOML 配置段,在同一 Wi-Fi 下直连 HarmonyOS NEXT 真机,完成查看画面与自动化真机验证。

兼容 HarmonyOS NEXT(API 24 及以上)更新日期:2026-11-14阅读时长:约 5 分钟

快速步骤概览

  1. 确认电脑已经装好 Node.js(可用 npx),手机完成小贝无线调试并连入同一 Wi-Fi。
  2. 让 Codex 读取配对文档自动写入 ~/.codex/config.toml,或运行 config 命令生成 UUID 后手动贴入 TOML 配置块。
  3. 在 Codex 中发出「用小贝检查一下手机连接」触发配对码,并在小贝「AI 连接」确认允许。
  4. 授权后即可让 Codex 查看鸿蒙真机屏幕、定位元素或执行点击测试。

Codex 支持通过标准 MCP 连接纯血鸿蒙手机,不过和大多数桌面 IDE 不同,Codex 使用 TOML 文件(config.toml)管理 MCP 服务,而不是 mcp.json。按下面步骤配好,Codex 就能直接读写你手边的 HarmonyOS NEXT 真机界面。

准备条件

  1. 手机装好 小贝自动点击器,已完成单机无线调试配对并登录有效会员。
  2. 电脑已安装 Node.js(终端可用 npx),且与手机连在同一个 Wi-Fi 局域网。

方法一:发一句话让 Codex 自动改好 config.toml

在 https://mcp.aoqi360.com/?client=codex#connect 复制,或者直接把下面这句话发给 Codex:

请阅读小贝接入教程:https://mcp.aoqi360.com/autoclicker/llms.txt,帮我在 "Codex" 中连接小贝。

Codex 会按 TOML 格式把小贝服务写进你当前的 config.toml(默认 ~/.codex/config.toml,如设置了 CODEX_HOME 则为 $CODEX_HOME/config.toml),并保留你原先配置好的其他服务。

方法二:手动把 TOML 配置块写入 ~/.codex/config.toml

  1. 先在终端跑一次配置生成命令,拿一个固定的 XIAOBEI_MCP_INSTANCE_ID(UUID):
npx -y xiaobei-harmony-mcp config --client=codex
  1. 打开 ~/.codex/config.toml(Windows 通常在 %USERPROFILE%\.codex\config.toml),在末尾加上这几行(Windows 如需把 "npx" 改为 "npx.cmd"):
[mcp_servers.xiaobei-harmony]
command = "npx"
args = ["-y", "xiaobei-harmony-mcp"]

[mcp_servers.xiaobei-harmony.env]
XIAOBEI_MCP_CLIENT_ID = "codex"
XIAOBEI_MCP_INSTANCE_ID = "替换为上一步生成的UUID,生成一次固定保留"
XIAOBEI_MCP_APP_ID = "autoclicker"
XIAOBEI_MCP_HUB_URL = "https://api.aoqi360.com"

请不要把别的客户端教程里的 .json 整段直接粘进 config.toml,否则 Codex 启动会报 TOML 语法错误。

手机确认配对与开始使用

  1. 重新进入 Codex(让它加载刚写的 config.toml),然后发送:
用小贝检查一下手机连接。
  1. 此时会打开二维码配对页并显示 4 位短码(有效期 10 分钟)。
  2. 打开手机上的 小贝自动点击器 -> AI 连接,扫码或者填 4 位短码,确认客户端显示为 Codex 后点击 「允许连接」。
  3. 配对完成后,即可让 Codex 截图检查鸿蒙页面、定位控件或帮忙执行回归点按流程。

切换客户端与中断保护

  • 小贝允许在手机里同时保存 Codex、Cursor、CubeAgent 等多份授权;哪天换用别的工具时,在手机「AI 连接」页面切换一下当前启用的客户端即可。
  • 操作期间,小窗和实况通知栏都能随时暂停或停止;所有手机画面与指令都在本地局域网内点对点传送。

相关常见问题

Codex 的 MCP 配置能直接复制 JSON 贴进去吗?

不能。Codex 使用的是 TOML 格式配置文件(默认是 ~/.codex/config.toml,或自定义 CODEX_HOME/config.toml),必须按本教程里的 [mcp_servers.xiaobei-harmony] TOML 写法添加。

我在项目里单独配过 .codex/config.toml,会冲突吗?

一般只在用户级 ~/.codex/config.toml 加一次小贝即可。如果你已经在当前可信项目下写过项目级 .codex/config.toml,注意两边不要重复填入不同的 XIAOBEI_MCP_INSTANCE_ID。

已经连过手机,但重新打开 Codex 还是只看得到状态工具?

在当前 Codex 会话里再调用一次检查连接(或发送「用小贝检查一下手机连接」),即可刷新出手机端最新工具列表,不需要重新扫码。