1. 装完连不通这件事先别急着卸载重装dsh-pocket 这类 CLI 工具装完之后连不通是很多人第一次上手 DeepSeek Harness 时最容易卡住的环节。我见过太多人一看到报错就条件反射地npm uninstall再重装折腾两小时发现根本不是安装的问题。实际上dsh-pocket 的连通性故障有非常明确的几个高发区按顺序排查绝大多数情况十分钟内就能定位。这篇文章面向的是已经完成 dsh-pocket 安装、但在执行连接或认证环节失败的用户。不管你是刚接触 DeepSeek Harness 的新手还是已经在用 codex cli、zcode cli 这类工具的老手只要遇到装完了但连不上的问题下面的排查路径都能直接套用。我会按照故障发生概率从高到低排列每一处都讲清楚为什么这里容易出问题、怎么快速验证、怎么修而不是丢一堆命令让你自己猜。先说一个核心判断原则dsh-pocket 连不通90% 的情况不是二进制本身坏了而是认证链路或网络出口这两个环节断了。所以排查的第一步永远不是重装而是确认它到底卡在哪一层。下面这张表是我自己总结的故障分层对照你可以先对号入座故障现象最可能的层级优先排查项命令执行后无任何输出直接退出认证层凭证文件、环境变量提示连接超时 / timeout网络层出口地址、代理配置提示 401 / 403 / unauthorized认证层Token 有效性、权限范围提示证书错误 / SSL error网络层系统时间、CA 证书提示 command not found安装层PATH、软链接能连但功能异常配置层插件、skill 部署路径这张表建议你截图存着下次遇到问题先看一眼现象落在哪一行能省掉大量无效尝试。2. 认证链路dsh-pocket 连不通的头号嫌疑2.1 凭证到底存在哪里为什么经常读不到dsh-pocket 的认证凭证通常不会明文写在配置文件里而是走一套凭证存储 环境变量引用的机制。这是很多人踩坑的根源你以为装完就自动登录了实际上它根本没找到你的凭证。凭证的常见存放位置有三处优先级从高到低环境变量比如DSH_TOKEN、DSH_API_KEY这类进程启动时直接读取优先级最高。用户级凭证文件一般在~/.config/dsh-pocket/或~/.dsh/目录下文件名可能是credentials.json或auth.toml。项目级配置当前工作目录下的.dshrc或类似文件只对当前项目生效。排查动作很直接按顺序执行# 1. 看环境变量有没有设 env | grep -i dsh # 2. 看用户级凭证文件在不在 ls -la ~/.config/dsh-pocket/ 2/dev/null ls -la ~/.dsh/ 2/dev/null # 3. 看当前目录有没有项目级配置 ls -la .dshrc .dsh/ 2/dev/null如果三处都为空那连不通就是必然的——它压根没有凭证可用。这时候你需要重新执行一次登录流程而不是去改网络配置。注意环境变量里的凭证如果带了多余的空格或换行工具读取时会直接判定为无效。用echo $DSH_TOKEN | cat -A可以看到隐藏字符行尾出现$是正常的出现^M$说明是 Windows 换行符混进来了需要清理。2.2 Token 过期与权限范围不匹配凭证存在不代表有效。dsh-pocket 用的 Token 通常有有效期短的可能几小时长的也就几十天。过期之后的表现往往是连接超时或401而不是明确提示Token 过期这就很容易误导人去查网络。验证 Token 是否还有效最稳妥的办法是拿它单独发一个最小请求curl -s -o /dev/null -w %{http_code} \ -H Authorization: Bearer $DSH_TOKEN \ https://你的服务端点/health返回200说明 Token 本身没问题问题在别处返回401就是 Token 失效或权限不足返回000说明网络根本没通直接跳到第 3 节。权限范围scope不匹配是更隐蔽的坑。有些 Token 只授权了读取权限但你执行的操作需要写入这时候报错信息可能非常含糊。我的经验是先确认这个 Token 是在哪个应用/项目下签发的它的授权范围是否覆盖你当前要做的操作。如果拿不准重新签发一个全权限的临时 Token 做对照测试能快速排除这个变量。2.3 多套凭证打架优先级搞反了这是进阶用户才会遇到的坑。你机器上可能同时装了 codex cli、zcode cli 和 dsh-pocket它们各自维护凭证环境变量名还可能撞车。比如你之前为 codex cli 设了某个通用名的 Token 变量dsh-pocket 启动时读到了这个变量但里面的凭证根本不是给 dsh-pocket 用的结果就是认证失败。排查方法把当前 shell 里所有可能相关的环境变量列出来逐个确认归属。env | grep -iE token|key|auth|dsh|codex|zcode看到不属于 dsh-pocket 的凭证变量要么改名隔离要么在启动 dsh-pocket 时显式覆盖。我个人的习惯是给每个 CLI 工具的凭证变量加工具前缀比如DSHP_TOKEN、CODEX_TOKEN从命名上就杜绝串用。3. 网络出口连不通的第二大来源3.1 先分清是连不上还是连得慢很多人把超时和不通混为一谈。这两者的排查方向完全不同不通是链路问题慢是带宽或 DNS 问题。区分方法很简单加长超时时间再试一次# 默认超时可能是 5s改成 30s 再试 curl --connect-timeout 30 -v https://你的服务端点/如果 30 秒能通说明链路是通的只是慢问题在 DNS 解析或中间节点如果 30 秒还是超时那就是真的不通继续往下查。3.2 DNS 解析最容易被忽略的一环dsh-pocket 连的服务端点如果是域名形式DNS 解析失败会直接表现为连不通。而 DNS 问题在容器环境、内网环境里特别常见。验证 DNS 是否正常# 看域名能不能解析出 IP nslookup 你的服务域名 dig 你的服务域名 short # 直接对比用 IP 直连能不能通 curl -v https://解析出的IP/ --resolve 你的服务域名:443:解析出的IP如果nslookup没结果但你知道正确的 IP那就是 DNS 的问题。临时方案是在/etc/hosts里写死映射长期方案是检查你的 DNS 配置/etc/resolv.conf是否指向了可用的解析服务。提示内网部署 dsh-pocket 的场景下服务端点往往是内网域名公网 DNS 解析不了是正常的。这时候必须确认你的 DNS 配置里包含了内网解析服务或者直接用 IP 访问。3.3 代理配置设了不该设的或者该设的没设代理是网络排查里最薛定谔的一环。dsh-pocket 是否走代理取决于它读取的是哪个环境变量。常见的代理变量有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY大小写敏感有的工具只认小写有的只认大写。先看当前设了什么env | grep -iE proxy然后分两种情况处理不该走代理却走了如果你在纯内网环境但环境变量里残留了代理配置所有请求都会被转发到一个不可达的代理上表现就是全部超时。解决方法是临时清空unset HTTP_PROXY HTTPS_PROXY ALL_PROXY再试。该走代理却没走如果服务端点在外部而你的网络需要经代理出去那就得正确设置代理变量并且确认代理本身是通的。我踩过的一个坑是代理变量设了但代理地址写的是localhost:port而 dsh-pocket 跑在容器里容器内的 localhost 根本不是宿主机的 localhost。这种场景下要把代理地址改成宿主机的实际 IP。3.4 端口与防火墙连通性测试的最后一公里链路、DNS、代理都排除了还是不通就要看端口了。用telnet或nc直接测目标端口# 测 443 端口通不通 nc -zv 服务地址 443 telnet 服务地址 443端口不通的话可能是本机防火墙、目标端防火墙或者中间网络设备拦了。这一步能明确告诉你问题不在 dsh-pocket而在网络链路上避免继续在工具配置里绕圈。4. 安装层与 PATH命令都找不到就别谈连通4.1 command not found 的真实原因有时候连不通其实是根本没跑起来。你敲dsh-pocket提示 command not found那不是连通性问题是安装没生效。先确认二进制到底装哪了# 全局查找 which dsh-pocket whereis dsh-pocket find / -name dsh-pocket* -type f 2/dev/null如果find能找到文件但which找不到那就是 PATH 没包含它的目录。把对应目录加进 PATHexport PATH$PATH:/找到的目录 # 永久生效写进 shell 配置 echo export PATH$PATH:/找到的目录 ~/.bashrc source ~/.bashrc4.2 软链接失效与多版本冲突用包管理器装的 dsh-pocket通常会创建一个软链接指向实际二进制。如果升级过程中断了软链接可能指向一个已经不存在的旧版本文件表现就是命令存在但执行报错。# 看软链接指向哪 ls -la $(which dsh-pocket) # 如果指向的文件不存在重新建立链接 ln -sf /实际二进制路径 /usr/local/bin/dsh-pocket多版本冲突也常见你系统里可能同时有通过 npm 全局装的、通过系统包管理器装的、以及手动下载的多个 dsh-pocket。which返回的是 PATH 里第一个找到的未必是你想用的那个。用type -a dsh-pocket可以看到所有匹配项确认你实际执行的是哪一个。4.3 依赖缺失导致的静默失败dsh-pocket 依赖某些运行时库比如特定版本的 Node、Python 或系统库依赖缺失时它可能不报错直接静默退出。这种无输出退出最迷惑人。排查方法是看退出码和详细日志dsh-pocket --version; echo exit code: $? dsh-pocket 你的命令 --verbose 21 | tee dsh-debug.log退出码非 0 但没输出基本可以确定是依赖或环境问题。这时候去看dsh-debug.log或者用ldd检查动态库依赖ldd $(which dsh-pocket) | grep not found有not found的库装上对应的依赖包即可。5. 配置层能连上但用不了的那些坑5.1 skill 部署路径不对功能直接哑火dsh-pocket 的 skill 机制是它的核心能力之一但 skill 部署到内网服务器时路径问题极其高发。skill 通常需要放在工具约定的目录下放错位置工具就找不到表现为连上了但某个功能不可用。确认 skill 目录约定# 看工具默认从哪读 skill dsh-pocket config get skill_path # 或查看帮助 dsh-pocket --help | grep -i skill把 skill 文件放到正确目录后还要确认文件权限。内网服务器上经常出现 skill 文件属主是 root、但工具以普通用户运行的情况读不到文件。用chmod和chown修正chown -R $(whoami):$(whoami) /skill目录 chmod -R 644 /skill目录/*5.2 配置文件格式错误引发的连锁反应dsh-pocket 的配置文件JSON、TOML、YAML 都有可能只要有一个字符格式错误整个配置就加载失败。而失败时的报错往往指向别处让人误以为是连通性问题。验证配置文件格式# JSON python -m json.tool config.json # YAML python -c import yaml; yaml.safe_load(open(config.yaml)) # TOML python -c import tomllib; tomllib.load(open(config.toml,rb))格式没问题再检查字段名是否拼错、值类型是否匹配。我遇到过一次是布尔值写成了字符串true而不是true工具解析时直接忽略了整个配置块排查了半天。5.3 系统时间偏差导致的证书校验失败这个坑非常隐蔽。dsh-pocket 走 HTTPS 时如果本机系统时间和真实时间偏差过大超过证书有效期容忍范围TLS 握手会直接失败报错可能是certificate verify failed或SSL error。检查系统时间date # 和标准时间对比偏差超过几分钟就要校准Linux 上校准sudo ntpdate pool.ntp.org # 或者 sudo timedatectl set-ntp true容器环境里系统时间偏差尤其常见因为容器默认继承宿主机时间宿主机时间不对容器里全错。6. 一套可复用的排查顺序照着走就行把上面所有内容浓缩成一条排查链路遇到 dsh-pocket 连不通按这个顺序走基本不会漏确认命令能跑dsh-pocket --version跑不起来先解决安装和 PATH。确认凭证存在检查环境变量和凭证文件三处都空就先登录。确认凭证有效用 curl 单独验证 Token排除过期和权限问题。确认 DNS 能解析nslookup服务域名解析不了就查 DNS 配置。确认端口能通nc -zv测目标端口不通就是网络链路问题。确认代理配置正确该走代理的走不该走的清掉。确认系统时间准确偏差大就校准避免证书校验失败。确认配置文件格式正确用解析器验证排除格式错误。确认 skill 路径和权限功能异常时重点查这一项。开 verbose 看详细日志前面都过了还不行日志里一定有线索。这套顺序的价值在于从内到外、从简到繁先排除工具自身的问题再排查网络最后才动配置。很多人一上来就查网络结果发现是凭证没设白白浪费一小时。提示排查过程中每改一个变量就重新测一次不要一次性改好几处。否则问题解决了你也不知道是哪一处起的作用下次再遇到还是不会。7. 几个我实际踩过的坑供你避雷第一个坑是凭证文件权限过宽被工具拒绝。有些工具出于安全考虑如果发现凭证文件是 777 权限会直接拒绝读取报错却说是认证失败。解决办法是chmod 600收紧权限。这个坑我卡了快半小时因为报错信息完全没提权限的事。第二个坑是内网环境下的时间同步。内网服务器往往连不上公网 NTP系统时间长期不校准偏差越来越大最后 TLS 握手全挂。内网部署 dsh-pocket 时一定要确认内网有自己的时间同步服务或者手动定期校准。第三个坑是skill 文件里的路径写成了绝对路径。skill 部署到不同服务器时绝对路径对不上功能就哑火。我的做法是 skill 内部一律用相对路径或环境变量引用部署时只改环境变量不动 skill 文件本身。第四个坑是多工具凭证串用。前面提过这里再强调一次codex cli、zcode cli、dsh-pocket 如果共用一套环境变量命名迟早出事。给每个工具的凭证变量加独立前缀是最省心的做法。第五个坑是升级后旧配置不兼容。dsh-pocket 升级后配置文件的字段结构可能变了旧配置加载时部分字段被忽略表现就是升级前好好的升级后连不通。升级后第一件事是看官方有没有配置迁移说明或者直接备份旧配置、用新版本重新生成一份。排查 dsh-pocket 连不通这件事本质上是在做分层定位把连不通这个模糊现象拆解成安装、认证、网络、配置四个可独立验证的层逐层排除。只要养成先定位层级、再动手修的习惯绝大多数故障都能在十分钟内解决。真正难的不是修而是知道该修哪里——希望上面这套顺序能帮你少走弯路。