# Groq

> Groq 设置（身份验证 + 模型选择 + Whisper 转录）

- 网址：https://funcoding.ai/agents/openclaw/providers/groq/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/providers/groq

---
[Groq](https://groq.com) 使用定制 LPU 硬件，为开放权重模型（Llama、Gemma、Kimi、Qwen、GPT OSS 等）提供超高速推理。Groq 插件同时注册一个兼容 OpenAI 的聊天提供商和一个音频媒体理解提供商。

| 属性                   | 值                                       |
| ---------------------- | ---------------------------------------- |
| 提供商 ID              | `groq`                       |
| 插件                   | 官方外部软件包                           |
| 身份验证环境变量       | `GROQ_API_KEY`                       |
| API                    | 兼容 OpenAI（`openai-completions`）       |
| 基础 URL               | `https://api.groq.com/openai/v1`                       |
| 音频转录               | `whisper-large-v3-turbo`（默认）               |
| 建议的默认聊天模型     | `groq/llama-3.3-70b-versatile`                       |

## 安装插件

安装官方插件，然后重启 Gateway 网关：

```bash
openclaw plugins install @openclaw/groq-provider
openclaw gateway restart
```

## 入门指南

**获取 API key**

在 [console.groq.com/keys](https://console.groq.com/keys) 创建 API key。

**设置 API key**

    ```bash
export GROQ_API_KEY=gsk_...
```

**设置默认模型**

```json5
{
  agents: {
    defaults: {
      model: { primary: "groq/llama-3.3-70b-versatile" },
    },
  },
}
```

**验证目录是否可访问**

```bash
openclaw models list --provider groq
```

### 配置文件示例

```json5
{
  env: { GROQ_API_KEY: "gsk_..." },
  agents: {
    defaults: {
      model: { primary: "groq/llama-3.3-70b-versatile" },
    },
  },
}
```

## 内置目录

OpenClaw 随附一个由清单支持的 Groq 目录，其中包含推理和非推理条目。运行 `openclaw models list --provider groq` 可查看已安装版本的静态条目，或查看 [console.groq.com/docs/models](https://console.groq.com/docs/models) 获取 Groq 的权威列表。

| 模型引用                                         | 名称                    | 推理 | 输入          | 上下文  |
| ------------------------------------------------ | ----------------------- | ---- | ------------- | ------- |
| `groq/llama-3.3-70b-versatile`                               | Llama 3.3 70B Versatile | 否   | 文本          | 131,072 |
| `groq/llama-3.1-8b-instant`                               | Llama 3.1 8B Instant    | 否   | 文本          | 131,072 |
| `groq/meta-llama/llama-4-scout-17b-16e-instruct`                               | Llama 4 Scout 17B       | 否   | 文本 + 图像   | 131,072 |
| `groq/openai/gpt-oss-120b`                               | GPT OSS 120B            | 是   | 文本          | 131,072 |
| `groq/openai/gpt-oss-20b`                               | GPT OSS 20B             | 是   | 文本          | 131,072 |
| `groq/openai/gpt-oss-safeguard-20b`                               | Safety GPT OSS 20B      | 是   | 文本          | 131,072 |
| `groq/qwen/qwen3-32b`                               | Qwen3 32B               | 是   | 文本          | 131,072 |
| `groq/groq/compound`                               | Compound                | 是   | 文本          | 131,072 |
| `groq/groq/compound-mini`                               | Compound Mini           | 是   | 文本          | 131,072 |

<div class="callout callout-tip">

目录会随每个 OpenClaw 版本演进。`openclaw models list --provider groq` 显示已安装版本已知的条目；请与 [console.groq.com/docs/models](https://console.groq.com/docs/models) 交叉核对新添加或已弃用的模型。

</div>

## 推理模型

Groq 推理模型（上表中的 `reasoning: true`）会将 OpenClaw 共享的 `/think` 级别映射为 `reasoning_effort` 的 `low`、`medium` 或 `high` 值。`/think off` 或 `/think none` 会从请求中省略 `reasoning_effort`，而不是发送禁用值。

有关共享的 `/think` 级别以及 OpenClaw 如何按提供商进行转换，请参阅[思考模式](https://funcoding.ai/agents/openclaw/tools/thinking/)。

## 音频转录

Groq 插件还会注册一个**音频媒体理解提供商**，以便通过共享的 `tools.media.audio` 接口转录语音消息。

| 属性             | 值                                        |
| ---------------- | ----------------------------------------- |
| 共享配置路径     | `tools.media.audio`                        |
| 默认基础 URL     | `https://api.groq.com/openai/v1`                        |
| 默认模型         | `whisper-large-v3-turbo`                        |
| 自动优先级       | 20                                        |
| API 端点         | 兼容 OpenAI 的 `/audio/transcriptions`        |

要将 Groq 设为默认音频后端：

```json5
{
  tools: {
    media: {
      audio: {
        models: [{ provider: "groq" }],
      },
    },
  },
}
```

<details>
<summary>守护进程的环境可用性</summary>

如果 Gateway 网关作为托管服务运行（launchd、systemd、Docker），`GROQ_API_KEY` 必须对该进程可见，而不能仅对交互式 shell 可见。

<div class="callout callout-warning">

仅在交互式 shell 中导出的密钥无法帮助 launchd 或 systemd 守护进程，除非该环境也被导入其中。请在 `~/.openclaw/.env` 中或通过 `env.shellEnv` 设置密钥，使 Gateway 网关进程可以读取它。

</div>

</details>

<details>
<summary>自定义 Groq 模型 ID</summary>

OpenClaw 在运行时接受任何 Groq 模型 ID。请使用 Groq 显示的确切 ID，并在前面加上 `groq/`。静态目录涵盖常见情况；未收录的 ID 会回退到默认的 OpenAI 兼容模板。

```json5
{
  agents: {
    defaults: {
      model: { primary: "groq/<your-model-id>" },
    },
  },
}
```

</details>

## 相关内容

- [模型提供商](https://funcoding.ai/agents/openclaw/concepts/model-providers/)：选择提供商、模型引用和故障转移行为。
- [思考模式](https://funcoding.ai/agents/openclaw/tools/thinking/)：推理工作量级别以及与提供商策略的交互。
- [配置参考](https://funcoding.ai/agents/openclaw/gateway/configuration-reference/)：完整的配置架构，包括提供商和音频设置。
- [Groq Console](https://console.groq.com)：Groq 控制面板、API 文档和定价。