1. 先搞清楚 dsh-codex-connect 到底在干什么dsh-codex-connect 这个插件名字拆开看就三块dsh 是宿主环境codex 是它要对接的代码智能服务connect 是它的核心动作——把本地开发环境和远端代码模型之间的链路打通。很多人第一次装完看到插件面板亮绿灯就以为万事大吉结果一敲命令就报错或者干脆卡在“connecting”转圈。这类问题的根源九成不在插件本身而在链路中间某一环断了而插件只告诉你“失败了”不告诉你“哪一段失败了”。我前后在三个不同网络环境、两台 Windows 和一台 Linux 机器上反复装过这个插件踩过的坑基本能覆盖新手会遇到的全部类型。这篇就把最高频的五个现象拎出来每个现象配一套可以直接复制粘贴的排查命令再讲清楚每条命令背后的判断逻辑。你不需要理解插件源码只需要按顺序敲命令、看输出、对号入座。适合谁看刚装完 dsh-codex-connect 发现用不了的用了一段时间突然连不上的换了网络环境或换了机器之后插件罢工的。如果你还没装建议先装完再回来对照排查因为下面很多命令的输出需要插件实际运行时的状态才有意义。提示全文命令以 Windows 的 cmd 和 PowerShell 为主Linux/macOS 的对应命令我会在括号里标注。所有命令都不涉及任何敏感操作纯粹是本地网络和进程排查。2. 排查前的通用准备先把“变量”固定住2.1 确认插件版本与宿主版本匹配在动手排查之前有一件事必须先做确认你装的 dsh-codex-connect 版本和 dsh 宿主版本是兼容的。我遇到过两次“连不上”最后发现是插件版本比宿主新了一个大版本接口对不上。查看方式很简单在 dsh 的插件管理面板里找到 dsh-codex-connect看它的版本号然后去插件市场的更新日志里核对兼容的宿主版本区间。如果你用的是命令行方式管理插件可以用类似下面的命令列出已安装插件及其版本具体命令名以你的 dsh 版本为准dsh plugin list --verbose输出里会包含插件名、版本、状态、依赖的宿主版本范围。重点看两列version和requires。如果requires写的宿主版本范围不包含你当前的宿主版本那后面所有排查都是白费功夫先降级或升级插件再说。2.2 记录当前网络环境的关键参数排查网络类问题最忌讳“边猜边改”。先把当前环境的关键参数记下来后面每改一次只动一个变量才能定位到真正的元凶。需要记录的有四项本机 IP、默认网关、DNS 服务器、代理设置状态。Windows 下用一条命令全拿到ipconfig /allLinux/macOS 下ip addr ip route cat /etc/resolv.conf把输出里的 IPv4 地址、默认网关、DNS 服务器抄下来。代理设置单独看Windows 在“设置 网络和 Internet 代理”里看Linux 看环境变量http_proxy、https_proxy、no_proxy。注意很多人排查时反复重启插件却从来没看过代理设置。dsh-codex-connect 默认会读取系统代理如果系统代理指向一个已经失效的地址插件就会一直卡在连接阶段而浏览器可能因为走了别的通道反而正常。这是最隐蔽的坑之一。2.3 准备一个“干净”的测试终端后面很多命令需要在终端里跑建议单独开一个干净的终端窗口不要和 IDE 内置终端混用。原因是 IDE 内置终端可能注入了额外的环境变量比如 IDE 自己设的代理会干扰判断。用系统自带的 cmd、PowerShell 或 Terminal 就行。3. 现象一插件面板一直显示“连接中”永远不变成“已连接”这是出现频率最高的现象没有之一。表现是插件图标一直在转圈或者状态栏写着“connecting”等五分钟还是这样。很多人第一反应是“网络不通”但实际上这个现象背后至少有四种完全不同的原因得逐层剥。3.1 第一步确认插件进程是否真的活着先别急着测网络先看插件进程在不在。有时候插件崩溃了但 UI 没刷新你看到的“连接中”其实是僵尸状态。Windows 下tasklist | findstr /i dsh codexLinux/macOS 下ps aux | grep -i dsh\|codex | grep -v grep如果输出为空说明插件进程根本没起来问题在插件加载阶段不在网络。这时候去看 dsh 的日志目录通常在主目录下的.dsh/logs里找最新的日志文件搜codex-connect关键字看有没有加载失败的堆栈。如果进程在但 CPU 占用一直是 0说明它卡在某个等待上继续往下走。3.2 第二步用 telnet 测端口通不通这是最经典也最有效的一招。先确认插件要连的目标地址和端口这个信息在插件的配置文件里通常在.dsh/plugins/dsh-codex-connect/config.json或类似路径。找到host和port两个字段。假设目标是api.example-codex.com的 443 端口用 telnet 测telnet api.example-codex.com 443如果屏幕变成一片黑或者显示Connected to ...说明 TCP 层是通的问题在更上层TLS 握手或应用层协议。如果显示Could not open connection或一直卡住然后超时说明 TCP 层就不通问题在路由、防火墙或 DNS。提示Windows 默认没开 telnet 客户端。开启方法控制面板 程序 启用或关闭 Windows 功能 勾选“Telnet 客户端”。或者用 PowerShell 的Test-NetConnection代替效果一样Test-NetConnection api.example-codex.com -Port 443输出里的TcpTestSucceeded为True就是通False就是不通。3.3 第三步DNS 解析是否正常如果 telnet 直接报“找不到主机”那就是 DNS 问题。先用 nslookup 确认nslookup api.example-codex.com正常应该返回一个或多个 IP 地址。如果返回Non-existent domain或超时说明 DNS 解析失败。这时候换一个公共 DNS 试试比如把系统 DNS 临时改成223.5.5.5或119.29.29.29再测一次。如果换了 DNS 就通了说明是你原来那个 DNS 服务器的问题不是插件的问题。我遇到过一种情况公司内网 DNS 把某个域名解析到了一个内网地址而那个地址上根本没有对应的服务导致 telnet 能通但 TLS 握手失败。这种“假通”最迷惑人所以 DNS 解析出来的 IP 一定要和预期对一下。3.4 第四步抓包看卡在哪一步如果前三步都正常但插件还是连不上就得上抓包了。Windows 下用pktmonWin10 1809 以后自带Linux 下用tcpdump。Windowspktmon start --etw -c --comp nics然后复现一次连接停止抓包pktmon stop pktmon etl2txt PktMon.etl -o capture.txt在 capture.txt 里搜目标 IP看 TCP 三次握手有没有完成。如果只有 SYN 没有 SYN-ACK说明对方没响应可能是防火墙拦了。如果 SYN-ACK 有了但紧接着是 RST说明对方主动拒绝可能是目标端口不对或服务没起。Linux 下更简单tcpdump -i any host api.example-codex.com -w capture.pcap抓完用 Wireshark 打开看时序图一目了然。4. 现象二提示“认证失败”或“token 无效”连接能建立但一到认证环节就挂。这个现象比第一个好排查因为错误信息更具体。核心就三个方向token 本身过期、token 传丢了、系统时间不对。4.1 检查 token 是否过期dsh-codex-connect 用的 token 通常有有效期。在插件配置里找到 token 字段它一般是一串 JWT 格式的字符串三段用点分隔。把中间那段拿出来用 base64 解码看exp字段对应的时间戳。echo 中间那段 | base64 -d解出来是个 JSON里面有exp过期时间Unix 时间戳和iat签发时间。把exp转成可读时间date -d 1700000000如果这个时间已经过了那就是 token 过期重新在插件里走一遍授权流程拿新 token 就行。4.2 确认 token 有没有被环境变量覆盖这是个很隐蔽的坑。插件读取 token 的优先级通常是环境变量 配置文件。如果你之前为了测试在系统里设过一个CODEX_TOKEN环境变量插件会优先用它而你可能早就忘了这回事。Windows 下查看set | findstr /i codex tokenLinux/macOS 下env | grep -i codex\|token如果有输出而且值和你配置文件里的不一样那就是它在捣乱。临时清掉再试set CODEX_TOKENLinux/macOSunset CODEX_TOKEN4.3 系统时间偏差导致签名校验失败JWT 的签名校验依赖时间。如果你的系统时间比真实时间慢了或快了超过几分钟签名校验就会失败报“token 无效”。这个现象特别容易在虚拟机或长时间没同步时间的机器上出现。Windows 下同步时间w32tm /resyncLinux 下sudo ntpdate pool.ntp.org或者用timedatectl看当前时间同步状态timedatectl status看System clock synchronized是不是yes。如果不是先解决时间同步问题。实操心得我有一次在一台离线虚拟机上排查了半小时最后发现虚拟机时间停在三个月前。同步完时间token 立刻就能用了。这个坑的迷惑性在于错误信息只说“token 无效”完全不提时间。5. 现象三连接成功但命令执行超时插件显示已连接但一执行具体命令就卡住最后报 timeout。这个现象说明链路是通的但数据传输出问题。常见原因有三个MTU 不匹配、中间设备做了深度包检测、目标服务响应慢。5.1 用 ping 测 MTU 和丢包先测基础连通性和丢包率ping -n 20 api.example-codex.comWindows 下-n是次数Linux 下是-c。看输出里的丢包率和平均延迟。如果丢包率超过 5%那超时就是网络质量导致的跟插件无关。再测 MTU。默认以太网 MTU 是 1500但经过某些隧道或特殊链路时可能需要调小。用带-f不分片和指定包大小的 ping 来探测ping -f -l 1472 api.example-codex.comWindows 下-l指定数据部分大小1472 28 字节头 1500。如果报“需要分片但设置了 DF 标志”说明 MTU 小于 1500逐步减小-l的值直到能通找到实际 MTU。Linux 下ping -M do -s 1472 api.example-codex.com如果实际 MTU 明显小于 1500需要在网卡上调整netsh interface ipv4 set subinterface 以太网 mtu1400 storepersistent5.2 检查是否有中间设备干扰有些企业网络或公共网络会对长连接做限制或者对特定协议做深度包检测。判断方法是换一个网络环境比如用手机热点再试。如果热点下正常原网络下超时那就是网络中间设备的问题。这种情况下可以尝试让插件走更短的连接或调整心跳间隔。在插件配置里找keepalive或heartbeat相关字段把间隔调小让连接保持活跃减少被中间设备断开的概率。5.3 目标服务响应慢的确认方法如果换网络也慢那可能是目标服务本身响应慢。用 curl 直接测一次请求耗时curl -o /dev/null -s -w DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n https://api.example-codex.com/health看各阶段耗时。如果time_connect就很大是网络问题如果time_appconnect大是 TLS 握手慢如果time_total大但前面都小是服务端处理慢。6. 现象四插件加载失败或直接闪退这个现象通常发生在启动阶段插件还没进入连接流程就挂了。原因集中在依赖缺失、权限不足、配置文件损坏三类。6.1 查看插件加载日志dsh 的日志是排查这类问题的第一手资料。日志位置一般在Windows:%USERPROFILE%\.dsh\logs\Linux/macOS:~/.dsh/logs/找最新的那个日志文件搜codex-connect和error。常见的错误信息有错误信息含义解决方向Cannot find module xxx依赖缺失重装插件或手动补依赖EACCES/Permission denied权限不足用管理员权限运行或改文件权限Unexpected token in JSON配置文件损坏删除配置文件让插件重建Port already in use端口被占用换端口或杀掉占用进程6.2 检查端口占用如果日志里提到端口被占用用命令查是谁占的Windowsnetstat -ano | findstr :你的端口号拿到 PID 后tasklist | findstr PIDLinuxlsof -i :你的端口号或者ss -tlnp | grep 你的端口号找到占用进程后要么杀掉它要么在插件配置里换一个端口。6.3 配置文件损坏的修复配置文件损坏最常见的原因是手动编辑时格式错了或者写入过程中断电。修复方法很简单把配置文件重命名备份然后重启 dsh插件会自动生成一份默认配置。mv config.json config.json.bak重启后如果插件能正常加载说明就是配置问题。然后对照备份文件把必要的字段token、host、port手动填回新配置里别整个覆盖回去。注意有些插件的配置文件里存了加密后的凭据直接复制备份文件可能导致解密失败。所以建议只手动迁移必要字段而不是整个文件覆盖。7. 现象五能连上但功能异常比如代码补全不工作这是最“软”的一类问题链路完全正常但具体功能不对。排查思路和前四种完全不同重点在功能配置和版本兼容。7.1 确认功能开关是否打开dsh-codex-connect 的很多功能是分开关控制的。在插件设置面板里逐项确认代码补全、代码解释、重构建议这些开关是不是都开了。有时候插件更新后新版本默认关闭了某些功能而你没注意到。配置文件里对应的字段通常是features下面的布尔值{ features: { completion: true, explain: true, refactor: false } }如果refactor是false那重构功能不工作就是正常的打开就行。7.2 检查语言服务器是否正常代码补全这类功能依赖语言服务器。如果语言服务器没起来补全就不工作。在 dsh 的输出面板里找语言服务器相关的日志看有没有启动失败的记录。常见问题是语言服务器需要的运行时比如某个版本的 Node.js 或 Python没装或版本不对。用命令确认node --version python --version对照插件文档里要求的版本范围不在范围内就升级或降级。7.3 版本兼容性矩阵功能异常很多时候是版本组合不对。我整理了一个常见的兼容性对照表供参考插件版本宿主版本语言服务器版本备注1.2.x3.0 - 3.40.9.x稳定组合1.3.x3.51.0.x需要宿主 3.5 以上1.4.x3.61.1.x最新功能最全如果你的组合不在表里去插件市场的更新日志里找对应版本的说明。版本不匹配导致的功能异常靠改配置是修不好的只能升级或降级。7.4 用最小化配置复现如果以上都正常但功能还是不对用最小化配置测试新建一个干净的配置文件只填 host、port、token 三个必填项其他全用默认值。然后重启插件看功能是否恢复。如果恢复了说明是你原来的某个配置项有问题逐项加回去定位。8. 常见问题速查表与排查顺序建议把上面五个现象和对应的排查命令整理成一张速查表方便你遇到问题时快速定位现象首要排查命令最可能原因解决动作一直连接中tasklist | findstr dsh进程没起或卡死看日志重启插件一直连接中telnet host portTCP 不通查防火墙、DNS认证失败解码 token 看 exptoken 过期重新授权认证失败set | findstr token环境变量覆盖清掉环境变量命令超时ping -n 20 host网络质量差换网络或调 MTU命令超时curl -w ...服务端慢联系服务方加载失败看.dsh/logs依赖或权限重装或提权加载失败netstat -ano | findstr 端口端口占用换端口功能异常看 features 配置开关没开打开开关功能异常node --version运行时版本不对升级运行时排查顺序建议按这个优先级来先确认进程活着再确认 TCP 通再确认认证过最后才看功能。不要跳步因为后面的问题往往被前面的问题掩盖。我见过有人直接去查功能配置结果发现根本原因是 token 过期白折腾一小时。实操心得每次排查只改一个变量改完立刻复现。同时改多个地方即使问题解决了你也不知道是哪个改动起的作用下次遇到同样问题还是不会修。9. 几个我踩过的坑和对应的土办法第一个坑Windows 下用 PowerShell 跑 telnet 测试结果 PowerShell 把 telnet 当成了别名实际执行的是Test-NetConnection输出格式完全不一样我对着输出愣了半天。后来改用 cmd 跑 telnet 才正常。所以命令在哪个 shell 里跑一定要看清楚。第二个坑插件配置文件里的 host 字段填的是域名但 DNS 解析出来是 IPv6 地址而我的网络环境 IPv6 不通导致连接超时。解决办法是在配置里强制用 IPv4或者把 host 直接改成 IPv4 地址。判断方法很简单nslookup看返回的是 A 记录还是 AAAA 记录。第三个坑公司网络对长连接有 5 分钟空闲断开的策略插件默认心跳是 10 分钟结果每次空闲几分钟后第一个命令必然超时。把心跳改成 2 分钟后问题消失。这个坑的隐蔽性在于它只在“空闲一段时间后”才出现如果你一直在用反而不会触发。第四个坑插件更新后配置文件格式变了旧配置里的某个字段在新版本里被重命名了但插件没有做向后兼容直接报解析错误。解决办法是看更新日志里的“Breaking Changes”部分手动迁移字段。养成看更新日志的习惯能省很多排查时间。10. 把排查流程固化成脚本如果你经常需要在多台机器上排查可以把上面的命令串成一个脚本一键输出所有关键信息。Windows 下写个.batecho off echo Process tasklist | findstr /i dsh codex echo Port Test powershell -Command Test-NetConnection api.example-codex.com -Port 443 echo DNS nslookup api.example-codex.com echo Proxy reg query HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings | findstr /i ProxyEnable ProxyServer echo Time w32tm /query /statusLinux 下写个.sh#!/bin/bash echo Process ps aux | grep -i dsh\|codex | grep -v grep echo Port Test timeout 5 bash -c cat /dev/null /dev/tcp/api.example-codex.com/443 echo TCP OK || echo TCP FAIL echo DNS nslookup api.example-codex.com echo Proxy env | grep -i proxy echo Time timedatectl status跑一遍脚本把输出保存下来对比正常和异常时的差异定位速度会快很多。这个脚本我放在每台开发机的桌面出问题先跑一遍五分钟内基本能锁定方向。最后分享一个判断“是不是插件本身问题”的土办法找一个确定能用的环境比如同事的机器把同样的配置导过去试。如果那边能用说明是你环境的问题如果那边也不能用说明是插件或服务端的问题。这个二分法能帮你快速排除掉一半的可能性省下大量瞎猜的时间。