故障排除 - MegaLLM

安装问题

npm: 未找到命令

Node.js 和 npm 未安装。解决方案:

macOS
Linux
Windows

# 使用 Homebrew
brew install node

# 或从 nodejs.org 下载

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
sudo dnf install nodejs

验证安装:

node --version
npm --version

EACCES 权限被拒绝错误

您没有安装全局包的权限。解决方案 1: 配置 npm 使用不同的目录 (推荐)

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# 添加到 ~/.bashrc 或 ~/.zshrc
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

解决方案 2: 修复 npm 权限

sudo chown -R $USER /usr/local/lib/node_modules
sudo chown -R $USER /usr/local/bin

解决方案 3: 使用 npx (无需安装)

npx megallm@latest

使用了旧版本

npm 缓存中有过时的版本。解决方案:

# 清除 npm 缓存
npm cache clean --force

# 运行最新版本
npx megallm@latest

# 或更新全局安装
npm update -g megallm

# 验证版本
npx megallm@latest --version

配置问题

配置未加载

配置文件未被读取。诊断:

# 检查文件是否存在
ls -la ~/.claude/settings.json
ls -la ~/.codex/config.toml
ls -la ~/.config/opencode/opencode.json

# 检查项目级配置
ls -la .claude/settings.json
ls -la opencode.json

解决方案:1. 验证文件位置:

# Claude Code
~/.claude/settings.json          # 系统级
./.claude/settings.json          # 项目级

# Codex
~/.codex/config.toml             # 仅系统级

# OpenCode
~/.config/opencode/opencode.json # 系统级
./opencode.json                  # 项目级

2. 检查文件权限:

chmod 644 ~/.claude/settings.json
chmod 644 ~/.codex/config.toml
chmod 644 ~/.config/opencode/opencode.json

3. 验证语法:

# JSON 文件
jq . ~/.claude/settings.json

# TOML 文件
cat ~/.codex/config.toml
# (安装 toml-cli 进行验证)

4. 检查工作目录:

pwd
# 对于项目级配置,您必须在项目目录中

API 密钥未被识别

API 密钥未从配置或环境中读取。诊断:

# 检查环境变量
echo $ANTHROPIC_API_KEY
echo $MEGALLM_API_KEY

# 检查配置文件
jq '.env.ANTHROPIC_API_KEY' ~/.claude/settings.json
cat ~/.codex/config.toml | grep MEGALLM_API_KEY
jq '.provider.anthropic.options.apiKey' ~/.config/opencode/opencode.json

解决方案:1. 重新加载 shell 配置:

source ~/.bashrc  # 或 ~/.zshrc
# 或重启您的终端

2. 验证 API 密钥格式:

必须以 sk-mega- 开头
至少 20 个字符长
密钥周围没有空格或引号

3. 手动设置环境变量:

# Claude Code
export ANTHROPIC_API_KEY="sk-mega-your-key"

# Codex/Windsurf 和 OpenCode
export MEGALLM_API_KEY="sk-mega-your-key"

4. 直接测试 API 密钥:

curl -H "Authorization: Bearer sk-mega-your-key" \
     https://ai.megallm.io/v1/models

使用了错误的基础 URL

工具连接到了错误的 API 端点。诊断:

# 检查环境变量
echo $ANTHROPIC_BASE_URL

# 检查配置文件
jq '.env.ANTHROPIC_BASE_URL' ~/.claude/settings.json
cat ~/.codex/config.toml | grep base_url
jq '.provider.anthropic.options.baseURL' ~/.config/opencode/opencode.json

解决方案:确保基础 URL 完全正确:

https://ai.megallm.io

常见错误:

# <Icon icon="xmark" /> 错误
https://ai.megallm.io/      # 尾部斜杠
https://ai.megallm.io/v1/   # 额外的 /v1/ (仅 Codex/OpenCode)
http://ai.megallm.io        # HTTP 而不是 HTTPS

# <Icon icon="check" /> Claude Code 的正确格式
https://ai.megallm.io

# <Icon icon="check" /> Codex/OpenCode 的正确格式
https://ai.megallm.io/v1

修复:

# Claude Code
export ANTHROPIC_BASE_URL="https://ai.megallm.io"

# 使用正确的 URL 更新配置文件

配置优先级问题

使用了错误的配置。理解优先级:

环境变量 (最高)

在 shell 中设置的变量始终优先

项目级配置

当前目录中的配置 (.claude/, opencode.json)

系统级配置 (最低)

主目录中的全局配置 (~/.claude/, ~/.codex/, ~/.config/opencode/)

诊断:

# 检查在哪里设置了什么
echo "环境变量: $ANTHROPIC_API_KEY"
echo "项目: $(jq -r '.env.ANTHROPIC_API_KEY' .claude/settings.json 2>/dev/null)"
echo "系统: $(jq -r '.env.ANTHROPIC_API_KEY' ~/.claude/settings.json 2>/dev/null)"

解决方案:删除冲突的配置或使用正确的优先级:

# 要强制使用项目级,取消设置环境变量
unset ANTHROPIC_API_KEY

# 要强制使用环境变量,设置它
export ANTHROPIC_API_KEY="sk-mega-your-key"

CLI 执行问题

CLI 挂起或冻结

CLI 在执行过程中卡住。解决方案:1. 取消并重试:

# 按 Ctrl+C 取消
# 然后再次运行
npx megallm@latest

2. 检查提示: CLI 可能正在等待输入。查找以下问题:

“输入您的 API 密钥:”
“继续? (y/n)”

3. 使用调试模式运行:

DEBUG=* npx megallm@latest
# 显示正在发生的详细日志

4. 检查后台进程:

# 检查是否有另一个实例正在运行
ps aux | grep megallm

工具未检测到

CLI 说工具未安装但它确实安装了。诊断:

# 检查工具是否全局安装
npm list -g --depth=0 | grep claude
npm list -g --depth=0 | grep codex
npm list -g --depth=0 | grep opencode

# 检查命令是否可用
which claude-code
which codex
which windsurf
which opencode

解决方案:1. 确保全局安装:

npm install -g @anthropic-ai/claude-code
npm install -g @codeium/windsurf
npm install -g opencode

2. 重启终端:

# 关闭并重新打开终端
# 或重新加载 shell 配置
source ~/.bashrc

3. 检查 PATH:

echo $PATH
# 应该包含 npm 全局 bin 目录

4. 手动配置: 如果检测失败,在不使用 CLI 的情况下手动配置。

创建配置文件时权限被拒绝

CLI 无法写入配置目录。解决方案:macOS/Linux:

# 修复所有权
sudo chown -R $USER ~/.claude ~/.codex ~/.config/opencode

# 修复权限
chmod -R 755 ~/.claude ~/.codex ~/.config/opencode

# 对于项目配置
chmod -R 755 .claude

Windows: 以管理员身份运行终端或在文件资源管理器中修复文件夹权限。

API 连接问题

API 连接失败

无法连接到 MegaLLM API。诊断:

# 测试 API 连接
curl -v https://ai.megallm.io/v1/models \
  -H "Authorization: Bearer sk-mega-your-key"

解决方案:1. 检查互联网连接:

ping -c 3 ai.megallm.io

2. 检查防火墙/代理:

# 如果在代理后面,设置 npm 代理
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

3. 验证 API 密钥:

访问 megallm.io/dashboard
生成新的 API 密钥
更新您的配置

4. 检查 API 状态: 访问 megallm.io/status 查看服务状态

401 未授权错误

API 密钥无效或已过期。解决方案:1. 生成新的 API 密钥:

访问 megallm.io/dashboard
创建新的 API 密钥
更新配置

2. 更新配置:

# 再次运行 CLI 进行重新配置
npx megallm@latest

# 或手动更新
jq '.env.ANTHROPIC_API_KEY = "new-key"' ~/.claude/settings.json > tmp.json && mv tmp.json ~/.claude/settings.json

3. 清除并重置:

# 删除旧配置
rm ~/.claude/settings.json ~/.claude.json
rm ~/.codex/config.toml
rm ~/.config/opencode/opencode.json

# 重新运行 CLI
npx megallm@latest

超出速率限制

在短时间内发送了太多 API 请求。解决方案:1. 等待并重试: 速率限制通常在一段时间后重置(通常 1 分钟)。2. 检查您的使用情况:

访问 megallm.io/dashboard
查看 API 使用统计信息

3. 升级计划: 如果您经常遇到速率限制,请考虑升级您的计划。4. 实施重试逻辑:

# 在您的应用程序代码中
import time
import openai

for i in range(3):
    try:
        response = client.chat.completions.create(...)
        break
    except openai.RateLimitError:
        if i < 2:
            time.sleep(2 ** i)  # 指数退避
        else:
            raise

Shell 和环境问题

环境变量未持久化

关闭终端后变量丢失。解决方案:环境变量必须添加到 shell 配置文件:

# 确定您的 shell
echo $SHELL

# bash: ~/.bashrc 或 ~/.bash_profile
echo 'export ANTHROPIC_API_KEY="sk-mega-..."' >> ~/.bashrc
source ~/.bashrc

# zsh: ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-mega-..."' >> ~/.zshrc
source ~/.zshrc

# fish: ~/.config/fish/config.fish
echo 'set -x ANTHROPIC_API_KEY "sk-mega-..."' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

验证:

# 关闭终端
# 打开新终端
echo $ANTHROPIC_API_KEY
# 应该显示您的密钥

Shell 配置未重新加载

对 shell 配置的更改未生效。解决方案:1. 重新加载 shell 配置:

# bash
source ~/.bashrc

# zsh
source ~/.zshrc

# fish
source ~/.config/fish/config.fish

2. 重启终端: 关闭并重新打开您的终端应用程序。3. 检查语法错误:

# bash/zsh
bash -n ~/.bashrc  # 检查语法
bash -n ~/.zshrc

# fish
fish -n ~/.config/fish/config.fish

4. 检查文件是否实际修改:

tail -20 ~/.bashrc
# 应该显示您最近的添加

平台特定问题

macOS: 安装后找不到命令

npm 全局包的 PATH 未更新。解决方案:

# 将 npm 全局 bin 添加到 PATH
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.zshrc
source ~/.zshrc

# 或对于 bash
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

Windows: PowerShell 执行策略

脚本被 PowerShell 执行策略阻止。解决方案:

# 以管理员身份运行 PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 然后运行 CLI
npx megallm@latest

Linux: /usr/local/lib 权限问题

由于权限问题无法安装全局包。解决方案:

# 选项 1: 使用 nvm (推荐)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# 选项 2: 更改 npm 前缀
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

高级故障排除

启用调试模式

获取详细日志以诊断问题:

# 使用调试输出运行
DEBUG=* npx megallm@latest

# 或设置环境变量
export DEBUG=*
npx megallm@latest

完全重置

如果所有其他方法都失败,完全重置配置:

# 1. 备份现有配置
mkdir ~/megallm-backup
cp -r ~/.claude ~/megallm-backup/
cp -r ~/.codex ~/megallm-backup/
cp -r ~/.config/opencode ~/megallm-backup/

# 2. 删除所有配置
rm -rf ~/.claude
rm -rf ~/.codex
rm -rf ~/.config/opencode
rm -rf .claude
rm -f opencode.json

# 3. 删除环境变量
# 编辑 ~/.bashrc 或 ~/.zshrc 并删除包含以下内容的行:
# - ANTHROPIC_BASE_URL
# - ANTHROPIC_API_KEY
# - MEGALLM_API_KEY

# 4. 重新加载 shell
source ~/.bashrc

# 5. 重新运行 CLI
npx megallm@latest

收集诊断信息

对于支持请求,收集此信息:

# 系统信息
uname -a
node --version
npm --version

# 检查配置
ls -la ~/.claude/ ~/.codex/ ~/.config/opencode/
cat ~/.claude/settings.json
cat ~/.codex/config.toml
cat ~/.config/opencode/opencode.json

# 检查环境
env | grep -E "ANTHROPIC|MEGALLM"

# 使用调试运行
DEBUG=* npx megallm@latest 2>&1 | tee megallm-debug.log

仍需要帮助?

如果您仍然遇到问题:

查看常见问题

常见问题和答案

电子邮件支持

从我们的团队获得帮助

GitHub Issues

报告错误或搜索现有问题

Discord 社区

向社区提问

预防提示

保持工具更新

定期更新 Node.js、npm 和 AI 工具

备份配置

保留工作配置的备份

更改后测试

手动编辑后验证配置

使用版本控制

提交工作配置(不包含 API 密钥)

Documentation Index

​安装问题

​配置问题

​CLI 执行问题

​API 连接问题

​Shell 和环境问题

​平台特定问题

​高级故障排除

​启用调试模式

​完全重置

​收集诊断信息

​仍需要帮助?