@1claw/sdk(v

⭐ 星号 1clawAI/代理模板 ——即时运行代理模板接通1Claw. 这是我们唯一的主演Repo.

1Claw Vault API的TypeScript/JavaScript客户端.

这是Node.js,Next.js的官方SDK,以及浏览器应用,通过HTTP调用1Claw. 它涵盖金库,秘密,代理,政策,国库,intents API签名,执行约束,平台应用,计费,和x402支付. 类型由OpenAPI spec生成,因此请求形状与API保持同步.

JWTs的代理密钥自动交换,到期前刷新. 如果你在Cursor或Claude桌面上 给一个人工智能代理 @ 1claw/ mcp 换句话说 如果您在TypeScript中构建了网络应用或后端服务,请从这里开始.

安装

npm install @1claw/sdk

说明: 这个软件包是 仅限无害环境管理在无害环境管理背景下使用(例如:. "type": "module" 内 package.json,或 .mjs 文档). Next.js和其他捆绑商在本地处理无害环境管理。 运行带有平原的脚本 node 或者说 tsx 可能需要建立无害环境管理机制以避免 ERR_PACKAGE_PATH_NOT_EXPORTED。 。 。 .

快速启动

import { createClient } from "@1claw/sdk";

const client = createClient({
    baseUrl: "https://api.1claw.co",
    apiKey: "ocv_...", // auto-exchanges for a JWT
});

// List vaults
const { data } = await client.vault.list();
console.log(data?.vaults);

// Store a secret
await client.secrets.set("vault-id", "OPENAI_KEY", "sk-...", {
    type: "api_key",
});

// Retrieve a secret.
// Every call returns { data, error }. `data` is null whenever `error` is set,
// so `data?.value` alone turns a 403 into a silent undefined — check `error`.
const { data, error, meta } = await client.secrets.get("vault-id", "OPENAI_KEY");
if (error) {
    console.error(meta?.status, error.type, error.message, meta?.requestId);
} else {
    console.log(data?.value);
}

API合同: 这个SDK是从 开放API 3.1 谱. 犬科的种类公布于 @ 1claw/ openapi- spec (YAML/JSON) (日语). 类型生成方式 npm run generate (单位:千美元)openapi-typescript ../openapi-spec/openapi.yaml) (中文(简体) ). 运行 generate 光谱改变后 npm run build。形状,例如 LlmTokenBillingStatus (包括任择) credit_balance 财务报告和审定财务报表 billing_cycle_usage.metered_lines)来自生成 api-types.ts。关于完整的终点清单,请参见 API 参考 或谱.

认证

JWT探员 POST /v1/auth/agent-token 可能包括任择债权,例如: shroud_enabled 财务报告和审定财务报表 shroud_config (当Shroud在为那个特工。 这些是服务类 外壳 校验 JWT; TypeScript SDK 使用符号进行 Vault API 调用, 不需要读取 shroud_config 除非你建立自定义的工具.

SDK支持四个认证模式:

// 1. User API key (exchanged for a JWT on first request)
const client = createClient({
    baseUrl: "https://api.1claw.co",
    apiKey: "1ck_...",
});

// 2. Agent with API key (auto-authenticates as agent)
const agent = createClient({
    baseUrl: "https://api.1claw.co",
    apiKey: "ocv_...",
    agentId: "agent-uuid",
});

// 3. Pre-authenticated JWT
const authed = createClient({
    baseUrl: "https://api.1claw.co",
    token: "eyJ...",
});

// 4. Platform API key (sent as the Bearer token as-is, no exchange;
//    `token: "plt_..."` works the same way)
const platform = createClient({
    baseUrl: "https://api.1claw.co",
    apiKey: "plt_...",
});

// Or authenticate manually:
await client.auth.login({ email: "...", password: "..." });
await client.auth.agentToken({ agent_id: "...", api_key: "..." });
await client.auth.google({ id_token: "..." });

// Password reset (public; no Bearer token — use a client without stored JWT)
await client.auth.forgotPassword({ email: "[email protected]" });
await client.auth.resetPassword({ token: "...", new_password: "..." });

// Set password (platform OIDC users who don't have one)
await client.auth.setPassword({ password: "...", password_confirm: "..." });

// Change email (sends verification code to new address)
await client.auth.changeEmail({ new_email: "[email protected]" });
await client.auth.verifyEmailChange({ code: "123456" });

API 资源

平台拖网响应 : bootstrapUser() 返回 a summary 包含对象 agent_api_key (一次性,以后不可收回)和 signing_keys[] (每个提供钥匙都有链条、地址和公用钥匙).

环境变量

以环境范围界定(生产、预览、开发)和基于优先的分辨率管理每层环境变量:

// List env vars for a vault
const { env_vars } = await client.envVars.list(vaultId);

// Create an env var
const envVar = await client.envVars.create(vaultId, {
  key: "DATABASE_URL",
  value: "postgres://...",
  environments: ["production", "preview"],
  sensitive: true,
});

// Get a specific env var
const dbUrl = await client.envVars.get(vaultId, "DATABASE_URL");

// Update an env var
await client.envVars.update(vaultId, "DATABASE_URL", {
  value: "postgres://new-host/...",
});

// Resolve env vars (the final KEY=VALUE set with precedence)
const { vars, sources } = await client.envVars.resolve(vaultId, "production");

// Delete an env var
await client.envVars.delete(vaultId, "DATABASE_URL");

代理环境标签(v0.52)

具有命名环境的标记剂用于政策范围界定和内分辨率:

// Create an agent tagged for preview deployments
await client.agents.create({
  name: "preview-bot",
  environment: "preview",
  env_auto_resolve: true,
});

// Update environment and per-environment guardrails
await client.agents.update(agentId, {
  environment: "production",
  environment_locked: true,
  per_environment_guardrails: {
    production: { max_value: "1.0", daily_limit: "10.0" },
    preview: { max_value: "0.1", daily_limit: "1.0" },
  },
});

// Resolve env vars — when env_auto_resolve is true on the agent JWT,
// omit environment and the server uses the agent's tag
const { vars } = await client.envVars.resolve(vaultId);

JWT探员包括 environment 设定时索赔。 政策条件支助 environment_in 用于环境范围访问.

代理创建响应 : agents.create() 返回时 { agent: AgentResponse, api_key?: string }编辑 api_key 仅为 auth_method: "api_key" 并显示一次——使用 data.agent.id 财务报告和审定财务报表 data.api_key 从回应.

获得补助金: grantAgent(vaultId, agentId, permissions, options?) 位置参数;选项包括 secretPathPattern, (中文(简体) ), conditions, (中文(简体) ), expires_at。 。 。 .

响应信封

所有方法都返回打入的信封 :

interface OneclawResponse<T> {
    data: T | null;
    error: { type: string; message: string; detail?: string } | null;
    meta?: { status: number };
}

检查 error 访问前 data数字 :

const res = await client.secrets.get("vault-id", "key");
if (res.error) {
    console.error(res.error.type, res.error.message);
} else {
    console.log(res.data.value);
}

错误类型

SDK 为捕获流量导出一个按键的错误等级 :

意图 API

代理人可以被授予通过Intents API在链上签名和广播交易的能力. 私人密钥留在HSM——代理提交意向,API标志和广播.

切换 intents_api_enabled 在创建或更新代理时:

// Register an API key agent with Intents API access (default auth_method)
const { data } = await client.agents.create({
    name: "defi-bot",
    auth_method: "api_key", // "api_key" | "mtls" | "oidc_client_credentials"
    scopes: ["keys/*", "api-keys/*"],
    intents_api_enabled: true,
});
// data.api_key is only returned for auth_method: "api_key"
// All agents automatically receive an Ed25519 SSH keypair (data.agent.ssh_public_key)

// Register an mTLS agent (no API key returned)
const { data: mtlsAgent } = await client.agents.create({
    name: "mtls-bot",
    auth_method: "mtls",
    client_cert_fingerprint: "sha256-fingerprint-hex",
});

// Register an OIDC agent (no API key returned)
const { data: oidcAgent } = await client.agents.create({
    name: "oidc-bot",
    auth_method: "oidc_client_credentials",
    oidc_issuer: "https://accounts.google.com",
    oidc_client_id: "your-client-id",
});

// Or enable it later
await client.agents.update(agentId, {
    intents_api_enabled: true,
});

// Check an agent's proxy status
const agent = await client.agents.get(agentId);
console.log(agent.data?.intents_api_enabled); // true

提交交易

一次 intents_api_enabled 代理人的签名密钥存储在可用的金库中, 代理人可以提交交易意向 :

const txRes = await client.agents.submitTransaction(agentId, {
    to: "0x000000000000000000000000000000000000dEaD",
    value: "0.01", // ETH
    chain: "base",
    // Optional: data, signing_key_path, nonce, gas_price, gas_limit
});

console.log(txRes.data?.status); // "signed"
console.log(txRes.data?.tx_hash); // "0x..."
console.log(txRes.data?.signed_tx); // signed raw transaction hex

后端从金库取出签名密钥,签署EIP-155交易,并返回所签名的交易十六进制. 签名密钥被解密成-memory,被使用,并立即被零化——它永远不会离开服务器.

SDK 自动生成一个 Idempotency-Key 每个标题( UUID v4) submitTransaction 电话,提供回放保护。 24小时内重复请求返回缓存回复,而不是重新签名.

只签名模式( BYORPC)

使用 signTransaction 如果您想要服务器签名, 但是 没有 例如,通过自己的RPC(Flashbots、MEV保护、自定义中继器)提交:

const signRes = await client.agents.signTransaction(agentId, {
    to: "0x000000000000000000000000000000000000dEaD",
    value: "0.01",
    chain: "base",
});

console.log(signRes.data?.signed_tx); // raw signed tx hex
console.log(signRes.data?.tx_hash);   // precomputed keccak hash
console.log(signRes.data?.from);      // derived sender address

// Broadcast yourself via ethers, viem, or raw JSON-RPC

所有代理护栏(排行表、值封顶、每日限制)与提交时完全相同。 交易记录用于审计和每日限制追踪 status: "sign_only"。 。 。 .

HITL & v0.55 护栏毕业

配置有 Intents API 功能的代理商的已毕业入室阈值 :

await client.agents.update(agentId, {
  tx_approval_policy: {
    require_above_native: { ethereum: "0.1", base: "0.05" },
    require_for_new_recipients: true,
    require_for_unlimited_approvals: true,
  },
  typed_data_policy: "approve",           // EIP-712 → 202 awaiting_approval
  simulation_failure_policy: "approve",   // Tenderly revert → HITL
  raw_signing_policy: "approve",          // allow | deny | approve
  tx_block_unlimited_approvals: true,
  tx_max_value_usd: "1000",
  tx_daily_limit_usd: "5000",
  allow_erc4337: true,
  allow_eip7702: false,
  clear_auto_suspended: true,             // owner/admin — clear circuit breaker
});

奥尔格紧急冻结(业主/管理人员): POST /v1/org/freeze 财务报告和审定财务报表 POST /v1/org/unfreeze。 。 。 .

非EVM交易(比特币、索拉纳、XRP、Cardano、Tron)

一样 submitTransaction 编号 : signTransaction 方法接受特定链字段。 数值在链的原生单位(BTC,SOL,XRP,ADA,TRX):

// Solana devnet — native SOL
await client.agents.submitTransaction(agentId, {
    chain: "solana-devnet",
    to: "RecipientBase58...",
    value: "0.001",
});

// Bitcoin testnet
await client.agents.signTransaction(agentId, {
    chain: "bitcoin-testnet",
    to: "tb1q...",
    value: "0.00001",
    fee_rate_sat_per_vbyte: 5,
});

// XRP — simple Payment with destination tag
await client.agents.submitTransaction(agentId, {
    chain: "xrp-testnet",
    to: "r...",
    value: "1",
    destination_tag: 12345,
});

// XRP — arbitrary XRPL transaction type via xrpl_tx_json
// Supports 30+ types: TrustSet, OfferCreate, NFTokenMint, AMMCreate, EscrowCreate, etc.
// Account, Sequence, Fee, and SigningPubKey are auto-filled by the server.
await client.agents.submitTransaction(agentId, {
    chain: "xrp",
    xrpl_tx_json: {
        TransactionType: "TrustSet",
        LimitAmount: {
            currency: "USD",
            issuer: "rIssuer...",
            value: "100",
        },
    },
});

// Solana SPL token
await client.agents.submitTransaction(agentId, {
    chain: "solana-devnet",
    to: "RecipientBase58...",
    value: "10",
    token_mint: "MintBase58...",
    token_decimals: 6,
});

见 意向 API 指南 用于充分实地参考.

密钥属性 :

• 默认禁用 人类必须明确允许每名特工
• 签名密钥永不离开 HSM - 与秘密相同的信封加密
• 默认缺额 ——每份划界案包括自动生成的 Idempotency-Key 标题
• 每笔交易都有审计记录 包含完整调用数据
• 可立即恢复 设置 intents_api_enabled: false 切断进入

TEE 执行(Pro+)

把特工关起来 这样签字和执行 必须 发生在硬件飞地(Shroud TEE). 保险库执行它的方式是转发给Shroud,而不是拒绝你.

await client.agents.update(agentId, {
    intents_require_tee: true,    // Only signs within the hardware enclave
    execution_require_tee: true,  // Only runs within the hardware enclave
});

何时 intents_require_tee 事实 :

• 交易提交/签名请求在 Shroud 的 TEE 内签名, 不论您拨打哪个主机—— 保险库转发到一个请求 api.1claw.co 因此SDK不需要特别的 baseUrl
• 直接电话: shroud.1claw.co 仍在工作, 需要用于 DPOP 绑定的符号

何时 execution_require_tee 事实 :

• 执行在 Shroud 的 TEE 执行表面运行的请求 —— 由金库强制, 不需要客户端路径
• 特工读取的所有直接秘密都被封锁——武力使用行刑意图约束

两者都要求 intents_api_enabled 编号 : execution_intents_enabled 成为第一.

代理配对指纹

一个特工可以用自己的Ed25519公用钥匙报名. 金库返回 SSH 风格 SHA256: 在批准页面上给人指纹比较,代理者在批准后自己收集其API密钥——没有任何东西通过电子邮件进行旅行.

import { AgentsResource } from "@1claw/sdk";

const result = await AgentsResource.pair(
    "https://api.1claw.co",
    { name: "my-agent", public_key: "ssh-ed25519 AAAA…" },
    (fingerprint, approvalUrl) => console.log(`Show the human: ${fingerprint}\n${approvalUrl}`),
);
// result.status === "approved" → result.api_key (shown once)

要求特定访问,而不是默认的启动者赠款(examples/** 输入 default 保险库),添加 requested_access,人类在批准页上看到金库,路径和权限;如果批准,则在缺少时创建金库,在路径上创建政策,而金库被捆绑在代理人身上.

const result = await AgentsResource.pair(
    "https://api.1claw.co",
    {
        name: "harness-relay",
        public_key: "ssh-ed25519 AAAA…",
        requested_access: { vault: "Harness", path: "harness/**" }, // permissions default to ["read", "write"]
    },
    (fingerprint, approvalUrl) => console.log(`Show the human: ${fingerprint}\n${approvalUrl}`),
);
// result.granted_access → { vault: "Harness", vault_id, vault_created, path: "harness/**", permissions, granted: true }

保险箱:由赠款支付

当人类拥有带有密码的EVM保险箱时(custody: passkey_owner) 并且已经给予该代理人一个连锁津贴(安全津贴单元),该代理人在其中没有触觉地花;该单元执行上限.

const spend = await client.agents.spendFromPasskeySafe(agentId, safeId, {
    to: "0xRecipient…",
    amount: "10000000000000000", // base units (0.01 ETH)
    // token: "0xUSDC…"          // omit for the native token
});
console.log(spend.data.tx_hash, spend.data.remaining_after);

代理对代理代表团

由人工控制授权代理任务授权. 未经人类建立的明确授权记录,代理人不得委托给其他代理人.

// Create a delegation (human-only)
await client.agents.createDelegation(orchestratorId, {
    delegate_id: subAgentId,
    allowed_tools: ["delegate_task", "search_memory"],
    max_daily_delegations: 100,
    max_depth: 2,
    delegation_mode: "caller",
    expires_at: "2026-12-31T23:59:59Z",
});

// List delegations for an agent
const delegations = await client.agents.listDelegations(agentId);

// Get effective delegations (agent-callable — for runtime tool discovery)
const effective = await client.agents.getEffectiveDelegations(agentId);

// Update a delegation (human-only)
await client.agents.updateDelegation(agentId, delegationId, {
    max_daily_delegations: 200,
    is_active: false,
});

// Revoke a delegation (human-only)
await client.agents.revokeDelegation(agentId, delegationId);

代表团模式 : caller (delegate使用自己的证书), target (delegate使用目标配置), both (每次引用都采用两种方式).

间接费用和交易限额

防止非价值排水攻击(ATA租金排出、XRP储备耗尽、Tron能源排出):

await client.agents.update(agentId, {
    tx_max_per_day: 100,                     // Cap transactions per UTC day
    tx_overhead_budget: {                    // Per-chain non-value cost budgets (native units)
        solana: "0.5",
        xrp: "100",
        ethereum: "0.01",
    },
    solana_ata_allowlist: [                  // Only these addresses may have ATAs created
        "7nYzKqAqfaGEhN6oeKCQVFjduQ9qH1dWs2gVFkNKBpQF",
    ],
    per_chain_guardrails: {                  // Per-chain overrides
        solana: { max_per_day: 20, overhead_budget: "0.2", max_ata_creates_per_day: 5 },
    },
});

// Check current spend:
const agent = await client.agents.get(agentId);
console.log(agent.data?.tx_count_today);           // e.g. 42
console.log(agent.data?.tx_overhead_today_by_chain); // e.g. { "solana": "0.12" }

OAuth2 / PKCE ("与 1Claw 一起签名")

SDK为完全实现OAuth2 PKCE流量和管理符/同意提供帮助:

import { generatePKCE, buildAuthorizeUrl, createClient } from "@1claw/sdk";

// 1. Generate PKCE pair
const pkce = await generatePKCE();

// 2. Build the authorize URL
const authUrl = buildAuthorizeUrl("https://1claw.co", {
    clientId: "your-platform-app-slug",
    redirectUri: "https://yourapp.com/callback",
    scopes: ["openid", "profile", "email"],
    state: "random-state",
    codeChallenge: pkce.codeChallenge,
});

// 3. After redirect, exchange the code for tokens
const client = createClient({ baseUrl: "https://api.1claw.co" });
const tokens = await client.auth.exchangeOAuthCode({
    code: "authorization-code-from-callback",
    client_id: "your-platform-app-slug",
    redirect_uri: "https://yourapp.com/callback",
    code_verifier: pkce.codeVerifier,
});

// 4. Fetch user info
const userInfo = await client.auth.getUserInfo(tokens.data?.access_token);

// 5. Revoke a token (RFC 7009)
await client.auth.revokeToken({ token: "...", token_type_hint: "refresh_token" });

// 6. Revoke consent for an app (invalidates all tokens)
await client.auth.revokeConsent("platform-app-id");

OIDC联合会(Athropic WIF、GCP STS、AWS STS)

https://api.1claw.co 是一个完全 OpenID 连接 - 符合要求的发行者 。 外部依赖方——Anthropic Workload Definition Federation,GCP STS,AWS STS,Stytch等——可以通过获取:

• GET https://api.1claw.co/.well-known/openid-configuration
• GET https://api.1claw.co/.well-known/jwks.json

SDK暴露了一种 铸造联邦标志的方法:

const tokenRes = await client.auth.exchangeFederatedToken({
    audience: "https://api.anthropic.com",
    // subjectToken? — defaults to the client's current login or apiKey
    // scope? — optional space-separated subset of agent's scopes
});

const oidcJwt = tokenRes.data?.access_token; // RS256-signed; ~15 min default TTL, hard cap 1h

代理必须拥有 federation_enabled: true 编辑 audience 一定是在它上,我必须 federation_audiences 允许列表(通过仪表板设置或 client.agents.update) (中文(简体) ). 每个活跃的 KMS 密钥版本都以 JWKS 发布, 因此验证器拒绝未知 kid当 1claw 旋转密钥时自动 s.

端到端 Anthropic WIF 演示: 见 examples/anthropic-wif 重投和 internal-docs/runbooks/oidc-federation.md。 。 。 .

客户管理的加密密钥

对于需要密码学证明1claw不能单方面获取其秘密的企业,SDK提供客户端的CMEK公用事业. 密钥完全由您一方生成和管理——只有SHA-256指纹存储在服务器上.

import { cmek } from "@1claw/sdk";

// Generate a 256-bit AES key (returns CryptoKey)
const key = await cmek.generateCmekKey();

// Compute fingerprint (SHA-256 hex)
const fingerprint = await cmek.cmekFingerprint(key);

// Enable CMEK on a vault
await client.vault.enableCmek(vaultId, { fingerprint });

// Encrypt a secret value before storing
const encrypted = await cmek.cmekEncrypt(key, "my-secret-value");
await client.secrets.set(vaultId, "path/to/secret", encrypted);

// Decrypt after retrieving
const res = await client.secrets.get(vaultId, "path/to/secret");
const plaintext = await cmek.cmekDecrypt(key, res.data.value);

服务器辅助密钥旋转

await client.vault.rotateCmek(vaultId, oldKey, newKey, {
    new_fingerprint: await cmek.cmekFingerprint(newKey),
});

服务器按100批次重新加密所有机密. 投票旋转状态 :

const job = await client.vault.getRotationJobStatus(vaultId, jobId);
console.log(job.data?.status, job.data?.processed, "/", job.data?.total_secrets);

MPC 默认支持

断层可以选择使用多方计算(MPC)进行秘密分取. 当MPC被启用后,服务器持有一股而客户端持有另一股——任何一方都无法单独重建这个秘密.

// Enable MPC on a vault
await client.vault.enableMpc(vaultId);

// Store a secret — response includes the client_share
const res = await client.secrets.set(vaultId, "my-key", "secret-value");
const clientShare = res.data?.client_share; // Save this securely on your side

// Retrieve a secret — pass client_share to reconstruct
const secret = await client.secrets.get(vaultId, "my-key", {
    client_share: clientShare,
});
console.log(secret.data?.value);

// Disable MPC (converts back to standard encryption)
await client.vault.disableMpc(vaultId);

当 MPC 启用时, set 答复包括a client_share 字段必须存储客户端。 这个 get 方法接受可选 client_share 参数可以重建完整的秘密。 没有客户端共享,服务器只返回其共享.

代理托肯自动更新

使用代理证书时(agentId + 键 apiKey),SDK在到期前60秒自动刷新了令牌. 不需要手动符号管理 :

const client = createClient({
    baseUrl: "https://api.1claw.co",
    apiKey: "ocv_...",
    agentId: "agent-uuid",
});
// Tokens refresh transparently — just make API calls

交换回复中也提到代理商有权获得什么(错误 ? 0.61.17),所以工具主机可以在没有第二次呼叫的情况下塑造其表面:

const res = await client.auth.agentToken({ api_key: "ocv_..." });
res.data?.entitlements;
// { intents_api: true, execution_intents: false, execution_require_tee: false, intents_require_tee: false,
//   cards: false, memory: true, shroud: false, discoverable: false, treasury_signer: false, has_delegations: false }

更改具有债权的代理字段(scopes, (中文(简体) ), vault_ids, (中文(简体) ), is_active, (中文(简体) ), intents_api_enabled, (中文(简体) ), shroud_enabled, (中文(简体) ), execution_intents_enabled, (中文(简体) ), *_require_tee, (中文(简体) ), environment)通过 client.agents.update() 撤销代理未完成的JWT;SDK的下个请求自动再交换.

DPoP( 赞助会)

启用 DPoP (RFC 9449) (中文(简体) ) 绑定符与客户端的电源。 当启用时, SDK 在启动时生成一个 P-256 ECDSA 键盘并附加一个 DPoP 每一个请求的JWT证明——没有匹配的私人密钥,被窃的令牌是无法使用的.

const client = createClient({
    baseUrl: "https://api.1claw.co",
    apiKey: "ocv_...",
    agentId: "agent-uuid",
    dpop: true, // Generates ephemeral P-256 keypair, attaches DPoP proofs
});

这个 DPoPManager 类还被导出用于高级用途:

import { DPoPManager } from "@1claw/sdk";

const dpop = new DPoPManager();
await dpop.init();

const proof = await dpop.generateProof("POST", "https://api.1claw.co/v1/auth/agent-token");
const thumbprint = dpop.getThumbprint(); // JWK SHA-256 thumbprint (base64url)

风险引擎

查询风险事件,检索威胁判决,管理蜂窝 client.risk数字 :

// List recent risk events (filtered by severity)
const events = await client.risk.listEvents({
    severity: "high",
    limit: 50,
});
console.log(events.data?.events);

// Get the current risk verdict for a specific agent
const verdict = await client.risk.getVerdict("agent", agentId);
console.log(verdict.data?.verdict?.severity); // "low" | "medium" | "high" | "critical"
console.log(verdict.data?.verdict?.reasons);  // detector breakdown

// List all verdicts for the org
const verdicts = await client.risk.listVerdicts();

// Create a honeytoken (canary secret that triggers alerts on access)
const ht = await client.risk.createHoneytoken({
    vault_id: vaultId,
    secret_path: "honeypot/admin-key",
    notes: "Canary for unauthorized agent access",
});
console.log(ht.data?.honeytoken.id);

// List and delete honeytokens
const honeytokens = await client.risk.listHoneytokens();
await client.risk.deleteHoneytoken(honeytokenId);

x402 支付协议

当超过自由级限制时, API 返回 402 Payment Required。如果您提供了签名符, SDK 可以自动处理付款 :

import { createClient, type X402Signer } from "@1claw/sdk";

const signer: X402Signer = {
    getAddress: async () => "0x...",
    signPayment: async (accept) => {
        // Sign EIP-712 payment with your wallet library (ethers, viem, etc.)
        return signedPayloadHex;
    },
};

const client = createClient({
    baseUrl: "https://api.1claw.co",
    apiKey: "ocv_...",
    x402Signer: signer,
    maxAutoPayUsd: 0.01, // auto-pay up to $0.01 per request
});

// Or use the explicit pay-and-fetch flow:
const secret = await client.x402.withPayment("vault-id", "key", signer);

支付卡(x402)

订购预付卡和礼品卡,其中代理人通过外出支付x402次付款(USDC on Base),从未看到PAN/CVV:

// Order a prepaid card
const card = await client.cards.order("agent-id", {
    kind: "prepaid",
    amount_usd: "5.00",
});
// card.id, card.status ("pending"), card.last4 (once ready)

// Poll until ready (or rely on card.ready webhook)
const status = await client.cards.get(card.id);

// Reveal (human-only with password re-auth)
const revealed = await client.cards.reveal(card.id, { password: "my-password" });
// revealed.pan, revealed.cvv, revealed.disclaimer

// Gift cards
const gifts = await client.cards.searchGiftCards({ country: "US" });
const giftCard = await client.cards.order("agent-id", {
    kind: "gift_card",
    amount_usd: "25.00",
    laso_server_id: gifts[0].serverId,
});

// Lifecycle
await client.cards.void(card.id);
await client.cards.refresh(card.id);
const all = await client.cards.list();

插件

SDK支持可选的插件接口,用于扩展行为而不修改核心 :

import { createClient } from "@1claw/sdk";
import type { CryptoProvider, AuditSink, PolicyEngine } from "@1claw/sdk";

const client = createClient({
    baseUrl: "https://api.1claw.co",
    apiKey: "ocv_...",
    plugins: {
        cryptoProvider: myAwsKmsProvider,
        auditSink: mySplunkSink,
        policyEngine: myOpaEngine,
    },
});

在您的软件包中执行任何接口——不需要对 SDK 的 PR .

外壳安全( LLM 代理)

特工可以通过以TEE为基础的具有综合安全功能的代理Shroud通过LLM流量. 通过 shroud_config 对象 :

const { data } = await client.agents.create({
    name: "secure-agent",
    shroud_enabled: true,
    shroud_config: {
        // Basic settings
        pii_policy: "redact",           // block | redact | warn | allow
        injection_threshold: 0.7,

        // Model restrictions
        allowed_models: ["gpt-4o-mini", "claude-sonnet-5"],  // Whitelist specific models
        denied_models: ["gpt-3.5-turbo"],                   // Blacklist models
        allowed_providers: ["openai", "anthropic"],          // Restrict providers

        // Threat detection
        unicode_normalization: {
            enabled: true,
            strip_zero_width: true,
            normalize_homoglyphs: true,
        },
        command_injection_detection: {
            enabled: true,
            action: "block",            // block | sanitize | warn | log
        },
        social_engineering_detection: {
            enabled: true,
            action: "warn",
            sensitivity: "medium",      // low | medium | high
        },
        encoding_detection: { enabled: true, action: "warn" },
        network_detection: { enabled: true, action: "warn" },
        filesystem_detection: { enabled: false },  // disabled by default

        // Advanced inspection (Phase 2+3)
        tool_call_inspection: {
            enabled: true,
            scan_arguments: true,
            block_credential_exfil: true,
            action: "block",
        },
        output_policy: {
            enabled: true,
            blocked_entities: ["CompetitorCo"],
            block_harmful_content: true,
            harmful_categories: ["malware", "illegal"],
            action: "warn",
        },
        secret_injection_detection: {
            enabled: true,
            action: "block",
            sensitivity: "medium",
        },
        advanced_redaction: {
            enabled: true,
            detect_base64_encoded: true,
            detect_split_secrets: true,
            detect_prefix_leak: true,
        },
        semantic_policy: {
            enabled: true,
            allowed_topics: ["customer_support"],
            denied_tasks: ["code_generation", "data_export"],
            action: "warn",
        },
        flagged_request_retention_days: 30,

        // Global settings
        sanitization_mode: "block",     // block | surgical | log_only
        threat_logging: true,
    },
});

更新现有代理的安全配置 :

await client.agents.update(agentId, {
    shroud_config: {
        command_injection_detection: { enabled: true, action: "block" },
        social_engineering_detection: { enabled: true, action: "block" },
        allowed_models: ["gpt-4o-mini"],  // Restrict to cost-effective models
    },
});

在请求中指定模式

在向 Shroud 提出 LLM 请求时, 以两种方式之一指定模型 :

备选案文1:标题

const res = await fetch("https://shroud.1claw.co/v1/chat/completions", {
  method: "POST",
  headers: {
    "X-Shroud-Agent-Key": `${agentId}:${agentApiKey}`,
    "X-Shroud-Provider": "openai",
    "X-Shroud-Model": "gpt-4o-mini",  // ← Model in header
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [{ role: "user", content: "Hello" }],
  }),
});

备选案文2:请求机构 (适用于 OpenAI 风格的提供者)

body: JSON.stringify({
  model: "gpt-4o-mini",  // ← Model in body
  messages: [{ role: "user", content: "Hello" }],
})

{\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}Shroud执行经纪人的命令 allowed_models 财务报告和审定财务报表 denied_models 自动限制——使用未经授权的模型返回的请求 403 禁止使用。 。 。 .

见 铺面安全指南 用于完整配置选项.

v.48 — Cedar/OPA 执行 v2

政策后端设置、合同ABI登记和尚待批准的共识:

// Org policy backend (shadow mode default)
const settings = await client.org.getPolicyBackendSettings();
await client.org.updatePolicyBackendSettings({ mode: "shadow", backend: "builtin+cedar" });
const report = await client.org.getPolicyShadowReport();

// Contract ABI registry (owner/admin)
await client.contractAbis.create({
    chain: "ethereum",
    contract_address: "0x...",
    abi_json: [...],
});
await client.contractAbis.list({ chain: "ethereum" });

// Consensus pending approvals
await client.pendingApprovals.submit({
    policy_id: "...",
    action: "sign",
    action_payload: { chain: "ethereum", to: "0x...", value: "0" },
});
await client.pendingApprovals.list({ status: "pending" });

// Access policies with consensus_trigger
await client.access.createPolicy(vaultId, {
    secret_path_pattern: "keys/*",
    principal_type: "agent",
    principal_id: agentId,
    permissions: ["read"],
    consensus_trigger: {
        conditions: [{ type: "value_above", threshold_wei: "1000000000000000000" }],
        approval: {
            min_approvals: 2,
            required_roles: ["owner", "admin"],
            per_role_minimums: { owner: 1 },
            require_credential_types: ["passkey"],
        },
    },
    tx_conditions: {
        eip712_primary_type_in: ["Permit", "Permit2"],
        eip712_verifying_contract_in: ["0x000000000022D473030F116dDEE9F6B43aC78BA3"],
        eip7702_authorized_addresses_in: ["0xKnownSafeDelegate"],
    },
});

v0.47 — 统包对等

用于企业和金库的新SDK资源:

// Unified portfolio across treasury wallets, signing keys, and smart accounts
const portfolio = await client.portfolio.get({ include_tokens: true });

// Cedar declarative policies (Team+ tier)
await client.cedarPolicies.create({ name: "allow-read", cedar_text: "permit(...);" });
await client.cedarPolicies.test({ principal_type: "agent", action: "read", ... });

// OPA Rego policies (Business+ tier)
await client.opaPolicies.create({ name: "deny-export", rego_source: "package oneclaw\n..." });

// Sub-organizations (Enterprise hierarchy)
await client.subOrgs.create({ name: "Engineering" });
await client.subOrgs.list();

// Import existing Gnosis Safe smart accounts
await client.agents.importSmartAccount(agentId, {
    chain: "ethereum",
    chain_id: 1,
    safe_address: "0x...",
    verify: true,
});

// BYOK signing key import (human-only, requires password re-auth)
await client.signingKeys.import(agentId, "ethereum", {
    private_key: "0x...",
    format: "hex",
}, { authConfirm: "your-password" });

v0.56 — 安全账户、护卫治理、住房基金

第5阶段 安全基础和v0.56 护道治理 API:

// Agent on-chain accounts (EOA + counterfactual Safe)
const { data: accounts } = await client.agents.listAccounts(agentId);
await client.agents.migrateToSafe(agentId, { chain: "ethereum", deprecate_eoa: true });
await client.agents.deprecateEoaAccount(agentId, "ethereum");
await client.agents.syncOrgSafeAllowances(); // owner/admin

// Public Safe module registry (Guard + Zodiac addresses per chain)
const registry = await client.agents.getSafeModuleRegistry("ethereum");

// Guardrail widening returns 202 — resubmit PATCH with approval_id after decide
await client.agents.update(agentId, {
    tx_to_allowlist: ["0xNewRecipient..."],
    approval_id: "uuid-from-202-response",
});

// Guardrail governance (owner/admin)
await client.org.getGuardrailShadowReport({ since: "2026-01-01T00:00:00Z" });
await client.org.listGuardrailRevisions();
await client.agents.replayGuardrails(agentId, {
    days: 7,
    draft_guardrails: { tx_max_value_eth: "0.1" },
});

// Human Factor Auth — treasury send/swap step-up policies
await client.auth.getHumanFactorAuth();
await client.auth.setHumanFactorAuth({ require_passkey: true, require_totp: false });
const embedded = await client.treasuryWallets.getAuthPolicy(); // wallet-react / embedded clients

// Passkey tx-assert for treasury send/swap (alternative to X-Auth-Confirm password)
const begin = await client.auth.beginPasskeyTxAssert({ tx_digest: "abc123...", action: "swap" });
// ... complete ceremony, then send with X-Passkey-Token header

v0.57 — 平台 API扩展

SIWE 钱包登录,参数化后缀,连接投票,应享权利,以及推论预算:

// SIWE challenge + upsert (plt_ auth)
const challenge = await client.platform.siweChallenge();
// ... sign SIWE message, upsert with subject_token_type urn:1claw:params:oauth:token-type:siwe

await client.platform.getConnection(connectionId);
await client.platform.getConnectionUsage(connectionId);
await client.platform.listEntitlements(connectionId);
await client.platform.previewTemplate(appId, templateId, { parameters: { agent_name: "demo" } });

await client.treasuryWallets.getInferenceBudget();

v0.60 — 舰队管理

每个特工都提供一个靴子套模板,作为一个组。 每个呼叫行动 所以表面比每剂要窄 API:护栏和能力的旗帜不能散装,而且有一个不好的场 拒绝整个补丁.

const { data: fleet } = await client.platform.getFleet(appId, templateId);
console.log(`${fleet.agents_behind} of ${fleet.total_agents} behind`);

// Read the allowlist from the server rather than hard-coding it.
if (fleet.bulk_patchable_fields.includes("system_prompt")) {
    await client.platform.bulkPatchFleet(appId, templateId, {
        system_prompt: "You are a careful assistant.",
    });
}

// A dry run changes nothing and claims no job, so job_id comes back null.
const { data: plan } = await client.platform.rolloutFleet(appId, templateId, {
    dry_run: true,
});
console.log(plan.skipped_drifted, "agent(s) were hand-edited and would be skipped");

await client.platform.listFleetAgents(appId, templateId, { limit: 100 });
await client.platform.pauseFleet(appId, templateId);

v0.58 — 平台 API 控制平面

App-scoped reading, Cost-policy idency, 以及所有权的转让(plt auth, 除非注明):

await client.platform.transferAppOwnership(appId, {
    target_org_id: "org-uuid",
});
await client.platform.getSpendPolicy(appId, policyId);
await client.platform.getConnectionSpendPolicy(connectionId);
await client.platform.listConnectionApprovals(connectionId);
await client.platform.getConnectionApproval(connectionId, approvalId);
await client.platform.listConnectionPendingApprovals(connectionId);
await client.platform.getTemplate(appId, templateId);
await client.platform.createConnectionRuntime(connectionId, {
    name: "my-runtime",
    agent_id: "agent-uuid",
    preset: "small",
    template: "openclaw",
});
await client.platform.connectionAgentChat(connectionId, agentId, {
    message: "Hello",
});
await client.platform.decideConnectionPendingApproval(connectionId, approvalId, {
    decision: "approve",
    payload_hash: "...",
    credential_type: "wallet_mandate",
});
await client.platform.decideConnectionApproval(connectionId, approvalId, {
    decision: "approved",
});
await client.platform.deactivateConnectionSigningKey(connectionId, "ethereum", agentId);
// setUserSpendPolicy(connectionId, data, { idempotencyKey: "..." }) — 24h replay protection

v0.59 — Fathom 平台整合

连接扫描运行时间、 密码录入和代理 system_prompt数字 :

await client.platform.getConnectionRuntime(connectionId, runtimeId);
await client.platform.connectionPasskeyEnrollBegin(connectionId);
await client.platform.connectionPasskeyEnrollComplete(connectionId, {
    credential_id: "...",
    attestation_object: "...",
    client_data_json: "...",
});
await client.platform.connectionAgentChat(connectionId, agentId, {
    message: "Hello",
    system_prompt: "You are helpful.",
});
await client.agents.create({ name: "bot", system_prompt: "Default persona" });
// getConnection() includes provisioned_tier when billing_model is platform_pays

v.61——大赦国际开支、定价和沃尔格概览

巨兽的代理人在推论上花费了多少(虚构 0.6140) 由提供者,模型, 代理和日用org的价卡——加上单一的仪表板样式 快照终点.

// Last 30 days by default; pass from/to/interval to change the window.
const { data: spend } = await client.spend.ai({
    interval: "day",
    provider: "anthropic",
});
console.log(spend.totals.cost_usd, "vs.", spend.previous.cost_usd, "previous window");
for (const row of spend.by_model) {
    console.log(row);
}

// CSV export — one row per agent × provider × model. Returns a path, not a
// fetch: build the full URL yourself (e.g. `${baseUrl}${client.spend.aiCsvPath()}`).
const csvPath = client.spend.aiCsvPath({ from: "2026-09-01T00:00:00Z" });

// The price card: global list prices plus this org's overrides.
const { data: card } = await client.spend.listPrices();

// Owner/admin: override a price, or remove the override.
const { data: price } = await client.spend.setPrice({
    provider: "anthropic",
    modelPattern: "claude-opus-4-*",
    inputUsdPerMtok: 12,
    outputUsdPerMtok: 60,
});
await client.spend.deletePrice(price.id);

// Owner/admin: price any requests that arrived before a price card existed for their model.
const { data: result } = await client.spend.reprice();
console.log(`${result.repriced} request(s) priced`);

// A single snapshot across inventory, activity, spend, and health — the
// dashboard overview endpoint, `hours` default 24.
const { data: overview } = await client.org.overview(24);
console.log(overview.spend.inference_usd, overview.health);

v.61 — 一次性运行服务

代理(新或已存在) + 密钥 + 默认违约赠款 + 运行时间 + 启动, 在一个 电话(故障) 0.6148。 每个现有的每步门(代理配额、运行时间) 配额、控制飞机批准)仍然适用于这一呼吁.

const { data: provisioned } = await client.runtimes.provision({
    name: "my-runtime",
    template: "openclaw",
    preset: "small",
    // Either { id } for an existing agent, or { name } to create one — the
    // create path also grants it read/write on a new default vault.
    agent: { name: "my-agent" },
});
console.log(provisioned.runtime.id, provisioned.started);
if (provisioned.agent_api_key) {
    // Only present when the agent was created here — shown once, store it now.
    console.log("save this key:", provisioned.agent_api_key);
}

v.63:自控密钥

client.keyCustody 覆盖自控的 HTTP 侧: 2–3 FROST 钱包 (单位:千美元)client_tss: keygen, 签名, 共享刷新, 包裹共享, 回收包, 恢复, ), Tron 2-of-3 本地多西格和EVM 2-of-3 保险箱(client_multisig,β) (中文(简体) ). 这个 设备侧面( FROST 回合, 在 PRF 密码下包装股份, 回收) 工具包)在浏览器中运行 @1claw/tss-wasm;这些方法带有其输出. 采用的方法 passkeyToken 发送 X-Passkey-Token;那些采取 authConfirm 发送 X-Auth-Confirm。请求和答复类型来自 开口API spec. 仅限人类用户.

const { data: chains } = await client.keyCustody.getTssChains();

// Prepare runs wallet access, sanctions, spend policy, transaction policy and
// treasury_send consensus. A consensus hold answers 202.
let res = await client.keyCustody.treasuryPrepare("solana", { to, value: "0.5" });
if (res.meta?.status === 202) {
    const { pending_approval_id } = res.data as { pending_approval_id: string };
    // ...once approved:
    res = await client.keyCustody.treasuryPrepare("solana", {
        to,
        value: "0.5",
        approval_id: pending_approval_id,
    });
}

// Adding a second wrap needs a re-auth token for purpose "tss.key.wrap_add".
await client.keyCustody.rewrapClientShare(keyId, wrap, reauthToken);

// Kit coverage is recorded only from a kit proof.
await client.keyCustody.confirmKit(keyId, { generation, group_public_key, kit_proof });

api-types.ts 从 @1claw/openapi-spec 0.61.76 (英语).

OpenAPI 类型

SDK的请求类型来自 开放API 3.1 spec, 发表于 @ 1claw/ openapi- spec。高级用户可以访问原始生成的类型:

import type { paths, components, operations, ApiSchemas } from "@1claw/sdk";

// Access any schema from the spec
type Vault = ApiSchemas["VaultResponse"];
type Agent = ApiSchemas["AgentResponse"];

光谱变化后再生类型( 从单重键) : cd packages/sdk && npm run generate - 读取 ../openapi-spec/openapi.yaml 通过 openapi-typescript。 。 。 .

MCP 一体化(AI代理)

SDK披露了AI代理的MCP相容工具定义:

import { getMcpToolDefinitions, McpHandler } from "@1claw/sdk/mcp";
import { createClient } from "@1claw/sdk";

// Get tool definitions for your agent's tool registry
const tools = getMcpToolDefinitions();
// → 1claw_get_secret, 1claw_set_secret, 1claw_list_secret_keys, etc.

// Dispatch tool calls from your agent
const client = createClient({ baseUrl: "...", token: "..." });
const handler = new McpHandler(client);
const result = await handler.handle("1claw_get_secret", {
    vault_id: "...",
    key: "OPENAI_KEY",
});

使用 Vercel AI SDK 软件

import { tool } from "ai";
import { z } from "zod";
import { createClient } from "@1claw/sdk";

const client = createClient({ baseUrl: "...", apiKey: "..." });

export const oneclawTools = {
    getSecret: tool({
        description: "Fetch a secret from the 1claw vault",
        parameters: z.object({
            vaultId: z.string(),
            key: z.string(),
        }),
        execute: async ({ vaultId, key }) => {
            const res = await client.secrets.get(vaultId, key);
            if (res.error) return { error: res.error.message };
            return { status: "available", hint: `Secret retrieved (${key})` };
        },
    }),
};

许可证

麻省理工学院