在 OpenClaw 中接入 Groq LPU 推理服务的完整配置步骤。使用 openclaw onboard --auth-choice groq-api-key 或 export GROQ_API_KEY 完成认证；默认推荐 groq/llama-3.3-70b-versatile 模型；音频转写自动选用 whisper-large-v3-turbo，推理模型支持 /think 级别映射。内置模型目录涵盖 Llama、Gemma、Kimi、Qwen、DeepSeek R1 等二十余种模型，运行 openclaw models list --provider groq 即可查看当前可用条目。

Groq 接入 OpenClaw 配置与模型设置

Groq 使用自研 LPU 硬件，为开源模型（Llama、Gemma、Kimi、Qwen、GPT OSS 等）提供极速推理服务。OpenClaw 内置了 Groq 插件，同时注册了一个 OpenAI 兼容的聊天提供者和一个音频媒体理解提供者。

属性	值
提供商标识	groq
插件类型	内置，默认启用 (enabledByDefault: true)
认证环境变量	GROQ_API_KEY
向导配置标志	--auth-choice groq-api-key
API 类型	OpenAI 兼容 (openai-completions)
基础 URL	https://api.groq.com/openai/v1
音频转写模型	whisper-large-v3-turbo (默认)
推荐默认模型	groq/llama-3.3-70b-versatile

快速接入步骤

1. 获取 API Key
   前往 console.groq.com/keys 创建一个 API Key。

2. 设置 API Key
   可以使用 OpenClaw 向导交互式设置，或通过环境变量直接配置。

   # 使用向导（推荐）
   openclaw onboard --auth-choice groq-api-key

   # 直接设置环境变量
   export GROQ_API_KEY=gsk_...

3. 配置默认模型
   在配置文件中指定智能体默认模型：

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

4. 验证模型目录是否可达

   openclaw models list --provider groq

   输出应显示当前版本 OpenClaw 已知的所有 Groq 模型。

完整配置文件示例

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

内置模型目录

OpenClaw 随版本发布内置的 Groq 模型清单，同时包含推理（reasoning）和非推理模型。运行 openclaw models list --provider groq 可看到当前安装版本的全部条目，或查阅 console.groq.com/docs/models 获取 Groq 官方完整列表。

模型引用	名称	推理型	输入类型	上下文长度
groq/llama-3.3-70b-versatile	Llama 3.3 70B Versatile	否	text	131,072
groq/llama-3.1-8b-instant	Llama 3.1 8B Instant	否	text	131,072
groq/meta-llama/llama-4-maverick-17b-128e-instruct	Llama 4 Maverick 17B	否	text + image	131,072
groq/meta-llama/llama-4-scout-17b-16e-instruct	Llama 4 Scout 17B	否	text + image	131,072
groq/llama3-70b-8192	Llama 3 70B	否	text	8,192
groq/llama3-8b-8192	Llama 3 8B	否	text	8,192
groq/gemma2-9b-it	Gemma 2 9B	否	text	8,192
groq/mistral-saba-24b	Mistral Saba 24B	否	text	32,768
groq/moonshotai/kimi-k2-instruct	Kimi K2 Instruct	否	text	131,072
groq/moonshotai/kimi-k2-instruct-0905	Kimi K2 Instruct 0905	否	text	262,144
groq/openai/gpt-oss-120b	GPT OSS 120B	是	text	131,072
groq/openai/gpt-oss-20b	GPT OSS 20B	是	text	131,072
groq/openai/gpt-oss-safeguard-20b	Safety GPT OSS 20B	是	text	131,072
groq/qwen-qwq-32b	Qwen QwQ 32B	是	text	131,072
groq/qwen/qwen3-32b	Qwen3 32B	是	text	131,072
groq/deepseek-r1-distill-llama-70b	DeepSeek R1 Distill Llama 70B	是	text	131,072
groq/groq/compound	Compound	是	text	131,072
groq/groq/compound-mini	Compound Mini	是	text	131,072

提示：模型目录随 OpenClaw 版本更新而变更。openclaw models list --provider groq 显示的是当前版本内置的条目，可对比 console.groq.com/docs/models 确认新增或废弃的模型。

推理模式映射

OpenClaw 将共享的 /think 级别映射到 Groq 模型对应的 reasoning_effort 参数：

• 对于 qwen/qwen3-32b：关闭思考时发送 none，开启思考时发送 default。
• 对于 Groq GPT OSS 推理模型（openai/gpt-oss-*）：OpenClaw 根据 /think 级别发送 low、medium 或 high。关闭思考时不发送 reasoning_effort，因为这些模型不支持关闭值。
• DeepSeek R1 Distill、Qwen QwQ 和 Compound 使用 Groq 原生的推理接口；/think 控制日志可见性，但模型始终会推理。

详细映射规则和共享 /think 级别定义参见思维模式。

音频转写配置

Groq 内置插件同时注册了一个音频媒体理解提供者，使得语音消息可以通过共享的 tools.media.audio 配置进行转写。

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

将 Groq 设为默认音频后端：

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

环境变量对守护进程的可见性

如果 Gateway 以托管服务运行（launchd、systemd、Docker），GROQ_API_KEY 必须对该进程可见，而非仅对当前交互式 Shell 可见。

WARNING

仅在交互式 Shell 中导出的 Key 无法被 launchd 或 systemd 守护进程使用，除非该环境也被导入。请将 Key 写入 ~/.openclaw/.env 或通过 env.shellEnv 配置，以使其从网关进程可读。

:::

使用自定义 Groq 模型 ID

OpenClaw 支持运行时可接受任何 Groq 模型 ID。使用 Groq 显示的确切 ID 并加上 groq/ 前缀即可。内置模型目录覆盖常见用例，未收录的 ID 会回退到默认的 OpenAI 兼容模板。

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

相关链接

• 模型提供者选择 — 选择提供者、模型引用和故障切换行为。
• 思维模式 — 推理努力级别和提供者策略交互。
• 配置参考 — 包含提供者和音频设置的完整配置 schema。
• Groq 控制台 — 仪表盘、API 文档和定价。

常见问题

为什么我设置了 GROQ_API_KEY 但 openclaw models list --provider groq 报错？

最常见的原因是环境变量未生效。检查：

• 如果 Gateway 以 systemd/launchd 运行，Key 必须写入 ~/.openclaw/.env 或通过 env.shellEnv 配置。
• 确认 Key 值正确（以 gsk_ 开头），且没有多余空格。
• 使用 echo $GROQ_API_KEY 验证当前 Shell 是否能看到该变量。

如何让 OpenClaw 使用 Groq 的 Whisper 转写语音？

在配置文件的 tools.media.audio.models 数组中添加 { provider: "groq" }。具体配置见上文的“音频转写配置”部分。默认使用 whisper-large-v3-turbo，无需额外指定模型。

Groq 的推理模型（如 DeepSeek R1）在 OpenClaw 中怎么配置？

直接使用模型目录中的 ID 作为默认模型即可，例如 groq/deepseek-r1-distill-llama-70b。OpenClaw 会自动映射 /think 级别：这些模型始终进行推理，/think 控制日志可见性。无需额外参数。