Deploying Claw across our teams and the confusion around agents is a constant timesink. The docs don't help. You have the **Orchestrator**, the **Worker**, and the **Listener**, and people keep trying to use them interchangeably, which breaks everything.
Here's the cheat sheet I give new engineers now:
**Orchestrator** (runs *once* per pipeline, on your CI server/runner):
```yaml
# claw-config.yml
agent:
type: orchestrator
control_plane: "https://claw.internal"
```
* Schedules work, aggregates results. Never runs a scan itself.
**Worker** (scales out, runs the actual jobs):
```yaml
agent:
type: worker
orchestrator_url: "https://claw.internal"
queue: "security-scans"
```
* Pulls tasks from the Orchestrator's queue. Ephemeral. You can have 50 of these.
**Listener** (passive, for runtime context):
```yaml
agent:
type: listener
api_key: ${CLAW_LISTENER_KEY}
```
* Deployed alongside your app (e.g., as a sidecar). Collects data, reports back. Not for CI.
The mix-up I see daily: teams putting a Listener config in their pipeline, then wondering why no scan results appear. Or trying to make a Worker do Orchestrator tasks.
What's your clearest way to explain this? Any other config pitfalls to watch for?
cg
YAML all the things.
Oh thank you for this! I've been fumbling with this for a week. Your sheet helps, but can I ask a dumb question?
Is the Listener *only* for things already running live? Like, if I'm just using Claw in our deployment pipeline to check a pull request, I shouldn't even think about it, right?
Yeah, that's not a dumb question at all! I was stuck on the same thing. The way I finally got it is that the Listener is indeed for already-running stuff, like live production containers.
But here's the new part that tripped me up: you *can* use it in a pipeline, just for a different reason. If you have a long-running service in your staging environment that's part of the deployment, you might attach a Listener to *that* to monitor it *after* the scan, not to do the scan itself. So for a simple PR check, you're right, you can totally ignore it.
Thanks for asking this, helps me too! 😅 Does that match what you've seen?