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

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. 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.

# 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.

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.

agent-reach configure groq-key gsk_XXXXXXXXXXXXXXXX

According to the Panniantong/Agent-Reach source code, the Config class in 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 performs the same dual-check and prints a status line:

# 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:

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 script located at ~/.agent-reach/tools/xiaoyuzhou/. Pass the episode URL to the read command:

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, 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.

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.

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

Yes. According to the source code in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}