Skip to content

Commit 58c7064

Browse files
vincentkocvincentkoc
committed
docs(providers): rewrite Cerebras, Groq, and SGLang with code-verified setup
Cerebras (docs/providers/cerebras.md): rewrote against extensions/cerebras/openclaw.plugin.json. Added a complete properties summary, CodeGroup for onboarding/direct-flag/env, a Reasoning column on the four-model catalog table (Z.ai GLM 4.7 and GPT OSS 120B are reasoning-capable; Qwen 3 235B and Llama 3.1 8B are not), and a CardGroup of related links. Groq (docs/providers/groq.md): expanded the catalog from 4 hand-picked entries to all 18 bundled models from extensions/groq/openclaw.plugin.json with model refs, reasoning flags, input modalities, and context windows. Removed a stale 'Mixtral 8x7B' row that does not exist in the bundled catalog. Surfaced the audio media-understanding contract (whisper-large-v3-turbo, auto priority 20) as a properties table and explained the per-model reasoning_effort mapping for qwen/qwen3-32b vs the GPT OSS reasoning models. Added an onboarding CodeGroup so the API-key step does not skip 'openclaw onboard --auth-choice groq-api-key'. SGLang (docs/providers/sglang.md): added a properties summary table at the top, including the Qwen/Qwen3-8B model placeholder from extensions/sglang/defaults.ts, the supportsStreamingUsage runtime flag, and the modelPricing.external: false setting. Clarified that the onboarding choice id is bare 'sglang' (custom method) rather than the '-api-key' suffix used by other providers, matching the manifest.
1 parent 093b2b9 commit 58c7064

3 files changed

Lines changed: 172 additions & 92 deletions

File tree

‎docs/providers/cerebras.md‎

Lines changed: 64 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -6,34 +6,56 @@ read_when:
66
- You need the Cerebras API key env var or CLI auth choice
77
---
88

9-
[Cerebras](https://www.cerebras.ai) provides high-speed OpenAI-compatible inference.
9+
[Cerebras](https://www.cerebras.ai) provides high-speed OpenAI-compatible inference on custom inference hardware. OpenClaw includes a bundled Cerebras provider plugin with a static four-model catalog.
1010

11-
| Property | Value |
12-
| -------- | ---------------------------- |
13-
| Provider | `cerebras` |
14-
| Auth | `CEREBRAS_API_KEY` |
15-
| API | OpenAI-compatible |
16-
| Base URL | `https://api.cerebras.ai/v1` |
11+
| Property | Value |
12+
| --------------- | ---------------------------------------- |
13+
| Provider id | `cerebras` |
14+
| Plugin | bundled, `enabledByDefault: true` |
15+
| Auth env var | `CEREBRAS_API_KEY` |
16+
| Onboarding flag | `--auth-choice cerebras-api-key` |
17+
| Direct CLI flag | `--cerebras-api-key <key>` |
18+
| API | OpenAI-compatible (`openai-completions`) |
19+
| Base URL | `https://api.cerebras.ai/v1` |
20+
| Default model | `cerebras/zai-glm-4.7` |
1721

18-
## Getting Started
22+
## Getting started
1923

2024
<Steps>
2125
<Step title="Get an API key">
2226
Create an API key in the [Cerebras Cloud Console](https://cloud.cerebras.ai).
2327
</Step>
2428
<Step title="Run onboarding">
25-
```bash
26-
openclaw onboard --auth-choice cerebras-api-key
27-
```
29+
<CodeGroup>
30+
31+
```bash Onboarding
32+
openclaw onboard --auth-choice cerebras-api-key
33+
```
34+
35+
```bash Direct flag
36+
openclaw onboard --non-interactive \
37+
--auth-choice cerebras-api-key \
38+
--cerebras-api-key "$CEREBRAS_API_KEY"
39+
```
40+
41+
```bash Env only
42+
export CEREBRAS_API_KEY=csk-...
43+
```
44+
45+
</CodeGroup>
46+
2847
</Step>
2948
<Step title="Verify models are available">
3049
```bash
3150
openclaw models list --provider cerebras
3251
```
52+
53+
The list should include all four bundled models. If `CEREBRAS_API_KEY` is unresolved, `openclaw models status --json` reports the missing credential under `auth.unusableProfiles`.
54+
3355
</Step>
3456
</Steps>
3557

36-
### Non-Interactive Setup
58+
## Non-interactive setup
3759

3860
```bash
3961
openclaw onboard --non-interactive \
@@ -42,29 +64,28 @@ openclaw onboard --non-interactive \
4264
--cerebras-api-key "$CEREBRAS_API_KEY"
4365
```
4466

45-
## Built-In Catalog
67+
## Built-in catalog
4668

47-
OpenClaw ships a static Cerebras catalog for the public OpenAI-compatible endpoint:
69+
OpenClaw ships a static Cerebras catalog that mirrors the public OpenAI-compatible endpoint. All four models share a 128k context and 8,192 max-output tokens.
4870

49-
| Model ref | Name | Notes |
50-
| ----------------------------------------- | -------------------- | -------------------------------------- |
51-
| `cerebras/zai-glm-4.7` | Z.ai GLM 4.7 | Default model; preview reasoning model |
52-
| `cerebras/gpt-oss-120b` | GPT OSS 120B | Production reasoning model |
53-
| `cerebras/qwen-3-235b-a22b-instruct-2507` | Qwen 3 235B Instruct | Preview non-reasoning model |
54-
| `cerebras/llama3.1-8b` | Llama 3.1 8B | Production speed-focused model |
71+
| Model ref | Name | Reasoning | Notes |
72+
| ----------------------------------------- | -------------------- | --------- | -------------------------------------- |
73+
| `cerebras/zai-glm-4.7` | Z.ai GLM 4.7 | yes | Default model; preview reasoning model |
74+
| `cerebras/gpt-oss-120b` | GPT OSS 120B | yes | Production reasoning model |
75+
| `cerebras/qwen-3-235b-a22b-instruct-2507` | Qwen 3 235B Instruct | no | Preview non-reasoning model |
76+
| `cerebras/llama3.1-8b` | Llama 3.1 8B | no | Production speed-focused model |
5577

5678
<Warning>
57-
Cerebras marks `zai-glm-4.7` and `qwen-3-235b-a22b-instruct-2507` as preview models, and `llama3.1-8b` / `qwen-3-235b-a22b-instruct-2507` are documented for deprecation on May 27, 2026. Check Cerebras' supported-models page before relying on them for production.
79+
Cerebras marks `zai-glm-4.7` and `qwen-3-235b-a22b-instruct-2507` as preview models, and `llama3.1-8b` plus `qwen-3-235b-a22b-instruct-2507` are documented for deprecation on May 27, 2026. Check Cerebras' supported-models page before relying on them for production workloads.
5880
</Warning>
5981

60-
## Manual Config
82+
## Manual config
6183

62-
The bundled plugin usually means you only need the API key. Use explicit
63-
`models.providers.cerebras` config when you want to override model metadata:
84+
The bundled plugin usually means you only need the API key. Use explicit `models.providers.cerebras` config when you want to override model metadata or run in `mode: "merge"` against the static catalog:
6485

6586
```json5
6687
{
67-
env: { CEREBRAS_API_KEY: "sk-..." },
88+
env: { CEREBRAS_API_KEY: "csk-..." },
6889
agents: {
6990
defaults: {
7091
model: { primary: "cerebras/zai-glm-4.7" },
@@ -88,7 +109,22 @@ The bundled plugin usually means you only need the API key. Use explicit
88109
```
89110

90111
<Note>
91-
If the Gateway runs as a daemon (launchd/systemd), make sure `CEREBRAS_API_KEY`
92-
is available to that process, for example in `~/.openclaw/.env` or through
93-
`env.shellEnv`.
112+
If the Gateway runs as a daemon (launchd, systemd, Docker), make sure `CEREBRAS_API_KEY` is available to that process — for example in `~/.openclaw/.env` or through `env.shellEnv`. A key sitting only in `~/.profile` will not help a managed service unless the env is imported separately.
94113
</Note>
114+
115+
## Related
116+
117+
<CardGroup cols={2}>
118+
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
119+
Choosing providers, model refs, and failover behavior.
120+
</Card>
121+
<Card title="Thinking modes" href="/tools/thinking" icon="brain">
122+
Reasoning effort levels for the two reasoning-capable Cerebras models.
123+
</Card>
124+
<Card title="Configuration reference" href="/gateway/config-agents#agent-defaults" icon="gear">
125+
Agent defaults and model configuration.
126+
</Card>
127+
<Card title="Models FAQ" href="/help/faq-models" icon="circle-question">
128+
Auth profiles, switching models, and resolving "no profile" errors.
129+
</Card>
130+
</CardGroup>

‎docs/providers/groq.md‎

Lines changed: 93 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,24 @@
11
---
2-
summary: "Groq setup (auth + model selection)"
2+
summary: "Groq setup (auth + model selection + Whisper transcription)"
33
title: "Groq"
44
read_when:
55
- You want to use Groq with OpenClaw
66
- You need the API key env var or CLI auth choice
7+
- You are configuring Whisper audio transcription on Groq
78
---
89

9-
[Groq](https://groq.com) provides ultra-fast inference on open-source models
10-
(Llama, Gemma, Mistral, and more) using custom LPU hardware. OpenClaw connects
11-
to Groq through its OpenAI-compatible API.
10+
[Groq](https://groq.com) provides ultra-fast inference on open-weight models (Llama, Gemma, Kimi, Qwen, GPT OSS, and more) using custom LPU hardware. OpenClaw includes a bundled Groq plugin that registers both an OpenAI-compatible chat provider and an audio media-understanding provider.
1211

13-
| Property | Value |
14-
| -------- | ----------------- |
15-
| Provider | `groq` |
16-
| Auth | `GROQ_API_KEY` |
17-
| API | OpenAI-compatible |
12+
| Property | Value |
13+
| ---------------------- | ---------------------------------------- |
14+
| Provider id | `groq` |
15+
| Plugin | bundled, `enabledByDefault: true` |
16+
| Auth env var | `GROQ_API_KEY` |
17+
| Onboarding flag | `--auth-choice groq-api-key` |
18+
| API | OpenAI-compatible (`openai-completions`) |
19+
| Base URL | `https://api.groq.com/openai/v1` |
20+
| Audio transcription | `whisper-large-v3-turbo` (default) |
21+
| Suggested chat default | `groq/llama-3.3-70b-versatile` |
1822

1923
## Getting started
2024

@@ -23,9 +27,18 @@ to Groq through its OpenAI-compatible API.
2327
Create an API key at [console.groq.com/keys](https://console.groq.com/keys).
2428
</Step>
2529
<Step title="Set the API key">
26-
```bash
27-
export GROQ_API_KEY="gsk_..."
28-
```
30+
<CodeGroup>
31+
32+
```bash Onboarding
33+
openclaw onboard --auth-choice groq-api-key
34+
```
35+
36+
```bash Env only
37+
export GROQ_API_KEY=gsk_...
38+
```
39+
40+
</CodeGroup>
41+
2942
</Step>
3043
<Step title="Set a default model">
3144
```json5
@@ -38,6 +51,11 @@ to Groq through its OpenAI-compatible API.
3851
}
3952
```
4053
</Step>
54+
<Step title="Verify the catalog is reachable">
55+
```bash
56+
openclaw models list --provider groq
57+
```
58+
</Step>
4159
</Steps>
4260

4361
### Config file example
@@ -55,37 +73,56 @@ to Groq through its OpenAI-compatible API.
5573

5674
## Built-in catalog
5775

58-
OpenClaw ships a manifest-backed Groq catalog for fast provider-filtered model
59-
listing. Run `openclaw models list --all --provider groq` to see the bundled
60-
rows, or check
61-
[console.groq.com/docs/models](https://console.groq.com/docs/models).
62-
63-
| Model | Notes |
64-
| --------------------------- | ---------------------------------- |
65-
| **Llama 3.3 70B Versatile** | General-purpose, large context |
66-
| **Llama 3.1 8B Instant** | Fast, lightweight |
67-
| **Gemma 2 9B** | Compact, efficient |
68-
| **Mixtral 8x7B** | MoE architecture, strong reasoning |
76+
OpenClaw ships a manifest-backed Groq catalog with both reasoning and non-reasoning entries. Run `openclaw models list --provider groq` to see the bundled rows for your installed version, or check [console.groq.com/docs/models](https://console.groq.com/docs/models) for Groq's authoritative list.
77+
78+
| Model ref | Name | Reasoning | Input | Context |
79+
| ---------------------------------------------------- | ----------------------------- | --------- | ------------ | ------- |
80+
| `groq/llama-3.3-70b-versatile` | Llama 3.3 70B Versatile | no | text | 131,072 |
81+
| `groq/llama-3.1-8b-instant` | Llama 3.1 8B Instant | no | text | 131,072 |
82+
| `groq/meta-llama/llama-4-maverick-17b-128e-instruct` | Llama 4 Maverick 17B | no | text + image | 131,072 |
83+
| `groq/meta-llama/llama-4-scout-17b-16e-instruct` | Llama 4 Scout 17B | no | text + image | 131,072 |
84+
| `groq/llama3-70b-8192` | Llama 3 70B | no | text | 8,192 |
85+
| `groq/llama3-8b-8192` | Llama 3 8B | no | text | 8,192 |
86+
| `groq/gemma2-9b-it` | Gemma 2 9B | no | text | 8,192 |
87+
| `groq/mistral-saba-24b` | Mistral Saba 24B | no | text | 32,768 |
88+
| `groq/moonshotai/kimi-k2-instruct` | Kimi K2 Instruct | no | text | 131,072 |
89+
| `groq/moonshotai/kimi-k2-instruct-0905` | Kimi K2 Instruct 0905 | no | text | 262,144 |
90+
| `groq/openai/gpt-oss-120b` | GPT OSS 120B | yes | text | 131,072 |
91+
| `groq/openai/gpt-oss-20b` | GPT OSS 20B | yes | text | 131,072 |
92+
| `groq/openai/gpt-oss-safeguard-20b` | Safety GPT OSS 20B | yes | text | 131,072 |
93+
| `groq/qwen-qwq-32b` | Qwen QwQ 32B | yes | text | 131,072 |
94+
| `groq/qwen/qwen3-32b` | Qwen3 32B | yes | text | 131,072 |
95+
| `groq/deepseek-r1-distill-llama-70b` | DeepSeek R1 Distill Llama 70B | yes | text | 131,072 |
96+
| `groq/groq/compound` | Compound | yes | text | 131,072 |
97+
| `groq/groq/compound-mini` | Compound Mini | yes | text | 131,072 |
6998

7099
<Tip>
71-
Use `openclaw models list --all --provider groq` for the manifest-backed Groq
72-
rows known to this OpenClaw version.
100+
The catalog evolves with each OpenClaw release. `openclaw models list --provider groq` shows the rows known to your installed version; cross-check with [console.groq.com/docs/models](https://console.groq.com/docs/models) for newly-added or deprecated models.
73101
</Tip>
74102

75103
## Reasoning models
76104

77-
OpenClaw maps its shared `/think` levels to Groq's model-specific
78-
`reasoning_effort` values. For `qwen/qwen3-32b`, disabled thinking sends
79-
`none` and enabled thinking sends `default`. For Groq GPT-OSS reasoning models,
80-
OpenClaw sends `low`, `medium`, or `high`; disabled thinking omits
81-
`reasoning_effort` because those models do not support a disabled value.
105+
OpenClaw maps its shared `/think` levels to Groq's model-specific `reasoning_effort` values:
106+
107+
- For `qwen/qwen3-32b`, disabled thinking sends `none` and enabled thinking sends `default`.
108+
- For Groq GPT OSS reasoning models (`openai/gpt-oss-*`), OpenClaw sends `low`, `medium`, or `high` based on `/think` level. Disabled thinking omits `reasoning_effort` because those models do not support a disabled value.
109+
- DeepSeek R1 Distill, Qwen QwQ, and Compound use Groq's native reasoning surface; `/think` controls visibility but the model always reasons.
110+
111+
See [Thinking modes](/tools/thinking) for the shared `/think` levels and how OpenClaw translates them per provider.
82112

83113
## Audio transcription
84114

85-
Groq also provides fast Whisper-based audio transcription. When configured as a
86-
media-understanding provider, OpenClaw uses Groq's `whisper-large-v3-turbo`
87-
model to transcribe voice messages through the shared `tools.media.audio`
88-
surface.
115+
Groq's bundled plugin also registers an **audio media-understanding provider** so voice messages can be transcribed through the shared `tools.media.audio` surface.
116+
117+
| Property | Value |
118+
| ------------------ | ----------------------------------------- |
119+
| Shared config path | `tools.media.audio` |
120+
| Default base URL | `https://api.groq.com/openai/v1` |
121+
| Default model | `whisper-large-v3-turbo` |
122+
| Auto priority | 20 |
123+
| API endpoint | OpenAI-compatible `/audio/transcriptions` |
124+
125+
To make Groq the default audio backend:
89126

90127
```json5
91128
{
@@ -100,42 +137,44 @@ surface.
100137
```
101138

102139
<AccordionGroup>
103-
<Accordion title="Audio transcription details">
104-
| Property | Value |
105-
|----------|-------|
106-
| Shared config path | `tools.media.audio` |
107-
| Default base URL | `https://api.groq.com/openai/v1` |
108-
| Default model | `whisper-large-v3-turbo` |
109-
| API endpoint | OpenAI-compatible `/audio/transcriptions` |
110-
</Accordion>
111-
112-
<Accordion title="Environment note">
113-
If the Gateway runs as a daemon (launchd/systemd), make sure `GROQ_API_KEY` is
114-
available to that process (for example, in `~/.openclaw/.env` or via
115-
`env.shellEnv`).
140+
<Accordion title="Environment availability for the daemon">
141+
If the Gateway runs as a managed service (launchd, systemd, Docker), `GROQ_API_KEY` must be visible to that process — not just to your interactive shell.
116142

117143
<Warning>
118-
Keys set only in your interactive shell are not visible to daemon-managed
119-
gateway processes. Use `~/.openclaw/.env` or `env.shellEnv` config for
120-
persistent availability.
144+
A key sitting only in `~/.profile` will not help a launchd or systemd daemon unless that environment is imported there too. Set the key in `~/.openclaw/.env` or via `env.shellEnv` to make it readable from the gateway process.
121145
</Warning>
122146

123147
</Accordion>
148+
149+
<Accordion title="Custom Groq model ids">
150+
OpenClaw accepts any Groq model id at runtime. Use the exact id shown by Groq and prefix it with `groq/`. The bundled catalog covers the common cases; uncatalogued ids fall through to the default OpenAI-compatible template.
151+
152+
```json5
153+
{
154+
agents: {
155+
defaults: {
156+
model: { primary: "groq/<your-model-id>" },
157+
},
158+
},
159+
}
160+
```
161+
162+
</Accordion>
124163
</AccordionGroup>
125164

126165
## Related
127166

128167
<CardGroup cols={2}>
129-
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
168+
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
130169
Choosing providers, model refs, and failover behavior.
131170
</Card>
171+
<Card title="Thinking modes" href="/tools/thinking" icon="brain">
172+
Reasoning effort levels and provider-policy interaction.
173+
</Card>
132174
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
133175
Full config schema including provider and audio settings.
134176
</Card>
135177
<Card title="Groq Console" href="https://console.groq.com" icon="arrow-up-right-from-square">
136178
Groq dashboard, API docs, and pricing.
137179
</Card>
138-
<Card title="Groq model list" href="https://console.groq.com/docs/models" icon="list">
139-
Official Groq model catalog.
140-
</Card>
141180
</CardGroup>

‎docs/providers/sglang.md‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,21 @@ read_when:
66
title: "SGLang"
77
---
88

9-
SGLang can serve open-source models via an **OpenAI-compatible** HTTP API.
10-
OpenClaw can connect to SGLang using the `openai-completions` API.
11-
12-
OpenClaw can also **auto-discover** available models from SGLang when you opt
13-
in with `SGLANG_API_KEY` (any value works if your server does not enforce auth)
14-
and you do not define an explicit `models.providers.sglang` entry.
15-
16-
OpenClaw treats `sglang` as a local OpenAI-compatible provider that supports
17-
streamed usage accounting, so status/context token counts can update from
18-
`stream_options.include_usage` responses.
9+
SGLang serves open-weight models via an OpenAI-compatible HTTP API. OpenClaw connects to SGLang using the `openai-completions` provider family with auto-discovery of available models.
10+
11+
| Property | Value |
12+
| ------------------------- | ------------------------------------------------------------ |
13+
| Provider id | `sglang` |
14+
| Plugin | bundled, `enabledByDefault: true` |
15+
| Auth env var | `SGLANG_API_KEY` (any non-empty value if server has no auth) |
16+
| Onboarding flag | `--auth-choice sglang` |
17+
| API | OpenAI-compatible (`openai-completions`) |
18+
| Default base URL | `http://127.0.0.1:30000/v1` |
19+
| Default model placeholder | `sglang/Qwen/Qwen3-8B` |
20+
| Streaming usage | Yes (`supportsStreamingUsage: true`) |
21+
| Pricing | Marked external-free (`modelPricing.external: false`) |
22+
23+
OpenClaw also **auto-discovers** available models from SGLang when you opt in with `SGLANG_API_KEY` and you do not define an explicit `models.providers.sglang` entry — see [Model discovery (implicit provider)](#model-discovery-implicit-provider) below.
1924

2025
## Getting started
2126

0 commit comments

Comments
 (0)