SUPPORT

常见问题

安装或使用开发工具时遇到问题，可按下列现象逐项检查。

#连接问题

#401 Unauthorized（未授权）

先确认密钥已正确设置，并检查当前终端是否能够读取对应环境变量。

# Claude Code
echo $ANTHROPIC_API_KEY

# CodeX / OpenAI 兼容客户端
echo $OPENAI_API_KEY

# Gemini CLI
echo $GEMINI_API_KEY

echo $env:ANTHROPIC_API_KEY
echo $env:OPENAI_API_KEY
echo $env:GEMINI_API_KEY

如果变量为空，请重新设置 API Key，再关闭并重新打开终端或工具。

#Connection refused（连接被拒绝）

最常见的原因是 API 地址填写错误。Claude Code 使用根地址；CodeX 和 OpenClaw 使用带 /v1 的 OpenAI 兼容地址。

# Claude Code
https://www.qianmodao.com

# CodeX / OpenClaw
https://www.qianmodao.com/v1

#网络超时

先检查基础网络连通性：

curl -I https://www.qianmodao.com

如果当前网络需要代理，请在终端中正确设置 HTTP_PROXY 与 HTTPS_PROXY，然后重新启动工具。

#安装问题

#npm 权限错误（EACCES）

Linux 或 macOS 可把 npm 全局目录调整到当前用户目录：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

将 PATH 配置写入当前 Shell 的配置文件后，重新加载配置并再次安装。

#node: command not found

node --version
npm --version
which node
echo $PATH

使用 nvm 安装的用户可重新加载 nvm；Windows 用户可重新打开终端，并确认 Node.js 安装目录已加入 PATH。

#命令未找到（claude / codex）

npm config get prefix
npm list -g --depth=0
echo $PATH

确认 npm 全局可执行目录已经加入 PATH，然后重新安装对应 CLI。

#配置问题

#环境变量不生效

临时环境变量只对当前终端有效。需要长期使用时，应写入 Shell 配置文件或使用系统级环境变量。

# zsh
source ~/.zshrc

# bash
source ~/.bashrc

修改后重新打开终端，并用 echo 命令确认变量值。

#配置文件找不到

工具提示找不到配置文件时，可手动创建对应目录和文件。

Claude Code：

mkdir -p ~/.claude
# 创建 ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_API_KEY": "你的千模岛_API令牌",
    "ANTHROPIC_BASE_URL": "https://www.qianmodao.com"
  },
  "model": "自行选择一个该Claude Code分组支持的model（在模型广场查看）"
}

CodeX：

mkdir -p ~/.codex
# 创建 ~/.codex/config.toml
model_provider = "qianmodao"
model = "自行选择一个该CodeX分组支持的model（在模型广场查看）"

[model_providers.qianmodao]
name = "千模岛 API"
base_url = "https://www.qianmodao.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

export OPENAI_API_KEY="你的千模岛_API令牌"

Windows 中将 ~ 替换为 %USERPROFILE%。

#使用问题

#响应速度慢

常见原因是网络延迟或服务器负载。检查网络与代理配置，也可以在有多个可用模型时选择响应更快的模型。

ping www.qianmodao.com

#模型不可用

如果提示模型名称无效，请检查拼写，并以千模岛模型广场对应分组为准。

目标文档列出的主流示例包括 Claude Opus 4.7、Claude Opus 4.6、 GPT-5.5、GPT-5.4 和 GPT-5.3-Codex。

#SSL 证书错误

提示 SSL 证书验证失败时，先更新系统 CA 证书：

# Ubuntu / Debian
sudo apt update && sudo apt install ca-certificates

# Fedora
sudo dnf install ca-certificates

# macOS
brew install ca-certificates

如果问题仍然存在，请检查系统证书、代理证书和网络拦截策略。

#Windows 特定问题

#PowerShell 执行策略错误

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

#编码问题

配置文件出现中文乱码时，请使用不带 BOM 的 UTF-8 编码保存：

$configContent = Get-Content config.toml -Raw
[System.IO.File]::WriteAllText(
  (Join-Path $PWD "config.toml"),
  $configContent,
  [System.Text.UTF8Encoding]::new($false)
)

#macOS 特定问题

#M1/M2 芯片兼容性

# 使用 Rosetta
arch -x86_64 npm install -g @anthropic-ai/claude-code

# 或安装原生版本
npm install -g @anthropic-ai/claude-code --target_arch=arm64

#Homebrew 权限问题

sudo chown -R $(whoami) /usr/local/Homebrew

#获取帮助

查看日志：Claude Code ~/.claude/logs/；CodeX ~/.codex/logs/。
访问千模岛 API 控制台查看服务状态、密钥有效性和余额。
参考 Claude Code 文档与 CodeX 文档。

重点检查

Claude Code 使用不带 /v1 的 https://www.qianmodao.com；CodeX / OpenAI 工具使用带 /v1 的 https://www.qianmodao.com/v1。