openserv-client

OpenServ 客户端

@openserv-labs/client 包是 OpenServ Platform API 的 TypeScript 客户端。只要代码需要与平台交互——注册 Agent、创建工作流、设置触发器或运行任务——就会用到它。

为什么需要这个包

你的 Agent（使用 @openserv-labs/sdk 构建）运行在你的计算机或服务器上。除非你告知平台它是什么、可以通过什么地址访问，以及如何触发它，否则平台并不知道它的存在。客户端可以帮你完成这些操作。它可以创建平台账户（或复用现有账户）、注册 Agent、定义工作流和触发器（webhook、cron、手动触发或 x402 付费触发器），并绑定凭据，让 Agent 能够接收任务。没有它，你的 Agent 就无法接入平台或接收工作。

你可以用它做什么

• 配置 — 一次性完成设置：创建或复用账户（通过钱包）、注册 Agent、创建包含触发器和任务的工作流，并获取 API 密钥和身份验证令牌。通常每次应用启动时调用一次 provision()；该操作具有幂等性。
• 平台 API — 通过 PlatformClient 完全控制平台：创建和列出 Agent、工作流、触发器和任务；触发触发器；运行工作流；管理凭据。当默认的配置流程无法满足需求时使用此功能。
• 模型参数 — 配置平台用于 Agent 任务的大模型及其参数。在创建或更新 Agent 时，或通过 provision() 设置 model_parameters。
• 模型 API — 通过 client.models.list() 查看可用的大模型及其参数架构。
• x402 付款 — 为 Agent 设置付费墙；调用方需在任务运行前按请求付费（例如使用 USDC）。配置流程可以设置 x402 触发器并返回付费墙 URL。
• ERC-8004 链上身份 — 在链上（Base）注册 Agent、铸造身份 NFT，并将服务元数据发布到 IPFS，让其他人能够以标准方式发现并为你的 Agent 付费。

参考文档： reference.md（完整 API）· troubleshooting.md（常见问题）· examples/（可运行代码）

安装

npm install @openserv-labs/client

---

快速开始：只需 provision() + run()

最简单的部署只需调用两次：provision() 和 run()。 就这么简单。

你需要一个平台账户来注册 Agent 和工作流。最简单的方式是让 provision() 为你创建账户：它会创建一个钱包，并使用该钱包为你注册（无需电子邮件）。每次运行时都会复用该账户。

完整的可运行示例请参见 examples/agent.ts。

要点： provision() 具有幂等性。每次应用启动时都调用它——无需先检查 isProvisioned()。

provision() 的功能

1. 创建或复用 Ethereum 钱包（如果是新账户，也会创建平台账户）
2. 向 OpenServ 平台进行身份验证
3. 创建或更新 Agent（幂等）
4. 生成 API 密钥和身份验证令牌
5. 将凭据绑定到 Agent 实例（如果提供了 agent.instance）
6. 创建或更新包含触发器和任务的工作流
7. 创建工作流图（用于连接触发器和任务的边）
8. 激活触发器并将工作流设为运行状态
9. 将状态持久化到 .openserv.json

工作流名称与目标

workflow 配置需要两个重要属性：

• name（字符串）——这会成为 ERC-8004 中的 Agent 名称。请起一个精炼、有力且令人难忘的名称——这是用户看到的对外品牌名称。要像在为产品发布命名，而不是变量名。示例：'Viral Content Engine'、'Crypto Alpha Scanner'、'Life Catalyst Pro'。
• goal（字符串，必填）——详细描述工作流要完成的任务。描述必须全面详尽；简短或含糊的目标会导致 API 调用失败。至少写一个完整句子来说明工作流的用途。

workflow: {
  name: 'Deep Research Pro',
  goal: 'Research any topic in depth, synthesize findings from multiple sources, and produce a comprehensive report with citations',
  trigger: triggers.webhook({ waitForCompletion: true, timeout: 600 }),
  task: { description: 'Research the given topic' }
}

Agent 实例绑定（v1.1+）

将 Agent 实例传入 provision()，即可自动绑定凭据：

const agent = new Agent({ systemPrompt: '...' })

await provision({
  agent: {
    instance: agent, // Calls agent.setCredentials() automatically
    name: 'my-agent',
    description: '...',
    model_parameters: { model: 'gpt-5', verbosity: 'medium', reasoning_effort: 'high' } // Optional
  },
  workflow: { ... }
})

// agent now has apiKey and authToken set - ready for run()
await run(agent)

这样就无需手动设置 OPENSERV_API_KEY 环境变量。

模型参数

可选的 model_parameters 字段用于控制平台在为你的 Agent 执行任务时（包括无运行能力和 generate() 调用）使用的大模型及其参数。如果未提供，则使用平台默认值。

await provision({
  agent: {
    instance: agent,
    name: 'my-agent',
    description: '...',
    model_parameters: {
      model: 'gpt-4o',
      temperature: 0.5,
      parallel_tool_calls: false
    }
  },
  workflow: { ... }
})

发现可用模型及其参数：

const { models, default: defaultModel } = await client.models.list()
// models: [{ model: 'gpt-5', provider: 'openai', parameters: { ... } }, ...]
// default: 'gpt-5-mini'

配置结果

interface ProvisionResult {
  agentId: number
  apiKey: string
  authToken?: string
  workflowId: number
  triggerId: string
  triggerToken: string
  paywallUrl?: string // For x402 triggers
  apiEndpoint?: string // For webhook triggers
}

---

API 密钥：Agent 与用户

provision() 会创建两种凭证。它们不可互换：

凭证	环境变量	使用方	用途
Agent API 密钥	OPENSERV_API_KEY	SDK 内部	在从平台接收任务时验证 Agent 身份。通过 agent.instance 自动设置。不要将其用于 PlatformClient。
钱包密钥	WALLET_PRIVATE_KEY	PlatformClient	在管理调用中验证你的账户身份（列出任务、调试工作流、管理 Agent）。
用户 API 密钥	OPENSERV_USER_API_KEY	PlatformClient	钱包验证的替代方式。可从平台控制面板获取。

如果使用 PlatformClient 时遇到 401 Unauthorized，你很可能误用了 Agent API 密钥。请改用钱包验证或用户 API 密钥。

---

PlatformClient：完整 API 访问权限

如需高级用例，请直接使用 PlatformClient：

import { PlatformClient } from '@openserv-labs/client'

// Using wallet authentication (recommended — uses wallet from provision)
const client = new PlatformClient()
await client.authenticate(process.env.WALLET_PRIVATE_KEY)

// Or using User API key (NOT the agent API key)
const client = new PlatformClient({
  apiKey: process.env.OPENSERV_USER_API_KEY // NOT OPENSERV_API_KEY
})

完整 API 文档请参见 reference.md：

• client.agents.* - Agent 管理
• client.workflows.* - 工作流管理
• client.triggers.* - 触发器管理
• client.tasks.* - 任务管理
• client.models.* - 可用的大模型及其参数
• client.integrations.* - 集成连接
• client.payments.* - x402 支付
• client.web3.* - 充值点数

---

Triggers 工厂

使用 triggers 工厂进行类型安全的触发器配置：

import { triggers } from '@openserv-labs/client'

// Webhook (free, public endpoint)
triggers.webhook({
  input: { query: { type: 'string', description: 'Search query' } },
  waitForCompletion: true,
  timeout: 600
})

// x402 (paid API with paywall)
triggers.x402({
  name: 'AI Research Assistant',
  description: 'Get comprehensive research reports on any topic',
  price: '0.01',
  timeout: 600,
  input: {
    prompt: {
      type: 'string',
      title: 'Your Request',
      description: 'Describe what you would like the agent to do'
    }
  }
})

// Cron (scheduled)
triggers.cron({
  schedule: '0 9 * * *', // Daily at 9 AM
  timezone: 'America/New_York'
})

// Manual (platform UI only)
triggers.manual()

超时

重要： 对 webhook 和 x402 触发器，始终将 timeout 设置为至少 600 秒（10 分钟）。Agent 通常需要较长时间来处理请求，尤其是在多 Agent 工作流中，或执行研究、内容生成等复杂任务时。较短的超时时间（例如 180s）会导致过早失败。如有疑问，请设置更长的超时时间。对于包含许多连续步骤的多 Agent 流水线，请考虑设置为 900 秒或更长。

输入架构

为 webhook/x402 付费墙界面定义字段：

triggers.x402({
  name: 'Content Writer',
  description: 'Generate polished content on any topic',
  price: '0.01',
  input: {
    topic: {
      type: 'string',
      title: 'Content Topic',
      description: 'Enter the subject you want covered'
    },
    style: {
      type: 'string',
      title: 'Writing Style',
      enum: ['formal', 'casual', 'humorous'],
      default: 'casual'
    }
  }
})

Cron 表达式

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
* * * * *

常见示例：0 9 * * *（每天上午 9 点）、*/5 * * * *（每 5 分钟）、0 9 * * 1-5（工作日上午 9 点）

---

部署到 OpenServ Cloud

使用以下命令将 Agent 部署到 OpenServ 托管云：

npx @openserv-labs/client deploy [path]

其中 [path] 是包含 Agent 代码的目录（默认为当前目录）。

先决条件

1. .env 中的 OPENSERV_USER_API_KEY — Agent 目录中的 .env 文件必须包含 OPENSERV_USER_API_KEY。请从 OpenServ 平台控制面板获取此密钥。部署命令（以及 PlatformClient 的管理操作）需要此密钥。请注意，provision() 本身不需要此密钥——它会创建自己的钱包、完成身份验证，并独立将凭据保存到 .openserv.json。如果存在，用户 API 密钥也会在 provision 后保存到 .openserv.json。

2. 先调用 provision() — 部署前必须至少运行一次 provision()。它会在平台上注册 Agent，并将凭据保存到 .openserv.json。推荐的 Agent 模板已在 main() 中于 run(agent) 前调用 provision()，因此在本地启动 Agent（npm run dev 或 npx tsx src/agent.ts）即可。如果你的代码没有调用 provision()（例如，你只在自定义脚本中调用 run(agent)），则必须显式添加 provision() 调用，并在部署前运行一次。

部署工作流

1. Set OPENSERV_USER_API_KEY in .env
2. Call provision() during local startup (npm run dev) — registers the agent and writes .openserv.json
3. npx @openserv-labs/client deploy .

---

状态管理

import { getProvisionedInfo, clearProvisionedState } from '@openserv-labs/client'

// Get stored IDs and tokens
const info = getProvisionedInfo('my-agent', 'My Awesome Workflow')

// Clear state (forces fresh creation)
clearProvisionedState()

---

发现并触发 x402 服务

发现可用服务（无需身份验证）

discoverServices() 会列出所有公开的、已启用 x402 的工作流。无需身份验证——你可以在一个未经配置的 PlatformClient 上调用它：

import { PlatformClient } from '@openserv-labs/client'

const client = new PlatformClient() // no API key or wallet needed
const services = await client.payments.discoverServices()

for (const service of services) {
  console.log(`${service.name}: $${service.x402Pricing}`)
  console.log(`URL: ${service.webhookUrl}`)
}

触发器

// By workflow ID (recommended — resolves the URL automatically)
const result = await client.triggers.fireWebhook({
  workflowId: 123,
  input: { query: 'hello world' }
})

// Or by direct URL
const result = await client.triggers.fireWebhook({
  triggerUrl: 'https://api.openserv.ai/webhooks/trigger/TOKEN',
  input: { query: 'hello world' }
})

x402（编程方式）

// By workflow ID (recommended)
const result = await client.payments.payWorkflow({
  workflowId: 123,
  input: { prompt: 'Hello world' }
})

// Or by direct URL
const result = await client.payments.payWorkflow({
  triggerUrl: 'https://api.openserv.ai/webhooks/x402/trigger/TOKEN',
  input: { prompt: 'Hello world' }
})

---

环境变量

变量	说明	必需
OPENSERV_USER_API_KEY	用户 API 密钥（来自平台）。部署和 PlatformClient 必需	是*
WALLET_PRIVATE_KEY	用于 SIWE 身份验证的钱包	是*
OPENSERV_API_URL	自定义 API URL	否

*PlatformClient 需要 API 密钥或钱包密钥，两者具备其一即可。npx @openserv-labs/client deploy 需要 OPENSERV_USER_API_KEY。

---

ERC-8004：链上 Agent 身份

完成配置后，在链上注册你的 Agent。这会在 Identity Registry 上铸造 NFT，并将 Agent 的服务端点发布到 IPFS。

需要 Base 上的 ETH。 provision() 创建的钱包初始余额为零。注册前，请为其充值少量 Base 主网上的 ETH。务必使用 try/catch 包裹，以免失败导致 run(agent) 无法启动。

在 provision() 后重新加载 .env。 provision() 会在运行时将 WALLET_PRIVATE_KEY 写入 .env，但启动时 process.env 已加载了空值。请在 provision() 后使用 dotenv.config({ override: true })，以读取刚写入的密钥。完整的 dotenv 模式请参阅 openserv-agent-sdk skill。

import { PlatformClient } from '@openserv-labs/client'

// Reload .env to pick up WALLET_PRIVATE_KEY written by provision()
dotenv.config({ override: true })

try {
  const client = new PlatformClient()
  await client.authenticate(process.env.WALLET_PRIVATE_KEY)

  const erc8004 = await client.erc8004.registerOnChain({
    workflowId: result.workflowId,
    privateKey: process.env.WALLET_PRIVATE_KEY!,
    name: 'My Agent',
    description: 'What this agent does'
  })

  console.log(`Agent ID: ${erc8004.agentId}`) // "8453:42"
  console.log(`Explorer: ${erc8004.blockExplorerUrl}`)
  console.log(`Scan: ${erc8004.scanUrl}`) // "https://www.8004scan.io/agents/base/42"
} catch (error) {
  console.warn('ERC-8004 registration skipped:', error instanceof Error ? error.message : error)
}

• 首次运行会铸造一个新的 NFT。再次运行会更新 URI——Agent ID 保持不变。
• 默认链为 Base 主网（8453）。要使用其他链，请传入 chainId 和 rpcUrl。
• 除非你有意创建新的 Agent ID，否则切勿清除钱包状态。

完整的 ERC-8004 API（钱包管理、链辅助函数、故障排查）请参阅 reference.md。

---

清理

await client.workflows.delete({ id: workflowId })
await client.agents.delete({ id: agentId })
clearProvisionedState()

---

更新此 skill

此 skill 可能已过时。OpenServ 团队会定期发布更新——新功能、API 更改和错误修复在更新之前不会反映在此处。如果某些内容无法按预期工作，或者你想确保获取最新信息，请先更新 skill，再继续操作。

# Check if updates are available
npx skills check

# Update all installed skills to latest versions
npx skills update

或者直接重新安装 OpenServ skills：

npx skills add openserv-labs/skills

---

相关技能

• openserv-agent-sdk - 构建具备各种能力的 Agent
• openserv-multi-agent-workflows - 多 Agent 协作模式
• openserv-launch - 在 Base 区块链上发行代币
• openserv-ideaboard-api - 在 Ideaboard 上寻找创意并发布 Agent 服务