Note

This repository contains the AtlasClaw core implementation, including the agent runtime, API layer, channel adapters, provider registry, skills, tools, and session/memory management，see atlasclaw.ai.

Concrete providers are not implemented in this repository. AtlasClaw loads provider packages from providers_root. In a sibling-repository layout, a common value is ../atlasclaw-providers/providers.

AtlasClaw

AtlasClaw is an enterprise agent framework that lets employees interact with multiple enterprise systems through one conversational AI interface. Instead of switching between separate consoles, dashboards, and approval portals, users can use natural language to trigger workflows, query operational data, and complete cross-system tasks from a single entry point.

Background

Enterprise software teams often need to work across CRM, ITSM, Monitoring, HR, Finance, OA and other internal systems. The challenge is not only system fragmentation, but also the mismatch between data models, workflow boundaries, authorization models, and user experience across those systems.

AtlasClaw is designed around two practical developer questions:

• How do you provide one unified AI Agent experience on top of the systems an enterprise already has?
• How do you let enterprise software developers add AI Agent capabilities to their own systems quickly, without rebuilding agent infrastructure from scratch?

AtlasClaw addresses those problems with a developer-oriented agent framework:

• A unified conversational layer for cross-system workflows and operations
• A pluggable provider model that lets developers expose system capabilities to the agent quickly
• Strict permission inheritance so every action runs under the authenticated user's real access rights
• Multi-channel access through web UI, embedded panels, chat platforms, and programmatic webhooks

The framework is built to help teams add agent capabilities to existing enterprise software without weakening governance. AtlasClaw does not bypass RBAC, does not escalate privileges, and keeps platform-specific authorization and auditing where they already belong.

Key Capabilities

• LLM-driven Skills model instead of hard-coded traditional workflows
• Skills define business scenarios, decision boundaries, and how the agent interacts with external systems
• A cross-system agent brain for analysis, judgment, coordination, and execution across enterprise software
• Provider-based integration model that lets developers add new system capabilities quickly
• Thin-core architecture that keeps platform-specific logic in Providers and reusable agent logic in the core
• Embeddable agent foundation for enterprise application developers
• Context-aware floating assistant that follows Enterprise System navigation and binds the current page object to the appropriate Provider Skill
• Core-matched, Provider-defined dynamic Context routes and object actions without page-specific business mappings in AtlasClaw Core
• API-first interaction model with interactive APIs, WebSocket streaming, and webhook entry points
• Flexible LLM backend support through external model providers

Deployment Modes

AtlasClaw supports two practical usage modes for enterprise software teams.

Embedded Agent Mode

AtlasClaw can be embedded into an existing enterprise system as a module inside that system. In this mode, the AI Agent becomes part of the product itself, serving that system's own users, data, and business scenarios.

• Embedded as an in-product AI module
• Provides two independent embedded surfaces that can be deployed together: a full menu UI and a compact floating UI
• Uses the same Enterprise System Cookie authentication context for both surfaces, so they share the signed-in user's existing system access and upstream permissions
• Keeps menu integration minimal: the Enterprise System only adds a menu entry and embeds the Agent with embedded=1&surface=menu
• Adds a generic page bridge for floating mode: the Enterprise System manages the launcher/iframe and reports normalized page paths with a nonce and a monotonically increasing generation
• Lets the two surfaces share a bootstrap-validated active Chat Session without turning one surface into the other
• Re-resolves Context when the Enterprise System page changes, so the assistant follows the current business object in the floating UI instead of keeping stale page state
• Lets Core match Provider-owned route manifests, while Provider resolvers load a minimal object projection and present state-aware actions
• Supports both user-facing interaction interfaces and agent-style automation
• Uses Skills to define scenarios and system-specific actions inside the existing system
• Fits teams that want to add AI Agent capability to an existing enterprise product quickly

The formal integration component is the configured HostApp Provider inside AtlasClaw. It maps Enterprise System pages to business objects, Domain Skills, and state-aware actions without requiring a new service in the Enterprise System. See Embedded Integration for the Cookie, surface, Context, and message contracts.

Standalone Agent Mode

AtlasClaw can also run as an independent enterprise AI Agent system that connects multiple existing systems together. In this mode, it acts as a unified AI layer above those systems rather than belonging to only one of them.

• Runs as an independent AI Agent platform for the enterprise
• Connects and coordinates multiple systems through Providers
• Builds a shared cross-system brain for analysis, judgment, coordination, and execution
• Fits teams that want one unified AI Agent entry point across the enterprise

Architecture

AtlasClaw is organized around a thin core plus rich providers.

• Access channels support both embedded in-system experiences and standalone enterprise entry points
• AtlasClaw Core hosts the API layer, session/config services, and the agent engine
• LLM services are external and replaceable through configuration
• Providers encapsulate authentication, skills, and scripts for each connected enterprise platform
• Enterprise systems remain the source of truth for authorization and auditing

Overall Architecture

At a high level, requests enter through one of the supported channels, pass through the AtlasClaw Core, and are executed against enterprise systems through Providers. Embedded mode exposes two independent entry points inside an existing Enterprise System: a full menu UI for ordinary conversations and a compact floating UI for page-scoped assistance. Both receive the same Enterprise System Cookie authentication context, so they represent the same signed-in user and reuse that user's existing permissions. The menu requires only a nested Agent entry. The floating UI additionally requires the Enterprise System to manage its launcher/iframe and provide a secure page-change bridge, but Enterprise System code does not resolve objects or invoke Agent and Tool APIs. The surfaces can also share a bootstrap-validated active Chat Session, while only the floating UI consumes page changes. For each change, Core deterministically matches the normalized path against the configured HostApp Provider's Context routes, and that Provider resolves the visible business object and its current actions. The resulting Context is bound to the matching existing Skill and the authenticated user's permissions before it enters the normal Chat and Tool execution path. In standalone mode, AtlasClaw exposes an independent AI Agent interface that sits above multiple enterprise systems. In both cases, the core remains lightweight and reusable, while each Provider contains the system-specific integration logic.

Core Architecture

The core runtime in this repository centers on:

• API Layer: interactive APIs, WebSocket streaming, and webhook endpoints for both user-driven and programmatic invocation
• Agent Engine: routing, prompt building, tool selection, and execution orchestration
• Session & Memory: conversation context, persistence, and retrieval
• Tools & Skills: reusable execution units exposed to the agent
• Provider Registry: registration and discovery of enterprise integrations
• Execution Context: dependency injection for auth, tenant, and runtime-scoped data

Repository Layout

project-root/
├── app/atlasclaw/api/         # REST, SSE, WebSocket, gateway orchestration
├── app/atlasclaw/agent/       # Agent runner, routing, streaming, prompt building
├── app/atlasclaw/channels/    # Channel adapters and registries
├── app/atlasclaw/core/        # Config, execution context, provider registry
├── app/atlasclaw/memory/      # Memory manager and retrieval
├── app/atlasclaw/session/     # Session context, queue, and manager
├── app/atlasclaw/skills/      # Skill loading and registry
├── app/atlasclaw/tools/       # Built-in tools and tool catalog
├── app/atlasclaw/workflow/    # Workflow engine and orchestrator
├── docs/                      # Concepts, tools, channels, and design notes
└── tests/                     # Pytest test suite

Quick Start

Requirements

• Python 3.11+
• A virtual environment is recommended
• Access to an LLM provider and target enterprise systems for end-to-end integration

Install Dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

For development and test execution, install the development manifest instead; it includes all runtime dependencies plus the test runner:

pip install -r requirements-dev.txt

Configure Environment

AtlasClaw uses atlasclaw.json for configuration. Create a configuration file in the project root:

{
  "providers_root": "../atlasclaw-providers/providers",
  "model": {
    "primary": "kimi/kimi-k2.5",
    "temperature": 0.7,
    "providers": {
      "kimi": {
        "base_url": "${ANTHROPIC_BASE_URL}",
        "api_key": "${ANTHROPIC_API_KEY}",
        "api_type": "anthropic"
      }
    }
  }
}

The example above assumes a sibling atlasclaw-providers repository. The schema default for providers_root remains ../providers.

Configuration options:

• providers_root - Root directory for provider packages, resolved relative to atlasclaw.json (schema default: ../providers)
• Provider skills discovered under providers_root are registered as provider:skill to avoid name collisions
• model.primary - Primary model in format provider/model-name
• model.providers - Provider configurations with base_url, api_key, and api_type
• api_type - API type: openai (default) or anthropic

Environment variables are expanded from ${VAR_NAME} format. Set them before starting:

# For Kimi (Anthropic-compatible API)
export ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic"
export ANTHROPIC_API_KEY="your-api-key"

# For Doubao (OpenAI-compatible API)
export DOUBAO_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export DOUBAO_API_KEY="your-api-key"

Run Tests

# Run all tests
pytest tests/atlasclaw -q

# Run LLM integration tests (requires API credentials)
export ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic"
export ANTHROPIC_API_KEY="your-api-key"
pytest tests/atlasclaw/test_agent_integration.py -v -m llm

# Run e2e tests (requires running service)
pytest tests/atlasclaw/test_e2e_api.py -v -m e2e

Start the Service

Start the backend API server:

uvicorn app.atlasclaw.main:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://127.0.0.1:8000.

Access the Web UI

Once the service is running, open your browser and navigate to:

http://127.0.0.1:8000/

The Web UI provides:

• Chat interface powered by DeepChat
• Real-time streaming responses via SSE
• Multi-language support (Chinese / English)
• Session management with conversation history

Frontend Development

The frontend is located in app/frontend/ and supports two deployment modes:

Open Source Mode (default):

• Source files are served directly without bundling
• No build step required
• Edit files in app/frontend/scripts/ and refresh browser

Enterprise Mode:

cd app/frontend
npm install
npm run build

• Produces minified dist/app.min.js
• Update index.html to reference the bundled file

Run Frontend Tests:

cd app/frontend
npm test

Development Notes

• Entry point: app/atlasclaw/main.py - FastAPI application with lifespan management
• The API surface lives under app/atlasclaw/api/
• Core orchestration logic lives under app/atlasclaw/agent/, app/atlasclaw/workflow/, and app/atlasclaw/tools/
• Provider integrations are loaded from providers_root (schema default: ../providers; common sibling-repo layout: ../atlasclaw-providers/providers)

If you are integrating AtlasClaw into a host service, start by wiring the API layer, execution context, provider registry, and session manager together in your application bootstrap.

Further Reading

• Architecture Concepts
• Tooling Documentation
• Channel Documentation
• Automation Documentation