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

入门

搭建指南 开始之前 第一步 · 搭建远程机器 第二步 · 连接你的设备 排查问题 客户端安装 连接 agents 开始第一个会话

指南

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

帮助

反馈问题

服务器参考

高级安装 多服务器 备份与卸载

文档

搭建指南

最后更新:2026 年 10 月 14 日 · 约需 15 分钟

  • AgentsServer 在你自己的远程机器上执行实际工作。
  • AgentsDock 客户端运行在你的设备上并连接到这台服务器;远程机器搭建一次,之后想连多少设备都可以。

开始之前

  • 一台由你掌控的远程机器(Linux,或 Apple silicon Mac)来运行服务器,已安装 Node.js 22.14 或更高版本及 npm。tmux 是可选的,只有应用内终端需要它。
  • 服务器机器上已安装 uv。它管理服务器的 Python 环境和依赖,AgentsDock 不会自动安装它。具体步骤见下方的先安装 uv。
  • 一个 Tailscale 账号(强烈推荐)。设备和服务器不在同一 Wi-Fi 或局域网时,需要使用 Tailscale,除非你已有能让设备访问服务器的 VPN 或私有网络。同一局域网内可以直接使用服务器的局域网 IP。
  • 在远程机器上安装你计划使用的 provider 对应的 CLI 命令行工具:Claude Code、Codex、OpenCode、Cursor 或 Gemini。各 provider 的配置方式见连接 agents。
  • 一台能运行 AgentsDock 客户端的设备:macOS、Windows、Linux、iPhone、iPad 或 Android。

AgentsDock 是完全自托管的。你的会话、文件和 API 密钥都留在你的远程机器上——应用只是一个查看窗口。

第一步搭建远程机器

在负责执行工作的那台机器上做一次即可。它会持续运行,你的各个设备都连接到它。

1安装 AgentsServer

先安装 uv。只有运行服务器的机器需要它,手机或只用作客户端的电脑不需要。macOS 已安装 Homebrew 时,运行:

brew install uv
uv --version

Linux 或其他安装方式请参考 uv 官方安装指南。在同一个终端里确认 uv --version 能打印版本号,再继续下一步。

然后在远程机器上,用将要运行服务器的用户安装 AgentsDock CLI:

npm install -g agentsdock

在一台新机器上,这个命令也会创建并启动默认服务器。标准安装不需要 clone repo。不要使用 sudo。

npm 可能隐藏安装成功时的提示。安装时使用 npm install -g agentsdock --foreground-scripts 可以显示这些信息。已发布的 1.0.10 CLI 只打印简短摘要,不会直接展示安装器的完整输出或 token。

使用 --foreground-scripts 时的安装提示示例,省略了 npm 自身的信息,实际地址可能不同:

agentsdock: Setting up your first AgentsDock server. This may take a few minutes.
agentsdock: Server 1.0.10 is ready at http://100.100.100.12:7850. Open AgentsDock to connect. Use agentsdock token to view/copy its private token.

服务器默认监听 7850 端口,并在远程机器上持续运行——你的设备连接的就是它。

安装结束后,确认 default 的状态是 running,并查看连接地址:

agentsdock list

以下示例已连接 Tailscale。实际地址取决于你的网络和服务器绑定设置:

NAME                 STATUS     PORT
default              running    7850
  Tailscale / other networks: http://100.100.100.12:7850 (recommended)
  Same Wi-Fi / LAN:          http://192.168.1.23:7850
  This machine only:         http://127.0.0.1:7850

同一局域网内使用 LAN 地址,跨网络时使用私有 Tailscale 网络中的地址。127.0.0.1 只能在服务器本机使用。

单独查看默认服务器的 token,并妥善保管:

agentsdock token default

以下是支持剪贴板的本地终端输出示例,其中的 token 是占位文本,不是真实凭据:

Access token (default):
ad_tok_EXAMPLE_ONLY_DO_NOT_USE

Copy token to this machine's clipboard? [y/N]

只把你自己的真实 token 粘贴到应用中。通过 SSH 或终端不支持剪贴板时,请手动复制 token 那一行。

更多运行信息可用 agentsdock status 查看。重启、更新和卸载等命令见管理服务器。

在 GitHub 上查看 AgentsServer 源码 →

2连接你的 agent provider

安装并登录你要让 AgentsDock 使用的提供方 CLI:Claude Code、Codex、OpenCode 或 Cursor。按提供方支持的正常方式登录即可,例如浏览器登录或配置 API key。自定义 endpoint 的配置见连接 agents。

Gemini 使用 API 连接,而不是 Google 账号或 CLI 登录。服务器上仍需安装兼容版本的 Gemini CLI 命令行工具。按照连接 Gemini API中的说明安装,并在桌面客户端配置 API key。

3在远程机器上安装 Tailscale

强烈推荐。设备和服务器不在同一 Wi-Fi 或局域网时,需要使用 Tailscale,除非你已有能连通两端的 VPN 或私有网络。使用已有的网络时可以跳过这一步;如果两端在同一局域网内,也可以直接使用服务器的局域网 IP。

在远程机器上安装 Tailscale 并登录。这会给机器分配一个私有的 100.x.x.x 地址,你的其他设备可以从任何地方访问它——无需向公网开放任何端口。记下这个地址(或机器的 Tailscale 主机名),第二步会用到。

有不止一台机器?在每台机器上重复第一步。AgentsDock 可以同时保存多个服务器——它们都会出现在侧边栏顶部的服务器菜单里,一键即可切换。

The server menu at the top of the AgentsDock sidebar listing three servers, with Add Server and Server Settings below
服务器菜单列出你添加的所有服务器。绿点表示可以连上。

第二步从你的设备连接

在你想作为 AgentsDock 客户端使用的每台设备上重复以下步骤。

1下载 AgentsDock 客户端

到下载区选择你的平台(macOS、Windows、Linux、iPhone、iPad 或 Android),下载并打开客户端。

2在设备上安装 Tailscale

跨 Wi-Fi 或局域网连接时,强烈推荐使用 Tailscale。选择 Tailscale 后,在这台设备上也安装它,并用与服务器相同的账号登录,两端都保持连接。只有当两端在同一局域网内,或你已有能让这台设备访问服务器的 VPN 或私有网络时,才可以跳过这一步。

3连接到你的服务器

在 AgentsDock 中添加服务器,填入远程机器的地址——它的 Tailscale 100.x.x.x 地址加端口 7850——然后把第一步得到的 token 粘贴到token字段。它长这样:

ad_tok_9f3b7c2e••••••••••••••••••••   (sample)

这个 token 存放在你的服务器机器上——也就是第一步搭建的远程机器,而不是你正在用来连接的设备。想再次获取,在远程机器上运行:

agentsdock token default

点击测试连接(Test connection)确认应用能连到服务器,再点添加并切换(Add & switch)。连接成功后:新建一个会话,选择一个提供方,并指定远程机器上的一个工作目录。

AgentsDock connection form on macOS with the Access token field, a Test connection button, and Add and switch
把 token 粘贴到token字段,保存前先点击测试连接验证。
AgentsDock Settings on macOS showing a connected Mac Mini server and a Runtimes & prerequisites panel with tmux and provider CLI status
连接后,应用的设置页可以监控连接状态,并检查服务器上的 tmux 和提供方 CLI 是否就绪。

要连接不止一台机器?用同样的方法逐个添加——打开侧边栏顶部的服务器菜单,选择 Add Server。之后你随时可以在该菜单里切换服务器。

在侧边栏顶部的菜单里切换服务器——每个服务器都保留自己的会话。

排查问题

uv 未安装或无法运行

如果安装时提示 A trusted uv installation is required on PATH.,表示 uv 未安装、不在 PATH 中,或无法运行。请安装 uv,在同一个终端里确认 uv --version 正常,再重试并显示状态信息:

npm install -g agentsdock --foreground-scripts

这个前置依赖错误不需要修改配置或删除文件。如果 uv 正常后安装仍失败,请通过问题反馈提供新的诊断输出,并移除 token 等凭据。

连不上?

  • 确认在同一台设备的浏览器里能打开服务器 URL——浏览器打不开的话,应用也连不上。
  • 检查两端的 Tailscale 都已开启并登录,并且你用的是远程机器的 100.x.x.x Tailscale 地址(而不是只在远程机器自己网络里有效的局域网 IP)。
  • 确保 URL 带了端口(7850),且 token 完全一致、没有多余空格。

还是不行?前往支持页面,或在我们的 Discord 提问。

连接好了?到功能指南看看 AgentsDock 能做什么 →

AgentsDock

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

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