配置

供应商

hara 与供应商无关。它对阿里 Token Plan、火山方舟 Agent Plan、MiniMax Token Plan、 Anthropic Claude、DeepSeek 和 Qwen（免费 OAuth 额度）提供一流支持，并能对接任何 OpenAI 兼容端点——OpenAI、GLM 或本地模型服务。

# 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
 
# 阿里 Token Plan —— 个人版或团队版订阅 Key
hara profile add aliyun --byok --provider token-plan --model qwen3.8-flash
 
# MiniMax Token Plan
hara profile add minimax --byok --provider minimax-token-plan --model MiniMax-M3
 
# 火山方舟 Agent Plan —— 专属 Plan Key、北京 Responses 路线
hara profile add ark-agent-plan --byok --provider volcengine-agent-plan --model ark-code-latest
 
# DeepSeek —— 直连官方 API
export DEEPSEEK_API_KEY=...
hara config set provider deepseek
hara config set model deepseek-v4-pro
# 会话需要上传图片时：
hara config set model deepseek-v4-flash-vision-exp
 
# 任意 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

方舟 Agent Plan 为不同客户端提供两条不同路线，并不是一条 URL 可以复制给所有工具。Hara 与 Codex 使用 Responses 路线 https://ark.cn-beijing.volces.com/api/plan/v3 和 ARK_API_KEY；Claude Code 使用 Anthropic 兼容路线 https://ark.cn-beijing.volces.com/api/plan 和 ANTHROPIC_AUTH_TOKEN。 Hara 会自动选择固定的 Responses 路线，上述 profile 命令会通过遮罩输入读取 Agent Plan 专属 Key。 不要换成普通按量 Ark Key 或旧 Coding Plan Key。详见官方 Codex 接入文档 和官方 Claude Code 接入文档。

阿里 Token Plan 使用固定的北京 OpenAI 兼容端点，不要替换成按量计费的 Workspace URL。Hara 会读取 当前 Key 实际授权的实时模型目录，并让当前 Qwen 3.8/3.7/3.6、DeepSeek V4 与 GLM 5.2 Agent 模型 走官方 Responses 路由；生图、语音和视频模型不会混入对话选择器。关闭“识图优先”时， qwen3.8-max、qwen3.8-flash、qwen3.7-plus 与 qwen3.6-flash 会直接接收图片附件。 除非用户明确配置，Hara 不会把图片交给另一个模型或静默转发到另一家供应商。

普通聊天会显示模型支持的思考档位。选择「关闭」时只发送 enable_thinking:false，因为这是实测能把 Token Plan reasoning token 归零的行为；开启档位使用 reasoning.effort。消息 Flow 默认关闭思考， 以稳定延迟与 Credits 消耗，但可以显式继承聊天设置或选择其他档位。Hara 会发送 store:false、把完整 对话持久化在本机，并启用阿里的 Session 前缀缓存。供应商托管的 Harness 工具不会被静默打开，本地 审批、公司策略与 Hara 审计仍是唯一执行边界。

以上命令都会通过 Hara 的遮罩输入框读取 Key，不要把凭据直接写进 shell 历史。Token Plan 订阅 Key 只允许用于受支持的交互式编程与 Agent 工具，不能作为任意应用后端或批处理接口； Key 也只能由订阅者本人使用。请以最新的阿里 Token Plan 个人版规则为准。

直连官方 https://api.deepseek.com 时，deepseek-v4-flash 与 deepseek-v4-pro 使用 DeepSeek 无状态 Responses API 处理文本。精确的 deepseek-v4-flash-vision-exp 还会通过 Responses input_image 接收上传的 PNG、JPEG、GIF、WebP；Hara 会内嵌本地附件，不要求先把图片放到公网 URL。 Hara 会接收语义化的推理、正文与 Function Call 流事件，并校验顺序和终态。Flash 与 Pro 不会因为 同属一个供应商就被误标成视觉模型。

自定义端点或 Hara Control 托管 profile 遵循网关实际提供的协议，不能据模型名称假定其支持 /v1/responses。显式关闭思考时会改用 DeepSeek Chat 路线并关闭 thinking。上游模型和媒体边界见 DeepSeek 官方视觉指南。

识图优先路线

如果希望所有图片都先经过一个指定识图模型，请设置 visionModel。即使主对话模型本身也支持图片， Hara 仍只把识图模型输出的文字描述交给主模型：

hara config set visionModel deepseek-v4-flash-vision-exp
# 在交互会话中查看、切换或关闭：
/vision
/vision deepseek-v4-flash-vision-exp
/vision off

个人连接可在 Desktop「设置 → AI 与模型」中通过遮罩输入配置独立的识图端点和 Key。公司连接会忽略 个人端点/Key 覆盖：识图模型必须出现在当前 Space 的服务端允许列表中，并继续使用同一枚受管设备凭据。 执行 /vision off 后，图片恢复由主对话模型按自身原生能力处理。

任何时候都可以运行 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:token-plan | minimax-token-plan | anthropic | deepseek | 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 把东西放在哪里