PalmClaw LLM Provider配置教程:如何接入自己的API Key并开始第一个对话
PalmClaw LLM Provider配置教程:如何接入自己的API Key并开始第一个对话
PalmClaw 是一个原生运行在 Android 手机上的 AI Agent 框架,它本身不内置模型服务——LLM Provider(模型提供方)配置是整个使用流程的第一步。本文是一份面向新手的完整指南:教你如何配置 PalmClaw 的 LLM Provider、正确填入自己的 API Key、通过连接测试,最终开始你的第一个 Agent 对话。全程只需 3~5 分钟,无需任何编程基础。
为什么必须先配置 LLM Provider?
在 PalmClaw 的架构中,手机负责会话、上下文、记忆、Skills 和 Agent loop 等"大脑调度",而模型推理由你配置的 LLM API 提供。理解这个分工,就明白为什么首次启动时它一定会让你先设置 Provider:
📌 一句话理解:PalmClaw 是"车",LLM API 是"发动机"。装好发动机,车才能跑起来。
准备工作:内置 Provider 清单与 API Key 获取
PalmClaw 内置了 15 个 Provider 预设(源码见 ProviderCatalog.kt),覆盖主流国内外大模型平台:
| Provider | 预设默认模型 | 适合场景 |
|---|---|---|
| OpenAI | gpt-5.4-mini |
通用对话、工具调用 |
| Anthropic | claude-sonnet-4-6 |
复杂推理与长任务 |
| Google AI | gemini-3-flash-preview |
高性价比通用推理 |
| DeepSeek(深度求索) | deepseek-chat |
国内直连、低成本 |
| Moonshot AI(月之暗面) | kimi-latest |
国内直连、长文本 |
| Zhipu AI(智谱) | glm-4.5-air |
国内直连 |
| Alibaba Cloud(百炼) | qwen-plus |
国内直连、通义千问 |
| Volcengine(火山引擎) | doubao-seed-1-6-251015 |
豆包系列模型 |
| Groq | llama-3.3-70b-versatile |
高响应速度 |
| Mistral AI | mistral-small-latest |
欧洲生态模型 |
| OpenRouter | openai/gpt-5.4-mini |
一个 Key 调用多家模型 |
| Perplexity | sonar |
联网搜索增强 |
| MiniMax(稀宇极智) | MiniMax-M2.7 |
对话与 Agent 任务 |
| BytePlus | seed-2-0-lite-001 |
字节跳动海外 |
| Custom(自定义) | 手动填写 | 任意兼容端点 |
获取 API Key 的步骤以各平台官方控制台为准,PalmClaw 在设置页中直接提供了"前往 ×× 官方 API 页面"的快捷入口,点击即可跳转到对应平台的 API Key 管理页,创建或复制你的 Key 即可。
⚠️ 安全提示:API Key 等同于支付凭证,请只粘贴到你信任的应用中,切勿公开发布。PalmClaw 的 Key 输入框默认以密码形式隐藏显示。
四步完成 Provider 配置(3 分钟上手)
首次启动 PalmClaw 时,应用内置新手引导(源码见 FirstRunOnboardingScreen.kt),流程为:1 语言 → 2 提供方 → 3 名称。进入"提供方"页后,完成以下四步:
第一步:选择 Provider
在"提供方"下拉框中选择你要接入的平台,例如 OpenAI、DeepSeek 或 Google AI。选择预设后,PalmClaw 会自动填入推荐的基础 URL(Base URL)和默认模型,你基本只需处理 API Key 一项。
第二步:核对 Base URL 与模型
- Base URL:预设 Provider 已自动填好,一般无需修改;选择
Custom时则需手动填写你的端点地址。 - 模型:点击输入框右侧的箭头可从预设列表中选择(如 OpenAI 的
gpt-5.4/gpt-5.4-pro/gpt-5.4-mini),也可以手动输入任意模型名。
💡 小建议:新手优先选择"默认模型"(列表中体积更小、响应更快的档位),上手体验最流畅,之后可随时切换更强模型。
第三步:填入 API Key 并测试连接
将 API Key 粘贴到 API Key 输入框,然后点击 "测试 API" 按钮。PalmClaw 会立即用你的 Key 发起一次真实请求验证连通性,测试通过再保存,可以避免把错误配置带入后续使用。
第四步:保存并启用
测试通过后点击保存。PalmClaw 支持保存多组 Provider 配置并随时切换"当前生效"的一组,方便在不同平台之间快速来回。Provider 的解析与缓存逻辑见 ProviderResolutionStore.kt,界面实现见 ProviderSettingsPage.kt。
开始第一个对话
Provider 配置完成后,返回主界面即可直接从本地会话开始聊天:
- 在底部输入框输入第一句话,例如:"请先简单介绍一下你自己,你现在能帮我做什么?"
- PalmClaw 会由你配置的 LLM 生成回复,并开始管理会话上下文。
- 你可以直接要求它使用手机能力——查询天气、管理日历与联系人、读写本地文件、设置定时提醒等,这些均由内置工具执行(工具清单参考 BuiltInToolCatalog.kt)。
至此,PalmClaw + 你的 API Key 组合已经正式跑起来了 🎉
进阶:Custom 自定义 Provider 与协议自动识别
如果你的模型端点不在预设列表中(例如自建网关、企业内网服务),选择 Custom 即可:
- 协议自动识别:PalmClaw 会根据 URL 特征自动判断协议——URL 含
/v1/messages或anthropic.com识别为 Anthropic 协议,含/chat/completions识别为 OpenAI 协议,含/responses识别为 OpenAI Responses 协议(识别逻辑见 ProviderCatalog.kt)。 - 手动选择协议:Custom 模式下也支持手动指定 OpenAI / OpenAI Responses / Anthropic 三种协议,无需依赖自动识别。
- 自定义名称:保存时可以给配置起一个自己的名字,便于区分多组配置。
常见问题速查
| 问题 | 可能原因与处理 |
|---|---|
| "测试 API" 失败 | 检查 Key 是否复制完整、是否过期;确认网络可达该平台端点 |
| 连接超时 | 部分海外平台需要稳定的网络环境;国内用户可优先考虑 DeepSeek、Kimi、智谱、百炼等预设 |
| 模型名报错 | 模型名必须与平台控制台完全一致,区分大小写;可先回退到默认模型 |
| 换 Key 后仍用旧配置 | 确认已点击保存,并检查当前"启用中"的是哪一组 Provider 配置 |
小结
- LLM Provider 配置是 PalmClaw 使用流程的第一步,决定手机 Agent 的推理能力来源。
- 15 个内置预设覆盖主流平台,选择后只需填 API Key,点击"测试 API"验证,保存即可聊天。
- 私有端点用
Custom模式,协议大多可以自动识别。 - 配置完成后,即可在手机上体验具备文件、日历、提醒、网页等能力的端侧 Agent。
想深入了解整体设计与各模块职责,可以继续阅读工程文档:docs/engineering/architecture.md、docs/engineering/README.md。

