@agentauto/agent-gateway

v1.0.10

Published

2 months ago

Standalone Agent Gateway for AionUI remote ACP sessions (OpenCode, Claude Code, Flowise, LangGraph)

0High
0Medium
0Low

senro

@aionui/agent-gateway

独立部署的 Agent Gateway，把不同执行后端（OpenCode / Claude Code / Flowise / LangGraph）统一封装成一个 WebSocket 服务，供 AionUI 或其他客户端远程接入。

功能概览

WebSocket 命令入口：/ws
健康检查接口：/healthz
四种 runtime：opencode / claude-code / flowise / langgraph
远程工作目录 workspace 支持，并受 allowedRoots 白名单限制
Token 鉴权（客户端通过 ?token=... 传入）
远程工作空间文件读写、增删改、目录浏览
会话空闲回收、客户端断开自动清理
模型切换、运行时配置切换、权限确认透传

一个进程 = 一个 runtime = 一个端口

多个 runtime 不能共用同一个端口。

Gateway 启动时根据 --runtime 参数实例化唯一一个 SessionManager，整个进程在该端口上只服务这一种后端（见 index.ts:34-39）。

如果需要在同一台服务器上同时提供 OpenCode、Claude Code、Flowise、LangGraph 四种后端，请启动 4 个 Gateway 进程，分别监听不同端口，例如：

| Runtime | 端口 | 说明 | | ----------- | ----- | --------------------------------- | | opencode | 18790 | 本地 opencode acp 子进程 | | claude-code | 18791 | 本地 claude-agent-acp(ACP 适配器) | | flowise | 18792 | 远程 Flowise HTTP/SSE | | langgraph | 18793 | 远程 LangGraph HTTP/SSE |

AionUI 客户端在添加远程 Agent 时，分别填写对应端口即可。

安装

pnpm install
pnpm build

或全局安装发布包：

pnpm dlx @agentauto/agent-gateway --help

启动方式（按 runtime 分类）

所有示例都假设：

鉴权 token：your-token
允许的远程工作目录：/srv/projects

客户端连接地址统一为：ws://host:port/ws?token=your-token

1. OpenCode runtime（默认）

后端是本地的 opencode 二进制，Gateway 通过 opencode acp 拉起子进程，使用 ACP-over-stdio 协议通信。

前置依赖： Gateway 所在机器已安装并能直接运行 opencode。

# 开发模式
pnpm dev -- \
  --runtime opencode \
  --port 18790 \
  --token your-token \
  --allowed-roots /srv/projects

# 生产模式（构建后）
pnpm start -- \
  --runtime opencode \
  --port 18790 \
  --token your-token \
  --allowed-roots /srv/projects

# 全局命令
pnpm dlx @agentauto/agent-gateway \
  --runtime opencode \
  --port 18790 \
  --token your-token \
  --allowed-roots /srv/projects

如需自定义启动命令或参数：

pnpm start -- \
  --runtime opencode \
  --opencode-command /usr/local/bin/opencode \
  --opencode-args acp,--verbose \
  --port 18790 \
  --token your-token \
  --allowed-roots /srv/projects

2. Claude Code runtime

后端是 ACP 适配器 @zed-industries/claude-agent-acp，它内部封装了 @anthropic-ai/claude-agent-sdk 并暴露 ACP-over-stdio 接口。协议层与 OpenCode 完全相同，区别只在 spawn 的命令换成 claude-agent-acp，并在 session/new 上额外携带 _meta.claudeCode.options.resume 用于恢复会话（见 src/gateway-claude-code/sessionManager.ts:30-78）。

注意：Anthropic 官方的 claude CLI 本身不支持 ACP，没有 --experimental-acp 这个 flag。必须使用上面这个独立的适配器包。AionUI 桌面端的本地 Claude Code ACP 集成走的是同一个包，所以在同一台机器上一份安装即可同时供桌面和 Gateway 使用（见 src/common/types/acpTypes.ts:41-42）。

前置依赖：

Gateway 所在机器全局安装 @zed-industries/claude-agent-acp（提供 claude-agent-acp 命令）
已设置 ANTHROPIC_API_KEY 环境变量，或本机已经登录过 Claude（适配器会复用 Claude Code SDK 的认证逻辑）

npm i -g @zed-industries/claude-agent-acp

pnpm start -- \
  --runtime claude-code \
  --port 18791 \
  --token your-token \
  --allowed-roots /srv/projects

自定义命令或参数（例如指向某个绝对路径或测试新版本）：

pnpm start -- \
  --runtime claude-code \
  --claude-code-command /usr/local/bin/claude-agent-acp \
  --port 18791 \
  --token your-token \
  --allowed-roots /srv/projects

3. Flowise runtime

后端是远程 Flowise 服务。Gateway 不会拉起任何子进程，而是把客户端消息转成 HTTP/SSE 请求发给 Flowise 的 prediction 接口，并把流式结果转成 ACP 风格事件回推给客户端。

前置依赖：

一个可访问的 Flowise 实例
一个已经发布的 Flowise workflow（chatflow）id
（可选）Flowise 的 Authorization 头

可以在启动时通过 --flowise-* 参数提供默认值，AionUI 客户端在 create_session 时也可以在 payload.flowise 中按会话覆盖。

pnpm start -- \
  --runtime flowise \
  --port 18792 \
  --token your-token \
  --allowed-roots /srv/projects \
  --flowise-base-url https://flowise.example.com \
  --flowise-workflow-id 1f2e3d4c-5b6a-7890-abcd-ef0123456789 \
  --flowise-authorization "Bearer sk-xxxxxxxx"

Flowise runtime 仍需要 --allowed-roots：工作空间面板的文件读写仍发生在 Gateway 所在机器上。

4. LangGraph runtime

当前 LanggraphSessionManager 是 FlowiseSessionManager 的薄子类（见 src/gateway-langgraph/sessionManager.ts），协议与启动参数与 Flowise 完全一致，区别只在客户端侧的标签：

pnpm start -- \
  --runtime langgraph \
  --port 18793 \
  --token your-token \
  --allowed-roots /srv/projects \
  --flowise-base-url https://langgraph.example.com \
  --flowise-workflow-id your-graph-id

CLI 参数

通用参数：

| 参数 | 默认值 | 说明 | | ---------------------- | ---------- | ---------------------------------------------------- | | --host | 0.0.0.0 | 监听地址 | | --port | 18790 | 监听端口 | | --runtime | opencode | opencode / claude-code / flowise / langgraph | | --token | 无 | WS 鉴权 token，客户端 ?token=... | | --allowed-roots | 无 | 工作目录白名单，逗号分隔的绝对路径列表 | | --max-sessions | 30 | 最大并发会话数 | | --idle-timeout-ms | 1800000 | 会话空闲回收毫秒数（30 分钟） | | --request-timeout-ms | 300000 | RPC 请求超时毫秒数（5 分钟） |

OpenCode runtime 专用：

| 参数 | 默认值 | 说明 | | -------------------- | ---------- | ------------------- | | --opencode-command | opencode | opencode 可执行文件 | | --opencode-args | acp | 启动参数，逗号分隔 |

Claude Code runtime 专用：

| 参数 | 默认值 | 说明 | | ----------------------- | ------------------ | -------------------------------------- | | --claude-code-command | claude-agent-acp | ACP 适配器可执行文件 | | --claude-code-args | 无 | 启动参数，逗号分隔（适配器一般不需要） |

Flowise / LangGraph runtime 专用：

| 参数 | 说明 | | ------------------------- | ------------------------------------------------- | | --flowise-base-url | Flowise / LangGraph API base URL | | --flowise-workflow-id | 默认 workflow / chatflow id | | --flowise-authorization | 默认 Authorization 请求头（例如 Bearer sk-xxx） |

环境变量

每个 CLI 参数都有同名环境变量；CLI 参数优先级更高，会覆盖环境变量。

AGENT_GATEWAY_HOST
AGENT_GATEWAY_PORT
AGENT_GATEWAY_RUNTIME
AGENT_GATEWAY_TOKEN
AGENT_GATEWAY_ALLOWED_ROOTS
AGENT_GATEWAY_MAX_SESSIONS
AGENT_GATEWAY_IDLE_TIMEOUT_MS
AGENT_GATEWAY_REQUEST_TIMEOUT_MS
AGENT_GATEWAY_OPENCODE_COMMAND
AGENT_GATEWAY_OPENCODE_ARGS
AGENT_GATEWAY_CLAUDE_CODE_COMMAND
AGENT_GATEWAY_CLAUDE_CODE_ARGS
AGENT_GATEWAY_FLOWISE_BASE_URL
AGENT_GATEWAY_FLOWISE_WORKFLOW_ID
AGENT_GATEWAY_FLOWISE_AUTHORIZATION

示例（systemd / docker-compose 中常用）：

export AGENT_GATEWAY_RUNTIME=claude-code
export AGENT_GATEWAY_PORT=18791
export AGENT_GATEWAY_TOKEN=your-token
export AGENT_GATEWAY_ALLOWED_ROOTS=/srv/projects,/data/workspaces
node dist/cli.js

WebSocket 协议

连接地址：

ws://host:port/ws?token=your-token

客户端请求格式：

{
  "action": "create_session",
  "requestId": "req-1",
  "payload": {
    "workspace": "/srv/projects/demo-repo"
  }
}

支持的 action：

会话与对话：

create_session — 新建会话，payload.workspace 必须落在 allowedRoots 内
send_message — 发送一轮提问；服务端立刻返回 accepted，真正的流式输出走 event
set_model — 切换模型（仅 ACP runtime 有效）
set_config_option — 切换运行时配置项（仅 ACP runtime 有效）
confirm_permission — 应答工具调用权限请求
stop_session — 终止指定会话
list_sessions — 列出当前进程内的会话

工作空间（所有 runtime 都支持，操作目标始终是 Gateway 本机的 workspace 目录）：

list_workspace — 列目录
read_file — 读文件
write_file — 写文件
create_entry — 创建文件 / 目录
rename_entry — 重命名 / 移动
delete_entry — 删除（可 recursive）

服务端响应格式：

{
  "type": "response",
  "requestId": "req-1",
  "success": true,
  "data": {
    "sessionId": "gateway-session-id"
  }
}

服务端事件格式（流式输出、权限请求、工作空间变更等）：

{
  "type": "event",
  "sessionId": "gateway-session-id",
  "event": {
    "type": "acp_message",
    "payload": {}
  }
}

常见事件 type：

status — 会话状态变化（starting / ready / closed …）
acp_message — 模型流式消息块
permission_request — 工具调用前的权限请求
stream_end — 一轮对话结束（含可选 error）
workspace_changed — 工作空间文件变化
stderr — 后端进程的 stderr 输出（调试用）

AionUI 客户端配置样例

在 AionUI 中，每个远程后端对应一个「自定义 ACP 代理（Custom ACP Agent）」。在 设置 → 模型与代理 → 自定义 ACP 代理 → 添加 → 高级 (JSON) 里粘贴下面的配置即可。

通用字段说明：

| 字段 | 说明 | | -------------------------- | -------------------------------------------------------------------------------------------- | | defaultCliPath | 用于在 UI 上区分后端类型；远程模式下不会真正执行，建议填运行时名（opencode / claude 等） | | enabled | 是否启用 | | env | 注入到子进程的环境变量；远程模式下保持 {} 即可 | | gateway.url | Gateway 的 WebSocket 地址，必须以 ws:// 或 wss:// 开头并以 /ws 结尾 | | gateway.token | 与 Gateway --token 保持一致 | | gateway.workspace | 远程会话的工作目录，必须落在 Gateway --allowed-roots 内 | | gateway.requestTimeoutMs | RPC 超时（毫秒），建议 ≥ Gateway 端的 --request-timeout-ms | | gateway.upstream | 仅 Flowise / LangGraph 需要，按会话覆盖远端 base URL / workflow / Authorization 等 |

1. OpenCode runtime 配置样例

{
  "defaultCliPath": "opencode",
  "enabled": true,
  "env": {},
  "gateway": {
    "url": "ws://127.0.0.1:18790/ws",
    "token": "your-token",
    "workspace": "/srv/projects/demo-repo",
    "requestTimeoutMs": 300000
  }
}

2. Claude Code runtime 配置样例

{
  "defaultCliPath": "claude",
  "enabled": true,
  "env": {},
  "gateway": {
    "url": "ws://127.0.0.1:18791/ws",
    "token": "your-token",
    "workspace": "/srv/projects/demo-repo",
    "requestTimeoutMs": 300000
  }
}

3. Flowise runtime 配置样例

{
  "defaultCliPath": "flowise",
  "enabled": true,
  "env": {},
  "gateway": {
    "url": "ws://127.0.0.1:18792/ws",
    "token": "your-token",
    "workspace": "/srv/projects/demo-repo",
    "requestTimeoutMs": 600000,
    "upstream": {
      "baseUrl": "https://flowise.example.com",
      "workflowId": "1f2e3d4c-5b6a-7890-abcd-ef0123456789",
      "authorization": "Bearer sk-xxxxxxxx",
      "streaming": true,
      "passWorkspace": true,
      "passSessionId": true,
      "runtimeEmbedUrl": "https://flowise.example.com/chatbot/1f2e3d4c-5b6a-7890-abcd-ef0123456789"
    }
  }
}

upstream 中的字段会按会话覆盖 Gateway 启动时的 --flowise-* 默认值。如果 Gateway 已经通过 CLI 配好默认 workflow，这里只需保留必要的差异即可。

4. LangGraph runtime 配置样例

LangGraph 当前协议与 Flowise 共用，区别只在 defaultCliPath 标签：

{
  "defaultCliPath": "langgraph",
  "enabled": true,
  "env": {},
  "gateway": {
    "url": "ws://127.0.0.1:18793/ws",
    "token": "your-token",
    "workspace": "/srv/projects/demo-repo",
    "requestTimeoutMs": 600000,
    "upstream": {
      "baseUrl": "https://langgraph.example.com",
      "workflowId": "your-graph-id",
      "authorization": "Bearer sk-xxxxxxxx",
      "streaming": true,
      "passWorkspace": true,
      "passSessionId": true
    }
  }
}

远程访问时把 127.0.0.1 换成 Gateway 公网地址，并强烈建议在 Nginx / Caddy 前面套一层 wss:// + 真实证书。

健康检查

curl http://host:port/healthz
# {"ok":true}

部署

更多 systemd / Docker / Nginx 反向代理示例，见 DEPLOY.md。