文档

管理服务器

AgentsServer 是运行在你自己机器上的开源后端。下面的所有操作都在那台机器的终端里完成——是服务器，而不是运行应用的设备。

GitHub 上的 AgentsServer →

想查全部安装选项、环境变量、一台机器上的多个服务器或备份？请看服务器参考。

安装与更新

首次安装——克隆仓库并运行安装脚本：

git clone https://github.com/ZhengyiLuo/AgentsServer.git
cd AgentsServer
./install.sh

更新时，拉取代码并重新运行同一个安装脚本。它会换上新的运行时、重启服务，并保留你的令牌和状态：

git pull --ff-only
./install.sh

你也可以在应用里更新——设置 → 安装或更新 AgentsServer，或使用更新页面介绍的稳定版 / 测试版开关。

安装选项

• --port PORT——固定使用指定端口（默认 7850）。不指定时，若默认端口被占用，安装脚本会在后续 5 个空闲端口中选一个。
• --bind ADDRESS——绑定地址（默认 0.0.0.0，其他设备可以访问）。
• --allow-port-fallback / --no-port-fallback——允许或禁止回退到邻近端口。
• --release-version VERSION——安装指定的发布版本。
• --non-interactive——不出现任何提示；用于脚本化或通过 SSH 驱动的运行。
• --show-token——打印访问令牌并退出（见下文）。

要求：macOS（Apple 芯片）或 Linux，预装 uv（macOS 上 brew install uv），以及你计划使用的提供方 CLI 已安装并登录。tmux 可选——它支撑应用内终端和托管更新。

查看你的访问令牌

安装脚本结束时会打印一次令牌。之后随时想再看，在服务器上运行下面的命令——它只读取现有配置，不做任何更改：

./install.sh --show-token

添加服务器时把它粘贴到应用的访问令牌字段（参见搭建指南）。

确认正在运行

在服务器机器上：

curl http://127.0.0.1:7850/api/health

如果服务器要求令牌（运行 install.sh 后默认如此），以 bearer 请求头传入：

curl -H 'Authorization: Bearer YOUR_TOKEN' http://127.0.0.1:7850/api/health

响应会包含 tmux 和你的提供方 CLI 是否可用。在应用里，设置页显示同样的运行时检查，以及一个重启服务器（Restart server）按钮。

启动、停止、重启与日志

安装脚本会把 AgentsServer 注册为登录时自动启动的用户级服务。用你平台的服务管理器来管理它。

macOS——LaunchAgent 为 com.agentsdock.server：

# status
launchctl print gui/$(id -u)/com.agentsdock.server

# restart
launchctl kickstart -k gui/$(id -u)/com.agentsdock.server

# stop until next login / start again
launchctl bootout gui/$(id -u)/com.agentsdock.server
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agentsdock.server.plist

# logs
tail -f ~/Library/Logs/AgentsServer/server.log
tail -f ~/Library/Logs/AgentsServer/server-error.log

Linux——服务单元为 agents-server.service：

# status
systemctl --user status agents-server.service --no-pager -l

# restart / stop / start
systemctl --user restart agents-server.service
systemctl --user stop agents-server.service
systemctl --user start agents-server.service

# logs
journalctl --user -u agents-server.service -f

手动运行

开发时或不用服务只想跑一次，可以直接从仓库启动服务器：

uv venv && uv sync --frozen
uv run python agent_server.py serve --bind 0.0.0.0 --port 7850

在该 shell 中设置 AGENTSDOCK_AGENT_TOKEN 以要求令牌，设置 AGENTSDOCK_STATE_DIR 可把状态存放在 ~/.agentsdock 以外的位置。

卸载

./uninstall.sh

这会停止并移除服务、版本化的运行时，以及包括访问令牌在内的生成配置。做任何更改前都会先询问（--yes 跳过提示）。~/.agentsdock 下的会话、任务、文件和终端会保留，之后再运行 ./install.sh 会直接接管它们。

若要连同这些状态一起删除，加上 --purge-state——它总是要求你输入完整路径确认，且不可撤销。持久会话终端会作为 tmux 会话继续留在这台服务器的 tmux 服务上；tmux ls 可以列出它们。只关闭你确认属于本服务器会话终端的会话——机器上的其他 tmux 会话，以及任何命名服务器实例（它们使用各自的 tmux socket），都不受卸载默认服务器的影响。

设置与文件位置

服务器上各项内容的位置：

• ~/.agentsdock——会话历史、任务、文件、令牌（状态目录）。
• ~/.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——共享的访问令牌。
• AGENTSDOCK_STATE_DIR——状态目录（~/.agentsdock）。
• AGENTSDOCK_AGENT_CWD——新会话的默认工作目录（你的主目录）。
• AGENTSDOCK_BACKEND——默认后端，claude 或 codex。
• CLAUDE_BIN / CODEX_BIN——命令行工具不在 PATH 中时的可执行文件路径。

完整列表（包括任务并发和内存保护）见 README 的配置表。