依赖项

Agentrix CLI 运行任务需要若干外部工具。守护进程在启动时会检查这些依赖， agentrix doctor 可以显示完整状态。

CLI 核心依赖

git（必须）

所有任务都需要 Git — 每个工作区都是一个 git 仓库。

• macOS / Linux：通常已预装。如需下载请访问 https://git-scm.com/downloads。
• Windows：使用 Git for Windows 或 WSL。

claude（必须）

Claude Code CLI 是 Claude 代理任务所必须的，而大多数 Agentrix 使用场景都依赖它。

npm install -g @anthropic-ai/claude-code

codex（可选）

仅在创建 Codex 任务时才需要，Claude 任务不需要它。

npm install -g @codex-ai/codex-cli

Pi（内置）

Pi 任务使用 Agentrix 内置的 Pi SDK，无需单独安装 CLI。提供商、凭据、模型、技能和提示模板 沿用 Pi 标准的 ~/.pi/agent/ 目录；可通过 PI_CODING_AGENT_DIR 覆盖该目录。

沙箱依赖

沙箱将 Worker 进程与您文件系统的其余部分隔离。不同平台所需工具不同。

macOS — ripgrep

ripgrep（rg）用于 macOS 上的沙箱运行时。

brew install ripgrep

备选（MacPorts）：

sudo port install ripgrep

Linux — bubblewrap + socat

bubblewrap（bwrap）在 Linux 上提供基于命名空间的沙箱隔离。

# Debian / Ubuntu
sudo apt install bubblewrap

# RHEL / CentOS / Fedora
sudo yum install bubblewrap
# 或
sudo dnf install bubblewrap

# Arch Linux
sudo pacman -S bubblewrap

socat 处理沙箱内部的 socket 通信。

# Debian / Ubuntu
sudo apt install socat

# RHEL / CentOS / Fedora
sudo yum install socat

# Arch Linux
sudo pacman -S socat

检查依赖状态

agentrix doctor

Doctor 输出显示每个依赖的安装状态和路径：

🔧 CLI Dependencies
✓ git - Version control system (required for all tasks)
  Location: /usr/bin/git
✓ claude - Claude Code CLI (required for most features)
  Location: /usr/local/bin/claude
⚠️  codex - Codex CLI (optional, for Codex tasks)
  Install: npm install -g @codex-ai/codex-cli

🔒 Sandbox Dependencies
Platform: macos
✓ ripgrep - Fast code search tool (required by sandbox)
  Location: /usr/local/bin/rg

✓ All required dependencies are installed

启动时检查

agentrix start 在启动守护进程之前检查关键依赖。如有缺失，会打印错误并退出，不会启动守护进程：

⚠️  Missing Critical Dependencies
Cannot start daemon. Missing: ripgrep

Run "agentrix doctor" for detailed dependency information and installation instructions.

修复缺失的依赖后，重新运行 agentrix start 即可。

PATH 问题

如果 CLI 报告某个依赖未找到，但实际上它已安装，可能是该二进制文件不在您的 PATH 中。

# 查看 npm 全局二进制文件的安装位置
npm config get prefix
# 输出示例: /usr/local

# 二进制文件在 <prefix>/bin 下 — 如果 PATH 中没有，请添加
export PATH="$PATH:$(npm config get prefix)/bin"

将该 export 添加到您的 shell 配置文件（~/.zshrc、~/.bashrc 等）中以使其永久生效。

对于通过 Homebrew 安装的工具：

# Apple Silicon Mac 上 Homebrew 自动设置 /opt/homebrew/bin
# Intel Mac 使用 /usr/local/bin
# 验证方式：
echo $PATH | tr ':' '\n' | grep -E 'homebrew|local'