From 527dc282b82a871a150c11971d9c2a4308609abe Mon Sep 17 00:00:00 2001
From: zyc123 <2594064239@qq.com>
Date: Thu, 14 May 2026 18:13:54 +0800
Subject: [PATCH] 943
---
support/troubleshooting.md | 275 ++++++++++++++++---------------------
1 file changed, 116 insertions(+), 159 deletions(-)
diff --git a/support/troubleshooting.md b/support/troubleshooting.md
index 6461380..ede7a4f 100644
--- a/support/troubleshooting.md
+++ b/support/troubleshooting.md
@@ -1,249 +1,206 @@
-# 疑难杂症排查指南
+# 疑难杂症排查指南
-本文档汇总了 Claude Code、CodeX、Gemini CLI 等 AI 编程工具的常见问题和解决方案。
+本文档汇总了 Claude Code、CodeX、Gemini CLI 等 AI 编程工具在使用 oneinai 服务时的常见问题与解决方案。
-## 🔍 服务状态查看
+## 服务状态查看
-在排查问题前，建议先查看服务状态：
+排查问题前，建议先确认 oneinai 服务是否正常：
-**服务分组状态页** ：
+**服务分组状态页**：
-* * *
+---
-## 一、Claude Code 启动时跳登录
+## 一、Claude Code 启动时反复跳登录
-### 问题描述
+### 问题描述
-启动 Claude Code 时，反复弹出登录界面。
+启动 Claude Code 时，反复弹出登录界面，无法进入正常使用状态。
-### 解决方案
+### 解决方案
-#### 方案一：使用 CC-Switch 跳过功能
+#### 方案一：使用 CC-Switch 跳过功能
打开 CC-Switch，进入「设置」-「通用」，在「窗口行为」中开启「跳过初次安装确认」开关，即可绕过反复弹出的登录界面。
详细步骤参见：[CC-Switch 初始化设置]()
-#### 方案二：手动修改配置文件
+#### 方案二：手动修改配置文件
参考教程：
-* * *
+---
-## 四、API Connect Error 排查
+## 二、API Connect Error 排查
-### 排查方向
+### 排查方向
- 1. **本地网络异常**
+1. **本地网络异常**
+ - 检查网络连接是否正常
+ - 尝试访问其他网站验证网络可达性
- * 检查网络连接是否正常
- * 尝试访问其他网站验证网络
- 2. **代理/梯子不稳定**
+2. **代理 / 梯子不稳定**
+ - 检查代理配置是否正确
+ - 尝试切换代理节点
- * 检查代理配置
- * 尝试切换代理节点
+### 建议
-### 建议
+**优先尝试直连网络**：关闭代理后测试是否恢复正常。若直连可用，说明问题出在代理链路上。
-👉 **尝试直接使用直连网络**
+---
-关闭代理后测试是否恢复正常。
+## 三、上下文过大导致异常
-* * *
+### 问题表现
-## 八、CC 上下文过大导致异常
+对话中出现异常错误，通常表现为响应失败或返回乱码，多与上下文过大有关。
-### 问题表现
+### 解决方案
-对话中出现异常错误，通常与上下文过大有关。
+1. **新建会话**：开启新的对话，清空上下文。
+2. **查看 Token 分布**：执行 `/context` 命令查看当前上下文的 Token 使用情况。
+3. **关闭自动压缩**：关闭 Auto Compress 功能，手动控制上下文大小。
-### 解决方案
+---
- 1. **新建会话**
+## 四、Request Timed Out（请求超时）
- * 开启新的对话，清空上下文
- 2. **查看 Token 分布**
-
- /context
+### 可能原因
-1
+1. 本地网络连接问题
+2. 代理或梯子状态不稳定
+3. 服务端负载过高
-查看当前上下文的 Token 使用情况
+### 解决方案
- 3. **关闭自动压缩**
+- 检查本地网络连接
+- 检查代理或梯子状态
+- 必要时切换至直连网络
+- 查看 [oneinai 服务状态页]() 确认服务可用性
- * 关闭 Auto Compress（自动压缩）功能
- * 手动控制上下文大小
+---
-* * *
+## 五、API Error 503
-## 九、Request Timed Out（请求超时）
+### 错误说明
-### 可能原因
+当前 oneinai 分组服务暂时不可用。
- 1. 本地网络连接问题
- 2. 代理或梯子状态不稳定
- 3. 服务端负载过高
+### 解决方案
-### 解决方案
+1. 切换至其他可用的服务分组
+2. 通过状态页确认分组的实时状态
- * 检查本地网络连接
- * 检查代理或梯子状态
- * 必要时尝试直连网络
- * 查看[服务状态页]()确认服务可用性
+**服务状态查看**：
-* * *
+---
-## 十、API Error 503
+## 六、Gemini CLI 报错 400
-### 错误说明
-
-当前分组服务不可用。
-
-### 解决方案
-
- 1. 切换至其他可用服务分组
- 2. 通过状态页确认分组状态
-
-**服务状态查看** ：
-
-* * *
-
-## 十一、Gemini CLI 报错 400
-
-### 问题说明
+### 问题说明
当前会话异常，通常是会话状态错误导致。
-### 解决方案
+### 解决方案
直接重开会话即可解决。
-* * *
+---
-## 十二、Claude Code 2.0.73 版本内容割裂
+## 七、Claude Code 2.0.73 版本内容割裂
-### 问题说明
+### 问题说明
-在 2.0.73 版本中出现对话/内容割裂问题。
+在 2.0.73 版本中出现对话 / 内容割裂的问题。
-### 解决方案：回退版本
+### 解决方案：回退版本
-bash
-
-
- npm install -g @anthropic-ai/claude-code@2.0.72
+```bash
+npm install -g @anthropic-ai/claude-code@2.0.72
+```
-1
+回退到稳定的 2.0.72 版本即可恢复。
-回退到稳定的 2.0.72 版本。
+---
-* * *
+## 八、关闭 Claude Code 自动更新
-## 十三、如何关闭 Claude Code 自动更新
-
-### 问题描述
+### 问题描述
不希望 Claude Code 自动更新到新版本。
-### 解决方案
+### 解决方案
在 `settings.json` 中添加以下环境变量：
-json
-
-
- {
- "env": {
- "DISABLE_AUTOUPDATER": "1"
- }
- }
-
-1
-2
-3
-4
-5
+```json
+{
+ "env": {
+ "DISABLE_AUTOUPDATER": "1"
+ }
+}
+```
或在系统环境变量中设置：
-bash
-
-
- # macOS/Linux
- export DISABLE_AUTOUPDATER=1
-
- # Windows PowerShell
- $Env:DISABLE_AUTOUPDATER = "1"
+```bash
+# macOS / Linux
+export DISABLE_AUTOUPDATER=1
+```
-1
-2
-3
-4
-5
+```powershell
+# Windows PowerShell
+$Env:DISABLE_AUTOUPDATER = "1"
+```
-* * *
+---
-## 🔧 排查技巧总结
+## 排查技巧总结
-### 快速诊断流程
+### 快速诊断流程
- 1. ✅ 查看[服务状态页]()
- 2. ✅ 检查环境变量配置
- 3. ✅ 验证令牌是否有效
- 4. ✅ 检查网络和代理状态
- 5. ✅ 查看 Token 余额
- 6. ✅ 尝试重新开启会话
+1. 查看 [oneinai 服务状态页]()
+2. 检查环境变量配置
+3. 验证令牌是否有效
+4. 检查网络和代理状态
+5. 查看 Token 余额
+6. 尝试重新开启会话
-### 常用调试命令
+### 常用调试命令
-#### Claude Code
+#### Claude Code
-bash
-
-
- /status # 查看当前会话状态
- /context # 查看上下文 Token 使用
- /clear # 清空当前会话
+```bash
+/status # 查看当前会话状态
+/context # 查看上下文 Token 使用
+/clear # 清空当前会话
+```
-1
-2
-3
+### 环境变量检查
-### 环境变量检查
+#### Windows
-#### Windows
+```powershell
+# 查看所有 ANTHROPIC 相关变量
+Get-ChildItem Env: | Where-Object { $_.Name -like "*ANTHROPIC*" }
+```
-powershell
-
-
- # 查看所有 ANTHROPIC 相关变量
- Get-ChildItem Env: | Where-Object {$_.Name -like "*ANTHROPIC*"}
+#### macOS / Linux
-1
-2
+```bash
+# 查看所有 ANTHROPIC 相关变量
+env | grep ANTHROPIC
+```
-#### macOS/Linux
+---
-bash
-
-
- # 查看所有 ANTHROPIC 相关变量
- env | grep ANTHROPIC
-
-1
-2
-
-* * *
-
-## 📮 获取帮助
+## 获取帮助
如果以上方法都无法解决您的问题，请：
- * 📧 查看[售前售后]()联系客服
- * 💬 加入 Telegram 群组：
- * 📖 查看[常见问题 FAQ]()
+- 查看 [售前售后]() 联系 oneinai 客服
+- 加入 Telegram 群组：
+- 查看 [常见问题 FAQ]()
-* * *
+---
- _本文档持续更新中，如有新的疑难杂症欢迎反馈..._
+_本文档持续更新中，如有新的疑难杂症欢迎反馈。_