Persome（personal-model）是一个在本地构建 HUMAN.md 个人模型的 Runtime：它观察你的工作痕迹，用 LLM 把零散记录提炼成结构化画像。本教程讲解 Persome LLM 配置的两种方式——接入 API Key，或复用 Codex / Claude Code / Cursor 的编码 Agent 订阅驱动后台建模，并附带验证与故障排查步骤。

为什么 Persome 需要 LLM？

Persome 的采集与 BM25 检索不依赖 LLM，但语义建模必须：timeline 窗口归约、memory_delta 增量建模、schema 挖掘、Root 综合等十几个阶段都要调用模型（见 docs/config.md 的模型阶段清单）。没有 LLM 时它只能采集和检索，模型不会自己长出来。

一条 Provider 配置就能驱动全部语义阶段。Persome 支持两种协议：Anthropic 原生 Messages 和 OpenAI 兼容的 Chat Completions，内置 15+ 托管预设（Anthropic、OpenAI、DeepSeek、OpenRouter、Gemini、Groq、Mistral、xAI、Qwen、Moonshot/Kimi、Zhipu GLM、SiliconFlow、Azure OpenAI 等）与 3 个免 Key 本地预设（Ollama、LM Studio、vLLM），预设定义见 src/persome/providers.py。

三条配置路线速览：

方式一：三步接入 API Key（测试通过才保存）

第 1 步：查看可用 Provider

persome llm providers # 列出预设及本机已检测到的 Key persome llm providers --details # 查看协议、默认模型与端点

第 2 步：引导式 setup：先探测，后保存

persome llm setup

这是 Persome 最贴心的设计：测试之前，绝不写入。流程是：

1. 选择 Provider（若本机恰好只检测到一枚凭据会自动选中，多枚时提示选择）；
2. 只需输入 Provider 和 API Key——端点和默认模型由 Persome 托管，你不用手填 URL；
3. Persome 发起一次小规模补全 + 一次强制工具调用探测（实现见 src/persome/llm_setup.py），因为建模阶段依赖 tool calling，很多"能对话但不会调工具"的模型会被提前拦下；
4. 连通性/鉴权失败 → 什么都不写；模型能对话但不会调工具 → 需要你显式确认降级模式；
5. 全部通过才落盘：非秘密路由写入~/.persome/config.toml的[models.default]，密钥则存到同目录env文件里，统一命名为PERSOME_LLM_API_KEY，TOML 中永远不出现明文 Key。

[models.default] provider = "openrouter" protocol = "openai" model = "anthropic/claude-sonnet-4" base_url = "https://openrouter.ai/api/v1" api_key_env = "PERSOME_LLM_API_KEY"

第 3 步：验证当前生效路由

persome llm status --check # 展示生效的 Provider/模型/端点，并做实时探测 persome doctor # 离线前置检查，不发起 LLM 调用

status --check的探测分两档：completion_ok是硬门槛，tool_call_ok单独报告（命令实现见 src/persome/cli.py）。

💡 提示：daemon 只加载一次配置，改完config.toml记得重启 daemon。--api-key-env可从已有环境变量导入 Key（仍统一存为PERSOME_LLM_API_KEY）；Azure 与 custom-openai / custom-anthropic 属于进阶路径，需自备端点和模型名。

方式二：复用编码 Agent 订阅驱动后台建模

如果你已经订阅了 Codex、Claude Code 或 Cursor，还可以让 Persome 的后台建模直接消耗这份订阅，无需再买一份 API 额度。这就是[agent_funding]编码 Agent CLI 桥接：daemon 的语义阶段通过本地 CLI 调用你的 Agent，登录态完全由 Agent 自己持有并刷新，Persome 只保存可执行文件路径、路由策略和每日调用上限，不存储任何 OAuth token。

启用步骤：一条命令 + 一次验证调用

persome llm agent setup --client codex --daily-call-limit 50 --check # 同样支持：claude-code、cursor-agent persome llm status

--check会消耗一次预算内的验证调用，确认补全与工具选择都可用后才保存配置（见 src/persome/cli.py）。也可以在安装 MCP 时用--fund-model一次性表达同意：

persome install claude-code --fund-model persome install codex --fund-model

每日预算与 fail-closed 行为

对应[agent_funding]配置段（完整说明见 docs/config.md）：

[agent_funding] enabled = true client = "codex" # codex | claude-code | cursor-agent executable = "/absolute/path/to/codex" model = "" # 留空 = 使用客户端订阅默认模型 daily_call_limit = 50 # 每日上限，跨 daemon 重启持久化 timeout_seconds = 180.0 max_parallel_calls = 1

• 每次模型调用在启动客户端前就预留 1 个每日配额，崩溃、超时、无效响应都无法绕过上限；
• 配额用尽后语义工作fail closed（直接停摆到下一个本地日历日），Persome 绝不会悄悄回退到你付费的 API 配置；
• 撤销同样简单，且不影响 Agent 登录态与备用 Provider 配置：

persome llm agent disable # 恢复此前的 API/本地 Provider 路由 persome llm agent status # 查看登录态、能力与已用/总预算

这套桥接正是 Persome "睡后建模"体验的核心——夜里你睡觉，语义流水线消耗订阅额度把窗口归约、schema 挖掘跑完，早上醒来直接看结果：

方式三：本地免 Key 方案（Ollama / LM Studio / vLLM）

没有 Key、又在意数据不出机器？选本地预设即可：persome llm setup中选择 Ollama、LM Studio 或 vLLM（需本地服务暴露/v1端点），整个流程免 Key。注意预设只描述端点默认值，不代表对每个模型的能力保证——同样会走补全 + 工具调用双重探测，能力不达标的模型在 setup 阶段就会被指出来。

常见问题排查

相关实现与文档索引：

• 配置全解：docs/config.md
• 探测与保存逻辑：src/persome/llm_setup.py
• Provider 预设注册表：src/persome/providers.py
• MCP 客户端 Sampling 桥接：src/persome/writer/agent_funded.py