# @1claw/sdk 中文文档

规范地址：https://npmcn.com/package/%401claw/sdk/

版本：0\.63\.4
npm 元数据更新时间：2026-11-07T06:21:15.746Z
中文译文更新时间：2026-11-07T06:23:34.837Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%401claw/sdk
原文对照：https://npmcn.com/package/%401claw/sdk/?lang=original
项目主页：https://github.com/1clawAI/1claw-sdk#readme
源码仓库：https://github.com/1clawAI/1claw-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.4 MB，255 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-20T15:51:04.625Z
- 最新版本发布：2026-11-07T06:21:15.531Z
- 近 30 天下载量：3078（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：140（近 12 个月 140 个）

## 中文简介

1Claw Vault的SDK类型——AI代理的秘密管理

## 安装

```sh
npm install @1claw/sdk
```

也可以使用：`pnpm add @1claw/sdk`、`yarn add @1claw/sdk`、`bun add @1claw/sdk`

## README

# @1claw/sdk(v

> ⭐ **星号 [1clawAI/代理模板](https://github.com/1clawAI/agent-templates)** ——即时运行代理模板接通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](https://www.npmjs.com/package/@1claw/mcp) 换句话说 如果您在TypeScript中构建了网络应用或后端服务,请从这里开始.

## 安装

```bash
npm install @1claw/sdk
```

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

## 快速启动

```typescript
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](https://www.npmjs.com/package/@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 参考](https://docs.1claw.co/docs/reference/api-reference) 或谱.

## 认证

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

SDK支持四个认证模式:

```typescript
// 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: "user@example.com" });
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: "new@example.com" });
await client.auth.verifyEmailChange({ code: "123456" });
```

## API 资源

| 资源 | 方法 |
| --- | --- |
| `client.vault` | `create`, (中文(简体) ), `get`, (中文(简体) ), `list`, (中文(简体) ), `delete`, (中文(简体) ), `enableMpc`, (中文(简体) ), `disableMpc` |
| `client.secrets` | `set`, (中文(简体) ), `get`, (中文(简体) ), `delete`, (中文(简体) ), `list`, (中文(简体) ), `rotate` |
| `client.access` | `grantHuman`, (中文(简体) ), `grantAgent`, (中文(简体) ), `update`, (中文(简体) ), `revoke`, (中文(简体) ), `listGrants` |
| `client.agents` | `enroll` (另见: `AgentsResource.enroll(baseUrl, …)` 静态), `create`, (中文(简体) ), `getSelf`, (中文(简体) ), `get`, (中文(简体) ), `list`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `rotateKey`, (中文(简体) ), `generateEoa`, (中文(简体) ), `createSmartAccount`, (中文(简体) ), `deleteSmartAccount`, (中文(简体) ), `rotateSigner`, (中文(简体) ), `submitTransaction`, (中文(简体) ), `signTransaction`, (中文(简体) ), `getTransaction`, (中文(简体) ), `listTransactions`, (中文(简体) ), `simulateTransaction`, (中文(简体) ), `simulateBundle`, (中文(简体) ), `sign`, (中文(简体) ), `createDelegation`, (中文(简体) ), `listDelegations`, (中文(简体) ), `getDelegation`, (中文(简体) ), `updateDelegation`, (中文(简体) ), `revokeDelegation`, (中文(简体) ), `getEffectiveDelegations`, (中文(简体) ), `pair`, (中文(简体) ), `spendFromPasskeySafe`, (中文(简体) ), `createChild`, (中文(简体) ), `listChildren`, (中文(简体) ), `createRouterKey`, (中文(简体) ), `listRouterKeys`, (中文(简体) ), `revokeRouterKey`, (中文(简体) ), `createToolBinding`, (中文(简体) ), `listToolBindings`, (中文(简体) ), `deleteToolBinding` |
| `client.chains` | `list`, (中文(简体) ), `get`, (中文(简体) ), `adminList`, (中文(简体) ), `create`, (中文(简体) ), `update`, (中文(简体) ), `delete` |
| `client.sharing` | `create`, (中文(简体) ), `access`, (中文(简体) ), `listOutbound`, (中文(简体) ), `listInbound`, (中文(简体) ), `accept`, (中文(简体) ), `decline`, (中文(简体) ), `revoke` |
| `client.approvals` | `request`, (中文(简体) ), `list`, (中文(简体) ), `approve`, (中文(简体) ), `deny`, (中文(简体) ), `check`, (中文(简体) ), `subscribe` |
| `client.billing` | `usage`, (中文(简体) ), `history`, (中文(简体) ), `llmTokenBilling`, (中文(简体) ), `subscribeLlmTokenBilling`, (中文(简体) ), `disableLlmTokenBilling` (LLM 令牌帐单 / 条纹AI 网关) |
| `client.audit` | `query` |
| `client.org` | `listMembers`, (中文(简体) ), `getAgentKeysVault`, (中文(简体) ), `getOnboardingStatus`, (中文(简体) ), `provisionOnboarding`, (中文(简体) ), `updateMemberRole`, (中文(简体) ), `removeMember`, (中文(简体) ), `diffChart`, (中文(简体) ), `applyChart` |
| `client.auth` | `login`, (中文(简体) ), `signup`, (中文(简体) ), `agentToken`, (中文(简体) ), `apiKeyToken`, (中文(简体) ), `google`, (中文(简体) ), `socialLogin`, (中文(简体) ), `sendEmailOtp`, (中文(简体) ), `verifyEmailOtp`, (中文(简体) ), `exchangeOAuthCode`, (中文(简体) ), `revokeToken`, (中文(简体) ), `revokeConsent`, (中文(简体) ), `getUserInfo`, (中文(简体) ), `changePassword`, (中文(简体) ), `setPassword`, (中文(简体) ), `changeEmail`, (中文(简体) ), `verifyEmailChange`, (中文(简体) ), `forgotPassword`, (中文(简体) ), `resetPassword`, (中文(简体) ), `exportData`, (中文(简体) ), `exchangeFederatedToken`, (中文(简体) ), `logout`, (中文(简体) ), `getMe`, (中文(简体) ), `updateMe`, (中文(简体) ), `deleteMe` |
| `client.apiKeys` | `create`, (中文(简体) ), `list`, (中文(简体) ), `revoke` |
| `client.treasury` | `create`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `addSigner`, (中文(简体) ), `removeSigner`, (中文(简体) ), `requestAccess`, (中文(简体) ), `listAccessRequests`, (中文(简体) ), `approveAccess`, (中文(简体) ), `denyAccess`, (中文(简体) ), `propose`, (中文(简体) ), `listProposals`, (中文(简体) ), `getProposal`, (中文(简体) ), `signProposal`, (中文(简体) ), `executeProposal` |
| `client.treasuryWallets` | `generateWallets`, (中文(简体) ), `listWallets`, (中文(简体) ), `getWallet`, (中文(简体) ), `getWalletBalance`, (中文(简体) ), `sendFromWallet`, (中文(简体) ), `swapFromWallet`, (中文(简体) ), `exportWallet`, (中文(简体) ), `rotateWallet`, (中文(简体) ), `deactivateWallet`, (中文(简体) ), `getEffectiveSpendPolicy` |
| `client.depositDestinations` | `create`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `update` |
| `client.internalAccounts` | `create`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `transfer`, (中文(简体) ), `getLedger` |
| `client.fiat` | `createOnrampSession`, (中文(简体) ), `initiateOfframp` |
| `client.signingKeys` | `create`, (中文(简体) ), `list`, (中文(简体) ), `rotate`, (中文(简体) ), `deactivate`, (中文(简体) ), `export` |
| `client.agents` (银行) | `leaseBankrKey`, (中文(简体) ), `listBankrKeys`, (中文(简体) ), `revokeBankrKey` 特权; `api_key` 用于代理 JWTs (使用 Shroud) 的省略 |
| `client.platform` | `createApp`, (中文(简体) ), `listApps`, (中文(简体) ), `getApp`, (中文(简体) ), `updateApp`, (中文(简体) ), `deleteApp`, (中文(简体) ), `rotateKey`, (中文(简体) ), `rotateWebhookSecret`, (中文(简体) ), `getAppStats`, (中文(简体) ), `marketplace`, (中文(简体) ), `createTemplate`, (中文(简体) ), `listTemplates`, (中文(简体) ), `getTemplate`, (中文(简体) ), `upsertUser`, (中文(简体) ), `listUsers`, (中文(简体) ), `bootstrapUser`, (中文(简体) ), `reissueClaim`, (中文(简体) ), `claimPreview`, (中文(简体) ), `claimRedeem`, (中文(简体) ), `listConnectedApps`, (中文(简体) ), `disconnectApp`, (中文(简体) ), `grantAccess`, (中文(简体) ), `listGrants`, (中文(简体) ), `revokeGrant`, (中文(简体) ), `createSpendPolicy`, (中文(简体) ), `listSpendPolicies`, (中文(简体) ), `setUserSpendPolicy`, (中文(简体) ), `deleteSpendPolicy`, (中文(简体) ), `updateConnectionDelegation`, (中文(简体) ), **`siweChallenge`**, (中文(简体) ), **`getConnection`**, (中文(简体) ), **`getConnectionUsage`**, (中文(简体) ), **`listEntitlements`**, (中文(简体) ), **`refreshEntitlements`**, (中文(简体) ), **`previewTemplate`**, (中文(简体) ), **`transferAppOwnership`**, (中文(简体) ), **`getSpendPolicy`**, (中文(简体) ), **`getConnectionSpendPolicy`**, (中文(简体) ), **`listConnectionApprovals`**, (中文(简体) ), **`getConnectionApproval`**, (中文(简体) ), **`listConnectionPendingApprovals`**, (中文(简体) ), **`createConnectionPendingApproval`**, (中文(简体) ), **`getConnectionPendingApproval`**, (中文(简体) ), **`decideConnectionPendingApproval`**, (中文(简体) ), **`decideConnectionApproval`**, (中文(简体) ), **`createConnectionRuntime`**, (中文(简体) ), **`getConnectionRuntime`**, (中文(简体) ), **`connectionPasskeyEnrollBegin`**, (中文(简体) ), **`connectionPasskeyEnrollComplete`**, (中文(简体) ), **`connectionAgentChat`**, (中文(简体) ), **`listConnectionSigningKeys`**, (中文(简体) ), **`getConnectionSigningKey`**, (中文(简体) ), **`deactivateConnectionSigningKey`**, (中文(简体) ), **`patchConnectionAgent`**, (中文(简体) ), **`getConnectionPortfolio`**, (中文(简体) ), **`getConnectionBalances`**, (中文(简体) ), **`listConnectionAutomations`**, (中文(简体) ), **`createConnectionAutomation`**, (中文(简体) ), **`cancelConnectionAutomationRun`**, (中文(简体) ), **`getConnectionMemory`**, (中文(简体) ), **`putConnectionMemory`**, (中文(简体) ), **`deleteConnectionMemory`**, (中文(简体) ), **`getConnectionOtelTopology`**, (中文(简体) ), **`getConnectionOtelThreats`**, (中文(简体) ), **`getConnectionOtelSummary`**, (中文(简体) ), **`connectionOtelStream`** |
| `client.treasuryWallets` | . **`getInferenceBudget`** (平台连接用户) |
| `client.bindings` | `create`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `test`, (中文(简体) ), `execute`, (中文(简体) ), `rotateCredential`, (中文(简体) ), `listExecutions` |
| `client.chat` | `sendMessage`, (中文(简体) ), `sendMessageStream`, (中文(简体) ), `listConversations`, (中文(简体) ), `getConversation`, (中文(简体) ), `deleteConversation` |
| `client.channels` | `create`, (中文(简体) ), `list`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `send`, (中文(简体) ), `test`, (中文(简体) ), `refreshWebhook`, (中文(简体) ), `listMessages` |
| `client.oauthConnect` | `listProviders`, (中文(简体) ), `listConnections`, (中文(简体) ), `connect`, (中文(简体) ), `disconnect`, (中文(简体) ), `saveAppCredentials`, (中文(简体) ), `listAppCredentials`, (中文(简体) ), `deleteAppCredentials` |
| `client.cedarPolicies` | `create`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `delete`, (中文(简体) ), `test` |
| `client.opaPolicies` | `create`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `delete`, (中文(简体) ), `test` |
| `client.contractAbis` | `upload`, (中文(简体) ), `list`, (中文(简体) ), `delete` |
| `client.pendingApprovals` | `list`, (中文(简体) ), `get`, (中文(简体) ), `approve`, (中文(简体) ), `execute`, (中文(简体) ), `cancel` |
| `client.subOrgs` | `create`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `delete`, (中文(简体) ), `grantPermission`, (中文(简体) ), `revokePermission`, (中文(简体) ), `addUser`, (中文(简体) ), `generateWallets` |
| `client.portfolio` | `get` |
| `client.cards` | `order`, (中文(简体) ), `orderGiftCard`, (中文(简体) ), `searchGiftCards`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `reveal`, (中文(简体) ), `update`, (中文(简体) ), `void`, (中文(简体) ), `refresh`, (中文(简体) ), `import` |
| `client.pay` | `prepare`, (中文(简体) ), `sign`, (中文(简体) ), `reportResult`, (中文(简体) ), `get`, (中文(简体) ), `getSession`, (中文(简体) ), `createGrant`, (中文(简体) ), `revokeGrant`, (中文(简体) ), `updateSettings` -x402 付费墙。 逐字发送402字节;金库会计算文摘并决定授权. 签字时会收取限制费 `reportResult` 释放什么 |
| `client.devices` | `register`, (中文(简体) ), `list`, (中文(简体) ), `delete`, (中文(简体) ), `challenge`, (中文(简体) ), `attest`, (中文(简体) ), `setPushToken` |
| `client.passkeys` | `list`, (中文(简体) ), `registerBegin`, (中文(简体) ), `registerComplete`, (中文(简体) ), `assertBegin`, (中文(简体) ), `assertComplete`, (中文(简体) ), `delete` |
| `client.otel` | `topology`, (中文(简体) ), `threats`, (中文(简体) ), `summary`, (中文(简体) ), `metrics`, (中文(简体) ), `flows`, (中文(简体) ), `agentTrust`, (中文(简体) ), `stream` ——控制平面遥测. 仅限人类使用者(a) `1ck_` ; 拒绝代理. `stream()` 是SSE 上的同步执行器 `Last-Event-ID` 恢复;a `{type: "gap"}` 事件表示反切 `topology()` |
| `client.risk` | `listEvents`, (中文(简体) ), `getVerdict`, (中文(简体) ), `listVerdicts`, (中文(简体) ), `createHoneytoken`, (中文(简体) ), `listHoneytokens`, (中文(简体) ), `deleteHoneytoken` |
| `client.tokens` | `list`, (中文(简体) ), `listByChain`, (中文(简体) ), `create`, (中文(简体) ), `delete` |
| `client.webhooks` | `create`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `update`, (中文(简体) ), `delete` |
| `client.memory` | `put`, (中文(简体) ), `get`, (中文(简体) ), `list`, (中文(简体) ), `delete`, (中文(简体) ), `search`, (中文(简体) ), `listNamespaces`, (中文(简体) ), `deleteNamespace` |
| `client.connectors` | `listPresets`, (中文(简体) ), `list`, (中文(简体) ), `install`, (中文(简体) ), `subscribe`, (中文(简体) ), `listSubscriptions`, (中文(简体) ), `unsubscribe`, (中文(简体) ), `pollNow` 预建连接器和民意调查事件来源 |
| `client.automations` | `create`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `trigger`, (中文(简体) ), `listRuns`, (中文(简体) ), `resumeRun` |
| `client.runtimes` | `create`, (中文(简体) ), `list`, (中文(简体) ), `get`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `start`, (中文(简体) ), `stop`, (中文(简体) ), `logs`, (中文(简体) ), `checkSlug` |
| `client.discovery` | `getAgentCard`, (中文(简体) ), `directory`, (中文(简体) ), `updateDiscovery`, (中文(简体) ), `marketplace` |
| `client.envVars` | `list`, (中文(简体) ), `create`, (中文(简体) ), `get`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `resolve` |
| `client.x402` | `getPaymentRequirement`, (中文(简体) ), `pay`, (中文(简体) ), `verifyReceipt`, (中文(简体) ), `withPayment` |

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

### 环境变量

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

```typescript
// 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)

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

```typescript
// 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`。 。 。 .

## 响应信封

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

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

检查 `error` 访问前 `data`数字 :

```typescript
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 为捕获流量导出一个按键的错误等级 :

| 错误 | HTTP 状态 | 说明 |
| --- | --- | --- |
| `OneclawError` | 任意 | 基础错误类 |
| `AuthError` | 401, 403 (韩语) | 认证/授权失败 |
| `PaymentRequiredError` | 402 (韩语) | 所需付款(包括 `paymentRequirement`(中文(简体) ) |
| `ResourceLimitExceededError` | 403 (韩语) | 达到的分级限制(缺陷、代理人、秘密) |
| `ApprovalRequiredError` | 403 (韩语) | 人类批准门启动 |
| `NotFoundError` | 404 (韩语) | 未找到资源 |
| `ConflictError` | 409个 | 资源已经存在, 例如重复的金库名称 |
| `RateLimitError` | 429个 | 超过费率限额 |
| `ValidationError` | 400个 | 无效的请求正文 |
| `ServerError` | 500岁以上 | 服务器侧失败 |

## 意图 API

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

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

```typescript
// 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` 代理人的签名密钥存储在可用的金库中, 代理人可以提交交易意向 :

```typescript
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保护、自定义中继器)提交:

```typescript
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 功能的代理商的已毕业入室阈值 :

```typescript
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):

```typescript
// 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 指南](https://docs.1claw.co/docs/guides/intents-api#non-evm-transaction-signing) 用于充分实地参考.

密钥属性 :

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

### TEE 执行(Pro+)

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

```typescript
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密钥——没有任何东西通过电子邮件进行旅行.

```typescript
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`,人类在批准页上看到金库,路径和权限;如果批准,则在缺少时创建金库,在路径上创建政策,而金库被捆绑在代理人身上.

```typescript
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`) 并且已经给予该代理人一个连锁津贴(安全津贴单元),该代理人在其中没有触觉地花;该单元执行上限.

```typescript
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);
```

### 代理对代理代表团

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

```typescript
// 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能源排出):

```typescript
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流量和管理符/同意提供帮助:

```typescript
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暴露了一种 铸造联邦标志的方法:

```typescript
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`](https://github.com/1clawAI/1claw-examples/tree/main/anthropic-wif) 重投和 [`internal-docs/runbooks/oidc-federation.md`](https://npmcn.com/package/internal-docs/runbooks/oidc-federation.md)。 。 。 .

## 客户管理的加密密钥

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

```typescript
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);
```

### 服务器辅助密钥旋转

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

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

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

## MPC 默认支持

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

```typescript
// 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秒自动刷新了令牌. 不需要手动符号管理 :

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

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

```typescript
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) (中文(简体) )](https://datatracker.ietf.org/doc/html/rfc9449) 绑定符与客户端的电源。 当启用时, SDK 在启动时生成一个 P-256 ECDSA 键盘并附加一个 `DPoP` 每一个请求的JWT证明——没有匹配的私人密钥,被窃的令牌是无法使用的.

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

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

```typescript
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`数字 :

```typescript
// 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 可以自动处理付款 :

```typescript
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:

```typescript
// 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支持可选的插件接口,用于扩展行为而不修改核心 :

```typescript
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,
    },
});
```

| 接口 | 目的 | 默认行为 |
| --- | --- | --- |
| `CryptoProvider` | 客户端加密( 加密、 解密、 生成Key) | 服务器端的 HSM( 不操作) |
| `AuditSink` | 将 SDK 事件转发到外部系统( Splunk, Datadog) | 无操作( 服务器处理审计) |
| `PolicyEngine` | 在API呼叫前在当地预先评价政策 | 无操作( 服务器执行) |

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

## 外壳安全( LLM 代理)

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

```typescript
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,
    },
});
```

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

```typescript
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:标题**

```typescript
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 风格的提供者)

```typescript
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 禁止使用**。 。 。 .

见 [铺面安全指南](https://docs.1claw.co/docs/guides/shroud) 用于完整配置选项.

## v.48 — Cedar/OPA 执行 v2

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

```typescript
// 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资源:

```typescript
// 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:

```typescript
// 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 钱包登录,参数化后缀,连接投票,应享权利,以及推论预算:

```typescript
// 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:护栏和能力的旗帜不能散装,而且有一个不好的场 拒绝整个补丁.

```typescript
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, 除非注明):

```typescript
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`数字 :

```typescript
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的价卡——加上单一的仪表板样式 快照终点.

```typescript
// 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。 每个现有的每步门(代理配额、运行时间) 配额、控制飞机批准)仍然适用于这一呼吁.

```typescript
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. 仅限人类用户.

```typescript
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](https://www.npmjs.com/package/@1claw/openapi-spec)。高级用户可以访问原始生成的类型:

```typescript
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`](https://npmcn.com/package/%401claw/openapi-spec/openapi.yaml) 通过 `openapi-typescript`。 。 。 .

## MCP 一体化(AI代理)

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

```typescript
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 软件

```typescript
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})` };
        },
    }),
};
```

## 许可证

[麻省理工学院](https://npmcn.com/package/%401claw/sdk/LICENSE)

## 常见问题

### @1claw/sdk 是什么？

1Claw Vault的SDK类型——AI代理的秘密管理

### 如何安装 @1claw/sdk？

在项目目录运行 npm install @1claw/sdk，或使用 pnpm add / yarn add / bun add。

### @1claw/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @1claw/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @1claw/sdk 可以商用吗？

@1claw/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @1claw/sdk 的下载量有多少？

根据 npm 官方下载统计，@1claw/sdk 在 2026/10/05 – 2026/11/03 这 30 天内被下载 3,078 次，日均约 103 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @1claw/sdk 还在维护吗？

最新版本 0\.63\.4 发布于 2026/11/07（今天）；至今共发布 140 个版本，其中过去 12 个月发布了 140 个；首次发布于 2026/02/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。