The Bridge loads one implementation per provider id. When you assign a task to an agent, CtrlNode sends it to the Bridge with that agent’s provider; the Bridge runs the matching CLI or SDK on your machine. Open-source reference: github.com/ctrlnode-ai/ctrlnode (Documentation Index
Fetch the complete documentation index at: https://docs.ctrlnode.ai/llms.txt
Use this file to discover all available pages before exploring further.
src/providers/).
Supported providers
| CtrlNode agent type | Bridge id | Guide |
|---|---|---|
OpenClaw | openclaw | OpenClaw |
ClaudeCode | claude | Claude Code (CLI) |
ClaudeAgentSdk | claude-sdk | Claude Agent SDK |
Copilot | copilot | GitHub Copilot |
Gemini | gemini | Gemini CLI |
CodexSdk | codex | OpenAI Codex |
Cursor | cursor | Cursor |
Pick the agent type that matches the tool you install on the Bridge host. Mixing types in one project is fine — each agent stores its own type.
How routing works
- You create a project with a default agent type (CLI badge in the sidebar).
- You register agents in Team; CtrlNode stores
agent_typeper agent. - On Bridge connect, CtrlNode pushes
sync_{provider}_agentswith agent IDs and metadata. - On dispatch, the Bridge resolves the agent ID → provider → runs that implementation.
Multi-provider Bridge
One Bridge process can load several providers at once:PROVIDERS to use the default (all built-in providers). Install only the CLIs you need; missing tools surface as clear task failures, not silent mis-routing.
Sessions and resume
| Provider | Session behavior |
|---|---|
claude (CLI) | Resumes via Claude CLI --resume when the same task continues |
claude-sdk, copilot, gemini | Fresh session per dispatch (ACP or SDK) |
codex, cursor | Per-agent CODEX_HOME / SDK runner isolation |
openclaw | OpenClaw gateway sessions |
Common troubleshooting
| Symptom | Likely cause |
|---|---|
| Task stuck in Inbox | Bridge offline or agent not registered |
| Failed with 401 | Expired API key or CLI not logged in |
| Agent not found | Bridge connected before agent was created — reconnect |
| Wrong tool ran the task | Agent type does not match installed CLI |
| No terminal event in app | Bridge must send contextTaskId with dispatch (fixed in current Bridge releases) |
Per-provider documentation
OpenClaw
HTTP gateway,
openclaw.json, multi-agent orchestrationClaude Code (CLI)
claude CLI, subscription or login, CLAUDE.md in task folderClaude Agent SDK
@anthropic-ai/claude-agent-sdk, API key, programmatic toolsGitHub Copilot
@github/copilot ACP, PAT or copilot loginGemini CLI
gemini ACP, API key or Google loginOpenAI Codex
@openai/codex-sdk, codex CLI, CODEX_BIN_PATHCursor
@cursor/sdk, CURSOR_API_KEY, Node.js runner