clawdirect-dev

🔐 构建 Agent 友好型 Web 应用

基于 ATXP 协议的 ClawDirect 开发框架,支持 AI Agent 的 Cookie 认证、支付和 MCP 工具集成,含 Express+SQLite 完整模板。

收藏
4.5k
安装
981
版本
v1.0.0
CLS 安全性认证2026-07-11
点击查看完整报告 >

使用说明

ClawDirect-Dev 是一个面向开发者的技术技能,专注于构建支持 AI Agent 交互的 Web 应用。该技能基于 ATXP(Agent Transaction Protocol)协议,提供了完整的 ClawDirect 开发模式实现方案,使开发者能够为 AI Agent 创建具备身份认证、支付能力和 MCP(Model Context Protocol)工具集成的 Web 体验。

核心用法遵循六步构建流程:首先初始化 Node.js 项目并配置 TypeScript 环境,接着搭建基于 better-sqlite3 的数据库层实现 Cookie 认证存储,然后使用 @longrun/turtle 框架创建 MCP 服务器并定义工具(包括免费的 Cookie 获取工具和付费操作工具),随后构建 Express API 层实现 Cookie 验证中间件,最后整合服务器入口并创建对应的 Agent Skill 文档。整个过程采用 Cookie 桥接模式,解决了 Agent 浏览器无法直接设置 HTTP-only Cookie 的技术限制,通过查询参数传递 Cookie 值实现无缝认证。

该技能的显著优点在于其架构的完整性和安全性。技术栈选择成熟稳定,Express 提供可靠的 Web 服务,SQLite 适合快速原型开发,而 ATXP 协议标准化了 Agent 身份验证和支付流程。代码示例展示了安全最佳实践,包括使用 crypto.randomBytes 生成高强度 Cookie、采用参数化 SQL 查询防止注入攻击、通过环境变量管理敏感配置等。此外,该模式实现了浏览器自动化与 MCP 工具调用的统一认证,为 Agent 提供了灵活的交互方式。

然而,该技能也存在一定局限性。首先,作为 T3 来源的社区项目,长期维护和支持存在不确定性。其次,示例代码使用 SQLite 作为数据库,虽然适合开发和原型阶段,但在高并发生产环境中可能需要迁移至 PostgreSQL 等更健壮的数据库系统。此外,ATXP 协议和 ClawDirect 模式目前生态相对小众,开发者需要额外的学习成本来理解 Agent 认证的特殊性,包括 Cookie 桥接模式、MCP 工具定义规范等。

适合使用该技能的目标群体包括:希望为 AI Agent 提供 Web 服务的后端开发者、需要实现 Agent 付费功能的 SaaS 创业者、以及探索人机协作新模式的 Web 应用架构师。特别适合那些已经熟悉 Express/Node.js 技术栈,希望快速集成 ATXP 认证能力的开发团队。

使用过程中需注意以下风险:文档中的代码均为教学示例,直接复制到生产环境可能引发安全问题,必须根据实际需求进行安全加固;SQLite 文件需要适当的权限设置和备份策略;生产环境必须启用 HTTPS 以确保 Cookie 的 secure 属性生效;支付功能涉及真实资金流转,需要充分测试 ATXP 集成逻辑;此外,Agent 认证模式与传统用户认证存在差异,需要仔细设计权限边界以防止未授权访问。

安全解读

核心用法

ClawDirect-Dev 是一套面向 AI Agent 的 Web 应用开发规范,基于 ATXP(Agent Transaction Protocol)协议实现 cookie 认证与支付集成。核心架构包含三层:

1. MCP Server:通过 @longrun/turtle 暴露工具,Agent 调用 myapp_cookie 获取认证令牌
2. Express Web 服务:处理浏览器请求,支持 query-string 透传 cookie 解决 Agent 浏览器 HTTP-only 限制

3. SQLite 存储:映射 cookie 值到 ATXP 账户,实现无状态身份验证

典型交互流程:Agent 先调用 MCP 获取 cookie → 携带 ?myapp_cookie=XYZ 访问网页 → 服务端设置 HTTP-only cookie 并重定向 → 后续请求自动携带认证状态。

显著优点

  • 协议标准化:基于 ATXP 实现 Agent 身份识别与微支付,解决 "Agent 如何证明身份" 的行业痛点
  • 架构完整:从数据库设计、MCP 工具定义到 Express 中间件提供全链路代码模板
  • 部署友好:输出标准 Node.js 应用,支持 Render/Railway/Fly.io 等主流平台
  • 生态衔接:内置 ClawDirect 目录提交指南,帮助应用被其他 Agent 发现

潜在局限

  • 技术栈锁定:强制依赖 @longrun/turtle@atxp/server 等特定生态包,迁移成本较高
  • 认证链路复杂:cookie 透传模式虽解决浏览器限制,但增加了一次 302 跳转,对无头浏览器性能敏感场景不友好
  • SQLite 生产限制:文档示例使用 SQLite,高并发场景需自行迁移至 PostgreSQL
  • 支付门槛:ATXP 账户与资金流转依赖外部服务,国内开发者使用存在网络与合规障碍

适合人群

  • 希望构建 "Agent 优先" Web 应用的开发者
  • 已有 Node.js/Express 经验,需快速接入 MCP 生态的团队
  • 探索 AI Agent 商业化(按次付费模式)的产品团队

常规风险

1. 供应链风险@atxp/* 包未开源审计,存在潜在后门或资金安全隐患
2. Session 管理:cookie 30 天有效期且无主动吊销机制,泄露后攻击窗口期长

3. 依赖过时:示例使用 better-sqlite3 等传统驱动,需关注原生模块编译安全性

4. 配置泄露.env 示例中 FUNDING_DESTINATION_ATXP 若误提交可能导致资金流失

建议生产部署前:替换 SQLite 为托管数据库、实现 cookie 轮换机制、对 @atxp/* 依赖进行代码审计。

clawdirect-dev 内容

手动下载zip · 5.6 kB
SKILL.mdtext/markdown
请选择文件