故障排除

从这里开始

出现问题时，先运行完整诊断：

agentrix doctor

它在一个输出中显示版本信息、配置、环境变量、认证状态、依赖状态和守护进程状态。大多数问题在这里都能看出来。

---

守护进程无法启动

缺少依赖项

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

安装缺失的工具（参见依赖项），然后再次运行 agentrix start。

陈旧的守护进程状态

如果上一个守护进程崩溃，其 .state.json 锁文件可能仍然存在。 agentrix start 会自动清理，但如果没有自动清理：

agentrix stop        # 尝试正常停止
agentrix killall     # 终止所有残留的 agentrix 进程
agentrix start

守护进程启动后立即退出

✗ Daemon exited shortly after startup

查看守护进程日志以找到根本原因：

cat ~/.agentrix/logs/daemon.log | tail -30

常见原因：

日志信息	解决方法
Machine binding revoked	运行 agentrix logout 并重新认证
认证 / 网络错误	检查到 agentrix.xmz.ai 的连通性及代理设置

---

认证问题

机器绑定被撤销

Machine binding revoked
Run `agentrix logout` and bind again.

您机器的令牌已在 Web 应用中被撤销或已过期。解除绑定并重新认证：

agentrix logout
agentrix start

浏览器未打开

如果浏览器未自动启动，请将终端打印的 URL 复制后手动打开：

If the browser did not open, please copy and paste this URL:
https://agentrix.xmz.ai/auth/machine?...

无头环境（无浏览器）

使用 CLOUD_AUTH_TOKEN 跳过浏览器流程：

CLOUD_AUTH_TOKEN=<your-token> agentrix start

---

依赖项未找到

即使工具已安装，如果其二进制文件不在 PATH 中，CLI 也可能报告为未找到。

# 检查 npm 全局二进制文件的安装位置
npm config get prefix

# 添加到 PATH（粘贴到 ~/.zshrc 或 ~/.bashrc）
export PATH="$PATH:$(npm config get prefix)/bin"

然后重新加载 shell 并重试：

source ~/.zshrc   # 或 source ~/.bashrc
agentrix doctor

---

会话卡死或僵尸进程

# 列出活跃会话
agentrix ls

# 停止特定会话
agentrix kill task-abc123

# 终止所有失控的 agentrix 进程
agentrix killall

---

日志文件

日志	位置
守护进程日志	~/.agentrix/logs/daemon.log
Worker 日志	~/.agentrix/logs/worker-<taskId>.log

# 实时跟踪守护进程日志
tail -f ~/.agentrix/logs/daemon.log

# 查看最后 30 行
tail -30 ~/.agentrix/logs/daemon.log

安全说明： CLI 0.51.3 及更早版本在开启 DEBUG 日志时，可能把 Git URL 中嵌入的凭据写入守护进程日志。如果您曾使用受影响版本和带认证信息的 Git URL，请升级 CLI，并轮换可能暴露的访问令牌或密码；归档日志和支持包中留存的凭据也应一并处置。

---

重置 / 重新安装

如需全新开始，停止守护进程，删除凭据和状态，然后重新认证：

agentrix stop
agentrix killall

# 仅删除凭据（保留配置）
rm ~/.agentrix/credentials.json

# 或删除所有内容
rm -rf ~/.agentrix

# 重新认证
agentrix start

重新安装 CLI：

npm install -g @agentrix/cli@latest
agentrix start

---

代理 / 网络问题

如果您的网络需要代理，在 ~/.agentrix/settings.json 中配置：

{
  "daemonEnv": {
    "enabled": true,
    "variables": {
      "HTTPS_PROXY": "http://proxy.corp.example.com:8080",
      "NO_PROXY": "localhost,127.0.0.1"
    }
  }
}

保存后重启守护进程：

agentrix stop && agentrix start

完整的 daemonEnv 说明请参见配置。

---

检查环境变量

agentrix doctor

Environment Variables 部分显示 Agentrix 在运行时看到的值：

🌍 Environment Variables
AGENTRIX_HOME_DIR: not set
AGENTRIX_SERVER_URL: not set
DEBUG: not set
NODE_ENV: not set

如果 AGENTRIX_SERVER_URL 指向错误的主机，请覆盖它：

export AGENTRIX_SERVER_URL=https://agentrix.xmz.ai
agentrix start