Pi Agent: 配置详解
最后更新：2026-08-31
配置是 Pi Agent 的"控制面板"——搞懂它，才能精细调节 Agent 的每个参数。
1. 配置层级
Pi Agent 的配置按优先级从低到高：
TEXT
📖 仅展示
默认值 → 全局配置 → 项目配置 → 环境变量 → 代码参数 → CLI 参数
（最低） （最高）
高优先级覆盖低优先级。
2. 全局配置
位置：~/.pi-agent/config.yaml
YAML
default_provider: deepseek
default_model: deepseek-chat
providers:
deepseek:
api_key: "sk-xxxxxxxx"
base_url: "https://api.deepseek.com"
model: "deepseek-chat"
temperature: 0.7
max_tokens: 4096
openai:
api_key: "sk-xxxxxxxx"
model: "gpt-4o"
display:
theme: dark
code_highlight: true
show_token_count: true
session:
auto_save: true
save_dir: "~/.pi-agent/sessions"
templates_dir: "~/.pi-agent/templates"
skills_dir: "~/.pi-agent/skills"
3. 项目配置
位置：项目根目录 .pi-agent.yaml
YAML
project:
name: "my_fastapi_app"
description: "FastAPI 项目"
agent:
system_prompt: "你是这个 FastAPI 项目的专属助手"
tools:
- file_reader
- shell
- search
context:
inject:
- "README.md"
- "requirements.txt"
- "pyproject.toml"
providers:
deepseek:
temperature: 0.3 # 项目级别覆盖全局配置
4. 环境变量
所有配置项都有对应的环境变量，格式为 PI_ + 大写键名：
| 配置项 | 环境变量 |
|---|---|
| providers.deepseek.api_key | PI_DEEPSEEK_API_KEY |
| default_provider | PI_DEFAULT_PROVIDER |
| display.theme | PI_DISPLAY_THEME |
| session.auto_save | PI_SESSION_AUTO_SAVE |
| agent.temperature | PI_AGENT_TEMPERATURE |
5. 代码配置
PYTHON
from pi_agent import Agent
agent = Agent(
name="custom",
provider="deepseek",
model="deepseek-chat",
temperature=0.5,
max_tokens=2048,
tools=["search", "calculator"],
system_prompt="你是一个数学助手",
context_window=8192,
truncation_strategy="summarize",
auto_save=True
)
6. 动态配置
运行时修改配置：
(1) 切换模型
PYTHON
agent.configure(model="deepseek-reasoner", temperature=0.2)
(2) 启用/禁用工具
PYTHON
agent.enable_tool("shell")
agent.disable_tool("search")
(3) 更新系统提示词
PYTHON
agent.set_system_prompt("你现在是一个严格的安全审查员")
7. 配置验证
▶ 示例 1：配置健康检查（难度⭐）
PYTHON
from pi_agent import Config
config = Config.load()
# 验证配置完整性
issues = config.validate()
if issues:
for issue in issues:
print(f"⚠️ {issue}")
else:
print("✅ 配置验证通过")
# 检查 API 密钥
for provider, cfg in config.providers.items():
if cfg.get("api_key"):
print(f"✅ {provider}: 密钥已配置")
else:
print(f"❌ {provider}: 密钥未配置")
8. 配置文件参考
完整配置项一览：
| 类别 | 配置项 | 默认值 | 说明 |
|---|---|---|---|
| Agent | name | "agent" | Agent 名称 |
| Agent | system_prompt | "" | 系统提示词 |
| Agent | temperature | 0.7 | 温度参数 |
| Agent | max_tokens | 4096 | 最大输出 token |
| Agent | context_window | 8192 | 上下文窗口 |
| Agent | truncation_strategy | "remove_oldest" | 截断策略 |
| Provider | api_key | "" | API 密钥 |
| Provider | base_url | "" | API 地址 |
| Provider | model | "" | 模型名称 |
| Display | theme | "dark" | 界面主题 |
| Display | code_highlight | true | 代码高亮 |
| Session | auto_save | false | 自动保存 |
| Session | save_dir | "~/.pi-agent/sessions" | 保存目录 |
❓ 常见问题
Q 配置项很多，哪些必须配？
A 只需要配 API 密钥（
providers.<name>.api_key），其他都有默认值。用本地模型连密钥都不用配。Q 项目配置和全局配置冲突时怎么办？
A 项目配置优先。这是"就近原则"——项目级 > 用户级 > 全局默认。
Q 可以把配置文件提交到 Git 吗？
A 项目配置（.pi-agent.yaml）可以提交，但不要包含 API 密钥。用环境变量代替密钥配置。
📖 小节
- 配置优先级：默认值 < 全局 < 项目 < 环境变量 < 代码 < CLI
- 全局配置在
~/.pi-agent/config.yaml，项目配置在.pi-agent.yaml - 环境变量格式
PI_+ 大写键名 - 运行时可动态修改配置
- API 密钥用环境变量，不要提交到 Git
📝 作业
- 基础题（难度⭐）：创建全局配置文件，配置至少一个 LLM 提供商。
- 进阶题（难度⭐⭐）：为你的项目创建
.pi-agent.yaml，设置项目专属的系统提示词和工具。 - 挑战题（难度⭐⭐⭐）：写一个配置验证脚本，检查所有配置项的完整性和一致性。
