Remote Agent 部署与使用

Remote Agent 用于把 APIPIG 控制台创建的 Coding 任务分发到远程工作机，并在隔离工作目录中调用本机 Codex CLI。Agent 主动连接 Controller，不要求工作机开放入站端口。

工作链路

Web 管理端
    |
    v
APIPIG Controller
    |
    | 注册、心跳、长轮询、日志与结果上报
    v
Remote Agent
    |
    +-- git clone 到独立任务目录
    +-- Prompt 通过 stdin 传给 Codex
    +-- 上传 stdout / stderr
    +-- 上报结果与修改文件

Controller 不提供任意 Shell 执行接口。每个任务只会触发预定义的 Git 克隆、Codex 执行、Git 状态读取和任务停止操作。

部署前检查

项目	要求
Controller	已启用 Remote Agent 配置，Agent 可访问其 HTTP/HTTPS 地址
工作机	Windows、Linux 或 macOS，建议使用专用的普通用户
Git	已安装并可从 Agent 进程的 `PATH` 或配置的绝对路径执行
Codex CLI	已安装、已认证，且服务用户能执行 `codex exec`
仓库	只接受不含内嵌用户名和密码的 HTTPS Git URL
网络	Agent 能主动访问 Controller 和 Git 仓库；私有模型还需访问对应服务

非 root 运行

Linux Agent 启动时会检查当前用户，使用 root 运行将直接退出。生产环境应为 Agent 创建专用低权限用户。

配置 Controller

在 Controller 的 config.yaml 中增加：

remote-agent:
  registration-token: "替换为至少 32 位随机字符串"
  heartbeat-timeout-seconds: 90
  offline-check-cron: "* * * * *"
  command-poll-timeout-seconds: 25
  dispatch-lease-seconds: 30

已有部署也可以通过环境变量注入注册密钥：

export APIPIG_REMOTE_AGENT_REGISTRATION_TOKEN='替换为高强度随机字符串'

Windows PowerShell：

$env:APIPIG_REMOTE_AGENT_REGISTRATION_TOKEN = '替换为高强度随机字符串'

配置变更后重启 Controller。registration-token 是 Agent 首次注册和重启后重新注册使用的引导密钥，不能使用空值，也不应提交到代码仓库。

网络与反向代理

Agent 配置中的 controller-url 应填写 Controller 根地址，例如：

https://controller.example.com

不要填写 /v1 或 /v1/remote-agent，Agent 会自动追加 API 路径。反向代理需要允许以下接口，并将上游读取超时设置为大于长轮询时间：

POST /v1/remote-agent/register
POST /v1/remote-agent/heartbeat
GET  /v1/remote-agent/command/next
POST /v1/remote-agent/command/acknowledge
POST /v1/remote-agent/task/logs
POST /v1/remote-agent/task/result

Web 实时日志通过 POST /v1/ai-applications/remote-agent/task/log/stream 使用 SSE。经过 Nginx 等反向代理时，应对该接口关闭响应缓冲并配置足够长的读取超时。

安装和认证 Codex CLI

Codex CLI 必须安装在工作机上，并且要以运行 Agent 的同一个操作系统用户完成认证。Agent 启动 Codex 子进程时会继承自身环境，并读取该用户的 Codex 配置和认证信息。

先确认可执行文件：

command -v codex
codex --version
codex login status

可以使用设备认证：

codex login --device-auth

或从 stdin 写入 API Key：

printenv OPENAI_API_KEY | codex login --with-api-key

认证后，用与 Agent 一致的非交互方式进行冒烟测试：

printf '只输出 OK，不修改文件\n' | \
  codex exec --sandbox workspace-write --skip-git-repo-check --color never -

Windows 可执行文件

Agent 使用 Go 直接启动 Codex，不会经过 PowerShell。通过 npm 或 Node 版本管理器安装 Codex 后，优先把 codex-command 配置为可直接执行的 codex.exe 绝对路径，避免只解析到 codex.ps1。

Agent 配置

Linux 推荐配置：

controller-url: https://controller.example.com
registration-token: "与 Controller 完全相同的注册密钥"
agent-key: workstation-01
name: 开发工作机-01

workspace-root: /var/lib/apipig-agent/workspaces

codex-command: /usr/local/bin/codex
codex-args:
  - exec
  - --sandbox
  - workspace-write
  - --skip-git-repo-check
  - --color
  - never
  - "-"

git-command: /usr/bin/git
poll-wait-seconds: 25
request-timeout-seconds: 40
log-file: /var/log/apipig-agent/remote-agent.log

配置字段说明：

字段	必填	说明
`controller-url`	是	Controller 根地址，只能是 HTTP/HTTPS，不带 `/v1`
`registration-token`	是	与 Controller 相同的注册引导密钥
`agent-key`	建议	节点稳定且唯一的标识；为空时使用 hostname
`name`	建议	控制台显示名称；为空时使用 hostname
`workspace-root`	否	每个任务的隔离工作区根目录
`codex-command`	否	Codex 可执行文件，默认 `codex`
`codex-args`	否	Codex 固定参数，最后的 `-` 表示从 stdin 读取 Prompt
`git-command`	否	Git 可执行文件，默认 `git`
`poll-wait-seconds`	否	命令长轮询时间，最大 25 秒
`request-timeout-seconds`	否	HTTP 请求超时，必须大于轮询时间
`log-file`	否	Agent 自身运行日志文件

workspace-write 只允许 Codex 在任务工作区中写入。不要使用 --dangerously-bypass-approvals-and-sandbox，除非工作机已经由外部强隔离且风险经过明确评估。

Windows 配置示例：

controller-url: https://controller.example.com
registration-token: "与 Controller 完全相同的注册密钥"
agent-key: windows-workstation-01
name: Windows 开发工作机-01
workspace-root: D:/apipig-agent/workspaces
codex-command: C:/Users/codex-agent/.nvmd/bin/codex.exe
codex-args:
  - exec
  - --sandbox
  - workspace-write
  - --skip-git-repo-check
  - --color
  - never
  - "-"
git-command: C:/Program Files/Git/cmd/git.exe
poll-wait-seconds: 25
request-timeout-seconds: 40
log-file: D:/apipig-agent/logs/remote-agent.log

Linux systemd 部署

创建服务用户和目录

sudo useradd --system --create-home \
  --home-dir /home/codex-agent \
  --shell /usr/sbin/nologin codex-agent

sudo install -d -o root -g root -m 0755 /opt/apipig-agent
sudo install -d -o root -g codex-agent -m 0750 /etc/apipig-agent
sudo install -d -o codex-agent -g codex-agent -m 0750 \
  /var/lib/apipig-agent/workspaces \
  /var/log/apipig-agent \
  /home/codex-agent/.codex

安装二进制和配置：

sudo install -o root -g root -m 0755 \
  remote-agent-linux-amd64 /opt/apipig-agent/remote-agent

sudo install -o root -g codex-agent -m 0640 \
  remote-agent.yaml /etc/apipig-agent/remote-agent.yaml

以服务用户验证 Git、Codex 和认证状态：

sudo -u codex-agent -H /usr/bin/git --version
sudo -u codex-agent -H /usr/local/bin/codex --version
sudo -u codex-agent -H /usr/local/bin/codex login status

如果尚未认证，可运行：

sudo -u codex-agent -H /usr/local/bin/codex login --device-auth

创建 systemd 服务

保存为 /etc/systemd/system/apipig-agent.service：

[Unit]
Description=APIPIG Remote Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=codex-agent
Group=codex-agent
WorkingDirectory=/opt/apipig-agent
Environment=HOME=/home/codex-agent
Environment=CODEX_HOME=/home/codex-agent/.codex
EnvironmentFile=-/etc/apipig-agent/codex.env
ExecStart=/opt/apipig-agent/remote-agent -c /etc/apipig-agent/remote-agent.yaml
Restart=always
RestartSec=5
UMask=0077
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/var/lib/apipig-agent /var/log/apipig-agent /home/codex-agent/.codex

[Install]
WantedBy=multi-user.target

启动并查看状态：

sudo systemctl daemon-reload
sudo systemctl enable --now apipig-agent
sudo systemctl status apipig-agent
sudo journalctl -u apipig-agent -f

正常注册时日志中会出现：

registered agent 开发工作机-01 as <agent-id>

Windows 部署

创建专用的标准 Windows 用户并以该用户安装、认证 Codex CLI。
将程序和配置放到 D:\apipig-agent。
确认该用户对 workspace 和 logs 目录具有读写权限。
在该用户会话中先进行前台测试：

cd D:\apipig-agent
where.exe git
where.exe codex
.\remote-agent.exe -c .\remote-agent.yaml

前台验证完成后，可使用 Windows 任务计划程序以该标准用户在系统启动时运行：

程序：D:\apipig-agent\remote-agent.exe
参数：-c D:\apipig-agent\remote-agent.yaml
起始于：D:\apipig-agent

不要配置为 SYSTEM 或管理员账户，否则 Codex 的用户认证信息、Git 凭据和实际运行环境可能与手工验证时不一致。

私有 Git 仓库

任务只接受 HTTPS 仓库地址，并禁止在 URL 中携带用户名或密码：

https://git.example.com/team/project.git

私有仓库认证应提前配置在 Agent 服务用户环境中，例如使用操作系统 Git Credential Manager、只读部署令牌对应的 credential helper，或受权限保护的 .netrc。正式启动前应以服务用户验证：

sudo -u codex-agent -H \
  git ls-remote https://git.example.com/team/project.git HEAD

凭据必须支持非交互调用，且不要写入 Agent YAML、任务 Prompt 或仓库 URL。

创建和查看任务

登录 APIPIG 管理端。
打开 AI 应用 → Remote Agent → Agent 节点。
确认目标节点状态为“在线”。
点击“创建任务”，选择 Agent，填写 HTTPS Git 地址、仓库内相对工作目录和 Prompt。
提交后进入任务详情，查看命令状态、stdout/stderr 实时日志、结果和修改文件。

Agent 实际执行过程等价于：

git clone --depth 1 <repository-url> <workspace-root>/<task-id>
cd <workspace-root>/<task-id>/<working-dir>
codex exec --sandbox workspace-write --skip-git-repo-check --color never -

Prompt 通过 stdin 传入，不会出现在操作系统进程参数中。working-dir 必须是仓库内已经存在的规范相对路径，不能使用绝对路径或 .. 跳出工作区。

运行行为

每个任务使用 <workspace-root>/<task-id> 独立目录。
执行任务前会删除同 ID 的旧目录并重新浅克隆仓库。
Git clone 和 Codex 的 stdout/stderr 会实时上传到 Controller。
日志按序号上传，断线重试不会重复写入同一条日志。
Codex 结束后，Agent 使用 git status --porcelain 收集修改文件。
Agent 会先刷新剩余日志，再上报任务最终结果。
Controller 重启后，超出租约的未确认命令可以重新分发。
Agent 进程异常重启后，运行中的任务会重新进入等待状态，从全新 workspace 再次执行，并从已持久化日志的下一个序号继续上传。
取消运行中任务时，Controller 会下发停止任务指令并取消 Codex 进程上下文。

升级 Agent

Agent 的长期配置主要是 YAML、Codex 用户认证和 Git 凭据，程序本身可以原地替换：

sudo systemctl stop apipig-agent
sudo install -o root -g root -m 0755 \
  remote-agent-linux-amd64 /opt/apipig-agent/remote-agent
sudo systemctl start apipig-agent
sudo journalctl -u apipig-agent -n 50 --no-pager

升级前不要删除 workspace 目录。正在执行的任务应先在控制台取消或等待完成。

故障排查

现象	检查项
`registration-token is required`	Agent YAML 未填写注册密钥
持续出现 `registration failed`	Controller 密钥不一致、URL 带了错误路径、网络或证书不可用
`remote agent must not run as root`	改用专用普通用户启动 Agent
节点注册后很快离线	Controller 心跳超时、Agent 进程退出或反向代理中断请求
Codex 版本为空	`codex-command` 不可执行，或服务用户的 PATH/权限不正确
Windows 无法启动 Codex	将 `codex-command` 指向实际的 `codex.exe`，不要只指向 `.ps1`
`git clone failed`	仓库 URL、TLS、DNS 或服务用户的 Git 凭据有问题
工作目录不存在	`working-dir` 不是仓库中已经存在的相对目录
任务一直等待执行	Agent 不在线、已在执行其他任务或状态被禁用
Codex 没有修改文件	检查 `codex-args` 是否使用 `workspace-write`，并检查 Prompt 与 Codex 输出
Web 日志不能实时更新	检查浏览器到 Controller 的 SSE 连接及反向代理缓冲配置
Agent 日志无法写入	`log-file` 父目录不存在或服务用户没有写权限

常用诊断命令：

sudo -u codex-agent -H /usr/local/bin/codex login status
sudo -u codex-agent -H git ls-remote <https-repository-url> HEAD
sudo journalctl -u apipig-agent -n 200 --no-pager
curl -I https://controller.example.com

安全检查清单

Controller 和 Agent 通信在生产环境使用 HTTPS。
注册密钥使用高强度随机值，并通过受控配置或环境变量分发。
Agent YAML 权限限制为 root 和 Agent 服务组可读。
Agent 使用专用普通用户，不与日常管理员账号共用。
Codex 保持 workspace-write 沙箱，不启用危险的全权限绕过。
Git 凭据不写入 URL、Prompt、日志或配置文件。
workspace 和日志目录不向其他系统用户开放。
定期升级 Git、Codex CLI 和 Remote Agent 二进制。