企业官网建设流程全解析

1. 从 OpenClaw 的 18 万 Star 说起：Pi Agent SDK 到底解决了什么问题

如果你最近在 GitHub 上刷到过一个叫 OpenClaw 的项目，大概率会注意到它那夸张的 Star 增速。一个能在你本地电脑上跑起来、帮你读写文件、执行命令、装依赖、跑脚本的智能体，听起来像是把一整套 DevOps 流水线塞进了一个对话框。但真正让技术人好奇的不是它「能做什么」，而是它「怎么做到的」——毕竟市面上不缺功能列表华丽的 Agent 框架，缺的是能稳定跑完长任务、不中途发疯、不把上下文撑爆的引擎。

OpenClaw 背后的引擎就是 Pi Agent SDK。我第一次拆它的源码时，最直观的感受是「空」——不是功能空，而是抽象层薄得惊人。很多框架喜欢在 LLM 和工具之间塞一堆中间层：任务规划器、记忆管理器、工具路由器、反思模块……Pi 几乎把这些全砍了，只留下一个 Agent Loop 和四个工具。这种极简不是偷懒，而是一种工程判断：大模型本身已经足够聪明，框架要做的是别挡路。

这篇文章面向的是想在自己项目里复现同类架构的开发者。你会看到 Agent Loop 的调度逻辑、pi-ai 抽象层如何做到跨模型切换、bash 工具链的注册与调用链路，以及一套可以直接复制的最小配置。我试过在本地把一个精简版 Agent 跑通，过程中踩的坑也会一并写出来。核心检索词先摆在这里：Pi Agent SDK 是一个极简 Agent 引擎，OpenClaw 是它的上层应用，Agent Loop 是它的调度核心，pi-ai 是它的模型抽象层，bash 是它权限最大的工具。适合谁？适合已经用过 LangChain 或 AutoGPT、觉得太重、想自己掌控每一行调度逻辑的人。

2. TaoToken 前置准备：给 Agent Loop 接上稳定的模型出口

在拆 Agent Loop 之前，得先解决一个现实问题：你的循环再优雅，模型请求不稳定也是白搭。Pi Agent SDK 本身不绑定任何模型厂商，它通过 pi-ai 层做抽象，这意味着你可以把任何兼容 OpenAI 协议的服务接进来。我自己的做法是用 TaoToken 作为统一出口，原因是它在跨模型切换时不需要改代码，只改配置。

先拿 Key。打开 https://taotoken.net/api-keys ，登录后创建一个 API Key。注意这个 Key 只在创建时完整显示一次，复制后先存到本地环境变量里，别直接写进代码提交到 Git。我习惯用.env文件加.gitignore，或者直接用 shell 的 export。

export TAOTOKEN_API_KEY="sk-你的key"

Base URL 用https://taotoken.net/api，注意不要加 UTM 参数，那是给网页链接用的，API 端点保持干净。Model ID 这块，Pi 的 pi-ai 层支持在配置里写模型名，你可以先用claude-sonnet-4-20250514或者gpt-4o这类通用 ID 测试，确认链路通了再换。如果你打算长期跑编码类 Agent，可以了解下 Coding Plan（https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ），它在长任务场景下的额度策略更友好。

这里有个容易忽略的点：Pi 的 Agent Loop 会在一次任务里发起多次模型请求，每次请求都携带历史上下文。如果你的出口有并发限制或速率限制，循环跑到一半被限流，整个任务就断了。所以前置准备不只是拿 Key，还要确认你的出口能扛住连续请求。TaoToken 的接入文档在 https://taotoken.net/doc ，里面有关于请求头和错误码的说明，建议先扫一遍。

注意：不要把 API Key 硬编码在 Agent 的配置文件里。Pi 的 bash 工具权限很大，如果 Agent 被诱导执行了cat config.json，你的 Key 就泄露了。用环境变量注入是底线。

3. 可复制配置：Agent Loop 最小片段与 bash 工具注册示例

现在进入正题。Pi Agent SDK 的配置哲学是「能少写就少写」，但少写不等于不写。下面这份配置是我本地跑通的最小版本，你可以直接复制到项目根目录的agent.config.json里，改掉 Key 和模型 ID 就能用。

{ "agent": { "name": "pi-minimal", "maxIterations": 25, "loop": { "observe": true, "decide": true, "act": true, "reflectOnError": true } }, "piAi": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKeyEnv": "TAOTOKEN_API_KEY", "modelId": "claude-sonnet-4-20250514", "contextSerialization": true, "fallbackModels": ["gpt-4o", "kimi-k2"] }, "tools": { "read": { "enabled": true, "rootDir": "./workspace" }, "write": { "enabled": true, "rootDir": "./workspace" }, "edit": { "enabled": true, "rootDir": "./workspace" }, "bash": { "enabled": true, "timeoutMs": 30000, "allowedCommands": ["ls", "cat", "grep", "find", "node", "npm", "python3", "pip", "git"], "denyPatterns": ["rm -rf /", "curl.*\\|.*sh", "chmod 777"] } } }

这份配置里有几个关键字段值得展开。maxIterations是 Agent Loop 的硬刹车，防止模型陷入死循环无限调用工具。我设 25 是因为大多数编码任务在 15 到 20 轮内能收敛，留点余量。contextSerialization是 pi-ai 层的核心能力，它把对话历史序列化成模型无关的格式，这样你在fallbackModels里切换模型时，上下文不会丢。bash工具的allowedCommands和denyPatterns是安全边界，虽然 Pi 的设计哲学是「给 AI 最小但通用的工具」，但最小不等于无限制，白名单加黑名单双保险。

bash 工具的注册在 Pi 里不是写代码，而是写一段 Markdown 描述。这是它和其他框架最大的区别：你不需要实现一个bashTool类，只需要告诉模型这个工具怎么用。在tools/bash.md里写：

# bash 工具 你可以通过 bash 执行系统命令来完成文件操作、依赖安装、脚本运行。 ## 使用规则 - 每次只执行一个命令，等待结果后再决定下一步 - 命令输出超过 200 行时，用 head 或 tail 截取关键部分 - 安装依赖前先检查 package.json 或 requirements.txt - 执行失败时，先读错误信息，再决定是否重试 ## 示例 - 查看目录：ls -la - 搜索代码：grep -rn "functionName" ./src - 运行测试：npm test

这段 Markdown 会被注入到系统提示里，模型据此决定何时调用 bash。你可能会问：这不就是提示词工程吗？是的，Pi 把「工具实现」和「工具描述」解耦了，扩展新能力不需要改引擎代码，写文档就行。这种设计让 Agent 的能力边界变得极其灵活，但也意味着你的描述质量直接决定工具调用准确率。

4. 验证请求：本地跑通 Agent Loop 的完整步骤

配置写好了，接下来验证它真的能跑。我建议分三步走，每步都有明确的成功标志，避免一上来就跑复杂任务然后对着报错发呆。

第一步，验证 pi-ai 层的连通性。写一个最小脚本test-piai.mjs：

import { PiAi } from '@pi-agent/pi-ai'; const ai = new PiAi({ baseUrl: 'https://taotoken.net/api', apiKey: process.env.TAOTOKEN_API_KEY, modelId: 'claude-sonnet-4-20250514' }); const res = await ai.chat([ { role: 'user', content: '只回复两个字：通了' } ]); console.log(res.content);

跑node test-piai.mjs，如果输出「通了」，说明模型出口没问题。如果报 401，检查 Key 是否导出到了当前 shell；如果报 model not found，检查 Model ID 拼写。

第二步，验证 Agent Loop 的调度。写test-loop.mjs：

import { AgentLoop } from '@pi-agent/core'; import config from './agent.config.json' assert { type: 'json' }; const loop = new AgentLoop(config); const result = await loop.run('在当前目录创建一个 hello.txt，内容写 Hello Pi'); console.log('迭代次数:', result.iterations); console.log('最终输出:', result.output);

成功标志是：workspace 目录下出现hello.txt，且result.iterations大于 1。大于 1 说明 Loop 真的在「观察-决定-执行」多轮调度，而不是一次模型调用就结束。

第三步，验证 bash 工具链。把任务换成「用 bash 列出当前目录所有 .json 文件，并把文件名写入 filelist.txt」。这一步会触发 bash 工具的注册、调用、结果回传全链路。如果 filelist.txt 内容正确，说明工具链通了。

实测下来，最容易卡住的是第二步。常见现象是 Loop 只跑一轮就停，原因是模型没有正确输出工具调用格式。这时候检查你的 bash.md 描述是否清晰，以及 pi-ai 的contextSerialization是否开启。另外，maxIterations设太小也会导致任务没完成就退出，先设 25 跑通再调优。

5. 本篇常见错排查：401、local proxy failed 与 reading choices 报错

排障这部分我按真实遇到的报错来写，每个都给出定位思路和修复动作。

401 Unauthorized。这是最高频的。Pi 的 pi-ai 层在发起请求时，如果apiKeyEnv指向的环境变量为空，会直接抛 401。排查顺序：先在终端echo $TAOTOKEN_API_KEY确认有值；再确认 Node 进程能读到这个变量（有些 IDE 的调试配置不继承 shell 环境）；最后检查 Key 是否被复制时带了空格。修复就是重新 export 一次，或者用 dotenv 在脚本开头加载。

local proxy failed。这个报错通常出现在你本地配了 HTTP 代理，但 Pi 的请求没走代理或者代理不可达。注意，这里说的是本地开发环境的网络配置问题，不是让你去搞什么特殊网络手段。修复方式是检查HTTP_PROXY/HTTPS_PROXY环境变量，如果不需要代理就 unset 掉；如果公司网络有要求，确保代理地址正确。Pi 的 pi-ai 层默认读取系统代理设置，行为和其他 HTTP 客户端一致。

reading 'choices' of undefined。这个报错说明模型返回的 JSON 结构里没有choices字段，而 pi-ai 层在解析时直接读了它。原因通常是 Base URL 配错了，请求打到了某个返回 HTML 错误页的地址，解析 JSON 失败后变成 undefined。检查你的baseUrl是不是https://taotoken.net/api，注意结尾不要多加/v1或斜杠，除非文档明确要求。另外，如果模型 ID 不存在，有些出口会返回非标准错误结构，也会触发这个报错。

OAuth token expired。如果你用的是某些需要 OAuth 的模型服务，token 过期后会报这个。Pi 本身不管理 OAuth 刷新，它把这部分交给 pi-ai 的 provider 实现。修复方式是重新走一遍授权流程，或者换成 API Key 认证的出口。这也是我推荐用统一 API 出口的原因，省掉 OAuth 刷新的心智负担。

bash 工具超时。报错信息通常是bash timeout after 30000ms。这说明命令执行超过了timeoutMs配置。排查：先手动在终端跑一遍那个命令，看是不是真的慢；如果是npm install这类正常慢命令，把timeoutMs调到 120000；如果是命令卡死，检查是否有交互式提示等待输入，bash 工具不支持交互，需要加--yes或-y参数。

提示：排障时把maxIterations临时设为 3，让 Loop 快速失败，这样你能更快看到报错，而不是等 25 轮跑完。定位到问题后再调回去。

6. 语义一致 CTA：把极简 Agent 架构落到你自己的项目里

拆完 Pi Agent SDK 的 Agent Loop、pi-ai 抽象层和 bash 工具链，你会发现它的极简不是功能少，而是抽象层薄、扩展点清晰。Agent Loop 只做观察-决定-执行-反思四件事，pi-ai 只做模型无关的上下文序列化，bash 工具只做命令执行和结果回传。每个模块的职责边界都很硬，所以你能单独替换其中一层而不影响其他层。

如果你想在自己的项目里复现这套架构，建议从最小闭环开始：先用一份 JSON 配置把 Loop 跑起来，接一个模型出口，注册 bash 工具，跑一个「创建文件」的任务。跑通之后再逐步加 read、write、edit，最后再考虑多模型 fallback 和错误自愈。不要一上来就堆功能，Pi 的哲学是「少即是多」，你加得越多，调试成本越高。

模型出口这块，如果你不想自己维护多厂商的 Key 和额度，可以用 TaoToken 的统一 API（https://taotoken.net/api ）作为 pi-ai 层的 provider，Base URL 填https://taotoken.net/api，Key 从 https://taotoken.net/api-keys 拿，Model ID 按需切换。接入文档在 https://taotoken.net/doc ，里面有完整的请求示例和错误码对照。想先感受下模型对话效果，可以走 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。长期跑编码类 Agent 的话，Coding Plan 的额度策略更合适，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

最后说一个我踩过的坑：Pi 的 bash 工具默认继承当前工作目录，如果你在项目根目录跑 Agent，它可能误改你不想动的文件。我的做法是在配置里把rootDir指向一个独立的workspace目录，Agent 的所有文件操作都限制在里面。这样即使模型判断失误，损失也可控。极简架构给了你掌控权，但掌控权也意味着你得自己设边界。