知己

安全接收人类的秘密——无聊天暴露，无复制粘贴，无历史泄露。

🚨 关键流程 — 请先阅读此处

这是一个人机交互流程。您无法自行获取秘密。

1. 运行脚本→ 您将获得一个安全URL
2. 在聊天中向用户发送此URL← 这是强制步骤
3. 等待用户在浏览器中打开URL并提交秘密
4. 脚本处理后续步骤（接收、保存到磁盘、确认）

❌ DO NOT curl/fetch the secret URL yourself — it's a web form for humans
❌ DO NOT skip sharing the URL — the user MUST receive it in chat
❌ DO NOT poll the API to check if the secret arrived — the script does this
❌ DO NOT proceed without confirming the secret was received
✅ Share URL → Wait → Confirm success → Use the secret silently

🔧 设置（每个环境仅需一次）

运行以下命令一次以全局安装CLI（避免缓慢的npx调用）：

bash {skill}/scripts/setup.sh

{skill}是包含此SKILL.md文件的目录的绝对路径。代理可以在运行时解析它。

SKILL_DIR=$(find "$HOME" -name "SKILL.md" -path "*/confidant/skill*" -exec dirname {} \; 2>/dev/null | head -1)
# Then use: bash "$SKILL_DIR/scripts/setup.sh"

⚡ 快速开始

你需要用户提供API密钥？一条命令搞定：

bash {skill}/scripts/request-secret.sh --label "OpenAI API Key" --service openai

脚本会处理所有事情：

• ✅ 如果服务器未运行则启动（或复用现有服务器）
• ✅ 通过网页表单创建安全请求
• ✅ 检测现有隧道（ngrok或localtunnel）
• ✅ 返回可供用户分享的URL
• ✅ 轮询直到密钥被提交
• ✅ 保存至~/.config/openai/api_key（设置权限为chmod 600）并退出

如果用户是远程的（不在同一网络），请添加--tunnel参数：

bash {skill}/scripts/request-secret.sh --label "OpenAI API Key" --service openai --tunnel

这会自动启动一个localtunnel（无需账户）并返回一个公共URL。

输出示例：

🔐 Secure link created!

URL: https://gentle-pig-42.loca.lt/requests/abc123
  (tunnel: localtunnel | local: http://localhost:3000/requests/abc123)
Save to: ~/.config/openai/api_key

Share the URL above with the user. Secret expires after submission or 24h.

分享URL → 用户打开 → 提交密钥 → 脚本保存至磁盘 → 完成。

如果没有--服务或--保存，脚本仍会轮询并将密钥打印到标准输出（适用于管道传输或手动检查）。

脚本

request-secret.sh— 请求、接收并保存密钥（推荐）

# Save to ~/.config/<service>/api_key (convention)
bash {skill}/scripts/request-secret.sh --label "SerpAPI Key" --service serpapi

# Save to explicit path
bash {skill}/scripts/request-secret.sh --label "Token" --save ~/.credentials/token.txt

# Save + set env var
bash {skill}/scripts/request-secret.sh --label "API Key" --service openai --env OPENAI_API_KEY

# Just receive (no auto-save)
bash {skill}/scripts/request-secret.sh --label "Password"

# Remote user — start tunnel automatically
bash {skill}/scripts/request-secret.sh --label "Key" --service myapp --tunnel

# JSON output (for automation)
bash {skill}/scripts/request-secret.sh --label "Key" --service myapp --json

check-server.sh— 服务器诊断（无副作用）

bash {skill}/scripts/check-server.sh
bash {skill}/scripts/check-server.sh --json

报告服务器状态、端口、PID及隧道状态（ngrok或localtunnel）。

⏱ 长时间运行进程 — 使用tmux

该request-secret.sh脚本会持续阻塞直至密钥提交完成（通过持续轮询实现）。多数代理运行时环境（包括OpenClaw的exec工具）设有执行超时限制，这将导致进程在用户提交密钥前被强制终止。

请始终在tmux会话中运行Confidant：

# 1. Start server in tmux
tmux new-session -d -s confidant
tmux send-keys -t confidant "confidant serve --port 3000" Enter

# 2. Create request in a second tmux window
tmux new-window -t confidant -n request
tmux send-keys -t confidant:request "confidant request --label 'API Key' --service openai" Enter

# 3. Share the URL with the user (read from tmux output)
tmux capture-pane -p -t confidant:request -S -30

# 4. After user submits, check the result
tmux capture-pane -p -t confidant:request -S -10

为什么不直接执行？代理运行时通常会在30-60秒后终止进程。由于脚本需要等待人工输入（这可能耗时数分钟），它在完成前就会收到SIGKILL信号。而tmux能独立维持进程运行。

如果你的代理平台支持无超时限制的长时间后台进程，直接执行配合request-secret.sh是可行的。但若有疑虑，请使用tmux。

代理准则

1. 切勿要求用户在聊天中粘贴密钥——务必使用此技能
2. 切勿在聊天中泄露接收到的密钥——即使是部分内容也不可
3. 切勿直接通过curl调用Confidant API——请使用专用脚本
4. 切勿为启动新服务而终止现有服务器 to start a new one
5. 切勿尝试直接暴露端口（公网IP、防火墙规则等）— 请使用--tunnel替代
6. 务必在聊天中向用户分享URL— 这是该工具的核心目的
7. 务必等待脚本执行完毕— 它会自动轮询并保存/输出密钥；切勿自行尝试获取
8. 当用户处于远程环境时（不在同一机器/网络）请使用--tunnel
9. 对于API密钥，建议采用--service— 这是最规范的约定
10. 接收密钥后：确认成功，静默使用密钥

退出代码（脚本）

代理程序可根据退出代码进行分支处理，实现程序化错误处理：

使用--json时，所有错误都包含一个"code"字段，用于程序化分支：

{ "error": "...", "code": "MISSING_DEPENDENCY", "hint": "..." }

示例代理对话

交互过程应如下所示：

User: Can you set up my OpenAI key?
Agent: I'll create a secure link for you to submit your API key safely.
       [runs: request-secret.sh --label "OpenAI API Key" --service openai --tunnel]
Agent: Here's your secure link — open it in your browser and paste your key:
       🔐 https://gentle-pig-42.loca.lt/requests/abc123
       The link expires after you submit or after 24h.
User: Done, I submitted it.
Agent: ✅ Received and saved to ~/.config/openai/api_key. You're all set!

⚠️ 注意：代理发送URL并等待。它不会尝试自行访问该URL。

工作原理

1. 脚本启动Confidant服务器（或重用端口3000上的现有服务器）
2. 通过API创建具有唯一ID和安全Web表单的请求
3. 可选启动localtunnel以提供公共访问（或检测现有的ngrok/localtunnel）
4. 打印URL——代理在聊天中将其分享给用户
5. 将轮询任务委托给confidant request --poll该命令会阻塞直到密钥提交完成
6. 使用--service或--save密钥已保存到磁盘 (chmod 600)，然后在服务器上销毁
7. 不使用--service/--save：密钥被打印到标准输出，然后在服务器上销毁

隧道选项

脚本会自动检测两者。如果两者都未运行，并且传入了--tunnel，则启动 localtunnel。

高级：直接使用命令行界面

针对脚本未覆盖的边缘情况：

# Start server only
confidant serve --port 3000 &

# Start server + create request + poll (single command)
confidant serve-request --label "Key" --service myapp

# Create request on running server
confidant request --label "Key" --service myapp

# Submit a secret (agent-to-agent)
confidant fill "<url>" --secret "<value>"

# Check status of a specific request
confidant get-request <id>

# Retrieve a delivered secret (by secret ID, not request ID)
confidant get <secret-id>

如果confidant未全局安装，请先运行bash {skill}/scripts/setup.sh，或在命令前添加npx @aiconnect/confidant。

⚠️ 仅在脚本无法满足需求时，才直接使用命令行界面。