这个教程解决什么问题

读完这篇你能做到：选对适合自己设备的安装路线，完成 AgentDock 的部署，验证 8765 端口服务正常，配好访问 Token，并避开新手最常见的三个坑。

AgentDock 是让 AI Agent 操作真实机器的 MCP 运行时，安装过程不复杂，但路线选择会影响后续体验——容器适合常驻，原生安装适合开发机。先选路线，再动手。

路线怎么选

你的场景推荐路线理由
NAS / VPS / 家用服务器Docker 容器常驻运行、升级方便、环境隔离
macOS 日常开发机原生安装直接操作本机文件和开发环境
Windows 工作站原生安装（PowerShell）官方提供 PS 脚本和原生二进制
需要 GPU 跑模型GPU 容器镜像官方镜像自带 GPU 支持

原则很简单：这台机器是「干活的工人」就用容器常驻，是「你每天用的桌子」就原生安装。

路线一：Docker 部署（推荐服务器用户）

官方镜像在 Docker Hub：agentdockio/agentdock。最小化启动：

docker run -d \
  --name agentdock \
  -p 8765:8765 \
  -v agentdock_data:/data \
  -e AGENTDOCK_TOKEN=换成你的长随机Token \
  agentdockio/agentdock:latest

三个关键点：

  1. 端口 8765 是 MCP Streamable HTTP 的默认入口，AI 客户端全部通过这个端口连接
  2. AGENTDOCK_TOKEN 是访问凭证，务必换成长随机字符串（可以用 openssl rand -hex 32 生成），不要用示例值
  3. 数据卷 把工作区和配置持久化到宿主机，容器升级不丢数据

启动后验证服务：

curl -s http://127.0.0.1:8765/mcp -o /dev/null -w "%{http_code}\n"

返回 4xx（比如 401）说明服务活着且认证在工作——MCP 端点会拒绝没有 Token 的请求，这是正常现象。直接返回 200 反而要检查一下是不是忘了配 Token。

路线二：macOS / Linux 原生安装

macOS 和 Linux 用官方安装脚本：

curl -fsSL https://raw.githubusercontent.com/uvwt/agentdock/main/install.sh | bash

脚本完成后，运行自检命令确认环境就绪：

agentdocks doctor

doctor 是 AgentDock 自带的体检命令，会检查运行时依赖、工作区目录、网络连通性。第一次部署后跑一遍，输出里的每一项都过再往下走。

路线三：Windows 安装

Windows 用户走 PowerShell：

# 以管理员或当前用户身份执行官方安装脚本
irm https://raw.githubusercontent.com/uvwt/agentdock/main/install.ps1 | iex

装完同样用 agentdocks doctor 自检。Windows 下有两个平台特有的注意点：

  • 执行策略：如果 PowerShell 报脚本禁止运行，先 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 再装
  • 路径权限：AgentDock 的工作区目录默认在用户目录下，如果想让 AI 操作其他盘符的目录，需要在配置里显式添加，不要为了省事把整个磁盘设为工作区

核心环境变量速查

变量作用建议
AGENTDOCK_HOME数据与配置的根目录容器部署时挂载持久化
AGENTDOCK_TOKEN客户端访问凭证必配，长随机串
AGENTDOCK_NO_AUTH关闭认证仅限本机调试，绝不暴露到网络
AGENTDOCK_ALLOWED_ORIGINS来源白名单Web 客户端场景必配
AGENTDOCK_ADMIN_TOKEN管理接口凭证与普通 Token 分开，权限最小化

这套变量设计遵循一个原则：认证默认开启，放开任何限制都需要显式操作。 这比很多工具「默认裸奔、安全靠自觉」的做法靠谱得多。

三个常见坑

坑一：客户端连不上 8765。 大概率是防火墙或绑定地址问题。Docker 部署确认 -p 8765:8765 映射正确；云服务器确认安全组放行；本机调试先确认 curl 能通再怀疑客户端配置。

坑二：Token 配了还是 401。 检查 Token 是否带引号、前后空格传进去了。环境变量里的引号会被当作值的一部分，这是 Docker 新手的经典错误。

坑三：容器升级后工作区丢失。 没挂载数据卷。AgentDock 的工作区、Skills、任务状态都在 AGENTDOCK_HOME 下，升级镜像前确认这个路径已经用 -v 挂到宿主机。

端点验证速查

装完别急着接客户端，先把服务对外的几个入口都验一遍：

入口本机验证方式预期表现
/mcpcurl -s http://127.0.0.1:8765/mcp无 Token 返回 4xx，说明认证在工作
/artifacts带 Token 请求任务制品的存取入口
/wsWebSocket 客户端连接长连接入口

哪条不对，先跑 agentdocks doctor 看缺了哪个依赖，再回头查配置——顺序别反。

安装 FAQ

Q：忘了 AGENTDOCK_TOKEN 怎么办？

Docker 部署可以 docker inspect agentdock | grep AGENTDOCK_TOKEN 找回启动时注入的值；原生安装查环境变量或启动脚本。不想找回就直接换新 Token 重启，客户端同步改一遍。

Q：8765 端口被占用了怎么办？

Docker 改宿主机侧映射即可：-p 18765:8765，容器内仍是 8765，客户端 URL 里换用新端口。原生安装则腾出占用进程，或查看配置项调整端口。

Q：NAS、树莓派这类 ARM 设备能装吗？

优先考虑 Docker 路线。先用 docker manifest inspect agentdockio/agentdock:latest 确认镜像是否提供你设备的架构，有就按前文的 docker run 命令起；没有就放 x86 机器上跑，别硬来。

Q：Docker 和原生安装能共存吗？

能，而且推荐。原生节点管开发环境，容器节点当「随便折腾」的实验工人，两个工作区互不干扰——这正是多设备编排里「单机多角色」玩法的起点。

Q：容器起来但 curl 一直不通？

按顺序查三层：docker ps 确认容器在跑且 8765 映射存在；docker logs agentdock 看启动日志有没有报错；宿主机防火墙放行端口。三层查完基本能定位，别跳步。

Q：GPU 镜像怎么起？

宿主机先装好 NVIDIA 容器运行时（nvidia-container-toolkit），然后 docker run 加 --gpus all 参数，其余参数不变。启动后 agentdocks doctor 里能看到 GPU 相关项是否就绪。

Q：升级会丢数据吗？

AGENTDOCK_HOME 挂了卷就不会丢。Docker 的升级三步：docker pull 新镜像、删旧容器、用原参数重新 docker run——所以第一次的启动命令务必留档，升级就是原样重放。

Q：日常怎么备份？

备份 AGENTDOCK_HOME 挂载到宿主机的目录即可，工作区、Skills、任务状态都在里面。容器可以随时删掉重建，卷还在就什么都在。

部署完的下一步

装好只是开始。接下来建议按这个顺序玩：

  1. 把它接入你的 AI 客户端——AgentDock 接入 ChatGPT、Claude Code、Codex 的完整配置
  2. 试试多设备玩法——一个对话操控 Mac、VPS 和容器
  3. 多台设备多了以后，上中心控制台——NexusDock 部署教程

MCP 生态的客户端接入方式各有细节，如果你在用 Cursor 或 Claude Code，也可以参考本站的 Cursor 接入 MCP 教程和 Claude Code MCP 配置，思路相通，把端点换成 AgentDock 的 8765 即可。