跳到主要内容

Codex 离线配置

本地 Codex 推荐直接安装 AScript Codex 离线包。它把本地 AScript MCP、自动化开发 Skill 和本地 Marketplace 一次性打包好，安装后不需要再去配官方插件目录，也不需要处理付款方式或审核提交。

安装后，Codex 可以查询 AScript API、扫描和连接设备、读取截图和控件树、执行 Python 片段、上传运行工程并分析日志。

本地直连版

这个插件运行在开发者电脑上，通过局域网或 Android USB/ADB 连接手机。它不包含 AI Studio 服务器的 Relay 地址、context token 或配对链路。

插件包含什么​

文件作用
.agents/plugins/marketplace.jsonAScript Codex Marketplace 入口
plugins/ascript/.codex-plugin/plugin.json插件清单、展示信息和能力声明
plugins/ascript/.mcp.json本地 AScript MCP，固定兼容版本
plugins/ascript/skills/ascript/SKILL.md本地真机自动化开发工作流
plugins/ascript/assets/logo.pngAScript 插件图标

1. 下载离线包​

解压后目录如下：

ascript-codex-plugin/
├── .agents/plugins/marketplace.json
└── plugins/ascript/
    ├── .codex-plugin/plugin.json
    ├── .mcp.json
    ├── assets/logo.png
    └── skills/ascript/SKILL.md

2. 准备 uvx​

插件通过 uvx 启动本地 MCP。终端无法执行 uvx --version 时，先安装 uv。

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"

3. 安装插件​

macOS / Linux：进入解压后的 ascript-codex-plugin 目录执行：

codex plugin marketplace add "$(pwd)"
codex plugin add ascript@ascript

Windows PowerShell：进入解压目录执行：

codex plugin marketplace add (Get-Location).Path
codex plugin add ascript@ascript

Marketplace 只需要添加一次。下载包发布新版本后，重新下载并解压到原目录，再执行 codex plugin add ascript@ascript 更新安装。

4. 验证插件​

安装后新开一个 Codex 任务，输入：

/mcp

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

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

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

插件安装成功只表示 MCP 已加载，不表示手机已经连接。

局域网连接：Android / iOS​

  1. 在手机安装并打开 AScript App，进入 开发者，开启设备服务。

  2. 让手机和运行 Codex 的电脑连接同一个局域网。

  3. 在 Codex 中输入：

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

  4. 确认目标后，Codex 调用 connect_device 连接。默认端口为 9096。

USB 连接：Android​

  1. 打开 Android 开发者选项和 USB 调试。

  2. 用 USB 连接电脑，并在手机上确认 ADB 授权。

  3. 确认 adb devices 中设备状态为 device。

  4. 在 Codex 中输入：

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

连接后，让 Codex 调用 get_device_status、screen_capture 或 observe_device 验证。只有返回真实设备状态或截图，才表示手机已经连通。

AI Studio 配对码不能用于本地插件

AI Studio 配对码属于 AI Studio 服务器 Relay 链路。本地 Codex 插件不读取配对码，也不能因为手机已经和 AI Studio 配对就直接控制该手机。本地插件必须使用同一局域网或 Android USB/ADB；不要把手机的 9096 端口暴露到公网。

为什么走离线包​

这个版本的目标很明确：让本地 Codex 直接拥有 AScript 同款能力。

它走的是本地 Marketplace + 本地 MCP + 局域网/ADB 真机连接，不依赖 Codex 官方插件目录，也不需要你先准备付款方式、企业验证或公网 MCP。

如果以后我们再做公网中转版，可以单独出一套官方目录提交文档；这份文档先只讲离线可用的安装法。

备用：手工直连 MCP​

只有 Codex 版本暂不支持插件时，才使用备用配置：

将 codex-config.toml 中的 [mcp_servers.ascript-local] 合并到 ~/.codex/config.toml，并把 ascript-skill.md 保存为 ~/.codex/skills/ascript/SKILL.md。

注意​

  • 本地插件固定使用 uvx --with 'mcp<2' ascript-mcp==1.7.0。
  • 不要把真机调试 MCP 改成 https://mcp.ascript.cn/sse；线上 MCP 只适合文档查询。
  • 插件不包含 AI Studio 服务器内部地址、token、项目绑定或配对中转配置。