CLI 命令参考

全局选项

标志	说明
`--version`, `-v`	打印 CLI 版本
`--help`, `-h`	显示任意命令的帮助信息
`--debug`, `-d`	启用本地调试模式（明文输出，用于排错）

agentrix start

启动守护进程（如未运行），然后显示其状态。

agentrix start

执行步骤：

认证（首次运行时打开浏览器 OAuth，或验证已有凭据）。
检查关键依赖（git、沙箱工具）。如有缺失则退出。
将守护进程作为分离的后台进程启动。
等待最多 5 秒，直到守护进程报告就绪。
打印守护进程状态。

agentrix start 不会检查 CLI 升级。需要升级 CLI 时，请手动运行 agentrix upgrade；可用时也可以从应用的 machine-control 入口触发 upgrade-cli。

示例输出：

Starting Agentrix background service...
✓ Daemon started successfully

🤖 Daemon Status
✓ Daemon is running
  PID: 12345
  Started: 4/22/2026, 10:00:00 AM
  CLI Version: 1.2.3
  HTTP Port: 51234

agentrix stop

停止正在运行的守护进程。

agentrix stop

守护进程停止时，所有活跃的 Worker 会话都会被终止。

agentrix status

显示守护进程和认证状态。

agentrix status

等效于运行只显示守护进程 + 认证部分的 agentrix doctor。

示例输出：

🤖 Daemon Status
✓ Daemon is running
  PID: 12345
  Started: 4/22/2026, 10:00:00 AM
  CLI Version: 1.2.3
  HTTP Port: 51234

🔐 Authentication
✓ Authenticated (credentials found)

agentrix doctor

完整的系统诊断——版本、配置、环境变量、认证、依赖项和守护进程状态。

agentrix doctor

排查问题时请以此命令为第一步。它会显示：

CLI 版本、平台、Node.js 版本
守护进程启动路径（包装脚本、入口文件）
配置信息（主目录、服务器 URL、日志目录）
影响 Agentrix 行为的环境变量
认证状态
依赖状态（git、claude、codex、沙箱工具）
守护进程状态（运行中 / 状态陈旧 / 未运行）

agentrix llm-config apply

根据 Agentrix 环境变量生成 Claude Code、Codex 和 Gemini 配置。CLI Docker 镜像启动 agentrix daemon 或 agentrix start 前会自动运行此命令；本地或 systemd 部署也可以手动运行。

export AGENTRIX_BASE_URL=https://api.xmz.ai
export AGENTRIX_API_KEY=<llm-gateway-api-key>

agentrix llm-config apply --verbose

在这个命令里，AGENTRIX_API_KEY 和 AGENTRIX_BASE_URL 指向 LLM 网关。agentrix-run 提交任务时也会读取同名变量，但含义是 Agentrix API 参数，见 agentrix-run。

默认只写入缺失的配置文件，不覆盖已有文件。Codex 配置会保持最小配置，运行时沙箱和审批策略由 Worker 启动参数控制。

选项：

选项	说明
`--source env`	从环境变量读取配置。当前仅支持 `env`
`--force`	覆盖已存在的 Claude、Codex、PI 和 Gemini 配置文件
`--dry-run`	只打印计划写入的文件，不修改磁盘
`--verbose`	打印每个配置文件的写入或跳过结果

相关环境变量：

变量	默认值	说明
`AGENTRIX_API_KEY`	—	LLM 网关密钥
`AGENTRIX_API_KEY_FILE`	—	从文件读取 LLM 网关密钥
`AGENTRIX_BASE_URL`	`https://api.xmz.ai`	LLM 网关地址；Codex 会使用该地址下的 `/v1`
`AGENTRIX_CLAUDE_HOME`	`~/.claude`	Claude Code 配置目录
`AGENTRIX_CODEX_HOME`	`~/.codex`	Codex 配置目录
`AGENTRIX_PI_HOME`	`~/.pi/agent`	PI 配置目录；也兼容 `PI_CODING_AGENT_DIR`
`AGENTRIX_PI_HOME`	`~/.pi/agent`	PI 配置目录；也兼容 `PI_CODING_AGENT_DIR`
`AGENTRIX_GEMINI_HOME`	`$AGENTRIX_HOME_DIR/config/gemini`	Gemini 配置目录
`AGENTRIX_CODEX_MODEL`	`gpt-5.5`	Codex 默认模型
`AGENTRIX_PI_MODEL`	同 `AGENTRIX_CODEX_MODEL`	PI 默认模型
`AGENTRIX_CLAUDE_MODEL`	`claude-sonnet-4-6`	Claude 默认模型
`AGENTRIX_CLAUDE_FAST_MODEL`	`claude-haiku-4-5`	Claude fast model
`AGENTRIX_CLAUDE_SUBAGENT_MODEL`	同 `AGENTRIX_CLAUDE_MODEL`	Claude subagent model
`AGENTRIX_GEMINI_IMAGE_MODEL`	`gemini-2.5-flash-image`	Gemini 图片模型

agentrix upgrade

升级 CLI 到 npm 上的最新版本。

agentrix upgrade

此命令执行 npm install -g @agentrix/cli@latest，并：

检查代理更新（companion 等）。
如果守护进程正在运行，自动重启。

agentrix start 不会自动检查 CLI 升级。

agentrix logout

解除此机器与 Agentrix 账户的绑定。

agentrix logout

删除 ~/.agentrix/credentials.json。下次运行 agentrix start 时将重新打开浏览器认证流程。

agentrix ls

列出当前守护进程跟踪的所有会话。

agentrix ls

每个会话对应一个正在运行或刚启动的 Worker 进程。

示例输出：

Active sessions:
[
  {
    "taskId": "task-abc123",
    "pid": 54321,
    "startedBy": "cli"
  }
]

如果没有 Worker 在运行，则返回 No active sessions。

agentrix kill <sessionId>

通过任务 ID 停止特定的 Worker 会话。

agentrix kill task-abc123

agentrix killall

终止系统上找到的所有失控的 agentrix 进程。

agentrix killall

当会话卡住或守护进程状态不一致时使用此命令。会报告已终止的进程数。

agentrix git-server add

把一个私有 GitLab 服务写入本机 daemon 配置，并保存用于访问该 GitLab 的 PAT。用户身份绑定与 proxy 注册是两个互不依赖的选择。

agentrix git-server add \
  --base-url https://gitlab.example.com

选项：

选项	说明
`--base-url <url>`	GitLab 站点 URL，例如 `https://gitlab.example.com`
`--api-url <url>`	GitLab API URL。默认是 `<base-url>/api/v4`
`--pat-file <file>`	从文件读取 PAT；使用 `-` 可从 stdin 读取
`--bind-user` / `--no-bind-user`	是否把 GitLab 账号绑定到当前 Agentrix 用户；提示时直接回车默认不绑定
`--proxy` / `--no-proxy`	是否把当前机器注册为该 GitLab 的 proxy node；默认会询问

未指定 --pat-file 时，命令会交互式提示输入 PAT，并且不会回显。

printf '%s' "$GITLAB_PAT" | agentrix git-server add \
  --base-url https://gitlab.example.com \
  --pat-file -

命令会输出 JSON，包含 webhookUrl 和 webhookSecret。PAT 和 webhook secret 会加密保存在 ~/.agentrix/credentials/ 下；baseUrl / apiUrl 会以本机配置形式保存。

交互提示默认不绑定，适合 Private Cloud 机器使用公共 bot PAT。daemon 仍会在本地验证并保存 PAT，但不会把 PAT 发给 Agentrix API，也不会创建用户级 GitLab credential、身份或仓库。只有 PAT 确实代表当前 Agentrix 用户时才传 --bind-user。--proxy 与此选项独立，可以只开放机器到 GitLab 的网络能力，而不把 bot 当作当前用户身份。

运行此命令前需要先完成机器绑定。若提示缺少 Agentrix auth secret，请先运行 agentrix start。

agentrix git-server list

列出本机保存的私有 GitLab 配置。

agentrix git-server list

输出包含完整的本机信息：Git server ID、baseUrl、apiUrl、webhook endpoint、daemon 当前可用的 webhookUrl、PAT 是否已配置、PAT 用户元信息、webhookSecret，以及已缓存的项目级 pipeline trigger token。

[
  {
    "id": "corp-gitlab",
    "type": "gitlab",
    "baseUrl": "https://gitlab.example.com",
    "apiUrl": "https://gitlab.example.com/api/v4",
    "webhookEndpointPath": "/webhooks/gitlab/corp-gitlab",
    "webhookUrl": "http://192.168.1.10:30624/webhooks/gitlab/corp-gitlab",
    "patConfigured": true,
    "patMeta": {
      "username": "alice",
      "email": "[email protected]",
      "lastValidatedAt": "2026-04-27T05:00:00.000Z",
      "expiresAt": null
    },
    "webhookSecret": "...",
    "projectTriggerTokens": {}
  }
]

如果 daemon 没有运行，webhookUrl 可能为空；先运行 agentrix start 再查看。

GitLab webhook 配置

daemon 自带的 web server 可以直接接收 GitLab webhook，并把符合条件的事件转成 GitLab pipeline trigger。

基本步骤：

运行 agentrix start，确保 daemon 已启动。
运行 agentrix git-server add 保存 GitLab baseUrl、apiUrl 和 PAT。
运行 agentrix git-server list，复制 webhookUrl 和 webhookSecret。
在 GitLab 项目的 Webhooks 页面中，将 webhookUrl 填到 URL，将 webhookSecret 填到 Secret token，并勾选需要触发 pipeline 的事件类型。
如果 GitLab 不在本机，需要在 ~/.agentrix/settings.json 中启用 daemonControl.allowLanAccess 并重启 daemon。

{
  "daemonControl": {
    "allowLanAccess": true
  }
}

支持的事件与映射

daemon webhook endpoint 会校验 GitLab 的 X-Gitlab-Token，规范化支持的事件并触发 GitLab pipeline。它不会把 GitLab webhook payload 转发给 Agentrix 仓库 inbox 通道。

Pipeline trigger 当前默认触发所有支持的规范化事件：

GitLab webhook	Pipeline 结果	规范化事件
`event_type: "issue"` 或 `object_kind: "issue"`	触发项目 pipeline	`GITLAB_BRIDGE_EVENT_NAME=issues`，`GITLAB_BRIDGE_EVENT_ACTION=<github_action>`
`merge_request`	触发项目 pipeline	`GITLAB_BRIDGE_EVENT_NAME=pull_request` 或 `pull_request_review`，`GITLAB_BRIDGE_EVENT_ACTION=<github_action>`
`note` 的非 system issue/MR 评论	触发项目 pipeline	`GITLAB_BRIDGE_EVENT_NAME=issue_comment` 或 `pull_request_review_comment`，`GITLAB_BRIDGE_EVENT_ACTION=created/edited/deleted`
`pipeline`	触发项目 pipeline	`GITLAB_BRIDGE_EVENT_NAME=workflow_run`，`GITLAB_BRIDGE_EVENT_ACTION=requested/in_progress/completed`
system `note`、GitLab-only 变化和其他 unsupported 事件	不触发 pipeline，响应体为 `status: "ignored"`，`reason` 会说明忽略原因	不适用

常见规范化 action：

GitLab 信号	normalized event
Issue open/reopen/close	`issues.opened/reopened/closed`
Issue label added/removed	`issues.labeled/unlabeled`，每个 label 一条事件
MR open/reopen/close/merge	`pull_request.opened/reopened/closed`，merge 时设置 `GITLAB_BRIDGE_PULL_REQUEST_MERGED=true`
MR source/head 更新	`pull_request.synchronize`
MR reviewer added/removed	`pull_request.review_requested/review_request_removed`
Issue/MR 普通评论	`issue_comment.created/edited/deleted`
Pipeline created/pending/running	`workflow_run.requested/in_progress`；`created` 对外的 `GITLAB_BRIDGE_WORKFLOW_RUN_STATUS=pending`
Pipeline success/failed/canceled/skipped	`workflow_run.completed`，通过 `GITLAB_BRIDGE_WORKFLOW_RUN_CONCLUSION` 区分结果

bridge 默认注入的 pipeline 变量统一使用 GITLAB_BRIDGE_* 前缀。Agentrix 还会额外追加 AGENTRIX_GIT_SERVER_ID，让 agentrix-run 能解析本机配置的私有 GitLab server。

所有 daemon 触发的 pipeline 都会收到这些基础变量：

变量	含义
`GITLAB_BRIDGE_EVENT_NAME`	规范化事件名，例如 `issues`、`pull_request`、`issue_comment`、`workflow_run`
`GITLAB_BRIDGE_EVENT_ACTION`	规范化后的事件动作
`GITLAB_BRIDGE_REPOSITORY`	完整仓库路径，例如 `group/subgroup/repo`
`GITLAB_BRIDGE_REPOSITORY_OWNER`	`project.path_with_namespace` 去掉最后一段后的路径，支持 subgroup
`GITLAB_BRIDGE_REF_NAME`	触发 pipeline 使用的目标 ref
`AGENTRIX_GIT_SERVER_ID`	本机配置的 Git server ID

不同事件会追加这些变量：

事件	追加变量
`issues`	`GITLAB_BRIDGE_ISSUE_NUMBER`、`GITLAB_BRIDGE_ISSUE_TITLE`、`GITLAB_BRIDGE_ISSUE_URL`，label 事件还有 `GITLAB_BRIDGE_LABEL_NAME`、`GITLAB_BRIDGE_LABELS`、`GITLAB_BRIDGE_LABELS_JSON`、`GITLAB_BRIDGE_LABEL_CHANGES_JSON`
`pull_request` / `pull_request_review`	`GITLAB_BRIDGE_PR_NUMBER`、`GITLAB_BRIDGE_HEAD_REF`、`GITLAB_BRIDGE_BASE_REF`、`GITLAB_BRIDGE_PR_TITLE`、`GITLAB_BRIDGE_PR_BODY`、`GITLAB_BRIDGE_PR_URL`、`GITLAB_BRIDGE_LABELS`、`GITLAB_BRIDGE_LABELS_JSON`，synchronize 事件在 GitLab 提供 commit 数据时还会有 `GITLAB_BRIDGE_HEAD_SHA` 和 `GITLAB_BRIDGE_OLD_HEAD_SHA`
`issue_comment` / `pull_request_review_comment`	`GITLAB_BRIDGE_COMMENT_BODY`、`GITLAB_BRIDGE_COMMENT_ID`、`GITLAB_BRIDGE_COMMENT_URL`，并根据评论对象设置 `GITLAB_BRIDGE_ISSUE_NUMBER` 或 `GITLAB_BRIDGE_PR_NUMBER`
`workflow_run`	`GITLAB_BRIDGE_WORKFLOW_RUN_STATUS`、`GITLAB_BRIDGE_WORKFLOW_RUN_CONCLUSION`、`GITLAB_BRIDGE_WORKFLOW_RUN_ID`、`GITLAB_BRIDGE_WORKFLOW_RUN_NUMBER`、`GITLAB_BRIDGE_WORKFLOW_RUN_URL`、`GITLAB_BRIDGE_WORKFLOW_RUN_REF`、`GITLAB_BRIDGE_WORKFLOW_RUN_SHA`，能关联 MR 时还会设置 `GITLAB_BRIDGE_PR_NUMBER`

可选变量只有 GitLab payload 提供对应字段时才存在，例如：

变量	含义
`GITLAB_BRIDGE_ISSUE_TITLE`	Issue 标题；GitLab payload 提供时才存在
`GITLAB_BRIDGE_ISSUE_URL`	Issue URL；优先使用 payload 中的 URL，否则由项目 URL 和 IID 拼出
`GITLAB_BRIDGE_OLD_HEAD_SHA`	`pull_request.synchronize` 的上一版 MR head revision，GitLab 提供时才存在
`GITLAB_BRIDGE_HEAD_SHA`	`pull_request.synchronize` 的当前 MR head SHA，GitLab 提供时才存在

说明：

Webhook URL 只包含 daemon endpoint，不包含 PAT、API URL 或 pipeline trigger token。
Webhook secret 对应 GitLab 的 X-Gitlab-Token 请求头，用于确认请求来自你配置的 GitLab webhook。
Pipeline trigger token 是 GitLab 项目级 token。daemon 首次处理某个项目的 webhook 时会创建或复用 GitLab webhook bridge trigger，并把 token 加密缓存在本机。
Delivery identity 会优先读取 GitLab 稳定 delivery header：webhook-id、Idempotency-Key、 X-Gitlab-Webhook-UUID、X-Gitlab-Event-UUID，再读 legacy X-Gitlab-Delivery；都不存在时使用稳定 payload hash。
成功投递过的 normalized fan-out event 会对重复投递做去重。重复 redelivery 返回 status: "ignored"，对应 delivery 的 reason 为 "duplicate_delivery_event"；失败的 fan-out event 不会写入去重记录，因此后续手动 redelivery 可继续补偿。
如果 GitLab pipeline 触发失败（例如项目缺少 .gitlab-ci.yml），daemon 会记录日志，并对 GitLab 返回 200，响应体中 status 为 failed，避免 GitLab 反复重试业务失败。非 200 只用于 bridge 无法安全处理请求的情况，例如 secret 错误、bridge 未配置或本地 GitLab 配置缺失。

环境变量

这些变量可在不修改 settings.json 的情况下改变 CLI 行为。

变量	默认值	说明
`AGENTRIX_HOME_DIR`	`~/.agentrix`	根状态目录
`AGENTRIX_SERVER_URL`	`https://agentrix.xmz.ai`	后端 API URL
`AGENTRIX_WEBAPP_URL`	`https://agentrix.xmz.ai`	Web 应用 URL（用于认证跳转）
`AGENTRIX_WORKSPACE_HOME_DIR`	`~/.agentrix/workspaces`	任务工作区根目录
`AGENTRIX_AGENTS_HOME_DIR`	`~/.agentrix/agents`	自定义代理安装根目录
`AGENTRIX_CLAUDE_HOME`	`~/.claude`	Claude Code 配置目录
`AGENTRIX_CODEX_HOME`	`~/.codex`	Codex 配置目录
`AGENTRIX_GEMINI_HOME`	`~/.agentrix/config/gemini`	Gemini 配置目录
`AGENTRIX_API_KEY`	—	LLM 网关密钥；`agentrix llm-config apply` 和 Docker 自动配置会读取
`AGENTRIX_API_KEY_FILE`	—	从文件读取 LLM 网关密钥
`AGENTRIX_BASE_URL`	`https://api.xmz.ai`	LLM 网关地址
`AGENTRIX_PI_MODEL`	同 `AGENTRIX_CODEX_MODEL`	PI 默认模型
`AGENTRIX_CLAUDE_PATH`	—	覆盖 `claude` 二进制路径
`AGENTRIX_CODEX_PATH`	—	覆盖 `codex` 二进制路径
`AGENTRIX_LLM_AUTO_CONFIG`	`true`	Docker 镜像启动 daemon/start 时是否自动生成 LLM 配置
`AGENTRIX_LLM_CONFIG_FORCE`	`false`	Docker 自动配置时是否覆盖已有 LLM 配置
`GITLAB_BASE_URL`	—	Docker/cloud runner 启动后自动配置的 GitLab 站点 URL
`GITLAB_API_URL`	`<base-url>/api/v4`	自动配置 GitLab 时使用的 API URL
`GITLAB_TOKEN`	—	自动配置 GitLab token；写入本机 worker token store，并在启用用户绑定时同步为 API credential
`GITLAB_TOKEN_FILE`	—	从文件读取 GitLab token，适合 Docker secret
`AGENTRIX_GITLAB_BIND_USER`	本机：`true`；Private Cloud：`false`	自动配置时是否把 GitLab 账号绑定到当前 Agentrix 用户；显式配置会覆盖运行模式默认值
`AGENTRIX_GITLAB_USE_AS_PROXY`	`true`	自动配置时是否把当前 runner 注册为 Git proxy node
`AGENTRIX_GITLAB_AUTO_CONFIG`	`true`	设为 `false` 可禁用 Docker/cloud runner GitLab 自动配置
`AGENTRIX_DISABLE_CAFFEINATE`	—	设为 `true` 允许机器在任务执行期间进入睡眠
`CLOUD_AUTH_TOKEN`	—	cloud runner 认证令牌；部署 Private Cloud runner 时设置为 runner secret
`CLOUD_AUTH_TOKEN_FILE`	—	从文件读取 cloud runner 认证令牌
`DEBUG`	—	启用详细调试日志

全局选项​

agentrix start​

agentrix stop​

agentrix status​

agentrix doctor​

agentrix llm-config apply​

agentrix upgrade​

agentrix logout​

agentrix ls​

agentrix kill <sessionId>​

agentrix killall​

agentrix git-server add​

agentrix git-server list​

GitLab webhook 配置​

支持的事件与映射​

环境变量​

全局选项

agentrix start

agentrix stop

agentrix status

agentrix doctor

agentrix llm-config apply

agentrix upgrade

agentrix logout

agentrix ls

agentrix kill <sessionId>

agentrix killall

agentrix git-server add

agentrix git-server list

GitLab webhook 配置

支持的事件与映射

环境变量