用户指南

欢迎阅读 Agentrix 用户指南。本文档涵盖作为终端用户使用 Agentrix 平台所需的全部内容。

什么是 Agentrix？

Agentrix 是一个企业级 AI 代理托管与协作平台。它让团队可以将编码和分析任务分发给运行在自己机器上的 AI 代理，代码和数据始终在您的掌控之下。

核心概念

概念	说明
任务（Task）	从 Web 应用或 API 发送给代理的一个工作单元
守护进程（Daemon）	在您的机器上管理 Worker 的后台常驻进程
Worker	守护进程为每个任务生成的子进程（Claude、Codex 或其他代理类型）
机器（Machine）	注册到您 Agentrix 账户的本地运行环境
工作区（Workspace）	Worker 执行每个任务时所使用的隔离目录

工作原理

Web App / API
      │ WebSocket
      ▼
  Agentrix 后端
      │ WebSocket（机器通道）
      ▼
  守护进程 ──────── ~/.agentrix/logs/daemon.log
      │ 生成子进程
      ▼
  Worker 进程 ──── ~/.agentrix/logs/worker-<taskId>.log
      │ git 工作树 / 隔离工作区
      ▼
  任务结果 → 同步回后端

您在 Web 应用中创建任务，关联代码仓库并选择代理类型。
后端通过 WebSocket 连接将任务发送到您机器上运行的守护进程。
守护进程在隔离工作区中生成一个 Worker。
Worker（如 Claude Code）处理任务，提交结果并同步回平台。

为什么选 Agentrix

AI 代理跑得快。Agentrix 让你在用上这个速度的同时，对代码库、凭据和工程流程保持完整掌控。

执行发生在本地 — 代理通过守护进程运行在你自己的机器上，代码、密钥和本地工具链都不出本地环境。
产出真实的代码变更 — 关联仓库，下发任务，拿回一个可审阅的提交，而不是一段对话截图。
每个任务独立运行 — 每次执行都有独立工作区，并行任务互不干扰，实验也不会动到主分支。
融入已有的 Git 流程 — 看变更、审阅结果、决定合不合并，跟普通 PR 没什么区别。
桌面或 CLI，按场景选 — 桌面应用适合日常开发，CLI 适合 Linux 服务器和 CI/CD。
执行过程随时可查 — 机器状态、日志和任务进度，Web 应用和命令行里都能看到。
需要时再开沙箱 — 可以限制 Worker 的文件系统和网络访问，适合对安全边界有要求的环境。

常见使用场景

把功能实现和重复性工作交给 AI 代理，专注更有价值的决策
让代理在真实仓库上下文中定位问题，而不是在聊天框里猜
把重构、清理、批量修改放到隔离工作区里执行，审阅后再合并
在开发机、共享机器或无头服务器上稳定运行 AI Worker

选择安装方式

安装方式取决于您的操作系统和使用场景。

桌面应用 — macOS 或 Windows

对于 macOS 或 Windows 上的开发者，推荐使用桌面应用。这是一个开箱即用的 Electron 应用，它能：

自动安装并管理独立的 Node.js 运行时（无需预先安装 Node.js）
通过图形界面引导安装所有依赖（Git、Claude CLI、ripgrep 等）
通过系统托盘图标管理守护进程
直接在窗口内嵌 Agentrix Web 应用
通过原生深链接回调处理认证

→ 桌面应用安装（macOS / Windows）

CLI — Linux、服务器或 CI/CD

CLI 适用于 Linux 机器、无头服务器和自动化流水线。需要 Node.js 18+ 并手动安装依赖。

npm install -g @agentrix/cli
agentrix start

→ CLI 安装（Linux / 服务器）

目录结构

桌面应用和 CLI 共用同一个状态目录：

~/.agentrix/
├── credentials.json      — 机器令牌（请勿分享）
├── settings.json         — 守护进程与沙箱配置
├── daemon.state.json     — 运行中的守护进程元数据（PID、端口、版本）
├── workspaces/           — 每个任务的隔离工作目录
├── agents/               — 已安装的自定义代理
├── config/
│   ├── claude/           — Agentrix 专用的 Claude Code 配置
│   ├── codex/            — Agentrix 专用的 Codex 配置
│   └── gemini/           — Agentrix 专用的 Gemini 配置
└── logs/
    ├── daemon.log
    └── worker-<taskId>.log

可通过 AGENTRIX_HOME_DIR 环境变量覆盖根目录。

延伸阅读

文档	说明
桌面应用安装	在 macOS 或 Windows 上安装并使用桌面应用
CLI 安装	在 Linux 或 CI/CD 中安装并使用 CLI
依赖项	CLI 依赖详情（git、claude、沙箱工具）
CLI 命令参考	完整 CLI 命令说明
配置	配置守护进程、沙箱与环境变量
故障排除	诊断并解决常见问题
agentrix-run	从 GitHub Actions、GitLab CI 或 shell 提交 Agentrix CI run
Private Cloud 部署	在团队自管服务器上部署和管理 private cloud runner
Web 应用工作流	创建聊天和任务，选择执行环境，查看智能体产出
仓库工作流	在 GitHub 或 GitLab 仓库、issue、MR 和 inbox 中推进工作
Agent Community	发现、安装、发布、评价和讨论 agents 与 skills
账户、计费与 API Keys	管理资料、积分、订阅、机器、偏好设置和 API keys

什么是 Agentrix？​

核心概念​

工作原理​

为什么选 Agentrix​

常见使用场景​

选择安装方式​

桌面应用 — macOS 或 Windows​

CLI — Linux、服务器或 CI/CD​

目录结构​

延伸阅读​