1. 从一次误删事故说起Agent Loop 与 Permission System 到底在防什么很多人第一次用 Claude Code 这类编码 Agent都会经历一个心理转折前十分钟觉得它像个听话的实习生半小时后开始担心它像个过于热心的同事——你只是让它「清理一下构建产物」它可能顺手把dist、.cache甚至某个还没提交的临时目录一起删了。这不是模型笨恰恰相反是它太想帮你把任务做完。Claude Code 的核心检索词就三个Agent Loop智能体循环、Permission System权限系统、沙箱Sandbox。它们分别回答三个问题Agent 怎么持续干活、谁来决定某个动作能不能执行、执行时怎么保证出错也不炸。适合谁看适合已经用过 Claude Code、Cline、Codex 这类工具想搞清楚「为什么它要这么设计」并且想把这套思路落地到自己项目里的开发者。我试过把 Claude Code 的架构拆开看会发现它和早期 LangChain 那种 Workflow 路线是两种哲学。Workflow 是「你画好流程图模型在节点间流转」好处是可控坏处也是可控——所有可能性都被你框死了。而 Agent Loop 走的是 ReAct 模式本质是一个 while 循环模型推理出下一步动作框架执行工具把结果喂回模型再推理直到任务完成。它把「怎么走」的决定权交给了模型人只负责给目标和边界。但高自由度必然带来风险。于是 Claude Code 做了决策与执行分离模型只负责「决定调用哪个工具、传什么参数」真正执行的是框架本身而执行前必须过 Permission System 这一关。这一关的优先级是 Deny Ask Allow也就是 Deny-First。为什么不是 Allow-First因为安全默认值必须是「不确定就拦」。Anthropic 有个统计很说明问题当 Claude Code 弹窗问用户「是否允许执行这个工具调用」时93% 的回答都是 Allow。这意味着人根本不会仔细看弹窗形同虚设。所以真正靠得住的不是「问用户」而是沙箱和 worktree 这种隔离机制——即使用户手滑点了允许损失也被限制在可控范围内。理解了这三点你才能理解为什么 CLAUDE.md 是明文存储、为什么权限规则要写成 JSON、为什么沙箱不是可选项。下面我会从配置落地讲起把 Agent Loop 的循环控制、Permission System 的规则写法、沙箱的边界验证一步步拆开最后给你一份可以直接抄的 CLAUDE.md 和权限配置。2. TaoToken 前置准备把 Base URL、Key、Model ID 三件套配齐在讲 Claude Code 的架构落地之前得先有一个能稳定调用的模型入口。Claude Code 本身是个客户端框架它需要一个兼容 Anthropic API 的服务端来跑 Agent Loop。这里我用 TaoToken 作为接入层因为它同时提供模型对话、Coding Plan 和 API Keys 管理适合做这种需要反复调试的 Agent 场景。先说清楚三件套这是后面所有配置的基础缺一不可Base URLhttps://taotoken.net/api注意这个地址不带任何查询参数是纯 API 根路径。API Key在控制台的 API Keys 页面生成格式通常是一串以sk-开头的字符串。Model ID比如claude-sonnet-4-5这类具体模型标识要和你在 Coding Plan 里选的模型一致。为什么强调「三件套要写全」因为 Claude Code、Cline、Codex 这些工具在配置时任何一个缺失都会导致请求失败而且报错信息往往很含糊。比如只填了 Base URL 没填 Model ID可能报reading choices之类的解析错误Key 写错则直接 401。把这三个当成一个整体来配能省掉大量排查时间。具体操作路径是这样的先到控制台生成 API Key然后确认你要用的 Model ID最后把 Base URL 填进 Claude Code 的配置。如果你用的是 Claude Code 的 settings 文件配置大概长这样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你用的是 Codex 的auth.json结构会不一样但三件套的逻辑相同{ base_url: https://taotoken.net/api, api_key: sk-你的key, model: claude-sonnet-4-5 }这里有个容易踩的坑Base URL 末尾不要多加/v1或/chat/completions不同客户端对路径拼接的处理不一样多写反而会 404。TaoToken 的 API 根路径就是https://taotoken.net/api客户端会自己拼后续路径。配好之后建议先用模型对话页面做一次最小验证确认 Key 和 Model ID 是通的再去跑 Claude Code 的 Agent Loop。因为 Agent Loop 会连续发多次请求如果基础调用都不通循环里会疯狂报错很难定位是配置问题还是权限问题。另外如果你打算长期跑编码任务Coding Plan 会比按次调用更划算而且它和 API Keys 是打通的切换时不用改 Base URL。对于要反复调试 Permission System 规则的场景这点很重要——你会需要大量试错。3. 可复制配置CLAUDE.md 与权限规则 JSON 怎么写这一节是全文的核心直接给你能抄的配置。Claude Code 的 Agent Loop 之所以能安全地跑靠的是两层约束一层是 CLAUDE.md 里的行为约定另一层是 Permission System 的规则文件。前者告诉模型「你应该怎么做」后者告诉框架「什么能执行、什么要问、什么直接拒」。先说 CLAUDE.md。它的定位是「项目级记忆」明文存储模型每次启动都会读。所以它既是给模型看的说明书也是你审计 Agent 行为的入口。一份实用的 CLAUDE.md 应该包含项目结构说明、常用命令、禁止事项、以及权限相关的约定。下面这份可以直接改# 项目约定 ## 项目结构 - 源码在 src/测试在 tests/构建产物在 dist/ - 配置文件在 config/不要手动改 dist/ 下的任何文件 ## 常用命令 - 安装依赖npm install - 跑测试npm test - 构建npm run build - 本地启动npm run dev ## 禁止事项 - 不要执行 rm -rf不要删除 dist/ 以外的目录 - 不要修改 .env、.git/config、package-lock.json - 不要执行 git push、git reset --hard - 不要访问项目目录以外的路径 ## 权限约定 - 读文件、跑测试可以直接执行 - 写文件、装依赖需要确认 - 删除文件、改 git 历史默认拒绝这份文件的关键在于「禁止事项」和「权限约定」两段。它们不是硬约束而是给模型的行为提示真正兜底的是 Permission System。但两者配合起来效果最好模型看到 CLAUDE.md 会主动避开危险操作减少弹窗次数而权限规则则在框架层拦截漏网之鱼。接下来是权限规则。Claude Code 的权限配置通常放在 settings 文件里用 JSON 描述。核心是三个数组deny、ask、allow优先级从高到低。写法如下{ permissions: { deny: [ Bash(rm -rf:*), Bash(git push:*), Bash(git reset --hard:*), Write(.env), Write(.git/**) ], ask: [ Bash(npm install:*), Bash(npm run build:*), Write(src/**), Edit(src/**) ], allow: [ Read(**), Bash(npm test:*), Bash(git status:*), Bash(git diff:*) ] } }这里的设计意图很明确deny放最危险的操作直接拒绝连问都不问ask放有副作用但常见的操作弹窗让用户确认allow放只读或低风险操作全程放行。注意deny的优先级最高即使某个操作同时匹配allow和deny也会被拒绝。这就是 Deny-First 的落地方式。有个细节值得说Bash(rm -rf:*)这种写法里的:*是通配符表示匹配以rm -rf开头的所有命令。如果你只写Bash(rm -rf)可能匹配不到带参数的变体。所以规则要写得稍微宽一点宁可多拦不可漏拦。再配合沙箱使用。Claude Code 支持在沙箱环境里执行工具调用比如用 worktree 隔离出一个临时工作目录Agent 在里面怎么折腾都不影响主仓库。配置沙箱通常需要在启动时加参数或者在 settings 里指定{ sandbox: { enabled: true, worktree: true, allowedPaths: [src, tests, config], deniedPaths: [dist, .git, node_modules] } }这样即使 Permission System 被绕过或者用户手滑点了 AllowAgent 也只能在allowedPaths里活动deniedPaths里的东西碰不到。这就是「人也会犯错」的兜底。把 CLAUDE.md、权限 JSON、沙箱配置三样配齐你的 Agent Loop 才算真正可控。下面讲怎么验证这套配置生效。4. 验证请求与成功结果跑一次 Agent Loop 看权限拦截配置写完不验证等于没配。这一节给你一套可复现的验证步骤确认 Agent Loop 在跑、Permission System 在拦、沙箱在隔离。第一步先确认基础调用通。用 curl 直接打 TaoToken 的 API验证 Key 和 Model IDcurl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 128, messages: [{role: user, content: 回复 ok}] }如果返回里有正常的content字段说明三件套没问题。如果报 401检查 Key如果报模型不存在检查 Model ID如果报路径错误检查 Base URL 是不是多写了后缀。第二步启动 Claude Code让它做一个「应该被拦截」的操作。比如在对话里输入「帮我删除 dist 目录下的所有文件」。观察它的行为如果配置生效它应该先尝试调用 Bash 工具然后被 Permission System 拦截弹出确认或直接拒绝。如果它直接执行了说明deny规则没生效检查 JSON 格式和路径匹配。第三步验证沙箱隔离。让 Agent 尝试写一个allowedPaths之外的文件比如/tmp/test.txt或项目根目录的secret.txt。如果沙箱生效这个操作应该失败报错类似path not allowed或sandbox violation。第四步看 Agent Loop 的循环控制。给它一个多步任务比如「跑测试如果有失败就修复然后重新跑」。观察它是否在循环跑测试 → 读报错 → 改代码 → 再跑测试。如果它跑一次就停说明循环没起来可能是模型没返回工具调用或者框架没把结果喂回去。成功的结果应该长这样Agent 连续执行多个工具调用每次调用前权限系统按规则放行或拦截沙箱限制路径最终任务完成。你可以在会话记录里看到完整的调用链因为 Claude Code 是明文存储会话的每一步都可追溯。这里有个实测经验如果 Agent Loop 卡住不动先看是不是某个工具调用在等用户确认Ask 规则触发而你没注意到弹窗。Claude Code 的弹窗有时候会被终端输出淹没建议把终端窗口拉大一点。验证通过后你就有了一个可控的 Agent 环境。接下来讲常见报错怎么排查。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置 Agent 环境时报错信息往往比代码还难懂。这一节把最常见的几类错误和对应解法列出来都是真实会遇到的。401 Unauthorized。这是最直接的Key 不对或没传。检查三处API Key 是不是复制完整有时候会漏掉末尾字符、请求头字段名对不对Anthropic 用x-api-keyOpenAI 兼容用Authorization: Bearer、Key 有没有过期。如果用的是 TaoToken到控制台的 API Keys 页面重新生成一个替换掉配置里的旧值。local proxy failed。这个报错通常出现在客户端尝试走本地代理但连不上时。先确认你的 Base URL 是不是写成了http://localhost:xxxx之类的本地地址。如果是改成https://taotoken.net/api。另外检查环境变量里有没有残留的HTTP_PROXY、HTTPS_PROXY这些会干扰请求。清掉再试。reading choices 相关报错。这类错误一般出现在解析响应时比如cannot read property choices of undefined。原因是客户端按 OpenAI 格式解析但服务端返回的是 Anthropic 格式或者反过来。检查你的客户端配置里API 格式选的是不是和 Base URL 匹配。TaoToken 同时支持两种格式但路径不同Anthropic 格式走/v1/messagesOpenAI 格式走/v1/chat/completions。配错了就会解析失败。OAuth 相关报错。如果你用的是需要 OAuth 登录的客户端比如某些版本的 Claude Code可能会遇到 token 刷新失败。这种情况通常是 OAuth 配置和 API Key 混用了。建议统一用 API Key 方式在 settings 里明确写ANTHROPIC_API_KEY不要同时开 OAuth。如果必须用 OAuth确认回调地址和客户端配置一致。权限规则不生效。检查 JSON 格式permissions下面的deny、ask、allow必须是数组每项是字符串。路径匹配要注意大小写和通配符。比如Write(src/**)匹配src下所有文件但Write(src/*)只匹配一层。改完规则后重启 Claude Code因为权限配置通常在启动时加载。沙箱报 path not allowed。说明 Agent 尝试访问allowedPaths之外的位置。要么把路径加进白名单要么调整任务让它别越界。注意deniedPaths优先级高于allowedPaths如果某个路径同时出现在两边会被拒绝。Agent Loop 不循环。如果 Agent 执行一次工具就停检查模型返回里有没有tool_use类型的 content。如果没有可能是模型没理解任务或者 max_tokens 太小导致输出被截断。把 max_tokens 调大或者在 CLAUDE.md 里明确要求「完成任务前不要停止」。排查的核心思路是先确认基础调用通curl 验证再确认权限规则加载看启动日志最后确认沙箱边界故意越界测试。一层层往下查比瞎改配置快得多。6. 把架构思路落地到自有项目从 CLAUDE.md 到权限边界理解了 Claude Code 的 Agent Loop、Permission System 和沙箱设计最终目的是把这套思路用到自己的项目里。不管你是做内部工具、还是给团队搭编码 Agent这几个原则可以直接迁移。第一决策与执行分离。你的 Agent 框架里模型只负责输出「要调用什么工具、传什么参数」真正执行工具的是框架代码而且执行前必须过权限层。这样即使模型幻觉也不会直接造成破坏。实现上就是一个中间件模型返回 tool_use → 权限检查 → 通过则执行 → 结果回传。第二Deny-First 的权限默认值。不要设计成「默认允许危险操作才拦」而要设计成「默认拒绝明确允许才放行」。因为用户对弹窗的注意力极低93% 的 Allow 率说明「问用户」不是安全机制。真正的安全机制是默认拒绝加沙箱隔离。第三明文可审计。Claude Code 把会话和记忆明文存储这个选择很关键。它让 Agent 的每一步都可追溯、可修改。你的项目里也可以用类似方式把 Agent 的决策日志、工具调用记录写成明文文件方便事后审计和调试。向量数据库适合检索但不适合审计两者可以并存。第四CLAUDE.md 作为行为契约。它不只是给模型看的提示词更是团队约定的载体。把项目结构、常用命令、禁止事项写进去新人和 Agent 都能快速上手。而且它是版本控制的改动能被 review。具体落地时你可以先从一个最小闭环开始一份 CLAUDE.md 一份权限 JSON 一个沙箱配置。跑通之后再逐步细化规则。比如先只配deny和allow观察哪些操作需要ask再补进去。规则不是一次写好的是跑出来的。如果你要长期跑编码任务建议用 Coding Plan 配合 API Keys这样调试权限规则时不用担心调用成本。模型对话页面可以用来快速验证单个工具调用的行为接入文档里有完整的路径和参数说明。把这套配置跑顺之后你会发现 Agent 不再是「不可控的黑盒」而是一个边界清晰、可审计、可回滚的协作工具。