DSH 接入内网 MCP 踩坑记录:OAuth 代理与三层静默失败

简介: 自带的 MCP 插件只支持 stdio 与静态 header,接不了必须走 OAuth 的内网服务;用 mcp-remote 做 stdio 代理补上这一层之后,剩下的时间全部花在插件加载体系的三层静默失败上:模块解析域、insert 语义、YAML 缩进。全文附 10 条坑、可复用检查清单和三样取证工具。

DSH 自带的 MCP 插件不支持 OAuth,这条链路上真正花时间的也不是写代码,而是插件加载体系的三层静默失败。 我用一个 stdio 代理把内网 MCP 接进来,最终注册出 33 个工具,中间踩了 10 个坑,每一个都是靠日志和 --dump-config 取证才定位的。

环境:DeepSeek Harness 0.2.2-rc.2(Electron 44.7.0 / 内置 Node 24.21.0)、本机 Node v22.12.0、app 自带的 pnpm 11.28.5、mcp-remote@0.16.6、MCP SDK @modelcontextprotocol/client@2.2.0。

目标是让 Agent 调用内网的日志与链路查询服务,并且登录走标准的动态 OAuth(PKCE + 动态客户端注册),而不是手工贴一个长期 token。

结论先行

# 现象 根因 修复
1 MCP 配置里没有 OAuth/认证字段 createTransport 只构造 stdio 与 streamable-http 两种传输,没有 authProvider 注入点 用 mcp-remote 做 stdio 代理,OAuth 交给它
2 直连 HTTPS 端点报 UNABLE_TO_VERIFY_LEAF_SIGNATURE 内网 CA 不在 Node 的信任链里 在同一条内网链路上改走 http:// + --allow-http
3 授权完成后连接不建立 回调地址用 localhost(可能解析成 ::1),本地监听却绑在 127.0.0.1 --host 127.0.0.1 --bind-host 127.0.0.1
4 配置里写 command: npx 起不来 app 进程的 PATH 只有系统目录,没有 node/npx 用绝对路径的 node + proxy.js
5 从 profile 里解析不到内置 MCP 插件包 插件条目的 name 按 profile 作用域解析,app.asar 里的内置包不在这个域里 用 app 自带的 pnpm 把插件及 peer 闭包装进 profile
6 配置里加的新插件「没反应」,日志一片空白 顶层 - id: 只用于覆盖已有条目,id 不存在时整条被丢弃 新插件必须写成 - insert: [...]
7 模块被 import 了,但 apply 永不执行 YAML 缩进少两格,config: 的子项成了同级,合成后是 config: null 修正缩进,子项多缩两格
8 启动失败,提示插件在等 service patch 引用的 hook 文件被外部工具重写时删掉 → ERR_MODULE_NOT_FOUND 从安装包模板里拷回该文件
9 升级后 profile 里 rc.1 的插件「消失」 加载器做严格版本审计,不兼容的 bundle 整包跳过,只打一行 stderr 把 profile 依赖对齐到同一版本
10 耗时对比数据不可信 测试脚本自己直连 MCP,绕过了 DSH 原生工具 删掉临时脚本,确认 mcp__ops__* 真出现在工具列表

能力边界:为什么不能直接用官方插件走 OAuth

看编译产物就够了(@deepseek-ai/dsh-mcp-client/lib/index.js):

function createTransport(config) {
   
  switch (config.transport) {
   
    case 'stdio': return new StdioClientTransport({
    command, args, env, cwd })
    case 'streamable-http':
      return new StreamableHTTPClientTransport(new URL(config.url), {
   
        requestInit: {
    headers: config.headers }   // 只有静态 header
      })
  }
}
  • 配置 schema 里只有 url / headers(值可以是 !!js 表达式,比如 Bearer ${process.env.MCP_TOKEN}),没有 authProvider;
  • 而内置的 MCP SDK 本身是支持 OAuth 的(OAuthClientProvider、UnauthorizedError、registration_endpoint 都在);
  • 服务端也是标准实现:401 + WWW-Authenticate: Bearer ... resource_metadata=... → RFC 9728 保护资源元数据 → 元数据里带 authorization_endpoint、token_endpoint、registration_endpoint(DCR),以及 code_challenge_methods_supported: ["S256"]。

也就是说,缺口只在客户端插件的接线。要么改插件,要么在插件外面套一个「会 OAuth 的 stdio MCP 服务器」。选了后者:零代码,也不随 app 升级失效。这类「只在运行时才看得出问题」的组合层差异,和 配置层优先级 里讲的分层是同一套机制。

方案:把 OAuth 交给 stdio 代理

DSH 通过 stdio 代理接入内网 MCP 的链路

mcp-remote 负责全部 OAuth 细节:动态注册 → PKCE → 浏览器授权 → 换 token → 过期自动 refresh,token 落在 ~/.mcp-auth/mcp-remote-v1/<hash>_tokens.json。DSH 那边只看到一条最普通的 stdio MCP。

第一个坑:证书链

直连 HTTPS 端点报:

UNABLE_TO_VERIFY_LEAF_SIGNATURE

内网 CA 在系统钥匙串里有,Node 不认。三条路:注入 NODE_EXTRA_CA_CERTS、NODE_TLS_REJECT_UNAUTHORIZED=0(不可取)、或者在内网链路上直接走 http。选了第三条:

http://mcp-gateway.internal.example/mcp --transport http-only --allow-http

--allow-http 是 mcp-remote 的前置条件,默认拒绝明文端点。这个选择成立的前提是链路本身在内网,公网端点不要这么干。证书链的排查方式和 企业代理下的 TLS 证书错误 完全一致。

第二个坑:localhost 和 127.0.0.1 不是一回事

授权页点完「同意」,浏览器跳回 http://localhost:<port>/callback,但本地监听绑的是 127.0.0.1。有些环境里 localhost 先解析到 IPv6 的 ::1,连不上 → 页面看起来授权成功,连接却不建立。补两个参数后 3 秒走完:

--host 127.0.0.1 --bind-host 127.0.0.1

--host 影响生成的 redirect_uri,--bind-host 影响真实监听地址,两个都要。

第三个坑:宿主的 PATH 是极简的

DSH app 进程的 PATH 只有:

/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

没有 node,没有 npx。而 mcp-remote 的 shim 是 #!/usr/bin/env node,所以 command: npx 一律失败。必须写绝对路径:

command: /Users/you/.n/bin/node
args:
  - '/Users/you/.n/lib/node_modules/mcp-remote/dist/proxy.js'

插件加载体系的三层静默失败

这部分是整场排查里最贵的,也最值得写。

三层静默失败:解析域、patch 语法、YAML 缩进

第一层:模块解析域

DSH 把插件树按 bundle → patch 分层合成后,每个条目的 name 在一个特定作用域里解析:

  • 绝对路径:从 profile 目录出发,相对路径锚定在 patch 文件旁边;
  • 包名:从 profile 的 node_modules 解析,app.asar 里的内置包不在这个域里。

所以内置的 @deepseek-ai/dsh-mcp-client 虽然 app 自己天天在用,从 patch 里引用它就是找不到。往 app.asar 里塞符号链接也不行(ESM realpath 校验会拒)。正确做法是装进 profile:

cd ~/.dsh/profiles/desktop
ELECTRON_RUN_AS_NODE=1 "/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" \
  ".../runtime/primary-runtime/dependencies/pnpm/bin/pnpm.mjs" \
  add @deepseek-ai/dsh-mcp-client@0.2.2-rc.2

注意要用 app 自带的 pnpm:它的版本要求 Node ≥ 22.13,本机 22.12.0 直接跑会报错,所以用 ELECTRON_RUN_AS_NODE=1 借 Electron 自带的 Node 24 来跑。装完还会依次报缺 dsh-scope → cordis → dsh-http-proxy → dsh-llm,一路把 peer 闭包补齐。手工装插件包的过程在 把本地插件装进 profile 里也有对照。

第二层:insert 还是 override

cordis.patch.yml 是补丁层,条目有两种语义。

裸 - id: 只覆盖已存在的条目。id 不存在时整条被丢弃,而且不会有任何报错——这是很容易踩的一格:

- id: mcp-ops-oauth
  name: '@deepseek-ai/dsh-mcp-client'

新增插件必须放进 insert 列表:

- insert:
    - id: mcp-ops-oauth
      name: '@deepseek-ai/dsh-mcp-client'
      config: {
   ...}

loader 的 failOnStartupError 默认是 false,所以丢弃是静默的。一开始照着已有的托管块改,却漏了这层 wrapper。

第三层:缩进,模块加载了但 apply 不跑

放进 insert 之后仍然没反应。给插件打临时埋点后看到:

[mcp] plugin module loaded      ← 模块确实被 import 了
(没有 apply 那一行)            ← 但 apply 从未执行

为了区分「条目没挂载」和「在等 service」,又加了一个形状相同的探针插件(同样 inject: ['tools'])。探针的 apply 能跑,说明条目挂载没问题、tools service 也在。

最后用 --dump-config 看合成后的树,问题一眼可见:

- id: mcp-ops-oauth
  name: '@deepseek-ai/dsh-mcp-client'
  config: null                  # ← 空的
  serverName: ops               # ← 配置项全跑到条目顶层了
  transport: stdio

config: 在 6 空格,子项也在 6 空格,二者成了同级。schema 校验失败,cordis 不创建插件实例,于是只有 import、没有 apply。改成 8 空格后立刻 ready outcome=ok。

记住:insert 之后,config: 及其子项相对 - id: 行要多缩进;args: 是 config 的孙节点,还要再进一级。

启动失败不一定是 MCP 的锅

改完配置重启,应用起不来,界面提示若干插件「waiting for services」。crash log(~/Library/Logs/DeepSeek Harness/crash-*.log)里真正的错误只有一个:

agent-hooks → ERR_MODULE_NOT_FOUND
  ~/.dsh/hooks/agent-stop-hook.mjs

当天有外部工具重写了这个钩子插件的托管块,却没把 hook 文件写回磁盘,而 patch 仍引用这个绝对路径 → 插件加载失败 → 启动流程卡住,其它插件看起来都在等 service。

这类「patch 引用绝对路径文件」的插件是软依赖:文件消失即启动崩,而且报错不会指向 patch 文件本身。「在等 service」这个提示本身的排查顺序,可以对照 插件一直等不到服务时先看什么。

另外两个操作层面的坑:

  • 启动失败后 open -a 不会重新拉起(主进程卡死),osascript quit 会返回 -128(被失败弹窗挡住);
  • 需要先 kill -TERM,不行再 kill -9,然后再 open -a。

升级之后插件被静默跳过

app 自动从 0.2.2-rc.1 升到 0.2.2-rc.2,而 profile 里装的还是 rc.1。加载器做严格版本审计,不兼容的 bundle 整包跳过,只在 stderr 打一行:

dsh: skipping profile bundle "@deepseek-ai/dsh-subagent-codex": Error: Plugin
...@0.2.2-rc.1 is incompatible with dsh 0.2.2-rc.2 ...

而 app 正常启动时这行 stderr 是看不到的——表现为「codex / claude-code 子代理功能莫名其妙没了」。把两个 subagent 包升到 rc.2,重跑 --dump-config 后 stderr 干净。

规则:app 升级后,profile 里所有 @deepseek-ai/* 依赖都要跟着对齐同一版本。

排查工具箱

--dump-config:看合成后的树

desktop profile 被 Electron app 独占,不能直接 dump,但可以复制一份再 dump:

mkdir -p /tmp/dshhome/profiles/test
cp ~/.dsh/profiles/desktop/{
   cordis.yml,cordis.patch.yml,package.json,pnpm-lock.yaml} /tmp/dshhome/profiles/test/
ln -s ~/.dsh/profiles/desktop/node_modules /tmp/dshhome/profiles/test/node_modules

DSH_HOME=/tmp/dshhome ELECTRON_RUN_AS_NODE=1 \
  "/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" \
  ".../app.asar/dsh/node_modules/@deepseek-ai/dsh/lib/bin.js" \
  --profile test --dump-config

它能同时回答三个问题:条目有没有进树、config 是否嵌套正确、哪个 bundle 被版本审计跳过了(看 stderr)。

Electron-as-Node 读 app.asar

普通 cat 读不了 asar,但 Electron 以 Node 模式运行时 fs 是支持 asar 的:

ELECTRON_RUN_AS_NODE=1 "/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" -e '
  const fs = require("fs")
  const f = "/Applications/DeepSeek Harness.app/Contents/Resources/app.asar/dsh/node_modules/@deepseek-ai/dsh-mcp-client/lib/index.js"
  console.log(fs.readFileSync(f, "utf8").slice(0, 2000))
'

插件源码、loader 实现、package.json 版本,全靠这个看。

分级探针

  • 探针 A(inject: []):证明 patch 的 insert 机制本身通不通;
  • 探针 B(inject: ['tools'],和出问题的插件同形):证明依赖的 service 在不在、条目是否真的被挂载;
  • 埋点:在模块顶层、apply 入口、createTransport、connection.ready、syncTools 各打一行到 /tmp/*.log,并挂上 uncaughtException / unhandledRejection。

注意 pnpm add 会覆盖手工埋点的文件,升级后埋点消失,别以为是「埋点没生效」。

其它

  • pgrep -fl "mcp-remote/dist/proxy.js":stdio 子进程有没有起来;
  • ~/Library/Logs/DeepSeek Harness/crash-*.log:启动失败的唯一可信现场;
  • 应用正常启动时 stderr 基本是空的,不要指望在这里看到插件错误。

验证时的两个方法论坑

  1. 工具数统计:第一版统计出 40 / 34 个工具,都是错的——把 serverInfo.name 和 SSE 重复事件也算进去了。正确做法是只看 tools/list 的 tools[] 去重后的原始名称集合,两条链路(静态 token / OAuth)都是 33 个。
  2. 测试污染:在没有原生工具的那几轮里,自动化脚本自己找到了 ~/.mcp-auth 的 token,写了个直连 MCP 的脚本。结果是「看起来能查日志」,但走的是脚本而不是 DSH 工具,耗时对比数据也不可信。验证接入成功的唯一标准是 mcp__ops__* 出现在会话的工具列表里,不是脚本能调通。

最终配置

新插件必须放进 insert 列表:裸 - id: 只覆盖已存在的条目,id 不存在时会被静默丢弃(failOnStartupError 默认 false)。

- insert:
    - id: mcp-ops-oauth
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: ops
        transport: stdio
        # 绝对路径:app 的 PATH 里没有 node/npx
        command: /Users/you/.n/bin/node
        args:
          - '/Users/you/.n/lib/node_modules/mcp-remote/dist/proxy.js'
          - 'http://mcp-gateway.internal.example/mcp'
          - '--header'
          - 'x-mcp-client-version: 1.0.0'
          - '--transport'
          - 'http-only'
          - '--allow-http'
          - '--host'
          - '127.0.0.1'
        toolCallTimeoutMs: 180000

验证日志(埋点期):

[mcp] apply serverName=ops
[mcp] createTransport {"transport":"stdio","command":"/Users/you/.n/bin/node",...}
[mcp] syncTools registering 33 tools: mcp__ops__ops-global-helper, mcp__ops__ops-log, ...
[mcp] ready outcome=ok

可复用的检查清单

给 DSH 新增一个「要自己启动子进程」的 MCP 插件时,按顺序过一遍:

  1. name 指向 app.asar 内置包吗?→ 先 pnpm add 进 profile,用 app 的 pnpm + Electron-as-Node。
  2. 条目是新增的吗?→ 必须写 - insert:,不能裸 - id:。
  3. config: 的子项比 - id: 多缩两格了吗?→ 用 --dump-config 确认不是 config: null。
  4. 子进程命令是绝对路径吗?→ app 的 PATH 只有系统目录。
  5. app 版本变了吗?→ profile 里 @deepseek-ai/* 全部对齐同一版本,否则整包被跳过。
  6. 端点证书链不全?→ 注入 NODE_EXTRA_CA_CERTS,或在内网链路上走 http + --allow-http。
  7. 起不来先看 crash log,不要只看 UI 提示的「waiting for services」。
  8. 验证标准是工具列表里出现 mcp__<server>__*,不是脚本能直连。
  9. 临时探针和埋点用完即删(探针文件、patch 条目、/tmp 日志、源码里的调试分支)。

这类问题的共同点:失败都是静默的。 插件没被插入不报错,配置形状不对不报错,版本不兼容只打一行 stderr,启动失败只显示「在等 service」。所以真正可迁移的经验不是那 10 个坑本身,而是那三样取证工具——--dump-config、Electron-as-Node、分级探针。


相关阅读

本文由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
完整版含两张示意图,见:DSH 接入内网 MCP:OAuth 代理与三层静默失败
文中引用的插件开发文档收录于:https://dsh-plugin.com/zh/blog

目录
相关文章
|
5天前
|
存储 自然语言处理 安全
DeepSeek Harness 接入记忆 MCP:为什么「它记住了」可能只是模型在复述?
给 DSH 接入记忆 MCP 时,最容易出现的误判是「它记住了」:同一会话里问它,对答如流;换一个会话,却一片空白。本文记录我在接入和验证时遇到的六个坑:三个示例默认全关、工具发现是异步的、同会话验证是假阳性、存储范围会悄悄漂移、关掉连接不等于删掉数据,以及 stdio 桥会剥掉像凭据的环境变量。
85 0
|
9天前
|
人工智能 开发者 Docker
【2026实测】Docker Desktop下载、安装、汉化、配置教程(附官网安装包)
Docker Desktop作为本地开发工具,和阿里云容器镜像服务、ECS、容器服务配合,是一套非常成熟的开发流水线。本地写代码、打包、测试、调试,镜像推送到ACR,再到云上部署,全程环境一致,消除本地和线上环境差异带来的问题。新手可以先从安装、汉化、配置阿里云加速器入手,熟悉镜像拉取、打包推送流程,再慢慢掌握资源限制、代理、Kubernetes附加组件等进阶能力。
1185 0
|
1月前
|
缓存 开发工具 git
DSH skill 怎么安装、放在哪个目录?DeepSeek Harness 技能与插件的区别与用法
dsh skill 不是插件:它是给模型的可加载 Markdown 指令集,由本地提供方按 rank 扫描六个根目录发现,用 dsh plugin add 装不进去。本文讲清六个根目录的优先级、SKILL.md 写法与两个调用开关。
2533 4
DSH skill 怎么安装、放在哪个目录?DeepSeek Harness 技能与插件的区别与用法
|
3月前
|
缓存
dsh plugin 命令怎么用?DSH 插件安装、卸载、列出命令大全
dsh plugin 是管理 DSH 插件的命令族:add 安装、remove 卸载、list 列出,都配合 --profile 指定环境。安装有 npm 包名、GitHub 源码、本地目录、市场图形化四种方式,卸载有命令行与界面两种,本文逐个展开步骤并附常见问题排查。
8213 1
dsh plugin 命令怎么用?DSH 插件安装、卸载、列出命令大全
|
1月前
|
人工智能 运维 安全
七亿批量远程管理工具:从安装到使用的全面指南
七亿批量远程管理工具(RdpManager)是一款国产免费运维利器,集成SSH、RDP、SFTP/FTP于单窗口,支持批量添加、分组管理、九宫格桌面、多机群控与AI命令助手。轻量(10MB+)、安全(AES加密/防爆破)、易上手,专为IDC/机房批量运维设计。官网:rdp.7ehl.com
|
5月前
|
人工智能 缓存 自然语言处理
Claude Code 原生终端仪表盘
Claude Code 内置 `statusline` 命令,支持自定义终端底部状态栏:实时显示模型、目录、Git 分支、Token 消耗、缓存命中率及上下文进度条。三种配置方式——自然语言指令、脚本手动设置或 ChatGPT 辅助设计,兼顾简洁性与信息密度,显著提升 AI 编程的上下文掌控感。(239字)
739 0
|
8月前
|
人工智能 安全 API
OpenClaw(Clawdbot)保姆级图文攻略:阿里云/本地部署+11个必装Skill清单+百炼API配置及避坑,效率翻倍
OpenClaw的真正价值,藏在其开放的Skill生态中——没有Skill的OpenClaw,只是一个连接聊天工具与AI的网关;而搭载了合适Skill的OpenClaw,能变身开发者助手、信息管理专家、办公自动化引擎甚至生活管家,成为真正“离不开的个人AI团队”。
2187 1
|
9月前
|
存储 人工智能 网络安全
2026年OpenClaw/Clawdbot多Agent实战指南:阿里云+Windows部署,打造全功能AI智能体协作团队
2026年AI智能体进入规模化协作时代,OpenClaw(原Clawdbot)凭借原生多Agent支持、独立工作区隔离、灵活路由机制,成为搭建专属智能体团队的首选框架。不同于单智能体“全能但混乱”的痛点,多Agent架构通过“角色拆分、身份隔离、协作分工”,让每个智能体专注特定领域,彻底解决上下文污染、人设混乱、Token消耗过高的核心问题。
2656 3
|
机器学习/深度学习 自然语言处理
Deepseek开源R1系列模型,纯RL助力推理能力大跃升!
近期Deepseek正式发布 DeepSeek-R1,并同步开源模型权重。DeepSeek-R1 遵循 MIT License,允许用户通过蒸馏技术借助 R1 训练其他模型。
3523 25
|
11月前
|
数据采集 监控 数据安全/隐私保护
一文搞定 Python 正则表达式:常用场景速查表
本文通过20个实战案例详解Python正则表达式在邮箱验证、数据提取、文本处理等场景的应用,涵盖基础语法、高级技巧与性能优化,助你高效掌握这一字符串处理利器。
688 1

热门文章

最新文章