Axum headless 服务器 + WebSocket 把代理会话远程控制扩展到浏览器与 iOS

方案简介

该配方利用 Codexia 内置的 headless 模式：用 Rust Axum 启动一个 web 服务器，把桌面端的 Codex/Claude 代理能力通过 HTTP API 与 WebSocket 暴露出去，从而实现远程控制（包括从 iOS 设备）。它把定时任务调度（automation scheduler）也放到服务端 API 上，适合希望离开桌面、在浏览器或手机上继续驱动本机编码代理的开发者。

亮点与能力

• Health 与流接口：GET /health、GET /ws
• Codex 生命周期控制：thread / turn / model / approval 全套 API
• 自动化调度：创建、更新、列表、运行、暂停、删除定时任务
• 文件系统、git、终端操作 API
• Claude 集成接口与笔记、token 用量统计接口
• WebSocket broadcast stream 实时推送

组成与分工

• Axum web server：headless 后端（web/），提供 HTTP API 路由面
• WebSocket（/ws）：broadcast stream，向浏览器客户端实时广播更新
• Codex app-server JSON-RPC：底层代理运行时，API 封装其 session/turn 生命周期
• 浏览器客户端：通过 API 与 /ws 消费代理事件

实施步骤

1. 启动 headless 服务

启动文件为 web/src/server_web.rs（headless server startup）。

2. 验证服务

访问 GET /health 检查健康状态，连接 GET /ws 接收实时事件。

3. 使用 API

通过 /api/codex/thread/、/api/codex/turn/ 等接口驱动代理会话；用 /api/automation/* 管理定时任务。

使用与配置要点

核心入口：web/src/server_web.rs（headless server startup）、src-tauri/src/web/router.rs（HTTP API route surface）。新增能力的扩展路径：Add new API handlers under ./web/src/handlers/，Register routes in ./web/src/router.rs，Add corresponding frontend client calls in src/services/tauri/。

优缺点

• ✓ 可从浏览器/iOS 远程控制
• ✓ API 面完整覆盖生命周期
• ✕ 需本机常驻服务
• ✕ 远程暴露需自行注意安全

出处

本方案挖掘自开源项目 milisp/codexia，方案内容与实施命令均来自其 README 原文。