Back to Details

setup-agent

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Setup Karma Agent

设置Karma Agent

Configure your environment to use Karma agent skills. Run this once before using any action skill.
See Agent API Reference for base URL and error handling.
配置你的环境以使用Karma agent技能。在使用任何操作类skill前，请先运行此流程一次。
有关基础URL和错误处理的信息，请查看Agent API参考文档。

Flow

流程

Check if 
KARMA_API_KEY
is already set:
  • If set → skip to Verify Configuration
  • If not set → use the 
    AskUserQuestion
    tool with these options:
    • Question: "You need a Karma API key to continue. How would you like to set it up?"
    • Options: ["Quick start — Generate instantly (no account needed)", "Email login — Link to existing Karma account", "I already have a key"]
    • Quick start → go to Quick Start — No Account Needed
    • Email login → go to Create API Key via Email
    • I already have a key → ask for the key, skip to Save Your API Key
检查
KARMA_API_KEY
是否已设置：
  • 已设置 → 跳至验证配置
  • 未设置 → 使用
    AskUserQuestion
    工具，提供以下选项：
    • 问题：“你需要Karma API密钥才能继续。你希望如何进行设置？”
    • 选项：["快速开始——立即生成（无需账户）", "邮箱登录——关联现有Karma账户", "我已有密钥"]
    • 快速开始 → 进入快速开始——无需账户
    • 邮箱登录 → 进入通过邮箱创建API密钥
    • 我已有密钥 → 请求用户提供密钥，跳至保存你的API密钥

Quick Start — No Account Needed

快速开始——无需账户

The fastest way to get started. No email, no login, no existing account required.
bash
BASE_URL="${KARMA_API_URL:-https://gapapi.karmahq.xyz}"
INVOCATION_ID=$(uuidgen)

curl -s -X POST "${BASE_URL}/v2/agent/register" \
  -H "Content-Type: application/json" \
  -H "X-Source: skill:setup-agent" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 0.2.0" \
  -d '{}'
Expected response:
json
{ "key": "karma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
The key is shown only once. Proceed immediately to Set Your API Key.
Note: Projects created with this method get their own wallet. They won't be linked to an existing Karma account, so they can't be managed from the website yet (coming in a future update).
这是最快的入门方式，无需邮箱、登录或现有账户。
bash
BASE_URL="${KARMA_API_URL:-https://gapapi.karmahq.xyz}"
INVOCATION_ID=$(uuidgen)

curl -s -X POST "${BASE_URL}/v2/agent/register" \\
  -H "Content-Type: application/json" \\
  -H "X-Source: skill:setup-agent" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 0.2.0" \\
  -d '{}'
预期响应：
json
{ "key": "karma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
密钥仅会显示一次，请立即进入设置你的API密钥步骤。
注意：通过此方式创建的项目将拥有独立钱包。它们不会关联到现有Karma账户，因此目前无法通过网站进行管理（该功能将在后续更新中推出）。

Create API Key via Email

通过邮箱创建API密钥

Step 1: Ask for Email

步骤1：请求用户提供邮箱

Ask the user for their email address.
请用户提供他们的邮箱地址。

Step 2: Send Verification Code

步骤2：发送验证码

bash
BASE_URL="${KARMA_API_URL:-https://gapapi.karmahq.xyz}"
INVOCATION_ID=$(uuidgen)

curl -s -X POST "${BASE_URL}/v2/api-keys/auth/init" \
  -H "Content-Type: application/json" \
  -H "X-Source: skill:setup-agent" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 0.2.0" \
  -d '{ "email": "user@example.com" }'
Expected response:
json
{ "message": "Verification code sent to user@example.com" }
Tell the user: "Check your email for a verification code from Karma."
bash
BASE_URL="${KARMA_API_URL:-https://gapapi.karmahq.xyz}"
INVOCATION_ID=$(uuidgen)

curl -s -X POST "${BASE_URL}/v2/api-keys/auth/init" \\
  -H "Content-Type: application/json" \\
  -H "X-Source: skill:setup-agent" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 0.2.0" \\
  -d '{ "email": "user@example.com" }'
预期响应：
json
{ "message": "Verification code sent to user@example.com" }
告知用户：“请查看你的邮箱，获取来自Karma的验证码。”

Step 3: Verify Code

步骤3：验证验证码

Ask the user for the code they received, then:
bash
curl -s -X POST "${BASE_URL}/v2/api-keys/auth/verify" \
  -H "Content-Type: application/json" \
  -H "X-Source: skill:setup-agent" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 0.2.0" \
  -d '{
    "email": "user@example.com",
    "code": "123456",
    "name": "claude-agent"
  }'
Expected response:
json
{ "key": "karma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
Important: The key is shown only once. Proceed immediately to set it.
请用户提供收到的验证码，然后执行以下命令：
bash
curl -s -X POST "${BASE_URL}/v2/api-keys/auth/verify" \\
  -H "Content-Type: application/json" \\
  -H "X-Source: skill:setup-agent" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 0.2.0" \\
  -d '{
    "email": "user@example.com",
    "code": "123456",
    "name": "claude-agent"
  }'
预期响应：
json
{ "key": "karma_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
重要提示：密钥仅会显示一次，请立即进行设置。

Step 4: Handle Errors

步骤4：错误处理

ErrorMeaningAction
400 Invalid or expired code
Wrong code or expiredAsk user to check code or request a new one
409 Active key already exists
User already has a keyTell them to use their existing key or revoke it from the website
429 Too many requests
Rate limitedWait and try again
错误含义处理方式
400 Invalid or expired code
验证码错误或已过期请用户检查验证码或重新请求
409 Active key already exists
用户已拥有有效密钥告知用户使用现有密钥，或在网站上撤销旧密钥后重新生成
429 Too many requests
请求过于频繁等待片刻后重试

1. Save Your API Key

1. 保存你的API密钥

After obtaining the key, ask permission to save it permanently:
Would you like me to save your API key to your shell config so you don't have to paste it every time?
If yes, detect the user's shell and append the export:
bash
undefined
获取密钥后，请先征得用户许可再进行永久保存：
是否需要我将你的API密钥保存到shell配置文件中，这样你就无需每次都手动粘贴了？
如果用户同意，检测用户的shell并添加环境变量：
bash
undefined

Detect shell config file

检测shell配置文件

if [ -f "$HOME/.zshrc" ]; then SHELL_RC="$HOME/.zshrc" elif [ -f "$HOME/.bashrc" ]; then SHELL_RC="$HOME/.bashrc" fi
if [ -f "$HOME/.zshrc" ]; then SHELL_RC="$HOME/.zshrc" elif [ -f "$HOME/.bashrc" ]; then SHELL_RC="$HOME/.bashrc" fi

Append only if not already present

仅当文件中不存在时添加

grep -q 'KARMA_API_KEY' "$SHELL_RC" || echo '\n# Karma API Key\nexport KARMA_API_KEY="karma_..."' >> "$SHELL_RC"
grep -q 'KARMA_API_KEY' "$SHELL_RC" || echo '\

Also export for current session

Karma API Key\

export KARMA_API_KEY="karma_..."

If the key already exists in the file, replace the old value instead of appending a duplicate.

If the user declines, just set it for the current session:

```bash
export KARMA_API_KEY="karma_your_key_here"
export KARMA_API_KEY="karma_..."' >> "$SHELL_RC"

2. Set the API URL (Optional)

同时在当前会话中设置

Defaults to production. For local development:
bash
export KARMA_API_URL="http://localhost:3002"
export KARMA_API_KEY="karma_..."

如果文件中已存在该密钥，请替换旧值，避免重复添加。

如果用户拒绝，则仅在当前会话中设置密钥：

```bash
export KARMA_API_KEY="karma_your_key_here"

3. Verify Configuration

2. 设置API URL（可选）

bash
curl -s "${KARMA_API_URL:-https://gapapi.karmahq.xyz}/v2/agent/info" \
  -H "x-api-key: ${KARMA_API_KEY}" \
  -H "X-Source: skill:setup-agent" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 0.2.0" \
  | python3 -m json.tool
Expected response:
json
{
  "walletAddress": "0x...",
  "smartAccountAddress": "0x...",
  "supportedChainIds": [10, 137, 1135, ...],
  "supportedActions": ["createProject", "createMilestone", ...]
}
默认使用生产环境地址。本地开发时可设置为：
bash
export KARMA_API_URL="http://localhost:3002"

4. Confirm Success

3. 验证配置

If the response includes 
walletAddress
and 
supportedActions
, tell the user their API key and that they're ready:
Your Karma agent is ready!
API Key: 
karma_...
(the key from step 1 or the email flow)
You can now use these skills:
  • project-manager
    — Create and manage projects, grants, milestones, and updates
  • find-funding-opportunities
    — Search for grants, hackathons, bounties, and more
Do NOT show wallet address, smart account address, or chain IDs to the user. They only need the API key.
bash
curl -s "${KARMA_API_URL:-https://gapapi.karmahq.xyz}/v2/agent/info" \\
  -H "x-api-key: ${KARMA_API_KEY}" \\
  -H "X-Source: skill:setup-agent" -H "X-Invocation-Id: $INVOCATION_ID" -H "X-Skill-Version: 0.2.0" \\
  | python3 -m json.tool
预期响应：
json
{
  "walletAddress": "0x...",
  "smartAccountAddress": "0x...",
  "supportedChainIds": [10, 137, 1135, ...],
  "supportedActions": ["createProject", "createMilestone", ...]
}

Troubleshooting

4. 确认设置成功

IssueFix
401 Invalid or revoked API key
Key is wrong or expired — regenerate via email flow or at karmahq.xyz
walletAddress: null
Key was created before server wallets — regenerate it
Connection refused
Wrong 
KARMA_API_URL
— check the URL is reachable
KARMA_API_KEY not set
Run 
export KARMA_API_KEY="karma_..."
in your terminal
如果响应中包含
walletAddress
和
supportedActions
，则告知用户其API密钥已配置完成，可开始使用：
你的Karma agent已准备就绪！
API密钥：
karma_...
（来自步骤1或邮箱流程的密钥）
你现在可以使用以下技能：
  • project-manager
    — 创建并管理项目、资助、里程碑及更新
  • find-funding-opportunities
    — 搜索资助、黑客松、赏金任务等机会
请勿向用户展示钱包地址、智能账户地址或链ID。用户仅需知晓API密钥即可。
—

问题排查

—
问题解决方法
401 Invalid or revoked API key
密钥错误或已过期——通过邮箱流程或在karmahq.xyz上重新生成
walletAddress: null
密钥是在服务器钱包功能推出前创建的——请重新生成密钥
Connection refused
KARMA_API_URL
设置错误——检查该地址是否可访问
KARMA_API_KEY not set
在终端中运行
export KARMA_API_KEY="karma_..."