1. pstack-claude 是什么先说项目背景pstack-claude 这个项目最早是从一次 Claude Code 卡死开始的。当时我正在改一段还算复杂的脚本Claude Code 跑着跑着就不输出内容了终端光标在闪电脑风扇却越转越快。我等了半分钟没反应第一反应是崩溃了最后直接在终端里敲了pgrep -af claude然后把对应的进程树翻出来。那时候就产生了一个特别直接的想法要是能像 Linux 下的 pstack 一样随时看一眼 Claude 进程到底“卡在哪一行”调试就会轻松很多。pstack 这个命令老运维应该很熟。它可以把一个正在运行的进程的调用栈打印出来等同于快速抓取当前线程的执行位置。Claude Code 则是 Anthropic 推出的命令行编程助手核心跑在 Node.js 上。表面看这两者没什么关系但组合起来很有价值Claude Code 的进程在复杂任务里会长时间驻留一旦遇到死锁、等待子进程、更新脚本卡住日志只会告诉你“刚才发生了什么”不会告诉你“现在到底卡在哪个函数里”。pstack 正好补上这个缺口。所以 pstack-claude 不是要替代 Claude Code也不是要 hack Anthropic 的协议而是一套围绕 Claude Code 的“现场快照型诊断工具”。它把四件事放在一起环境自检、进程栈抓取、日志对照、模型服务切换。适合正在折腾 Claude Code、遇到了安装失败或运行卡死的人尤其是 Windows 下用 WSL 跑 Claude Code 的这批用户。1.1 为什么偏偏选了 pstack 而不是日志先说结论日志适合复盘栈快照适合定位“现在”。Claude Code 自身也提供调试模式比如ANTHROPIC_LOGdebug、claude --verbose日志文件会落在~/.claude/logs下。但日志量一多找有效信息的时间成本很高。更麻烦的是有些卡死发生在模型已经返回、终端输出却被子进程吞掉的场景里日志末尾看起来一切正常但用户端就是没有反应。这时候日志帮不上忙只有去看进程栈才知道线程停在读取管道、等待锁、还是在忙轮询。pstack 的思路和体检一样不看你过去得过什么病而是测你此刻的心跳、血压和脑电波。带着这个想法我给 Claude Code 的进程做了一套采样脚本并把项目命名为 pstack-claude。名字里的 pstack 就是一种方法论的代号先看现场再翻历史。1.2 pstack-claude 的组成模块这个项目按使用场景分成三个模块环境模块检测 WSL、Windows 虚拟机平台、Node/npm 安装状态处理virtual machine platform not available、npm prefix权限这类安装或升级问题。诊断模块用 pstack 或 gdb 抓 Claude Code 进程的调用栈支持连续多次采样对比栈帧变化判断是真死锁还是单纯等待。接入模块通过环境变量切换 Anthropic 兼容的模型服务比如把 Claude Code 接到 DeepSeek 的 Anthropic 兼容端点让工具链不被某一家的限制绑死。模块之间互相独立。即使你不用模型切换也能靠环境模块和诊断模块解决大部分运行问题。2. Claude Code 环境准备与安装踩坑2.1 Windows 下开启虚拟机平台和 WSL在 Windows 上跑 Claude Code最常用的方式是开 WSL在 Ubuntu 里安装。但不少人第一次安装就撞上一行报错Claudes workspace requires the virtual machine platform on Windows. Enable the Windows Hypervisor Platform。这个报错不是 Claude Code 的问题而是 Windows 的虚拟化功能没有开。你需要在“控制面板 - 程序 - 启用或关闭 Windows 功能”里勾选这几项虚拟机平台Windows 虚拟机监控程序平台适用于 Linux 的 Windows 子系统选完之后重启电脑。这里要重点提醒一句如果你平时还用 VMware 或 VirtualBox 跑别的虚拟机开启 Hypervisor Platform 之后可能会有性能或兼容性影响需要在装 Claude Code 之前想好是否要长期开启。重启后打开管理员 PowerShell安装并确认 WSLwsl --install -d Ubuntu-22.04 wsl -l -vwsl -l -v输出里能看到 Ubuntu 的版本号如果显示 VERSION 2说明 WSL2 正常。如果你之前装的 WSL1需要手动转换wsl --set-version Ubuntu-22.04 2Claude Code 的源码和运行模型都依赖 WSL2 提供的完整内核能力WSL1 会导致不少诡异问题比如文件监听失效、网络访问异常这些症状很难通过日志判断。2.2 使用 npm 安装 Claude CodeWSL 启动后在 Ubuntu 里装 Node.js 和 npm。我建议先用 nvm 装 LTS 版本避免系统包管理器给的 Node 版本太老curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts node -v npm -v然后安装 Claude Codenpm install -g anthropic-ai/claude-code安装完成后直接运行claude走官方登录流程即可。如果你更习惯传密钥也可以用ANTHROPIC_API_KEY环境变量直连这样不需要浏览器登录流程。2.3 自动更新报错 no write permission to npm prefix这是真正高频出现的坑。Claude Code 内置自动更新默认逻辑是把 npm 全局包替换成新版本。如果你的 npm 全局目录是/usr/local/lib/node_modules而当前用户对/usr/local没有写权限就会看到auto-update failed: no write permission to npm prefix这个问题有两种修法。第一种把 npm 全局目录改到用户目录下然后重装 Claude Codenpm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc npm install -g anthropic-ai/claude-code第二种保留系统级全局目录直接把 node_modules 和命令目录的属主改成当前用户。但这对多用户环境不友好所以我更推荐第一种。改完之后记得检查which claude npm prefix -g如果which claude指向~/.npm-global/bin/claude说明路径已经生效。之后再跑自动更新基本不会再碰到权限报错。2.4 VSCode 和 Trae 里使用 Claude Code如果你习惯在 VSCode 里操作可以直接安装 Claude Code 扩展然后在扩展设置里绑定 WSL 环境中的 CLI 路径。重点是把扩展的 shell 环境配置成和你终端一致的 npm 全局路径不然扩展里会出现“找不到 claude 命令”。Trae 这类 IDE 的原理也一样。IDE 本身只是提供一个终端和上下文窗口核心还是调用命令行里的 claude 程序。所以你在 IDE 里配 Claude 模型的时候真正要做的是让 IDE 能读到同一个 Node、同一个 npm 全局安装路径、同一份~/.claude/settings.json。很多人在 Trae 里配不上不是因为 IDE 不支持而是环境变量没配对。如果你要用 MCP记得确认npx也在 PATH 里。Claude Code 的不少 MCP server 是以 npx 命令形式启动的npx找不到会导致 MCP 连接失败报错内容和权限无关容易被误判。3. 核心实现pstack-claude 如何抓取进程栈3.1 为什么需要循环采样单次 pstack 只能看到一瞬的栈帧很多卡死状态是“间歇性”的。比如进程每秒醒一次然后又睡过去你单次采样很可能刚好采到睡眠状态看起来一切都正常但实际任务就是推不下去。所以 pstack-claude 的脚本做了一件很简单但很实用的变换连续采样三次每次隔三秒然后把三次结果合并到一个日志文件里。如果三次的栈顶都停在同一处说明进程大概率在一个长期阻塞或死循环里如果三次栈各不相同说明进程还在活动只是暂时没有输出或等待网络这种情况可能需要继续观察或查网络连接状态。3.2 一份可直接落地的采样脚本下面是我在 pstack-claude 里使用的简化版本放在 Ubuntu/WSL 里可以直接跑#!/usr/bin/env bash set -uo pipefail LOG_DIR${1:-/tmp/pstack-claude} mkdir -p $LOG_DIR PIDS$(pgrep -af claude-code|anthropic-ai | awk {print $1}) if [ -z $PIDS ]; then PIDS$(pgrep -af claude | awk {print $1} | head -n 20) fi if [ -z $PIDS ]; then echo no claude process found exit 1 fi for i in 1 2 3; do LOG_FILE$LOG_DIR/sample-$i-$(date %H%M%S).log echo sample $i at $(date) | tee -a $LOG_FILE for PID in $PIDS; do echo ---- PID $PID ---- | tee -a $LOG_FILE pstack $PID $LOG_FILE 21 || \ gdb -p $PID -batch -ex thread apply all bt $LOG_FILE 21 done sleep 3 done这里的逻辑是先用pgrep找 Claude Code 对应的 Node 进程再逐一对进程执行pstack。如果系统没有 pstack则自动退回到gdb -p PID -batch -ex thread apply all bt效果类似只是 gdb 输出的符号信息更粗糙一些。生成的日志在/tmp/pstack-claude/sample-*.log下文件名带时间戳方便对照某个时间点前后的行为。3.3 栈输出到底怎么读抓完栈之后很多人会盯着十六进制地址发呆。实际不需要看懂全部只需要抓住栈顶和栈底。栈顶就是当前 CPU 正在执行的函数。栈底等于入口函数通常保持不变。举例来说如果栈顶停在epoll_wait、uv__io_poll、do_sys_poll这类位置说明 Node 事件循环在等待 I/O 事件这最多算“空闲”不代表真卡死。真正的卡死通常有两个特征栈顶长时间没有任何变化并且 CPU 占用保持在高位或者多个线程都停在某个锁函数上比如futex_wait、pthread_cond_wait那大概率是线程死锁。我碰过一种情况pstack 采样三次栈顶始终停在process_buffer一类的自定义函数上CPU 拉满但终端不输出。查了 Claude Code 日志才发现是自动更新脚本和主进程在抢同一个临时目录锁。最后把自动更新权限问题解决掉再重启 Claude Code问题就消失了这个案例也正是 pstack-claude 最有价值的场景。需要注意的是pstack对目标进程有短时间停顿影响。调试一个自己正在使用的工作进程没问题但如果在生产服务器上抓别人的进程最好先评估影响不要随手狂采。4. 让 Claude Code 对接 DeepSeek 等 Anthropic 兼容服务4.1 换模型服务不意味着换工具最近不少人在把 Claude Code 接到 DeepSeek 上。这里先澄清一个概念Claude Code 本身只是一个客户端它通过 Anthropic Messages API 协议和模型服务通信。只要服务端能够兼容这套协议Claude Code 并不关心对面跑的是 Claude 大模型还是 DeepSeek。DeepSeek 提供 Anthropic 兼容端点所以你可以直接用环境变量切换。这比很多IDE里硬改插件配置要干净得多而且对 pstack-claude 这类诊断工具来说环境变量是透明的进程栈、日志、采样逻辑都不需要改动。4.2 切换 DeepSeek 的具体步骤在 WSL 里执行export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的DeepSeek API Key export ANTHROPIC_MODELdeepseek-chat然后运行claude如果你想在.claude/settings.json里固化这个配置可以写到env字段{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: 你的DeepSeek API Key, ANTHROPIC_MODEL: deepseek-chat } }这里有两个容易出错的地方。第一个变量名不是ANTHROPIC_API_KEY而是ANTHROPIC_AUTH_TOKEN。兼容服务解析认证信息时读的是ANTHROPIC_AUTH_TOKEN用错变量会一直报 401。第二个模型名要把默认的 Claude 模型改成实际可用的deepseek-chat或你账号下对应的模型 ID保留默认模型会导致 “model not found” 的报错。4.3 用 pstack-claude 确认配置是否生效切换完模型之后怎么确认进程真的读到了新配置可以在 Claude Code 运行的情况下用 pstack-claude 的记录脚本顺带把进程环境变量翻出来PID$(pgrep -f claude-code | head -n 1) tr \0 \n /proc/$PID/environ | grep -E ANTHROPIC|DEEPSEEK如果输出里有ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic说明配置已经生效。如果输出为空说明环境变量没传到进程可能在启动 Claude Code 之前就没写入或 IDE 在启动时覆盖了环境。这种方式特别适合排错因为它能看到进程真正的运行环境而不是你在终端里临时 setup 的“理想环境”。VSCode 扩展、Trae IDE、WSL 开机自启服务都会各自维护一套环境你很难保证它们配置一致用/proc检查是唯一可信的确认途径。5. 常见问题排查速查表5.1 高频报错与处理对照现象可能原因处理方式Claudes workspace requires the virtual machine platform on WindowsWindows 虚拟化功能未开启打开“虚拟机平台”和“Windows 虚拟机监控程序平台”重启auto-update failed: no write permission to npm prefixnpm 全局目录无写权限npm config set prefix ~/.npm-global重装 Claude Codeapp unavailable / Claude is only available in certain regions官方服务区域或账号状态限制以服务商官方说明为准不推荐任何第三方共享账号或不明来源的工具WSL 里安装成功但 claude 命令找不到PATH 未包含全局 bin 目录把~/.npm-global/bin加入.bashrc的 PATHVSCode 扩展提示找不到 CLI扩展 shell 环境和终端不一致在扩展设置里明确指向 WSL 中的 claude 绝对路径pstack: command not found系统没有安装 pstackapt install pstack或脚本自动回退到 gdb切换 DeepSeek 后报 model not found模型名仍为默认 Claude 模型设置ANTHROPIC_MODELdeepseek-chat切换 DeepSeek 后报 401变量名或密钥错误改用ANTHROPIC_AUTH_TOKEN确认密钥有效MCP 启动时报找不到 servernpx 不在 PATH 中检查 Node/npm 安装路径把 npx 目录加入 PATH启动时出现 start in cowork 之类的目录报错工作区路径或权限不对切到正确的项目目录重建 workspace确认目录可写这张表基本覆盖了 Claude Code 从安装到使用过程里最容易踩的位置。很多问题只靠看日志无法判断真实原因是环境变量或文件权限。5.2 几个排查心法先说第一个遇到卡死不要急着 kill。先采样再复现最后再处理。pstack-claude 的脚本三秒采样一次日志文件会保留后续复盘非常有价值。很多时候所谓卡死只是网络波动进程内部在等待超时多等 30 秒自己就恢复了。第二个Claude Code 的自动更新是很多问题的根因。如果你刚跑完claude就出现各种奇怪现象先看进程中是不是多了一个“安装更新”的临时进程。检查方式很简单ps -ef | grep -i claude | grep -i install有的话等它做完再继续操作。频繁切换模型服务和模型版本时旧进程和新版本同时存在也会导致行为异常。第三个环境变量一定要通过/proc验证而不是只信终端输出。尤其是用了 VSCode 和 Trae 之后环境差异是看不见的。pstack-claude 里加一个env子命令把所有相关进程的环境变量打出来这是我在实际调试中习惯了很久、但收益最高的一个习惯。我第一次跑通 pstack-claude 的完整流程是在 Windows 11 上开 WSL2装完 Claude Code然后抓了一次某次卡死的进程栈。那次抓栈的输出让我意识到所谓“Claude Code 傻了”很多时候只是它在等待自动更新锁。现在我的做法很固定先看版本再看栈最后看日志三步下来基本不会再浪费时间乱猜。