配了两周感觉哪里都对，但就是跑不稳——Pi Agent 的3个反直觉设置

两周前，我在群里发了一句话："Pi Agent 的配置文件我看了三遍，逻辑上完全没问题，但任务就是会在第二个子步骤卡死。"

发完之后沉默了很久。

后来有人回了一句："你是从 Claude Code 迁过来的吧？"

我说是。

"那就对了，你带了错误的直觉过来。"

这句话戳到了我。我花了接下来整整一周去验证这个判断，发现他说得分毫不差——不是 Pi Agent 有 bug，是我用 Claude Code 的思维方式在操作一个行为逻辑完全不同的工具。更难受的是，Pi Agent 不会报错，它只会静默地按照它自己的理解执行，然后给你一个"看起来在跑"但完全不符合预期的结果。

如果你也是从 Claude Code 迁移过来，或者两个工具并用，这篇文章可能能帮你省下至少两周的排查时间。

---

第一章：那个让我开始怀疑自己的失败场景

具体说说当时发生了什么。

我在 Pi Agent 里配置了一个三步任务链：先抓取数据，再做清洗，最后输出报告。在 Claude Code 里，这种任务我会用 sequential 模式，步骤之间传参，每一步完成后触发下一步，逻辑清晰，跑了很多次都稳。

我想当然地在 Pi Agent 里用了类似的写法，配置文件看起来很正常，跑起来也没有报错——但报告始终是空的。

调了半天，我才发现：Pi Agent 根本没有等第一步完成再跑第二步。它在第一步还没拿到数据的时候，就已经把空结果传给了清洗步骤，然后愉快地生成了一份空报告。

这不是 bug。这是 Pi Agent 的默认调度行为——它的并发优先级和 Claude Code 的完全不同。

这只是我踩的第一个坑。

• 第1周：照着 Claude Code 的习惯写配置，任务表面在跑，结果全部不对，开始怀疑是模型问题
• 第2周：逐字对比文档，发现几个字段的默认值和我预期的完全相反，开始系统性排查
• 第3周：彻底重写配置逻辑，稳定运行至今，连续11天没有中断

下面我把稳定后的完整配置直接给你，然后再逐一拆解那3个让我踩坑的设置。

---

第二章：可直接复制的完整配置文件（带注释版）

# Pi Agent 稳定配置模板 v1.3
适用场景：多步骤任务链 + 工具调用场景
最后更新：基于连续运行11天无中断的版本

agent:
name: "my-pi-agent"

# ── 调度策略 ──────────────────────────────────
execution:
mode: "sequential"          # 【关键】强制顺序执行，默认值是 "concurrent"
# Claude Code 用户注意：Pi Agent 默认并发，必须显式声明
step_timeout: 120           # 单步超时（秒），默认值 30，太短容易误判超时
retry_on_timeout: true      # 超时后自动重试，默认 false
max_retries: 2              # 最多重试次数，建议不超过3，否则费用失控

# ── 上下文管理 ────────────────────────────────
context:
window_strategy: "sliding"  # 【关键】滑动窗口策略，默认值是 "full"
# "full" 会把所有历史都塞进去，长任务必然溢出
window_size: 8000           # 保留最近 8000 token 的上下文
preserve_system: true       # 始终保留 system prompt，不随滑动被截断
summary_on_overflow: false  # 溢出时不自动摘要（摘要质量不稳定，建议关闭）

# ── 工具调用权限 ──────────────────────────────
tools:
permission_mode: "explicit" # 【关键】显式声明每个工具的权限，默认值是 "permissive"
# "permissive" 模式下 Agent 可以自行决定调用哪些工具
allowed_tools:
- name: "file_read"
scope: "project_dir"    # 只允许读取项目目录，不开放全盘
- name: "file_write"
scope: "output_dir"     # 写权限只给输出目录
require_confirm: false  # 写操作不需要二次确认（已限制了 scope，安全）
- name: "shell_exec"
enabled: false          # 完全禁用 shell 执行，除非你明确需要
deny_unlisted: true         # 未在列表中的工具一律拒绝，不走默认逻辑

# ── 模型配置 ──────────────────────────────────
model:
provider: "anthropic"
name: "claude-sonnet-4.6"   # 任务链场景推荐 Sonnet，性价比最优
temperature: 0.3            # 调低温度，减少步骤间的随机漂移
max_tokens: 4096            # 单次响应上限，根据任务复杂度调整

# ── 日志与调试 ────────────────────────────────
logging:
level: "debug"              # 调参阶段建议开 debug，稳定后改 info
log_tool_calls: true        # 记录每次工具调用，排查问题必备
log_context_size: true      # 记录每步的上下文大小，监控窗口使用情况

⚠️ 特别提醒：这份配置里有3个字段的默认值和大多数人的直觉完全相反。如果你只是复制粘贴，可能暂时能跑，但早晚会在某个场景下踩到。下面我逐一拆解这3个坑。

---

第三章：3个反直觉设置，逐一拆解

反直觉设置 #1：执行模式默认并发，不是顺序

在 Claude Code 里，任务链默认是顺序执行的。你不需要特别声明，它就会等上一步完成再跑下一步。这个行为太自然了，以至于大多数人从来没有意识到这是一个"设置"，而不是理所当然的逻辑。

Pi Agent 的 execution.mode 默认值是 "concurrent"。它会尽可能并行地推进所有步骤，除非步骤之间有明确的数据依赖声明。但问题在于：Pi Agent 判断"数据依赖"的方式非常保守——只有你显式用 depends_on 字段声明了依赖关系，它才会等待。否则，它就认为这些步骤可以并发。

我当时的任务链里没有写 depends_on，因为在 Claude Code 里根本不需要写。结果就是文章开头说的那个场景：第二步在第一步还没完成的时候就开始执行了。

❌ 错误写法（带入了 Claude Code 的默认预设）：

execution:
# 什么都没写，以为默认就是顺序执行
step_timeout: 30

✅ 正确写法：

execution:
mode: "sequential"   # 必须显式声明，不能依赖默认值
step_timeout: 120    # 同时把超时时间调长，避免网络抖动导致误超时

---

反直觉设置 #2：上下文窗口默认"全量保留"，长任务必然溢出

Claude Code 有内置的上下文管理机制，它会在接近窗口上限时自动做一些处理（压缩或截断），用户通常不需要手动配置这个。所以大多数人对"上下文窗口策略"这个字段完全没有概念。

Pi Agent 的 context.window_strategy 默认值是 "full"——它会把整个对话历史原封不动地塞进每一次请求。对于短任务，这没问题。但对于多步骤的长任务，到了第五六步，你的上下文可能已经撑到模型的物理上限，然后出现一个非常隐蔽的问题：不是报错，而是模型开始"遗忘"前面的内容，或者响应质量开始下降。

这个问题特别难排查，因为任务还在跑，日志看起来也正常，只是结果越来越偏。

❌ 错误写法：

context:
# 没有配置，默认 full 策略
# 长任务跑到后半段开始"抽风"，完全不知道为什么

✅ 正确写法：

context:
window_strategy: "sliding"  # 滑动窗口，只保留最近 N 个 token
window_size: 8000           # 根据你的任务复杂度调整这个值
preserve_system: true       # system prompt 必须始终保留，不能被滑掉

---

反直觉设置 #3：工具调用权限默认"宽松"，不是"最小权限"

Claude Code 的工具调用有比较明确的权限边界，而且每次调用高风险工具（比如写文件、执行命令）时会有明显的提示或确认步骤。用户会形成一种安全感：它不会在我不知情的情况下乱动文件系统。

Pi Agent 的 tools.permission_mode 默认值是 "permissive"。在这个模式下，Agent 可以自行决定调用哪些工具，只要这些工具在它的工具列表里。它不会问你，它直接调用。

我第一次发现这个问题，是因为我在项目目录里发现了几个不知道什么时候生成的临时文件。查了日志才发现，Agent 在某个步骤里自作主张地调用了 file_write，把中间结果写到了我没有预期的位置。

这不是恶意行为，是 Agent 在"帮你优化"——但你完全不知情。

❌ 错误写法：

tools:
# 没有配置权限，用默认的 permissive 模式
# Agent 可以在你不知情的情况下调用任何工具

✅ 正确写法：

tools:
permission_mode: "explicit"  # 显式声明模式，未列出的工具一律禁止
allowed_tools:
- name: "file_read"
scope: "project_dir"
- name: "file_write"
scope: "output_dir"
deny_unlisted: true          # 这一行必须加，否则 explicit 模式有漏洞

---

第四章：稳定运行后的实际效果

对比一下调整前后的体感差异：

最有感触的变化是最后一条。开了 log_tool_calls: true 和 log_context_size: true 之后，每一步在做什么、上下文用了多少，一目了然。之前排查问题像在黑盒里摸索，现在像在看监控录像。

---

第五章：给不同阶段读者的建议

先把 execution.mode: "sequential" 和 tools.permission_mode: "explicit" 这两行写进你的第一个配置文件。这是最低成本的防坑措施，其他字段可以慢慢摸索。

重点检查你现有配置里有没有"依赖默认值"的地方——也就是那些你根本没写、但以为它会按你预期工作的字段。Pi Agent 的默认值和 Claude Code 的行为有系统性差异，每一个"没写"的地方都是潜在的坑。

建议给 Pi Agent 单独维护一份配置模板，不要在两个工具之间来回复制。它们的字段有时候看起来相似，但语义完全不同，混用比完全不懂更危险。

---

💡 最后顺带提一句：调参阶段最怕的其实不是踩坑，是 API 费用跑飞。我现在测试新配置都用 [api.884819.xyz](https://api.884819.xyz)，支持 Claude Sonnet、GPT、Gemini 等多个主流模型，按量计费，没有月租。摸索期反复调用 API 测效果，比直接开官方订阅划算很多。新用户注册即送体验 token，注册只需要用户名+密码，可以直接上手试。

---

带走的不只是配置文件，而是一个排查框架

回顾这三周，我意识到真正的收获不是那份配置文件——而是一个判断 Pi Agent 行为的思维方式：

1. 这个字段的默认值是什么？ 不要假设它和你用过的其他工具一样。Pi Agent 的文档里每个字段都有默认值说明，先去查，再做判断。

2. 我有没有"依赖隐式行为"？ 任何你没有显式声明的配置，都可能在某个边界条件下触发你没预料到的行为。

3. 日志里有没有记录这一步在做什么？ 先把 log_tool_calls 和 log_context_size 打开，让行为可见，再谈排查。

这三个问题能覆盖我遇到的 80% 的问题场景。剩下 20% 通常是任务设计本身的问题，和配置无关。

---

下一篇我想聊聊 Pi Agent 的多任务编排——当你把它和本地工具链真正打通之后，调度行为里有几个地方是完全出乎意料的，踩坑程度不亚于今天说的这3个。感兴趣的可以先收藏这篇，下篇会直接在这个配置基础上继续往上搭，不需要从头来过。

---

#AI工具 #PiAgent #ClaudeCode #AI配置 #踩坑记录 #AI自动化 #8848AI #AI教程