摘要

Agmente是面向编码代理的iOS客户端，可连接ACP或Codex app-server协议的服务器，展示工具调用、结果与对话记录。支持Cloudflare Tunnel远程访问，可通过标准步骤部署远程ACP代理，并完成iOS端的构建与测试。

Agmente：面向编码代理的iOS客户端全指南 | 部署、使用与测试

作为开发者，你是否曾希望在iOS设备上便捷访问各类编码代理，实时查看工具调用过程、执行结果与完整的对话历史？Agmente这款专为编码代理打造的iOS客户端，恰好解决了这一需求——它能无缝对接遵循ACP（Agent Client Protocol）或Codex app-server协议的服务器，让移动场景下的编码代理访问变得简单高效。

一、Agmente是什么？核心价值在哪里？

Agmente的核心定位是编码代理的iOS端访问入口，它并非一款编码代理本身，而是充当了“桥梁”角色：一端连接运行ACP或Codex app-server协议的服务器（无论是本地还是远程），另一端在iOS设备上直观呈现编码代理的工具调用、执行结果与全量对话历史。

Agmente screenshot

从实际使用价值来看，Agmente的设计完全围绕开发者的移动访问需求展开：

  • 跨协议兼容：既支持ACP协议的各类编码代理，也适配Codex app-server的端点，覆盖主流的编码代理服务形态；
  • 移动化访问：摆脱桌面端限制，在iPhone/iPad上即可查看编码代理的全量交互过程，适配移动办公、外出调试等场景；
  • 安全远程访问：支持Cloudflare Tunnel + Access凭证的组合方式，既实现远程代理的访问，又保障连接的安全性；
  • 轻量化部署：配套的远程代理部署步骤简洁，无需复杂的环境配置，即可快速搭建可被Agmente访问的远程编码代理服务。

二、Agmente的核心能力：你能用到的关键功能

想要判断一款工具是否适配自己的需求，核心能力是最关键的参考维度。Agmente的核心能力均围绕“便捷、安全访问编码代理”展开，且每一项能力都经过实际场景验证，具备可落地性：

1. 多协议编码代理连接支持

Agmente的核心优势之一是对主流编码代理协议的兼容，具体覆盖两类核心协议体系：

  • ACP（Agent Client Protocol）代理：支持Copilot CLI、Gemini CLI、Claude Code适配器、Qwen、Mistral Vibe等多款基于ACP协议的编码代理，这意味着你日常使用的主流ACP编码代理，都能通过Agmente在iOS设备上访问；
  • Codex app-server端点：专门适配Codex app-server的服务端点，无需额外的协议转换，即可直接连接对应的编码代理服务。

2. 全量交互过程可视化

在iOS设备上使用编码代理时，最核心的需求是“看清过程、拿到结果”。Agmente会在对话记录（transcript）中完整展示：

  • 编码代理的工具调用行为：明确看到代理调用了哪些工具、调用的参数与触发条件；
  • 工具执行结果：每一次工具调用后的返回结果会实时呈现，无需切换到桌面端查看；
  • 完整对话历史：所有与编码代理的交互内容会留存，方便后续回溯、调试。

3. 安全的远程访问能力

如果你的编码代理部署在远程主机（而非本地），Agmente也提供了成熟的远程访问解决方案，核心依赖Cloudflare生态的安全能力：

  • Cloudflare Tunnel：将远程主机的编码代理服务暴露为加密的wss://端点，避免直接开放端口带来的安全风险；
  • Cloudflare Access凭证：可选配置该凭证，进一步限制访问权限，只有持有合法凭证的设备才能连接远程代理；
  • 令牌认证：支持bearer tokens（承载令牌），当远程端点被权限保护时，可通过令牌完成身份验证，保障访问的安全性。

三、How-To：部署远程ACP代理并接入Agmente

很多开发者的编码代理部署在远程主机（比如云服务器、私有服务器），如何让Agmente安全访问这些远程代理？以下是经过验证的、可直接落地的步骤，全程基于标准命令行操作，无额外定制化要求。

前置说明

本次实操的核心是通过stdio-to-ws工具，将远程主机上的ACP代理（以Copilot CLI为例）转换为WebSocket服务，再通过TLS加密暴露为wss://端点，最终被Agmente访问。所有操作均在远程主机的命令行中完成，需确保远程主机已安装Node.js（满足npx运行条件）。

步骤1：启动远程ACP代理的WebSocket服务

在远程主机的命令行中，执行以下命令：

npx -y @rebornix/stdio-to-ws --persist --grace-period 604800 "copilot --acp" --port 8765

命令参数解读（确保每一步可验证）

  • npx -y：无需手动确认，直接安装并运行stdio-to-ws工具；
  • @rebornix/stdio-to-ws：核心工具，作用是将标准输入输出（stdio）的ACP代理服务转换为WebSocket服务；
  • --persist：启用持久化模式，避免服务意外中断；
  • --grace-period 604800：设置优雅退出的超时时间为604800秒（7天），保障服务长期稳定运行；
  • "copilot --acp"：指定要运行的ACP代理命令（此处以Copilot CLI为例，可替换为Gemini CLI、Claude Code适配器等其他ACP代理命令）；
  • --port 8765：指定WebSocket服务监听的端口为8765（可根据远程主机端口占用情况调整）。

执行该命令后，远程主机的8765端口会启动一个WebSocket服务，该服务会转发所有请求到copilot --acp启动的ACP代理，此时ACP代理已具备被WebSocket访问的能力。

步骤2：停止远程ACP代理的WebSocket服务（按需操作）

如果需要停止已运行的WebSocket服务，可在远程主机执行以下命令：

pkill -9 -f "stdio-to-ws.*8765"

命令参数解读

  • pkill -9：强制终止匹配的进程；
  • -f "stdio-to-ws.*8765"：匹配所有包含“stdio-to-ws”且关联8765端口的进程，精准终止目标服务，避免误杀其他进程。

步骤3：将服务暴露为加密的wss://端点

完成步骤1后，8765端口的WebSocket服务仅能在远程主机内网访问，需通过TLS加密并暴露为公网可访问的wss://端点（具体步骤可参考docs/remote-agent.md）。核心要求是：

  • 为远程主机配置有效的TLS证书（可通过Cloudflare、Let’s Encrypt等方式获取）；
  • 将8765端口的WebSocket服务通过反向代理（如Nginx）或Cloudflare Tunnel映射为wss://<你的远程主机域名/IP>；
  • 确保暴露后的端点支持HTTPS/WSS加密，否则Agmente无法安全连接。

步骤4：在Agmente中接入远程代理

打开iOS设备上的Agmente应用，在连接配置中输入wss://<your-host>（替换为你暴露后的远程主机地址），若端点配置了bearer tokens或Cloudflare Access凭证，需在对应字段填写凭证信息，完成后即可连接远程ACP代理，查看工具调用、结果与对话历史。

四、Agmente的仓库结构与环境要求

想要自行构建Agmente的iOS应用（而非直接从App Store下载），首先需要了解其仓库布局与环境要求，所有要求均为行业标准，无特殊定制化依赖。

1. 仓库目录结构

Agmente的代码仓库采用模块化设计，不同功能模块拆分到独立目录，便于维护与扩展：

目录名称 核心功能
Agmente/ iOS应用的核心源代码，包含UI界面、交互逻辑、协议适配等核心功能
ACPClient/ 供iOS应用使用的Swift包，专门处理ACP协议的解析、通信等逻辑
AppServerClient/ 针对Codex app-server协议的客户端支持模块，负责该协议的通信与数据解析

这种目录结构符合iOS开发的最佳实践，不同协议的客户端逻辑解耦，便于后续扩展新的协议支持，也方便开发者针对特定模块进行二次开发。

2. 构建环境要求

构建Agmente的iOS应用需满足以下硬件与软件要求，所有要求均为苹果官方推荐的标准配置：

  • 操作系统：必须使用macOS（仅macOS支持iOS应用的构建，Windows/Linux无法完成）；
  • 开发工具：Xcode（推荐使用最新稳定版本，确保兼容最新的iOS SDK与Swift语法）；
  • 无额外依赖：除Xcode自带的开发工具链外，无需安装其他第三方工具（如CocoaPods等），直接通过Xcode即可完成构建。

五、How-To：Agmente的iOS应用构建与测试

如果你需要自行构建Agmente（比如定制化功能、适配特定iOS版本），以下是两种标准化的构建方式（图形界面与命令行），以及对应的测试方法，所有步骤均可直接验证，无模糊描述。

1. iOS应用构建（两种方式可选）

方式1：Xcode图形界面构建（适合可视化操作）

步骤如下：

  1. 打开macOS上的Xcode应用；
  2. 在Xcode中选择“Open a project or file”，找到并打开Agmente仓库中的Agmente.xcodeproj文件；
  3. 在Xcode的“Scheme”下拉菜单中选择“Agmente”方案；
  4. 在“Destination”下拉菜单中选择目标设备：可选择iOS模拟器（如iPhone 16）或已连接的iOS真机；
  5. 点击Xcode左上角的“Run”按钮（三角形图标），Xcode会自动编译代码、构建应用，并将应用安装到选定的模拟器/真机上。

方式2：CLI命令行构建（适合自动化/脚本部署）

如果需要通过脚本或自动化工具构建，可使用xcodebuild命令（Xcode自带的命令行构建工具），示例命令如下：

xcodebuild -project Agmente.xcodeproj -scheme Agmente -destination 'platform=iOS Simulator,name=iPhone 16'

命令参数解读

  • -project Agmente.xcodeproj：指定要构建的Xcode项目文件；
  • -scheme Agmente：指定构建的方案为Agmente（与Xcode图形界面中的Scheme对应）；
  • -destination：指定构建的目标设备，此处为iOS Simulator（iPhone 16），可替换为真机的UDID（格式：platform=iOS,name=<设备名称>,id=<UDID>）。

执行该命令后，xcodebuild会在终端输出构建日志，若构建成功，会在仓库的build目录下生成对应的iOS应用包（.app文件）。

2. Agmente的测试方法

测试是保障应用稳定性的关键，Agmente提供了两类标准化的测试方式，分别针对iOS应用本身和ACPClient Swift包。

测试1：Agmente iOS应用测试

通过xcodebuild的test参数可执行应用的自动化测试，示例命令如下：

xcodebuild -project Agmente.xcodeproj \
  -scheme Agmente \
  -destination "platform=iOS Simulator,id=<SIMULATOR_UDID>" \
  test

命令参数解读

  • -test：指定执行测试任务，而非构建任务；
  • -destination "platform=iOS Simulator,id=<SIMULATOR_UDID>"：指定测试的目标模拟器（需替换<SIMULATOR_UDID>为实际的模拟器唯一标识符）；
  • 其他参数：与构建命令一致，确保测试环境与构建环境匹配。

执行该命令后，Xcode会自动运行Agmente应用中的所有测试用例，并在终端输出测试结果（通过/失败的用例数、错误信息等）。

测试2：ACPClient Swift包测试

ACPClient是Agmente的核心Swift包，负责ACP协议的处理，可单独测试该包的功能，命令如下：

swift test --package-path ACPClient

命令参数解读

  • swift test：Swift官方的包测试命令，用于执行Swift Package的测试用例；
  • --package-path ACPClient：指定Swift包的目录为ACPClient，确保测试工具定位到正确的包。

执行该命令后，会自动运行ACPClient包中的所有测试用例，验证ACP协议解析、消息收发、异常处理等底层逻辑的正确性。

六、FAQ：关于Agmente的常见问题解答

为了帮你快速解决使用过程中可能遇到的问题，我们整理了最常被问到的核心问题，所有答案均基于Agmente的官方设计与功能特性：

Q1：Agmente支持哪些编码代理？

A1：Agmente支持两类编码代理：一是遵循ACP（Agent Client Protocol）的代理，包括Copilot CLI、Gemini CLI、Claude Code适配器、Qwen、Mistral Vibe等；二是部署在Codex app-server端点的编码代理，无需协议转换即可直接连接。

Q2：必须部署远程代理吗？Agmente能连接本地代理吗？

A2：不需要。Agmente既支持连接远程主机上的编码代理，也支持连接本地（与iOS设备同局域网）的ACP/Codex app-server代理，只需在配置中填写本地代理的wss:///ws://端点即可。

Q3：Cloudflare Tunnel是必须的吗？

A3：并非必须。Cloudflare Tunnel是为了保障远程代理的安全访问，若你的远程代理部署在可信内网、且无需公网访问，可直接暴露ws://端点（非加密）供Agmente访问；但公网访问时，强烈建议使用Cloudflare Tunnel + TLS加密，避免数据泄露或未授权访问。

Q4：自行构建Agmente需要付费吗？

A4：不需要。Agmente基于MIT许可证开源，所有源代码均可免费获取、修改、构建，仅需满足macOS + Xcode的环境要求，无额外的付费依赖或授权费用。

Q5：Agmente的测试用例覆盖哪些场景？

A5：Agmente的iOS应用测试主要覆盖UI交互、协议通信、数据展示等核心场景；ACPClient Swift包测试则聚焦于ACP协议的解析、消息收发、异常处理等底层逻辑，确保协议通信的稳定性。

Q6：如何获取Agmente？

A6：有两种方式：一是直接从App Store下载（链接：https://apps.apple.com/us/app/agmente/id6756249477），无需自行构建；二是从仓库获取源代码，在macOS上通过Xcode自行构建。

Q7：远程代理部署后，如何保障访问的安全性？

A7：可通过两种方式强化安全：一是为远程端点配置bearer tokens，只有持有合法令牌的设备才能访问；二是启用Cloudflare Access服务令牌，结合Cloudflare Tunnel实现权限管控，双重保障远程访问的安全性。

Q8：构建Agmente时，Xcode版本有严格要求吗？

A8：推荐使用最新稳定版本的Xcode，以兼容最新的iOS SDK和Swift语法，避免因版本过低导致的编译错误；无强制的最低版本要求，但需确保Xcode能支持iOS应用的常规构建流程。

七、Agmente的许可证与长期使用说明

Agmente采用MIT开源许可证（可查看仓库中的LICENSE文件），这意味着你可以：

  • 免费使用Agmente的所有功能，无论是个人还是商业用途；
  • 修改Agmente的源代码，适配自己的个性化需求；
  • 分发Agmente的构建产物，无需向原作者支付费用。

从长期使用的角度，Agmente的设计具备良好的扩展性：

  • 模块化的仓库结构让新增协议支持（如未来的新编码代理协议）变得简单；
  • 基于标准的Swift包与Xcode构建流程，适配苹果官方的iOS开发生态，不会因版本迭代出现兼容性问题；
  • 依赖的stdio-to-ws等工具均为开源且维护活跃，保障远程代理部署的长期可用性。

此外，Agmente的官方文档体系也为长期使用提供了支撑：

  • 完整的远程代理部署指南：docs/remote-agent.md详细说明如何将远程代理暴露为wss://端点，解决公网访问的核心问题；
  • 本地部署参考：setup.md（本地文档为Agents.md）提供了全流程的部署说明，涵盖从环境准备到代理连接的所有步骤；
  • 无隐藏配置：所有核心功能的实现逻辑均在开源代码中呈现，开发者可按需排查问题、定制化开发。

八、总结

Agmente作为一款专注于编码代理的iOS客户端，核心价值在于“打通移动设备与编码代理的连接链路”——它不只是一个简单的“查看工具”，更是将桌面端的编码代理能力延伸到iOS设备的完整解决方案。

无论是连接本地/远程的ACP代理，还是适配Codex app-server端点；无论是通过Cloudflare保障远程访问安全，还是自行构建定制化版本，Agmente都提供了标准化、可验证、易落地的方案。对于需要在移动场景下访问编码代理的开发者来说，它既具备专业的协议适配能力，又兼顾了使用的便捷性，是iOS平台上编码代理访问的可靠选择。

如果你在使用过程中需要更详细的部署指南（如完整的Cloudflare Tunnel配置），可参考仓库中的setup.md（本地文档为Agents.md）和docs/remote-agent.md，所有文档均提供了可直接操作的步骤，确保每一个功能都能落地使用。

从技术落地的角度，Agmente的设计遵循“最小化依赖、标准化流程”的原则：无需复杂的第三方组件，仅通过苹果官方工具链即可完成构建；远程代理部署仅需两条核心命令，降低了开发者的使用门槛；全流程的测试方案则保障了功能的稳定性，让开发者可以放心在生产场景中使用。