PinchTab 环境变量权威指南：PINCHTAB_TOKEN、PINCHTAB_CONFIG 与 PINCHTAB_SESSION 的完整解读

PinchTab 环境变量权威指南PINCHTAB_TOKEN、PINCHTAB_CONFIG 与 PINCHTAB_SESSION 的完整解读【免费下载链接】pinchtabHigh-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.项目地址: https://gitcode.com/gh_mirrors/pi/pinchtabPinchTab 是一个高性能浏览器自动化桥接与多实例编排工具其 Agent 工作流中的绝大多数运行行为应当通过config.json与pinchtab config命令配置而非环境变量。本文以仓库内 Agent 技能参考文档 为骨架结合cmd/、internal/cli/、internal/httpx/等目录的源码与测试实现完整讲解PINCHTAB_TOKEN、PINCHTAB_CONFIG、PINCHTAB_SESSION、PINCHTAB_AGENT_ID四个变量的语义、认证链路与推荐用法帮助你安全地让 CLI 与 MCP 客户端访问本地或远程受保护的 PinchTab 服务器。设计原则为什么这份参考刻意收窄原文档开篇就明确声明This reference is intentionally narrow.这份参考是刻意收窄的。这是 PinchTab 环境变量设计的第一原则对于 Agent 工作流绝大多数运行时行为都应通过config.json或pinchtab config命令配置而不是临时拼凑环境变量。这一原则在源码中同样有迹可循。CLI 的全局配置集中在cmd/pinchtab/root.go持久化标志只有两个--server服务器地址与--agent-id活动日志中的 Agent 标识其余浏览器调优、超时、代理等全部落在配置文件层。从源码结构可以推断环境变量在 PinchTab 中承担的是认证与寻址这一小而关键的职责而非通用的配置兜底通道。把浏览器参数写进环境变量不仅难以审计还会与配置文件产生隐式优先级冲突。Agent 相关的核心变量一览原文档给出了两个 Agent 直接相关的核心变量整理如下并补充取值说明变量典型用途说明PINCHTAB_TOKEN向受保护的服务器认证 CLI 或 MCP 请求以Authorization: Bearer token发送缺少时 CLI 会回退到本地配置中的server.tokenPINCHTAB_CONFIG覆盖配置文件路径自动化场景下应优先于零散的环境变量覆盖使用保证配置来源单一、可复现除表格外还有两个与当前标签页作用域相关的变量在原文档的推荐用法一节中给出变量典型用途说明PINCHTAB_SESSION以 Agent 会话身份调用按会话隔离当前标签页设置后 CLI 改用Authorization: Session token认证可独立吊销PINCHTAB_AGENT_ID无会话时按 Agent ID 隔离当前标签页与--agent-id标志等价二者择一即可PINCHTAB_TOKENCLI 与 MCP 请求的 Bearer 认证PINCHTAB_TOKEN是 PinchTab 认证体系中的核心凭据用于向受保护的服务器认证 CLI 或 MCP 请求。其发送方式在 internal/cli/apiclient/transport.go 中有明确实现func setClientHeaders(req *http.Request, token string) { req.Header.Set(X-PinchTab-Source, client) if token { return } if strings.HasPrefix(token, ses_) { req.Header.Set(Authorization, Session token) } else { req.Header.Set(Authorization, Bearer token) } }可见普通 token 以Bearer方案发送而以ses_开头的会话令牌则自动切换为Session方案。此外客户端还会附加X-PinchTab-Source: client头便于服务端识别请求来源。在配置加载侧cmd/pinchtab/config_load.go 的ensureMandatoryToken展示了凭据的优先级func ensureMandatoryToken() error { if strings.TrimSpace(os.Getenv(PINCHTAB_TOKEN)) ! { return nil } fc, configPath, err : config.LoadFileConfig() ... }即环境变量PINCHTAB_TOKEN优先于配置文件中的 token环境变量为空时才回退读取配置文件。这与原文档without one, the CLI falls back toPINCHTAB_TOKENor the local configsserver.token的描述相互印证——也就是说当你连本地服务器时即使不设环境变量CLI 也会自动携带本地配置server.token。定位远程服务器--server 与对端凭据的配对当 CLI 需要访问远程 PinchTab 服务器时请使用--serverCLI 标志而不是环境变量并且必须同时携带该主机自己的凭据PINCHTAB_TOKENthat-host-token pinchtab --server http://192.168.1.50:9867 snap PINCHTAB_TOKENthat-host-token pinchtab --server https://pinchtab.com snap--server标志定义于 cmd/pinchtab/root.go注释明确其默认值为http://127.0.0.1:server.port即不指定时直连本机。当你把它指向远程主机时必须把PINCHTAB_TOKEN换成那台主机的 token——否则 CLI 会默默地把本机的PINCHTAB_TOKEN或本地配置的server.token发给远程主机对方将拒绝该凭据并返回bad_token错误。这一点在 internal/httpx/unauthorized.go 的服务端提示语中被原样复述this host rejected the token; when targeting a remote server with --server, the token must belong to that host — otherwise the CLI sends PINCHTAB_TOKEN or the local configs server.token为什么刻意不提供 --token 标志原文档特别强调There is deliberately no--tokenflag.刻意不提供--token标志。原因非常实在进程列表可见性命令行参数会出现在进程列表中宿主机上的任何用户都能看到Shell 历史残留token 写入 shell history 后难以彻底清除形成长期泄露面。因此环境变量形式是唯一受支持的凭据传递方式。这与通用安全实践一致凭据应通过环境或密钥管理注入进程而不是出现在 argv 中。从 root.go 的持久标志列表只有--server与--agent-id也可以确认源码层面确实没有为 token 预留标志位。401 错误码语义missing_token 与 bad_token当认证失败时服务端会返回两类带编码的 401定义于 internal/httpx/unauthorized.goconst ( CodeMissingToken missing_token CodeBadToken bad_token )missing_token客户端根本没发送凭据。提示语会引导你设置PINCHTAB_TOKENbad_token客户端发送了凭据但被对端拒绝提示语会引导你检查--server指向的主机与其凭据是否配对。更贴心的是CLI 的错误渲染层 internal/cli/apiclient/apierror.go 还会记录并输出被拒凭据的来源func rejectedTokenProvenance(statusCode int, code string) string { if statusCode ! http.StatusUnauthorized || code ! bad_token || tokenSource { return } return fmt.Sprintf(the rejected token came from %s, tokenSource) }这条the rejected token came from ...信息直接指出错误根源——常见场景就是CLI 把本机的 token 发给了--server指向的远程主机。对应测试 internal/cli/apiclient/apierror_test.go 验证了missing_token场景不输出came from因为根本没发凭据而bad_token场景必须点名来源。另外如果你误把会话令牌ses_...当 Bearer 发送服务端会额外提示that looks like an agent session token; send it as Authorization: Session , not Bearer帮助你快速修正认证方案。PINCHTAB_CONFIG覆盖配置文件路径PINCHTAB_CONFIG用于覆盖配置文件路径是自动化场景下的首选配置注入方式。相比零散的环境变量覆盖它让整套配置浏览器、实例、网络、认证等来自单一、明确、可版本管理的文件。在测试代码中可以看到它的典型用法例如 internal/config/browsers_config_test.goif err : os.WriteFile(cfgPath, data, 0o644); err ! nil { t.Fatal(err) } t.Setenv(PINCHTAB_CONFIG, cfgPath) cfg : Load() if cfg.DefaultBrowser ! chrome { ... }即设置PINCHTAB_CONFIG后config.Load()便会从指定路径读取配置。对 Agent 工作流而言这意味着你可以为每个任务准备独立的配置文件不同浏览器目标、不同实例编排、不同超时策略并在启动 CLI 时通过一个环境变量切换整套行为而无需依赖 Shell 环境里的碎片化设置。关于配置文件的完整参数说明可参考 docs/reference/config.md。当前标签页的作用域匿名本地状态 vs 会话/Agent 服务端状态原文档的Recommended default一节揭示了一个重要的运行时语义当前标签页current tab状态的作用域取决于调用者是否被识别。匿名 CLI 调用在共享的本地状态文件中记住当前标签页XDG_STATE_HOME下的状态文件相关测试可见 cmd/pinchtab/cmd_cli_current_tab_test.go。这意味着在一个多步流程中先执行一次pinchtab nav URL后续的无作用域命令会自动复用该标签页。被识别的调用者改用服务端的当前标签页状态。Agent 会话PINCHTAB_SESSION按会话隔离当前标签页当不存在会话时--agent-id标志或PINCHTAB_AGENT_ID环境变量按Agent ID隔离。--tab id仅在需要显式指定某个特定标签页时才使用。CLI 端对调用者是否被识别的判断实现在 internal/cli/actions/actions_navigate.gofunc isIdentifiedCaller(cmd *cobra.Command) bool { return strings.TrimSpace(os.Getenv(PINCHTAB_SESSION)) ! || strings.TrimSpace(os.Getenv(PINCHTAB_AGENT_ID)) ! || agentIDFlag(cmd) ! }对应的导航测试internal/cli/actions/actions_navigate_test.go验证了设置了PINCHTAB_SESSION的调用者被视为 identified不会打印未建会话的提示——因为其多步流程天然复用会话的当前标签页不会意外新建第二个标签页。实践建议同一标签页上的多步流程请先pinchtab nav URL一次再使用无作用域命令只有当你明确要操作某个具体标签页时才追加--tab id。这能避免匿名回退fallback时服务器为同一个 URL 打开第二个标签页的问题。PINCHTAB_SESSION按 Agent 会话隔离与可独立吊销对于需要每 Agent 身份隔离与可吊销性的场景推荐使用 Agent 会话PINCHTAB_SESSIONses_...当PINCHTAB_SESSION被设置时CLI 改用Authorization: Session token而非 Bearer 认证见前文 transport.go 的实现。会话在服务端映射到特定的 agentId并可以被独立吊销——这意味着多个 Agent 可以共享一个服务器 token但各自的会话互不干扰当前标签页、活动日志按会话隔离某个 Agent 不再被信任时只需吊销其会话而无需更换整个服务器的 token会话与--agent-id/PINCHTAB_AGENT_ID配合时会话优先isIdentifiedCaller中PINCHTAB_SESSION是第一个判断条件。若想深入了解会话的管理方式创建、校验、吊销可查阅 internal/session 目录及 docs/reference/sessions.md。刻意不列入的内容原文档明确说明了两类故意不在本参考中列出的内容理解它们有助于避免误用浏览器调优不应进入临时环境变量浏览器参数隐身配置、UA、代理、实例数量等应统一存放在config.json中。环境变量只负责认证与寻址浏览器行为归配置管理职责边界清晰。内部进程接线与继承的环境透传属于实现细节进程间如何传递环境、内部子进程继承了什么变量都不属于 skill contract技能契约的一部分不应在 Agent 工作流中依赖这些行为——它们随时可能随实现变更。此外远程寻址请始终使用--server标志配合对端凭据其余一切配置、Profile、实例、服务器地址都应通过 config、profiles、instances 与--server标志来管理。推荐默认Agent 场景的最小变量集综合原文档与源码实现对大多数 Agent 任务而言你唯一真正需要的变量是PINCHTAB_TOKEN...其余按需叠加访问远程服务器PINCHTAB_TOKENthat-host-token pinchtab --server url ...注意 token 必须属于目标主机每 Agent 身份隔离、可吊销PINCHTAB_SESSIONses_...多 Agent 共享服务器且无会话--agent-id id或PINCHTAB_AGENT_IDid切换整套配置PINCHTAB_CONFIG/path/to/config.json。多步流程在同标签页上执行时先pinchtab nav URL后续使用无作用域命令即可显式定位标签页时才用--tab id。浏览器参数、实例编排、网络路由等一律走配置层——这也是 PinchTab 对 Agent 工作流给出的最终建议环境变量越少行为越可预测越容易被审计与复现。【免费下载链接】pinchtabHigh-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.项目地址: https://gitcode.com/gh_mirrors/pi/pinchtab创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考