第一步：注册或登录

打开 harbourmind.ai/user，输入个人邮箱，点击“发送验证码”，再输入邮件中的 6–8 位数字。第一次登录会自动创建你的个人账户和钱包，不需要管理员审批。

第二步：创建并保存 Key

进入左侧“API Keys”，填写用途名称；个人使用可暂时不填月预算。点击“创建 API Key”后，立即复制完整 Key。它只显示一次。建议保存到密码管理器，并在 terminal 设置：

export HM_API_KEY="粘贴完整 HM Key"

不要截图公开、不要写入代码、不要提交到 Git。Key 泄露时回到 API Keys 撤销并重建。

第三步：先验证 Key

先读取你真实可用的模型目录。看到 JSON 模型列表代表网关和 Key 都正常；这一步不会生成内容。

curl --fail-with-body https://harbourmind.ai/v1/models \
  -H "Authorization: Bearer $HM_API_KEY"

第四步：选择你使用的外壳

所有外壳都使用同一个 Base URL：https://harbourmind.ai/v1。默认模型 harbourmind 会智能路由；指定模型时，请复制“价格”页展示的完整模型 ID。

Python / Node.js

使用 OpenAI-compatible SDK 时，只需改 Base URL、Key 和模型。Python 初始化：OpenAI(base_url="https://harbourmind.ai/v1", api_key=os.environ["HM_API_KEY"])。Node.js 初始化：new OpenAI({baseURL:"https://harbourmind.ai/v1", apiKey:process.env.HM_API_KEY})。完整示例在机器接入规范中。

Codex：OpenAI 官方文档没有确认 HarbourMind 是 Codex 支持的登录 provider，因此这里不提供可能失效的“一键配置”。需要 HarbourMind Key 时优先使用 OpenCode；不要让脚本擅自覆盖 Codex 配置。

第五步：核对计费

完成请求后打开“用量”，按请求编号核对模型、输入/输出 Token 和费用；余额在概览显示。充值请进入“充值”，Stripe 支付成功后会回到同一账户钱包，Studio 和 API 共用该余额。

遇到问题时

401：Key 不完整、已撤销或 Authorization 格式错误，重新复制或创建 Key。　余额不足：前往充值页，到账后重试。　模型不可用：重新请求 GET /v1/models，使用返回的精确模型 ID。　429：降低并发并稍后重试。　网页和 terminal 文字不同：两边已使用相同 model/messages 且无隐藏 prompt，但生成存在随机性，应比较任务结果而不是逐字文本。