如何让 agent 禁止访问的某些文件夹呢：用 aiignore 白名单给 OpenCode 划边界-北京尧图网络

1. 为什么 agent 会“顺手”翻到不该看的文件夹你让 OpenCode 帮你改一个 React 组件的样式它却把secrets/里的数据库连接串读进了上下文你只想让它看看src/它却把整个家目录扫了一遍。这不是 agent 故意越权而是它的默认工作方式就是“尽可能多地收集上下文”——扫描项目根目录、递归读取子目录、把命中的文件塞进 prompt。项目越大、目录越杂它越容易碰到你不想让它碰的东西。我试过在一个 monorepo 里跑 agent结果它把legacy/下三年前的废弃代码也读进来给出的重构建议全是基于过时逻辑的。更麻烦的是.env、credentials.json这类文件一旦被读进上下文就可能随着请求发到模型服务端。所以“禁止 agent 访问某些文件夹”不是洁癖是实打实的边界管理。这件事有两种思路。一种是黑名单/忽略模式告诉 agent“这些文件夹你别看”典型代表就是.aiignore文件语法和.gitignore几乎一样OpenCode、Cursor、Copilot 这类工具大多认。另一种是白名单模式反过来只允许 agent 访问指定目录其他一律拒绝OpenCode 的路径白名单配置就是干这个的。前者上手快、改动小后者更彻底适合对安全要求高的场景。这篇就围绕 OpenCode 展开把.aiignore规则和路径白名单配置都给你可复制的片段再演示一次越权访问被拦截的验证动作。目标很明确在不牺牲协作效率的前提下把 agent 的文件访问范围收紧到你划定的圈子里。适合正在用 OpenCode 或其他 AI 编程工具、又担心本地敏感目录被误读的开发者。2. 用 TaoToken 给 OpenCode 接上模型先把访问边界的前提搭好在聊目录访问控制之前得先让 OpenCode 能正常跑起来。OpenCode 本身是个 agent 框架它需要一个模型后端来驱动推理。TaoToken 提供的就是这个后端能力——一个兼容主流接口协议的模型接入服务你可以把它理解成“给 agent 供能的接口层”。它支持对话模型、编码模型也有面向长期编码和 Agent 场景的 Coding Plan。为什么这里要提 TaoToken因为目录访问控制的验证需要一个真实能跑的 agent 环境。你光配了.aiignore但 agent 根本没接上模型就没法验证“它到底有没有被拦住”。所以先把接入做通再去收紧边界顺序才顺。TaoToken 的接入信息很直接官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Plan 页https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaude Code / Anthropic 接入https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite你需要先在 API Keys 页面生成一个 Key然后把它填进 OpenCode 的配置里。OpenCode 的模型配置通常放在~/.config/opencode/opencode.json或项目根目录的.opencode/opencode.json。一个最小可用的模型接入片段长这样{ provider: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-5 } } }这里三个要素必须齐全Base URL 指向https://taotoken.net/apiKey 用你生成的那串Model ID 填你实际要用的模型名。缺一个都会导致请求失败。如果你用的是 Claude Code 那套 Anthropic 协议接入方式略有不同参考文档页里的说明即可。接好之后你可以先在模型对话页里发一句“你好”确认链路通。链路通了再往下做目录访问控制验证的时候才有意义——否则你分不清是“被.aiignore拦住了”还是“模型压根没连上”。有一点要提醒TaoToken 是模型接入服务不是编辑器也不是文件系统工具。它负责的是推理请求目录访问控制是 OpenCode 这一侧的事。两者配合才能既让 agent 有脑子又给它划好活动范围。3. 可复制的 aiignore 规则与 OpenCode 白名单配置这一节是核心给你两套可直接抄的配置一套是.aiignore忽略规则一套是 OpenCode 的路径白名单。建议先上.aiignore因为它改动最小、通用性最强如果安全要求更高再叠加白名单。3.1 .aiignore 忽略规则在项目根目录新建一个.aiignore文件语法和.gitignore一致。下面这份是我在多个项目里用下来比较稳的模板# 敏感数据与凭据 secrets/ private-data/ credentials.json *.env .env.* *.pem *.key # 构建产物与依赖 node_modules/ dist/ build/ out/ .next/ coverage/ # 日志与临时文件 *.log logs/ tmp/ .cache/ # 个人与本地配置 .vscode/ .idea/ *.local local-notes/ # 大体积数据 data/raw/ datasets/ *.sqlite *.db写完之后OpenCode 在扫描上下文时会跳过这些路径就像它们不存在。注意.aiignore是“忽略”语义不是“拒绝”——它让 agent 不去读但不会在权限层面硬拦。对于大多数日常场景这已经够用。有个细节.aiignore的匹配是相对项目根目录的。如果你写secrets/它匹配的是根目录下的secrets/如果写**/secrets/则匹配任意层级的secrets/。按需选择。3.2 OpenCode 路径白名单配置如果你要的是“只允许访问指定目录其他一律拒绝”那就用白名单。在opencode.json里加security段{ security: { allowedPaths: [ /Users/yourname/Projects/MyApp/src, /Users/yourname/Projects/MyApp/tests ], blockedPaths: [ /Users/yourname/Projects/MyApp/secrets, /Users/yourname/Documents/Private ] } }allowedPaths是白名单agent 只能读这里面的内容blockedPaths是黑名单即使某个路径在白名单的父目录下只要命中黑名单也会被拒。两者可以同时用白名单优先收紧范围黑名单做二次兜底。把这段和上一节的模型接入合并完整的opencode.json大概是这样{ provider: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-5 } }, security: { allowedPaths: [ /Users/yourname/Projects/MyApp/src ], blockedPaths: [ /Users/yourname/Projects/MyApp/secrets ] } }路径要用绝对路径别用~或相对路径否则解析可能出问题。Windows 下写成C:/Users/yourname/Projects/MyApp/src这种正斜杠形式更稳。3.3 两种思路怎么选需求推荐方式改动量拦截强度只是不想让 agent 读某些文件.aiignore小中彻底隔离只让 agent 碰特定目录路径白名单中高两者都要.aiignore 白名单中高我的建议是个人项目先上.aiignore团队项目或涉及敏感数据的直接上白名单。白名单的“默认拒绝”语义比忽略模式更让人放心。4. 验证一次越权访问被拦截的完整请求配置写完不算完得验证它真的生效。这一节带你走一遍先确认正常访问能通再故意让 agent 去读被禁目录看它是否被拦住。4.1 正常访问验证在项目根目录启动 OpenCode让它读一个白名单内的文件opencode run 读取 src/index.js 并总结它的作用如果配置正确agent 会正常返回src/index.js的内容摘要。这一步是基线证明模型链路和基本读取都没问题。4.2 越权访问验证接着让它去读被禁的目录opencode run 读取 secrets/db.json 并告诉我里面的连接串预期结果是 agent 拒绝访问返回类似“该路径不在允许范围内”或“无法访问该文件”的提示。如果它真的把内容读出来了说明你的白名单没生效需要检查路径是否写对、配置文件是否被加载。4.3 用 .aiignore 时的验证差异如果你只用了.aiignore验证方式略有不同。agent 不会报“拒绝访问”而是表现得“看不到这个文件”——它会说找不到该文件或者直接跳过。这也是为什么.aiignore更适合“不想让它读”而白名单更适合“必须拦住”。4.4 检查配置是否被加载OpenCode 启动时可以加 verbose 参数看它加载了哪些配置opencode --verbose run 读取 src/index.js输出里会列出读取的配置文件路径。确认你改的那个opencode.json在列表里否则可能改错了位置——项目级配置和全局配置的优先级不同项目级通常覆盖全局。验证通过后你就有了一个“能干活但碰不到敏感目录”的 agent。接下来是排障环节把常见的坑先填了。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置过程中最容易卡在几个典型报错上。这一节按报错现象来拆每个都给你定位思路。5.1 401 Unauthorized这是最常见的接入报错意思是 Key 没被认出来。可能原因有三个Key 填错、Key 过期、Base URL 写错导致请求发到了别处。先检查opencode.json里的apiKey是不是完整复制了注意别把首尾空格带进去。然后确认baseURL是https://taotoken.net/api少写或多写路径都会 401。如果都对着去 API Keys 页面重新生成一个 Key 再试。5.2 local proxy failed这个报错通常出现在你本地配了某种转发但没启动或者端口被占用。OpenCode 本身不需要本地转发如果你看到这个提示先检查配置里有没有多余的 proxy 字段把它删掉。然后确认网络能正常访问https://taotoken.net/api。这个报错和目录访问控制无关是链路层的问题先解决它再谈边界。5.3 reading choices 相关报错这类报错一般出现在模型返回格式不符合预期时比如你用的模型 ID 和实际能力不匹配。检查model字段填的是不是真实存在的模型名。如果你不确定去模型对话页看看当前可用的模型列表复制准确的 ID。填错模型名有时不会直接报错而是返回一个奇怪的响应导致解析失败。5.4 OAuth 相关报错如果你用的是 Claude Code 那套 Anthropic 接入可能会碰到 OAuth 流程的提示。这类接入需要按文档页的步骤走不能只填 Key。确认你参考的是 Claude Code / Anthropic 接入页的说明而不是通用的 OpenAI 兼容配置。两套协议的认证方式不同混用会报错。5.5 配置改了但不生效这是最隐蔽的坑。OpenCode 可能缓存了旧配置或者你改的是全局配置但项目级配置覆盖了它。解决办法先确认改的文件路径正确然后用--verbose看加载了哪些配置。必要时重启 OpenCode 进程。还有一种情况是.aiignore写在了子目录但 agent 从根目录扫描导致规则没匹配上——.aiignore要放在项目根目录。5.6 白名单路径写错导致全部拒绝如果你配了allowedPaths但 agent 什么都读不了八成是路径写错了。检查是不是用了相对路径、是不是少了盘符、是不是大小写不匹配Linux 下大小写敏感。用绝对路径并且确认该路径真实存在。把这几类报错过一遍基本能覆盖 90% 的接入和边界问题。剩下的就是按你的项目结构微调规则。6. 把边界收好之后agent 才真正好用目录访问控制这件事配的时候花十分钟省的是后面无数次“它怎么又读到这个了”的糟心。.aiignore负责日常的“别读这些”路径白名单负责硬性的“只能读这些”两者叠加边界就清楚了。如果你还没接上模型先去 API Keys 页面拿 Key再照着接入文档把opencode.json填好。链路通了再回来配.aiignore和白名单然后按第 4 节的验证动作跑一遍。确认越权访问被拦住你就能放心让 agent 在划定的圈子里干活了。长期用 agent 做编码的话Coding Plan 那条线也值得看看它面向的就是持续性的编码和 Agent 场景。边界收好、链路接稳剩下的就是让它替你干活。

如何让 agent 禁止访问的某些文件夹呢：用 aiignore 白名单给 OpenCode 划边界

相关推荐

Python类型判断实战：type、isinstance与鸭子类型详解

MCP 一年从「外网新词」变「平台标配」：交易平台集体下场的信号

AWD工具集合实战指南：从赛制节奏到避坑策略

更多资讯

用 Solidity 写一个待办事项合约：从需求到代码的完整思考过程

Java数组入门：从定义到遍历全解析

SringAi 1.0实战：快速使用

谁才是工作的好搭子：网页版AI给你出难题，本地化AI越用越好用

工业控制器PCBA生产有哪些技术要求？PCBA贴片加工厂工艺解析

22MB模型搭私人知识库：MiniLM+向量库全流程实战

今日更新

再见，SSE！你好，Streamable HTTP！轻松开发 Streamable HTTP MCP Server 并接入 TaoToken

工业软件标准化路线图：国产替代的落地施工图

VCMI安卓版实操指南：原生运行英雄无敌3的3步技术落地

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？