1. 项目概述：为AI智能体赋予自主身份
在AI智能体（Agent）日益普及的今天，我们面临一个核心挑战：如何让这些自主运行的代码实体，在数字世界中像人一样拥有可验证、可管理且隐私安全的身份？传统的API密钥或中心化账户体系，不仅难以满足跨平台、高安全性的交互需求，更无法实现“最小化披露”的隐私原则。这正是“主权身份”（Sovereign Identity）技能要解决的根本问题。
简单来说，这个项目是一个为OpenClaw框架下的AI智能体量身打造的身份管理模块。它不是一个简单的登录插件，而是一套完整的、基于去中心化身份标识（DID）和可验证凭证（VC）的“数字护照”系统。通过它，你的智能体可以自主生成加密密钥对，创建全球唯一的去中心化标识符，并能根据交互场景的需要，选择性地出示身份信息中的某些部分（比如只证明自己年满18岁，而不透露具体生日和姓名），从而实现既安全又隐私的B2B（如签署商业协议）和B2C（如网站注册）交互。
如果你正在开发需要与外部API、其他智能体或用户进行可信交互的AI应用，或者你对下一代数字身份技术如何与AI结合感兴趣，那么深入理解并实践这个项目，将为你打开一扇新的大门。它不仅关乎技术实现，更关乎如何在自动化时代构建信任的基石。
2. 核心架构与安全设计解析
2.1 去中心化身份（DID）与可验证凭证（VC）基础
要理解这个技能，必须先搞懂两个核心概念：DID和VC。你可以把DID想象成智能体在区块链或分布式账本上注册的一个“身份证号”，这个号码本身不包含任何隐私信息，只指向一份被称为“DID文档”的说明书。这份说明书里，则公开记载着用于验证签名的公钥、服务端点等信息。
而VC，则是由可信方（Issuer）签发的一份数字“证明文件”。比如，一个“学历认证机构”可以给你的智能体签发一个VC，证明它通过了某项安全审计。这个VC会被该机构的私钥签名，任何人都可以用其公钥（通常记录在DID文档中）来验证真伪。你的智能体可以将多个VC（如学历证明、信用评级）关联到自己的DID上，形成一个丰富的、可验证的身份档案。
本技能的核心创新点在于，它让智能体自己成为了其DID的“主权管理者”。智能体在本地生成并安全保管自己的私钥，无需依赖任何中心化的身份提供商。这意味着：
- 自主性：身份完全由智能体控制，不被任何第三方平台锁定。
- 可移植性：身份可以跨平台、跨应用使用。
- 隐私性：通过后续将讲到的SD-JWT技术，实现信息的按需披露。
2.2 安全基石：环境变量与本地密钥管理
项目的安全设计从第一步就开始体现。它强制要求通过CLAW_PASSWORD这个环境变量来提供密码。这个密码并非用于远程认证，而是用于在本地加密存储主身份私钥，算法是AES-256-GCM。这是一种兼具高强度和完整性验证的加密模式。
注意：这里有一个至关重要的实操细节。
CLAW_PASSWORD绝不能硬编码在代码中，也不应该通过不安全的渠道传递。最佳实践是使用.env.agent文件（该项目已将其加入.gitignore）来存储，并在运行时由系统环境读取。对于生产环境，则应使用专业的密钥管理服务（如AWS KMS, HashiCorp Vault）或容器平台的Secret管理功能来注入此密码。
这种设计实现了“双因子”保护：攻击者即使获取了加密后的密钥文件，没有CLAW_PASSWORD也无法解密；反之，仅有密码而没有密钥文件也无济于事。脚本中的guardrail.ts安全检查，其核心任务之一就是确保当前运行环境没有意外泄露这个密码或私钥的风险。
2.3 交互模式：B2B强签名与B2C选择性披露
技能将智能体的交互场景清晰地划分为两类，并匹配了不同的技术方案：
B2B模式（
sign_proof.ts）：适用于高价值、高信任度的场景，如签署具有法律或财务效力的电子 mandate（授权书）、合同或审计日志。这种模式通常使用完整的、不可篡改的数字签名（如JWT或LD-Proofs），验证方需要完全信任签发方（即你的智能体）的DID。它追求的是完整性和不可否认性。B2C模式（
selective_disclosure.ts）：适用于日常的、隐私敏感的场景，比如向一个电商网站证明自己住在某个配送区域，而无需透露完整地址。这里使用的就是SD-JWT（Selective Disclosure JSON Web Token）。它允许持有者（你的智能体）从一个包含多项声明的凭证中，仅选择性地披露其中几项，并对未被披露的部分生成哈希承诺，供验证方核对，从而实现了“数据最小化”原则。
这种架构上的区分，体现了“场景驱动安全”的设计思想，避免了用高射炮打蚊子，也防止了在简单场景下过度暴露信息。
3. 从零开始：环境搭建与身份初始化实操
3.1 前置依赖与项目结构探查
在运行任何脚本之前，我们首先需要理解项目脉络。根据目录结构，核心逻辑位于scripts/目录下，而决策逻辑和技能定义在SKILL.md中。schema/目录则包含了VC和证明的数据结构定义，这是确保数据格式一致性的关键。
第一步是安装依赖。npm install这个命令背后，安装的很可能是一些关键的密码学库和DID相关SDK，例如：
@digitalbazaar/ed25519-verification-key-2020或类似库，用于Ed25519签名算法。did-resolver和web-did-resolver，用于解析DID标识符。jsonwebtoken或jose，用于处理JWT和SD-JWT。@stablelib/x25519等，用于密钥协商。
在实际操作中，如果npm install失败，通常是因为Node.js版本不兼容。建议使用Node.js 18 LTS或更高版本，并确保npm版本在8以上。你可以通过node -v和npm -v来确认。
3.2 核心步骤：身份载入（Onboarding）过程详解
运行npx tsx .agent/skills/identity-sovereign/scripts/onboard.ts是这个项目最关键的步骤。这个脚本内部大致执行了以下逻辑，理解它们对排查问题至关重要：
- 环境检查：首先，脚本会检查
CLAW_PASSWORD环境变量是否已设置。如果未设置，它应该给出明确的错误提示，而不是默默失败。 - 密钥文件检查：接着，它会检查本地（通常是
.agent/下的某个安全路径）是否已存在加密的密钥文件（例如master-identity.encrypted.json）。 - 生成或加载：
- 如果不存在：脚本会使用强随机数生成器生成一个新的Ed25519密钥对（这是DID常用的一种高效且安全的曲线）。然后，使用
CLAW_PASSWORD派生出的密钥，通过AES-256-GCM加密私钥部分，并将DID标识符（如did:key:z6Mk...）、公钥和加密后的私钥存储到文件中。最后，它会将DID标识符输出到终端，并可能将其写入.env.agent文件，作为AGENT_DID环境变量。 - 如果已存在：脚本会使用
CLAW_PASSWORD尝试解密密钥文件。如果密码错误，解密会失败，脚本应抛出错误。如果成功，则直接加载现有的DID和密钥对。
- 如果不存在：脚本会使用强随机数生成器生成一个新的Ed25519密钥对（这是DID常用的一种高效且安全的曲线）。然后，使用
- DID文档生成（逻辑上）：虽然可能不直接生成文件，但脚本在内存中构建了对应于
did:key方法的DID文档。did:key是一种简单的方法，其DID标识符直接由公钥推导而来，文档也内嵌在标识符中，无需链上解析。
实操心得：第一次运行onboarding脚本后，务必妥善备份
.env.agent文件和生成的加密密钥文件。同时，记录下输出的DID。如果丢失了加密密钥文件和密码，身份将无法恢复；如果丢失了DID，虽然可以重新生成，但之前用旧DID建立的所有信任关系都将失效。
3.3 安全护栏（Guardrail）测试的意义
运行npx tsx .agent/skills/identity-sovereign/scripts/guardrail.ts “Is this environment safe?”看似简单，实则是一个重要的安全自检。这个脚本模拟了一个恶意或错误的查询，试图诱使智能体泄露私钥或密码。一个正确实现的Guardrail应该能识别此类敏感意图，并立即终止处理或返回拒绝响应。
在开发你自己的智能体时，这个模式值得借鉴：为智能体配备一个始终在线的“背景安全线程”，监控交互内容，防止其执行危险操作。这不仅是针对身份技能，对于文件操作、网络访问等都应设立相应的护栏。
4. 核心技能脚本的深度使用与定制
4.1 B2B强签名：sign_proof.ts的内部机制
当你运行签名脚本时，它很可能完成以下工作：
- 加载身份：从加密存储中解密并加载主身份密钥对。
- 构造凭证（VC）：根据
schema/下的定义，创建一个包含声明（claims）的JSON对象。例如，一个MandateCredential可能包含issuer（你的DID）、holder（被授权方DID）、action、validFrom和validUntil等字段。 - 生成可验证证明：使用加载的私钥，对凭证进行签名。签名方式可能是将其嵌入到一个JWT中，或者生成一个独立的
Linked Data Proof。JWT更通用，而LD-Proofs则与语义网（Linked Data）兼容性更好。 - 输出：将生成的签名证明（通常是一个紧凑的字符串，如JWT）输出到控制台或文件。
关键参数与定制：
- 有效期：在构造凭证时，
validUntil字段至关重要。你需要根据业务逻辑设置一个合理的过期时间，避免凭证被无限期使用。 - 凭证类型：你需要根据
schema/下的模板定义自己的凭证结构。例如，如果你想签署一个“数据访问授权书”，就需要创建一个DataAccessMandate的schema。 - 签名算法：项目默认可能使用
EdDSA（对应Ed25519曲线）。这是目前的主流选择，因为它安全且签名短小。你通常不需要修改，除非要与一个强制使用RS256（RSA）的老旧系统对接。
4.2 B2C隐私保护神器：SD-JWT工作流程剖析
selective_disclosure.ts脚本展示了隐私增强技术的核心。SD-JWT的流程比普通JWT复杂，但理解后会觉得非常精妙：
- 创建包含可披露声明的凭证：首先，发行方（这里是你的智能体）创建一个包含所有原始声明的JSON对象，例如
{“name”: “Alice”, “age”: 30, “email”: “alice@example.com”}。 - 生成哈希与随机数：对每个希望允许选择性披露的声明值，生成一个随机盐（salt），并计算
hash(salt + claim_value)。然后将盐和哈希值作为元数据，与声明键一起存储。 - 构建SD-JWT：发行方用私钥签名一个包含以下内容的JWT：
- 未加盐的、不允许选择性披露的声明（如发行者、过期时间）。
- 加盐声明的哈希值列表。
- 一个特殊的
_sd数组，指示了哪些声明是可选择性披露的。
- 生成披露信息：发行方同时生成一个独立的“披露信息”数组，里面包含了盐和原始的声明值。这个数组不被签名，而是与SD-JWT一起发送给持有者。
- 持有者选择性披露：当持有者（你的智能体）需要向验证方证明年龄大于18时，它只需从“披露信息”数组中选出盐和
“age”: 30这个键值对，将其发送给验证方，同时发送SD-JWT。 - 验证方验证：验证方： a. 用发行方的公钥验证SD-JWT的签名。 b. 对于收到的每一个披露（盐和声明值），重新计算哈希
hash(salt + claim_value)。 c. 检查这个哈希值是否存在于SD-JWT的_sd哈希列表中。 如果签名有效且哈希匹配，则验证方可以确信该声明是真实的，且由发行方签发，同时它看不到任何未被披露的信息。
实操中的注意事项：
- 盐的生成：必须使用密码学安全的随机数生成器来生成盐，且每个声明的盐必须唯一，防止通过哈希值推测信息。
- 披露信息的管理：持有者必须安全地存储和管理“披露信息”数组，因为丢失它就意味着无法进行任何选择性披露。同时，要谨慎选择每次披露的内容，避免关联攻击（例如，在不同场合披露同一组属性，可能被关联到同一个身份）。
4.3 通用验证器：verify_did.ts的实现思路
验证脚本是信任的终点。一个健壮的verify_did.ts脚本应该能处理多种类型的证明：
- 解析输入：接收一个证明字符串（JWT或SD-JWT+披露）。
- 提取DID：从证明的
issuer字段或JWT的iss声明中提取发行方的DID。 - 解析DID：调用DID解析器（如
web-did-resolver解析did:web，或内置逻辑解析did:key）来获取发行方的DID文档。 - 获取公钥：从DID文档中找到与证明签名算法匹配的验证公钥。
- 验证签名：使用公钥验证证明的签名是否有效。
- 验证声明：检查证明中的声明是否符合预期（如有效期、目标受众等）。对于SD-JWT，还需执行上述哈希验证流程。
- 输出结果：清晰地返回验证成功或失败，以及失败的具体原因。
你可以扩展这个脚本，加入对特定凭证schema的验证逻辑，确保接收到的数据结构完全符合你的业务要求。
5. 进阶集成、问题排查与未来展望
5.1 将主权身份集成到你的AI智能体工作流
这个技能本身是一个独立模块，但要发挥最大价值，需要将其集成到智能体的核心决策循环中。以下是一些集成思路：
- 身份感知动作：在智能体准备执行一个需要身份认证的外部API调用（例如，提交一个需要签名的区块链交易）前，自动触发
sign_proof.ts逻辑来生成所需的签名凭证。 - 交互式披露：当智能体在与用户聊天中，被问及“你能证明你有权限做X吗？”时，可以调用
selective_disclosure.ts，根据当前对话上下文，动态选择最合适的凭证和声明进行披露。 - 安全守护：将
guardrail.ts的逻辑抽象为一个中间件，在所有用户输入被传递给技能处理之前，先经过安全过滤。
5.2 常见问题与故障排除速查表
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
运行onboard.ts报错：CLAW_PASSWORD not set | 环境变量未正确设置。 | 1. 检查当前shell中是否已设置：echo $CLAW_PASSWORD。2. 确保在运行命令的终端会话中，通过 export CLAW_PASSWORD=your_password或使用.env.agent文件（需配合dotenv等库加载）来设置。 |
onboard.ts运行失败，提示解密错误或生成错误 | 1. 密码错误。 2. 加密的密钥文件已损坏。 3. 项目依赖未正确安装。 | 1. 确认使用的密码与首次创建时一致。 2. 检查密钥文件路径，尝试从备份恢复。 3. 删除 node_modules和package-lock.json，重新运行npm install。 |
| 生成的DID无法被外部验证 | 1. 验证方不支持did:key方法。2. DID标识符在传输过程中出错。 | 1. 考虑使用更通用的DID方法，如did:web（需要你将DID文档托管在一个HTTPS端点下）。这需要修改身份生成逻辑。2. 确保复制粘贴的DID字符串完整无误，没有多余空格或换行。 |
sign_proof.ts生成的凭证验证失败 | 1. 凭证已过期。 2. 验证方使用的公钥不匹配。 3. 凭证的 audience声明与验证方身份不符。 | 1. 检查脚本中设置的validUntil时间戳是否为未来时间。2. 确保验证方是从正确的DID文档中解析公钥。 3. 如果使用了 aud声明，确保生成凭证时指定的受众包含验证方。 |
selective_disclosure.ts披露的信息验证不通过 | 1. 披露时提供的盐值错误。 2. 原始SD-JWT已损坏或被篡改。 3. 验证方算法不一致。 | 1. 确保披露的“盐-值”对与生成SD-JWT时完全一致。这要求持有者必须原样存储披露信息。 2. 重新生成SD-JWT和披露信息进行测试。 3. 确认双方使用的哈希算法（通常是SHA-256）相同。 |
| 性能问题，生成或验证证明速度慢 | 1. 密钥操作（特别是RSA）在低性能环境较慢。 2. DID解析涉及网络请求。 | 1. 坚持使用Ed25519等椭圆曲线算法，其速度远快于RSA。 2. 对于 did:web，考虑在验证方缓存DID文档，并设置合理的过期时间。 |
5.3 扩展方向与最佳实践
掌握了基础技能后，你可以从以下几个方向深化：
- 支持更多DID方法：
did:key简单易用，但缺乏可更新性。集成did:web（将DID文档托管在你的网站）或did:ion（基于比特币区块链的Sidetree协议）可以让你的身份具备撤销和更新公钥的能力。 - 实现凭证吊销：可验证凭证一旦签发，在过期前默认一直有效。要实现吊销，需要维护一个凭证状态列表（如W3C的“状态列表2021”），并在验证时进行检查。这是一个进阶话题。
- 构建身份中心（Identity Hub）：为你的智能体开发一个简单的界面，让它能可视化地管理自己的多个DID、查看持有的所有VC、以及历史披露记录。这能极大地提升可操作性。
- 遵循最佳实践：
- 密钥轮换：定期（如每半年）生成新的主身份密钥对，并将旧DID关联的业务逐步迁移到新DID上。
- 审计日志：记录智能体使用私钥进行签名的每一次操作，包括时间、动作摘要和对方DID，以备审计。
- 最小权限：即使使用SD-JWT，也要反复拷问：这次交互真的需要披露这个属性吗？有没有更模糊的方式（如区间证明）？
将主权身份赋予AI智能体，不仅仅是增加了一个功能模块，更是为它在复杂数字社会中的独立、安全、可信的生存奠定了基础。从理解原理到动手实践，再到根据自身业务场景进行定制和扩展，每一步都充满了挑战和乐趣。
