服务模式（ante serve）

服务模式（Server mode）将 Ante 作为长寿命守护进程运行，外部客户端可通过结构化的消息协议对其进行驱动。非常适合用于构建编辑器插件、Web UI 界面或任何需要长期以编程方式控制 Ante 的自动化工作流。

基础用法

ante serve

该命令将启动守护进程，并通过 stdin/stdout 桥接 JSONL 协议。进程会持续运行，直到客户端发送 Shutdown 操作指令或关闭 stdin。

Stdio 标准输入输出传输（默认）

ante serve --stdio

--stdio 参数为可选 —— stdio 是默认传输方式。守护进程从 stdin 逐行读取 OpMsg JSON 对象，并将 EventMsg JSON 对象逐行写入 stdout。

Unix 套接字传输

ante serve --sock                 # ~/.ante/run/serve.sock
ante serve --sock /tmp/ante.sock

--sock 将协议托管在 Unix 域套接字上，因此生命周期长于单次连接的客户端可以直接连入宿主，而无需每次都拉起一个新进程。未指定路径时，套接字位于 Ante 主目录下的 run/serve.sock。

每个连接驱动各自的会话。某个客户端的 Shutdown 只结束该客户端的连接，宿主继续监听；宿主进程在收到 SIGINT 或 SIGTERM 时退出。

备注

同一时刻只有一个宿主拥有某个套接字路径。所有权由套接字旁 .lock 文件上的排他锁表示：同一路径上的第二个 ante serve --sock 会拒绝启动，而不是抢占该路径，因此正在运行的宿主不会被从其客户端下方抽走。崩溃遗留的套接字文件不持有锁，会在下次启动时被替换，无需手动清理。

WebSocket 传输

ante serve --ws 127.0.0.1:8080

--ws 参数在指定地址上启动 WebSocket 服务端。每个客户端在共享主机上拥有独立连接与会话。服务端持续循环接受新连接，直到收到 Shutdown 操作指令。

备注

传输方式参数互斥 —— 只能在 --stdio、--sock、--ws 中选择其一。

警告

监听地址必须为本地回环地址（127.0.0.0/8 或 ::1）。Ante 拒绝绑定任何其他地址 —— 传入 0.0.0.0:8080 会在绑定前直接报错退出。由于该协议未设置身份认证，将其暴露到局域网或公网接口将赋予任何接入客户端在机器上执行任意工具的完全权限。若需从远程访问守护进程，请通过 SSH 隧道或带身份验证的反向代理转发。

工作原理

1. 主机启动并等待所选传输方式上的操作指令
2. 发送 StartSession 操作，使用所选模型和提供商初始化会话
3. 发送 UserInput 操作提交提示词
4. 在同一连接上接收流式事件 —— 思考增量、消息增量、工具调用、审批请求
5. 响应 TurnPause 事件，发送 ApprovalResponse 以批准或拒绝工具调用
6. 发送 Shutdown（或断开连接）以优雅关闭连接；在 stdio 和 WebSocket 模式下，Shutdown 还会结束服务进程

完整消息目录与报文格式请参阅通信协议参考手册。

调用会话示例

# 启动守护进程，通过命名管道向其 stdin 发送 JSONL
mkfifo /tmp/ante-pipe
ante serve < /tmp/ante-pipe &
echo '{"op":{"StartSession":{"model":"claude-sonnet-5","provider":"anthropic"}},"id":"op_001"}' > /tmp/ante-pipe
echo '{"op":{"UserInput":"what is 2+2"},"id":"op_002"}' > /tmp/ante-pipe

在实际工程中，您会通过子进程方式直接拉起并写入 stdin。以下为 Node.js 示例：

const { spawn } = require("child_process");

const ante = spawn("ante", ["serve"]);
let buffer = "";

ante.stdout.on("data", (chunk) => {
  buffer += chunk.toString();
  const lines = buffer.split("\n");
  buffer = lines.pop();
  for (const line of lines) {
    if (!line.trim()) continue;
    const event = JSON.parse(line);
    console.log("Event:", event.event);
  }
});

ante.stdin.write(JSON.stringify({
  op: { StartSession: { model: "claude-sonnet-5", provider: "anthropic" } },
  id: "op_001"
}) + "\n");

ante.stdin.write(JSON.stringify({
  op: { UserInput: "explain what this project does" },
  id: "op_002"
}) + "\n");

Rust SDK

ante-sdk 是面向外部程序的 Ante 客户端，因此 Rust 集成无需自行处理 JSONL 分帧或管理宿主进程。connect 会返回一个 Client —— 即一个 op 发送端与一个事件接收端 —— 适用于任意传输方式：

use ante_sdk::{ConnectOptions, connect, protocol::{Op, SessionRequest}};

let mut client = connect("stdio".parse()?, ConnectOptions::default()).await?;

client.send(Op::StartSession(SessionRequest {
    model: Some("claude-sonnet-5".into()),
    provider: Some("anthropic".into()),
    ..Default::default()
})).await?;

client.send(Op::UserInput("explain what this project does".into())).await?;

while let Some(event) = client.next_event().await {
    println!("{event:?}");
}

Endpoint 描述的是宿主在哪里可达 —— 而非某个会话。连接驱动哪个会话，由其上发送的 op（StartSession、ResumeSession）决定：

Endpoint	客户端行为	宿主生命周期
stdio	将 ante serve --stdio 作为自身子进程拉起	随连接结束 —— 丢弃 op 发送端即关闭子进程的 stdin
unix:<path>	连接某个 ante serve --sock 宿主的套接字文件	属于他人；宿主的生命周期长于该连接
ws://<addr>	指向一个 WebSocket 宿主，但目前尚不可连接	属于他人

每种方式都产出同一个 Client；自身托管会话的进程也直接从其宿主获得同一类型 —— 进程内通道传递的正是远程编解码器所序列化的协议类型，因此客户端所能观察到的一切并无差别。

ConnectOptions 全部字段可选，且仅作用于 stdio 路径上拉起的宿主：executable（默认为 PATH 上的 ante）、追加在 serve --stdio 之后的 args、cwd，以及额外的 env。连接成功仅代表传输层成功 —— 管道已打开，或套接字已连上。协议没有握手问候，因此第一个 op 的回复才是存活性检查。

// 连接他人正在运行的宿主
let client = connect("unix:/tmp/ante.sock".parse()?, ConnectOptions::default()).await?;

该 crate 的 claude 模块与 Ante 协议无关：它用于将 Claude Code 作为子进程驱动。

服务模式与无头模式的区别

	无头模式（Headless）	服务模式（Server）
生命周期	执行单次提示词后退出	长寿命常驻，支持多轮持续交互
输入方式	CLI 参数或 stdin 管道	结构化 JSONL 操作指令
输出形式	格式化文本（minimal/human/json）	原始协议事件流（JSONL）
传输层	无	Stdio（默认）、Unix 套接字 (--sock) 或 WebSocket (--ws)
会话管理	隐式创建 —— 单次调用对应单会话	显式声明 —— 客户端发送 StartSession
工具审批	自动批准（默认隐式 yolo）	客户端必须主动响应 TurnPause 事件

命令行参数参考

参数标识	说明
--stdio	通过 stdin/stdout 提供 JSONL 协议服务（默认）
--sock [PATH]	通过 Unix 域套接字提供协议服务（默认为 Ante 主目录下的 run/serve.sock）
--ws <ADDR>	在本地回环地址上通过 WebSocket 提供协议服务
--offline-model <PATH>	自动使用指定的 GGUF 模型拉起本地 llama-server，并将其作为 local 提供商注册给所有接入客户端

备注

--prompt 参数不能与 ante serve 同时使用。请通过 UserInput 操作指令传递提示词。