Remote Agent Server

English · MIT License · Node.js 22 · macOS / Linux

把 Claude Code、Codex 和 Hermes 接入你的工单、运维平台和内部业务系统。

在自己的机器上部署，让业务系统通过 HTTP API 派发任务，也可以从 Web 管理台直接调用熟悉的命令行 Agent。Remote Agent Server 负责排队、工作区、会话和执行记录；你的系统通过查询、SSE 或签名 Webhook 取得进度与结果。

项目环境提前准备仓库和依赖，每个 Session 使用独立的写时复制 Workspace。同一会话可以继续追问，调用方断开连接也不影响已提交任务的执行。

除了执行任务，还可以按 Agent 选择暴露的 MCP 工具，减少无关工具干扰；从 Git 仓库安装和更新 Skills，预览文件变化，再按 Agent 应用版本或回退，方便维护团队规范和业务处理流程。

服务通过 acpx 和 Agent Client Protocol（ACP） 与 Agent 通信，通过 MCP 接入外部工具，并提供执行器扩展与模型策略。单个 Fastify 进程配合 SQLite WAL，无需额外部署数据库或消息队列。

界面演示 · 安装并启动 · 完成第一条任务 · HTTP / Webhook 接入 · 主要功能 · 执行模型 · 配置 · 部署文档

业务系统接入演示

以工单排查为例：业务系统通过 Task API 提交任务 → 查看状态与结果 → 打开关联会话继续处理。

真实管理台录屏，使用合成的示例工单、工具事件和固定回复，未调用真实模型。录屏展示接口与界面流程，不代表模型排查效果或执行耗时。查看 MP4 · 接入文档

<details> <summary>查看完整截图：调用入口、任务结果、会话记录</summary>

调用入口：查看 HTTP 接口、认证方式与参数，并在管理台试调。

任务结果：将业务请求、最终回复、执行轨迹和关联会话放在一起核对。

会话记录：查看消息和工具事件，在原有上下文中继续补充信息。

</details>

适用场景

| 你想做什么 | 如何使用 | | --- | --- | | 让工单或运维平台派发代码排查任务 | 通过 Task API 提交日志、说明或附件，用业务会话标识继续补充信息。 | | 在现有 Shell 脚本、CI/CD 或内部平台中调用 Agent | 用 curl 或任意 HTTP 客户端提交异步任务，保存 Task ID，轮询结果或接收回调。 | | 在浏览器里运行和继续 Agent 任务 | 用管理台准备项目环境、创建 Agent 和 Session，查看消息、工具调用与结果。 | | 将 PR / MR 事件交给审核 Agent | 配置 GitHub / GitLab Webhook 和事件筛选；结果可查询或回调，写回评论需另配工具与权限。 |

适合已经在使用 Agent CLI，希望把它接入长期运行的业务流程的开发者和团队。首次可以只在管理台跑通一个任务，再接入现有系统；原有的脚本、CI、审批和发布流程可以继续使用。

Provider 继续负责推理、工具使用和原生会话，业务审批、工单状态机与部署规则由调用方维护。代码和运行记录由你管理，调用模型时仍遵循所选 Provider 的认证、计费与数据传输方式。当前面向可信用户的单机部署；Workspace 提供文件副本隔离，不是容器或安全沙箱。详见安全边界。

主要功能

• 异步 Task API：外部系统通过 HTTP 提交任务，使用幂等键避免重复执行，并可查询、取消或继续多轮 Conversation。
• 可靠事件出口：支持增量 Event 查询、可续读 SSE 和签名 Webhook；断线不影响正在执行的 Task。
• 统一管理 Agent：集中配置 Provider、Agent 指令、项目环境、Skills 和 MCP。
• MCP 工具按需暴露：为每个 Agent 的 MCP 选择全部工具或仅所选工具，控制暴露给模型的工具清单；支持 HTTP、stdio 和从 Provider 系统配置导入。
• Skills 从 Git 安装与更新：从 Git 仓库或 marketplace 安装 Skills，预览文件变化，再按 Agent 应用新版本或回退；也保留本机发现和 ZIP 上传。
• 可复用项目环境：提前准备一个或多个 Git 仓库及依赖，Session 创建时无需重新安装。
• 隔离 Workspace：macOS 使用 APFS Clone，Linux 使用 Btrfs Snapshot，为每个 Session 快速创建写时复制环境。
• 多轮 Agent 对话：同一 Session 可以连续执行多个 Run，并在 Provider 支持时续接 ACP Session。
• 完整执行记录：在 SQLite 中保存用户消息、Agent 输出、工具调用、状态、错误和最终结果。
• 执行器扩展：发现 Codex 和 Claude Code 的系统插件与 Hook，由每个 Agent 单独选择，在运行时投影到它的 Provider Home。
• 模型策略：自动读取 Agent Core 通过 ACP 暴露的模型，可跟随 Core 默认模型、固定模型，或按 UTC 星期和 24 小时时间段为新 Run 选择模型。
• 运行、存储与并发控制：在管理台调整 Run 超时、空闲 Session 大文件保留期和三类服务并发，并可为单个 Agent 设置 Run 上限。
• 有头浏览器：Agent 可以运行在真实桌面会话中，不要求放入容器。
• GitHub / GitLab 事件接入：原生 Webhook 验证、事件筛选、筛选预览和接收记录；与通用 Task API 共用执行流程。
• 图片与文件任务：在管理台上传、拖入或粘贴附件，也可通过 API 提交图文或纯附件消息；内容理解取决于 Provider、模型和工具。
• 部署初始化与诊断：pnpm run init 生成配置，pnpm run doctor 验证原生 Workspace 操作，首次使用由页面引导。

执行模型

外部系统接入是项目的主要服务接口：

外部系统
   |
   v
接入端点（鉴权 / 参数映射 / 幂等）
   |
   v
Task -> Conversation -> Session -> 隔离 Workspace -> acpx/ACP -> Provider
   |                         |
   |                         +-> Skills / 执行器扩展 / MCP / 模型策略
   |
   +-> 状态查询 / Event 查询 / SSE / 签名 Webhook

管理人员也可以从 Web 界面直接创建 Session 和 Run：

项目环境 -> Agent -> Session -> Run -> acpx/ACP -> Provider
                         |
                         +-> 消息、工具调用、状态和结果

| 对象 | 作用 | | --- | --- | | 项目环境 | 保存一个或多个 Git 项目及准备完成的依赖，按版本发布。 | | Agent | 绑定 Provider、项目环境、Agent 指令、Skills、执行器扩展、MCP、模型策略和并发策略。 | | Session | 一个隔离的 Workspace，也是一段可继续的 Agent 对话。 | | Run | Session 中的一次输入和完整执行记录。 | | 接入端点 | 其他系统调用服务的认证入口，绑定一个 Agent。 | | Conversation | 外部系统的多轮业务会话，内部复用同一个 Session。 | | Task | 外部系统提交的一次异步请求，最终对应一个 Run。 |

运行要求

• Node.js 22（.nvmrc 是项目已验证版本）
• 通过 Corepack 使用 pnpm 10
• Git
• 至少安装并登录一个 Provider CLI
• macOS 使用 APFS；Linux 使用服务用户可操作的 Btrfs
• Linux 需要安装 btrfs-progs，且服务用户必须能实际执行 btrfs subvolume create/snapshot/delete
• 需要有头浏览器时，服务器必须有真实桌面或 X display

项目环境和 Session Workspace 使用 APFS Clone 或 Btrfs Snapshot 创建写时复制副本。服务不提供普通目录复制回退。新主机请先完成部署文档中的文件系统准备。

安装并启动

git clone https://github.com/ma-pony/remote-agent-server.git
cd remote-agent-server

nvm install
corepack enable
pnpm install --frozen-lockfile
pnpm run init
pnpm start

pnpm run init 自动生成随机 API_TOKEN 和权限为 0600 的 .env，创建数据目录，并实际验证工作区创建、克隆／快照、独立写入和清理。若进程环境已提供 API_TOKEN，则沿用该值。已有 .env 不会被覆盖，Token 不会被重新生成。命令只检查 Provider 可执行文件是否存在，不会登录或调用模型。

• macOS：默认使用 ~/Library/Application Support/remote-agent-server，通常可直接执行以上命令。
• Linux：默认使用 /srv/remote-agent。先按部署文档准备服务用户可写的 Btrfs 目录；也可在首次初始化时用 pnpm run init --root /你的Btrfs目录/remote-agent 指定一个根目录，无需分别填写四个存储路径。

检查失败时会提示原因，新安装不会写入 .env。修复目录权限或文件系统后重试即可；初始化不会格式化磁盘、修改挂载或使用普通目录复制回退。--root 只用于首次生成配置，已有安装继续使用原 .env 的路径。

服务自动读取当前工作目录的 .env，不再需要 source；已经设置的进程环境变量优先。文件按 dotenv 数据解析，不执行 Shell 命令，也不展开 $HOME、~ 或变量引用，手工填写存储路径时使用绝对路径。

以后检查安装状态：

pnpm run doctor

doctor 检查现有配置和工作区操作，清理探测文件，不创建或修改 .env，不运行真实 Agent。它也支持完全由进程环境提供配置的部署；目录检查通过不代表 Provider 已登录或模型可用。

pnpm start 会先构建服务端和 Web 管理台，再以生产模式启动。若直接执行构建后的 Node 入口但 Web 构建不完整，服务会明确报错退出。

检查服务：

curl --fail http://127.0.0.1:3000/api/health

打开 http://127.0.0.1:3000，从 .env 复制 API_TOKEN 的值到登录页。初始化命令和启动日志不会打印 Token，Web 界面只在当前浏览器会话中保存它。新生成的配置默认只监听 127.0.0.1；跨机器访问可通过 SSH 端口转发，或按部署文档配置监听地址和 TLS 反向代理。

首次进入后按页面提示完成 项目环境 → 智能体 → 会话。尚无可用环境时，页面会直接引导创建或查看环境；环境准备好后再创建 Agent。只需先配置一个 Provider，Skills、MCP 和外部接入可在首个任务跑通后按需添加。

手动配置与直接启动

也可以手动管理配置。在尚无 .env 的新安装中执行：

cp -n .env.example .env
chmod 0600 .env
openssl rand -hex 32

把生成的随机值填入 .env 的 API_TOKEN，并设置当前用户可写的绝对存储路径；macOS 使用 APFS，Linux 使用 Btrfs，项目环境与 Session 根目录必须位于同一文件系统。然后检查、构建并直接运行：

pnpm run doctor
pnpm build
NODE_ENV=production node dist/server/main.js

服务会自动读取 .env，无需执行 source。也可以完全通过 Shell 环境变量或 systemd EnvironmentFile 提供配置；已有进程变量优先。常驻服务的 LaunchAgent / systemd 示例见部署文档，全部变量见配置。

本地开发

初始化后直接运行：

pnpm dev

该命令会同时启动后端监听和 Vite 前端开发服务器。两者自动读取项目 .env 中的 PORT，进程环境中的 PORT 优先。Vite 默认位于 http://127.0.0.1:5173，并把 /api 和 /integration 自动代理到该后端端口；前端修改可热更新，无需重复构建或重启后端。

从零完成一次 Agent 执行

1. 准备 Provider

Provider CLI 必须由运行服务的同一个操作系统用户安装并登录。安装和认证方式以官方文档为准：

• Claude Code
• Codex CLI
• Hermes Agent

下面是命令参考，只执行所选 Provider 对应的命令：

claude auth login
codex login
claude auth status
codex login status
claude --version
codex --version
hermes --version

只需选择实际使用的 Provider，在运行服务的系统用户下完成认证和模型配置。

服务启动时读取登录 Shell 的 PATH，并合并当前 Node 目录和进程 PATH。每个 Agent 使用独立的 Provider Home。服务会从运行用户的 Provider Home 准备基础配置、认证与模型信息，不复制历史会话、日志和临时运行数据。Codex 和 Claude Code 的系统插件、Hook 与全局 MCP 只作为可选配置来源，不会被 Agent 隐式继承。

2. 创建项目环境

进入 项目环境 → 新建项目环境：

1. 添加 Agent 可能使用的一个或多个 Git 仓库。
2. 为每个仓库填写可选的准备命令，例如 pnpm install、bundle install 或 uv sync。
3. 点击 立即同步。
4. 等待当前版本变为 可用。

同步会在持久目录中构建新版本。所有仓库及准备命令成功后，新版本才会发布。系统每 3 小时检查一次远程仓库，也可以手动同步。已有 Session 保持原版本，新 Session 使用最新可用版本。Session 直接使用当前版本的 APFS Clone/Btrfs Snapshot，不重复执行清理或准备命令；旧 Session 在首次继续运行时仍会完成一次兼容修复。

项目包含 uv.lock 时，服务会在原准备命令前先执行 uv venv --relocatable .venv，之后项目原有的 uv sync 或 Make 命令会复用这个可迁移环境。服务器需要安装 uv >= 0.10.8；升级后需要重新同步项目环境，已有 .venv 不会自动转换。同步时会比较 uv.lock、pyproject.toml 和 .python-version：依赖未变只更新源码，依赖变化才清理并重新准备该项目。项目环境只保留当前 Workspace；Session 使用自己的 Btrfs 快照，不依赖旧项目环境 Workspace。

3. 创建 Agent

进入 Agent → 新建 Agent：

1. 选择 Claude Code 或 Codex 等 Provider。
2. 选择已经可用的项目环境。
3. 填写 Agent 的职责、代码规范和交付要求。
4. 保存后运行 运行检查，确认 Provider 和项目环境可用。

4. 创建 Session 并发送消息

进入 Session → 新建 Session，选择 Agent，并填写当前 Session 需要的 MCP 参数。系统从项目环境当前版本创建独立 Workspace。

进入 Session 后发送消息。系统创建 Run 并排队执行，页面会展示 Agent 输出、工具调用、执行状态、错误和最终结果。

在同一 Session 中继续发送消息会创建新的 Run，并在 Provider 支持时续接同一个 ACP Session。每个 Run 仍保留独立的输入、事件和结果。

第一次可以用一个容易核对结果的任务：

阅读当前项目，说明目录结构、启动方式和测试命令。先不要修改文件。

Agent 配置与运行策略

Agent 页面还可以配置：

• Skills：从 Git 仓库安装、预览更新和回退版本，也可发现本机 Skill 或上传 ZIP；为每个 Agent 单独选择启用的 Skill 和版本。
• 执行器扩展：查看当前 Provider 系统配置中发现的插件和 Hook，并为这个 Agent 启用需要的项。
• MCP：添加 HTTP 或 stdio MCP，检查连接并选择暴露的工具；支持固定值、Session 参数和运行时参数，也可将 Codex 或 Claude Code 的系统全局 MCP 导入当前 Agent。
• 运行并发策略：默认继承系统 Run 并发，也可以设置当前 Agent 的独立上限；实际上限取两者较小值。
• 模型策略：模型列表来自当前 Agent Core，不允许手填未配置的模型。可以跟随 Core 默认模型、固定一个模型，或按 UTC 星期和 24 小时时间段切换；Core 未暴露模型列表时后两项不可用。

模型策略在 Run 离开队列、真正开始执行时解析，因此排队时间不会导致提前选错模型。切换复用同一个 Session 和 Provider 对话上下文，只更新 ACP model 配置；不会中断正在执行的 Run，下一次 Run 才使用新模型。固定或定时策略会在每个 Run 上记录实际解析出的模型，便于审计。

模型策略速查

进入 Agent → 目标 Agent → 设置 → 模型策略 配置：

| 模式 | 行为 | 适合场景 | | --- | --- | --- | | 跟随 Agent Core 默认模型 | 使用 Core 当前公开的默认模型。 | 由 Codex、Claude Code 等 Core 统一管理模型。 | | 固定模型 | 每个新 Run 都选择同一个模型。 | 一个 Agent 需要稳定使用指定模型。 | | 按 UTC 规则切换 | 同时命中星期和时间段时使用其模型，其他时间使用兜底模型。 | 工作日/周末使用不同模型，或按模型可用时段、成本和吞吐策略自动切换。 |

管理台按规则组配置：每组统一选择一个或多个 UTC 星期、一个模型和可选的 Run 并发上限，组内可添加多个 24 小时制 HH:mm 时间段，例如工作日 08:00–10:00 和 14:00–18:00 共用同一模型与并发。开始时间包含、结束时间不包含；结束早于开始时自动跨到下一 UTC 日，所选星期表示时间段的开始日。规则组重叠时配置靠前的优先。并发留空时继承 Agent 平时的并发策略，填写后覆盖 Agent 上限但仍不超过系统全局上限。页面提供“工作日 / 周末 / 每天”快捷选择，未命中的时间使用兜底模型和默认并发。保存时服务会重新读取 Core 模型目录，并拒绝已经不在目录中的模型。

策略修改只影响之后真正开始的 Run：正在执行的 Run 不切换，仍在队列中的 Run 会在获得执行槽位时按当时 UTC 时间解析。Session、Workspace 和 Provider 对话上下文都会继续复用。服务解析出明确模型时，Session 页面会在 Run 上展示它，管理 API 也会在 resolvedModel 字段中返回；完全跟随且 Core 未公开默认模型时，该字段为 null。接口配置格式与解析顺序见产品与架构：模型发现、策略与审计。

Skills、执行器扩展和 MCP 的变更从下一次 Run 生效。已有 Session 检测到配置变化后会刷新执行器连接；Provider 支持时，会继续原有 Provider Session 和对话上下文。

Skills：从 Git 安装和更新

把团队规范、业务处理流程和操作经验维护在 Git 仓库中，再为不同 Agent 选择需要的 Skills 和版本：

1. 进入 Agent → 目标 Agent → Skills → 管理 Git 来源，添加 GitHub、GitLab 或其他 Git 服务的 HTTPS/SSH 地址，可指定分支、标签、提交 SHA 和仓库子目录。
2. 来源同步完成后，在 Skills 列表中启用需要的项，安装到当前 Agent。
3. 仓库更新后手动刷新来源。可在“管理 Git 来源”中一次应用当前 Agent 的全部 Git Skill 更新，或逐项预览文件变化后应用；需要时可选择历史版本回退。批量应用会跳过本地已修改的 Skill，并显示每项失败结果。

版本预览先列出变化文件、大小和权限，点击文件的“查看差异”后才加载文本变更片段。每个文件的当前和目标内容分别支持最多 1 MiB 的 UTF-8 文本，差异最多显示 64 KiB，超出时明确提示截断；文件之间不共用预览额度。二进制、非 UTF-8 和超限文件分别说明原因，仍保留文件变化信息。预览期间内容发生变化时，需要重新点击“预览变更”。

支持普通 Skills 仓库、Claude 的 .claude-plugin/marketplace.json、Codex 的 .agents/plugins/marketplace.json，以及 plugin.json、.codex-plugin/plugin.json 和 .claude-plugin/plugin.json 中的 Skills 声明。marketplace 的本地目录和 Git 插件源会解析为完整包快照；不支持的条目会显示提示。导入只提供 Skills，不执行插件 Hook、MCP 或依赖安装命令。

手动刷新来源只发现新版本。已启用的 Agent 保持原版本，直到明确批量应用 Git 更新，或逐项预览文件变化后应用；也可以选择历史版本回退。同名上传 ZIP 可作为原 Skill 的新版本发布，发布后仍需单独应用。版本摘要覆盖整个包的文件内容和可执行权限，修改 scripts、references 也会被识别。重复启用已启用的 Skill 不会更新版本，本地副本有修改时会阻止覆盖。移除 Git 来源保留已启用副本和版本历史；不同 Agent 的选择互不影响。

每次 Run 使用自己的 Session 投影，运行中的任务保留原内容。Run 管理 API 的 skillsRevision 记录实际投影的摘要；升级前的历史 Run 为 null。来源管理及版本接口使用同一个管理 API Token，详见能力投影设计。

2026-09-14 的验收记录确认了真实 Git 来源导入和 Codex gpt-5.5 的读取、更新、回退及会话连续性。GitLab 实测覆盖仓库拉取；Claude Code 和 Hermes 的真实执行分别被上游模型权限和通道可用性阻塞，尚未完成验收。

已知运行时限制：部分 Provider 会把上游模型错误作为普通回复返回，同时报告运行完成。验收时需要检查实际回复和预期产物，不能只看 Run 状态。此错误状态传递问题尚未修复，排查方法见部署文档。

执行器扩展

执行器扩展遵循“发现 → Agent 选择 → 运行时投影”流程。在服务运行用户的 Codex 或 Claude Code 配置中安装新插件、添加 Hook 后，它们会出现在 Agent 的 执行器扩展 页面，默认不启用。启用的项只投影到当前 Agent。Hermes 目前不提供这项扩展管理能力。

Codex 插件按 Agent 发布为本地 marketplace 快照；选择与内容版本相同的 Session 共用插件缓存。默认情况下，同一 Agent 的 Session 也共用内置市场同步目录；显式启用 Codex rollout 压缩的 Session 保留独立 .tmp，使各自的压缩锁互不影响。插件选择变化在下一次 Run 生效；包文件变化在发现缓存刷新后生效（默认最多 30 秒）。已有 Session 的旧插件缓存与临时克隆在下一次准备运行目录时清理，空闲 Session Home 仍按原保留策略清