Aiapi-doc/support/troubleshooting.md

# 疑难杂症排查指南

本文档汇总了 Claude Code、CodeX、Gemini CLI 等 AI 编程工具在使用 oneinai 服务时的常见问题与解决方案。

## 服务状态查看

排查问题前，建议先确认 oneinai 服务是否正常：

**服务分组状态页**：<https://status.oneinai.cc/>

---

## 一、Claude Code 启动时反复跳登录

### 问题描述

启动 Claude Code 时，反复弹出登录界面，无法进入正常使用状态。

### 解决方案

#### 方案一：使用 CC-Switch 跳过功能

打开 CC-Switch，进入「设置」-「通用」，在「窗口行为」中开启「跳过初次安装确认」开关，即可绕过反复弹出的登录界面。

详细步骤参见：[CC-Switch 初始化设置](</tools/cc-switch#第一步：初始化设置>)

#### 方案二：手动修改配置文件

参考教程：<https://www.cnblogs.com/gordonMlxg/articles/19103691>

---

## 二、API Connect Error 排查

### 排查方向

1. **本地网络异常**
   - 检查网络连接是否正常
   - 尝试访问其他网站验证网络可达性

2. **代理 / 梯子不稳定**
   - 检查代理配置是否正确
   - 尝试切换代理节点

### 建议

**优先尝试直连网络**：关闭代理后测试是否恢复正常。若直连可用，说明问题出在代理链路上。

---

## 三、上下文过大导致异常

### 问题表现

对话中出现异常错误，通常表现为响应失败或返回乱码，多与上下文过大有关。

### 解决方案

1. **新建会话**：开启新的对话，清空上下文。
2. **查看 Token 分布**：执行 `/context` 命令查看当前上下文的 Token 使用情况。
3. **关闭自动压缩**：关闭 Auto Compress 功能，手动控制上下文大小。

---

## 四、Request Timed Out（请求超时）

### 可能原因

1. 本地网络连接问题
2. 代理或梯子状态不稳定
3. 服务端负载过高

### 解决方案

- 检查本地网络连接
- 检查代理或梯子状态
- 必要时切换至直连网络
- 查看 [oneinai 服务状态页](<https://status.oneinai.cc/status/api>) 确认服务可用性

---

## 五、API Error 503

### 错误说明

当前 oneinai 分组服务暂时不可用。

### 解决方案

1. 切换至其他可用的服务分组
2. 通过状态页确认分组的实时状态

**服务状态查看**：<https://status.oneinai.cc/status/api>

---

## 六、Gemini CLI 报错 400

### 问题说明

当前会话异常，通常是会话状态错误导致。

### 解决方案

直接重开会话即可解决。

---

## 七、Claude Code 2.0.73 版本内容割裂

### 问题说明

在 2.0.73 版本中出现对话 / 内容割裂的问题。

### 解决方案：回退版本

```bash
npm install -g @anthropic-ai/claude-code@2.0.72
```

回退到稳定的 2.0.72 版本即可恢复。

---

## 八、关闭 Claude Code 自动更新

### 问题描述

不希望 Claude Code 自动更新到新版本。

### 解决方案

在 `settings.json` 中添加以下环境变量：

```json
{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}
```

或在系统环境变量中设置：

```bash
# macOS / Linux
export DISABLE_AUTOUPDATER=1
```

```powershell
# Windows PowerShell
$Env:DISABLE_AUTOUPDATER = "1"
```

---

## 排查技巧总结

### 快速诊断流程

1. 查看 [oneinai 服务状态页](<https://status.oneinai.cc/status/api>)
2. 检查环境变量配置
3. 验证令牌是否有效
4. 检查网络和代理状态
5. 查看 Token 余额
6. 尝试重新开启会话

### 常用调试命令

#### Claude Code

```bash
/status    # 查看当前会话状态
/context   # 查看上下文 Token 使用
/clear     # 清空当前会话
```

### 环境变量检查

#### Windows

```powershell
# 查看所有 ANTHROPIC 相关变量
Get-ChildItem Env: | Where-Object { $_.Name -like "*ANTHROPIC*" }
```

#### macOS / Linux

```bash
# 查看所有 ANTHROPIC 相关变量
env | grep ANTHROPIC
```

---

## 获取帮助

如果以上方法都无法解决您的问题，请：

- 加入 Telegram 群组：<https://t.me/oneinai>
- 查看 [常见问题 FAQ](</support/faq>)

---

_本文档持续更新中，如有新的疑难杂症欢迎反馈。_