1 line
29 KiB
JSON
1 line
29 KiB
JSON
{"repo": "aaronyang-ai/openclaw-guide-zh", "files": {"src/content/docs/ch03.md": {"4998b4c671ee1548cbf288cf05fbb1daacbd5ed4": {"t": 1785674200.2029707, "n": 9037, "h": "81a328563df90772", "c": "---\ntitle: \"第3章 10 分钟跑通第一个 Agent\"\ndescription: \"快速上手：onboard 引导、API Key 配置、Telegram Bot 接入\"\n---\n\n> 一句话：跑完 `openclaw onboard`、填个 API Key、接个 Telegram Bot，你的 AI 助手就上线了。\n\n---\n\n## 3.1 Onboard：交互式引导\n\n安装好 OpenClaw 后，运行引导命令开始初始化：\n\n```bash\nopenclaw onboard --install-daemon\n```\n\n`--install-daemon` 参数会在引导过程中同时安装后台守护进程（daemon）。daemon 负责保持 Gateway 持续运行、管理渠道连接、处理消息收发、维护 Agent 会话状态。\n\n引导流程会依次问你几个问题：选择模型提供商、填写 API Key、配置认证方式。我们一步步来。\n\n---\n\n## 3.2 选择模型提供商\n\n模型提供商就是\"AI 大脑\"的来源。OpenClaw 本身不包含 AI 模型，它需要连接外部的 LLM API。\n\n### 首推：DeepSeek（国内直连零门槛）\n\n**DeepSeek** 是国内用户最无脑的入门选择：\n\n- 国内直连，无需代理\n- 注册只需手机号\n- 按量计费，输入 $0.28/百万 token（缓存命中低至 $0.028/M），输出 $0.42/M（请以官网为准）\n- 中文理解能力强\n- DeepSeek-V3.2，128K context\n\n```bash\n# 运行 onboard 向导，在模型选择环节手动选择 DeepSeek\nopenclaw onboard\n# 或非交互式：用 custom-api-key 方式\nopenclaw onboard --auth-choice custom-api-key \\\n --custom-base-url \"https://api.deepseek.com/v1\" \\\n --custom-model-id \"deepseek-chat\" \\\n --custom-provider-id \"deepseek\"\n```\n\n注册步骤：\n1. 打开 https://platform.deepseek.com，注册账号\n2. 进入 \"API Keys\" 页面，创建新 Key（格式为 `sk-...`）\n3. 设置环境变量：\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-deepseek-key-here\necho 'export DEEPSEEK_API_KEY=sk-your-deepseek-key-here' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n### 方案二：云厂商 Coding Plan（超低价，首月 ¥7.9）\n\n> **注意**：以下定价信息截至 2026 年 3 月，请以各平台官网为准。\n\n2026 年最具性价比的入门方式。**一个专用 Key 就能切换多家国产模型**：\n\n| 平台 | 首月价 | 支持模型 |\n|------|--------|---------|\n| 阿里云百炼 | ¥7.9（Lite 套餐 3/20 起停止新购） | Qwen3.5-Plus、GLM-4.7、Kimi K2.5、MiniMax-M2.5 |\n| 腾讯云 LKEAP | ¥7.9 | 混元 2.0、Kimi K2.5、GLM-4.7、MiniMax-M2.5、tc-code |\n| 百度千帆 | ¥7.9 | GLM-4.7、MiniMax-M2.5、Kimi-K2.5、文心等 |\n\n> **重要**：云厂商 Coding Plan 的 Key（`sk-sp-` 开头）与普通 API Key 不同，需要配置专用 Base URL。完整配置方法详见第 8 章 8.2 节。\n\n### 方案三：独立厂商 Coding Plan / 按量计费\n\n> **注意**：以下定价信息截至 2026 年 3 月，请以各平台官网为准。\n\n各独立模型厂商也提供自己的订阅 Plan 或按量计费，直接使用其最新模型。完整套餐详情见第 8 章 8.2 节。\n\n| 厂商 | 计费方式 | 起步价 | 代表模型 | onboard 命令 |\n|------|---------|-------|---------|-------------|\n| DeepSeek | 按量（无订阅制） | 输入 ¥2.0/百万 token | V3.2 | `openclaw onboard --auth-choice custom-api-key ...` |\n| Kimi | 订阅制 | ¥49/月起 | K2.5 | `openclaw onboard --auth-choice moonshot-api-key` |\n| MiniMax | 订阅制 | ¥29/月起 | M2.7 | `openclaw onboard --auth-choice minimax-api` |\n| 智谱 GLM | 订阅制 | ¥49/月起 | GLM-5 | `openclaw onboard --auth-choice zai-api-key` |\n\n### 方案四：免费方案\n\n- **通义千问 Qwen**：OAuth 免费额度 2000 次/天\n- **小米 MiMo**：免费 API，mimo-v2-flash，262K context（需配置 Custom Provider）\n- **Ollama 本地模型**：完全离线、零成本\n\n```bash\n# Qwen（需先启用插件）\nopenclaw plugins enable qwen-portal-auth\nopenclaw gateway restart\nopenclaw models auth login --provider qwen-portal --set-default\n\n# MiMo（通过 Custom Provider 方式）\nopenclaw onboard --auth-choice custom-api-key \\\n --custom-base-url \"https://api.xiaomimimo.com/anthropic\" \\\n --custom-model-id \"mimo-v2-flash\" \\\n --custom-provider-id \"xiaomi\" \\\n --custom-compatibility anthropic\n\n# Ollama\ncurl -fsSL https://ollama.com/install.sh | sh\nollama pull qwen2.5:14b\n```\n\n### 方案五：OpenRouter（一个 Key 用所有模型）\n\nOpenRouter 是一个 LLM API 聚合平台，一个账号可以访问几十家模型提供商的上百个模型：\n\n```bash\nopenclaw onboard --auth-choice openrouter-api-key\n```\n\n注册步骤：打开 https://openrouter.ai → Sign Up → 创建 Key（格式 `sk-or-v1-...`）\n\n### 方案六：Anthropic / OpenAI（需海外账户）\n\n如果你有海外手机号和信用卡：\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-xxxxx # Anthropic\nexport OPENAI_API_KEY=sk-xxxxx # OpenAI\n```\n\n> **提示**：即使没有海外账户，也可以通过 OpenRouter 使用 Claude 和 GPT 模型。\n\n### 推荐策略总结\n\n| 方案 | 月费 | 适合谁 |\n|------|------|--------|\n| DeepSeek | 按量（极低，无订阅制） | **国内入门首选**，零门槛 |\n| 云厂商 Coding Plan | 首月 ¥7.9 | 一个 Key 多家模型 |\n| Kimi Code Plan | ¥49–¥699/月 | 长上下文 + Agent 集群 |\n| MiniMax Token Plan | ¥29–¥899/月 | 编码能力强 + 多模态 |\n| 智谱 GLM Coding Plan | ¥49–¥469/月 | GLM-5 工程能力 |\n| Qwen / MiMo / Ollama | 免费 | 轻度 / 体验 / 离线 |\n| OpenRouter | 按量 | 需要海外模型 |\n| 官方 API | 按量 | 有海外账户 |\n\n---\n\n## 3.3 连接第一个渠道：Telegram Bot\n\n渠道（Channel）是 Agent 对外沟通的\"嘴巴和耳朵\"。OpenClaw 支持 20+ 渠道，其中 **Telegram Bot 是最快上手的**——5 分钟就能搞定。国内用户也可以考虑**微信**——自 2026 年 3 月微信官方推出 ClawBot 插件后，微信接入同样只需两步（详见第 7 章）。\n\n### 第一步：在 Telegram 创建 Bot\n\n1. 打开 Telegram，搜索 **@BotFather**（Telegram 官方的 Bot 管理工具）\n2. 发送 `/newbot`\n3. 按提示输入 Bot 的显示名称（比如 `My AI Assistant`）\n4. 输入 Bot 的用户名（必须以 `bot` 结尾，比如 `my_ai_assistant_bot`）\n5. 创建成功后，BotFather 会返回一个 **Bot Token**：\n\n```\n123456789:ABCdefGHIjklMNOpqrsTUVwxyz\n```\n\n**把这个 Token 复制下来，千万不要泄露给别人！**\n\n### 第二步：配置 OpenClaw\n\n编辑配置文件 `~/.openclaw/openclaw.json`：\n\n```json5\n{\n channels: {\n telegram: {\n enabled: true,\n botToken: \"123456789:ABCdefGHIjklMNOpqrsTUVwxyz\", // 替换为你的 Token\n }\n }\n}\n```\n\n> **注意配置格式**：channels 是**对象格式**（不是数组），每个渠道用 `enabled: true` 启用。这是 OpenClaw 的标准写法。\n\n国内用户需要配置代理才能连接 Telegram：\n\n```json5\n{\n channels: {\n telegram: {\n enabled: true,\n botToken: \"your-token-here\",\n proxy: \"socks5://127.0.0.1:1080\", // 替换为你的代理地址\n // 支持 socks5:// 和 http://，也支持带认证的代理\n }\n }\n}\n```\n\n### 第三步：启动并验证\n\n```bash\n# 启动 Gateway（如果 daemon 没跑）\nopenclaw gateway start\n\n# 检查状态\nopenclaw gateway status\n```\n\n看到 `telegram connected` 就说明连上了。现在去 Telegram 找到你创建的 Bot，发一条消息试试！\n\n---\n\n## 3.4 Dashboard 控制台\n\nOpenClaw 内置了一个 Web 控制面板：\n\n```bash\nopenclaw dashboard\n# 自动打开浏览器，访问 http://127.0.0.1:18789\n```\n\nDashboard 提供的功能：\n- **实时对话**：直接在网页上和 Agent 聊天（不需要 Telegram 也能测试）\n- **会话管理**：查看所有渠道的聊天记录\n- **配置编辑**：可视化修改配置\n- **状态监控**：查看 Gateway、渠道、Agent 的运行状态\n- **技能管理**：浏览和安装 ClawHub 技能\n\n> **小贴士**：如果你只是想快速测试 Agent 能不能正常工作，Dashboard 的网页聊天是最方便的——不需要配置任何外部渠道。\n\n---\n\n## 3.5 发送第一条消息\n\n现在你有两种方式和 Agent 对话：\n\n**通过 Telegram**：打开 Telegram，找到你创建的 Bot，发送任意消息。\n\n**通过 Dashboard**：打开 `http://127.0.0.1:18789`，在聊天框中输入消息。\n\n如果一切正常，你会看到 Agent 给你一段流畅的回复。恭喜！\n\n### 聊天内命令\n\n在和 Agent 的对话中，你可以使用这些内置命令：\n\n| 命令 | 说明 |\n|------|------|\n| `/new` | 开始新会话（清空当前对话上下文） |\n| `/status` | 查看 Agent 当前状态 |\n| `/model <name>` | 切换模型（需在白名单中） |\n| `/compact` | 手动触发上下文压缩 |\n| `/reset` | 重置会话 |\n\n---\n\n## 3.6 完整配置示例\n\n### 示例一：DeepSeek + Telegram（国内用户推荐）\n\n```json5\n// ~/.openclaw/openclaw.json\n{\n agents: {\n defaults: {\n model: { primary: \"deepseek/deepseek-v3.2\" },\n },\n },\n models: {\n providers: {\n deepseek: {\n baseUrl: \"https://api.deepseek.com/v1\",\n api: \"openai-completions\",\n },\n },\n },\n channels: {\n telegram: {\n enabled: true,\n botToken: \"123456789:ABCdefGHIjklMNOpqrsTUVwxyz\",\n proxy: \"socks5://127.0.0.1:1080\", // 国内需要代理\n },\n },\n}\n```\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-deepseek-key-here\n```\n\n### 示例二：阿里云百炼 Coding Plan + Telegram\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"dashscope-coding/qwen3.5-plus\" },\n },\n },\n models: {\n providers: {\n \"dashscope-coding\": {\n baseUrl: \"https://coding.dashscope.aliyuncs.com/v1\",\n api: \"openai-completions\",\n },\n },\n },\n channels: {\n telegram: {\n enabled: true,\n botToken: \"your-token\",\n proxy: \"socks5://127.0.0.1:1080\",\n },\n },\n}\n```\n\n```bash\nexport DASHSCOPE_CODING_API_KEY=\"sk-sp-xxxxx\"\n```\n\n### 示例三：只用 Dashboard（不接任何外部渠道）\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"deepseek/deepseek-v3.2\" },\n },\n },\n models: {\n providers: {\n deepseek: {\n baseUrl: \"https://api.deepseek.com/v1\",\n api: \"openai-completions\",\n },\n },\n },\n}\n```\n\n启动后访问 `http://127.0.0.1:18789` 即可开始对话。\n\n---\n\n## 3.7 常见问题排查\n\n### 问题一：端口 18789 被占用\n\n```\nError: Port 18789 is already in use\n```\n\n```bash\n# 查看谁占了端口并杀掉\nlsof -i :18789\nkill $(lsof -ti :18789)\nopenclaw gateway start\n\n# 或者换端口（在 openclaw.json 中）\n# gateway: { port: 18790 }\n```\n\n### 问题二：API Key 无效\n\n```\nError: Authentication failed. Invalid API key.\n```\n\n排查步骤：\n\n```bash\n# 1. 确认环境变量已设置（不为空）\necho $DEEPSEEK_API_KEY\n\n# 2. 确认 Key 格式正确（DeepSeek 以 sk- 开头，OpenRouter 以 sk-or- 开头）\n\n# 3. 确认没有多余空格或换行，重新设置\nexport DEEPSEEK_API_KEY=\"sk-your-key-here\"\n\n# 4. 重启 Gateway 让新环境变量生效\nopenclaw gateway restart\n```\n\n### 问题三：Telegram Bot 不回消息\n\n```bash\n# 1. 确认 Gateway 在运行\nopenclaw gateway status\n\n# 2. 确认 Telegram 渠道已连接（看 Channels 下是否 connected）\n\n# 3. 查看日志找错误\nopenclaw logs --limit 50\n\n# 4. 确认 Bot Token 正确（在 Telegram 给 @BotFather 发 /mybots）\n```\n\n### 问题四：国内网络连不上 Telegram\n\n必须配置代理。在 channels.telegram 中添加 `proxy` 字段：\n\n```json5\n{\n channels: {\n telegram: {\n enabled: true,\n botToken: \"your-token\",\n proxy: \"socks5://127.0.0.1:1080\", // SOCKS5 代理\n // proxy: \"http://127.0.0.1:7890\", // HTTP 代理\n }\n }\n}\n```\n\n> **提醒**：proxy 配置是渠道级别的，只影响 Telegram 渠道的网络连接。LLM API 如果也需要代理，通过系统环境变量 `https_proxy` 设置。\n\n### 问题五：API 调用失败（401 / 429 / 500）\n\n| 状态码 | 原因 | 解决 |\n|--------|------|------|\n| 401 | API Key 无效或过期 | 重新生成 Key |\n| 429 | 请求频率超限 | 稍等再试，或升级账户 |\n| 500 | 服务端故障 | 等一会儿再试，或临时切换模型 |\n\n> **新手最常踩的三个坑**：\n> 1. API Key 忘了加引号，shell 把特殊字符解析错了\n> 2. 环境变量设了但忘了 `source ~/.bashrc`，变量没生效\n> 3. 改了配置文件但没重启 Gateway——配置没生效\n\n---\n\n## 3.8 小结\n\n| 步骤 | 操作 |\n|------|------|\n| 1. 初始化引导 | `openclaw onboard --install-daemon` |\n| 2. 配置 API Key | 设置对应的环境变量 |\n| 3. 创建 Telegram Bot | 在 @BotFather 创建 Bot，获取 Token |\n| 4. 写入配置 | 编辑 `~/.openclaw/openclaw.json`，填入 botToken |\n| 5. 打开 Dashboard | `openclaw dashboard` |\n| 6. 检查状态 | `openclaw gateway status` |\n| 7. 开始对话 | 通过 Telegram 或 Dashboard 发送消息 |\n\n你的 AI Agent 已经在运行了。但它目前还只是一个\"默认 Agent\"——没有个性、没有技能、只连了一个渠道。接下来的章节，我们会深入 Gateway 配置、Agent 人设定制、多渠道接入和技能生态，一步步把它打造成你的专属 AI 助手。\n"}}, "src/content/docs/ch08.md": {"4998b4c671ee1548cbf288cf05fbb1daacbd5ed4": {"t": 1785674220.2535162, "n": 10924, "h": "5364f809ead71d1d", "c": "---\ntitle: \"第8章 模型接入全攻略\"\ndescription: \"30+ 模型供应商统一配置，国产模型首推方案\"\n---\n\n> 一句话：OpenClaw 支持 30+ 模型提供商，国产模型首推 DeepSeek / Kimi / MiniMax / GLM，云厂商 Coding Plan 首月 ¥7.9 性价比拉满。\n\n---\n\n## 8.1 模型配置统一方式\n\n所有模型都使用 `provider/model` 格式指定：\n\n```json5\n{\n agents: {\n defaults: {\n model: {\n primary: \"deepseek/deepseek-v3.2\", // 国产直连\n // primary: \"minimax/MiniMax-M2.7\", // MiniMax\n // primary: \"openrouter/anthropic/claude-sonnet-4-6\", // 通过 OpenRouter\n },\n },\n },\n}\n```\n\n### API Key 管理\n\n推荐通过环境变量设置（比写在配置文件里更安全）：\n\n```bash\nexport DEEPSEEK_API_KEY=\"sk-xxxxx\"\nexport MINIMAX_API_KEY=\"xxxxx\"\nexport MOONSHOT_API_KEY=\"sk-xxxxx\"\nexport ZAI_API_KEY=\"xxxxx\"\nexport OPENROUTER_API_KEY=\"sk-or-xxxxx\"\n```\n\n也可以通过配置文件的 `env` 段集中管理（参见第 4 章 4.7 节）。\n\n---\n\n## 8.2 Coding Plan 方案详解\n\n> **注意**：以下定价信息截至 2026 年 3 月，请以各平台官网为准。\n\n### 云厂商聚合 Plan\n\n2026 年最具性价比的入门方式——**一个专用 Key 就能切换多家国产模型**，首月仅 ¥7.9。\n\n**阿里云百炼 Coding Plan**：\n\n| 项目 | 详情 |\n|------|------|\n| 首月价 | ¥7.9（Lite 套餐自 2026-03-20 起停止新购，Pro 套餐首月 ¥39.9） |\n| 支持模型 | Qwen3.5-Plus、GLM-4.7、Kimi K2.5、MiniMax-M2.5 |\n| Key 格式 | `sk-sp-` 开头 |\n| Base URL | `https://coding.dashscope.aliyuncs.com/v1` |\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"dashscope-coding/qwen3.5-plus\" },\n },\n },\n models: {\n providers: {\n \"dashscope-coding\": {\n api: \"openai-completions\",\n baseUrl: \"https://coding.dashscope.aliyuncs.com/v1\",\n },\n },\n },\n}\n```\n\n```bash\nexport DASHSCOPE_CODING_API_KEY=\"sk-sp-xxxxx\"\n```\n\n**腾讯云 LKEAP Coding Plan**：\n\n| 项目 | 详情 |\n|------|------|\n| 首月价 | ¥7.9 |\n| 支持模型 | 混元 2.0、Kimi K2.5、GLM-4.7、MiniMax-M2.5、tc-code |\n| Base URL | `https://api.lkeap.cloud.tencent.com/coding/v3` |\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"lkeap-coding/hunyuan-2.0\" },\n },\n },\n models: {\n providers: {\n \"lkeap-coding\": {\n api: \"openai-completions\",\n baseUrl: \"https://api.lkeap.cloud.tencent.com/coding/v3\",\n },\n },\n },\n}\n```\n\n```bash\nexport LKEAP_CODING_API_KEY=\"sk-sp-xxxxx\"\n```\n\n**百度千帆 Coding Plan**：\n\n| 项目 | 详情 |\n|------|------|\n| 首月价 | ¥7.9 |\n| 支持模型 | GLM-4.7、MiniMax-M2.5、Kimi-K2.5、文心等 |\n\n### 独立厂商 Coding Plan\n\n> **注意**：以下定价信息截至 2026 年 3 月，请以各平台官网为准。定价可能随时调整。\n\n除了云厂商聚合方案，各独立模型厂商也提供自己的订阅 Plan（或按量计费），直接使用自家最新模型：\n\n#### DeepSeek（按量计费，非订阅制）\n\nDeepSeek 不提供订阅制 Coding Plan，采用纯按量计费模式。价格极低，适合用量波动大的开发者。\n\n| 项目 | 详情 |\n|------|------|\n| 计费模式 | 按量计费（无月费） |\n| 代表模型 | DeepSeek-V3.2，128K context |\n| 输入价格 | ¥2.0/百万 token（缓存命中 ¥0.2/百万 token） |\n| 输出价格 | ¥3.0/百万 token |\n| 新用户福利 | 注册赠送 500 万–1000 万免费 token |\n| 错峰优惠 | 每日 00:30–08:30 输入/输出再打折 |\n\n> **提示**：也可通过阿里云百炼、腾讯云 LKEAP、百度千帆等云厂商 Coding Plan 间接使用 DeepSeek 系列模型。\n\n#### Kimi（月之暗面）Code Plan\n\nKimi Code Plan 基于 K2.5 模型（256K–512K context），分四档订阅：\n\n| 套餐 | 月费 | 定位 |\n|------|------|------|\n| Andante（行板） | ¥49/月 | 入门，含 Kimi 会员权益 |\n| Moderato（中板） | ¥99/月 | 推荐档，每周更新额度，多设备登录 |\n| Allegretto | ¥199/月 | 高级用户，更高并发上限 |\n| Allegro | ¥699/月 | 重度开发，最高限额 |\n\n- 额度按 5 小时滚动窗口 + 每周重置\n- 仅统计未命中缓存的 token，缓存命中不消耗额度\n- 3 倍额度活动已从限时转为永久\n- 年付可享优惠（Andante ¥39/月起，Moderato ¥79/月起）\n- 兼容 Claude Code、Kimi CLI、VS Code 插件等\n\n#### MiniMax Token Plan（原 Coding Plan 升级）\n\n2026 年 3 月，MiniMax 将 Coding Plan 升级为 Token Plan，搭载 M2.7 编程模型。分为标准版和极速版两条产品线：\n\n**标准版：**\n\n| 套餐 | 月费 | 定位 |\n|------|------|------|\n| Starter | ¥29/月 | 轻度使用，不含多模态权益 |\n| Plus | ¥49/月 | 主力档，赠送多模态额度 |\n| Max | ¥119/月 | 重度使用，高并发 |\n\n**极速版（100+ TPS 高速推理）：**\n\n| 套餐 | 月费 |\n|------|------|\n| Plus-极速 | ¥98/月 |\n| Max-极速 | ¥199/月 |\n| Ultra-极速 | ¥899/月 |\n\n- 额度按 5 小时滚动窗口重置\n- Plus 及以上赠送海螺视频、语音合成、音乐生成等多模态额度\n- API 按量：M2.7 输入 $0.30/M、输出 $1.20/M\n- 年付可省约 17%\n- 兼容 Claude Code、Cursor、VS Code 插件等\n\n#### 智谱 GLM Coding Plan\n\n智谱 GLM Coding Plan 基于 GLM-5 / GLM-4.7 模型（200K context），分三档订阅：\n\n| 套餐 | 月费 | 可用模型 |\n|------|------|---------|\n| Lite | ¥49/月 | GLM-4.7 |\n| Pro | ¥149/月 | GLM-4.7 + GLM-5 |\n| Max | ¥469/月 | GLM-4.7 + GLM-5（最高优先级） |\n\n- 额度按 5 小时滚动窗口 + 每周重置（Lite ~80 prompts/5h，Pro ~400/5h，Max ~1600/5h）\n- GLM-5 调用消耗 3 倍额度（仅 Pro/Max 可用）\n- 2026 年 2 月取消首购优惠并调价\n- 连续包季享 9 折，包年享 7 折\n- 兼容 Claude Code、Cursor、VS Code 插件等\n\n### 免费/按量方案\n\n| 方案 | 费用 | 特点 |\n|------|------|------|\n| 通义千问 Qwen | OAuth 免费 2000 次/天 | 零成本体验 |\n| 小米 MiMo | 免费 | mimo-v2-flash，262K context |\n| Ollama | 完全免费 | 本地运行，无需网络 |\n\n---\n\n## 8.3 国产模型逐一配置\n\n### DeepSeek\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"deepseek/deepseek-v3.2\" },\n },\n },\n models: {\n providers: {\n deepseek: {\n api: \"openai-completions\",\n baseUrl: \"https://api.deepseek.com/v1\",\n },\n },\n },\n}\n```\n\n```bash\nexport DEEPSEEK_API_KEY=\"sk-xxxxx\"\n```\n\n### 月之暗面 Kimi\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"moonshot/kimi-k2.5\" },\n },\n },\n}\n```\n\n```bash\nexport MOONSHOT_API_KEY=\"sk-xxxxx\"\n```\n\n### MiniMax\n\n> **注意**：MiniMax M2.7 于 2026-03-18 发布，晚于本书基于的 OpenClaw v2026.3.13。使用 M2.7 需要在 `models.providers` 中手动配置模型定义（见下方）。M2.5 可通过 `openclaw onboard` 向导或 `openclaw configure` 自动配置，也可以手动添加 `models.providers.minimax` 配置块（见下方完整示例）。\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"minimax/MiniMax-M2.7\" },\n // 内置版本：minimax/MiniMax-M2.5（无需额外 provider 配置）\n },\n },\n // M2.7 需要手动添加 provider 配置（M2.5 不需要）\n models: {\n mode: \"merge\",\n providers: {\n minimax: {\n baseUrl: \"https://api.minimax.io/anthropic\",\n apiKey: \"${MINIMAX_API_KEY}\",\n api: \"anthropic-messages\",\n models: [{\n id: \"MiniMax-M2.7\",\n name: \"MiniMax M2.7\",\n reasoning: true,\n input: [\"text\"],\n cost: { input: 0.3, output: 1.2 },\n contextWindow: 204800,\n maxTokens: 131072,\n }],\n },\n },\n },\n}\n```\n\n```bash\nexport MINIMAX_API_KEY=\"xxxxx\"\n```\n\n### 智谱 GLM\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"zai/glm-5\" },\n },\n },\n}\n```\n\n```bash\nexport ZAI_API_KEY=\"xxxxx\"\n```\n\n### 百度千帆\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"qianfan/ernie-4-turbo\" },\n },\n },\n}\n```\n\n```bash\nexport QIANFAN_API_KEY=\"xxxxx\"\n```\n\n### 通义千问\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"dashscope/qwen3.5-plus\" },\n },\n },\n}\n```\n\n或使用 OAuth 免费额度（2000 次/天）：\n\n```bash\nopenclaw plugins enable qwen-portal-auth\nopenclaw gateway restart # 需要重启 Gateway 加载插件\nopenclaw models auth login --provider qwen-portal --set-default\n```\n\n### 小米 MiMo\n\nMiMo 使用 Anthropic Messages API 兼容格式，需要配置 Custom Provider：\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"xiaomi/mimo-v2-flash\" },\n },\n },\n models: {\n providers: {\n xiaomi: {\n baseUrl: \"https://api.xiaomimimo.com/anthropic\",\n api: \"anthropic-messages\",\n apiKey: \"XIAOMI_API_KEY\",\n models: [{\n id: \"mimo-v2-flash\",\n name: \"Xiaomi MiMo V2 Flash\",\n contextWindow: 262144,\n maxTokens: 65536,\n cost: { input: 0, output: 0 },\n }],\n },\n },\n },\n}\n```\n\n```bash\nexport XIAOMI_API_KEY=\"xxxxx\"\n```\n\n---\n\n## 8.4 国际模型（需海外账户）\n\n### Anthropic\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"anthropic/claude-sonnet-4-6\" },\n // 或 \"anthropic/claude-opus-4-6\"（更强但更贵）\n },\n },\n}\n```\n\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-xxxxx\"\n```\n\n> 需要海外手机号注册、海外信用卡付款。国内可通过 OpenRouter 使用。\n\n### OpenAI\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"openai/gpt-5.4\" },\n },\n },\n}\n```\n\n```bash\nexport OPENAI_API_KEY=\"sk-xxxxx\"\n```\n\n### Google Gemini\n\n> **注意**：Gemini 通过插件支持，使用前需确认插件已启用。模型 ID 请以 `openclaw models list --provider google` 实际输出为准。\n\n<!-- 以下模型 ID 基于 OpenClaw 测试文档记录，实际可用版本可能随 Google 更新变化 -->\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"google/gemini-3-flash-preview\" },\n // 其他可选：google/gemini-3.1-pro-preview\n },\n },\n}\n```\n\n```bash\nexport GEMINI_API_KEY=\"xxxxx\"\n# 或通过 onboard：openclaw onboard --auth-choice gemini-api-key\n```\n\n---\n\n## 8.5 本地模型（Ollama）\n\nOllama 让你在本地运行开源模型，完全免费、完全离线：\n\n```bash\n# 安装 Ollama\ncurl -fsSL https://ollama.com/install.sh | sh\n\n# 拉取推荐的国产开源模型\nollama pull qwen2.5:14b # 通义千问 14B\nollama pull glm4:9b # GLM4 9B\nollama pull deepseek-coder-v2:16b # DeepSeek Coder\n```\n\n配置：\n\n```json5\n{\n agents: {\n defaults: {\n model: { primary: \"ollama/qwen2.5:14b\" },\n },\n },\n models: {\n providers: {\n ollama: { baseUrl: \"http://localhost:11434\", api: \"ollama\" },\n },\n },\n}\n```\n\n> **硬件需求**：7B 模型约需 8GB 内存/显存，14B 约需 16GB，70B 约需 48GB。\n\n---\n\n## 8.6 OpenRouter（一个 Key 用所有模型）\n\nOpenRouter 是一个模型聚合平台，一个 API Key 可以访问上百个模型：\n\n```json5\n{\n agents: {\n defaults: {\n model: {\n primary: \"openrouter/anthropic/claude-sonnet-4-6\",\n // 或 \"openrouter/openai/gpt-5.4\"\n // 或 \"openrouter/auto\" // 自动选择最优模型\n },\n },\n },\n}\n```\n\n```bash\nexport OPENROUTER_API_KEY=\"sk-or-v1-xxxxx\"\n```\n\nOpenRouter 格式：`openrouter/provider/model`。\n\n---\n\n## 8.7 Model Failover 两阶段回退\n\nOpenClaw 的模型回退分两个阶段：\n\n**第一阶段：fallbacks 列表**\n\n```json5\n{\n agents: {\n defaults: {\n model: {\n primary: \"deepseek/deepseek-v3.2\",\n fallbacks: [\n \"minimax/MiniMax-M2.5\", // 第一备选\n \"moonshot/kimi-k2.5\", // 第二备选\n ],\n },\n },\n },\n}\n```\n\n主模型返回错误时，按顺序尝试 fallbacks 列表中的模型。\n\n**第二阶段：自动降级**\n\n如果 fallbacks 也全部失败，Gateway 会在日志中记录错误并通知用户模型不可用。\n\n---\n\n## 8.8 模型选型建议表\n\n| 模型 | 上下文 | 编码能力 | Tool Calling | 中文 | 成本 |\n|------|-------|---------|-------------|------|------|\n| DeepSeek V3.2 | 128K | 强 | 好 | 强 | 极低 |\n| MiniMax M2.7 | 205K | 很强 | 好 | 强 | 低 |\n| Kimi K2.5 | 256K | 强 | 好 | 强 | 中 |\n| GLM-5 | 200K | 强 | 好 | 很强 | 低 |\n| Qwen3.5-Plus | 1M | 强 | 好 | 很强 | 低 |\n| Claude Sonnet 4.6 | 1M | 很强 | 很好 | 好 | 中 |\n| GPT-5.4 | 272K（最大 1M） | 很强 | 很好 | 好 | 较高 |\n\n### Tool Calling 可靠性\n\nAgent 的核心能力依赖 Tool Calling（工具调用）。不同模型的 Tool Calling 可靠性差异较大：\n\n- **可靠**：Claude Sonnet/Opus、GPT-5.4、MiniMax M2.7、Kimi K2.5\n- **较好**：DeepSeek V3.2、GLM-5、Qwen3.5\n- **一般**：小型本地模型（7B 以下），Tool Calling 容易出错\n\n> **建议**：如果 Agent 需要频繁使用工具（浏览器、代码执行等），优先选择 Tool Calling 可靠性高的模型。\n\n---\n\n## 8.9 成本控制策略\n\n### 策略一：Coding Plan 封顶\n\n云厂商 Coding Plan 月费固定，不怕超支。适合日常使用。\n\n### 策略二：fallbacks 降级\n\n高频场景用便宜模型，fallbacks 里放贵但强的模型做兜底：\n\n```json5\n{\n agents: {\n defaults: {\n model: {\n primary: \"deepseek/deepseek-v3.2\", // 便宜\n fallbacks: [\"minimax/MiniMax-M2.5\"], // 备选\n },\n },\n },\n}\n```\n\n### 策略三：Heartbeat 成本优化\n\n如果使用 Heartbeat 心跳（第 10 章），开启 `lightContext: true` 可以大幅降低每次心跳的 token 消耗。\n\n### 策略四：图片压缩\n\n设置 `imageMaxDimensionPx` 压缩用户发送的图片，减少 token 消耗：\n\n```json5\n{\n agents: {\n defaults: {\n imageMaxDimensionPx: 800, // 极限省 token\n },\n },\n}\n```\n\n### 策略五：及时 Compact\n\n对话过长时，上下文中的旧消息会重复消耗 token。及时 `/compact` 或让 Agent 自动 compaction 可以控制成本。\n\n---\n\n## 8.10 小结\n\n| 主题 | 要点 |\n|------|------|\n| 统一格式 | `provider/model`，API Key 通过环境变量设置 |\n| Coding Plan | 云厂商首月 ¥7.9，一个 Key 多家模型 |\n| 国产首选 | DeepSeek（零门槛按量）、MiniMax（编码强）、Kimi（长上下文） |\n| 国际模型 | 通过 OpenRouter 使用，或直连（需海外账户） |\n| 本地模型 | Ollama，推荐 qwen2.5:14b |\n| Failover | primary + fallbacks 两阶段回退 |\n| 成本控制 | Coding Plan 封顶 / fallbacks 降级 / 图片压缩 / Compact |\n\n下一章进入多 Agent 架构——让多个 Agent 协同工作。\n"}}}} |