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

# QClaw

> QClaw 客户端集成指南

## 一、产品简介

QClaw（昵称「小龙虾 AI」）是腾讯电脑管家基于 OpenClaw 开源生态打造的本地化 AI Agent 助手，主打「**随时随地，微信一下，帮你搞定一切**」——无需编程、无需配置环境，安装后即可用自然语言让电脑自动完成文件整理、报表处理、文档编辑、代码生成等任务。微信 / QQ 扫码绑定后，即使不在电脑旁，也能通过手机远程下达指令；所有任务均在本地电脑执行，数据不出本机。

QClaw 内置 Kimi、GLM、MiniMax、DeepSeek 等国产模型，同时支持在「模型配置」中接入任意 OpenAI 兼容协议的第三方模型服务。通过对接 GravitexAI，您可以获得：

| 能力      | 说明                                                                          |
| ------- | --------------------------------------------------------------------------- |
| 一把密钥全模型 | 无需分别注册各家账号，一个密钥即可在 QClaw 中调用 GPT、Claude、Gemini、DeepSeek、Kimi、MiniMax 等全模型矩阵 |
| 图形化一键接入 | 对话框 → 模型配置 → 自定义大模型，填入接口地址、协议、密钥、模型 ID 即可，无需手动改配置文件                         |
| 数据不出本地  | 任务在本地电脑执行，模型请求由 QClaw 直接发往你配置的 GravitexAI 接口                                |
| 按量自主付费  | 自定义模型产生的费用由您直接向 GravitexAI 结算，与 QClaw 内置模型互不影响                              |

## 二、环境要求

* Windows 或 macOS 桌面系统（具体版本要求以官网下载页为准）
* 稳定的网络连接（用于模型 API 调用与微信远程指令）

## 三、前置条件

* 已在电脑上安装 QClaw（官网 [qclaw.qq.com](https://qclaw.qq.com/) 下载）
* 已在 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 创建 API Key（格式 `sk-xxxxxxxxxx`）

## 四、快速开始

### 第一步：安装 QClaw

访问官网 [qclaw.qq.com](https://qclaw.qq.com/)，下载 Windows 或 macOS 安装包，双击安装即可，无需命令行操作。安装完成后打开 QClaw，按引导用微信扫码登录并绑定，即可远程下达指令。

### 第二步：获取 GravitexAI API Key

1. 访问 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys)
2. 点击「新建令牌」，命名并保存
3. 复制以 `sk-` 开头的密钥备用

### 第三步：打开「自定义大模型」入口

启动 QClaw，在对话框下方依次操作：

1. 选择 **云端模型** 标签
2. 点击右侧的模型选择按钮（显示当前模型名的下拉，如 `Auto`）
3. 在弹出的模型列表底部，点击「**自定义大模型**」

<img src="https://mintcdn.com/gravitexai/lwgeO6PIBps2JkvQ/images/qclaw1.png?fit=max&auto=format&n=lwgeO6PIBps2JkvQ&q=85&s=a4783842c5431d805922a6f3fb693195" alt="QClaw 自定义大模型入口" width="2400" height="1600" data-path="images/qclaw1.png" />

在打开的 **模型 API** 标签页中，点击「自定义配置」。

### 第四步：填写 GravitexAI 接入信息

按下表填写后点击「确定」，等待配置生效：

| 字段           | 填写值                                                                                    | 说明                                                                                     |
| ------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **接口地址**     | OpenAI 兼容协议：`https://api.gravitex.ai/v1`<br />Anthropic 兼容协议：`https://api.gravitex.ai` | OpenAI 协议**必须带 `/v1`**；Anthropic 协议**不带 `/v1`**                                        |
| **API 协议类型** | Claude 系列选 `Anthropic 兼容协议`<br />其余模型选 `OpenAI 兼容协议`                                   | 按下拉选项选择，需与模型类型匹配                                                                       |
| **API Key**  | 如 `sk-...`                                                                             | 粘贴第二步获取的 GravitexAI 令牌                                                                 |
| **模型名称**     | 自定义显示名，如 `GPT-6 Astra`                                                                 | 仅用于界面展示，可随意填写                                                                          |
| **模型 ID**    | 如 `claude-sonnet-5`、`gpt-5.5`、`deepseek-v4-pro`、`gemini-3.6-flash`、`kimi-k3`           | **决定实际调用的模型**，必须与 [GravitexAI 模型广场](https://maas.gravitex.ai/#/api-models) 公布的 ID 完全一致 |
| **可用功能**     | 按模型实际能力勾选「图片输入」「推理模式」                                                                  | 不确定时建议宁可少勾，勾选与模型实际能力不符可能导致调用报错                                                         |

<img src="https://mintcdn.com/gravitexai/lwgeO6PIBps2JkvQ/images/qclaw2.png?fit=max&auto=format&n=lwgeO6PIBps2JkvQ&q=85&s=644fb5aef0fd72b89e6c81c2a91f7ce9" alt="QClaw 添加自定义大模型配置示例" width="2400" height="1600" data-path="images/qclaw2.png" />

<Note>
  每个模型都需要**单独配置**接口地址、API Key 和模型名称并保存。需要配置多个模型时，重复「自定义配置」步骤逐个添加即可。
</Note>

### 第五步：切换到自定义模型使用

返回对话界面，在模型选择中切换到刚配置好的自定义模型（如图所示，对话框右下角的模型下拉中选中 `gpt-5.6-sol`），即可开始对话与任务：

<img src="https://mintcdn.com/gravitexai/lwgeO6PIBps2JkvQ/images/qclaw3.png?fit=max&auto=format&n=lwgeO6PIBps2JkvQ&q=85&s=fb7fbabdf55e9a4c2305d5dee6b15ae1" alt="QClaw 切换自定义模型对话" width="2400" height="1600" data-path="images/qclaw3.png" />

## 五、常用功能速查

| 功能           | 说明                                   |
| ------------ | ------------------------------------ |
| 微信 / QQ 远程指令 | 扫码绑定后，随时随地通过手机发指令，远程让电脑执行任务          |
| 本地任务执行       | 文件整理、报表处理、文档编辑、代码生成等任务均在本地完成         |
| 多模型切换        | 内置国产模型与自定义模型一键切换，按任务类型选用             |
| 龙虾管家安全防护     | 实时监控拦截高风险脚本、文件误删和异常网络访问，并提供安全守护日志    |
| 技能生态         | 5000+ Skill 与「专家广场」，零门槛调用专业 Agent 能力 |
| 连接器          | 支持腾讯文档、腾讯会议、金山文档、Notion、邮箱等跨应用直连     |

## 六、常见问题

<AccordionGroup>
  <Accordion title="接口地址应该填什么？">
    取决于所选协议：OpenAI 兼容协议填 `https://api.gravitex.ai/v1`（**必须带 `/v1`**）；Anthropic 兼容协议填 `https://api.gravitex.ai`（**不带 `/v1`**）。如果配置界面要求填写完整接口路径，请按其提示补充，如 OpenAI 协议补充为 `https://api.gravitex.ai/v1/chat/completions`。
  </Accordion>

  <Accordion title="Claude 系列模型应该怎么配置？">
    Claude 系列模型（如 `claude-sonnet-5`）的「API 协议类型」选择 `Anthropic 兼容协议`，接口地址填 `https://api.gravitex.ai`（**不带 `/v1`**）。GPT、DeepSeek、Gemini、Kimi 等其余模型统一使用 `OpenAI 兼容协议` + `https://api.gravitex.ai/v1`。
  </Accordion>

  <Accordion title="提示 401 / 认证失败怎么排查？">
    1. 确认 API Key 以 `sk-` 开头且复制完整、没有多余空格
    2. 确认接口地址拼写正确（`https://api.gravitex.ai/v1`）
    3. 在 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 检查令牌是否启用、账户余额是否充足（余额不足也会返回 401）
    4. 必要时禁用旧密钥并重新创建
  </Accordion>

  <Accordion title="报 `Invalid 'max_output_tokens': integer below minimum value` 怎么办？">
    完整报错类似 `Invalid 'max_output_tokens': integer below minimum value. Expected a value >= 16, but got 1 instead.`。这是请求的「最大输出 tokens」被设置成了过小的值（如 1），上游接口要求最小为 16。解决方法：检查该自定义模型的配置中是否有「最大输出」相关设置，将其留空（使用默认值）或改为合理数值（如 `8192`），保存后重试；如果界面中没有该选项，删除该模型后重新添加，配置过程中不要填写过小的数值。
  </Accordion>

  <Accordion title="提示模型不存在怎么办？">
    确认「模型 ID」一栏与 [GravitexAI 模型广场](https://maas.gravitex.ai/#/api-models) 公布的模型 ID 完全一致，注意大小写与拼写。建议直接从模型广场复制，避免手打出错。「模型名称」只是显示名，不影响调用。
  </Accordion>

  <Accordion title="想配置多个模型怎么做？">
    QClaw 要求每个模型单独配置并保存。在「模型 API」标签页重复「自定义配置」步骤，为每个模型分别填写接口地址、API Key 和模型名称即可，接口地址和 API Key 可以复用。
  </Accordion>

  <Accordion title="通过 GravitexAI 调用模型的费用怎么计算？会影响 QClaw 内置模型吗？">
    自定义模型产生的全部费用（Token 消耗等）由您直接向 GravitexAI 结算，与 QClaw 内置模型的免费/套餐策略互不影响。请自行关注 GravitexAI 账户的余额与用量，避免产生超出预期的支出。
  </Accordion>

  <Accordion title="我的 API Key 和任务数据会被上传吗？">
    不会。QClaw 是本地化 AI Agent，任务在你自己的电脑上执行，数据不出本机；接入 GravitexAI 后，QClaw 仅作为通信链路将请求直接发往你配置的接口地址，输出由模型直接返回。
  </Accordion>
</AccordionGroup>

## 七、相关资源

* QClaw 官网：[qclaw.qq.com](https://qclaw.qq.com/)
* 密钥管理：[https://maas.gravitex.ai/#/api-keys](https://maas.gravitex.ai/#/api-keys)
* 模型广场：[https://maas.gravitex.ai/#/api-models](https://maas.gravitex.ai/#/api-models)