跳到主要内容

Codex 配置

Codex 本地用户推荐直接安装 AScript Codex 本地插件包。插件里同时包含本地 MCP 和 AScript Skill，不再让用户分别拼 config.toml、MCP、Skill。它复用了 AI Studio 服务器的工具思路和工作流，Skill 已针对本地直连重新适配。

提示

AI Studio 服务器没有使用公开线上 MCP：服务器内的 MCP 通过配对链路访问手机。本地 Codex 同样运行本地 MCP，但通过局域网或 Android USB/ADB 直连手机。

本地适配配置包含什么​

文件作用
plugins/ascript/.codex-plugin/plugin.jsonCodex 插件入口，声明 Skill 和 MCP
plugins/ascript/.mcp.json本地 MCP，固定使用 ascript-mcp 1.7.0 和兼容的 MCP SDK
plugins/ascript/skills/ascript/SKILL.mdAI Studio 工作流的本地直连适配版 Skill
marketplace.json本地插件市场入口，名称为 ascript-local

1. 下载本地配置包​

解压后重点使用：

ascript-ai-coding-kit/
├── marketplace.json
└── plugins/
    └── ascript/
        ├── .codex-plugin/plugin.json
        ├── .mcp.json
        └── skills/ascript/SKILL.md

2. 安装到本机 Codex​

先安装 uv，让 uvx 可用：

macOS / Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

把插件目录复制到：

~/plugins/ascript

把 marketplace.json 复制到：

~/.agents/plugins/marketplace.json

然后在终端执行：

codex plugin add ascript@ascript-local

如果你已经有自己的 ~/.agents/plugins/marketplace.json，不要直接覆盖；把配置包里 plugins 数组中的 ascript 条目合并进去，然后使用你现有 marketplace 的 name 执行：

codex plugin add ascript@你的-marketplace-name

3. 验证​

新开一个 Codex 任务，让 Codex 重新加载插件。输入：

/mcp

应该能看到 ascript-local。随后可以直接说：

$ascript 检查当前 AScript 工程，连接设备并给出运行验证计划

4. 连接手机并控制真机​

安装插件不会自动连接手机。第一次使用前，需要先让本机 MCP 能访问手机上的 AScript App。

方式 A：局域网连接（Android / iOS）​

  1. 在手机安装并打开 AScript App，进入 开发者，开启设备服务，并记下显示的局域网 IP。

  2. 让手机和运行 Codex 的电脑连接同一个 Wi-Fi。电脑不能只和手机能上网，必须能访问手机所在的局域网。

  3. 在 Codex 中输入：

    请先扫描局域网 AScript 设备；找到设备后先告诉我设备名称、平台和 IP，等我确认后再连接。

  4. 确认设备后，让 Codex 调用 connect_device 连接。局域网默认端口是 9096。

方式 B：USB 连接（Android）​

  1. 打开 Android 开发者选项和 USB 调试，用 USB 线连接电脑，并在手机上确认 ADB 授权。

  2. 确认电脑可以执行 adb devices，状态应为 device。

  3. 在 Codex 中输入：

    请扫描 USB/ADB 设备，连接我确认的 Android 设备，然后读取设备状态和当前屏幕。

连接完成后，要求 Codex 调用 get_device_status 或 screen_capture 验证。只有工具返回真实设备状态或截图，才表示手机已经连通；仅看到 MCP 已连接不代表手机已连接。

AI Studio 配对码不是本地连接方式

AI Studio 服务器中的手机是通过配对码主动连接服务器，再由服务器转发给服务器内的 Codex。当前下载的本地 uvx ascript-mcp==1.7.0 不读取 AI Studio 配对码，也不能直接控制已经在 AI Studio 中配对的手机。本地 Codex 必须使用上面的局域网直连或 Android USB/ADB；不要把手机 9096 暴露到公网。

备用：不用插件时直连 MCP​

不推荐把 Codex 配成散装方式；但如果你的 Codex 暂时不能安装插件，可以下载备用配置。把 codex-config.toml 中的 [mcp_servers.ascript-local] 合并到 ~/.codex/config.toml，再把 ascript-skill.md 保存为 ~/.codex/skills/ascript/SKILL.md：

这两个文件只是兜底方案。完整的本地适配配置仍然是插件包。

注意​

  • 不要把这里改成 https://mcp.ascript.cn/sse。线上 MCP 只适合文档查询，不能复刻 AI Studio 服务器内部设备调试能力。
  • 本地配置固定使用 uvx --with 'mcp<2' ascript-mcp==1.7.0，请先确认终端能执行 uvx --version。
  • 真实 AI Studio 服务器内部地址、token、配对中转配置不导出；可导出和复用的是插件结构、MCP 工具和 Skill 工作流。