Plannotator 配置完整清单:环境变量与 config.json 选项速查表
Plannotator 配置完整清单:环境变量与 config.json 选项速查表
Plannotator 是一款本地浏览器里的 AI 编码代理审查工具:当 Claude Code、Codex、Gemini CLI、OpenCode 等代理提出计划(plan)或写完代码后,它会自动在浏览器中打开一个可视化界面,让你批注、评论,并一键把反馈送回给代理。要让 Plannotator 贴合自己的工作流,核心就靠两类配置:环境变量和 config.json(默认位于 ~/.plannotator/config.json)。本文整理了一份完整清单速查表,覆盖全部常用 PLANNOTATOR_* 环境变量与 config.json 字段,帮助你快速完成安装与定制。
三种配置方式与优先级规则
Plannotator 的配置入口有三个,同一选项通常"多处可设、按优先级生效":
| 配置方式 | 位置 | 典型场景 |
|---|---|---|
| ⌨️ 命令行参数 | 每次命令后附加,如 plannotator review --no-git-remote-check |
一次性临时覆盖 |
| 🔧 环境变量 | shell 中 export PLANNOTATOR_XXX=... |
全局或某台机器固定生效 |
| 📄 config.json | ~/.plannotator/config.json(可手动编辑) |
持久化个人偏好 |
优先级一般是:命令行参数 > 环境变量 > config.json > 默认值。例如 Jina 的判定顺序就是 --no-jina 标志 → PLANNOTATOR_JINA 环境变量 → config.json 的 jina 字段 → 默认开启,逻辑见 packages/shared/config.ts。
💡 布尔型环境变量的通用约定:
1/true/on表示开启,0/false/off/disabled表示关闭,留空则视为"未设置"。
配置读取与写入的实现都在 packages/shared/config.ts,数据目录的解析逻辑在 packages/shared/data-dir.ts。
核心环境变量速查表(最高频)
下面这张表是日常使用中最常用的核心变量,完整说明可查官方文档 environment-variables.md。
| 变量 | 默认值 | 作用 |
|---|---|---|
PLANNOTATOR_REMOTE |
自动检测 | 强制远程模式(1/true)或本地模式(0/false);SSH 下可自动识别 |
PLANNOTATOR_PORT |
本地随机 / 远程 19432 |
固定服务端口,也支持 19432-19463 这样的端口范围 |
PLANNOTATOR_URL_HOST |
localhost |
仅用于展示的域名(如 Tailscale 主机名),让远程链接可被其他设备访问 |
PLANNOTATOR_BROWSER |
系统默认 | 指定打开 UI 的浏览器,接受应用名、可执行路径或自定义脚本 |
PLANNOTATOR_DATA_DIR |
~/.plannotator |
整个数据根目录(计划、历史、草稿、config.json 等全部在此) |
PLANNOTATOR_AI |
启用 | 设为 disabled 关闭 Ask AI、Review Agents 等 AI 功能 |
PLANNOTATOR_SHARE |
启用 | 设为 disabled 隐藏全部分享入口,适合敏感计划 |
PLANNOTATOR_ALLOWED_HOSTS |
未设置 | 额外允许访问会话的 Host 头,配合反向代理 / Docker 使用 |
PLANNOTATOR_ORGAN — |
— | — |
PLANNOTATOR_ORIGIN |
自动检测 | 显式指定代理来源(claude-code、opencode、gemini-cli 等) |
PLANNOTATOR_PLAN_TIMEOUT_SECONDS |
345600 |
仅 OpenCode:submit_plan 等待超时(秒),0 表示不超时 |
远程模式三件套:PORT + URL_HOST + ALLOWED_HOSTS
当你通过 SSH、devcontainer 或 Docker 使用 Plannotator 时,推荐组合配置:
export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=19432
export PLANNOTATOR_URL_HOST=your-machine.tailnet.ts.net
端口解析顺序为:① PLANNOTATOR_PORT → ② 远程模式的 19432 → ③ 本地模式的随机端口(remote.md)。指定端口范围时会从低到高逐个尝试,绑定第一个可用端口。
Claude Code 与代理工具相关变量
如果你主要使用 Claude Code / Pi / OpenCode 2,这四个变量决定代理能"看到"哪些工具:
| 变量 | 默认值 | 说明 |
|---|---|---|
PLANNOTATOR_CLAUDE_MOD |
开 | Claude Code 2.1.287+ 的非阻塞 mod(不等 Claude 等待的审查体验);设 0 回退经典 hook |
PLANNOTATOR_AGENT_TOOL |
Claude Code 开 / Pi、OpenCode 2 关 | 是否给代理注册 plannotator 工具,让它主动打开 Plannotator |
PLANNOTATOR_INBOX_TOOL |
同上 | 控制 Inbox 的 plannotator_inbox 工具与回复唤醒 |
PLANNOTATOR_MOD_DEBUG |
关 | 设 1 后 mod 会写调试日志到 ~/.plannotator/claude-code-mod/debug.log,报障时很有用 |
⚠️ 注意:AGENT_TOOL 与 INBOX_TOOL 只在会话启动时读取,修改后需要重启代理或新开会话才生效。两者也都支持 config.json("agentTool": false、"inboxTool": { "pi": true })。
高级功能开关与沙箱变量
| 变量 | 默认值 | 作用 |
|---|---|---|
PLANNOTATOR_GIT_REMOTE_CHECK |
启用 | 关闭后本地 Git 审查不再执行 git ls-remote,适合 SSH 依赖硬件安全密钥的场景 |
PLANNOTATOR_CURSOR_SANDBOX |
启用 | 关闭 Cursor Agent 的强制沙箱参数(NixOS 等系统需要) |
PLANNOTATOR_CLAUDE_SANDBOX |
启用 | 为审查任务单独关闭 Claude Code 沙箱(缺少 bubblewrap 的 Linux 需要) |
PLANNOTATOR_JINA |
启用 | URL 批注是否走 Jina Reader;可配合 JINA_API_KEY 提升速率限制 |
PLANNOTATOR_GLIMPSE / _WIDTH / _HEIGHT |
启用 / 1280 / 900 |
Glimpse 原生窗口开关与尺寸 |
PLANNOTATOR_FEEDBACK_HISTORY |
启用 | 关闭后不再把提交记录归档到 ~/.plannotator/feedback/ |
PLANNOTATOR_ANNOTATE_HISTORY |
启用 | 关闭后 annotate 会话完全无状态 |
PLANNOTATOR_REVIEW_PROGRESS |
启用 | 关闭后"已查看"标记不再跨会话记忆 |
PLANNOTATOR_AUTO_UPDATE |
关 | 允许二进制每天最多一次后台检查更新 |
PLANNOTATOR_TODO_PROVIDER |
auto |
Pi 专属:是否把批准的计划清单镜像到 pi-todos |
PLANNOTATOR_READY_FILE / PLANNOTATOR_SKIP_BROWSER_OPEN |
— | 宿主插件内部使用的旁路信号,一般无需手动设置 |
自建服务与 Bitbucket 相关变量
自托管分享门户、paste 服务或对接 Bitbucket PR 审查时使用:
| 变量 | 默认值 | 说明 |
|---|---|---|
PLANNOTATOR_SHARE_URL |
https://share.plannotator.ai |
分享链接的根地址(自托管分享门户时修改) |
PLANNOTATOR_GUIDE_SHARE_URL |
https://guides.show |
Guided Review 分享链接上传的主机 |
PLANNOTATOR_GUIDE_VIEWER_URL |
https://guides.show/v1/ |
已下载的可移植 guide 所固定的查看器地址 |
PLANNOTATOR_PASTE_URL |
https://plannotator-paste.plannotator.workers.dev |
paste 服务 API 地址 |
PASTE_PORT / PASTE_DATA_DIR / PASTE_TTL_DAYS / PASTE_MAX_SIZE / PASTE_ALLOWED_ORIGINS |
19433 / ~/.plannotator/pastes / 7 / 5MB / 见文档 |
自托管 paste 服务自身的运行参数 |
PLANNOTATOR_BITBUCKET_TOKEN |
未设置 | Atlassian API token(需 4 个 bitbucket 权限范围);也可写进 config.json 的 bitbucketToken(明文,不推荐) |
PLANNOTATOR_BITBUCKET_EMAIL |
未设置 | 提供 token 的账号邮箱;不提供则按 Bearer 方式发送 |
PLANNOTATOR_BITBUCKET_API_URL |
https://api.bitbucket.org/2.0 |
API 基址,用于本地假 API 测试或企业代理 |
安装脚本专用变量
以下变量只被安装脚本读取(scripts/install.sh、scripts/install.ps1、scripts/install.cmd),运行时不生效:
| 变量 | 作用 |
|---|---|
PLANNOTATOR_VERIFY_ATTESTATION |
安装时用 gh attestation verify 校验二进制来源(需装 gh CLI) |
PLANNOTATOR_MINIMAL |
只装 plannotator 二进制,跳过 skills、hooks、slash 命令等一切附加物 |
PLANNOTATOR_SKIP_SEM_INSTALL |
跳过可选的 sem 语义 diff sidecar |
PLANNOTATOR_INSTALL_CALLDIFF |
预装 CallDiff(调用流分析)核心运行时 |
PLANNOTATOR_CALLDIFF_PATH |
开发用:指向本地已构建的 CallDiff |
PLANNOTATOR_SKIP_CODEX_INSTALL / _GEMINI_ / _KIRO_ / _VIBE_ / _OPENCODE_ |
分别跳过对应代理的集成写入(对应 config.json 的 skipInstall 字段) |
PLANNOTATOR_SKIP_SKILLS_INSTALL |
跳过全部 skills / slash 命令检出,此时不再强依赖 git |
CLAUDE_CONFIG_DIR |
自定义 Claude Code 配置目录,hook 将写入此处 |
config.json 完整字段速查表
手动编辑 ~/.plannotator/config.json 时的全部可选字段(类型定义见 packages/shared/config.ts 中的 PlannotatorConfig 接口):
| 字段 | 默认 | 说明 |
|---|---|---|
displayName |
— | 自定义显示名(批注署名,默认为自动生成的 形容词-名词-tater) |
diffOptions |
— | diff 外观:diffStyle、overflow、lineDiffType、showLineNumbers、fontSize、defaultDiffType 等,类型定义见 packages/core/config-types.ts |
reviewAnalysis |
语义开 / 调用流关 | semanticDiff、callFlow 两个审查分析层 |
theme |
— | 主题:mode(light/dark/system)+ 明暗两套调色板 |
favicon |
totman |
totman 或 classic 两种图标风格 |
prompts |
内置模板 | 自定义发给代理的批准 / 拒绝 / 批注反馈文案,支持按 runtime 覆盖 |
conventionalComments / conventionalLabels |
— | 是否启用及自定义"约定式评论标签"(如 blocking 标签) |
agentTerminalSide |
left |
annotate 模式代理终端停靠侧:left / right / hidden |
agentTerminalDefaultAgent |
第一个可用 | annotate 终端预选的代理 id |
jina |
true |
URL 批注走 Jina Reader |
annotateHistory |
true |
保存 annotate 版本历史(版本 diff 的来源) |
feedbackHistory |
true |
归档提交的审查记录到 feedback/ |
guideHistory |
true |
持久化成功的 Guided Review 到 guides/ |
markdownExtensions |
空 | 让 annotate 把额外扩展名(如 .livemd)当 markdown 处理 |
reviewProgress |
true |
跨会话记忆"已查看"文件 |
autoUpdate |
false |
后台自动更新开关 |
claudeCodeMod |
true |
Claude Code mod 总开关 |
agentTool / inboxTool |
按宿主 | 代理工具 / Inbox 工具开关,inboxTool 支持按宿主分别配置 |
inboxNotifications |
— | Inbox 浏览器通知的 enabled / dismissed / allowedOrigin |
inboxPhones |
false |
手机端 Inbox 开关(面向 iPhone 应用开发) |
pfmReminder |
false |
每次 EnterPlanMode 注入 PFM 扩展提醒 |
glimpse |
true |
Glimpse 原生窗口开关 |
share |
enabled |
"disabled" 可关闭全部分享 UI |
guideShareUrl |
— | 自托管 guide 主机地址 |
bitbucketToken / bitbucketEmail |
— | Bitbucket 凭据(token 为明文,优先用环境变量) |
cursorSandbox / claudeSandbox |
true |
审查任务的沙箱策略 |
gitRemoteCheck |
true |
审查时是否查询 git 远程 |
urlHost |
— | 同 PLANNOTATOR_URL_HOST 的持久化版本 |
todoProvider |
auto |
auto / off |
skipInstall |
全关 | { "codex": true, "gemini": true, ... } 安装跳过清单 |
verifyAttestation |
false |
安装时校验二进制 attestation |
一个最小示例:
{
"claudeCodeMod": false,
"share": "disabled",
"autoUpdate": true,
"diffOptions": { "diffStyle": "split", "showLineNumbers": true },
"theme": { "mode": "system" }
}
快速上手:3 条最常用的配置
1️⃣ SSH 远程开发:export PLANNOTATOR_REMOTE=1 + 端口转发,链接自动变为固定端口。
2️⃣ 敏感项目禁用分享:export PLANNOTATOR_SHARE=disabled(或 config.json 写 "share": "disabled"),Share 标签页、复制链接、导入审查全部隐藏。
3️⃣ 彻底无状态审查:同时设置 PLANNOTATOR_ANNOTATE_HISTORY=0 与 PLANNOTATOR_FEEDBACK_HISTORY=0,Plannotator 不再向磁盘写入任何历史记录。
常见疑问 FAQ
Q1:改了 config.json 要重启吗?
大多数字段(主题、diff 选项、沙箱开关等)在下一个会话启动时生效;agentTool、inboxTool 类字段只在会话开始读取一次,改完请新开会话或重启代理。
Q2:环境变量和 config.json 冲突听谁的?
环境变量优先。例外是 CLI 参数(如 --no-git-remote-check、--browser),它们永远赢。
Q3:数据目录可以搬走吗?
可以,设置 PLANNOTATOR_DATA_DIR=/some/path 即可整体迁移(含 config.json);未设置时已存在的 ~/.plannotator 永远优先于 XDG_DATA_HOME。
Q4:完整文档在哪看? 环境变量全表:environment-variables.md;配置总览:configuration.md;界面内设置说明:ui-settings.md;代码实现:packages/shared/config.ts。
掌握这份速查表后,你可以在一分钟之内把 Plannotator 配置成最贴合自己团队的工作模式——剩下的,就交给代理们慢慢改吧 🚀



