{"skill":{"slug":"openclaw-audit-trail","displayName":"openclaw audit trail","summary":"The Immutable Black Box for AI Decisions - Track, audit, and verify AI agent decisions with cryptographic guarantees","description":"---\nname: openclaw-audit-trail\ndisplay_name: Agent Audit Trail\nversion: 1.0.0\nauthor: ZhenStaff\ncategory: ai-tools\nlicense: MIT-0\ndescription: The Immutable Black Box for AI Decisions - Track, audit, and verify AI agent decisions with cryptographic guarantees\ntags: [ai-audit, agent-tracking, decision-trail, immutable-log, ai-transparency, audit-trail, cryptographic-verification, ai-governance]\nrepository: https://github.com/ZhenRobotics/openclaw-audit-trail\nhomepage: https://github.com/ZhenRobotics/openclaw-audit-trail\ndocumentation: https://github.com/ZhenRobotics/openclaw-audit-trail#readme\n---\n\n# Agent Audit Trail\n\n**AI决策的不可篡改黑匣子**\n**The Immutable Black Box for AI Decisions**\n\n追踪、审计和验证AI Agent决策，提供密码学保证。\nTrack, audit, and verify AI agent decisions with cryptographic guarantees.\n\n---\n\n## 🎯 概述 / Overview\n\nAgent Audit Trail 是一个为AI决策提供密码学保证的审计追踪工具，可以记录、验证和审计AI Agent的每一个决策过程。\n\nAgent Audit Trail is an audit trail system that provides cryptographic guarantees for AI decisions, enabling recording, verification, and auditing of every AI Agent decision process.\n\n### 核心特性 / Core Features\n\n- 🔗 **密码学链条** - SHA-256哈希链确保不可篡改 / Cryptographic chain with SHA-256 hashing ensures immutability\n- 📝 **完整记录** - 捕获输入、推理、输出全过程 / Complete recording of input, reasoning, and output\n- ✅ **完整性验证** - 自动检测任何篡改行为 / Integrity verification detects any tampering\n- 📊 **多格式导出** - JSON、CSV、HTML、Markdown / Multiple export formats\n- ⚡ **CLI和API** - 命令行和编程接口双重支持 / Both CLI and programmatic interfaces\n- 🔐 **本地存储** - 所有数据存储在本地，无外部依赖 / All data stored locally, no external dependencies\n\n---\n\n## 📦 安装 / Installation\n\n### NPM (推荐 / Recommended)\n\n```bash\n# 全局安装 / Install globally\nnpm install -g openclaw-audit-trail\n\n# 或项目依赖 / Or as project dependency\nnpm install openclaw-audit-trail\n```\n\n### ClawHub\n\n```bash\nclawhub install openclaw-audit-trail\n```\n\n### 从源码 / From Source\n\n```bash\ngit clone https://github.com/ZhenRobotics/openclaw-audit-trail.git\ncd openclaw-audit-trail\nnpm install\nnpm link\n```\n\n---\n\n## 🚀 快速开始 / Quick Start\n\n### 初始化 / Initialize\n\n```bash\n# 初始化审计追踪 / Initialize audit trail\naudit-trail init --agent-id my-ai-agent --version 1.0.0\n\n# 或使用别名 / Or use alias\naat init --agent-id my-agent\n```\n\n### 记录决策 / Record Decisions\n\n```bash\n# 简单记录 / Simple recording\naudit-trail record \\\n  --prompt \"Should I approve this loan?\" \\\n  --decision \"Approved\" \\\n  --reasoning \"Credit score 750, income verified, debt ratio acceptable\"\n\n# 带更多细节 / With more details\naudit-trail record \\\n  --prompt \"Classify this image\" \\\n  --decision \"cat\" \\\n  --reasoning \"Detected feline features with 95% confidence\" \\\n  --agent-id vision-classifier\n```\n\n### 验证完整性 / Verify Integrity\n\n```bash\n# 验证审计链 / Verify audit chain\naudit-trail verify\n\n# 预期输出 / Expected output:\n# ✓ Chain integrity intact\n#   Total entries: 42\n#   Verified: 42/42\n```\n\n### 列出决策 / List Decisions\n\n```bash\n# 列出最近的决策 / List recent decisions\naudit-trail list --limit 10\n\n# 按时间过滤 / Filter by time\naudit-trail list --start 1700000000 --end 1700100000\n```\n\n### 导出审计追踪 / Export Audit Trail\n\n```bash\n# 导出为JSON / Export as JSON\naudit-trail export --output audit-report.json --format json\n\n# 导出为HTML报告 / Export as HTML report\naudit-trail export --output audit-report.html --format html --include-reasoning\n\n# 导出为CSV / Export as CSV\naudit-trail export --output audit-data.csv --format csv\n```\n\n---\n\n## 💻 编程使用 / Programmatic Usage\n\n### TypeScript/JavaScript API\n\n```typescript\nimport { AgentAuditTrail } from 'openclaw-audit-trail';\n\n// 初始化 / Initialize\nconst trail = new AgentAuditTrail({\n  agentId: 'my-ai-agent',\n  agentVersion: '1.0.0',\n  storagePath: './audit-data'\n});\n\nawait trail.initialize();\n\n// 记录决策 / Record a decision\nconst entry = await trail.recordDecision(\n  // 输入 / Input\n  {\n    prompt: 'Should I send this email?',\n    context: { urgency: 'high', recipient: 'user@example.com' }\n  },\n  // 推理 / Reasoning\n  {\n    steps: [\n      {\n        step: 1,\n        action: 'analyze',\n        thought: 'Checking email content for sensitive information',\n        timestamp: Date.now()\n      },\n      {\n        step: 2,\n        action: 'decide',\n        thought: 'No sensitive data detected, urgency is high',\n        timestamp: Date.now()\n      }\n    ],\n    model: 'gpt-4',\n    temperature: 0.7\n  },\n  // 输出 / Output\n  {\n    decision: 'send',\n    confidence: 0.95,\n    alternatives: [\n      { decision: 'delay', confidence: 0.05, reasoning: 'Wait for manual review' }\n    ]\n  },\n  // 执行时间 / Execution time\n  1250\n);\n\nconsole.log(`Decision recorded: ${entry.id}`);\n\n// 验证完整性 / Verify integrity\nconst verification = trail.verify();\nif (!verification.valid) {\n  console.error('Chain compromised!', verification.errors);\n}\n\n// 导出 / Export\nconst htmlReport = await trail.export({\n  format: 'html',\n  includeMetadata: true,\n  includeReasoning: true\n});\n\nawait trail.close();\n```\n\n### 简化版本 / Simplified Version\n\n```typescript\n// 用于简单用例 / For simple use cases\nconst entry = await trail.recordSimple(\n  'What is 2+2?',\n  '4',\n  'Basic arithmetic calculation',\n  50 // execution time in ms\n);\n```\n\n---\n\n## 🎯 使用场景 / Use Cases\n\n### 1. AI安全与合规 / AI Safety & Compliance\n\n**场景 / Scenario**: 金融机构使用AI进行贷款审批 / Financial institution using AI for loan approvals\n\n```typescript\nawait trail.recordDecision(\n  {\n    prompt: 'Approve loan application #12345',\n    context: { creditScore: 720, income: 80000, debtRatio: 0.3 }\n  },\n  {\n    steps: [\n      { step: 1, action: 'evaluate', thought: 'Checking credit score threshold' },\n      { step: 2, action: 'analyze', thought: 'Debt-to-income ratio acceptable' },\n      { step: 3, action: 'decide', thought: 'All criteria met for approval' }\n    ]\n  },\n  {\n    decision: 'approved',\n    confidence: 0.92,\n    metadata: { loanAmount: 50000, interestRate: 0.045 }\n  },\n  2300\n);\n```\n\n**好处 / Benefits**: 完整的监管合规审计追踪，能够向客户解释决策 / Full audit trail for regulatory compliance, ability to explain decisions to customers\n\n### 2. 自主系统 / Autonomous Systems\n\n**场景 / Scenario**: 自动驾驶汽车决策日志 / Self-driving car decision logging\n\n```typescript\nawait trail.recordDecision(\n  {\n    prompt: 'Pedestrian detected crossing street',\n    context: { speed: 35, distance: 50, weather: 'clear' }\n  },\n  {\n    steps: [\n      { step: 1, action: 'detect', thought: 'Pedestrian at 50m ahead' },\n      { step: 2, action: 'calculate', thought: 'Stopping distance: 35m' },\n      { step: 3, action: 'decide', thought: 'Initiate emergency brake' }\n    ]\n  },\n  { decision: 'emergency_brake', confidence: 1.0 },\n  120\n);\n```\n\n**好处 / Benefits**: 事故调查黑匣子记录，安全分析 / Black box recording for accident investigation, safety analysis\n\n### 3. 内容审核 / Content Moderation\n\n**场景 / Scenario**: AI审核用户生成内容 / AI moderating user-generated content\n\n```typescript\nawait trail.recordDecision(\n  {\n    prompt: 'Moderate comment: \"...\"',\n    context: { userId: 'user123', platform: 'forum' }\n  },\n  {\n    steps: [\n      { step: 1, action: 'scan', thought: 'Checking for hate speech patterns' },\n      { step: 2, action: 'analyze', thought: 'Detected potential violation' }\n    ]\n  },\n  {\n    decision: 'flag_for_review',\n    confidence: 0.75,\n    metadata: { violationType: 'potential_hate_speech' }\n  },\n  850\n);\n```\n\n**好处 / Benefits**: 用户透明度，政策执行的证据 / Transparency for users, evidence for policy enforcement\n\n### 4. 研究与开发 / Research & Development\n\n**场景 / Scenario**: 调试AI Agent行为 / Debugging AI agent behavior\n\n```bash\n# 查找所有失败的决策 / Find all failed decisions\naudit-trail list --limit 100 | grep \"failed\"\n\n# 导出上周的决策用于分析 / Export last week's decisions for analysis\naudit-trail export --output weekly-decisions.json \\\n  --start $(date -d '7 days ago' +%s) \\\n  --format json --include-reasoning\n\n# 验证未发生篡改 / Verify no tampering occurred\naudit-trail verify\n```\n\n**好处 / Benefits**: 可重现的实验，决策模式分析 / Reproducible experiments, decision pattern analysis\n\n---\n\n## 🏗️ 架构 / Architecture\n\n```\n┌─────────────────────────────────────────┐\n│           CLI / API Layer               │\n│   (User Interface & Integration)        │\n└──────────────┬──────────────────────────┘\n               │\n┌──────────────▼──────────────────────────┐\n│      AgentAuditTrail (Main API)         │\n│  - Record decisions                     │\n│  - Query & export                       │\n│  - Verification                         │\n└──────────────┬──────────────────────────┘\n               │\n    ┌──────────┴──────────┐\n    │                     │\n┌───▼──────────┐  ┌──────▼─────────┐\n│ AuditChain   │  │ Storage Layer  │\n│              │  │                │\n│ - Hash chain │  │ - JSON files   │\n│ - Integrity  │  │ - SQLite       │\n│ - Verify     │  │ - PostgreSQL   │\n└──────────────┘  └────────────────┘\n```\n\n---\n\n## 🔐 安全性 / Security\n\n### 密码学保证 / Cryptographic Guarantees\n\n- **SHA-256哈希** - 工业标准加密哈希 / Industry-standard cryptographic hash\n- **链式关联** - 每个条目引用前一个哈希 / Each entry references previous hash\n- **篡改检测** - 任何修改立即可检测 / Any modification is immediately detectable\n- **创世哈希** - 唯一链标识符 / Unique chain identifier\n\n### 数据隐私 / Data Privacy\n\n- ✅ **本地存储** - 所有数据存储在本地文件系统 / All data stored locally\n- ✅ **无外部传输** - 不连接任何外部服务器 / No external server connections\n- ✅ **用户控制** - 完全由用户控制数据 / User has full control of data\n- ✅ **可删除** - 用户可随时删除审计数据 / Users can delete audit data anytime\n\n---\n\n## 📊 技术规格 / Technical Specifications\n\n- **语言 / Language**: TypeScript\n- **Node.js版本 / Version**: >= 18.0.0\n- **加密算法 / Crypto**: SHA-256\n- **存储格式 / Storage**: JSON (SQLite, PostgreSQL planned)\n- **导出格式 / Export**: JSON, CSV, HTML, Markdown\n- **测试覆盖 / Test Coverage**: 100% (25/25 tests passing)\n\n---\n\n## 📝 CLI 命令参考 / CLI Command Reference\n\n### `init` - 初始化 / Initialize\n```bash\naudit-trail init --agent-id <id> [--version <ver>] [--storage-path <path>]\n```\n\n### `record` - 记录决策 / Record Decision\n```bash\naudit-trail record \\\n  --prompt <text> \\\n  --decision <text> \\\n  --reasoning <text> \\\n  [--agent-id <id>]\n```\n\n### `verify` - 验证完整性 / Verify Integrity\n```bash\naudit-trail verify [--agent-id <id>]\n```\n\n### `list` - 列出决策 / List Decisions\n```bash\naudit-trail list [--limit <n>] [--start <timestamp>] [--end <timestamp>]\n```\n\n### `export` - 导出数据 / Export Data\n```bash\naudit-trail export \\\n  --output <file> \\\n  --format <json|csv|html|markdown> \\\n  [--include-reasoning]\n```\n\n### `info` - 显示信息 / Show Information\n```bash\naudit-trail info [--agent-id <id>]\n```\n\n---\n\n## 🗺️ 路线图 / Roadmap\n\n### v1.1 (即将推出 / Coming Soon)\n- [ ] SQLite 存储后端 / SQLite storage backend\n- [ ] PostgreSQL 存储后端 / PostgreSQL storage backend\n- [ ] 数字签名支持 / Digital signature support\n- [ ] 压缩支持 / Compression support\n- [ ] Web 仪表板 / Web dashboard\n\n### v1.2 (未来 / Future)\n- [ ] 区块链集成 / Blockchain integration\n- [ ] 实时流API / Real-time streaming API\n- [ ] 高级分析 / Advanced analytics\n- [ ] 多Agent支持 / Multi-agent support\n\n---\n\n## 🐛 常见问题 / FAQ\n\n### Q: 如何确保审计数据不被篡改？ / How to ensure audit data cannot be tampered with?\n\n**A**: 使用密码学哈希链。每个条目包含前一条目的SHA-256哈希，任何修改都会破坏链条。定期运行 `audit-trail verify` 检测篡改。\n\n**A**: Use cryptographic hash chain. Each entry contains the SHA-256 hash of the previous entry. Any modification breaks the chain. Run `audit-trail verify` regularly to detect tampering.\n\n### Q: 审计数据存储在哪里？ / Where is audit data stored?\n\n**A**: 默认存储在 `./audit-data` 目录。可通过 `--storage-path` 参数或环境变量 `STORAGE_PATH` 自定义。\n\n**A**: Stored in `./audit-data` directory by default. Customizable via `--storage-path` parameter or `STORAGE_PATH` environment variable.\n\n### Q: 支持分布式审计吗？ / Does it support distributed auditing?\n\n**A**: 当前版本(v1.0.0)支持本地文件存储。未来版本将支持SQLite、PostgreSQL和区块链集成。\n\n**A**: Current version (v1.0.0) supports local file storage. Future versions will support SQLite, PostgreSQL, and blockchain integration.\n\n---\n\n## 📞 支持 / Support\n\n- **GitHub Issues**: https://github.com/ZhenRobotics/openclaw-audit-trail/issues\n- **文档 / Documentation**: https://github.com/ZhenRobotics/openclaw-audit-trail#readme\n- **Email**: support@zhenrobotics.com\n\n---\n\n## 📄 许可证 / License\n\nMIT License - 查看 [LICENSE](https://github.com/ZhenRobotics/openclaw-audit-trail/blob/main/LICENSE) 文件了解详情。\n\nMIT License - see [LICENSE](https://github.com/ZhenRobotics/openclaw-audit-trail/blob/main/LICENSE) file for details.\n\n---\n\n**以透明为理念构建。让AI决策可审计、可信任。**\n**Built with transparency in mind. Make AI decisions auditable and trustworthy.**\n\n🔗 **GitHub**: https://github.com/ZhenRobotics/openclaw-audit-trail\n📦 **NPM**: https://www.npmjs.com/package/openclaw-audit-trail\n🦅 **ClawHub**: https://clawhub.ai/ZhenStaff/openclaw-audit-trail\n\n---\n\n**版本 / Version**: 1.0.0\n**最后更新 / Last Updated**: 2026-03-13\n**状态 / Status**: ✅ Production Ready\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":609,"installsAllTime":23,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1773403786626,"updatedAt":1778491885889},"latestVersion":{"version":"1.0.0","createdAt":1773403786626,"changelog":"**Initial public release with major cleanup and refocus:**\n\n- Removed setup scripts, documentation files, and legacy usage examples for a leaner distribution.\n- Replaced detailed technical docs with a feature-focused README (bilingual: Chinese/English), highlighting cryptographic audit trail capabilities.\n- All prior shell and Python example code, compliance mapping tables, and deep integration/formatting instructions have been removed.\n- Now emphasizes installation, core features, CLI/API usage, and practical use cases in a more accessible overview.\n- Prepared for new Node.js/NPM-based workflows and OpenClaw ecosystem integration.","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"zhenstaff","userId":"s173q0k18pjbw86jqbmsmgkz7h83h3vm","displayName":"Justin Liu","image":"https://avatars.githubusercontent.com/u/34432727?v=4"},"moderation":null}