FAQ

常见问题解答。

第一次用 anet?

想跑通第一个 agent → 上手指南 (30 秒装好 + 派任务)
想知道版本号含义 → 版本号体系 (npm 包版 vs v0.10.x bundle release)
没找到答案 → 故障排查 / Discussions

基础问题

1. Agent Network 是什么？和 LangChain / CrewAI 有什么区别？

Agent Network 是一个 多 Agent 通信基础设施，而不是 Agent 框架。它不关心你的 Agent 怎么"想"，只负责让多个 Agent 能互相通信、派任务、追踪结果。

对比	Agent Network	LangChain / CrewAI
定位	通信基础设施	Agent 框架
协议	MCP 标准协议	自定义
模型	任意模型混搭	通常单模型
部署	分布式（多机）	通常单进程
管理	CLI + Dashboard	代码定义

2. 需要服务器吗？

开发/个人使用：anet hub start 在本地笔记本上启动，不需要额外服务器。

团队使用：建议在一台服务器上部署 CommHub Server，团队成员各自连接。最低配置 1 核 1G 内存即可。

3. 免费吗？

Apache-2.0 开源、self-hosted。 代码和仓库许可证不要求购买 license，没有官方 SaaS 托管；但当前 stable 代码里仍保留 legacy trial/pro-license 表和 send_task 过期检查。

仓库公开、源码可改
商业模式 = 卖课 + 卖服务咨询，不依赖强制官方 SaaS
anet license / anet activate 是 v0.6 legacy 命令，OSS 后不再需要；若命中 license_expired（Hub 后向兼容仍创建 14 天 trial），按 troubleshooting — license_expired 直接清掉 licenses 表即可

v0.6 license 路径计划清理

当前 server 在 send_task 仍跑 licenses.expires_at 检查（V3 遗留代码，verify server/src/tools.ts license_expired 仍在）—— v0.9.x / v0.10.x 整条 stable 线都未动 license 路径（每个 release 的具体改动见 changelog），排到 v0.11+ 整段移除。

4. 支持哪些 AI 模型？

任何支持 Anthropic Messages API 的模型都可以通过 claude-agent-sdk runtime 接入。anet node create 的 VENDORS 列表里内置的 provider（每项都是 verified-with-real-call 才进列表，详见 runtimes 已验证 vs 未验证）：

Anthropic 原生 SDK（Claude Sonnet / Opus / Haiku；查 Anthropic Models）
MiniMax（Anthropic 兼容；查 MiniMax 平台）
书生 InternLM（Anthropic 兼容；查书生）
小米 MiMo（Anthropic 兼容；查小米开放平台）
OpenAI Codex（codex-sdk runtime；查 OpenAI Codex 文档）
xAI Grok（grok-build-acp runtime, ACP 协议；目前只通过 --runtime grok-build-acp flag 启用，详细 runtime 指南 ↗）

未进 VENDORS 列表的 provider（DeepSeek / 智谱 GLM / Moonshot Kimi / OpenRouter 等）—— 用「自定义 custom」供应商接入：任何 Anthropic 兼容 API 都能填 base URL + model id，能用但请自己先跑通验证。

完整 endpoint 表 + 配置示例见多模型配置。任何支持 Anthropic Messages API 的服务商都可以通过 ANTHROPIC_BASE_URL 接入。

5. 一个网络最多支持多少 Agent？

技术上没有硬限制。实测：

10 Agent：完全流畅
50 Agent：正常运行
100 Agent：SSE 推送有轻微延迟（< 1s）

SQLite WAL 模式支持高并发读写，瓶颈通常在 AI 模型的响应速度。

安装和配置

6. 安装时报权限错误（EACCES）

bash

# 方法一：使用 nvm 管理 Node.js（推荐）
nvm install 20
nvm use 20
npm install -g @sleep2agi/agent-network

# 方法二：修改 npm 全局目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @sleep2agi/agent-network

7. 找不到 bun 命令

bash

# 安装 Bun
curl -fsSL https://bun.sh/install | bash

# 刷新 PATH
source ~/.bashrc
# 或
export PATH="$HOME/.bun/bin:$PATH"

# 验证
bun --version

8. anet hub start 报端口被占用

bash

# 查看谁占了端口
lsof -i :9200
# 或
ss -tlnp | grep 9200

# 换个端口
anet hub start --port 9201

# 或停掉占用的进程
kill <PID>

# anet hub stop 子命令（[#200](https://github.com/sleep2agi/agent-network/issues/200) v0.10.11 起 ship，已在 npm latest）
# SIGTERM → 3s → SIGKILL 兜底, 不用手动找 PID
anet hub stop          # 默认端口 9200
anet hub stop --port 8080

v0.10.11 起更简单

v0.10.11 (#200) 加了 anet hub stop 命令, 不用 lsof + kill <PID> 手动 hack。已在 npm latest，老用户跑 anet upgrade 即得。

9. 配置文件在哪里？

文件	路径	内容
全局配置	`~/.anet/config.json`	hub 地址、`utok_`、当前激活 network
节点配置	`{cwd}/.anet/nodes/<alias>/config.json`	runtime、model、tools、`ntok_`、env、flags（目录名是 alias，不是内部 `node_id`）
节点 env 文件（v0.10.10+）	`{cwd}/.anet/nodes/<alias>/.env`	envRef Option A 自动 source 的 API key（mode 0600；`anet node create` 写入，`anet node start` 启动前自动 source；详见 envRef wizard 自动衔接）
数据库	`~/.commhub/commhub.db`	hub 端 SQLite（WAL 模式）

Agent 问题

10. Agent 启动后状态一直是 offline

可能的原因：

网络不通：检查 Agent 能否访问 CommHub Server

bash

curl http://YOUR_IP:9200/health

Token 错误：检查 Token 是否有效

bash

anet whoami

防火墙：确保 9200 端口开放

bash

ufw allow 9200

心跳超时：如果 Agent 之前正常运行后崩溃，需要等 10 分钟超时或手动重启

11. Agent 处理任务后结果没有返回

检查 Agent 的消息类型处理逻辑：

task / broadcast 类型 -> AI 处理后回复（正确）
reply / message / ack 类型 -> 不处理（正确，避免 think 循环；详见 Task 生命周期 — 消息类型）

如果是 claude-code-cli runtime，检查项目根目录 CLAUDE.md 中是否有正确的回复规则（CLAUDE.md 是 Claude Code 自动加载的指令文件）。

12. 两个 Agent 互相发消息导致无限循环

这是消息类型设计的问题。确保：

发任务用 send_task（type=task）-> 触发 AI 处理
回复结果用 send_reply（type=reply）-> 不触发 AI 处理
日常聊天用 send_message（type=message）-> 不触发 AI 处理

如果仍然循环，检查 agent-node 是否只响应 new_task 和 broadcast 事件。

13. MiniMax Agent 报 API 错误

bash

# 检查 API Key 是否正确
curl -H "Authorization: Bearer $MINIMAX_API_KEY" \
  https://api.minimaxi.com/anthropic/v1/messages \
  -d '{"model":"<minimax-model-id>","max_tokens":100,"messages":[{"role":"user","content":"hi"}]}'
# 把 <minimax-model-id> 替换为你 MiniMax 账号当前可用的 model id（查 https://platform.minimaxi.com 控制台）

注意：

ANTHROPIC_BASE_URL 必须是 https://api.minimaxi.com/anthropic（注意 /anthropic 后缀）
MiniMax 用 ANTHROPIC_AUTH_TOKEN 传 Key（不是 ANTHROPIC_API_KEY——后者仅用于 api.anthropic.com 直连。两者职责区分详见 runtimes — claude-agent-sdk 常见坑）

14. 如何查看 Agent 的详细日志？

bash

# anet 启动的 Agent
anet logs 代码1号                # 最近一段
anet logs 代码1号 --follow       # 实时 tail（类似 tail -f）

# npx 启动的 Agent：直接看终端输出

# Docker 中的 Agent
docker compose logs -f worker-1

# CommHub Server 日志
docker compose logs -f server

网络和权限

15. utok_ 和 ntok_ 的区别？什么时候用哪个？

Token	用途	能做什么	不能做什么
`utok_`	CLI / Dashboard 登录	跨网络读取；在所属 network 内 role ≥ member 时可 MCP 写（owner / admin / member 可写，viewer 只读，详见 tokens 权限决策）	viewer 在该网络写、跨网络写非成员的 network
`ntok_`	Agent 连接	锁定的单网络内所有 member+ 权限操作（hub 强制锁 network_id）	跨网络

简记：人用 utok_，Agent 用 ntok_。

16. 怎么把 Agent 加入另一个网络？

bash

# 方法一：邀请码加入（推荐）
anet network use other-network
anet network invite --role member
# 把邀请码给对方
# 对方在自己机器上执行：anet network join inv_xxx

# 方法二：在目标机器本地注册 node（跨机部署，**不要 copy config.json**）
# 在目标机器上：
anet login --hub http://<hub-host>:9200 --username admin --password ...
anet network use other-network
anet node create other-agent                   # CLI 跟 hub 注册 + 拿独立 ntok_
anet node start other-agent

不要跨机 copy .anet/nodes/<name>/config.json

config 里的 node_id 是 hub 注册时分配的唯一 ID, 复制到另一台机器会让两台机器同时报告同一个 node, SSE 路由会乱. 详见 networks — 跨机器部署.

17. 怎么查看/管理网络成员？

bash

# 查看当前 network 成员（CLI）
anet network members

# 查看成员（REST 直查）
curl http://localhost:9200/api/networks/net_xxx/members \
  -H "Authorization: Bearer utok_xxx"

# 邀请新成员（owner/admin）
anet network invite --role member        # 生成邀请码（admin/member/viewer）

角色变更入口

当前 v0.10.x stable 线仍不提供 CLI promote / demote 子命令（changelog 整条线都未触碰 member role 管理）。改角色目前要通过 REST API /api/networks/:id/members/:user_id 调用或 Dashboard Admin 页（部分实装，详见 Dashboard Admin）。完整 CLI 入口排到 v0.11+ / 未排期。

17a. 怎么改密码？

bash

anet passwd                       # 交互式：输旧密码 → 输新密码 ≥ 8 字符 + 非弱密码字典

要求：≥ 8 字符 + 不在 password-dict.ts WEAK_PASSWORDS 字典里。anet passwd / anet hub admin reset-user 无任何长度豁免 —— 只有首次注册 admin（register 路径）才允许 ≥ 4，让 quick-start admin / anethub 默认成立（verify auth.ts:43-44）。

17b. 忘密码怎么办？

方案 A（推荐）：在 Hub 所在机器跑 admin reset：

bash

anet hub admin reset-user <username>   # 强制重置某用户密码，无需老密码
# → 生成随机新密码 + 撤销该用户全部 utok_ + 颁发新 utok_ + 写 audit_log password_reset_by_admin

方案 B（兜底，连 Hub 机器都不能登的极端情况）：直接改 SQLite + 删 admin marker：

bash

# 1. 删用户记录
sqlite3 ~/.commhub/commhub.db "DELETE FROM users WHERE username='admin'"

# 2. 关键：删 admin-utok.json marker（否则 anet hub start 会跳过 register 不重建）
rm -f ~/.anet/server/admin-utok.json

# 3. 重启 hub 触发 non-interactive bootstrap（输出 '✅ Admin account created'）
anet hub start

必须删 marker

anet hub start bootstrap 是 non-interactive 幂等的，幂等性靠 ~/.anet/server/admin-utok.json marker 文件。只 DELETE FROM users 不删 marker → hub start 看到 marker 还在直接跳过 register flow → admin 不会重建（输出 ✅ Admin already exists，但 db 里其实没 admin row）。详见 troubleshooting → 第二次 anet hub start 还重新 bootstrap admin？

⚠️ 方案 B 是兜底，会清掉用户记录 + audit_log 不记 reset 事件。生产建议方案 A。详见安全设计。

部署问题

18. Docker Compose 中 Worker 连不上 Server

确保：

Server 健康检查通过后再启动 Worker

yaml

depends_on:
  server:
    condition: service_healthy

使用 Docker 内部网络名（server:9200 而非 localhost:9200）
Seed 容器成功导出了 ntok_

bash

docker compose logs seed

19. Dashboard 部署到 Vercel 失败

必须使用 prebuilt 方式部署 —— 两步，顺序不能错：

bash

cd agent-network-dashboard
vercel build --prod                  # 本地 build，产物写入 .vercel/output
vercel deploy --prebuilt --prod      # 上传 .vercel/output

注意 第一步必须是 vercel build，不是 npm run build —— vercel deploy --prebuilt 只上传 .vercel/output 目录，而这个目录由 vercel build 生成；只跑 npm run build 的话 .vercel/output 是空的或上一次的旧产物。不在 Vercel 云端 build 既省构建费，也避免环境变量缺失。

20. PostgreSQL 支持如何？

当前 stable 暂不推荐 PostgreSQL

代码里有 DATABASE_URL=postgres://... 的入口，但当前 stable 上没有做过 PostgreSQL 的 E2E 验证，不建议生产使用。

当前请用默认的 SQLite（在 ~/.commhub/commhub.db）。SQLite 已经能跑到 100+ Agent 规模，单机部署足够。

注：v0.8+ 产品方向已转 SQLite only（见 docs/v3-postgresql-design.md banner），不在 maintained roadmap 上。adapter 接口保留作社区扩展点 —— HA / 多写副本场景需要 Postgres 的话，欢迎到 GitHub Discussions 讨论自部署方案。

性能问题

21. 任务响应慢

检查：

AI 模型延迟：不同模型响应时间不同
- Codex (codex-sdk)：3-15 秒
- Claude：5-30 秒
- MiniMax：1-5 秒
网络延迟：Agent 和 Server 之间的网络延迟
Server 负载：anet doctor 检查服务器状态
数据库大小：大量历史数据可能影响查询速度

22. SSE 连接经常断开

可能原因：

网络不稳定
反向代理超时设置太短
防火墙关闭了长连接
nginx proxy_buffering 默认 on（SSE 必须 off，否则事件被缓冲到 buffer 满才一次性送达）

断了 agent 会自己重连：#202 起，指数退避 1s → 30s 上限 + 重连即重 register + 1h 失败放弃。如果 hub 重启了 dashboard 看不到节点，参考 troubleshooting — Hub 重启后 Dashboard 看不到节点。

Nginx 配置建议：

nginx

location /events/ {
    proxy_pass http://127.0.0.1:9200;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  # rate limit 看真实 client IP
    proxy_read_timeout 86400;   # 24 小时
    proxy_buffering off;
    proxy_cache off;
}

# /api/* + /mcp 也建议透传 X-Forwarded-For 以便 audit_log 记录真实 IP
location / {
    proxy_pass http://127.0.0.1:9200;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;
}

rate limit IP 检测

hub 端 register / login 端点取 req.headers["x-forwarded-for"]?.split(",")[0] 作为 clientIP 喂给 checkRateLimit（server/src/index.ts:428 register / L443 login）。如果反代不设 X-Forwarded-For，所有请求会被认成同一个 IP（反代自身），rate limit 会误伤所有用户。

下一步

起步教程：

一键安装与起步 — 装好 anet 后第一个 agent
上手指南 — 完整安装到第一次跑

深入概念：

安全设计 — token / 密码 / 隔离
账号体系 — utok_ / ntok_ / 密码关系
架构概览 — 整体系统设计

升级和故障排查：

v0.7 → v0.8 升级指南 — admin bootstrap / 密码管理
故障排查 — 常见错误集合
anet doctor --fix — 自动 probe + 重发 ntok_

社区：

GitHub Issues — 报 bug / 功能建议
社区 — 加入讨论

FAQ ​

基础问题 ​

1. Agent Network 是什么？和 LangChain / CrewAI 有什么区别？ ​

2. 需要服务器吗？ ​

3. 免费吗？ ​

4. 支持哪些 AI 模型？ ​

5. 一个网络最多支持多少 Agent？ ​

安装和配置 ​

6. 安装时报权限错误（EACCES） ​

7. 找不到 bun 命令 ​

8. anet hub start 报端口被占用 ​

9. 配置文件在哪里？ ​

Agent 问题 ​

10. Agent 启动后状态一直是 offline ​

11. Agent 处理任务后结果没有返回 ​

12. 两个 Agent 互相发消息导致无限循环 ​

13. MiniMax Agent 报 API 错误 ​

14. 如何查看 Agent 的详细日志？ ​

网络和权限 ​

15. utok_ 和 ntok_ 的区别？什么时候用哪个？ ​

16. 怎么把 Agent 加入另一个网络？ ​

17. 怎么查看/管理网络成员？ ​

17a. 怎么改密码？ ​

17b. 忘密码怎么办？ ​

部署问题 ​

18. Docker Compose 中 Worker 连不上 Server ​

19. Dashboard 部署到 Vercel 失败 ​

20. PostgreSQL 支持如何？ ​

性能问题 ​

21. 任务响应慢 ​

22. SSE 连接经常断开 ​

下一步 ​

FAQ

基础问题

1. Agent Network 是什么？和 LangChain / CrewAI 有什么区别？

2. 需要服务器吗？

3. 免费吗？

4. 支持哪些 AI 模型？

5. 一个网络最多支持多少 Agent？

安装和配置

6. 安装时报权限错误（EACCES）

7. 找不到 bun 命令

8. anet hub start 报端口被占用

9. 配置文件在哪里？

Agent 问题

10. Agent 启动后状态一直是 offline

11. Agent 处理任务后结果没有返回

12. 两个 Agent 互相发消息导致无限循环

13. MiniMax Agent 报 API 错误

14. 如何查看 Agent 的详细日志？

网络和权限

15. utok_ 和 ntok_ 的区别？什么时候用哪个？

16. 怎么把 Agent 加入另一个网络？

17. 怎么查看/管理网络成员？

17a. 怎么改密码？

17b. 忘密码怎么办？

部署问题

18. Docker Compose 中 Worker 连不上 Server

19. Dashboard 部署到 Vercel 失败

20. PostgreSQL 支持如何？

性能问题

21. 任务响应慢

22. SSE 连接经常断开

下一步