AgentsDock
首页 文档 常见问题 Discord
  • English
  • 简体中文

入门

搭建指南 客户端安装 连接 agents 开始第一个会话

指南

功能指南 会话 Agent 之间通话 Share Chat Side chat Fork 会话 恢复会话 工作区 终端访问 查看与编辑代码 自动化 斜杠命令 定时任务 键盘快捷键 更新 语言 管理服务器

帮助

反馈问题

服务器参考

高级安装 要求 安装选项 端口与绑定地址 远程访问(Tailscale) token 服务模板 环境变量 文件位置 多服务器 备份与卸载

服务器参考

高级安装与配置

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

适用于 AgentsServer 1.0.x 发布版本。权威来源:AgentsServer 源码树、agentsdock --help 和已安装的原生辅助脚本。

要求

  • 主机:Linux,或 Apple 芯片的 macOS。不支持 Intel macOS;安装脚本会在做任何更改前停止。
  • Node.js/npm:用于 agentsdock CLI。需要 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)——日志

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

AgentsDock

为 agentic AI 研究而设计的 IDE。© 2026 AgentsDock

文档 支持 反馈问题 隐私 Discord ↗