Pi实战 01配置篇——把 Pi 调教成你的主力来源Pi 官方 Settings / Models / Providers / Themes 文档以及 deepakness、torchtree、dalenguyen 等开发者的实战配置。Pi 的配置文件不多但每一个都直接决定它有多懂你。核心文件就这几个文件作用位置settings.json默认模型、思考等级、压缩、重试、主题~/.pi/agent/settings.jsonmodels.json自定义/本地模型与提供商~/.pi/agent/models.jsonAGENTS.md项目/全局指令启动时加载全局~/.pi/agent/ 父目录 当前目录APPEND_SYSTEM.md直接拼进系统提示词优先级最高~/.pi/agent/APPEND_SYSTEM.mdweb-search.json联网搜索提供商配置~/.pi/agent/web-search.jsonthemes/my-theme.json终端配色主题~/.pi/agent/themes/下面逐个给可复制的例子。一、settings.json一次配好默认行为这是最该先配的文件。官方给出的完整示例{defaultProvider:anthropic,defaultModel:claude-sonnet-4-20250514,defaultThinkingLevel:medium,modelThinkingLevels:{anthropic/claude-sonnet-4-20250514:high},theme:dark,compaction:{enabled:true,reserveTokens:16384,keepRecentTokens:20000},retry:{enabled:true,maxRetries:3},enabledModels:[claude-,gpt-4o],warnings:{anthropicExtraUsage:true}}几个关键字段的实战用法1. 给不同模型设不同思考等级modelThinkingLevels默认defaultThinkingLevel是全局的但你可以对特定模型单独覆盖。比如日常用low省钱只在某个强模型上开highmodelThinkingLevels:{anthropic/claude-sonnet-4-20250514:high,openai/gpt-5-codex:medium}2. 控制CtrlP循环哪些模型enabledModels格式和 CLI 的--models一致用前缀匹配enabledModels:[claude-,gpt-4o,gemini-2]配好后会话里按CtrlP就只在这几个之间循环不会在一堆用不到的模型里翻。3. 上下文压缩compactionreserveTokens给压缩后保留的系统区留多少 token默认 16384。keepRecentTokens压缩时强制保留最近多少 token 的对话默认 20000避免把刚说的关键上下文压掉。调大keepRecentTokens适合最近几轮很重要的场景想更省 token 就调小。4. 重试retry本地模型或不稳定端点建议开重试。完整示例retry:{enabled:true,maxRetries:3,baseDelayMs:2000,provider:{timeoutMs:3600000,maxRetries:0,maxRetryDelayMs:60000}}配完不用重启 Pi会话里敲/reload即可生效。二、models.json接上你的本地模型或任意自定义端点这是 Pi 区别于 Claude Code只能 Anthropic的关键。本地 Ollama / LM Studio / vLLM或任何 OpenAI 兼容端点都能塞进来。本地 Ollama 示例dalenguyen 实测{providers:{ollama:{baseUrl:http://localhost:11434/v1,api:openai-completions,apiKey:ollama,models:[{id:qwen3-coder:30b,contextWindow:262144,compat:{supportsDeveloperRole:false,supportsReasoningEffort:false}}]}}}极简写法本地模型其实只要id就够了。比如跑 gpt-oss 并开启推理{providers:{ollama:{baseUrl:http://localhost:11434/v1,api:openai-completions,apiKey:ollama,models:[{id:gpt-oss:20b,reasoning:true}]}}}⚠️一个常见坑apiKey对本地 Ollama 是占位符Ollama 会忽略它但 Pi 仍认为需要鉴权才会在/model里显示。所以keyless 的本地服务要保留一个 dummy 值如ollama或用/login存个 key或选模型时传--api-key。覆盖内置提供商 / 自定义模型参数官方 full example{providers:{openrouter:{modelOverrides:{anthropic/claude-sonnet-4:{name:Claude Sonnet 4 (Bedrock Route),compat:{openRouterRouting:{only:[amazon-bedrock]}}}}}}}⚠️另一个坑ofox 实测没在models.json列出的模型 idPi 会报警告Model not found for provider然后按自定义模型跑但会继承默认值128k context、16384 max output。所以一个 1M context 的模型如果不列出来会在远早于必要的時候就触发压缩。→大上下文模型务必显式列出contextWindow和maxTokens。配好后/model里就能选到你刚加的本地模型了。三、AGENTS.md给 Pi 装一个项目大脑AGENTS.md是项目/全局指令启动时自动加载。加载顺序全局~/.pi/agent/→ 父目录 → 当前目录后加载的覆盖先加载的。TorchTree 的分工建议全局~/.pi/agent/AGENTS.md写你日常通用的技术栈偏好、代码规范跨项目适用。项目级AGENTS.md仓库根目录写这个具体项目的约束、构建命令、目录约定。一个项目级AGENTS.md长这样结构参考社区通用写法# Project: foo-service ## Stack - Node.js 20 TypeScript, Fastify, Prisma PostgreSQL ## Build Test - Install: npm install - Typecheck: npm run typecheck - Test: npm test - Run dev: npm run dev ## Conventions - 新代码用 ESMimport 而非 require - 数据库改动必须带 migration 文件 - API 错误统一用 ApiError 抛出 ## Gotchas - npm run dev 前必须先 npm run prisma:generate - 测试用 vitest不要碰真实数据库用 testcontainers四、APPEND_SYSTEM.md比 AGENTS.md 更高优先级的全局行为规则这是 deepakness 强烈推荐的用法。APPEND_SYSTEM.md放在~/.pi/agent/APPEND_SYSTEM.md内容直接追加到系统提示词末尾因此它的指令比AGENTS.md优先级更高对所有项目生效。deepakness 实际放的内容可直接抄- If the default provider doesnt have vision capabilities, use pi-vision-handoff for images. - Read relevant local files first when the answer is available in the codebase. If not, research online via pi-web-access. Before making a big change based on online research findings, confirm with me first. - Explain risky file edits and destructive commands before executing. - Write simply. Avoid AI-slop language – no flowery adjectives, unnecessary adverbs, or overly formal phrasing.翻译成中文就是四条黄金规则没视觉能力就用pi-vision-handoff处理图片。答案在代码库里就先读本地文件不在再联网查pi-web-access。基于联网结果做大改动前先跟我确认。执行危险文件编辑/破坏性命令前先解释清楚。写得简单点杜绝 AI 腔不要华丽形容词、多余副词、过度正式。这就是把你的工作习惯固化成 Agent 的默认行为。把它配好Pi 立刻从通用助手变成懂你脾气的助手。五、web-search.json配联网搜索默认 Exa免 API keyPi 本身不带联网搜索装pi-web-access后默认用 Exa免 key。deepakness 通过~/.pi/agent/web-search.json固定用 Exa{provider:exa,allowBrowserCookies:false,summaryModel:opencode-go/deepseek-v4-flash,workflow:none,curatorTimeoutSeconds:20}也可以换成 Perplexity / Gemini需各自 API key。summaryModel是用于总结抓取内容的模型——用一个便宜模型即可省钱。六、themes给终端换个配色Pi 的 TUI 几乎每个颜色都能改。主题文件放~/.pi/agent/themes/编辑当前主题会自动热重载。mkdir-p~/.pi/agent/themesvim~/.pi/agent/themes/my-theme.json{$schema:https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/theme-schema.json,name:my-theme,vars:{primary:#00aaff,secondary:242},colors:{accent:primary,border:primary,borderAccent:#00ffff,borderMuted:secondary,success:#00ff00,error:#ff0000,warning:#ffff00,muted:secondary,dim:240,text:,thinkingText:secondary,selectedBg:#2d2d30,scrollbarThumb:#555566,searchMatchBg:#2d2d30}}配色建议官方从一套基础 paletteNord / Gruvbox / Tokyo Night / Catppuccin起步在vars里定义再在colors里引用保持一致性。浅色终端用更暗、更低对比的颜色。VS Code 里设terminal.integrated.minimumContrastRatio: 1才能看到准确颜色。主题用 51 个颜色 token社区已有 Catppuccin 四味现成主题可直接装。七、一个抄完即用的完整配置清单把上面串起来新手可以直接照抄的最小可用组合~/.pi/agent/settings.json—— 设好defaultModel、defaultThinkingLevel、enabledModels。~/.pi/agent/APPEND_SYSTEM.md—— 放那 4 条全局行为规则。~/.pi/agent/AGENTS.md—— 放你的通用技术栈偏好。想省成本/要隐私 →~/.pi/agent/models.json接本地 Ollama见第二节。想换肤 →~/.pi/agent/themes/my-theme.json。每改完一个会话里/reload立刻生效。下一篇02 · 提示词与技能篇 —— 把重复工作固化为/xxx命令和技能。