企业官网建设流程全解析

CodeWhale网络策略：如何为AI Agent的联网行为设白名单

【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhale

CodeWhale 是一个用 Rust 编写的开源终端 AI 编码 Agent。当它的fetch_url、web_search等工具需要联网时，内置的**网络策略（Network Policy）**让你按域名设置白名单 / 黑名单，每次出站请求都可审计，被拦截的请求会明确告知原因。这篇指南帮你 3 步完成配置。

一、为什么 AI Agent 联网需要白名单？

AI Agent 会根据模型给出的 URL 主动发起网络请求，这带来三类风险：

• 提示注入：网页内容诱导 Agent 把请求发往陌生域名，造成信息外泄；
• SSRF 攻击：让 Agent 抓取169.254.169.254（云元数据）或127.0.0.1本地服务；
• 不可预期的流量：Agent 在错误域名上反复重试，浪费配额。

CodeWhale 用策略 + 审计两层机制回应这些风险：

1. 策略层：按域名（host）给出Allow（放行）/Deny（拒绝）/Prompt（弹窗征求同意）三种决策，且deny 优先——同一域名同时出现在 allow 和 deny 中时，一律拒绝；
2. 审计层：每次网络调用在~/.codewhale/audit.log追加一行记录，方便事后复盘"Agent 到底访问过哪些站"。

二、3 步快速上手：配置网络白名单

说明：[network]配置段是按需启用的。不写该段时不强制执行策略（兼容旧版本行为）；一旦写入即全面生效。

第 1 步：打开配置文件，加入 [network] 段

配置文件位于~/.codewhale/config.toml（各选项参考 config.example.toml 第 927–951 行的注释模板）：

[network] default = "prompt" # 未匹配域名的默认动作：prompt allow = ["api.deepseek.com", "github.com", ".githubusercontent.com"] deny = [] # 始终拒绝的域名 audit = true # 每次调用写一行审计日志

三种default值适合不同信任场景：

第 2 步：用 /network 命令随时增删白名单

不想手动改文件？在 TUI 里直接输入命令即可（实现见crates/tui/src/commands/groups/utility/network.rs）：

/network list # 查看当前策略 /network allow github.com # 加入白名单（支持直接粘贴完整 URL） /network deny tracker.example.com # 加入黑名单 /network remove github.com # 移除条目 /network default deny # 切换默认动作

命令会自动把 URL 归一化为域名（https://github.com/xxx→github.com），并把结果持久化到配置文件，重启不丢失。

第 3 步：验证生效

让 Agent 抓一个白名单外的页面，若返回如下提示，说明策略已工作：

network call to 'xxx' requires approval; re-run after /network allow xxx

三、域名匹配规则速查表

匹配忽略大小写、自动去除末尾的点。通配写法.example.com与*.example.com等价，只匹配子域名、不匹配主域本身：

想让主域和所有子域都放行，需要两条都写：["example.com", ".example.com"]。

核心判定逻辑（含 deny 优先、会话级缓存）位于crates/tui/src/network_policy.rs。

四、审计日志：谁在什么时候访问了什么

开启audit = true（默认）后，每次网络调用追加一行纯文本记录：

2026-08-28T05:31:22+08:00 network api.deepseek.com fetch_url Allow 2026-08-28T05:32:10+08:00 network evil.example.com web_search Deny

决策标签含义一目了然：

日志文件固定在~/.codewhale/audit.log，tail -f即可实时观察 Agent 的联网行为。

五、白名单之上：还有一道 SSRF 防线

即使某个域名被你加入白名单，CodeWhale 仍会在 DNS 解析后做二次校验（见crates/tui/src/tools/web/guard.rs）：

• 私网 / 回环 / 链路本地 / 云元数据 IP 一律拦截——防止"域名合法但解析到内网"的重绑定（rebinding）攻击；
• DNS 结果会被"钉住"，HTTP 客户端绑定到已验证的 IP，避免校验通过后地址被偷换；
• 环境代理被禁用，防止请求绕过本进程经代理二次解析；
• 使用 fake-IP 模式代理（如 TUN 透明代理）的用户，可通过[network]的proxy+proxy_fake_ip_cidrs（仅限198.18.0.0/15段）精确放行占位地址，真实内网地址仍不可绕过。

影响范围：fetch_url、web_search等联网工具与 MCP HTTP 传输受策略约束；直连 LLM 的 API 调用和 stdio 类型的 MCP 服务器不受影响。另外/skill install也受[network]门禁，安装前确保github.com、raw.githubusercontent.com可达。

六、推荐实践清单

• 🛡️ 新手默认用default = "prompt"，用"永久放行"选项逐步养成白名单；
• 🚫 把广告/统计域名放进deny——deny 优先，能压过任何宽泛的 allow；
• 🔍 定期tail ~/.codewhale/audit.log复盘 Agent 的访问足迹；
• 📦 白名单只列你确认需要的域名，子域用.域通配，主域单独列出。

相关文件索引：策略核心crates/tui/src/network_policy.rs· SSRF 守卫crates/tui/src/tools/web/guard.rs·/network命令crates/tui/src/commands/groups/utility/network.rs· 配置模板config.example.toml· 配置文档docs/CONFIGURATION.md

【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhale