文档
管理服务器
AgentsServer 是运行在你自己机器上的开源后端。下面的所有操作都在那台机器的终端里完成——是服务器,而不是运行应用的设备。
全程不需要 sudo。安装脚本以你的用户身份运行,保留上一个健康版本以便回滚,并在每次更新中保留你的会话历史、任务、文件和 token。
安装与更新
安装前:服务器机器需运行 macOS(Apple 芯片)或 Linux,并安装 Node.js 22.14 或更高版本、npm 和 uv。AgentsDock 不会自动安装 uv。macOS 已安装 Homebrew 时,运行 brew install uv;Linux 或其他安装方式见 uv 官方安装指南。
在同一个终端里确认 uv --version 正常,再用将要运行服务器的用户安装 AgentsDock CLI:
npm install -g agentsdock
在一台新机器上,全局安装会创建默认用户级服务,并把运行时安装到 ~/.local/share/agents-server。标准安装不需要 clone repo。不要使用 sudo。本地 npm install agentsdock 只会添加项目依赖,不会创建服务器服务。
安装后运行 agentsdock list,确认 default 正在运行并查看 URL,再用 agentsdock token default 查看 token。npm 可能隐藏安装提示,具体见连接信息输出示例。
更新已有服务器时,在应用里操作:打开设置 → 更新,点击 Check now,然后在出现时使用 Update server 或 Retry server update。托管更新会换上新的运行时、重启服务,并保留你的 token 和状态。
自定义安装选项
AGENTSDOCK_SKIP_SETUP=1 npm install -g agentsdock agentsdock setup [--port PORT] [--bind ADDRESS] [--non-interactive] [--dry-run]
--port PORT——固定使用指定端口(默认7850)。--bind ADDRESS——绑定地址(默认0.0.0.0,其他设备可以访问)。--non-interactive——不出现任何提示;用于脚本化或通过 SSH 驱动的运行。--dry-run——打印实际会执行的原生安装命令,但不执行。
在服务器上安装并登录你计划使用的提供方 CLI。tmux 可选——它支撑应用内终端和托管更新。如果安装时提示 PATH 中需要 uv,见 uv 问题排查。
如果旧服务器在 1.0.4 迁移期间中断,在服务器机器上运行 agentsdock recover,然后回到应用里选择 Retry server update。
查看你的 token
之后随时想看 token,在服务器上运行下面的命令——它只读取现有配置,不做任何更改:
agentsdock token default
命名服务器请把 default 换成对应名称。不带名称运行 agentsdock token,可以交互选择服务器。
添加服务器时把它粘贴到应用的token字段(参见搭建指南)。
确认正在运行
在服务器机器上:
agentsdock status
它会显示每个服务器实例的状态、地址、已安装版本和端口。只看某个命名实例时,运行 agentsdock status NAME。在应用里,设置页显示同样的运行时检查,以及一个重启服务器(Restart server)按钮。
Server (default):
Status: running
Address: http://100.100.100.12:7850 (Tailscale / other networks)
http://192.168.1.23:7850 (Same Wi-Fi / LAN)
http://127.0.0.1:7850 (This machine only)
Version: 1.0.10
Port: 7850
启动、停止与重启
安装脚本会把 AgentsServer 注册为登录时自动启动的用户级服务。日常服务控制直接使用 AgentsDock CLI:
# default server agentsdock restart default agentsdock stop default agentsdock start default # named instance agentsdock restart work
日常检查优先用 agentsdock status 或应用里的设置页;只有排查问题时才需要直接看日志:
# macOS tail -f ~/Library/Logs/AgentsServer/server.log tail -f ~/Library/Logs/AgentsServer/server-error.log # Linux journalctl --user -u agents-server.service -f
卸载
agentsdock remove default
这会停止并移除服务、版本化的运行时,以及包括 token 在内的生成配置。做任何更改前都会先询问(--yes 跳过提示)。~/.agentsdock 下的会话、任务、文件和终端会保留,之后重新安装会直接接管它们。
若要连同这些状态一起删除,加上 --purge-state——它总是要求你输入完整路径确认,且不可撤销。持久会话终端会作为 tmux 会话继续留在这台服务器的 tmux 服务上;tmux ls 可以列出它们。只关闭你确认属于本服务器会话终端的会话——机器上的其他 tmux 会话,以及任何命名服务器实例(它们使用各自的 tmux socket),都不受卸载默认服务器的影响。
设置与文件位置
服务器上各项内容的位置:
~/.agentsdock——会话历史、任务、文件、token(状态目录)。~/.config/agents-server/env——生成的服务配置,包括 token。~/.local/share/agents-server/releases/<version>——版本化的服务器发布;~/.local/share/agents-server/current指向当前生效的版本。~/Library/Logs/AgentsServer/(macOS)或journalctl --user(Linux)——日志。
大多数设置都是环境变量。你最可能用到的有:
AGENTSDOCK_AGENT_PORT/AGENTSDOCK_AGENT_BIND——端口(7850)和绑定地址(0.0.0.0)。AGENTSDOCK_AGENT_TOKEN——共享的 token。AGENTSDOCK_STATE_DIR——状态目录(~/.agentsdock)。AGENTSDOCK_AGENT_CWD——新会话的默认工作目录(你的主目录)。AGENTSDOCK_BACKEND——默认后端,claude或codex。CLAUDE_BIN/CODEX_BIN——命令行工具不在PATH中时的可执行文件路径。
完整列表(包括任务并发和内存保护)见 server 源码树。
保持私有。不要把 7850 端口暴露到公网。通过 Tailscale 或其他私有网络访问服务器,并保持 token 启用。