Pencil 桌面版启动问题排查与修复

问题现象

  • 软件打开后界面空白，没有任何内容
  • 点击 File > New，窗口内容一闪而过随即消失
  • 点击 File > Settings，无任何窗口弹出

根本原因

Pencil 需要两套独立的认证，缺任何一个都会导致 UI 无法显示：

认证 用途 存储位置
Pencil 账号 session 渲染 UI 界面 ~/.pencil/session-desktop.json
Claude API Key 调用 AI 功能 %APPDATA%/Pencil/config.json

需要提供的信息

  1. Pencil 账号：注册邮箱 + 密码
  2. Anthropic API Key：sk-ant-... 格式
  3. API Base URL（可选）：如果走代理，提供自定义地址

修复步骤

第一步：写入 Claude API Key

编辑 %APPDATA%\Pencil\config.json，确保包含以下字段：

{
  "claudeApiKey": "sk-ant-你的key",
  "claudeLoginType": "api-key"
}

第二步：获取 Pencil session token

计算设备 ID：

node -e "
const os = require('os'), crypto = require('crypto');
const machineId = os.hostname() + os.platform() + os.arch();
console.log(crypto.createHash('md5').update(machineId).digest('hex'));
"

用密码登录，获取 sessionToken：

curl -X POST "https://api.pencil.dev/auth/device-login" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "password",
    "email": "你的邮箱",
    "password": "你的密码",
    "deviceId": "上一步获得的设备ID",
    "clientType": "desktop"
  }'

返回示例：

{
  "sessionToken": "eyJhbGci......",
  "email": "xxx@qq.com",
  "hasSetPassword": true
}

第三步：写入 session 文件

将返回的 sessionToken 写入 ~/.pencil/session-desktop.json（没有则新建）：

{
  "email": "你的邮箱",
  "token": "返回的 sessionToken"
}

Windows 上路径为：C:\Users\用户名\.pencil\session-desktop.json

第四步：设置代理 Base URL（可选）

如果使用第三方代理服务，需要在 Windows 用户环境变量中添加：

变量名：ANTHROPIC_BASE_URL
变量值：https://你的代理地址

设置方法：右键"此电脑" > 属性 > 高级系统设置 > 环境变量 > 用户变量 > 新建

第五步：重启 Pencil

完成以上配置后，重启 Pencil 软件即可正常使用。

日志位置

如需排查其他问题，日志文件路径：

%APPDATA%\Pencil\logs\main.log

常见错误信息：

  • get-session → hasPayload: false → session 文件缺失或无效
  • 401 Unauthorized: Missing bearer or basic authentication → API Key 未配置或无效
  • removeResource: pencil-new.pen 紧随 open-settings 之后 → 同为 session 缺失导致