// Troubleshooting

接入问题指引

接入和解除常见问题的处理办法。

// 01

一键接入的原理

「一键接入」只做一件事：在您的客户端配置文件里，把请求地址指向本机转发，并填入占位令牌。 真正的 API Key 不会写入客户端配置。

写入客户端的内容

以下清单均以这四个特征辨认。若在配置中看到其中任意一项，即为 Skyline Connector 写入。

看到什么长什么样
本机转发地址http://127.0.0.1:<端口>…
占位令牌PROXY_MANAGED
provider 名称skyline-intelligence
生成的目录文件skyline-connector-model-catalog.json

另外两个常见问题

为什么客户端里填的是 PROXY_MANAGED，而不是真实 Key？

真实 Key 只在本地转发请求时替换，因此更换或删除 Key 都无需再修改客户端配置。

地址里的端口会变吗？

会。首选端口被其他程序占用时会顺延。请以应用状态栏显示的端口为准；端口变化后，客户端中的地址也需相应修改。

// 02

接入失败处理

应用内只显示一句提示，此处展开说明。失败码同样会记录在日志中。

read-failed无法读取配置文件

应用无法打开待修改的配置文件。通常是因为格式有误，例如 JSON 缺少逗号、引号未成对，或 TOML 缺少引号； 也可能是该文件没有读取权限，或正被其他程序占用。

  1. 用编辑器打开提示中的文件，VS Code 等编辑器会直接标出语法错误；
  2. 若无法定位错误，可在同一目录查找 <文件名>.bak.<13位时间戳>， 那是修改前的备份，可直接覆盖还原；
  3. 以上方法都不适用时，请按「解除失败处理」中的清理清单删除 Skyline Connector 写入的内容，清理后该配置即等同从未接入，可重新接入。
shape-invalid配置文件格式不正确

文件可以打开，但无法解析，同样属于语法问题。

  1. 逐项检查括号、引号与逗号；
  2. 若仍无法解决，请参照 read-failed 的第 2、3 步：用 .bak 覆盖还原，或删除 Skyline Connector 写入的内容。
write-failed无法写入配置文件

写入过程中断，通常是该客户端正在运行并锁定了此文件。

  1. 退出该客户端（如 Claude Code、Codex、OpenClaw）后重试；
  2. 检查权限：执行 ls -l 该文件，确认您具备写入权限，且文件不在只读磁盘上；
  3. macOS 上还需确认文件未被锁定，选中文件按 ⌘I 即可查看「已锁定」状态。
verify-failed写入后校验未通过

写入后复核时，发现有几处不应改动的内容被修改。可能是您此前手动编辑过该文件，或由其他工具改动。

  1. 查看提示中给出的文件名；
  2. 对照「解除失败处理」的清理清单，逐一核对文件中 Skyline Connector 应当写入的位置，多余的改动请先还原；
  3. 也可以删除 Skyline Connector 写入的内容，然后重新接入。
adapter-rejected该客户端缺少前提条件

最常见的情况是该客户端从未运行过，其配置目录和文件尚未生成。 Skyline Connector 不会代您创建客户端配置文件。

  1. 请先启动一次该客户端，使其生成配置文件，再返回接入；
  2. 对照提示中给出的文件路径，确认文件已存在；
  3. 若您曾更改配置目录，请在「设置」中将该客户端的配置目录修正。
no-api-key尚无可用 API Key
  1. 前往「本机 Key」页，粘贴一把在控制台创建的 Key，点击「保存并使用」；
  2. 返回后重新接入。

// 03

解除失败处理

正常情况下，解除会撤销 Skyline Connector 写入的每一处，并还原您原有的值。 但若当时该文件无法读取或写入，这几处将无法撤销。此时应用会逐条列出， 提示如下：「这几处没能撤掉，请你手动清理」。

有两种处理方式，任选其一：

  1. 按下表手动删除。每端只删除「写入位置」一列中的内容，其余键请勿改动；
  2. 或重新接入一次，再解除一次。接入会重写同样的位置，之后解除即可彻底清除。
此时状态已是「未接入」，不会再受文件影响，因此无需为了「让状态变正确」反复点击解除。

逐客户端清理清单

操作前请先备份文件。删除前请用「一键接入的原理」中的四个特征确认，该项确为 Skyline Connector 写入。

Claude Code · ~/.claude/settings.json

在 env 里面，删掉这几项：

  • ANTHROPIC_BASE_URL，值是 http://127.0.0.1:… 这样的本地地址；
  • ANTHROPIC_AUTH_TOKEN，值是 PROXY_MANAGED；
  • 三个角色各一对：ANTHROPIC_DEFAULT_SONNET_MODEL 和 …_MODEL_NAME， HAIKU 和 OPUS 同理，值为 Skyline Connector 写入的模型 id 和显示名。

请勿修改 ANTHROPIC_API_KEY 和顶层 model：这两项由您自行维护，Skyline Connector 不会写入。

Codex · ~/.codex/config.toml 和那份目录文件
  • 删除 model_provider = "skyline-intelligence" 这一行；
  • 删除整个 [model_providers.skyline-intelligence] 段，其中包含 name、 base_url、wire_api、experimental_bearer_token；
  • 删除 model_catalog_json，但仅当其指向 skyline-connector-model-catalog.json 时删除；若指向您自己的目录文件，请勿改动；
  • model 若已被改为 Skyline Connector 的模型，请按您的需要改回或删除；
  • 最后删除该目录文件本身：~/.codex/skyline-connector-model-catalog.json。

请勿改动 mcp_servers、auth.json，以及您自行配置的 provider。

OpenCode · ~/.config/opencode/opencode.json
  • 删除 provider.skyline-intelligence 整条，其中包含 npm、 name: "skyline-intelligence"、options.baseURL、 options.apiKey: "PROXY_MANAGED"，以及 models；
  • 其他 provider 及顶层键（如 model、theme）请勿改动。

OpenClaw · ~/.openclaw/openclaw.json
  • 删除 models.providers.skyline-intelligence 整条，其中包含 baseUrl、 apiKey: "PROXY_MANAGED"、api 和 models；
  • 删除 agents.defaults.models 中所有以 "skyline-intelligence/" 开头的键， 它们的值均为空的 {}；
  • 删除 agents.defaults.modelPolicy.allow 数组中以该前缀开头的字符串；
  • agents.defaults.model 若指向 Skyline Connector 的条目，请按您的需要修改。
只删除带 skyline-intelligence/ 前缀的条目。agents.defaults.models 中还包含您自己的模型（如 xiaomi/…），误删会导致客户端模型缺失。

DeepSeek Harness（dsh）· ~/.dsh/settings.yaml 和 .credentials.yaml
  • 删除 llm-pi-ai.providers.skyline-intelligence 整条，其中包含 displayName、 api、baseURL、headers.Authorization: "Bearer PROXY_MANAGED"、models；
  • 同级条目（如 xiaomi-token-plan-cn）及 agent-default-model 请勿改动；
  • 早期版本曾向凭据库写入内容。打开 ~/.dsh/.credentials.yaml，检查两处：
    • 旧格式位于顶层，键名为 SKYLINE_API_KEY；
    • 新格式位于 refs.SKYLINE_API_KEY。
    仅当值恰好等于 PROXY_MANAGED 时才删除。若值为您自己的 Key，则该条属于您，请勿改动。 文件不存在则无需处理。
dsh 凭据库遇到无法识别的顶层键会整份拒收，写坏后 dsh 将无法启动，因此此处只删不加。

Claude Desktop · ~/Library/Application Support/Claude* 一带的四份文件
  • Claude/claude_desktop_config.json：删除 deploymentMode（值为 "3p"，由 Skyline Connector 写入）。若这是您自行设置的，请按需保留；
  • Claude-3p/claude_desktop_config.json：同上；
  • Claude-3p/configLibrary/00000000-0000-4000-8000-000000157210.json： 整份删除。该文件由 Skyline Connector 创建，文件名即其固定 ID；
  • Claude-3p/configLibrary/_meta.json：删除 entries 中指向上述文件的条目， 以及 appliedId（若其指向 Skyline Connector）。

Windows 上这些文件位于 %APPDATA%\Claude 和 %APPDATA%\Claude-3p。

// 04

运行态自检

接入或解除后，打开对应的客户端配置文件，按以下两条核对即可确认结果。

接入正确的表现

  • 配置文件中的请求地址已改为本机转发地址，即 http://127.0.0.1:<端口>…；
  • 令牌为占位符 PROXY_MANAGED，而非真实 Key；
  • 可看到所使用的 provider 名称（skyline-intelligence 等）；
  • 应用状态栏显示「已接入」，且其端口与文件中的地址一致。

解除干净的表现

  • 以上四个特征全部不存在；
  • 您原有的配置（如 ANTHROPIC_API_KEY、顶层 model）保持原样；
  • 应用状态栏显示「未接入」。
应用仅依据文件中可见的内容判断状态：文件里找不到 Skyline Connector 写入的位置，就不会显示「已接入」。 因此判断接入是否正确，应以文件中的实际内容为准，不要只看状态栏。

// 05

其他

跨阶段的失败码

以下失败码在接入、解除时均可能出现，不专属于某一操作。

state-conflict当前状态不支持该操作

操作与当前状态不匹配，例如尚未接入却点击了「解除接入」，或上一个操作尚未完成。

  1. 刷新页面，或切换到其他页面后返回，再重试；
  2. 若仍无效，请重启应用；启动时会自动完成未结束的操作。
store-failed本地数据库读写失败

此问题出在应用自身的状态库，与您的客户端配置无关。

  1. 重启应用；
  2. 若反复出现，请将日志反馈给我们： ~/.skyline-connector/logs/skyline-connector.log， Windows 上是 %USERPROFILE%\.skyline-connector\logs\。
internal操作未能完成（其他少见错误码同理）
  1. 请先重试一次，多数瞬时问题可借此解决；
  2. 若仍失败，请重启应用，并将日志反馈给我们，路径见上文 store-failed。

从备份文件恢复

每次修改您的配置文件前，Skyline Connector 都会在同一目录保留一份备份，命名为 <文件名>.bak.<13位时间戳>，例如：

~/.claude/settings.json.bak.1789544781484

  1. 按时间戳选取最近的一份，或选取一份您确定「尚未接入」的；
  2. 先另存一份留底，再覆盖回原文件；
  3. 返回应用重试解除或接入。

形如 .bak.20260911_163652 的备份来自更早的版本或其他工具，并非当前版本命名，使用前请先确认。

其他疑问

转发未运行会怎样？

所有经它接入的客户端都将无法连接，因为它们平时通过本地转发请求。 请先查看应用左下角的状态条，如有需要点击「重启转发」。

解除接入会改动我自己配置的内容吗？

不会。解除只撤销 Skyline Connector 写入、且您未修改过的位置。操作前会将「文件当前的值」与「最后写入的值」逐一比对， 不一致的将跳过，并如实告知。提示中的「你手动改过的 N 处已保留」即指此类情况。

日志在哪里？

macOS 和 Linux：~/.skyline-connector/logs/skyline-connector.log； Windows：%USERPROFILE%\.skyline-connector\logs\。 也可在设置页的「日志与诊断」中直接打开；将级别调至 Debug 可查看更详细的过程。

问题仍未解决？ 请将日志反馈给我们。日志可在应用的「日志与诊断」中直接打开，文件路径见 05「日志在哪」。 安装、接入与选模型的步骤见《使用说明》。