Google Keep CLI 技能

使用非官方库 gkeepapi，通过命令行管理 Google Keep 笔记与列表。

安装配置

安装完成后，CLI 可执行文件位于技能目录（skill directory）中。建议设置便捷别名或封装脚本：

SKILL_DIR=""  # 例如：skills/google-keep
alias gkeep="$SKILL_DIR/.venv/bin/python3 $SKILL_DIR/gkeep.py"

或创建全局封装脚本：

cat > ~/.local/bin/gkeep << 'EOF'
#!/bin/bash
SKILL_DIR="$(dirname "$(readlink -f "$0")")/../.openclaw/workspace/skills/google-keep"
exec "$SKILL_DIR/.venv/bin/python3" "$SKILL_DIR/gkeep.py" "$@"
EOF
chmod +x ~/.local/bin/gkeep

身份验证

首次配置（OAuth Token 交换）：

1. 在浏览器中访问 https://accounts.google.com/EmbeddedSetup
2. 使用您的 Google 账户登录
3. 在授权页面点击 “I agree”（页面可能持续加载 — 可忽略）
4. 打开开发者工具（F12 → Application 标签页 → Cookies → accounts.google.com）
5. 复制 oauth_token Cookie 的值
6. 运行以下命令：

gkeep auth  

使用已获取的主令牌（Master Token）：

gkeep auth-master  

凭证将保存在 /.config/ 目录下（权限设为 600）。主令牌拥有对应 Google 账户的**完全访问权限**，应视同密码妥善保管。该令牌**永不过期**（不同于标准 OAuth 刷新令牌）。

命令说明

列出笔记

gkeep list                    # 活动中的笔记（默认）
gkeep list --archived         # 包含已归档笔记
gkeep list --pinned           # 仅显示置顶笔记
gkeep list --label "Shopping" # 按标签筛选
gkeep list --json             # 输出 JSON 格式
gkeep list -v                 # 显示笔记 ID

搜索

gkeep search "grocery"
gkeep search "todo" --json

获取指定笔记

gkeep get 
gkeep get "Shopping List"     # 按标题匹配（不区分大小写）
gkeep get  --json

创建笔记

gkeep create --title "Ideas" --text "Some thoughts"
gkeep create --title "Groceries" --list --items "Milk" "Eggs" "Bread"
gkeep create --title "Important" --pin --color Red --label "Work"

编辑笔记

gkeep edit  --title "New Title"
gkeep edit  --text "Updated text"
gkeep edit  --pin true
gkeep edit  --archive true
gkeep edit  --color Blue

列表操作（待办清单项）

gkeep check "Groceries" "milk"           # 勾选某一项
gkeep check "Groceries" "milk" --uncheck # 取消勾选
gkeep check "Groceries" "m" --all        # 勾选所有匹配项
gkeep add-item "Groceries" "Butter" "Cheese"  # 添加清单项

删除（移入回收站）

gkeep delete 

标签管理

gkeep labels              # 列出全部标签
gkeep labels --json

导出 / 备份

gkeep dump                # 导出全部笔记为 JSON
gkeep dump > backup.json

颜色支持

有效颜色值：White、Red、Orange、Yellow、Green、Teal、Blue、DarkBlue、Purple、Pink、Brown、Gray

工作原理

• 基于 gkeepapi（GitHub 超过 1600 颗星，持续维护）—— 一款非官方的、逆向工程实现的 Google Keep 客户端
• 认证流程使用 gpsoauth，通过 Google Play Services OAuth 流程获取主令牌（master token）
• 状态信息本地缓存于 .config/state.json，首次同步后可实现快速启动
• 主令牌永不过期，因此无需重复认证
• 非官方 API — Google 可能在任何时间更改接口导致兼容性中断（但 gkeepapi 已稳定运行多年）

安全须知

• 主令牌授予对关联 Google 账户的完全访问权限
• 凭证以 600 权限存储于 .config/ 目录下
• 切勿将 .config/ 目录提交至版本控制系统
• delete 命令仅将笔记移入回收站（可恢复），不会永久删除