aixyz-on-openclaw

面向 openclaw 用户的 aixyz 指南

本指南面向想要使用 aixyz 发布可运行并收费的 AI Agent 的 openclaw 用户。你无需具备编程经验，也不必了解加密基础设施——我们会从头讲解每个步骤。

**快速参考：**通用 aixyz 技能位于 skills.sh/agentlyhq/aixyz。 如需了解完整的 CLI 标志和高级主题，请查阅该技能。本指南重点介绍对 openclaw 用户最重要的流程。

---

你要构建什么

一个 AI Agent，它：

1. 通过公开 URL 在互联网上运行
2. 接受其他 Agent（A2A 协议）和 Claude Desktop 等 AI 客户端（MCP 协议）发送的工作请求
3. 通过 x402 微支付协议，以加密货币按请求收款
4. 可通过 ERC-8004 注册表在链上发现

---

步骤 1 — 安装 Bun

aixyz 需要 Bun（不是 Node）。如果你已经安装了 Bun ≥ 1.3，可跳过此步骤。

# macOS / Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell, requires WSL or Windows 10+)
powershell -c "irm bun.sh/install.ps1 | iex"

验证：

bun --version   # should print 1.3 or higher

为什么选择 Bun？ aixyz 构建流程使用 Bun 的原生构建 API 和插件系统——这是硬性架构要求，而非偏好。CLI（@aixyz/cli）无法在 Node 上运行。Bun 还内置了测试运行器，因此无需额外的测试框架。想了解完整原因？请阅读 Why Bun。

---

步骤 2 — 搭建 Agent 项目框架

重要：创建新的 Agent 项目时，必须使用 create-aixyz-app。 请勿手动创建 aixyz.config.ts、package.json、app/agent.ts 或其他项目文件。 手动创建这些文件会导致构建失败、依赖缺失和配置错误。 请始终先使用 bunx create-aixyz-app 搭建项目框架，再修改生成的文件。

# Create a new agent project (uses all defaults)
bunx create-aixyz-app my-agent --yes

cd my-agent

这会创建：

my-agent/
  aixyz.config.ts   ← agent name, description, payment config
  app/
    agent.ts        ← your AI agent logic
    tools/          ← tool files (optional)
  package.json
  .env.local        ← API keys (never commit this file)

打开 .env.local 并添加大模型提供商的 API 密钥。默认项目框架使用 @ai-sdk/openai，因此请添加：

OPENAI_API_KEY=sk-...

如果你倾向于使用其他提供商（Anthropic、Google、Amazon Bedrock 等），请在 package.json 和 app/agent.ts 中替换 @ai-sdk/* 适配器，然后设置对应的环境变量。完整提供商列表请参阅 ai-sdk.dev。

在本地运行以进行测试：

bun run dev
# Agent is now live at http://localhost:3000

使用 AI Agent 客户端进行测试？ 安装 use-agently 技能，这样你的 AI Agent 就能在开发模式下调用本地 Agent：

npx skills add https://github.com/agentlyhq/use-agently --skill use-agently

此技能可让任何 AI Agent 发现并调用在 http://localhost:3000 运行的本地 Agent。 在本地测试时，将 "scheme": "free" 设为免费，以免向调用方收费（请参阅步骤 7）。 上线前，请切换为 "scheme": "exact"，让你的 Agent 从每个请求中获得收入。

---

步骤 3 — 部署到互联网

你的 Agent 需要一个公开的 HTTPS URL，以便其他 Agent 和客户端访问。如果你已有偏好的托管平台，请使用它。如果你是从头开始，以下是我们的建议。

选项 A — Vercel（推荐，无需服务器相关知识）

Vercel 可免费提供 HTTPS URL，且无需任何配置。这是最简单的方式。

1. 将项目推送到 GitHub 仓库
2. 前往 vercel.com → Add New Project → 导入你的仓库
3. 将 Build Command 设为 bun run build，将 Output Directory 设为 .vercel/output
4. 在 Vercel 控制台的 Settings → Environment Variables 下添加大模型提供商的 API 密钥（例如 OPENAI_API_KEY）
5. 点击 Deploy——Vercel 会提供一个类似 https://my-agent.vercel.app 的 URL

每次推送时，Vercel 都会自动部署。你的 Agent 将以无服务器方式运行并自动扩缩。

选项 B — Railway / Render / Fly.io（持久化服务器）

如果你的 Agent 需要在请求之间保留状态或运行后台任务，请使用这些平台。

平台	免费套餐	备注
Railway	5 USD/月额度	无需 Docker，部署最简单
Render	慷慨的免费套餐	不活动后会休眠
Fly.io	免费额度	控制力更强，学习曲线更陡峭

对于这三个平台：推送你的仓库，连接平台，将你的大模型提供商 API 密钥（例如 OPENAI_API_KEY）设为环境变量，然后按照部署向导操作。它们都能自动检测 Bun。

选项 C — 云平台入口或本地隧道（进阶）

如果你已经在云平台上运行 OpenClaw（AWS、GCP、Azure、DigitalOcean 等），最简单的方式是通过同一平台公开 Agent：

• AWS — 在进程前使用 Application Load Balancer 或 API Gateway
• GCP — 使用 Cloud Run（零配置容器部署）或负载均衡器
• Azure — 使用 Azure Container Apps 或 App Service
• DigitalOcean — 使用 App Platform，或使用 nginx 作为反向代理的 Droplet

🔒 **最小权限规则：**公开 Agent 进程时，只开放 Agent 监听的端口（默认 3000）。请勿授予进程超出处理 HTTP 请求所需范围的网络、IAM 或文件系统访问权限。

如果你只需要用于本地测试的临时隧道，请使用 ngrok：

# ngrok — creates a public HTTPS URL that forwards to localhost:3000
npx ngrok http 3000

⚠️ 安全警告：本地隧道适合短期测试，但绝不能用于生产环境中的 Agent。任何发现该 URL 的人都可以向你的机器发送请求。处理线上流量时，请始终使用正规的托管服务提供商。

---

第 4 步 — 获取加密货币钱包

你需要一个钱包来：

• 接收 Agent 调用者支付的款项
• 支付 gas 费，以便在 ERC-8004 上注册

选项 A — 使用 use-agently（最简单，推荐给 openclaw 用户）

use-agently 是 aixyz 生态中最简单的钱包。它专为 Agent 之间相互支付的循环经济而设计。

在 aixyz erc-8004 register 过程中出现提示时，选择 “Generate a new wallet”，CLI 将为你创建钱包并显示私钥。

🔐 私钥安全 — 请仔细阅读：

• **绝不要将私钥分享给任何人。**任何持有私钥的人都能控制你的资金。
• 绝不要将私钥提交到 git，也不要将其粘贴到公开频道（Discord、Slack、GitHub 等）。
• 将私钥记下来并离线存放在安全的地方（例如密码管理器）。
• 如果生产环境中的 Agent 能赚取可观收入，请考虑使用硬件钱包（Ledger、Trezor）。

选项 B — MetaMask（浏览器扩展）

1. 在浏览器中安装 MetaMask
2. 创建新钱包 — MetaMask 会提供一个助记词（12 个单词）；请将其记在安全的地方，绝不要分享
3. 复制你的钱包地址（以 0x… 开头）

选项 C — 任意兼容 EVM 的钱包

任何支持以太坊兼容网络的钱包都可以使用：Coinbase Wallet、Rabby、Frame 等。

钱包地址就是你的“银行账号”。你可以公开分享。你的私钥 / 助记词就是密码——绝不要分享，也绝不要提交到代码中。

---

步骤 5 — 获取用于注册的加密货币

在 ERC-8004 上注册需要支付少量 Gas 费（不到 1 美元）。你需要准备所选网络的原生代币。

网络	所需代币	获取渠道
Ethereum 主网	ETH	Coinbase、Binance、Kraken
BNB Smart Chain	BNB	Binance
Base	ETH	Coinbase（Base 是 Coinbase 的 L2）
Polygon	POL	Coinbase、Binance

推荐网络：Base。 x402 支付促进器主要部署在 Base 上，因此你的 Agent 在那里收到付款的可靠性最高。Base 的 Gas 费也非常低，注册通常只需几美分。Ethereum 主网的 Gas 费波动很大，通常不适合入门使用。所有网络的 Gas 价格都可能波动；以上金额仅供粗略参考。

为钱包充值的步骤：

1. 在上述任一交易所创建账户（需要进行身份验证）
2. 购买少量相应代币（注册只需几美元）
3. 提币到你的钱包地址
4. 等待交易确认（约 1–5 分钟）

还没有加密货币？ 你仍然可以在本地和 Vercel 上构建并运行 Agent，无需注册。准备好公开展示后再注册。

---

步骤 6 — 在 ERC-8004 上注册

ERC-8004 是一个链上注册表，可让其他 Agent、平台和用户发现你的 Agent。它就像 AI Agent 的 DNS 记录。

部署好你的 Agent（步骤 3）并为钱包充值（步骤 4–5）后，运行：

# Interactive mode (will prompt you for each setting)
aixyz erc-8004 register

# Non-interactive mode (all values as flags)
aixyz erc-8004 register \
  --url https://my-agent.vercel.app \
  --chain base \
  --broadcast

CLI 会询问以下信息（也可通过标志传入）：

提示	标志	输入内容
Agent URL	--url	步骤 3 中部署的 URL
链	--chain	base（推荐）、ethereum、bsc、polygon
钱包私钥	--private-key	你的钱包私钥（切勿分享）
信任机制	--trust	接受默认值
广播	--broadcast	传入此标志以实际提交到链上

查看所有标志：

aixyz erc-8004 register --help

注册后，你的 Agent 会显示在 ERC-8004 注册表中，从而可被生态系统发现。

---

步骤 7 — 设置付款

在 app/agent.ts 中添加 accepts 导出，让调用者按请求付费：

import type { Accepts } from "aixyz/accepts";

// During local testing — callers are not charged
export const accepts: Accepts = { scheme: "free" };

// Production — callers pay $0.005 per request
// export const accepts: Accepts = { scheme: "exact", price: "$0.005" };

测试提示： 在本地开发和测试时使用 "scheme": "free"（安装 use-agently 技能，即可通过 AI 客户端调用本地 Agent）。 上线前，改为 "scheme": "exact" 并设置 price，这样 Agent 的每个请求都能带来收入。

在 aixyz.config.ts 中设置接收付款的钱包地址：

export default {
  name: "my-agent",
  // ...
  x402: {
    payTo: "0xYourWalletAddress", // ← paste your address from Step 4
  },
} satisfies AixyzConfig;

或者在脚手架生成时传入：

bunx create-aixyz-app my-agent --yes --pay-to 0xYourWalletAddress

付款会直接转入你的钱包——平台不会抽成。

---

步骤 8 — 上线检查清单

发布 Agent 前，请确认：

• bun run dev 可在本地正常运行，且 Agent 能正确响应
• Agent 已部署到公开 URL（Vercel 或类似平台）
• LLM 提供商的 API 密钥（例如 OPENAI_API_KEY）及其他机密信息均已在平台上设置为环境变量，而非提交到代码仓库
• aixyz.config.ts 中的 name、description 和 payTo 地址均正确
• ERC-8004 注册已完成，且注册表中显示了你的 Agent URL
• 已设置 accepts 导出项，使你的 Agent 能从请求中获得收入

---

步骤 9 — 推广你的 Agent

注册只是工作的一半。 上链并不会自动带来用户。你需要主动推广你的 Agent。

让用户找到你的 Agent

• 在 aixyz.config.ts 中编写清晰、具体的 description — 这会显示在 A2A Agent 卡片和链上注册表中
• 添加 app/icon.png — 出色的图标能让你的 Agent 在列表中脱颖而出
• 在 openclaw 社区发布你的 Agent URL 和 ERC-8004 Agent ID

触达潜在调用者

• 分享你的 /.well-known/agent-card.json URL — 这是 Agent 间发现的标准入口
• 将你的 Agent 添加到相关目录和市场（查看 aixyz.sh 了解当前列表）
• 制作一个简短演示，展示你的 Agent 能做什么以及费用是多少 — 发布到 X/Twitter、Farcaster 或 Discord 社区

考虑定价

• 太贵 → 没有调用者；太便宜 → 不值得运行
• 从每个请求 $0.001–$0.01 起步，并根据需求调整
• 监控你的钱包 — 收入交易会告诉你谁在使用你的 Agent，以及使用频率

持续改进

• 添加更多工具，让你的 Agent 更实用
• 回复问题并处理反馈
• 如果 URL 变更，请更新链上注册信息：aixyz erc-8004 update --help

---

故障排除

“command not found: bun”

安装 Bun 后重启终端，或运行 source ~/.bashrc（Linux）/ source ~/.zshrc（macOS）。

“API key is not set” / “OPENAI_API_KEY is not set”

将 LLM 提供商的 API 密钥添加到 .env.local（本地开发），或添加到平台的环境变量设置中（生产环境）。

ERC-8004 注册期间出现 “Transaction failed”

你的钱包没有足够的 Gas。充值一些相关代币后重试。

Agent 已部署但没有响应

确认平台的构建命令为 bun run build，并且所有环境变量均已设置。检查平台的部署日志中是否有错误。

未收到付款

确认 aixyz.config.ts 中的 payTo 地址正确，并确认修改后已重新构建和部署。

---

延伸阅读

• aixyz 文档 — 完整文档
• 通用 aixyz 技能 — 高级用法的 CLI 参考
• ERC-8004 协议 — 深入了解链上身份
• x402 付款 — 付款协议详情
• 示例 — 可供学习的可运行 Agent