> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jiji.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code 常见问题

> 使用吉吉API 配置 Claude Code 时的常见问题。

排查前建议先运行 `claude doctor`，它会检查安装状态和配置文件格式，并给出修复建议。

## 安装与更新

<AccordionGroup>
  <Accordion title="安装后提示命令未找到">
    安装完成后需要**打开一个新的终端窗口**再运行 `claude`。

    仍然找不到命令，说明安装目录没有加入 PATH。官方安装脚本会把 `claude` 安装到：

    * **macOS/Linux**：`~/.local/bin`
    * **Windows**：`%USERPROFILE%\.local\bin`

    **macOS/Linux**（使用 bash 时把 `~/.zshrc` 换成 `~/.bashrc`）：

    ```bash theme={null}
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
    source ~/.zshrc
    ```

    **Windows**：在「系统属性 → 环境变量」中，把 `%USERPROFILE%\.local\bin` 添加到用户变量 `Path`，然后重新打开终端。
  </Accordion>

  <Accordion title="安装命令报错">
    * **PowerShell 提示 `The token '&&' is not a valid statement separator`**：你在 PowerShell 中运行了 CMD 命令，改用 `irm https://claude.ai/install.ps1 | iex`
    * **CMD 提示 `'irm' is not recognized`**：你在 CMD 中运行了 PowerShell 命令，改用 CMD 安装命令
    * **`curl` 报错、返回 `403` 或 `syntax error near unexpected token '<'`**：通常是网络无法访问 `claude.ai`，请检查网络，或改用 Homebrew、WinGet 安装
  </Accordion>

  <Accordion title="如何更新 Claude Code">
    配置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 后自动更新会关闭，需要手动更新：

    ```bash theme={null}
    claude update
    ```

    Homebrew 安装的运行 `brew upgrade claude-code`，WinGet 安装的运行 `winget upgrade Anthropic.ClaudeCode`。
  </Accordion>

  <Accordion title="Windows 需要安装 Git 吗">
    不是必须的。未安装 Git for Windows 时，Claude Code 使用 PowerShell 执行命令；安装 [Git for Windows](https://git-scm.com/downloads/win) 后改用 Git Bash，兼容性更好。

    已安装 Git 但 Claude Code 找不到 Git Bash 时，在 `settings.json` 的 `env` 中指定路径：

    ```json theme={null}
    {
      "env": {
        "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## 配置问题

<AccordionGroup>
  <Accordion title="配置文件在哪里">
    * **macOS/Linux**：`~/.claude/settings.json`
    * **Windows**：`C:\Users\你的用户名\.claude\settings.json`

    该文件对所有项目生效。
  </Accordion>

  <Accordion title="请求地址要不要加 /v1">
    不要。Claude Code 使用 Anthropic 格式，会自动补全 `/v1/messages`，请求地址填：

    ```text theme={null}
    https://www.jiji.cc
    ```
  </Accordion>

  <Accordion title="如何确认配置已生效">
    启动 `claude` 后输入 `/status`：

    * `Anthropic base URL` 显示 `https://www.jiji.cc`：请求地址已生效。没有这一行说明没有读取到请求地址
    * `Auth token` 显示 `ANTHROPIC_AUTH_TOKEN`：API Key 已生效。如果显示的是 `Login method` 和 claude.ai 账号，说明没有读取到 API Key

    <Note>
      `settings.json` 中的配置优先级高于终端里 `export` 的同名环境变量，以 `/status` 显示为准。
    </Note>
  </Accordion>

  <Accordion title="API 连接失败">
    先在终端中直接测试请求地址和 API Key，把 `your-api-key-here` 换成你的 Key：

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      curl -sS -w '\n%{http_code}\n' -X POST "https://www.jiji.cc/v1/messages" \
        -H "Authorization: Bearer your-api-key-here" \
        -H "anthropic-version: 2023-06-01" \
        -H "content-type: application/json" \
        -d '{"model": "claude-opus-5-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
      ```

      ```powershell Windows theme={null}
      Invoke-RestMethod -Method Post -Uri "https://www.jiji.cc/v1/messages" `
        -Headers @{ "Authorization" = "Bearer your-api-key-here"; "anthropic-version" = "2023-06-01" } `
        -ContentType "application/json" `
        -Body '{"model": "claude-opus-5-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
      ```
    </CodeGroup>

    * 返回以 `{"id":"msg_` 开头的 JSON，或提示模型不存在：网络和 Key 都正常，请检查 `settings.json`
    * 返回 `401`：API Key 无效，参考下方「API Key 无效」
    * 连接超时或无法解析域名：检查网络，关闭代理后重试
  </Accordion>

  <Accordion title="启动时提示 Auth conflict 或 auth may not work as expected">
    你之前登录过 claude.ai 账号，同时又配置了 API Key。在 Claude Code 中运行 `/logout` 退出 claude.ai 账号，只保留 API Key 即可。
  </Accordion>
</AccordionGroup>

## 使用问题

<AccordionGroup>
  <Accordion title="已配置 API Key 仍要求登录">
    确认 `ANTHROPIC_AUTH_TOKEN` 写在用户目录的 `~/.claude/settings.json` 中，而不是项目目录下的 `.claude/settings.json`。项目级配置要在首次引导和信任目录确认之后才会生效。
  </Accordion>

  <Accordion title="提示无法连接到 Anthropic 服务">
    出现 `Unable to connect to Anthropic services` 或 `Failed to connect to api.anthropic.com` 时，在 `~/.claude.json` 中写入 `"hasCompletedOnboarding": true`，跳过首次登录引导。

    <Warning>
      该字段写在用户目录下的 `~/.claude.json`，不是 `~/.claude/settings.json`。不要覆盖 `settings.json`，否则 API Key 配置会丢失。
    </Warning>

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      node -e 'const fs=require("fs"),f=require("os").homedir()+"/.claude.json";const j=fs.existsSync(f)?JSON.parse(fs.readFileSync(f,"utf8")):{};j.hasCompletedOnboarding=true;fs.writeFileSync(f,JSON.stringify(j,null,2))'
      ```

      ```powershell Windows theme={null}
      $f="$env:USERPROFILE\.claude.json"
      $j=if (Test-Path $f) { Get-Content $f -Raw | ConvertFrom-Json } else { [pscustomobject]@{} }
      $j | Add-Member -NotePropertyName 'hasCompletedOnboarding' -NotePropertyValue $true -Force
      $j | ConvertTo-Json -Depth 100 | Set-Content $f -Encoding UTF8
      ```
    </CodeGroup>

    未安装 Node.js 时，也可以用文本编辑器打开 `~/.claude.json`，在最外层花括号内手动添加该字段。完成后重新运行 `claude`。
  </Accordion>

  <Accordion title="VS Code 扩展一直要求登录">
    VS Code 扩展的登录检查不读取 `~/.claude/settings.json`，需要在 VS Code 用户设置中单独配置，参考 [在 VS Code 中使用](/claude-code/introduction#在-vs-code-中使用)。
  </Accordion>

  <Accordion title="如何切换模型">
    * **会话中切换**：输入 `/model`，从列表中选择
    * **启动时指定**：`claude --model claude-opus-5-5`
    * **设置默认模型**：在 `settings.json` 的 `env` 中加入 `"ANTHROPIC_MODEL": "claude-opus-5-5"`

    可用的模型 ID 以 [模型广场](https://www.jiji.cc/extension/models) 为准。
  </Accordion>

  <Accordion title="部分功能不可用">
    使用 API Key 时，以下依赖 claude.ai 账号的功能不可用，属于正常现象：

    * Remote Control（远程控制）
    * 语音输入
    * Claude Code 网页版、Slack 集成等云端功能
  </Accordion>

  <Accordion title="常用命令">
    | 命令 | 说明 |
    | - | - |
    | `claude` | 启动交互式会话 |
    | `claude -p "问题"` | 一次性问答 |
    | `claude -c` | 继续最近的会话 |
    | `claude doctor` | 检查安装和配置 |
    | `claude update` | 更新到最新版本 |
    | `/status` | 查看当前请求地址和凭证 |
    | `/model` | 切换模型 |
    | `/logout` | 退出 claude.ai 账号 |
  </Accordion>
</AccordionGroup>

## 错误排查

<AccordionGroup>
  <Accordion title="API Key 无效">
    * 确认 API Key 已完整复制，没有多余空格
    * 确认使用的是 `ANTHROPIC_AUTH_TOKEN`，不是 `ANTHROPIC_API_KEY`
    * 确认 Key 所在分组包含 Claude 模型，账户余额充足
    * 确认请求地址是 `https://www.jiji.cc`（不带 `/v1`）
  </Accordion>

  <Accordion title="SSL 证书错误">
    出现 `SSL certificate verification failed` 或 `Self-signed certificate detected`，通常是公司网络或代理软件拦截了 HTTPS 连接。关闭代理后重试，或联系网络管理员。
  </Accordion>
</AccordionGroup>

## 仍未解决？

<Card title="提交工单" icon="headset" href="https://www.jiji.cc/extension/tickets">
  以上方法都无法解决时，请提交工单联系我们
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.