# How to Configure the Groq API Key for Xiaoyuzhou Podcast Transcription in Agent-Reach

> Configure your Groq API key for Xiaoyuzhou podcast transcription in Agent-Reach. Easily set your GROQ_API_KEY environment variable or use the agent-reach configure command.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-06

---

**To configure the Groq API key for Xiaoyuzhou podcast transcription in Agent-Reach, either export the `GROQ_API_KEY` environment variable or run `agent-reach configure groq-key gsk_xxxxx` to persist the key in `~/.agent-reach/config.yaml`.**

Agent-Reach is an open-source podcast automation tool that transcribes Xiaoyuzhou (小宇宙) episodes using Groq’s Whisper API. Before you can transcribe audio, you must configure the Groq API key for Xiaoyuzhou podcast transcription so the channel can authenticate with Groq’s servers. This guide walks through the exact resolution order, configuration commands, and verification steps as implemented in the `Panniantong/Agent-Reach` source code.

## How Agent-Reach Resolves the Groq API Key

The system checks two locations in order, as defined in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py). First, it inspects the `GROQ_API_KEY` environment variable. If that is unset, it falls back to the Agent-Reach configuration file at `~/.agent-reach/config.yaml` under the key `groq_api_key`. This lookup is handled by the `XiaoyuzhouChannel.check()` method, which also verifies that `ffmpeg` and the transcription script are present before validating API access.

```python

# agent_reach/channels/xiaoyuzhou.py

# Lines 39-52

has_key = bool(os.environ.get("GROQ_API_KEY"))
if not has_key:
    cfg = config if config is not None else Config()
    has_key = bool(cfg.get("groq_api_key"))
if not has_key:
    return "warn", (
        "需要配置 Groq API Key（免费）。步骤：\n"
        "  1. 注册 https://console.groq.com\n"
        "  2. 运行: agent-reach configure groq-key gsk_xxxxx"
    )

```

If both lookups fail, the channel returns a warning that instructs you to register at the Groq console and run the built-in configure command.

## Configuration Methods for the Groq API Key

### Option 1: Export the `GROQ_API_KEY` Environment Variable

Setting the environment variable is the fastest way to configure the Groq API key for Xiaoyuzhou podcast transcription. It is evaluated first by `XiaoyuzhouChannel.check()` but only lasts for the current shell session.

```bash
export GROQ_API_KEY=gsk_XXXXXXXXXXXXXXXX

```

### Option 2: Persist the Key with the Agent-Reach CLI (Recommended)

For a permanent configuration, use the built-in CLI command. This writes the key to `~/.agent-reach/config.yaml` under the name `groq_api_key`, which is managed by the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).

```bash
agent-reach configure groq-key gsk_XXXXXXXXXXXXXXXX

```

According to the `Panniantong/Agent-Reach` source code, the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) defines `FEATURE_REQUIREMENTS` and handles reading and writing these persistent values, making this the preferred method for repeated transcription tasks.

## Verify Your Groq API Key Configuration

You can confirm the key is recognized by running the diagnostics command or the install helper. During `agent-reach install --env=auto`, the routine in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) performs the same dual-check and prints a status line:

```python

# agent_reach/cli.py

# Lines 45-51

has_key = bool(os.environ.get("GROQ_API_KEY")) or bool(config.get("groq_api_key"))
if has_key:
    print("  ✅ Groq API key configured")
else:
    print("  -- Groq API key not set. Get free key at https://console.groq.com")
    print("     Then run: agent-reach configure groq-key gsk_xxxxx")

```

To verify interactively, run:

```bash
python -m agent_reach.cli doctor

```

Expect to see `✅ Groq API key configured` when the key is correctly set.

## Run a Xiaoyuzhou Podcast Transcription

Once the Groq API key is configured, the Xiaoyuzhou channel can automatically download episodes and invoke the Groq Whisper service via the [`transcribe.sh`](https://github.com/Panniantong/Agent-Reach/blob/main/transcribe.sh) script located at `~/.agent-reach/tools/xiaoyuzhou/`. Pass the episode URL to the read command:

```bash
agent-reach read https://www.xiaoyuzhoufm.com/episode/12345

```

The channel will handle audio extraction and send it to Groq for transcription.

## Summary

- Agent-Reach resolves the Groq API key in two places: the `GROQ_API_KEY` environment variable first, then `groq_api_key` in `~/.agent-reach/config.yaml`.
- The validation logic lives in `XiaoyuzhouChannel.check()` inside [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py), which also checks for `ffmpeg` and the transcription script.
- Use `agent-reach configure groq-key gsk_xxxxx` to persist the key permanently via the `Config` manager.
- Verify the setup with `python -m agent_reach.cli doctor` before running `agent-reach read` on a Xiaoyuzhou episode URL.

## Frequently Asked Questions

### What is the exact environment variable name for the Groq API key?

The environment variable must be named `GROQ_API_KEY`. This is the first value inspected by `XiaoyuzhouChannel.check()` and by the install helper in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

### Where does Agent-Reach store the persistent Groq API key?

The persistent key is stored in `~/.agent-reach/config.yaml` under the field `groq_api_key`. This file is managed by the `Config` class defined in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).

### Is ffmpeg required to transcribe Xiaoyuzhou podcasts with Agent-Reach?

Yes. According to the source code in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py), `XiaoyuzhouChannel.check()` verifies that `ffmpeg` and the transcription script are present before it checks for the Groq API key.

### How do I update my Groq API key after initial configuration?

Simply run the configure command again with your new key. The CLI will overwrite the existing `groq_api_key` value in `~/.agent-reach/config.yaml` with the updated token.