服务器参考

高级安装与配置

安装和配置 AgentsServer 的完整参考。日常命令（更新、令牌、重启、日志）见管理服务器；首次搭建的分步教程见搭建指南。

适用于 AgentsServer 1.0.x 发布版本。权威来源：AgentsServer 仓库和 ./install.sh --help。

要求

主机：Linux，或 Apple 芯片的 macOS。不支持 Intel macOS；安装脚本会在做任何更改前停止。
uv 预装在 PATH 中（macOS 上 brew install uv；Linux 上用发行版的包管理器）。它负责准备隔离的 Python 3.10+ 运行时。安装脚本从不下载引导脚本。
你计划使用的提供方 CLI（Claude Code、Codex 或 Cursor）已在主机上安装并登录，且与运行服务器的是同一个用户账号。
tmux（可选）——启用应用内终端、实时窗格查看和应用内托管更新。装有 Homebrew 的 macOS 上，安装脚本会询问是否代为安装；否则打印安装命令并继续。
Tailscale（可选）——让其他设备无需暴露端口即可访问服务器。
可用的用户服务会话：launchctl（macOS）或 systemctl --user（Linux）。全程不使用 sudo。

安装选项

./install.sh [--port PORT] [--bind ADDRESS] [--release-version VERSION]
             [--non-interactive] [--allow-port-fallback | --no-port-fallback]
             [--show-token] [--instance NAME]

--port PORT——固定使用指定端口。不指定时默认为 7850。
--bind ADDRESS——监听地址。默认 0.0.0.0（所有网卡，其他设备可连接）。
--release-version VERSION——安装指定的已发布版本而非最新版。
--non-interactive——从不提示（跳过 tmux 安装询问和剪贴板复制）。用于脚本和通过 SSH 驱动的运行。
--allow-port-fallback / --no-port-fallback——控制是否自动选择邻近端口（见下文）。
--show-token——打印访问令牌并退出，不重新安装也不重启。
--instance NAME——对命名实例而非默认服务器执行操作。参见多服务器。

每次运行都是幂等的：保留上一个健康版本以便回滚，保留访问令牌和配置，绝不触碰会话状态。运行失败时当前生效版本保持不变，并打印恢复指引。安装锁可防止被取消的 SSH 尝试与重试互相竞争。

端口与绑定地址

如果默认端口已被某个不是待替换 AgentsServer 的进程占用，安装脚本会报告该监听进程（可用时借助 lsof），并在向上最多五个空闲端口中选一个。所选端口会在运行结束时打印。

单独使用 --port 会固定该端口，被占用时直接失败。
--port … --allow-port-fallback 允许显式指定的端口回退到邻近的空闲端口。
--no-port-fallback 同样禁用默认端口的回退。

绑定到 0.0.0.0（默认）以接受其他设备的连接；只有应用与服务器在同一台机器上时才绑定 127.0.0.1。绑定到回环地址的服务器无法通过 Tailscale 访问。

远程访问（Tailscale）

远程访问推荐走 Tailscale，这样手机、平板和笔记本都能访问服务器，而无需把端口发布到互联网。它是可选的；主机上没有 Tailscale 时，安装脚本只会打印一条提醒。

在服务器上：

tailscale status
tailscale ip -4

在每台设备上加入同一个 tailnet，然后使用服务器 URL：

http://<tailscale-ip>:7850

如果设备上的浏览器能打开 /api/health 但应用连不上，请检查：设备已连接 Tailscale、URL 带有端口、应用里填的是同一个访问令牌，以及服务器绑定的是 0.0.0.0（而不只是 127.0.0.1）。

切勿把 7850 端口暴露到公网。使用 Tailscale 或其他私有网络，并保持访问令牌启用。

访问令牌

安装脚本会生成一个私有的 bearer 令牌并打印一次。每个 HTTP 调用、上传、文件/视频获取和 WebSocket 流都需要它。随时可以这样取回：

./install.sh --show-token

客户端以 Authorization: Bearer <token>（或 X-AgentsDock-Token 请求头）发送它。手动运行服务器时，请自行设置 AGENTSDOCK_AGENT_TOKEN；只有在可信的本地开发环境中才可以不设置。

手动安装与运行

如果你不想用安装脚本或服务，可以直接从代码检出目录运行服务器：

git clone https://github.com/ZhengyiLuo/AgentsServer.git
cd AgentsServer
uv venv
uv sync --frozen

# confirm the CLIs work in this same shell/user
command -v claude && claude --version
command -v codex  && codex --version

export AGENTSDOCK_AGENT_TOKEN='replace-with-a-long-random-token'
uv run python agent_server.py serve --bind 0.0.0.0 --port 7850

在服务器机器上检查：

curl -H 'Authorization: Bearer replace-with-a-long-random-token' http://127.0.0.1:7850/api/health

用 AGENTSDOCK_STATE_DIR 把状态存放在 ~/.agentsdock 以外的位置；只安装了其中一个命令行工具时，设置 AGENTSDOCK_BACKEND。

服务模板

安装脚本会为你创建并管理用户服务：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 令牌（未设置）

路径

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——状态：会话、任务、文件、上传、令牌、安全对等凭据
~/.config/agents-server——生成的配置和访问令牌
~/.local/share/agents-server——版本化的发布；current 指向当前生效的版本
~/Library/Logs/AgentsServer/（macOS）· journalctl --user -u agents-server.service（Linux）——日志

命名实例使用各自的同级路径——见每个实例的位置。