本地部署 Claude 3.5 Agent 的实战要点：OpenClaw、文件系统沙箱与成本控制

引言

在尝试将 Claude 3.5 Sonnet 与 OpenClaw 结合，使用 Telegram 作为轻量控制界面，构建本地自主代理的过程中，我遇到了一系列容易被忽视的坑。下面把部署流程、常见故障以及安全/成本考量系统化整理，供同类项目参考。

1. 架构优先于提示

输入 → 代理 → 模型 → 工具执行 → 状态 → 循环 整个闭环必须在代码层面明确权限边界。若文件系统访问未被限制，代理可以自行遍历磁盘、读取或写入任意文件，导致安全风险远超模型本身的“幻觉”。

2. Node 版本硬性要求

OpenClaw 采用 ESM 语法，仅在 Node v24（或更高）下可正常解析。使用旧版 Node 会抛出类似 ERR_MODULE_NOT_FOUND 的错误，且这些错误往往只出现在后台日志，容易被误判为模型失效。

3. 递归推理的代价

如果不为代理设置 MAX_STEPS（或等价的步数上限），递归调用会在毫秒级完成，却瞬间消耗数千 token，导致费用激增。建议在配置文件中加入：

{
  "max_steps": 10,
  "token_budget": 5000
}

并配合硬性超时（如 setTimeout）进行二次防护。

4. Webhook 并非模型故障

Telegram Bot 的 webhook 配置极其敏感：端口不匹配、TLS 证书错误或绑定的 URL 与实际服务不一致时，Telegram 会直接返回空响应，表面上看像是模型“卡死”。排查时先检查 ngrok/cloudflared 的转发日志，再确认 Bot Token 与 webhook URL 是否对应。

5. 沙箱隔离是底线

我将所有文件系统工具的根目录限制在 ./sandbox，并在启动脚本中加入 process.chdir('./sandbox')。切忌在项目根目录或系统根目录下直接执行工具，否则极易触发权限提升或意外删除关键文件。

实践建议

• 工具权限：采用 OS‑level 的 chroot 或容器化（Docker）方式，将可写目录显式挂载；在代码层面使用白名单路径检查。
• 循环步数限制：默认 MAX_STEPS=5~10，根据任务复杂度逐步调高；配合 token 预算防止“无限递归”。
• 成本控制：开启 Claude 的 usage 监控，实时记录 input_tokens、output_tokens；在超过阈值时自动暂停代理或回退到低成本模型（如 Claude 3.0 Haiku）。

结语

上述经验来源于一次完整的本地部署实验，涵盖了从环境准备到安全防护的全链路。希望能帮助其他开发者在搭建自主 LLM 代理时少走弯路。