AI Overview & Mental Model
Opbox's AI is best understood as four distinct layers that share one credential resolver, one cost ledger, and one tool catalogue. Get this mental model right and everything else follows.
The Four Layers
| # | Layer | Direction | Identity | Powered By |
|---|---|---|---|---|
| 1 | Personal AI Keys (BYOK) | Opbox -> provider | Your provider account | Anthropic / OpenAI / Groq / OpenClaw / Hermes |
| 2 | Opbox AI Agent | In-process or external | Acts as the agent member | The keys above |
| 3 | Opbox Agent (org member) | A row in the User table | Owns audit trail entries | n/a (it's an identity) |
| 4 | MCP Bridge | External client -> Opbox | The MCP API key | The same tool catalogue chat uses |
Five providers, one socket. The "Org AI" page is a BYOK socket for Anthropic, OpenAI, Groq, OpenClaw, and Hermes. OpenClaw is a long-lived stateful runtime with per-agent routing and bidirectional MCP bearer auth. Hermes is the per-tenant Onyx runtime exposed through an OpenAI-compatible API; it can run standalone without Opbox, and uses MCP only when the tenant agent needs to call back into Opbox tools. See OpenClaw Provider and Hermes Provider.
Mental model: Personal AI Keys are the fuel, the AI Agent is the engine, the Agent member is the driver's license, MCP is the road.
How They Interlock
You in Claude Code ──[MCP key #4]──> Opbox tools
│
└─ runs LLM calls with → Personal AI Keys (#1)
Opbox AI Agent (#2) ── acts as ──> Opbox Agent member (#3)
│
└─ when using Agent Bridge, calls back via ──> MCP (#4)
| Scenario | Layers used |
|---|---|
| You ask Claude Code "list my matters" | MCP only - Opbox runs SQL, no LLM call. |
| You ask Claude Code to summarise a matter | MCP + your Anthropic subscription (Claude Code's own LLM, not Opbox's BYOK). |
| You assign a matter to the Opbox Agent member | AgentTask -> AI Agent worker -> BYOK keys. May call back via MCP if running through the Agent Bridge. |
Spotlight chat (Cmd+K) | BYOK keys directly - no MCP, no AI Agent worker. |
The Resolver Chain
Every server-side AI call (chat, agent worker, workflow AI step, extraction, doc-gen detection) walks four credential tiers in priority order:
| # | Tier | Scope | Default |
|---|---|---|---|
| 1 | Personal (UserAiConfig) | One user, one workspace | None |
| 2 | Workspace (WorkspaceAiConfig) | All users in one workspace | Inherits from org |
| 3 | Organisation (OrganizationAiConfig) | All workspaces in one org | Inherits from env |
| 4 | Server env (ANTHROPIC_API_KEY / OPENAI_API_KEY) | Server-level fallback | None - last resort |
First non-empty key wins. The tier that supplied the key is recorded as keySource (user / workspace / org / server) and flows into the cost ledger so spend can be attributed accurately.
The Personal tier is skipped entirely when the parent org sets
allowPersonalKeys = false- a policy lever for cost-control, compliance, and audit-attribution. See BYOK Credentials.
One Tool Catalogue, Three Surfaces
Opbox registers ~406 AI tools (CRM, matters, documents, agent queue, doc-gen, admin, data, equity, ESOP, ...). The same registry is exposed across three surfaces:
| Surface | How it accesses tools | Auth |
|---|---|---|
| Spotlight chat | In-process JS calls | Logged-in user session |
| AI Agent worker | In-process JS calls | The agent member's session |
| MCP bridge | HTTP via /api/mcp | cp_live_* API key |
Every call passes through prompt-injection scanning on result re-entry, and every mutation honours the same autonomy / role / cell-locking rules. The MCP bridge adds a fourth gate: autonomyLevel (0-3) on the API key.
One Cost Ledger
Every LLM call writes one AiCostLedger row with workspaceId, operationType (chat / agent / extraction / embedding / other), model, inputTokens, outputTokens, actualCostUsd, and keySource. The ledger is the single source of truth for spend - chargeback, budgets, and reports all read from it.
Spend breakdowns pivot the ledger two ways:
- By feature - which subsystem consumed the spend (chat, agent, extraction, embedding, other)
- By tier - which credential paid for it (
USER_KEY/WORKSPACE_KEY/ORG_KEY/SERVER_KEY)
Surfaced at Settings > AI > Cost Control. See Cost Control for details.
Topology Scenarios
How AI behaves depends on the workspace topology. The five common cases:
| Scenario | Tooling visibility | Cross-workspace AI |
|---|---|---|
| One org, one workspace | Workspace-local | n/a |
| One org, two sibling workspaces | Each sees only itself | Blocked (no oversight edge) |
| One org, two workspaces with oversight (citadel) | Overseer can _targetWorkspaceId swap into client | Permitted, audit-logged |
| Two unrelated orgs | Complete isolation | Blocked |
| Two orgs linked by oversight (CSP serving external client) | Oversight edge crosses org boundary | Permitted; ledger row goes to calling workspace |
The CSP citadel model is the most common production pattern: each client workspace is a walled-off citadel, the CSP firm workspace looks in via oversight. Client workspaces have no awareness of siblings; the firm reasons across the whole client base via HMAC-SHA256 hashed identity links rather than cleartext data sharing.
Where to Go Next
- New to BYOK setup? Read BYOK Credentials.
- Setting up a workspace? Read Security & Limits.
- Building an MCP integration? Jump to MCP Overview.
- Curious about the autonomous worker? See Agent Worker.