第3章 10 分钟跑通第一个 Agent

一句话：跑完 openclaw onboard、填个 API Key、接个 Telegram Bot，你的 AI 助手就上线了。

---

3.1 Onboard：交互式引导

安装好 OpenClaw 后，运行引导命令开始初始化：

openclaw onboard --install-daemon

--install-daemon 参数会在引导过程中同时安装后台守护进程（daemon）。daemon 负责保持 Gateway 持续运行、管理渠道连接、处理消息收发、维护 Agent 会话状态。

引导流程会依次问你几个问题：选择模型提供商、填写 API Key、配置认证方式。我们一步步来。

---

3.2 选择模型提供商

模型提供商就是”AI 大脑”的来源。OpenClaw 本身不包含 AI 模型，它需要连接外部的 LLM API。

首推：DeepSeek（国内直连零门槛）

DeepSeek 是国内用户最无脑的入门选择：

• 国内直连，无需代理
• 注册只需手机号
• 按量计费，输入 $0.28/百万 token（缓存命中低至 $0.028/M），输出 $0.42/M（请以官网为准）
• 中文理解能力强
• DeepSeek-V3.2，128K context

# 运行 onboard 向导，在模型选择环节手动选择 DeepSeek
openclaw onboard
# 或非交互式：用 custom-api-key 方式
openclaw onboard --auth-choice custom-api-key \
  --custom-base-url "https://api.deepseek.com/v1" \
  --custom-model-id "deepseek-chat" \
  --custom-provider-id "deepseek"

注册步骤：

1. 打开 https://platform.deepseek.com，注册账号
2. 进入 “API Keys” 页面，创建新 Key（格式为 sk-...）
3. 设置环境变量：

export DEEPSEEK_API_KEY=sk-your-deepseek-key-here
echo 'export DEEPSEEK_API_KEY=sk-your-deepseek-key-here' >> ~/.zshrc
source ~/.zshrc

方案二：云厂商 Coding Plan（超低价，首月 ¥7.9）

注意：以下定价信息截至 2026 年 3 月，请以各平台官网为准。

2026 年最具性价比的入门方式。一个专用 Key 就能切换多家国产模型：

平台	首月价	支持模型
阿里云百炼	¥7.9（Lite 套餐 3/20 起停止新购）	Qwen3.5-Plus、GLM-4.7、Kimi K2.5、MiniMax-M2.5
腾讯云 LKEAP	¥7.9	混元 2.0、Kimi K2.5、GLM-4.7、MiniMax-M2.5、tc-code
百度千帆	¥7.9	GLM-4.7、MiniMax-M2.5、Kimi-K2.5、文心等

重要：云厂商 Coding Plan 的 Key（sk-sp- 开头）与普通 API Key 不同，需要配置专用 Base URL。完整配置方法详见第 8 章 8.2 节。

方案三：独立厂商 Coding Plan / 按量计费

注意：以下定价信息截至 2026 年 3 月，请以各平台官网为准。

各独立模型厂商也提供自己的订阅 Plan 或按量计费，直接使用其最新模型。完整套餐详情见第 8 章 8.2 节。

厂商	计费方式	起步价	代表模型	onboard 命令
DeepSeek	按量（无订阅制）	输入 ¥2.0/百万 token	V3.2	openclaw onboard --auth-choice custom-api-key ...
Kimi	订阅制	¥49/月起	K2.5	openclaw onboard --auth-choice moonshot-api-key
MiniMax	订阅制	¥29/月起	M2.7	openclaw onboard --auth-choice minimax-api
智谱 GLM	订阅制	¥49/月起	GLM-5	openclaw onboard --auth-choice zai-api-key

方案四：免费方案

• 通义千问 Qwen：OAuth 免费额度 2000 次/天
• 小米 MiMo：免费 API，mimo-v2-flash，262K context（需配置 Custom Provider）
• Ollama 本地模型：完全离线、零成本

# Qwen（需先启用插件）
openclaw plugins enable qwen-portal-auth
openclaw gateway restart
openclaw models auth login --provider qwen-portal --set-default

# MiMo（通过 Custom Provider 方式）
openclaw onboard --auth-choice custom-api-key \
  --custom-base-url "https://api.xiaomimimo.com/anthropic" \
  --custom-model-id "mimo-v2-flash" \
  --custom-provider-id "xiaomi" \
  --custom-compatibility anthropic

# Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5:14b

方案五：OpenRouter（一个 Key 用所有模型）

OpenRouter 是一个 LLM API 聚合平台，一个账号可以访问几十家模型提供商的上百个模型：

openclaw onboard --auth-choice openrouter-api-key

注册步骤：打开 https://openrouter.ai → Sign Up → 创建 Key（格式 sk-or-v1-...）

方案六：Anthropic / OpenAI（需海外账户）

如果你有海外手机号和信用卡：

export ANTHROPIC_API_KEY=sk-ant-xxxxx   # Anthropic
export OPENAI_API_KEY=sk-xxxxx          # OpenAI

提示：即使没有海外账户，也可以通过 OpenRouter 使用 Claude 和 GPT 模型。

推荐策略总结

方案	月费	适合谁
DeepSeek	按量（极低，无订阅制）	国内入门首选，零门槛
云厂商 Coding Plan	首月 ¥7.9	一个 Key 多家模型
Kimi Code Plan	¥49–¥699/月	长上下文 + Agent 集群
MiniMax Token Plan	¥29–¥899/月	编码能力强 + 多模态
智谱 GLM Coding Plan	¥49–¥469/月	GLM-5 工程能力
Qwen / MiMo / Ollama	免费	轻度 / 体验 / 离线
OpenRouter	按量	需要海外模型
官方 API	按量	有海外账户

---

3.3 连接第一个渠道：Telegram Bot

渠道（Channel）是 Agent 对外沟通的”嘴巴和耳朵”。OpenClaw 支持 20+ 渠道，其中 Telegram Bot 是最快上手的——5 分钟就能搞定。国内用户也可以考虑微信——自 2026 年 3 月微信官方推出 ClawBot 插件后，微信接入同样只需两步（详见第 7 章）。

第一步：在 Telegram 创建 Bot

1. 打开 Telegram，搜索 @BotFather（Telegram 官方的 Bot 管理工具）
2. 发送 /newbot
3. 按提示输入 Bot 的显示名称（比如 My AI Assistant）
4. 输入 Bot 的用户名（必须以 bot 结尾，比如 my_ai_assistant_bot）
5. 创建成功后，BotFather 会返回一个 Bot Token：

123456789:ABCdefGHIjklMNOpqrsTUVwxyz

把这个 Token 复制下来，千万不要泄露给别人！

第二步：配置 OpenClaw

编辑配置文件 ~/.openclaw/openclaw.json：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",  // 替换为你的 Token
    }
  }
}

注意配置格式：channels 是对象格式（不是数组），每个渠道用 enabled: true 启用。这是 OpenClaw 的标准写法。

国内用户需要配置代理才能连接 Telegram：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-token-here",
      proxy: "socks5://127.0.0.1:1080",  // 替换为你的代理地址
      // 支持 socks5:// 和 http://，也支持带认证的代理
    }
  }
}

第三步：启动并验证

# 启动 Gateway（如果 daemon 没跑）
openclaw gateway start

# 检查状态
openclaw gateway status

看到 telegram connected 就说明连上了。现在去 Telegram 找到你创建的 Bot，发一条消息试试！

---

3.4 Dashboard 控制台

OpenClaw 内置了一个 Web 控制面板：

openclaw dashboard
# 自动打开浏览器，访问 http://127.0.0.1:18789

Dashboard 提供的功能：

• 实时对话：直接在网页上和 Agent 聊天（不需要 Telegram 也能测试）
• 会话管理：查看所有渠道的聊天记录
• 配置编辑：可视化修改配置
• 状态监控：查看 Gateway、渠道、Agent 的运行状态
• 技能管理：浏览和安装 ClawHub 技能

小贴士：如果你只是想快速测试 Agent 能不能正常工作，Dashboard 的网页聊天是最方便的——不需要配置任何外部渠道。

---

3.5 发送第一条消息

现在你有两种方式和 Agent 对话：

通过 Telegram：打开 Telegram，找到你创建的 Bot，发送任意消息。

通过 Dashboard：打开 http://127.0.0.1:18789，在聊天框中输入消息。

如果一切正常，你会看到 Agent 给你一段流畅的回复。恭喜！

聊天内命令

在和 Agent 的对话中，你可以使用这些内置命令：

命令	说明
/new	开始新会话（清空当前对话上下文）
/status	查看 Agent 当前状态
/model <name>	切换模型（需在白名单中）
/compact	手动触发上下文压缩
/reset	重置会话

---

3.6 完整配置示例

示例一：DeepSeek + Telegram（国内用户推荐）

~/.openclaw/openclaw.json

{
  agents: {
    defaults: {
      model: { primary: "deepseek/deepseek-v3.2" },
    },
  },
  models: {
    providers: {
      deepseek: {
        baseUrl: "https://api.deepseek.com/v1",
        api: "openai-completions",
      },
    },
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      proxy: "socks5://127.0.0.1:1080",  // 国内需要代理
    },
  },
}

export DEEPSEEK_API_KEY=sk-your-deepseek-key-here

示例二：阿里云百炼 Coding Plan + Telegram

{
  agents: {
    defaults: {
      model: { primary: "dashscope-coding/qwen3.5-plus" },
    },
  },
  models: {
    providers: {
      "dashscope-coding": {
        baseUrl: "https://coding.dashscope.aliyuncs.com/v1",
        api: "openai-completions",
      },
    },
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-token",
      proxy: "socks5://127.0.0.1:1080",
    },
  },
}

export DASHSCOPE_CODING_API_KEY="sk-sp-xxxxx"

示例三：只用 Dashboard（不接任何外部渠道）

{
  agents: {
    defaults: {
      model: { primary: "deepseek/deepseek-v3.2" },
    },
  },
  models: {
    providers: {
      deepseek: {
        baseUrl: "https://api.deepseek.com/v1",
        api: "openai-completions",
      },
    },
  },
}

启动后访问 http://127.0.0.1:18789 即可开始对话。

---

3.7 常见问题排查

问题一：端口 18789 被占用

Error: Port 18789 is already in use

# 查看谁占了端口并杀掉
lsof -i :18789
kill $(lsof -ti :18789)
openclaw gateway start

# 或者换端口（在 openclaw.json 中）
# gateway: { port: 18790 }

问题二：API Key 无效

Error: Authentication failed. Invalid API key.

排查步骤：

# 1. 确认环境变量已设置（不为空）
echo $DEEPSEEK_API_KEY

# 2. 确认 Key 格式正确（DeepSeek 以 sk- 开头，OpenRouter 以 sk-or- 开头）

# 3. 确认没有多余空格或换行，重新设置
export DEEPSEEK_API_KEY="sk-your-key-here"

# 4. 重启 Gateway 让新环境变量生效
openclaw gateway restart

问题三：Telegram Bot 不回消息

# 1. 确认 Gateway 在运行
openclaw gateway status

# 2. 确认 Telegram 渠道已连接（看 Channels 下是否 connected）

# 3. 查看日志找错误
openclaw logs --limit 50

# 4. 确认 Bot Token 正确（在 Telegram 给 @BotFather 发 /mybots）

问题四：国内网络连不上 Telegram

必须配置代理。在 channels.telegram 中添加 proxy 字段：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-token",
      proxy: "socks5://127.0.0.1:1080",  // SOCKS5 代理
      // proxy: "http://127.0.0.1:7890",   // HTTP 代理
    }
  }
}

提醒：proxy 配置是渠道级别的，只影响 Telegram 渠道的网络连接。LLM API 如果也需要代理，通过系统环境变量 https_proxy 设置。

问题五：API 调用失败（401 / 429 / 500）

状态码	原因	解决
401	API Key 无效或过期	重新生成 Key
429	请求频率超限	稍等再试，或升级账户
500	服务端故障	等一会儿再试，或临时切换模型

新手最常踩的三个坑：

1. API Key 忘了加引号，shell 把特殊字符解析错了
2. 环境变量设了但忘了 source ~/.bashrc，变量没生效
3. 改了配置文件但没重启 Gateway——配置没生效

---

3.8 小结

步骤	操作
1. 初始化引导	openclaw onboard --install-daemon
2. 配置 API Key	设置对应的环境变量
3. 创建 Telegram Bot	在 @BotFather 创建 Bot，获取 Token
4. 写入配置	编辑 ~/.openclaw/openclaw.json，填入 botToken
5. 打开 Dashboard	openclaw dashboard
6. 检查状态	openclaw gateway status
7. 开始对话	通过 Telegram 或 Dashboard 发送消息

你的 AI Agent 已经在运行了。但它目前还只是一个”默认 Agent”——没有个性、没有技能、只连了一个渠道。接下来的章节，我们会深入 Gateway 配置、Agent 人设定制、多渠道接入和技能生态，一步步把它打造成你的专属 AI 助手。