Claude 接入常见问题

接入或使用过程中遇到报错，可先对照以下情况排查。Claude Desktop 与 Claude Code CLI 共用同一网关地址与 128 位用户 Token。

提示 Token 无效 / 401

回到 CodePass 用户中心重新复制 128 位用户 Token。不要手打，也不要混用 Anthropic 官方 Key 或其他平台的 Key。

Claude Desktop 找不到配置入口

未先开开发者模式，或看错菜单位置。 **macOS**：看屏幕顶部菜单栏（不是窗口内菜单）→ Help → Troubleshooting → Enable Developer Mode，再 Developer → Configure third-party inference。 **Windows**：窗口左上角 ☰ → Help → Troubleshooting → Enable Developer Mode；弹窗须点 **Enable**（不要点 Don't Enable），菜单才会出现 Developer。若仍没有 Developer，说明开发者模式未开成功，先重做这一步。

Claude Desktop 测试连接失败

核对这几项： | 字段 | 正确值 | |------|--------| | Gateway base URL | `https://gw.ca-3.com`（末尾**不要**加 `/v1`） | | Gateway auth scheme | `x-api-key` | | Credential kind | `Static API key` | | Gateway API key | 用户中心复制的 128 位 Token | 先点右上角 **Test connection**，底部出现绿色结果（如 Model discovery / Inference）后再点 **Apply Changes**。

Claude Desktop 改完仍走官方登录

先确认已点 **Apply Changes**，再**完全退出**后重开：macOS 用 `Cmd + Q`；Windows 右键托盘图标退出。仅关窗口不够。重启后发一条「你好」，能正常回复即成功。

Claude Code 报 connection refused

环境变量可能未生效。先检查： 无输出则重开终端后再试。持久化写入 `~/.claude/settings.json`（Windows：`%USERPROFILE%\.claude\settings.json`）或用户环境变量后，也需要新开终端才会生效。

提示连接失败 / Base URL 不对

检查 `ANTHROPIC_BASE_URL` 或 Desktop 的 Gateway base URL 是否完整。正确格式： 末尾不要加 `/v1`（与 Codex 不同）。

不知道现在用的是不是 CodePass

**Claude Code**：启动后输入 `/status`，看到 API Base URL 为 CodePass 地址即已接入；也可检查环境变量。 **Claude Desktop**：看左下角是否出现 Gateway 状态。

之前用个人 API Key，切换后仍走 Anthropic 直连

`ANTHROPIC_API_KEY` 优先级高于 `ANTHROPIC_AUTH_TOKEN`。需先清除个人 Key： 若写进了 `settings.json` 或系统环境变量，也要一并删掉后重开终端 / 客户端。

提示额度不足

Claude 会消耗 CodePass 的共用 API 额度池。额度不足时，需续费 Pass 或购买加油包。

529 或提示并发已满

同时进行的会话数超过上限。等待当前会话完成后重试；通常几秒内自动恢复。

503 上游暂时不可用

资源排队超时或上游繁忙。稍后重试；如持续出现请联系管理员。

模型响应慢或超时

先检查本机网络，再稍后重试。也可先用 curl 验证网关可达： 预期：`HTTP 200` + 正常响应内容。

Cowork 提示「Failed to start Claude's workspace」

通常是 VM 镜像损坏，或无法从 `downloads.claude.ai` 下载（该地址不经过网关，需直连）。 1. 完全退出 Claude Desktop（macOS 用 `Cmd + Q`） 2. 删除 VM 缓存： 3. 清空废纸篓释放空间 4. 重启电脑后重新打开 Claude Desktop，等待 VM 自动重新下载（约 2–5 分钟） 若仍失败，检查网络是否能访问 `downloads.claude.ai`。

Cowork 提示「Workspace still starting」

VM 未完成启动，或 VPN 冲突（Cowork 的 VM 使用 vsock 通信，VPN 可能劫持路由导致通道断裂）。 1. 如有 VPN 在运行，**先关闭 VPN** 再重试 2. 确保至少 4GB 可用内存和 15GB 磁盘空间 3. 等待 30–60 秒让 VM 完成启动

Cowork 并行子代理任务耗时很长

这是正常现象。并行子代理分析完成后，主代理还要合成结果，大上下文可能需要 2–5 分钟。看到「Model is processing internally」说明模型仍在工作，请耐心等待。