Pi实战 05：本地模型 · MCP · 安全沙箱篇

来源：Pi 官方 Models / Containerization / MCP 文档，dalenguyen、patloeber、Fabio Rehm、BenjaminWegener、ruizrica2 等实战，以及 Agent Sandbox / pi-less-yolo 等隔离方案。

这一篇解决三个"硬核"问题：用本地模型省钱/保隐私 、接 MCP 工具但不烧 context 、把 Agent 关进沙箱保证安全。

一、本地模型：零成本、零数据外泄

Pi 支持 15+ 提供商和自定义本地端点，通过 models.json 热重载。这是它相对纯云端 Agent 的最大优势之一。

方案 A：Ollama（最省事）

Ollama 自带一键配置：

bash 复制代码

ollama launch pi

它会引导你选推荐模型（GLM、MiniMax、Kimi 等 cloud 版先通过本地服务器代理到 ollama.com）。

手动接本地 Ollama （dalenguyen 实测，~/.pi/agent/models.json）：

json 复制代码

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        {
          "id": "qwen3-coder:30b",
          "contextWindow": 262144,
          "compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false }
        }
      ]
    }
  }
}

切换模型即时生效------pull 新模型 + 改 model 字段即可。dalenguyen 的结论："Replacing cloud APIs with a local Ollama server is a one-afternoon project: no cost, no data exposure, no rate limits."

方案 B：LM Studio + Gemma 4（patloeber 的完整流程）

LM Studio 是桌面 app，处理下载/量化，并暴露本地 OpenAI 兼容 API。patloeber 的 7 步：

装 LM Studio（lmstudio.ai，macOS/Windows/Linux）
下载 Gemma 4
启动本地 server
配置 context size
装 Pi
把 Pi 连到本地模型（同上面的 models.json）
加技能和扩展

LM Studio、llama.cpp、Ollama 都暴露 OpenAI 兼容端点，Pi 不在乎你用哪个，配置通用，换着试零成本。

方案 C：本地 + 云混合（BenjaminWegener 的 M4 Mac 实践）

用 TurboQuant fork 在 M4 上用 Metal 跑重推理，文档永不离开硬件。
用 .pi/agent 下的 agents.md / system.md 做"自定义微调"（提示词层面）。
把后台开发进程和推理分开，规避本地推理的上下文切换开销。
收益：数据主权、隐私（无云厂商窥探）、低延迟。

⚠️ 本地模型的坑 ：本地模型常"比 Claude Code 慢半拍或不够好"（HN 上很多人因此还没完全迁移）。建议混合用 ：本地跑日常，硬骨头 /model 切云端强模型。

二、MCP：接一堆工具，但只烧 ~200 tokens

传统 MCP 集成的痛点：3--4 个 server 光工具定义就能吃掉 30k+ tokens。Pi MCP Adapter 把这个压到无论接多少 server 都只 ~200 tokens。

安装 + 配置

bash 复制代码

pi install npm:pi-mcp-adapter
/mcp setup          # 交互式配置

mcp.json 全局示例 （~/.pi/agent/mcp.json）：

json 复制代码

{
  "mcpServers": {
    "supabase": {
      "transport": "streamable-http",
      "url": "https://your-project.supabase.co/functions/v1/mcp",
      "lifecycle": "eager"
    }
  }
}

配置加载位置（后者覆盖前者）：

复制代码

~/.pi/agent/mcp.json     ← 全局，所有项目生效
.pi/mcp.json             ← 项目级，覆盖全局

自动发现主机已有配置

bash 复制代码

pi-mcp-adapter init --discover-host-configs

扫描你主机上已有的 MCP 配置（~/.config/mcp/mcp.json 等），把缺失的兼容导入加到 ~/.pi/agent/mcp.json。

配置优先级（后者胜）：

复制代码

~/.config/mcp/mcp.json
~/.agents/mcp.json
~/.agents/mcp/mcp.json
<Pi agent dir>/mcp.json
.mcp.json
.pi/mcp.json

子代理里直接调 MCP 工具

如果用 subagent 扩展，agent 定义里可用 mcp:server-name 语法直接请求某 server 的工具：

markdown 复制代码

---
name: github-agent
mcp: github
---

进阶：pi-mcporter（带鉴权的 server）

json 复制代码

{
  "mcpServers": {
    "linear": {
      "baseUrl": "https://api.linear.app/graphql",
      "headers": { "Authorization": "Bearer ${LINEAR_API_KEY}" }
    },
    "everything": {
      "command": "npx -y @modelcontextprotocol/server-everything"
    }
  }
}

工作流：search 找 server.tool → describe 看 schema → call 执行（复杂参数可用 argsJson）。

三、安全沙箱：把 Agent 关进笼子

Pi 默认对你整个文件系统有完全访问权。要隔离，社区有从"轻量"到"硬核"的多层方案。

层级 1：内置 sandbox 扩展（最轻）

bash 复制代码

pi -e ./sandbox

基础的 OS 级限制。

层级 2：Gondolin 扩展（本地微虚拟机）

隔离内置工具和 ! 命令，同时把鉴权留在宿主机。见 examples/extensions/gondolin/。

层级 3：Plain Docker（官方推荐，简单可靠）

官方 Dockerfile.pi + 运行：

bash 复制代码

docker build -t pi-sandbox -f Dockerfile.pi .
docker run --rm -it \
  -e ANTHROPIC_API_KEY \
  -v "$PWD:/workspace" \
  -v pi-agent-home:/root/.pi/agent \
  pi-sandbox

-v "$PWD:/workspace" 把当前目录挂进容器，容器内 /workspace 的读写直接落到宿主机文件。
/root/.pi/agent 用 named volume → 容器内独立配置和会话。
- ⚠️ 若挂宿主机 ~/.pi/agent，会把宿主机 auth/session 文件暴露进容器。

验证隔离（ajeetraina 强烈建议至少做一次）：在运行的沙箱里打印 agent 能看到的 key，确认它只能看到你给的那把。

层级 4：Bubblewrap（bwrap，零默认权限，安全优先）

palaimon 的对比结论：Docker 和 bwrap 都依赖 Linux 内核命名空间，共享"内核 CVE 可逃逸"的根本风险。区别在于：

Docker = 完整环境（适合"agent 需要什么环境"）。
Bubblewrap = 零默认权限，一个 30 行的 bin/pi bwrap 脚本比 Dockerfile + devcontainer + compose 更易审查维护（适合"agent 能访问什么"）。

层级 5：现成的硬核隔离项目 ------ cjermain/pi-less-yolo

正如其名"Slightly less YOLO"，把 Pi 关进 Docker 沙箱：

以你自己的用户运行，不能提权。
agent 碰不到项目目录外的文件。
只转发必要的环境变量（PI_SKIP_VERSION_CHECK、PI_CACHE_RETENTION、PI_PACKAGE_DIR、VISUAL、EDITOR），不透传其他宿主变量。
auth 文件 ~/.pi/agent/auth.json 优先于环境变量。

作者老实交代："This is 'less YOLO', not 'no YOLO'. Container escapes exist. This is a meaningful reduction in risk, not a security guarantee."（这是"少作死"，不是"不作死"。）

层级 6：网络出口过滤（防数据外泄）

ajeetraina 的 kit：Pi 默认只放开 npm registry 和 Anthropic 域名，其他一律拒绝。要加别的自己开：

bash 复制代码

sbx policy allow network "example.com,cdn.example.com"
sbx policy log            # 看什么被拦了

四、实战：给敏感项目配一套"本地模型 + 沙箱"

bash 复制代码

# 1. 接本地模型（零外泄）
vim ~/.pi/agent/models.json     # 第一节 Ollama 配置

# 2. 项目级 AGENTS.md 写清约束
vim ./AGENTS.md

# 3. 用 Docker 沙箱跑（代码不出容器）
docker run --rm -it \
  -e OLLAMA_API_KEY \
  -v "$PWD:/workspace" \
  -v pi-agent-home:/root/.pi/agent \
  pi-sandbox

这套组合 = 代码不离开内网（本地模型）+ agent 破坏不了宿主机（沙箱）+ 网络只通必要端点。对合规/敏感项目足够稳妥。

五、小结

本地模型：Ollama 一键、LM Studio 图形化、M4+TurboQuant 本地推理------省钱省到 0、数据不出门。
MCP ：用 pi-mcp-adapter，接再多 server 也只 ~200 tokens，别用传统方式烧 30k。
沙箱：从内置 sandbox 扩展 → Gondolin → Docker → Bubblewrap → pi-less-yolo，按你的安全需求挑一层。
黄金法则：先验证隔离是否真生效（打印 agent 能看到的 key），别只信文档。

参考资料

Pi 官方《MCP》：https://pi.dev/docs/latest/mcp/ ｜《Containerization》：https://pi.dev/docs/latest/containerization/
Pi 官方讨论《Docker sandbox pi-less-yolo for containing the blast radius》（原帖）：https://github.com/earendil-works/pi/discussions/2520
cjermain《pi-less-yolo》（Docker 沙箱）：https://github.com/cjermain/pi-less-yolo
dalenguyen / Pi Documentation（本地模型 / MCP 配置）：https://github.com/dalenguyen/pi-documentation
Roman Imankulov《Agent engineering: Pi》：https://roman.pt/posts/pi-dev-version
flaviocopes《A deep dive into Pi》：https://flaviocopes.com/pi

上一篇：04 · 多智能体与高级工作流篇｜下一篇：06 · 日常实战 · 模式 · 选型篇