配置

供应商

hara 与供应商无关。它对 Anthropic Claude 和 Qwen(免费 OAuth 额度)提供一流支持, 并能对接任何 OpenAI 兼容 端点 —— OpenAI、GLM、DeepSeek 或本地模型服务。

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
hara config set provider anthropic
hara config set model claude-opus-4-8
 
# Qwen —— 免费设备登录(无需 key)
hara login qwen
 
# 任意 OpenAI 兼容端点
hara config set provider openai
hara config set baseURL https://your-endpoint/v1
hara config set apiKey  sk-...
hara config set model   your-model-id

任何时候都可以运行 hara doctor,检查供应商、鉴权和模型是否能正确解析。

配置文件

全局配置位于 ~/.hara/config.json(以 0600 权限写入 —— 它可能保存 API key)。仓库可以在 根目录放 .hara/config.json,但它默认不受信任:只读取经过校验的 model、theme、 vimMode、autoCompact 和 reasoningEffort 偏好。供应商路由、凭据、hooks、MCP、sandbox、 guardian、approval 和自动化配置都会被忽略。只有在你审查并信任该仓库时,才应在启动 hara 之前设置 HARA_TRUST_PROJECT_CONFIG=1;启动后再修改不能扩大信任。

hara config set <key> <value>   # 写入一个值
hara config get [key]           # 读取配置(apiKey 会被掩码)
hara config path                # 打印配置文件路径

值得了解的配置项

环境变量覆盖

每个配置项都有对应的 HARA_<KEY> 环境变量覆盖(全大写),它优先于配置文件 —— 在 CI、cron 和临时场景中很方便。

HARA_MODEL=claude-haiku-4-5 HARA_APPROVAL=full-auto hara -p "bump the version"

常用的有:HARA_PROVIDER、HARA_MODEL、HARA_API_KEY、HARA_BASE_URL、HARA_APPROVAL、 HARA_SANDBOX、HARA_MAX_CONCURRENCY、HARA_TUI=0(经典 readline)、HARA_PROFILE。

安全开关有意限定在单个进程:HARA_TRUST_PROJECT_CONFIG=1 信任特权项目配置/profile pin, HARA_ALLOW_TRUSTED_EXTENSIONS=1 允许审查过的 MCP/外部 agent 在非交互任务中运行, HARA_ALLOW_SENSITIVE_FILES=1 让本次启动可访问受保护文件。不要为不受控仓库持久设置它们。

Profile

profile 是一个命名好的身份 —— 也就是 hara 怎么访问模型。有两种:

• BYOK —— 你自己的供应商 + key(「个人」路径)。
• Gateway —— 由你所在组织运行的 hara-control 网关(「公司/团队」路径);真正的 key 留在服务端。

# BYOK:用你自己的 key
hara profile add personal --byok --provider anthropic --key sk-ant-... --model claude-opus-4-8
# --provider:anthropic | openai | qwen | qwen-oauth
# --base-url <url> 让 openai 指向任意 OpenAI 兼容端点(GLM、DeepSeek、本地……)
 
# Gateway:加入你所在组织的 fleet(--code 由管理员提供)
hara profile add work --gateway https://gw.example.com --code ABC123
# `hara enroll <url> --code <code>` 是添加默认 org 网关 profile 的简写

请填写管理员提供的公网 HTTPS 根地址，不要附加 /v1。远程明文 HTTP、重定向和带有内嵌 凭据的 URL 都会被拒绝。一次性注册码兑换后即被清除，只有有作用域的设备凭据留在 Hara 受保护的 profile 存储中。Desktop 中的同一流程位于「设置 → AI 与模型 → 企业托管」。

企业 profile 的模型列表由服务端授权决定，本机不能增加未授权模型。从 Hara Control 0.1.15 起， 一次注册和一枚设备凭据会收到完整允许模型目录，因此同一个命名 profile 可以直接切换 deepseek-v4-flash 与 deepseek-v4-pro，无需新注册码或新 Key。不同公司或不同网关仍应分别 保存 profile；同一企业内不再按模型拆连接。两种模型的思考档位均为 off、high、max。

然后管理与切换:

hara profile list        # 所有 profile,以及当前激活的是哪个
hara profile use <id>    # 设为默认 profile
hara profile pin <id>    # 把某个 profile 锁定到当前目录
hara --profile <id> -p "…"   # 单次运行使用某个 profile

pin 保存在本地 .hara-profile。Git 已跟踪的 pin 默认会被忽略,因为仓库不应静默替你选择身份; 只有显式信任项目配置后才会启用。

你也可以把更轻量的、只含设置的组合存进 ~/.hara/config.json,用 --profile(或 HARA_PROFILE) 选择 —— 适合在不切换完整身份的情况下临时调整 model / approval:

{
  "provider": "anthropic",
  "model": "claude-opus-4-8",
  "profiles": {
    "fast": { "model": "claude-haiku-4-5", "approval": "full-auto" },
    "review": { "model": "claude-opus-4-8", "approval": "suggest" }
  }
}

hara --profile fast -p "regenerate the snapshot tests"

hara 把东西放在哪里