Agent Reach 服务器端 Cookie 导出实战：从本地浏览器到远程 Agent 的安全凭据配置指南

本文基于 Agent Reach 仓库中的 Cookie 导出指南，完整讲解当你的 AI Agent 部署在无浏览器的服务器上时，如何从本地计算机导出 Twitter/X、小红书、Bilibili 等平台的登录 Cookie，并通过 agent-reach configure 安全地写入配置。读完后，你将掌握 Cookie-Editor 扩展导出、DevTools 手动导出两种方法的完整操作步骤，理解 --stdin 隐藏输入机制，并能从源码层面确认凭据的解析格式、落盘位置与文件权限边界。

一、背景：为什么服务器上的 Agent 需要"导入"Cookie

Agent Reach 的定位是"Give your AI agent eyes to see the entire internet"——让 Agent 通过 CLI 读取和搜索 Twitter、Reddit、YouTube、GitHub、Bilibili、小红书等平台，零 API 费用。许多需要登录态的功能（如 Twitter 高级检索、小红书笔记读取）依赖用户账号的 Cookie。

docs/cookie-export.md 开篇就点明了适用场景：

Your Agent is on a server and can't access your browser directly. Here's how to export cookies from your local computer — fastest method first.

即：Agent 运行在服务器上，无法直接访问你本地浏览器中的登录态。此时正确的工作流是——在本地电脑导出 Cookie 字符串 → 粘贴给 Agent → Agent 执行 agent-reach configure 完成写入。指南按"最快方法优先"组织了两种导出方式：Cookie-Editor 扩展（推荐，每站约 30 秒）和 DevTools 手动复制。

二、方法一：Cookie-Editor 扩展导出（推荐）

Cookie-Editor 是一款浏览器扩展（Chrome、Firefox、Edge 均可用），能把当前站点的 Cookie 一键导出为 "Header String" 格式（即 name1=value1; name2=value2; ...）。操作步骤：

1. 在 Chrome 中安装 Cookie-Editor 扩展；
2. 打开目标网站（例如 x.com），确认已登录；
3. 点击工具栏中的 Cookie-Editor 图标；
4. 点击 Export → Header String；
5. 把导出的字符串粘贴给你的 Agent。

收到字符串后，Agent 会执行对应的配置命令：

agent-reach configure twitter-cookies
agent-reach configure xhs-cookies

需要导出的站点对照表

站点	需访问的 URL	告诉 Agent 的话术
Twitter/X	x.com	"Here are my Twitter cookies: [粘贴]"
小红书	www.xiaohongshu.com	"Here are my XHS cookies: [粘贴]"
Bilibili	www.bilibili.com	"Here are my Bilibili cookies: [粘贴]"

隐藏输入与 --stdin：凭据不进进程参数

原文档强调了一条安全约束：两条 configure 命令都使用隐藏提示输入；在非交互式自动化场景下，应把同样的导出值通过 stdin 传入并附加 --stdin，永远不要把 Cookie 放在进程参数里。

这一设计在 cli.py 中有直接对应——configure 子命令显式定义了 --stdin 参数，帮助文本为 "Read the value from stdin instead of exposing it in process arguments"。其读取逻辑位于 _read_configure_value，实现了三层取值策略：

1. --stdin 模式：从标准输入读取，并强制 1 MiB 安全上限（_MAX_CONFIGURE_VALUE_CHARS = 1024 * 1024，超出即报错退出）；
2. 位置参数模式：对敏感 key 会打印弃用警告——"positional secrets are deprecated because shell history and process listings may expose them; omit the value for a hidden prompt or use --stdin"（shell 历史和进程列表可能泄露凭据）；
3. 隐藏提示模式：交互式终端下使用 getpass.getpass(f"Value for {args.key}: ")，输入不回显。

典型的自动化写法：

printf '%s' "$EXPORTED_COOKIES" | agent-reach configure twitter-cookies --stdin

参数校验逻辑（cli.py）还约束了组合关系：--stdin 不能与 --from-browser 混用，也不能同时提供位置值；--stdin 必须搭配一个 configure key。

三、twitter-cookies 与 xhs-cookies 的落盘格式（源码级解析）

3.1 Twitter：两种输入格式，解析出 auth_token 与 ct0

Twitter 凭据的解析函数是 _parse_twitter_cookie_input，接受两种输入格式：

1. 完整的 Cookie Header String：auth_token=xxx; ct0=yyy; ...——按分号切分后逐个匹配 auth_token= 与 ct0= 前缀；
2. 两个空格分隔的独立值：AUTH_TOKEN CT0（恰好两个 token 且不含 = 时按此解析）。

解析成功后的写入行为（cli.py）：

• config.set("twitter_auth_token", auth_token) 与 config.set("twitter_ct0", ct0)，凭据保存到 ~/.agent-reach/config.yaml；
• 明确打印"凭据未实时验证：不会执行 twitter status"——因为上游工具在验证失败时会自动回退读取浏览器 Cookie，实时验证没有意义；
• 若检测到未安装 twitter-cli，会提示 pipx install twitter-cli，同时提醒：独立的 twitter 命令不读取 Agent Reach 配置，直接使用时需在进程环境中显式设置 TWITTER_AUTH_TOKEN / TWITTER_CT0。

3.2 小红书：JSON 或 Header String，域过滤后导入容器

xhs-cookies 的处理函数是 _configure_xhs_cookies，同样接受两种格式：

1. Cookie-Editor JSON 导出（以 [ 开头的对象数组）：逐条校验 name/value 字段，并通过 domain_matches(cookie.domain, "xiaohongshu.com") 做域过滤——非 xiaohongshu.com 域的 Cookie 会被忽略并计数提示（"已忽略 N 个非 xiaohongshu.com 域 Cookie"）；
2. Header String：key1=val1; key2=val2; ...，解析后统一补全为 {"name", "value", "domain": ".xiaohongshu.com", "path": "/", ...} 结构的 JSON 数组。

解析成功后按环境分两条路径（cli.py）：

• Docker 可用：查找运行中的 xiaohongshu-mcp 容器，读取容器内 COOKIES_PATH 环境变量（缺省回退 /app/cookies.json），通过临时文件 + docker cp 写入容器，随后 docker restart 让容器重新加载 Cookie，并用 mcporter call xiaohongshu.check_login_status() 验证登录状态；
• 无 Docker：以 owner-only 权限写入本地文件 ~/.agent-reach/xhs-cookies.json，并打印手工导入命令 docker cp ~/.agent-reach/xhs-cookies.json xiaohongshu-mcp:/app/data/cookies.json。

3.3 落盘权限：0600 的强制约束

凭据文件不是"随便写个文件"。config.py 在原子写入时通过 os.fchmod(fd, stat.S_IRUSR | stat.S_IWUSR) 将配置文件固定为 0600（仅属主可读写），写入后还会 chmod 复核并拒绝符号链接（_reject_symlink）。tests/test_cookie_extract_perms.py 中的测试进一步验证了这条安全模型："Cookie/Token only stored locally, 600 permissions"——包括对已存在但权限过宽（如 0644）的凭据文件自动收紧到 0600。

四、凭据边界：配置值到底能"做什么"

原文档用了两段专门文字划定边界，这是容易被误解的部分，值得结合源码确认：

Twitter 侧：agent-reach configure twitter-cookies 保存的 Cookie，agent-reach doctor 只用它检查显式凭据是否存在，doctor 不会运行 twitter status 做实时验证。独立的 twitter 命令仍然需要在自己的进程环境中拿到 TWITTER_AUTH_TOKEN 和 TWITTER_CT0。这一点与 setup-twitter.md 的说明一致：配置值"供 agent-reach doctor 检查显式凭据是否齐全。doctor 不会执行 twitter status，不会实时验证账号是否可用，也不会修改当前 Shell"。

小红书侧：这次导出的 Cookie 是给 xiaohongshu-mcp 或存量工具用的。agent-reach configure xhs-cookies 不会把 Cookie 注入 OpenCLI 或 Chrome；OpenCLI 只可能使用用户已存在且明确控制的 Chrome 会话。Agent Reach 从不替用户登录，也从不读取小红书浏览器 Cookie。该边界同样在 setup-xiaohongshu.md 中声明。

可选的 legacy 同步：仅当用户明确同意并显式附加 --sync-legacy-twitter 时（cli.py），Twitter 凭据才会额外复制到两个 legacy 位置——~/.config/xfetch/session.json（cookie_extract.py 中以 authToken/ct0 键合并写入）与 ~/.config/bird/credentials.env（_sync_bird_env，用 shlex.quote 包裹值，防止含引号、$、反引号的 token 在 source 时突破 shell 语法——test_sync_bird_env_quotes_shell_metachars 用恶意 token 验证了这一点）。这两个文件同为 0700 目录 + 0600 文件；agent-reach uninstall 只会提醒这些 legacy 副本，不自动删除。

五、方法二：DevTools 手动导出（无需扩展）

如果没有扩展，可直接用 Chrome 开发者工具：

1. 在 Chrome 中打开目标站点，确认已登录；
2. 按 F12（或右键 → Inspect）打开开发者工具；
3. 切换到 Network 标签页；
4. 刷新页面（F5）；
5. 点击请求列表中的任意一条请求；
6. 在右侧面板滚动到 Request Headers；
7. 找到以 Cookie: 开头的行；
8. 复制 Cookie: 之后的整个值；
9. 粘贴给你的 Agent。

该方法得到的正是 Cookie-Editor "Header String" 的等价物，后续走完全相同的 agent-reach configure ... --stdin 路径。

六、与"本地浏览器自动提取"的关系：为什么 Twitter/XHS 被排除

需要区分两类部署形态。如果你是在本地有浏览器的机器上运行 Agent Reach，部分平台可以跳过手工导出，直接用 --from-browser 自动提取。cookie_extract.py 中的 PLATFORM_SPECS 定义了四个可提取平台：

平台	匹配域	提取的 Cookie
Twitter/X	.x.com、.twitter.com	auth_token、ct0
小红书	.xiaohongshu.com	无（cookies: None，仅支持 Cookie-Editor 手工导出）
Bilibili	.bilibili.com	SESSDATA、bili_jct
雪球	.xueqiu.com	xq_a_token

关键在 _COOKIE_EDITOR_ONLY：

_COOKIE_EDITOR_ONLY = {
    "twitter": "twitter-cookies",
    "xhs": "xhs-cookies",
}

_require_browser_extractable 会在浏览器提取前拦截这两个平台，报错引导改用 agent-reach configure twitter-cookies / xhs-cookies；CLI 层的 manual_keys 校验 也做了同样的双重保险。也就是说：Twitter 与小红书的 Cookie 永远走手工导出通道——这与 cookie-export.md 把这两个站点列为导出对象、而 --from-browser 实际可用的平台为 Bilibili 与雪球，完全对应。示例命令：

# 本地有浏览器时，提取 Bilibili Cookie（写入 bilibili_sessdata / bilibili_csrf）
agent-reach configure --from-browser chrome --platform bilibili

支持 chrome、firefox、edge、brave、opera 五种浏览器；仅 Chrome/Edge/Brave 支持 --profile 指定具体配置档，且 profile 不存在时直接失败而非回退到 Default（见 _profile_cookie_file）。

七、操作清单与注意事项

综合文档与源码，服务器端 Cookie 配置的完整检查清单：

1. 导出：优先 Cookie-Editor → Export → Header String，30 秒一站；无扩展时用 DevTools Network 面板复制 Cookie: 行值；
2. 传递：把字符串交给 Agent，Agent 侧使用 agent-reach configure <key> --stdin（自动化）或隐藏提示（交互），避免把 Cookie 作为进程参数传入；
3. 落盘位置：Twitter → ~/.agent-reach/config.yaml（twitter_auth_token/twitter_ct0）；XHS → 容器内 Cookie 路径或 ~/.agent-reach/xhs-cookies.json；文件权限均为 0600；
4. 能力边界：doctor 只做凭据存在性检查；独立 twitter 命令需自行设置环境变量；xhs-cookies 不注入 OpenCLI/Chrome；
5. Cookie 过期：重新手工导出并再次运行对应 configure 命令即可（setup-xiaohongshu.md 的 FAQ 亦如此说明）。

掌握这套流程后，即使 Agent 与浏览器完全隔离，你也可以以分钟级成本把任一支持平台的登录态安全地"搬运"到服务器，同时保持凭据只在受控的本地文件与容器内流转。