故障排除

安装问题

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 密钥)

快速入门

配置

指南

安装问题

配置问题

CLI 执行问题

API 连接问题

Shell 和环境问题

平台特定问题

高级故障排除

启用调试模式

完全重置

收集诊断信息

仍需要帮助?

查看常见问题

电子邮件支持

GitHub Issues

Discord 社区

预防提示

保持工具更新

备份配置

更改后测试

使用版本控制

​安装问题

​配置问题

​CLI 执行问题

​API 连接问题

​Shell 和环境问题

​平台特定问题

​高级故障排除

​启用调试模式

​完全重置

​收集诊断信息

​仍需要帮助?

查看常见问题

电子邮件支持

GitHub Issues

Discord 社区

​预防提示

保持工具更新

备份配置

更改后测试

使用版本控制

安装问题

配置问题

CLI 执行问题

API 连接问题

Shell 和环境问题

平台特定问题

高级故障排除

启用调试模式

完全重置

收集诊断信息

仍需要帮助?

预防提示