AgentDock 接入 ChatGPT、Claude Code、Codex 实战：MCP 客户端配置教程

这个教程解决什么问题

AgentDock 装好后只是一个等待连接的运行时（默认端口 8765），它的价值要等 AI 客户端接入才会兑现。读完这篇，你能把三种主流客户端连上 AgentDock，并理解两种接入协议（MCP 与 ACP）分别适合什么场景。

先分清两种接入方式

AgentDock 对外暴露两类端点，这是理解全部配置的前提：

端点	协议	谁来连	典型客户端
`/mcp`	MCP Streamable HTTP	支持 MCP 的 AI 客户端	ChatGPT、Claude Code、Cursor 等
`/acp`	ACP（Agent 通信协议）	Agent 适配器	Codex、Claude、Grok 的 worker 适配器

简单说：MCP 是「工具调用」的通道，ACP 是「让另一个 Agent 作为工人干活」的通道。 日常用 MCP 就够了；想让外部 Agent（比如 Codex CLI）作为子工人接入时才用 ACP。

接入 ChatGPT

ChatGPT 的 MCP 支持走远程服务器模式。在设置里添加 MCP 服务器时填：

名称：agentdock（随意，方便识别即可）
URL：https://你的域名或IP:8765/mcp
认证：选择 Bearer Token，填你部署时设置的 AGENTDOCK_TOKEN

三个实操细节：

公网可达是前提。 ChatGPT 的请求来自 OpenAI 的服务器，所以你的 AgentDock 必须能从公网访问。家里 NAS 部署的话用 Cloudflare Tunnel（AgentDock 官方文档给了现成方案），云服务器则直接用公网 IP 或域名。
HTTPS 不是可选项。 远程 MCP 走流式连接，公网明文 HTTP 大多数客户端会拒绝，也会把 Token 裸奔。Cloudflare Tunnel 或 Caddy 反代都能一键解决 HTTPS——本站写过雷池配合 Caddy 做防护，反代方案直接复用。
配完先发一句「列出你可用的工具」测试。 能看到 AgentDock 的文件、命令、Git 等工具列表，说明链路全通。

接入 Claude Code

Claude Code 的 MCP 配置在配置文件里完成。全局配置编辑 ~/.claude.json（项目级则在该项目 .mcp.json）：

{
  "mcpServers": {
    "agentdock": {
      "type": "http",
      "url": "https://你的域名:8765/mcp",
      "headers": {
        "Authorization": "Bearer 你的AGENTDOCK_TOKEN"
      }
    }
  }
}

配置后重启 Claude Code，用 /mcp 命令查看连接状态。如果你在 Claude Code MCP 配置那篇里接过其他 MCP server，会发现格式完全一样——AgentDock 就是又一个标准 MCP 服务器，只是能力更全。

本机部署的 Claude Code 有个便利：AgentDock 就在同一个局域网甚至同一台机器上，URL 可以直接写 http://127.0.0.1:8765/mcp，不需要公网暴露，Token 也不用出内网。

接入 Codex 与 ACP 适配器

OpenAI Codex CLI 是 AgentDock ACP 能力的典型用户。ACP（Agent 通信协议）的玩法和 MCP 不同：MCP 让 AI「调用工具」，ACP 则让 AgentDock 托管一个真正的 Agent worker。

配置思路：在 AgentDock 的 /acp 端点上挂载对应适配器（官方提供了 Codex、Claude、Grok 三类适配器），然后主对话里把任务派给这个 worker。Worker 在 AgentDock 所在的机器上跑，产出、日志、制品（/artifacts 端点）都留在你自己的机器上。

这对两个场景特别有价值：

过夜任务：晚上派活给 worker，早上看结果，任务中断了还能用 agentdocks task retry 重试
多 Agent 分工：主对话负责规划和判断，worker 负责执行，类似本站在 CLI Agents 并行里讨论的分工模式，但执行环境从本地终端换成了你的自托管运行时

三类客户端配置速查

把前文的配置动作压成一张表，配的时候对着填：

客户端	接入方式	配置位置	URL	认证
ChatGPT	远程 MCP	设置里添加 MCP 服务器	`https://地址:8765/mcp`	界面里填 Bearer Token
Claude Code	MCP（http 类型）	`~/.claude.json` 或项目 `.mcp.json`	同上	headers 带 Authorization
Codex	ACP 适配器	AgentDock 的 `/acp` 端点挂 worker	`/acp`	AgentDock 侧托管

表里有一个容易忽略的点：Codex 这一行走的是 ACP 而不是 MCP，所以它没有「客户端填 URL」这一步——适配器挂在 AgentDock 侧，你是在服务端配置 worker，而不是在客户端配置服务器。

认证与安全配置速查

接入客户端时，这四个安全变量直接决定你的暴露面：

变量	什么时候用	红线
`AGENTDOCK_TOKEN`	所有远程客户端	永远用长随机串，不进 Git
`AGENTDOCK_ALLOWED_ORIGINS`	有 Web 端客户端时	精确到域名，不用 `*`
`AGENTDOCK_ADMIN_TOKEN`	需要管理接口时	管理凭证与普通凭证分离
`AGENTDOCK_NO_AUTH=1`	仅本机调试	绝不在有公网访问的机器上开

一句话原则：能内网不公网，能 Tunnel 不开端口，能白名单不放开。 更系统的安全展开（包括公网部署的权限边界设计）在本系列的安全实践篇单独讲。

接入 FAQ

Q：多个客户端能同时连一个 AgentDock 吗？

能。AGENTDOCK_TOKEN 本来就是发给 MCP 客户端共用的，ChatGPT 和 Claude Code 并存没有问题。需要「独立凭证」的是多节点场景——每台机器一个 Token，而不是每个客户端一个。

Q：家里的机器没有公网 IP，ChatGPT 连不上怎么办？

ChatGPT 的请求来自 OpenAI 服务器，公网可达是硬前提。上 Cloudflare Tunnel：机器跑 cloudflared 出站连接，路由器不开任何端口，客户端 URL 换成 Tunnel 域名即可。

Q：URL 什么时候用 http，什么时候用 https？

本机或同一内网里，http://127.0.0.1:8765/mcp 这类地址直接用；只要流量出了本机，一律 https。判断标准就一条：Token 会不会经过不信任的网络。

Q：Codex worker 的产出在哪里拿？

制品走 /artifacts 端点访问，任务状态用 agentdocks task list 查，日志用 agentdocks task logs 看，失败可 agentdocks task retry。worker 跑在你部署 AgentDock 的机器上，产出不出你的机器。

Q：/mcp 和 /acp 能同时用吗？

能，两个端点各走各的。日常工具调用全走 /mcp；只有把 Codex、Claude、Grok 这类 Agent 作为 worker 接入时才碰 /acp，互不干扰。

Q：接入后 AI 能看到我整台电脑吗？

看不到。AI 能触达的只有配置的工作区目录和对应的能力模块，其余文件系统不在它的视野里——这也是部署时把工作区画小一点的意义。

排错清单

连接失败时按这个顺序排查，命中率高：

curl 先测通：curl -H "Authorization: Bearer 你的Token" https://你的地址:8765/mcp——curl 不通就是网络/防火墙/反代问题，和客户端无关
401 查 Token：引号、空格、变量没生效，逐个排除
客户端超时查协议：确认客户端支持 Streamable HTTP 的 MCP 传输（2025 年后的主流客户端都支持，老版本可能只支持 stdio）
工具列表为空：检查 AgentDock 日志里能力模块是否正常加载，必要时 agentdocks doctor 体检

三种客户端接完，你手上就有了一条完整的链路：手机/电脑上的 AI 对话 → AgentDock 运行时 → 你的真实机器。下一篇文章把这个链路从单机扩展到多机。