AgentAPI

通过 HTTP API 控制 Claude Code、Amazon Q、Opencode、Goose、Aider、Gemini、GitHub Copilot、Sourcegraph Amp、Codex、Auggie 和 Cursor CLI。

您可以使用 AgentAPI：

• 构建统一的编码代理聊天界面
• 作为 MCP 服务器中的后端，让一个代理控制另一个编码代理
• 创建一个向代理提交拉取请求评审的工具
• 以及更多！

快速入门

1. 安装 agentapi：

   OS=$(uname -s | tr "[:upper:]" "[:lower:]");
   ARCH=$(uname -m | sed "s/x86_64/amd64/;s/aarch64/arm64/");
   curl -fsSL "https://github.com/coder/agentapi/releases/latest/download/agentapi-${OS}-${ARCH}" -o agentapi && chmod +x agentapi
   

   或者，您也可以从 发布页面 下载最新版本的二进制文件。

2. 验证安装：

   agentapi --help
   

   在 macOS 上，如果系统提示无法验证该二进制文件，请前往“系统设置 -> 隐私与安全性”，点击“仍要打开”，然后再次运行该命令。

3. 启动 Claude Code 服务器（假设您的系统已安装 claude 并且它在 PATH 中）：

   agentapi server -- claude
   

   如果您收到错误提示说 claude 不在 PATH 中，但您可以在终端中直接运行它，请尝试运行 which claude 获取完整路径，并使用该路径代替。

4. 向代理发送消息：

   curl -X POST localhost:3284/message \
     -H "Content-Type: application/json" \
     -d '{"content": "你好，代理！", "type": "user"}'
   

5. 获取对话历史：

   curl localhost:3284/messages
   

6. 在 http://localhost:3284/chat 尝试使用聊天网页界面。

CLI 命令

agentapi server

运行一个 HTTP 服务器，让您能够控制代理。如果您想以附加参数启动代理，请在 -- 标志后传递完整的代理命令。

agentapi server -- claude --allowedTools "Bash(git*) Edit Replace"

您也可以使用 agentapi 来运行 Aider 和 Goose 代理：

agentapi server -- aider --model sonnet --api-key anthropic=sk-ant-apio3-XXX
agentapi server -- goose

[!NOTE] 使用 Claude、Codex、Opencode、Copilot、Gemini、Amp 或 CursorCLI 时，务必明确指定代理类型（例如：agentapi server -- type=codex -- codex），否则消息格式可能会出错。

OpenAPI 模式已在 openapi.json 中提供。

默认情况下，服务器在端口 3284 上运行。此外，服务器还在 http://localhost:3284/openapi.json 上公开相同的 OpenAPI 模式，并在 http://localhost:3284/docs 上提供可用端点的文档 UI。

共有 4 个端点：

• GET /messages - 返回与代理对话的所有消息列表
• POST /message - 向代理发送消息。当返回 200 响应时，AgentAPI 已检测到代理开始处理该消息
• GET /status - 返回代理的当前状态，即“稳定”或“运行”
• GET /events - 代理发出的 SSE 事件流：消息和状态更新

允许的主机

默认情况下，服务器仅允许主机头设置为 localhost 的请求。如果您希望将 AgentAPI 托管在其他位置，可以通过使用 AGENTAPI_ALLOWED_HOSTS 环境变量或 --allowed-hosts 标志来更改此设置。主机必须仅为域名（不含端口）；服务器在授权时会忽略传入请求中的端口部分。

要允许来自任何主机的请求，可将允许的主机设为 *。

agentapi server -- allowed-hosts '*' -- claude

要允许特定主机，可使用：

agentapi server -- allowed-hosts 'example.com' -- claude

要指定多个主机，可在使用 --allowed-hosts 标志时使用逗号分隔的列表，或在使用 AGENTAPI_ALLOWED_HOSTS 环境变量时使用空格分隔的列表。

agentapi server -- allowed-hosts 'example.com,example.org' -- claude
# 或
AGENTAPI_ALLOWED_HOSTS='example.com example.org' agentapi server -- claude

允许的来源

默认情况下，服务器允许来自 http://localhost:3284、http://localhost:3000 和 http://localhost:3001 的 CORS 请求。如果您希望更改哪些来源可以向 AgentAPI 发起跨域请求，可通过使用 AGENTAPI_ALLOWED_ORIGINS 环境变量或 --allowed-origins 标志来更改此设置。

要允许来自任何来源的请求，可将允许的来源设为 *：

agentapi server -- allowed-origins '*' -- claude

要允许特定来源，可使用：

agentapi server -- allowed-origins 'https://example.com' -- claude

要指定多个来源，可在使用 --allowed-origins 标志时使用逗号分隔的列表，或在使用 AGENTAPI_ALLOWED_ORIGINS 环境变量时使用空格分隔的列表。来源必须包含协议（http:// 或 https://），并支持通配符（例如：https://*.example.com）：

agentapi server -- allowed-origins 'https://example.com,http://localhost:3000' -- claude
# 或
AGENTAPI_ALLOWED_ORIGINS='https://example.com http://localhost:3000' agentapi server -- claude

agentapi attach

附加到正在运行的代理的终端会话。

agentapi attach -- url localhost:3284

按 ctrl+c 可断开与会话的连接。

工作原理

AgentAPI 运行一个内存中的终端模拟器。它将 API 调用转换为相应的终端按键操作，并将代理的输出解析为单独的消息。

将终端输出拆分为消息

消息有两种类型：

• 用户消息：由用户发送给代理
• 代理消息：由代理发送给用户

为了从终端输出中解析出单独的消息，我们采取以下步骤：

1. 在发送任何用户消息之前，初始的终端输出被视为代理的第一条消息。
2. 当用户通过 API 发送消息时，会在发送任何按键操作之前拍摄一次终端快照。
3. 然后将用户消息提交给代理。从此时起，每当终端输出发生变化时，都会拍摄一个新的快照。将其与初始快照进行差异比较，任何出现在初始内容下方的新文本都被视为代理的下一条消息。
4. 如果在发送新用户消息之前终端输出再次发生变化，则代理消息会被更新。

这样，我们就能够将终端输出拆分为一系列消息。

从代理消息中移除 TUI 元素

每条代理消息都包含一些对最终用户无用的额外内容：

• 消息开头的用户输入。编码代理通常会将用户的输入回显给用户，以便在终端中可见。
• 消息末尾的输入框。用户通常在此处输入内容。

AgentAPI 会自动移除这些内容。

• 对于用户输入，我们会删除包含用户上一条消息文本的行。
• 对于输入框，我们会查找消息末尾包含常见 TUI 元素的行，例如 > 或 ------。

当 Claude Code、Goose、Aider 或 Codex 更新其 TUI 时会发生什么？

将终端输出拆分为一系列消息的方式仍应有效，因为这并不依赖于 TUI 的结构。不过，移除额外内容的逻辑可能需要更新，以适应新的元素。AgentAPI 仍然可以使用，但某些额外的 TUI 元素可能会在代理消息中显现出来。

路线图

在收到反馈之前，我们正在考虑以下功能：

• 支持 MCP 协议
• 支持 Agent2Agent 协议

长期愿景

短期内，AgentAPI 解决了如何通过编程方式控制编码代理的问题。随着时间推移，我们希望各大代理厂商能够发布正式的 SDK。届时，人们可能会问：AgentAPI 是否还有必要？我们认为，这取决于代理厂商是否决定采用统一的 API 标准，还是各自坚持专有格式。

如果是前者，我们将弃用 AgentAPI，转而使用官方 SDK；如果是后者，我们的目标将是让 AgentAPI 成为一个通用适配器，用于控制任何编码代理，从而使开发者在使用 AgentAPI 时能够在不同代理之间切换，而无需修改代码。

AgentAPI 快速上手指南

环境准备

• 系统要求：支持 Linux、macOS 和 Windows（通过 WSL）。
• 前置依赖：
  • 安装好你希望控制的代码代理工具，如 claude、aider、goose 等，并确保其在系统 PATH 中可用。
  • 安装 curl 和 chmod 工具（Linux/macOS 系统通常自带）。

---

安装步骤

1. 下载并安装 agentapi：

   OS=$(uname -s | tr "[:upper:]" "[:lower:]");
   ARCH=$(uname -m | sed "s/x86_64/amd64/;s/aarch64/arm64/");
   curl -fsSL "https://github.com/coder/agentapi/releases/latest/download/agentapi-${OS}-${ARCH}" -o agentapi && chmod +x agentapi
   

   或者从 GitHub 发布页面 手动下载最新版本的二进制文件。

2. 验证安装是否成功：

   agentapi --help
   

   如果你在 macOS 上遇到系统无法验证二进制文件的问题，请前往 系统设置 -> 隐私与安全性，点击“仍要打开”，然后重新运行命令。

---

基本使用

启动一个代理服务（以 Claude Code 为例）

agentapi server -- claude

如果提示找不到 claude，请先用 which claude 查看完整路径，再替换为实际路径。

向代理发送消息

curl -X POST localhost:3284/message \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, agent!", "type": "user"}'

获取对话历史记录

curl localhost:3284/messages

使用 Web 界面聊天

打开浏览器访问：

http://localhost:3284/chat

---

📌 提示：你可以通过 agentapi server --help 查看更多参数选项，例如指定允许的主机、端口、代理类型等。