# Configuring Groq API Key for Xiaoyuzhou Podcast Transcription in Agent Reach

> Easily configure your Groq API key for Agent Reach Xiaoyuzhou podcast transcription. Set the GROQ_API_KEY environment variable or run the agent-reach configure command.

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

---

**To enable Xiaoyuzhou podcast transcription in Agent Reach, provide your Groq API key by setting the `GROQ_API_KEY` environment variable or executing `agent-reach configure groq-key gsk_xxxxx` to store it permanently in `~/.agent-reach/config.yaml`.**

Agent Reach integrates with Groq's Whisper API to transcribe audio from Xiaoyuzhou (小宇宙) podcast episodes. The system requires a valid Groq API key to process downloads, which it discovers through environment variables or a local configuration file. This guide explains the exact lookup mechanism implemented in the **Panniantong/Agent-Reach** repository and provides step-by-step configuration instructions.

## How Agent Reach Discovers the Groq API Key

According to the source code in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py), the `XiaoyuzhouChannel.check()` method validates transcription readiness by checking for the Groq key in two locations:

1. **Environment variable** `GROQ_API_KEY` (checked first)
2. **Configuration file** at `~/.agent-reach/config.yaml` under the key `groq_api_key` (checked second)

If neither location contains a key, the channel returns a warning with registration instructions. The relevant logic appears in lines 39-52 of the Xiaoyuzhou channel implementation:

```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"
    )

```

## Setting the Groq API Key

You can configure the key using either temporary environment variables or the persistent configuration command.

### Method 1: Environment Variable (Session-Only)

Set the `GROQ_API_KEY` variable in your shell to make the credential available to the current session:

```bash
export GROQ_API_KEY=gsk_XXXXXXXXXXXXXXXX

```

This approach does not persist across terminal sessions but takes precedence over the configuration file when present.

### Method 2: Persistent Configuration (Recommended)

Use the built-in CLI command to write the key to `~/.agent-reach/config.yaml`. This method stores the credential under the `groq_api_key` field as defined 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

```

The configuration manager in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (specifically within `Config.FEATURE_REQUIREMENTS` at lines 21-27) handles the persistence and retrieval of this value.

## Verification and Installation Checks

During the installation routine (`agent-reach install --env=auto`), the CLI performs the same key validation found in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) lines 45-51:

```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 your configuration manually, run the diagnostic command:

```bash
python -m agent_reach.cli doctor

```

Look for the line indicating **"✅ Groq API key configured"** in the output.

## Running Xiaoyuzhou Transcription

Once configured, the Xiaoyuzhou channel automatically invokes 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 a podcast URL to the read command:

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

```

Complete workflow example:

```bash

# Obtain key from https://console.groq.com

agent-reach configure groq-key gsk_XXXXXXXXXXXXXXXX

# Verify configuration

python -m agent_reach.cli doctor | grep "Groq API key"

# Transcribe episode

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

```

## Summary

- **Agent Reach** requires a Groq API key to transcribe Xiaoyuzhou podcasts using Groq's Whisper API.
- The system checks the `GROQ_API_KEY` environment variable first, then falls back to `~/.agent-reach/config.yaml`.
- Use `agent-reach configure groq-key <key>` for persistent storage managed by [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py).
- Validation occurs in `XiaoyuzhouChannel.check()` and during CLI installation routines.
- Verify your setup with `python -m agent_reach.cli doctor` before attempting transcription.

## Frequently Asked Questions

### Where does Agent Reach store the Groq API key when using the configure command?

The command writes to `~/.agent-reach/config.yaml` under the field name `groq_api_key`. This file is managed by the `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), which defines the feature requirements and handles all configuration persistence.

### Why does my transcription fail even after setting the environment variable?

Ensure the variable is exported in the same shell session running Agent Reach. The code in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) uses `os.environ.get("GROQ_API_KEY")`, which requires the variable to be present in the process environment. Simply defining it in `.bashrc` or `.zshrc` without exporting it to the current session will cause the check to fail.

### Can I use both the environment variable and config file simultaneously?

Yes. The implementation checks the environment variable first (lines 39-42 in [`xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaoyuzhou.py)), so if `GROQ_API_KEY` is set, it takes precedence regardless of config file contents. The configuration file only serves as a fallback when the environment variable is absent.

### Is the Groq API key required for all Agent Reach channels or only Xiaoyuzhou?

The Groq key specifically enables the Xiaoyuzhou channel's transcription capability, as implemented in `XiaoyuzhouChannel.check()` at lines 39-52. Other channels may have different API requirements defined in their respective validation logic within the `agent_reach/channels/` directory.