故障排查

按“环境 → Hub → 认证 → 节点 → runtime → 任务”的顺序排查。前一层不通时，后面的报错通常只是连带现象。

完整命令见 CLI 参考，部署问题见生产部署，runtime 专属问题见 Runtime 对比。

先收集最小诊断

在出问题的机器和项目目录运行：

anet doctor
anet hub status
anet whoami
anet status
anet node ls
anet info <alias>
anet logs <alias> --follow

doctor 会检查配置、Hub 连通性、节点身份和本机依赖。不要一上来运行 doctor --fix；先读清它准备修改的项目，再备份相关配置。

公开日志前删除 token、API key、密码、Cookie、完整环境变量和私有 Hub 地址。不要把 ~/.anet、.anet/nodes/*/config.json 或 .env 整份上传。

安装和启动

requires the Bun runtime / spawn bunx ENOENT / 找不到 Bun

2.3.0-preview.47 及以后的构建(现在 latest 与 preview 两条通道都在这个范围内)会在启动前拦下并给出明确提示：

❌ anet hub start requires the Bun runtime (commhub-server is bun-only …)

退出码 1。

更早、不含这道 preflight 的构建(如 2.2.x)会裸崩 Error: spawn bunx ENOENT + Node 堆栈。看到这个字样说明你装的是旧版本:先装 Bun,再 anet upgrade。查自己装的版本用 anet -v;查通道当前指向用 npm view @sleep2agi/agent-network dist-tags。

Agent Network CLI 需要 Node.js ≥ 22.13，Hub 需要 Bun ≥ 1.2：

node --version
bun --version
npm install -g bun @sleep2agi/agent-network @sleep2agi/agent-node

若刚安装仍找不到命令，重新打开 shell 并检查 PATH。全局 npm 安装报 EACCES 时，优先用 nvm/fnm 管理 Node，不要用 sudo npm 或放宽系统目录权限。

agent-node is not installed / 版本检查失败

agent-node --version
anet upgrade --dry-run
npm install -g @sleep2agi/agent-node

按当前发布频道升级，不要从旧文档复制固定 preview 或 package 版本。升级策略见版本说明和升级指南。

端口被占用或 Hub 立即退出

anet hub status
curl http://127.0.0.1:9200/health
lsof -iTCP:9200 -sTCP:LISTEN

先确认占用端口的是不是已有 Hub。由 anet 启动的实例用 anet hub stop 停止；不要按进程名批量 kill。需要换端口时，Hub、CLI 和节点配置必须同时指向新地址。

Hub 和网络连接

ECONNREFUSED

本机先验证：

curl http://127.0.0.1:9200/health
anet hub status

远端节点再验证它实际配置的 Hub URL：

curl http://HUB_HOST:9200/health

本机通、远端不通，通常是 Hub 只监听 loopback、防火墙/安全组未放行，或 URL/端口写错。跨机器部署需让 Hub 监听可达地址，并用 TLS 反向代理保护公网入口。

ETIMEDOUT / DNS / TLS 错误

从节点机器检查解析、路由、证书和代理，而不是只在 Hub 主机测试。若使用域名，确认它没有指向旧主机；若使用 HTTPS，确认反向代理能访问后端 /health。

SSE connection failed / 反复重连

先确认普通健康请求和登录都正常，再看节点日志。SSE 需要长连接；Nginx/Caddy/负载均衡器不得缓冲响应，也不能使用过短的空闲超时。配置示例见生产部署。

日志出现 SSE connected 才表示任务推送链路已建立。短暂断线会自动退避重连；持续失败时不要靠反复重启掩盖代理或身份错误。

登录、token 和 network

No hub configured

anet init --hub http://HUB_HOST:9200
anet login

~/.anet/config.json 中保存当前 Hub、用户 token 和 network。不要手工拼接或从另一台机器复制 token。

401 invalid token / auth required

anet whoami
anet login
anet doctor

Hub 数据库重建、token 被撤销或登录切到另一台 Hub 后，旧 token 都会失效。重新登录后再检查节点；节点必须使用自己的 ntok_，不要把用户 utok_ 填进节点配置。

若节点配置是旧格式或 token 已失效，先备份 .anet/nodes/<alias>/config.json，再根据 anet doctor 的输出决定是否运行：

anet doctor --fix

忘记密码

在 Hub 主机上运行：

anet hub admin reset-user --username <username>

它会生成新密码和用户 token，并撤销旧用户 token。不要直接删除 users、token 行或 bootstrap marker；这些做法会绕过审计并破坏关联状态。

network_id_required / access_denied / permission_denied

• network_id_required：调用者没有唯一可推断的 network。登录/切换到正确 network，或在支持的调用中显式传 network_id。
• access_denied / permission_denied：身份已解析，但角色无权执行该操作。由 network owner 调整成员角色；全局 admin 不自动成为每个 network 的 owner。
• Agent Node 使用绑定到单一 network 的 ntok_；不要跨 network 复用节点 token。

完整权限边界见 Token 与权限、角色和 Network。

其它认证/network 报错

报错	安全处理
password must be at least 8 characters / too common	使用至少 8 位且不在弱密码表中的新密码
429 / too many attempts	停止重试，等待响应指示的窗口后再试；先修正凭据，避免继续触发限流
network name already exists	查看当前 network，换一个名称；不要直接改数据库
network has N active session(s)	用 anet status 找出节点，正常停止后再删除 network
quota exceeded	用 anet network ls 检查并删除不再使用的 network。目前没有公开 CLI 可修改用户 plan/全局角色；联系 Hub 运维，不要把用户直接改成全局 admin

直接写数据库会绕过 API 的鉴权、审计和一致性检查，并可能损坏关联的身份状态，所以这里不提供 SQL“修复”。

Agent Node

节点一直 offline / 收不到任务

依次确认：

1. 节点机器能访问 Hub /health。
2. anet whoami 指向预期 Hub/network。
3. anet info <alias> 的 runtime、工作目录和身份正确。
4. anet logs <alias> --follow 最终出现 SSE connected。
5. 没有另一个进程使用同一 alias、node_id 或 ntok_。

安全重启单个节点：

anet node stop <alias>
anet node start <alias>

不要复制节点 config.json 到另一台机器。目标机器应重新登录并运行 anet node create，让 Hub 签发独立身份。

重复结果 / runtime 来回变化 / alias_identity_mismatch

这通常意味着同一身份被多个进程或旧配置使用：

anet info <alias>
anet logs <alias> --follow
tmux ls

停止旧实例，只保留一个进程。不要通过改 node_id、alias、token 或直接编辑 Hub 数据库“抢回”身份；改名用 anet node rename。

Node "<alias>" already exists 通常只是当前项目的 .anet/nodes/ 已有同名配置。先用 anet node ls / anet info <alias> 确认是否应复用，不要为了重建而直接删目录。

工作目录不对

文件工具使用节点的启动目录。停止节点，切到正确项目目录再启动。Codex TUI 共存时，线程目录继承自 app-server 进程；请按 Codex TUI 共存指南检查整组会话，不要只看桥进程。

远程 daemon 上建的 claude-code-cli 节点起不来

从 Dashboard 选一台远程机器（daemon）建节点时，能不能跑取决于节点用哪种认证：

认证方式	存在哪	能否跨机
API key（DeepSeek / MiniMax / Anthropic 等）	节点配置 + Hub secret vault	能，跟着节点走
Claude Code CLI 订阅登录（claude auth login）	那台机器的 ~/.claude	不能，绑定机器

多机场景优先用 API key：在 Dashboard 的供应商库里配好 vendor、model 和 key，建节点时选这个预设。一定要用订阅登录时，先 SSH 到那台机器执行一次 claude auth login，之后那台机器上的 claude-code-cli 节点才能跑。anet 不会替你把 ~/.claude 传到别的机器。

Runtime 和模型

先确认节点选中的 runtime 与已安装发布频道一致：

anet info <alias>
anet logs <alias> --follow
anet upgrade --dry-run

现象	检查
Claude/Codex 命令找不到	对应 CLI 是否安装、在节点进程的 PATH 中、已完成登录
Vendor 401/403	API key、envRef 指向的变量、ANTHROPIC_BASE_URL 是否匹配同一服务
Vendor 超时/限流	服务状态、账户配额、节点并发；不要靠无限重试消耗额度
Grok ACP 长任务超时	按 runtime 指南核 flags.grokAcpTimeoutMs / GROK_ACP_TIMEOUT_MS
Codex 共存重启后历史消失	升级到 preview.43+；普通 anet node start <alias> 会读取已保存的 codexThreadId 并执行 thread/resume。若旧 bridge 尚存活，先从外部终端 anet node stop <alias>

opencode-cli 可以做人机共存：V1 还能 headless，V2 只接受共存，并且仍是 preview。步骤见 OpenCode V2。Grok 共享 TUI 是实验能力，见 Grok 节点。以 Runtime 对比为准，不要照旧版本或 changelog 历史命令操作。

日志

节点日志「看着不动」，不知道任务还在不在跑

长任务过去在开始和结束之间可以整段没有输出（实测最长 4492 秒静默），于是「卡住了」和「正在干活」在日志里长得一样。现在跑着的任务每 30–60 秒写一行：

[12:34:56] [INFO ] [my-node] in-flight grok primary: loop=3, elapsed=2m 15s, last=tool_call (#7)

last= 是运行时最近一次动作。看不到这行说明进程没在推进，可以按卡死排查；看得到就是还在跑，等它。目前 grok 的两个 runtime（ACP 与 CLI）有这行，其它 runtime 后续跟进。

日志里全是 [grok-stderr] 警告，真正的问题被淹掉

Grok 的沙箱按工作目录拒绝越界路径（path outside Grok runtime cwd）是常见且可恢复的，模型会换软链路径重试，任务照样成功。这类已知无害的 stderr 不再每条升一个警告，而是每轮合并成一行：

[grok-stderr] known-benign stderr this turn: 12 (path-outside-cwd 12)

未被归类的失败仍然按原样告警——没见过的失败永远不会被静音。

调节日志密度

ANET_LOG_LEVEL=debug anet node start <alias>   # debug | info | warn | error，默认 info

也可用 --log-level、旧的 LOG_LEVEL 环境变量或节点配置里的 logLevel，优先级依次递减。写错值时不再静默按 info 处理，而是先告警再退回默认。

任务和消息

任务没有触发模型

需要执行的工作必须用 send_task。send_reply 是任务结果，send_message 是普通消息，两者都不会再次触发模型。

anet status

确认目标节点在线、任务属于当前 network，且目标 alias 正确。任务状态、重试和父子任务语义见任务生命周期。

task not found / message not found

常见原因是当前 token/network 与对象不一致，或者该对象不属于当前节点。先运行 anet whoami 和 anet status；不要通过直接查改 SQLite 绕过 network 隔离。

定时任务没有运行

应用里的「定时任务」页（Hub 计划）见定时任务。下面这几条命令查的是另一件事：命令行的 Goal / Loop。

anet goal list <alias>
anet info <alias>

循环任务要求节点在线，并会消耗真实模型额度。它不是高精度 cron；先用较长周期验证。 继续检查 goal show / wake-log 中的 next_wake_at、失败记录和 paused 状态。完整语义见 Goal 与 Loop。

Channel

anet channel status <alias>
anet logs <alias> --follow

检查 bot token、pairing/allowlist、目标节点和 channel runtime 是否一致。Telegram 使用长轮询；反向代理 webhook 设置与它无关。当前支持范围和重启要求见 Channel 指南。

Docker

docker compose ps
docker compose logs --tail=200 <service>

检查 Hub 健康检查、持久卷、容器内 Hub URL、token 文件和模型凭据挂载。容器内的 localhost 指向容器自身，不是宿主机。

不要用 docker system prune、docker image prune -a 或宽泛名称匹配清理共享宿主机；先逐个确认容器和精确镜像引用。

专项排查页

上面按层排查解决不了时，这几页各针对一个具体形态：

• 这个节点还活着吗 —— 派出去的任务没有回音时， 先回答「它还能不能干活」。附一张按可信度排序的判据表（status = idle 覆盖四种现实， 只有「它自己回一句话」算硬证据）。
• anet doctor 的输出怎么读 —— 四种前缀分别代表什么、 为什么版本那几行只报不判、以及它回答不了哪些问题。
• 连通性：Channel 与 MCP
• 节点卡在 stopping / starting
• 安全重启 Codex TUI 节点
• 飞书 Bot 收不到或不回消息

常见问题

Agent Network 是什么？免费吗？

自部署的多 Agent 通信层：CommHub 负责身份、任务和消息，Agent 通过 MCP 发现队友、通过 SSE 接收任务，它不规定 Agent 内部怎样推理。代码是 Apache 2.0 许可，项目不提供官方托管 Hub；个人使用把 Hub 跑在本机，跨机器或团队使用时部署在所有节点都能访问的机器上。选 runtime 和模型以 Runtime 对比和多模型配置为准。

配置和数据在哪里？

路径	内容
~/.anet/config.json	当前 Hub、用户 token、network
<项目>/.anet/nodes/<alias>/config.json	节点 runtime、身份和 flags
<项目>/.anet/nodes/<alias>/.env	可选的节点 secret，明文文件，权限应为 0600
~/.commhub/commhub.db	Hub 的 SQLite 数据库

不要提交 .anet、token 或 .env。详见安全设计。

可以直接把 9200 / 3000 暴露到公网吗？

不建议。先改初始密码，再通过 Caddy / Nginx 配 TLS 和访问控制，按生产部署逐项检查。

支持 PostgreSQL 吗？

**PostgreSQL 支持尚在开发中，目前不可用。**当前维护和验证的后端是 SQLite。代码里虽有 DATABASE_URL=postgres://… 入口，但这样配置的 Hub 启动时会拒绝运行。进展见 RFC-039。

仍未解决

提交 Issue 时附：

• anet -v、Node/Bun 版本和发布频道
• runtime、操作系统、部署方式
• 最小复现步骤和实际报错
• 已脱敏的 anet doctor、anet info 与相关日志片段

先搜索 Issues；安全问题请使用 GitHub Security Advisory，不要公开漏洞或凭据。