FAQ

FAQ

General

Do I need config.yaml to use OpenSwarm?

No. The TUI chat (openswarm), openswarm run, openswarm chat, and openswarm check commands work without any configuration file. You only need config.yaml for daemon mode (openswarm start) which requires Discord and Linear integration.

What Node.js version do I need?

Node.js 22 or later. OpenSwarm uses native ESM modules and recent Node.js APIs.

Does OpenSwarm work offline?

Yes, with the local adapter. Start Ollama, LMStudio, or llama.cpp server locally, then:

openswarm run "Fix the bug" --model gemma-4-e4b-it

No internet connection or API keys needed.

---

Adapters & Models

How do I switch between providers?

In config.yaml:

adapter: gpt    # claude | codex | gpt | local

At runtime via Discord:

!provider local

Per-command:

openswarm run "task" --model gpt-4o

Which adapter should I use?

Use Case	Recommended
Best code quality	claude (Sonnet/Opus)
Cost-sensitive	local (Gemma/Llama)
OpenAI preference	gpt (GPT-4o) or codex (o3)
Offline/private	local
Hybrid (cost + quality)	claude for Worker, local for Reviewer

Can I use different models for different roles?

Yes. See Adapters#hybrid-configuration:

autonomous:
  defaultRoles:
    worker:
      adapter: claude
      model: claude-sonnet-4-20250514
    reviewer:
      adapter: local
      model: gemma-4-e4b-it

How does model escalation work?

If a Worker or Reviewer fails after N iterations, it automatically switches to a more capable model:

worker:
  model: claude-sonnet-4-20250514
  escalateModel: claude-opus-4-6
  escalateAfterIteration: 3

---

Code Registry

What languages does the Code Registry support?

TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, and C#.

How do I scan my repository?

openswarm check --scan

This registers all code entities (functions, classes, types, interfaces) in the SQLite registry.

Can I use Code Registry in CI/CD?

Yes:

openswarm check --ci

Outputs JSON. Returns exit code 1 if critical BS issues are found.

---

Autonomous Mode

Is autonomous mode safe?

OpenSwarm includes multiple safety mechanisms:

• DecisionEngine: Filters out-of-scope and risky tasks
• Pipeline guards: Quality gate, fake data guard, uncertainty detection
• Approval flow: Tasks can require manual approval before execution
• Rate limits: 5-hour rolling window, per-project caps
• StuckDetector: Halts pipelines that aren't making progress

How does the approval flow work?

By default, tasks wait for manual approval via Discord (!approve/!reject). Enable auto-approval with !auto approve on.

What happens if a task gets stuck?

The StuckDetector monitors for:

• Repeating errors
• No progress between iterations
• Token budget exhaustion

It triggers model escalation or halts the pipeline, then reports to Discord.

---

Discord

How do I set up the Discord bot?

1. Create a bot at Discord Developer Portal
2. Enable Message Content Intent in bot settings
3. Add the bot to your server
4. Set environment variables:

DISCORD_TOKEN=your-bot-token
DISCORD_CHANNEL_ID=your-channel-id
DISCORD_ALLOWED_USERS=your-discord-user-id

Why are my commands being denied?

Check DISCORD_ALLOWED_USERS in your .env. It must contain your Discord user ID. If not set, all commands are denied (fail-closed).

---

Troubleshooting

"adapter not available" error

• Claude: Run claude auth to authenticate
• GPT: Run openswarm auth login --provider gpt
• Codex: Install with npm i -g @openai/codex
• Local: Make sure Ollama/LMStudio/llama.cpp server is running

Registry database errors

Try rescanning:

openswarm check --scan

The registry database is at ~/.openswarm/registry.db.

Web dashboard won't start

Check if port 3847 is already in use:

lsof -i :3847
openswarm dash -p 8080    # Use different port