企业官网建设流程全解析

如何安装 Paperclip CLI、配置 PAPERCLIP_API_KEY 并验证凭据有效

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

这篇文章解决一个具体问题：在 macOS 或 Linux 上安装 Paperclip CLI（GXL 提供的科研文献检索命令行工具），通过PAPERCLIP_API_KEY环境变量完成认证，并用一条真实查询证明凭据有效。Paperclip 把约 1100 万篇全文论文、21.7 万份监管文档、11 万份临床试验方案和 57.4 万条蛋白质条目暴露为只读虚拟文件系统（/papers、/fda、/trials、/proteins、/clipboard），用 Unix 风格命令浏览。适用前提是文档在 paperclip 0.7.14 和 0.7.15 上验证过的环境：macOS 或 Linux、POSIX shell、可访问网络。原生安装器不支持 Windows，Windows 用户需改用托管 MCP server（见 安装参考文档）。

先做 preflight：确认是否已安装

在动手安装之前，先运行 SKILL.md 给出的 preflight 检查，它一次性回答"是否已安装"和"当前凭据是什么"：

command -v paperclip >/dev/null || echo "paperclip NOT INSTALLED" command -v paperclip >/dev/null && { paperclip --version; [ -f .env ] && { set -a; . ./.env; set +a; }; paperclip config 2>&1 | grep -E "Auth|Health"; }

输出决定后续走向：paperclip NOT INSTALLED表示没有二进制，继续下面的安装步骤；Auth:行是后续一切判断的依据（各取值含义见验证章节）。

安装 Paperclip CLI

一行安装脚本（推荐，macOS 和 Linux）

curl -fsSL https://paperclip.gxl.ai/install.sh | bash

这条命令会用当前用户权限执行从网络拉取的脚本，文档明确说明没有已发布的 checksum 或签名可供校验。运行前建议先获得使用者确认，如果希望先审查脚本内容，文档给出了审查方式：

curl -fsSL https://paperclip.gxl.ai/install.sh | less

安装完成后，CLI 是 self-contained 的：本体放在~/.paperclip/（自带解释器和依赖，位于~/.paperclip/lib/），并在PATH上放一个启动器（macOS 上是~/.local/bin/paperclip）。它不会干扰项目里已有的 Python 虚拟环境。

如果安装后提示command not found: paperclip，说明~/.local/bin不在PATH中：

export PATH="$HOME/.local/bin:$PATH" # 加入 ~/.zshrc 或 ~/.bashrc 可持久化

可选：用 uv 安装

如果你想把包装进自己管理的环境（例如要在自己的代码中 import Python SDK）：

uv pip install https://paperclip.gxl.ai/paperclip.whl paperclip setup # = paperclip login + paperclip install

两个注意事项（均来自 references/installation.md）：wheel URL 不带版本号，每次解析到的都是当前版本，且gxl-paperclip没有发布到 PyPI；PyPI 上确实存在一个无关的paperclip包，uv pip install paperclip会装到错误的软件，必须始终用完整 URL 安装。

安装后注意：CLI 会自行择机升级，命令输出前可能打印[paperclip] Updated 0.7.14 → v0.7.15。无害，但长脚本运行期间版本可能变化；paperclip --version显示的是实际执行的版本。

配置 PAPERCLIP_API_KEY

创建 key 并写入.env

在https://paperclip.gxl.ai/keys创建 API key（形如gxl_...），然后在项目目录的.env中写入：

# .env — add to .gitignore PAPERCLIP_API_KEY=gxl_...

其中gxl_...替换为你在/keys页面创建的实际 key 值。.env必须加入.gitignore，不要把 key 提交进仓库，也不要把它写进将来要paperclip upload的文件。

为什么每次调用都要带 auth 前缀

这是整套流程里最容易出错的环节。references/installation.md 明确说明：Paperclip 没有 dotenv 支持，包内没有python-dotenv依赖，config.py只读os.getenv("PAPERCLIP_API_KEY", "")。放在命令旁边的.env文件对它是不可见的，必须先把内容导出到环境变量。

在持有.env的目录中，对每次调用使用文档要求的这种形式：

[ -f .env ] && { set -a; . ./.env; set +a; }; paperclip config

set -a让后续的赋值自动导出，.把文件读进当前 shell，set +a恢复原状。两个细节不是风格问题：

1. [ -f .env ]保护是必须的。不带保护地对一个不存在的文件执行. ./.env在 POSIX shell 中是致命错误——shell 直接终止，分号后面的内容全部被静默丢弃。带保护后，在.env存在、.env不存在、key 已在环境中、sh或bash四种状态下都安全。
2. 每一条调用都要带前缀。环境变量不会在两次独立的 shell 调用之间保留（这正是 agent 逐条执行命令的方式）。在第一次调用里导出 key、第二次调用再运行paperclip，key 已经消失，而且 Paperclip 不会报错：它会静默回退到已存储的 OAuth 凭据，那是另一个身份。文档演示的错误写法是Auth: ✓ someone@example.com（key 从未加载），正确写法是单条自包含命令得到Auth: ✓ API key (env)。

如果 key 已经通过 CI secrets、shell profile 或direnv导出，前缀是无害的空操作，可以省略。临时使用也可以直接：

export PAPERCLIP_API_KEY='gxl_...' # 仅当前 shell 有效

另有一个注意点：sourcing.env会把文件内容当作 shell 代码执行（docs/security-report.md 将其列为风险项），所以只在你明确信任该目录下的.env时使用这个前缀。

凭据解析顺序

文档针对 0.7.14 的cli/app.py和client/client.py验证过三级解析顺序：

环境变量中的 key 会完全短路 OAuth：_ensure_auth()直接返回，不会打开浏览器，即使存在已存储的登录也不读取。也就是说，导出的 key 会静默覆盖你曾登录的账号，paperclip config显示Auth: ✓ API key (env)而不是邮箱。

如果拿不到 key，备选路径是浏览器 OAuth：由人执行paperclip login（会打开浏览器并等待，agent 无法完成），凭据写入~/.paperclip/credentials.json。注意首次使用时未认证的调用会自动触发登录流程——在 CI 等无交互场景里，务必在第一次调用前把 key 配好。

验证凭据是否有效

分两步。第一步看安装和认证状态：

paperclip config

key 已导出且安装健康时，文档示例输出如下（文档示例，路径以你的系统为准）：

Paperclip Server: https://paperclip.gxl.ai (default) Auth: ✓ API key (env) Config: /Users/you/.paperclip Health: ✓ server reachable Sources: PubMed Central, bioRxiv, medRxiv, arXiv

OAuth 登录时Auth行显示的是你的邮箱。各取值对应 SKILL.md 中的 preflight 判断表：

关键限制：Auth: ✓只表示凭据存在，不代表它有效；Health: ✓ server reachable是一个未认证探针。一个无效的 key 会打印完全相同的两行。真正证明凭据有效需要一次真实查询：

[ -f .env ] && { set -a; . ./.env; set +a; }; paperclip search -s pmc "test" -n 1

成功时得到带编号的检索结果，结尾是一个[s_xxxxxxxx]形式的结果 id。key 无效时输出：

[error] Authentication failed (API key invalid).

并以退出码1结束——这是脚本里可判断的信号，文档建议以退出码为检查依据。

安装与认证阶段的常见问题

以下是 references/installation.md 故障排查表中与本场景直接相关的条目：

两条边界说明：CLI 会在命令中途自行更新，长会话中版本可能变化，paperclip update可显式升级并刷新已安装的 agent skills；通过 HTTP 传输时 key 走X-API-Key头，不要回显它，也不要把它包含进上传文件中。

下一步

凭据验证通过后，完整的命令面、MCP 客户端配置（Claude Code、Codex、Cursor、Claude Desktop 等）和更多安装细节在 references/installation.md；文献检索工作流（search/grep/map/sql、引用格式、已知缺陷清单）在 skills/paperclip/SKILL.md，其下还有references/cli-reference.md、references/search-and-retrieval.md等分册。

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills