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

# 在 Claude Code 中使用 LithosAI

> 通过 LiteLLM 的 Anthropic Messages 兼容代理，把 Claude Code 接入 LithosAI。

## 开始之前

在 [API Key](https://console.lithosai.cloud/keys?lang=zh) 页面创建 key，在 [模型](https://console.lithosai.cloud/models?lang=zh) 页面确认模型 ID，然后在启动 Claude Code 或其本地代理的 shell 中把这个 key 设为环境变量。

```bash theme={null}
export LITHOSAI_API_KEY="your-key"
```

Claude Code 使用的是 Anthropic Messages API，所以它的代理配置和 Codex 用的不一样。如果要同时使用这两个 Agent，把这个代理跑在另一个端口上。

<Warning>
  这是社区提供的、用于接入非 Claude 模型的兼容方案，不是 Anthropic 官方支持的配置。LiteLLM 会把常见的 Messages API 行为映射到 Chat Completions，但原生 thinking block、提示词缓存、token 计数、流式输出细节以及部分工具调用流程的表现可能不同。
</Warning>

<Steps>
  <Step title="安装 LiteLLM">
    [LiteLLM](https://docs.litellm.ai) 负责在 Anthropic Messages API 和 Chat Completions 之间做转换。

    ```bash theme={null}
    pip install 'litellm[proxy]'
    ```

    <Warning>
      请安装最新版本。2026 年 3 月，PyPI 上的 LiteLLM 1.82.7 和 1.82.8 曾被短暂替换成[窃取凭据的恶意版本](https://docs.litellm.ai/blog/security-update-march-2026)。
    </Warning>
  </Step>

  <Step title="配置代理">
    下面的模型条目只是示例，不是 LithosAI 的完整模型列表。要用其他模型或档位，复制一个条目，把 `hosted_vllm/` 后面的 ID 换成 [模型](https://console.lithosai.cloud/models?lang=zh) 页面上的 ID。后面 Claude Code 的环境变量里要使用对应的 `model_name` 别名。

    每个模型都要加 `hosted_vllm/` 前缀。它负责把 `/v1/messages` 请求转换成发往 LithosAI 的 Chat Completions 请求。

    <Accordion title="LiteLLM 代理配置">
      ```yaml claude-code.litellm.yaml theme={null}
      model_list:
        - model_name: kimi-k3-fast
          litellm_params:
            model: hosted_vllm/moonshotai/Kimi-K3-fast
            api_base: https://api.lithosai.cloud/v1
            api_key: os.environ/LITHOSAI_API_KEY
        - model_name: kimi-k3-ultra
          litellm_params:
            model: hosted_vllm/moonshotai/Kimi-K3-ultra
            api_base: https://api.lithosai.cloud/v1
            api_key: os.environ/LITHOSAI_API_KEY

      litellm_settings:
        drop_params: true

      general_settings:
        master_key: sk-claude-proxy
      ```
    </Accordion>

    <Warning>
      不要在这里沿用 Codex 的配置。带 `use_chat_completions_api` 的 `openai/` 条目在处理 `/v1/messages` 时会返回 `200 OK` 和空内容，Claude Code 看起来就像卡住了，而不会报错。
    </Warning>
  </Step>

  <Step title="启动代理">
    ```bash theme={null}
    litellm --config claude-code.litellm.yaml --host 127.0.0.1 --port 4001
    ```

    保持它运行，并确认代理已经启动。代理里保存着你的 LithosAI key，所以只绑定到 `127.0.0.1`，不要暴露到网络上。

    ```bash theme={null}
    curl http://127.0.0.1:4001/health/liveliness
    ```
  </Step>

  <Step title="让 Claude Code 连接代理">
    ```bash theme={null}
    export ANTHROPIC_BASE_URL="http://127.0.0.1:4001"
    export ANTHROPIC_AUTH_TOKEN="sk-claude-proxy"
    export ANTHROPIC_MODEL="kimi-k3-fast"
    export ANTHROPIC_DEFAULT_HAIKU_MODEL="kimi-k3-fast"
    claude
    ```

    `ANTHROPIC_DEFAULT_HAIKU_MODEL` 用于会话标题生成等后台任务。不设置的话，这些请求会发往代理没有提供的模型，从而失败。

    <Warning>
      设置 `ANTHROPIC_AUTH_TOKEN` 后，当前 shell 中的 Claude.ai 登录会被覆盖。建议在单独的 shell 或 profile 里设置这些环境变量，这样其他地方仍然可以使用你现有的订阅。
    </Warning>
  </Step>
</Steps>

Claude Code 识别不了 LithosAI 的模型名，会默认按 200k token 的上下文窗口处理，因而过早压缩上下文。设置实际的上下文窗口可以避免这个问题。

```bash theme={null}
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=262144
```

<Note>
  各模型的上下文窗口见控制台的 [模型](https://console.lithosai.cloud/models?lang=zh) 页面。
</Note>

## 问题排查

| 现象 | 原因 |
| - | - |
| 回复为空，或会话看起来卡住 | 模型条目用了带 `use_chat_completions_api` 的 `openai/`。Claude Code 需要用 `hosted_vllm/`。 |
| 对话正常，但后台请求失败 | 没有设置 `ANTHROPIC_DEFAULT_HAIKU_MODEL`，或者它指向的模型代理没有提供。 |
| 返回 `400` 和 `No connected db.` | `ANTHROPIC_AUTH_TOKEN` 与代理的 `master_key` 不一致。LiteLLM 报告的是查询失败，而不是认证错误。 |

所有 Agent 共有的问题见[常见问题](/zh/agent-integrations#常见问题)。


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