把 KNA 接入 OpenClaw

OpenClaw 是一款"个人 AI 助手"，可跑在你自己的设备/VPS 上，原生支持 25+ 消息平台（Telegram、Discord、Slack、WhatsApp、iMessage、飞书、微信、QQ 等）。GitHub: openclaw/openclaw

核心原理：OpenClaw 通过 models.providers 配置项支持任意 Anthropic 兼容的自定义端点。把 KNA 注册为一个 provider，所有 Claude 模型立刻可用，无需改一行代码。

0TL;DR（60 秒版）

# 1. 安装 OpenClaw
npm install -g openclaw@latest

# 2. 启动 onboarding 向导
openclaw onboard

# 3. 当向导问 provider 时，选 "Custom (Anthropic-compatible)"
#    - Base URL:  https://code.wearekna.com
#    - API Key:   sk-kna-xxxxxxxxxxxxxxxxxxxxxxxx
#    - Model:     claude-sonnet-4-6

如果你想跳过向导直接编辑配置（推荐脚本化场景）、或想配置辅助任务、或要排查问题，往下读。

1前提条件

1.1 在 KNA 注册账号、拿 API Key

1. 打开 https://wearekna.com，点 立即注册
2. 邮箱注册（无需海外信用卡、无需手机号实名）
3. 登录到 https://code.wearekna.com/dashboard
4. 左侧 API 密钥 → 创建 Key → 命名「openclaw」→ 复制以 sk-kna- 开头的 token
5. 充值（最低 ¥10，全场赠送 20%；推荐先充 ¥30 测试）

💡 首次充值建议 ¥30：到账约 $5 USD 余额，够跑约 250 万 Haiku tokens 或 33 万 Sonnet input tokens——足以验证 OpenClaw 完整工作流。

1.2 系统 / 平台支持

1.3 运行时依赖

OpenClaw 是 Node.js 项目，需要 Node 20+。安装方式任选：

# 方式 1：nvm 管理（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20

# 方式 2：直接下载 https://nodejs.org/

# 方式 3：用 bun（OpenClaw 兼容）
curl -fsSL https://bun.sh/install | bash

也支持 pnpm 和 bun 作为 package manager。

2安装 OpenClaw

2.1 全局安装（推荐）

npm install -g openclaw@latest

# 或用 pnpm
pnpm add -g openclaw@latest

# 或用 bun
bun add -g openclaw@latest

2.2 验证安装

openclaw --version
openclaw doctor

openclaw doctor 会检查 Node 版本、依赖、配置目录、网络等；正常输出全是 ✅。

2.3 安装为后台守护进程（用消息平台时必备）

openclaw onboard --install-daemon

这会注册 launchd（macOS）或 systemd user service（Linux），让 OpenClaw Gateway 始终在后台运行，从 Telegram / Discord 等收发消息。

3配置 KNA Key 进 OpenClaw —— 三种方式

OpenClaw 主配置文件：~/.openclaw/config.json5（JSON5 格式，支持注释和尾逗号）。
环境变量文件：~/.openclaw/.env。

下面三种方式选一个就行。

方式 A · 交互式 onboarding 向导（最简单）

openclaw onboard

按提示走：

1. Choose an LLM provider → 选 Custom (Anthropic-compatible) 或 Other / Custom
2. Provider ID → 输入 kna（可任意取名）
3. Base URL → https://code.wearekna.com
4. API Key → 粘贴你的 sk-kna-xxxxxxxxxxxxxxxxxxxxxxxx
5. API protocol → 选 anthropic-messages
6. Default model → claude-sonnet-4-6

完成后向导会自动写入 ~/.openclaw/config.json5 和 ~/.openclaw/.env，之后直接 openclaw agent --message "你好" 就能聊。

方式 B · CLI 命令行（脚本化，DevOps 友好）

# 1. 把 KNA Key 写入环境变量
echo 'ANTHROPIC_API_KEY=sk-kna-xxxxxxxxxxxxxxxxxxxxxxxx' >> ~/.openclaw/.env

# 2. 注册 KNA 为 provider
openclaw config set models.providers.kna.baseUrl https://code.wearekna.com
openclaw config set models.providers.kna.apiKey '${ANTHROPIC_API_KEY}'
openclaw config set models.providers.kna.api anthropic-messages

# 3. 设为默认模型
openclaw models set kna/claude-sonnet-4-6

验证：

openclaw models list --provider kna
# 应该看到 KNA 注册的所有模型

方式 C · 直接编辑配置文件（精细控制 / 多模型场景）

~/.openclaw/config.json5

{
  // KNA 注册为自定义 provider
  models: {
    mode: "merge",     // 与 OpenClaw 内置 provider 合并，不替换
    providers: {
      kna: {
        baseUrl: "https://code.wearekna.com",
        apiKey: "${ANTHROPIC_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
          { id: "claude-haiku-4-5",  name: "Claude Haiku 4.5" },
          { id: "claude-opus-4-7",   name: "Claude Opus 4.7" },
        ],
      },
    },
  },

  // 主模型（agent 默认对话用）
  agents: {
    defaults: {
      model: {
        primary: "kna/claude-sonnet-4-6",
        fallbacks: [
          "kna/claude-sonnet-4-6",   // primary 失败时尝试
          "kna/claude-haiku-4-5",    // 再失败用 Haiku（便宜兜底）
        ],
      },

      // 视觉任务（图片识别）单独指定
      imageModel: { primary: "kna/claude-sonnet-4-6" },

      // PDF 解析
      pdfModel: { primary: "kna/claude-sonnet-4-6" },
    },
  },
}

~/.openclaw/.env

# KNA API Key（Anthropic-compatible 端点）
ANTHROPIC_API_KEY=sk-kna-xxxxxxxxxxxxxxxxxxxxxxxx

⚠️ 不要 git commit .env——它是密钥。OpenClaw 默认 .gitignore 排除了它。

4KNA 支持的 Claude 模型清单

OpenClaw 里 model id 格式是 <provider>/<model>，比如 kna/claude-sonnet-4-6。

价格目前按 Anthropic 官方价 1.5 折引流价计费 — 实付仅官方 15%（KNA 不加价、不预扣、不取整 — 见 wearekna.com 价格说明）。1.5 折为限时引流价，之后会上调。

完整模型清单见 Anthropic 官方文档。新模型发布后，KNA 当天同步支持。

推荐配置（性价比 + 能力均衡）：

• 主模型：kna/claude-sonnet-4-6
• 辅助 / 压缩：kna/claude-haiku-4-5
• 复杂任务（手动切）：kna/claude-opus-4-7

5验证连接

5.1 用 OpenClaw 跑第一句话

openclaw agent --message "你是哪个模型？请返回完整 model id" --thinking high

正确响应应该说自己是 Claude Sonnet 4.6 / Opus / Haiku（取决于你的 default）。如果它说 GPT-X 或 Llama，说明配置走错 provider 了——回头检查 agents.defaults.model.primary 是否带了 kna/ 前缀。

5.2 用 curl 直接验证 KNA 端点（不通过 OpenClaw）

curl -s https://code.wearekna.com/v1/messages \
  -H "x-api-key: sk-kna-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 50,
    "messages": [{"role":"user","content":"返回三个字: 已验证"}]
  }' | jq '.model, .usage, .content[0].text'

期望输出：

"claude-sonnet-4-6"
{"input_tokens": 14, "output_tokens": 5, ...}
"已验证"

5.3 验证 OpenClaw 真的打到了 KNA

KNA 在每个响应里加了 x-upstream: api.anthropic.com 和 x-passthrough: true 头，证明请求确实转发到 Anthropic：

curl -sI -X POST https://code.wearekna.com/v1/messages \
  -H "x-api-key: sk-kna-xxxxxxxxxxxxxxxxxxxxxxxx" | grep -iE "x-upstream|x-passthrough"
# x-upstream: api.anthropic.com
# x-passthrough: true

6进阶 · 多模型 / 多平台策略

6.1 用 Haiku 做辅助任务省成本

OpenClaw 内部的总结、压缩、标题生成等辅助任务用 agents.defaults.models 单独指定 cheap 模型：

{
  agents: {
    defaults: {
      // 主模型仍用 Sonnet
      model: { primary: "kna/claude-sonnet-4-6" },

      // 但下面这些"机械任务"切到 Haiku（便宜 5 倍）
      summarizationModel: { primary: "kna/claude-haiku-4-5" },
      titleModel:         { primary: "kna/claude-haiku-4-5" },
      compressionModel:   { primary: "kna/claude-haiku-4-5" },
    },
  },
}

6.2 同时把消息平台接入

OpenClaw 的杀手锏是从 Telegram / Discord / iMessage 等收发消息。配置一次，全平台共享 KNA：

# 启动 onboarding，按需选平台
openclaw onboard

# 或单独配某个平台
openclaw onboard --enable-telegram
openclaw onboard --enable-discord

每个平台收到的消息都会用你设的 kna/claude-sonnet-4-6 回复。

6.3 多 Agent 路由（高阶）

让不同的 channel / 联系人路由到不同 agent，每个 agent 用不同模型：

{
  agents: {
    defaults: { model: { primary: "kna/claude-sonnet-4-6" } },
    list: [
      {
        id: "research",
        // 研究类对话用 Opus 4.7
        model: { primary: "kna/claude-opus-4-7" },
        bindings: [{ channel: "telegram", peer: "@your_research_chat" }],
      },
      {
        id: "casual",
        // 日常闲聊用 Haiku 省钱
        model: { primary: "kna/claude-haiku-4-5" },
        bindings: [{ channel: "imessage", peer: "*" }],
      },
    ],
  },
}

详见 Multi-agent routing。

6.4 Cron 调度任务

# 每天早上 9 点跑一次，用 Sonnet
openclaw cron add "0 9 * * *" \
  --message "看看 GitHub trending，挑 3 个 AI 项目总结发我 Telegram" \
  --target "telegram:@me"

Cron 任务默认用 agents.defaults.model.primary，也就是 KNA Sonnet。注意：长跑任务持续消耗余额，建议在 KNA dashboard 设置余额低提醒邮件。

7常见问题

{
  models: {
    mode: "merge",
    providers: {
      kna:        { baseUrl: "https://code.wearekna.com", apiKey: "${ANTHROPIC_API_KEY}", api: "anthropic-messages" },
      openrouter: { baseUrl: "https://openrouter.ai/api/v1", apiKey: "${OPENROUTER_API_KEY}", api: "openai-completions" },
      groq:       { baseUrl: "https://api.groq.com/openai/v1", apiKey: "${GROQ_API_KEY}", api: "openai-completions" },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "kna/claude-sonnet-4-6",
        fallbacks: ["openrouter/anthropic/claude-3.5-sonnet", "groq/llama-3.3-70b"],
      },
    },
  },
}

8数据流向（透明可验证）

你的 OpenClaw Agent (本地 / VPS / Docker)
        │
        │ HTTPS, TLS 1.3
        ▼
   Cloudflare 边缘 (中国可达 CDN)
        │
        │ retention: 0 / logs: none
        ▼
   KNA 转发节点 (Tokyo, AS-Vultr)
        │
        │ retention: 0 / logs: metadata only (model, tokens, latency)
        │ 不缓存、不读取 prompt、不路由其他模型
        ▼
   api.anthropic.com (Anthropic 官方端点)
        │
        ▼
       Claude (Opus / Sonnet / Haiku)

KNA 全程零留存，仅记录账单 metadata（哪个 model、多少 token、多久）。prompt 与 completion 内容不落盘。详细政策见 wearekna.com#notdo。

9故障排查 Checklist

按顺序检查：

• ☐ openclaw doctor 全 ✅
• ☐ openclaw config show 输出包含 models.providers.kna
• ☐ ~/.openclaw/.env 存在且 ANTHROPIC_API_KEY=sk-kna-...
• ☐ curl 测试 KNA 端点（见第 5.2 节）能拿到 200 响应
• ☐ KNA dashboard 余额 ≥ $0.01
• ☐ KNA Key 状态 = 启用、未过期
• ☐ openclaw models list --provider kna 能列出至少一个模型
• ☐ 当前 IP 没被加入 KNA 黑名单（dashboard → IP 管理可见）

如果以上全过还是不通，加 KNA 微信客服群（wearekna.com 首页 footer 二维码）或邮件 info@wearekna.com，附上：

1. openclaw doctor 输出
2. openclaw config show 输出（注意脱敏 API key）
3. 错误 stack trace 或 response body

10一行升级 / 一行回滚

升级 OpenClaw 到最新版：

npm install -g openclaw@latest

切回内置 Anthropic 直连（如果你有官方 API Key）：

openclaw models set anthropic/claude-opus-4-7

完整删除 KNA 配置：

openclaw config unset models.providers.kna
openclaw models set anthropic/claude-opus-4-7   # 或其他你要的 default

附录 · 完整 config.json5 参考

// ~/.openclaw/config.json5

{
  // ─────────────────────────────
  // KNA Provider 注册
  // ─────────────────────────────
  models: {
    mode: "merge",
    providers: {
      kna: {
        baseUrl: "https://code.wearekna.com",
        apiKey: "${ANTHROPIC_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-opus-4-7",   name: "Claude Opus 4.7" },
          { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
          { id: "claude-haiku-4-5",  name: "Claude Haiku 4.5" },
        ],
      },
    },
  },

  // ─────────────────────────────
  // Agent 默认模型 + Fallbacks
  // ─────────────────────────────
  agents: {
    defaults: {
      model: {
        primary: "kna/claude-sonnet-4-6",
        fallbacks: [
          "kna/claude-haiku-4-5",
        ],
      },

      // 辅助任务用 Haiku 省成本
      summarizationModel: { primary: "kna/claude-haiku-4-5" },
      titleModel:         { primary: "kna/claude-haiku-4-5" },
      compressionModel:   { primary: "kna/claude-haiku-4-5" },

      // 媒体理解
      imageModel: { primary: "kna/claude-sonnet-4-6" },
      pdfModel:   { primary: "kna/claude-sonnet-4-6" },
    },
  },
}

# ~/.openclaw/.env
ANTHROPIC_API_KEY=sk-kna-xxxxxxxxxxxxxxxxxxxxxxxx