Channels, Gateway, and Operations

Channels adapt different chat platforms into unified messages. The Gateway assembles Channels, AgentLoop, HTTP APIs, scheduled tasks, and observability into a long-running service.

Supported Channels

Interactive CLI sessions use ChatChannel, while one-shot commands use SingleTurnChannel. Both use the same unified message model.

Channel Responsibilities

BaseChannel and platform-specific implementations jointly handle:

1. starting and stopping connections and reporting runtime status;
2. enforcing sender policies such as allow_from;
3. extracting text, images, attachments, and reply metadata;
4. building SessionKey and InboundMessage;
5. converting OutboundMessage into a platform-native reply;
6. displaying processing state or reactions when supported by the platform.

Platform differences remain inside individual Channels, so AgentLoop does not depend on Feishu, Slack, or other platform SDKs.

ChannelManager creates every enabled instance from bot.channels and distinguishes multiple Bots of the same type using type__channel_id. It consumes the MessageBus outbound queue and routes replies back to the originating channel using SessionKey.

Gateway Runtime

vikingbot gateway starts the following components in one asyncio process:

FastAPI / Uvicorn
  + OpenAPIChannel
  + Configured chat Channels
  + MessageBus
  + AgentLoop
  + CronService
  + HeartbeatService

The default listen address is 127.0.0.1:18790. If gateway.host is not localhost, bot.gateway.token is required or the Gateway refuses to start.

Bot HTTP API

The Bot API is available under /bot/v1:

ChatRequest supports a session ID, additional context, reply control, request-level disabled tools, and a channel ID. ChatResponse returns a response ID, final text, intermediate events, relevant memories, and token usage.

SSE emits reasoning, content delta, tool call, tool result, iteration, and final response events.

OpenViking API Proxy

When an OpenViking Server is configured, the Gateway also provides:

The proxy removes hop-by-hop headers, forwards validated identity headers, and preserves the upstream response status. See OpenViking Integration for the complete connection and identity flow.

Access Control

The Gateway enforces several security boundaries:

1. non-local listeners require X-Gateway-Token;
2. loopback requests may use the local development boundary;
3. an OpenViking API Key is checked through upstream /health to validate identity and the effective auth mode;
4. only a trusted OpenViking Server proxy may supply openviking_connection;
5. API Sessions are isolated by combining the authenticated principal scope with the external session ID.

Ordinary request fields such as user_id, account ID, or connection data cannot prove an OpenViking identity by themselves.

Feedback and Outcome Evaluation

Every final reply receives a response_id. Clients may submit thumbs up, thumbs down, or a numeric rating, along with an optional reason and text. The Gateway stores the feedback, calculates feedback delay, and emits a feedback_submitted event.

When the user continues the conversation, Outcome Evaluator can infer whether the previous reply succeeded from subsequent behavior and emit a response_outcome_evaluated event. vikingbot feedback-stats aggregates local Sessions to report feedback coverage, ratings, outcome status, tool usage, and latency.

Langfuse and Logging

With bot.langfuse.enabled=true, model calls, token usage, latency, tool events, and outcome metadata are sent to Langfuse. A Langfuse initialization failure does not block the main Bot flow.

Runtime logs use Loguru. Gateway's --verbose flag enables more detailed logs. Analytics-only events are separated from normal replies and are not accidentally sent to chat platforms.

Implementation Locations

Related Documentation

• VikingBot Architecture
• Agent Capabilities
• OpenViking Integration
• Channel Configuration