服务器参考
高级安装与配置
安装和配置 AgentsServer 的完整参考。日常命令(更新、token、重启、日志)见管理服务器;首次搭建的分步教程见搭建指南。
要求
- 主机:Linux,或 Apple 芯片的 macOS。不支持 Intel macOS;安装脚本会在做任何更改前停止。
- Node.js/npm:用于
agentsdockCLI。需要 Node.js 22.14 或更高版本。 - 服务器的
PATH中已安装uv,并在 npm 安装前用uv --version验证。它管理隔离的 Python 环境和依赖,客户端不需要它。macOS 已安装 Homebrew 时,用brew install uv;Linux 或其他方式见 uv 官方安装指南。AgentsDock 不会自动安装 uv,检查失败时请看问题排查。 - 你计划使用的提供方 CLI(Claude Code、Codex、OpenCode 或 Cursor)已在主机上安装并登录,且与运行服务器的是同一个用户账号。
- tmux(可选)——启用应用内终端、实时窗格查看和应用内托管更新。装有 Homebrew 的 macOS 上,安装脚本会询问是否代为安装;否则打印安装命令并继续。
- Tailscale(强烈推荐)。设备和服务器不在同一 Wi-Fi 或局域网时需要使用,除非你已有能让设备访问服务器的 VPN 或私有网络。
- 可用的用户服务会话:
launchctl(macOS)或systemctl --user(Linux)。全程不使用sudo。
CLI 安装选项
# 标准默认 setup npm install -g agentsdock # 自定义 setup AGENTSDOCK_SKIP_SETUP=1 npm install -g agentsdock agentsdock setup [--port PORT] [--bind IP] [--non-interactive] [--dry-run]
--port PORT——固定使用指定端口。不指定时默认为7850。--bind ADDRESS——监听地址。默认0.0.0.0(所有网卡,其他设备可连接)。--non-interactive——从不提示(跳过 tmux 安装询问和剪贴板复制)。用于脚本和通过 SSH 驱动的运行。--dry-run——打印实际会执行的原生安装命令,但不执行。
全局安装只会在没有既有安装或状态时创建新的默认用户级服务,标准安装不需要 clone repo。已有服务器会保持不变;请从应用的设置 → 更新里更新。单独在项目里运行 npm install agentsdock 只会添加依赖,不会创建服务。运行中的服务也不会从 npm cache 中执行。
安装完成后,查看 token 用 agentsdock token,卸载默认服务器用 agentsdock remove default,命名实例用 agentsdock new / agentsdock list。原生辅助脚本仍位于 ~/.local/share/agents-server/current,供高级排查使用。
端口与绑定地址
如果默认端口已被某个不是待替换 AgentsServer 的进程占用,安装脚本会报告该监听进程(可用时借助 lsof),并在向上最多五个空闲端口中选一个。所选端口会在运行结束时打印。
--port会固定该端口,被占用时直接失败。
绑定到 0.0.0.0(默认)以接受其他设备的连接;只有应用与服务器在同一台机器上时才绑定 127.0.0.1。绑定到回环地址的服务器无法通过 Tailscale 访问。
远程访问(Tailscale)
远程访问强烈推荐使用 Tailscale。设备和服务器不在同一 Wi-Fi 或局域网时,需要使用它,除非你已有能让设备访问服务器的 VPN 或私有网络。同一局域网内可以直接使用服务器的局域网 IP。安装器不会强制要求 Tailscale,但安装成功并不代表其他网络上的设备就能访问服务器。
在服务器上:
tailscale status tailscale ip -4
在每台设备上加入同一个 tailnet,然后使用服务器 URL:
http://<tailscale-ip>:7850
如果设备上的浏览器能打开 /api/health 但应用连不上,请检查:设备已连接 Tailscale、URL 带有端口、应用里填的是同一个 token,以及服务器绑定的是 0.0.0.0(而不只是 127.0.0.1)。
切勿把 7850 端口暴露到公网。使用 Tailscale 或其他私有网络,并保持 token 启用。
token
安装脚本会生成一个私有的 bearer token。每个 HTTP 调用、上传、文件/视频获取和 WebSocket 流都需要它。随时可以这样取回:
agentsdock token
客户端以 Authorization: Bearer <token>(或 X-AgentsDock-Token 请求头)发送它。如需在服务器机器上做低层健康检查:
curl -H 'Authorization: Bearer YOUR_TOKEN' http://127.0.0.1:7850/api/health
服务模板
安装脚本会为你创建并管理用户服务:macOS 上是 LaunchAgent com.agentsdock.server,Linux 上是 agents-server.service。只有自定义部署才需要下面的模板。
mkdir -p ~/.config/systemd/user cp systemd/agents-server.service.example ~/.config/systemd/user/agents-server.service systemctl --user daemon-reload systemctl --user enable --now agents-server.service systemctl --user status agents-server.service --no-pager -l
两个平台的启动、停止、重启和日志命令见管理服务器。
环境变量
大多数设置都是服务器读取的环境变量。新配置请使用 AGENTSDOCK_* 名称;历史上的 ZENITHBOT_* / ZENITHDOCK_AGENT_TOKEN 仅作为兼容别名接受。括号内为默认值。
网络与访问
AGENTSDOCK_AGENT_BIND——绑定地址(0.0.0.0)AGENTSDOCK_AGENT_PORT——端口(7850)AGENTSDOCK_AGENT_TOKEN——共享的 bearer token(未设置)
路径
AGENTSDOCK_STATE_DIR——会话、任务和文件状态(~/.agentsdock)AGENTSDOCK_AGENT_CWD——新会话的默认工作目录(你的主目录)AGENTS_SERVER_INSTALL_DIR——版本化运行时根目录(~/.local/share/agents-server)CLAUDE_PROJECTS_ROOT——Claude 历史搜索根目录(~/.claude/projects)CODEX_SESSIONS_ROOT——Codex 历史搜索根目录(~/.codex/sessions)
后端
AGENTSDOCK_BACKEND——默认后端,claude或codex(claude)CLAUDE_BIN/CODEX_BIN——可执行文件名或路径(claude/codex)AGENTSDOCK_CLAUDE_TRANSPORT——交互式 Claude 传输方式:auto、agent-sdk或print(auto)AGENTSDOCK_CLAUDE_SDK_IDLE_TTL_SECONDS——每个会话的 SDK 客户端空闲保留时间(300)AGENTSDOCK_CLAUDE_SDK_MAX_LOADED_CHATS——最多保留的会话 SDK 客户端数(4)AGENTSDOCK_RUNTIME_CATALOG_TIMEOUT_SECONDS——每条命令的 CLI 版本/帮助/模型探测超时(6)AGENTSDOCK_CLAUDE_AUTH_PROBE_TIMEOUT_SECONDS——claude auth status的超时(15)AGENTSDOCK_RUNTIME_DIAGNOSTIC_TTL_SECONDS——CLI 版本/登录探测结果的缓存时长(60)
任务与保护
AGENTSDOCK_JOB_MAX_ACTIVE_RUNS——定时任务并发上限;0表示不限(0)AGENTSDOCK_MAX_ACTIVE_AGENT_RUNS——会话、定时和目标运行的全服务器上限;0= 不限(0)AGENTSDOCK_JOB_MIN_AVAILABLE_MEM_MB——任务启动的内存保护阈值(4096)AGENTSDOCK_MIN_START_AVAILABLE_MEM_MB——交互式启动的内存保护阈值(2048)AGENTSDOCK_CODE_DIFF_SNAPSHOT_TIMEOUT_SECONDS——每次隔离 Git worktree 快照的最长时间(120)
上下文摘要
AGENTSDOCK_HANDOFF_DIGEST_BACKEND——claude或codex(claude)AGENTSDOCK_HANDOFF_DIGEST_MODEL——模型(sonnet)AGENTSDOCK_HANDOFF_DIGEST_EFFORT——可选的推理/努力程度设置(未设置)AGENTSDOCK_HANDOFF_DIGEST_TIMEOUT_SECONDS——摘要生成超时(180)AGENTSDOCK_HANDOFF_DIGEST_CHARS——最终摘要的字符上限(56000)
文件位置
~/.agentsdock——状态:会话、任务、文件、上传、token、安全对等凭据~/.config/agents-server/env——生成的服务配置和 token~/.local/share/agents-server/releases/<version>——版本化的发布;~/.local/share/agents-server/current指向当前生效的版本~/Library/Logs/AgentsServer/(macOS)·journalctl --user -u agents-server.service(Linux)——日志
命名实例使用各自的同级路径——见每个实例的位置。