AgentDock 入门:在 Windows 上连接 AI 客户端与本机工具
根据官方文档,整理 Windows 安装、客户端连接、首次验证,以及 Skill、Plugin 和 MCP 的区别。
目录
本文依据 2026 年 11 月 16 日查阅的 AgentDock 官方文档整理,属于入门指南。任务示例用于说明用法,未在本文编写过程中执行;安装和菜单细节请结合当前官方文档核对。
AgentDock 负责哪一部分
这条链路可以理解为:你向支持 MCP 的 AI 客户端提出目标,客户端选择工具,AgentDock 在其所在的电脑或服务器上执行允许的操作。它向客户端提供文件、命令、Git 和浏览器等能力,本身不提供聊天界面或模型推理。
安装之后,还需要连接一个 AI 客户端。可以访问什么文件、执行什么操作,取决于系统账号权限、容器挂载范围及启用的功能。官方介绍
第一步:在 Windows 上安装
官方图形安装器支持 Windows 11 的 x64 和 ARM64。确认系统架构后,从官方安装页下载对应版本:Intel、AMD 电脑一般选择 x64,Windows ARM 设备选择 ARM64。
运行安装器,按照界面选择启动方式和运行权限。管理员增强模式属于可选项;初次尝试可以从标准用户模式开始,具体任务需要更高权限时再评估。
安装完成后打开控制面板,确认运行状态、版本和 MCP 地址。后续修改公网连接方式可以在面板里完成,不必为此重装。Windows 安装说明
第二步:选择本机还是公网连接
判断客户端实际运行在哪里,再决定连接方式:
| 场景 | 选择 |
|---|---|
| 客户端和 AgentDock 在同一台电脑 | 本地 MCP 地址 |
| 云端客户端或其他设备 | 公网 HTTPS MCP 地址 |
| 暂时体验公网连接 | 临时公网地址 |
| 长期保持稳定地址 | 按官方教程配置自己的域名和 Tunnel |
临时地址可能随服务或 Tunnel 重启而变化,失联时先核对控制面板。配置中要区分公网 Origin 与客户端 MCP 地址:前者不带 /mcp,后者使用面板给出的完整 MCP URL。连接方式说明
第三步:添加连接并完成认证
在客户端的 MCP 或连接器设置里添加 AgentDock,传输方式选择 Streamable HTTP。本机默认地址示例:
http://127.0.0.1:8765/mcp
公网地址示例:
https://agentdock.example.com/mcp
示例域名需要替换;云端客户端无法通过 127.0.0.1 访问你的电脑。实际操作使用自己面板中的地址和端口。
认证取决于客户端和服务配置:支持 OAuth 时按浏览器引导授权;支持自定义 HTTP Header 时也可以使用 Bearer Token。真实凭据存入客户端提供的安全配置,避免放进文章、截图和仓库。客户端连接指南
第四步:用只读任务验证连接
先读取能力概览,再开始修改文件。例如:
请调用 AgentDock 的 agentdock_context,
告诉我当前版本、系统、路径模型和可用能力。
完成真实调用,才能验证客户端确实能使用工具,也能知道后续应采用的设备和路径。界面显示“已连接”只是连接过程中的一个信号。首次验证说明
可以怎样描述任务
从容易检查的小任务开始:
查看指定项目的目录结构,说明启动方式,先不要修改文件。
开发任务则可以同时说明目标、范围和完成条件:
检查这个项目启动失败的原因。
定位后修改相关文件,运行已有检查,
说明检查结果以及尚未验证的部分。
复杂开发或排障可以保存为可恢复任务,保留目标、步骤、当前进度和验证记录。会话中断后先读取任务状态,再继续剩余步骤。任务与进度
浏览器操作需要先安装受支持的 Chrome、Chromium 或 Edge,并启用浏览器工具。默认的独立浏览器环境不会自动继承日常浏览器登录状态;首次登录可能仍需要手动扫码或验证。浏览器使用指南
Skill、Plugin 和外部 MCP 怎么选
| 名称 | 解决什么问题 |
|---|---|
| Skill | 教 Agent 一套可复用的任务处理方法 |
| Plugin | 把相关 Skill、MCP 配置打包管理 |
| 外部 MCP | 接入另一个工具服务或本机程序 |
Skill 适合积累操作方法。安装陌生 Skill 前先检查来源、文件和权限要求;凭据放在独立环境,避免打包进 Skill。Skill 说明
AgentDock 的 Plugin 可以包含 Skill、MCP 配置或两者。它与客户端里用来连接 AgentDock 的“插件入口”含义不同;包内容变化后应重新审查。Plugin 说明
外部 MCP 可以通过 HTTP 或本机程序接入。连接后用一次无副作用调用验证工具可用,凭据保存在该连接自己的环境中。外部 MCP 说明
连接失败时,从哪里排查
按由近到远的顺序检查:
- AgentDock 服务是否仍在运行。
- 本机健康检查是否可访问。
- MCP URL 是否正确,是否以
/mcp结尾。 - Token 或 OAuth 认证是否有效。
- 使用公网时再检查 Tunnel、域名和反向代理。
默认健康检查地址示例:
http://127.0.0.1:8765/healthz
健康检查通过说明对应 HTTP 服务可达,仍需真实 MCP 调用验证客户端链路。401 应先核对认证;旧工具列表可以尝试重新连接或新建会话。反馈问题时提供版本、系统、安装方式和脱敏错误信息。故障排查
更新与后续记录
当前 Windows 文档提供控制面板内更新。升级前后查看版本和状态,旧版本升级路径以官方说明为准。Windows 更新说明
后续使用手记可以继续补充真实任务:使用了哪个版本、目标是什么、修改了哪些文件、怎样验证,以及遇到了什么限制。将这些可复现的记录逐步补进本站,才会形成自己的经验积累。