🔐 ATP OpenClaw Integration

Quantum-safe security layer for OpenClaw AI agents

This package provides seamless integration between the Agent Trust Protocol™ (ATP) and OpenClaw, enabling enterprise-grade security, trust scoring, and policy enforcement for multi-agent AI systems.

🌟 Features

• 🛡️ Agent Identity Management - Quantum-safe DIDs for every OpenClaw agent
• 🔒 Tool Security Wrapper - ATP security checks on all tool calls
• 📊 Trust-Based Access Control - Dynamic trust scoring and policy enforcement
• 📝 Task-Level Security - Attach security metadata to tasks and knowledge graphs
• 🌐 Graph Validation - Policy-based validation of agent interaction graphs
• 📡 Observability Integration - Lunary metrics → ATP trust engine
• 🔑 Secrets Management - ATP-managed credentials for external services
• 📦 Zero Configuration - Works out of the box with OpenClaw

🚀 Quick Start

Installation

TypeScript / Node.js (this package):

npm install @atpdevelopment/openclaw-atp atp-sdk
# or
yarn add @atpdevelopment/openclaw-atp atp-sdk

Python:

pip install openclaw-atp

Basic Usage (TypeScript)

import { registerClawWithAtp, wrapSkillWithAtp, enforceAtpPoliciesForClawSession } from '@atpdevelopment/openclaw-atp';
import { ATPClient } from 'atp-sdk';

// Initialize with a security profile
const atp = new ATPClient({ baseUrl: 'https://api.atp.dev', profileId: 'openclaw-sandbox' });

// Register an OpenClaw agent with ATP identity
const { did, trustScore } = await registerClawWithAtp(atp, {
  name: 'trader-agent',
  capabilities: ['trading', 'analysis'],
  trustLevel: 'high'
});

// Secure tools with profile-based action gating
const secureTrade = wrapSkillWithAtp(tradeTool, atp, { actionType: 'network' });
const secureShell = wrapSkillWithAtp(shellTool, atp, { actionType: 'shell' });
const secureFs    = wrapSkillWithAtp(fileTool, atp, { actionType: 'filesystem' });

// Enforce session-state policies with profile
await enforceAtpPoliciesForClawSession(
  { state: 'executing', agentDid: did },
  atp,
  { profileId: 'openclaw-sandbox' }
);

Basic Usage (Python)

from openclaw.agents.langchain import ReActToolCallingOpenClawAgent
from openclaw_atp import (
    register_agent_with_atp,
    secure_tools,
    atp_protected_task,
    ATPClient
)

# Initialize ATP client
atp = ATPClient(base_url="https://atp.protocol")

# 1. Register agent with ATP identity
agent_meta = register_agent_with_atp(
    atp_client=atp,
    name="writer",
    role="content_writer",
    trust_level="verified"
)

# 2. Wrap tools with ATP security
raw_tools = [search_tool, write_tool, file_tool]
secure_tools_list = secure_tools(raw_tools, atp)

# 3. Create OpenClaw agent with ATP
writer = ReActToolCallingOpenClawAgent(
    name="writer",
    tools=secure_tools_list,
    metadata={"atp": agent_meta}
)

# 4. Create ATP-protected tasks
@atp_protected_task(
    required_trust=0.8,
    policy="finance_high_risk",
    data_classification="sensitive"
)
async def execute_trade():
    # Task implementation
    pass

Advanced Usage

from openclaw import OpenClaw
from openclaw.tasks import SimpleTask
from openclaw_atp import (
    validate_crew_with_atp,
    ATPPolicyProfile,
    ATPGraphValidator
)

# Create crew with multiple agents
crew = OpenClaw()
crew.add_agent(writer, [search_tool, write_tool])
crew.add_agent(trader, [market_tool, trade_tool])
crew.add_agent(reviewer, [read_tool, approve_tool])

# Define ATP policies
policy = ATPPolicyProfile(
    name="finance_workflow",
    inter_agent_rules={
        ("writer", "trader"): {"allowed": False},
        ("trader", "reviewer"): {"allowed": True, "data_types": ["trade_request"]}
    },
    workflow_constraints={
        "max_chain_depth": 5,
        "allow_cycles": False,
        "trust_threshold": 0.85
    }
)

# Validate crew graph with ATP before running
validator = ATPGraphValidator(atp, policy)
validation_result = validator.validate_crew(crew)

if not validation_result.is_valid:
    raise SecurityError(f"ATP validation failed: {validation_result.errors}")

# Run crew with ATP protection
crew.run()

📋 Security Profiles

ATP includes built-in security profiles that control what agents can do. Profiles are enforced per-tool-call via evaluateActionWithProfile.

Built-in Profiles

| Profile | Shell | Filesystem | Network | Best For | | --- | --- | --- | --- | --- | | safe-default | Blocked | Read-only | Internal only | Most agents | | dev-mode | Allowed | Read + Write | All domains | Local dev | | enterprise-locked | Blocked | Approved paths | Internal corp | Production | | openclaw-sandbox | Blocked (allowlist: ls, cat, echo) | Sandbox paths | Internal + partners | OpenClaw agents |

Profile-Based Tool Wrapping (TypeScript)

Every tool call goes through the profile before executing:

import { wrapSkillWithAtp, enforceAtpPoliciesForClawSession } from '@atpdevelopment/openclaw-atp';
import { ATPClient } from 'atp-sdk';

const atp = new ATPClient({ baseUrl: 'https://api.atp.dev', profileId: 'openclaw-sandbox' });

// Map each tool to an ATP action type
const secureShell = wrapSkillWithAtp(rawShellTool, atp, { actionType: 'shell' });
const secureFs    = wrapSkillWithAtp(rawFsTool,    atp, { actionType: 'filesystem' });
const secureHttp  = wrapSkillWithAtp(rawHttpTool,  atp, { actionType: 'network' });
const secureCreds = wrapSkillWithAtp(rawCredsTool, atp, { actionType: 'credentials' });
const secureMsg   = wrapSkillWithAtp(rawMsgTool,   atp, { actionType: 'messaging' });

// Register secure tools instead of raw tools in your OpenClaw config
// ATP now decides per call: allow / deny / require_approval

Session Enforcement with Profiles

// Evaluate session-level policies with a profile
const result = await enforceAtpPoliciesForClawSession(
  { state: 'executing', agentDid: agent.did },
  atp,
  { profileId: 'openclaw-sandbox' }
);

console.log(result.allowedTools);     // ["filesystem", "network"] (if profile allows)
console.log(result.forbiddenTools);   // ["shell", ...]
console.log(result.requiresApproval); // ["credentials", "messaging"]

OpenClaw Sandbox State Behavior

| State | Behavior | | --- | --- | | planning | No shell, no file writes, no outbound network. Analysis and reading only. | | executing | Filesystem and network allowed. Shell only via allowlisted commands with approval. Credentials gated. | | communicating | Internal messaging allowed. External send requires approval. | | completed | Read-only: inspect logs/results, no further writes or network calls. |

Configuration Profiles (Python)

from openclaw_atp import ATPConfigProfile

# Strict development profile (safe defaults)
dev_profile = ATPConfigProfile.strict_dev()

# Production finance profile
finance_profile = ATPConfigProfile.production_finance(
    min_trust=0.95,
    require_mfa=True,
    audit_level="full"
)

# PII-heavy workflow profile
pii_profile = ATPConfigProfile.pii_workflow(
    data_encryption=True,
    retention_days=90,
    compliance=["GDPR", "CCPA"]
)

🔧 Integration Points

1. Agent Registration

Every OpenClaw agent gets:

• Quantum-safe DID (Decentralized Identifier)
• Ed25519 + Dilithium key pair
• Initial trust score (0.0 - 1.0)
• Policy profile assignment

2. Tool Call Interception

ATP intercepts all tool calls to:

• Evaluate security profile (evaluateActionWithProfile) for the action type and session state
• Verify agent authentication
• Check policy permissions
• Log actions for audit
• Update trust scores
• Block unauthorized access (deny) or require human approval (require_approval)

3. Task Security Metadata

Attach to any SimpleTask:

• required_trust: Minimum trust score
• policy: Required policy set
• data_classification: PII, financial, public
• sensitivity_level: low, medium, high, critical

4. Graph Validation

Before crew.run():

• Validate agent-to-agent connections
• Check data flow permissions
• Enforce depth/fan-out limits
• Detect policy violations

5. Observability → Trust Engine

Stream from Lunary:

• Error rates per agent
• Tool misuse patterns
• Latency anomalies
• Call volume spikes

ATP automatically:

• Adjusts trust scores
• Triggers workflows (alerts, blocks)
• Updates access policies

6. External Service Protection

ATP-managed connectors for:

• HTTP APIs: Allow-lists, DLP checks
• Databases: Query validation, row-level security
• File Systems: Path restrictions, content scanning
• Secrets: Short-lived, scoped credentials

📊 Monitoring & Metrics

from openclaw_atp import ATPMonitor

monitor = ATPMonitor(atp)

# Real-time trust scores
trust_scores = monitor.get_agent_trust_scores()

# Policy violations
violations = monitor.get_policy_violations(since="24h")

# Tool usage stats
stats = monitor.get_tool_usage_stats(agent_name="trader")

# Security events
events = monitor.get_security_events(severity="high")

🧪 Testing

# Test ATP integration
python -m openclaw_atp.test

# Validate specific crew
from openclaw_atp import test_crew_security
test_crew_security(crew, atp_client)

📚 API Reference

Core Functions

• registerClawWithAtp(atpClient, config) - Register an OpenClaw agent; returns DID, keys, and trust score
• wrapSkillWithAtp(skill, atpClient, options) - Secure a skill with auth, profile evaluation, rate-limit, and audit. Pass actionType to enable profile-based gating.
• enforceAtpPoliciesForClawSession(ctx, atpClient, options) - Evaluate tool permissions for a session state. Pass profileId to use profile-based enforcement.
• secureTools(tools, atpClient, config) - Batch-wrap multiple tools at once
• register_agent_with_atp(client, name, role, trust_level) - Register agent identity (Python)
• secure_tools(tools, client) - Wrap tools with ATP security (Python)
• atp_protected_task(required_trust, policy, data_classification) - Decorator for tasks (Python)
• validate_crew_with_atp(crew, client, policy) - Validate agent graph

Classes

• ATPOpenClawAgent - Base agent class with ATP identity
• ATPToolWrapper - Security wrapper for tools
• ATPGraphValidator - Graph validation engine
• ATPPolicyProfile - Policy configuration
• ATPMonitor - Monitoring and metrics
• ATPLunaryExporter - Lunary → ATP bridge

🚀 Quick Agent Setup

The fastest way to get started with an OpenClaw agent is:

npx create-atp-agent my-openclaw-agent
cd my-openclaw-agent
npm install
npm start

The CLI scaffolds an ESM project (Node 18+), then opens an embedded onboarding UI at http://127.0.0.1:3456 by default (--no-dashboard to skip). In the wizard, choose OpenClaw as the runtime and openclaw-sandbox (or your profile) for security. Agents run in standalone mode without backend services until you connect ATP services.

🔐 Security Best Practices

1. Always validate crew graphs before production runs
2. Use strict profiles for development and testing
3. Set appropriate trust thresholds per task sensitivity
4. Enable full audit logging for compliance requirements
5. Rotate credentials via ATP secret management
6. Monitor trust score changes and investigate drops
7. Test policy violations before deploying workflows

🆘 Support

• Documentation: https://github.com/agent-trust-protocol/atp-core/tree/main/docs/openclaw
• Issues: https://github.com/agent-trust-protocol/core/issues
• Discord: https://discord.gg/atp
• Email: [email protected]

🚢 Releasing

Publishing is automated via the npm-publish workflow. Both atp-sdk and @atpdevelopment/openclaw-atp are published together on every version tag.

# Bump version in package.json, then:
git tag v1.0.1
git push origin v1.0.1

The workflow builds, tests, and publishes automatically. For a dry run (no actual publish), use Actions → Publish to npm → Run workflow with dry_run enabled.

📄 License

Apache-2.0 - see LICENSE

🙏 Credits

Built on top of:

• OpenClaw - Multi-agent orchestration
• ATP SDK - Agent Trust Protocol
• LangChain - LLM framework

Made with 🔐 by the Agent Trust Protocol™ Team