🚨 当你熟悉的 AI 编程搭档突然 Bus error 或直接“失联”，别慌！
本文汇总了从“命令找不到”到“核心转储”的典型故障，配上详尽的恢复步骤和图标指引，助你 10 分钟满血复活。

---

📌 引言：当效率工具变成“折腾黑洞”

你一定有过这种体验：
🔹 昨天还流畅地 ckimi 调着 Bug，重启虚拟机后，终端却冷冰冰地甩来一句 env: ‘claude’: No such file or directory。
🔹 好不容易找回命令，满怀期待地启动，结果 Bus error (core dumped) 瞬间把人打回原形。
🔹 终于进了界面，一句 hello 却换来无尽的 Retrying…，代理死活连不上。

这些问题看似诡异，其实根源都是环境配置的“小伤口”——PATH 丢失、二进制损坏、服务未自启、端口随机化……
我把自己连续踩坑的血泪经验整理成这篇自救手册，每一种故障都配有症状 / 诊断 / 处方，跟着走，无需重装系统。

---

🧭 问题一：claude 命令凭空消失

🩺 症状表现

$ ckimi
env: ‘claude’: No such file or directory

直接运行 claude --version 也提示 command not found。
但在 /home/<用户名>/.npm-global/lib/node_modules/... 里面还能找到 claude 的二进制文件。

🔍 诊断过程

• 用 find ~ -name "claude" -type f 2>/dev/null 搜出文件存在 → PATH 未生效。
• npm install -g @anthropic-ai/claude-code 安装时没有报错，但软链接可能断了。

💊 快速处方

✅ 方案一：重建软链接（如果文件完好）

mkdir -p ~/.npm-global/bin
ln -sf ~/.npm-global/lib/node_modules/@anthropic-ai/claude-code/node_modules/@anthropic-ai/claude-code-linux-x64/claude ~/.npm-global/bin/claude

📌 注意路径中的 @anthropic-ai/claude-code-linux-x64 版本号可能不同，请用实际目录名。

✅ 方案二：干脆重装（更彻底）

npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.npm-global/lib/node_modules/@anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

🔧 预防复发

将以下行写入 ~/.bashrc，确保重启后 ~/.npm-global/bin 始终在 PATH 中：

export PATH="$HOME/.npm-global/bin:$PATH"

然后执行 source ~/.bashrc。

---

💢 问题二：Bus error (core dumped) 猛击

🩺 症状表现

启动 Claude Code 时直接：

Bus error (core dumped)

进程闪退，无任何提示。

🔍 诊断过程

• 文件系统没有损坏，内存也够用，其他程序正常。
• 更新或异常关闭可能造成二进制不完整。

💊 快速处方：彻底清除后重装

# 1. 手动删除残留，避免 ENOTEMPTY
rm -rf ~/.npm-global/lib/node_modules/@anthropic-ai/claude-code
rm -rf ~/.npm-global/lib/node_modules/@anthropic-ai/.claude-code-*

# 2. 清理缓存
npm cache clean --force

# 3. 重新安装
npm install -g @anthropic-ai/claude-code

# 4. 验证
claude --version

若依旧报错，可尝试重启虚拟机后再执行重装。

---

🔗 问题三：代理服务“假死”，无限重试

🩺 症状表现

进入 Claude Code 后发送任何消息都提示：

Unable to connect to API (ConnectionRefused)
Retrying in 6s... attempt 5/10

或者明明配置了 litellm，健康检查却返回 401 或端口不是 4000。

🔍 诊断过程

• 用 systemctl --user status litellm.service 发现服务未启动。
• 或者 grep "Uvicorn running" /tmp/litellm.log 发现端口是 0.0.0.0:23567 这样的随机值。
• curl 直接测试 http://localhost:4000/health 失败。

💊 快速处方：固化 litellm+端口

创建稳定的 systemd 用户服务：

[Unit]
Description=LiteLLM Proxy
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/<用户名>/claude-nim-proxy
EnvironmentFile=/home/<用户名>/claude-nim-proxy/.env
ExecStart=/home/<用户名>/claude-nim-proxy/litellm-env/bin/litellm --config /home/<用户名>/claude-nim-proxy/litellm_config.yaml --port 4000
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

启用并立即启动：

systemctl --user daemon-reload
systemctl --user enable litellm.service
systemctl --user start litellm.service

关键步骤：在 litellm_config.yaml 中加入：

litellm_settings:
  drop_params: true

防止 Claude Code 发送的某些参数（如 output_config）被拒绝。

---

🏷️ 问题四：自定义别名“失踪”

🩺 症状表现

辛辛苦苦创建的 ckimi、cqwen 别名，重启后提示 command not found，但 source ~/.bashrc 后又能用了。

🔍 诊断过程

• 非交互式终端（如某些 systemd 环境）不会自动执行 ~/.bashrc。
• 别名不能被其他脚本直接继承。

💊 快速处方：用独立脚本代替别名

创建全局可执行的脚本 /usr/local/bin/ckimi：

#!/bin/bash
exec env ANTHROPIC_BASE_URL=http://localhost:4000 \
         ANTHROPIC_API_KEY=sk-123456 \
         /home/<用户名>/.npm-global/bin/claude \
         --model kimi-k2.6 "$@"

然后：

sudo chmod +x /usr/local/bin/ckimi

现在无论什么终端，都能直接 ckimi 启动。

其他模型同理，比如 cqwen 指向 qwen3.5-max，以此类推。

---

🔐 终极防御：打造“永不断线”的 AI 环境

经过上述磨难，我总结了一套预防策略，可以避免 90% 的重启后崩溃：

策略	说明
🌀 服务 systemd 化	所有后台进程（litellm、记忆服务）都用 systemd 管理，并设置 Restart=on-failure
📂 环境变量集中	使用 EnvironmentFile 统一管理密钥，而非散落在 shell 配置中
🗂️ 二进制固化	用绝对路径脚本取代别名，确保全局可用
🚦 端口锁定	配置文件不写 port，永远用 --port 4000 命令行参数，杜绝随机化
📦 备份关键文件	将 litellm_config.yaml、.env、systemd service 文件、自定义脚本纳入 Git
🔄 更新前清理	先 npm uninstall，再安装新版本，避免残骸引发 ENOTEMPTY 或 Bus error

---

🎯 结语

AI 编程工具的初衷是让我们专注创造，而不是把时间花在环境调试上。
但偏偏这些“小而致命”的故障最喜欢在深夜或死线前偷袭。
希望我整理的这套诊断-处方-预防闭环，能让你下次面对 Bus error 或 ConnectionRefused 时，不再抓狂。

💬 你在使用 Claude Code 或 litellm 时还遇到过哪些灵异问题？欢迎在评论区分享你的避坑经验，我们一起把雷区扫平！

---

本文所有操作均基于 Ubuntu 22.04，其他 Linux 发行版内核相近，路径和包管理器可能略有差异。截图和命令中的敏感信息已用示例值替代，请根据你的实际环境调整。