大部分设置都在应用的设置页里。这一页讲的是不在那里的部分:需要你在配置文件里手写的键,以及 harness 读取的环境变量。有专门页面的键——模型厂商、记忆、同步、插件——这里只简单列出,并附上对应页面的链接。
设置放在哪里
| 文件 | 作用范围 |
|---|
~/.oharness/config.json | 你自己,在这台电脑上。下面所有的键都可以写在这里。 |
项目里的 oharness.config.json(或 .oharness.json) | 打开这个项目的每个人。 |
项目文件会合并覆盖在你的配置之上,所以项目可以收紧或调整你的设置。有些键是故意不允许写在项目文件里的,因为你克隆下来的仓库不应该替你决定这些:
team:花谁的积分sync.url、sync.token、sync.team:你的对话记录发到哪里runtimePlugins:在你电脑上运行的代码- 开启自动提取或合并记忆,这会花你的模型积分。项目可以关闭它们。
OHARNESS_HOME 可以把整个 ~/.oharness 目录挪到别处。目录里的其他文件见配置文件。
{
"model": "sonnet",
"smallModel": "haiku",
"permissionMode": "auto",
"permissions": { "deny": ["Bash(git push --force*)"] },
"writableRoots": ["~/scratch"],
"maxTurns": 100,
"sessionRetention": { "maxAgeDays": 90 }
}
模型
| 键 | 作用 |
|---|
model | 新对话默认使用的模型,填 id 或别名。 |
smallModel | 用来做杂活的模型,这些活用不着主模型:上下文压缩的摘要、记忆提取、生成标题之类的后台任务,以及自动模式的审查模型。不设置时,它们会用对话本身的模型,成本可能比实际需要高得多。 |
thinking | 默认的推理设置:{ "enabled": true, "effort": "high" }。effort 会按模型支持的范围自动调整。budgetTokens 适用于接受 token 预算的模型。display 取 "summarized" 或 "omitted"。 |
cache | 在厂商支持时启用提示词缓存。默认开启。 |
models、providers、catalog、openAiCompatible、oauthProviders | 添加或覆盖模型和厂商。见模型厂商与模型。 |
记得设置 smallModel。 自动模式在审查每个操作之前都会调用它,长对话的压缩也会调用它。用一个又快又便宜的模型,两者都会更快,成本也更低。如果这个 id 解析不了,harness 会记一条警告,然后退回使用对话的模型。
权限
| 键 | 作用 |
|---|
permissionMode | 新对话默认的模式:default、acceptEdits、plan、auto 或 bypassPermissions。 |
permissions | allow、ask 和 deny 规则。deny 规则胜过所有模式,包括 Bypass。 |
workspaceMode | 允许写到哪里:read-only、workspace-write(默认:项目目录加上 writableRoots)或 full-access。它检查的是工具参数,不是操作系统沙箱。 |
writableRoots | agent 额外可以写入的目录。 |
readableRoots | agent 额外可以读取、但不能写入的目录。 |
audit | 把每一次权限决定和所属会话一起记录下来。除非设为 false,否则默认开启。 |
auditLog | 同时把每次决定追加到这个文件,适合需要收集记录的无人值守运行。 |
权限讲解了各种模式、规则语法,以及自动模式的审查模型如何做决定。
轮次与指令
| 键 | 作用 |
|---|
maxTurns | 一条提示词最多允许调用多少次模型,到了上限 agent 就停下来汇报。默认 60。 |
systemPrompt | 替换内置的系统提示词。一般不是你想要的。 |
appendSystemPrompt | 追加在内置系统提示词之后的文本。 |
instructionsFile | 用来替代默认文件的项目指令文件,路径相对于项目根目录。 |
| 键 | 作用 |
|---|
tools | 按工具名写的 { "allow": [...], "deny": [...] }。支持 mcp__github__* 这样的通配符。deny 在 allow 之后生效。这里排除掉的工具根本不会提供给模型;权限规则则不同,它是在调用发生时拒绝。 |
browser | { "mode": "auto" }(默认)让 agent 自己选择:通过扩展使用你的浏览器,或者用内置浏览器。设为 builtin、extension 或 off 则固定下来。 |
claudeAgent | 把你自己的 Claude Code 作为子 agent 和 @claude 提供出来,费用走你的 Claude 套餐。除非设为 true,否则关闭。 |
imports | 从 Claude Code 和 Codex 的原有位置读取它们的技能、agent 和 MCP 服务器。除非设为 false,否则两者都开启。 |
skillDirs、agentDirs | 额外扫描技能和子 agent 定义的目录。 |
disabledSkills | 按名称关闭的技能。 |
mcpServers、hooks、subagents、plugins、runtimePlugins | 见插件。 |
schedules | 按 cron 计划运行的提示词。 |
会话与 worktree
| 键 | 作用 |
|---|
sessionDir | 会话和对话记录的存放位置。默认是 ~/.oharness 下的 storage/。指定其他目录会从空白开始:默认位置里已有的记录不会被导入。 |
sessionRetention | { "maxAgeDays": 90, "keep": 500 } 会在启动时删除较旧的会话。不设置的话什么都不会删。 |
worktree | 准备新的 git worktree。copy 列出路径或通配符,worktree 里缺少这些文件时从项目复制过去(默认 .env*)。setup 是在新 worktree 里运行的 shell 命令,比如 npm ci。 |
memory、sync | 见记忆与同步。 |
计费与日志
| 键 | 作用 |
|---|
team | 把官方方案的用量记到某个团队的积分上,而不是你自己的。服务端会检查你是否在这个团队里。只能写在你自己的配置或 OHARNESS_TEAM 里,不能写在项目文件里。 |
logLevel | debug、info、warn、error 或 silent。 |
环境变量
如果有对应的配置键,环境变量会覆盖它。
| 变量 | 作用 |
|---|
OHARNESS_HOME | 用另一个目录代替 ~/.oharness。 |
OHARNESS_TEAM | 等同于 team。 |
OHARNESS_SYNC | 设为 0、false、off 或 no 时关闭同步,不管配置里怎么写。 |
OHARNESS_SYNC_TOKEN | 同步凭据,在配置里没有写时使用。 |
OHARNESS_SITE_URL | 自托管或开发环境的 Cloud 地址。 |
OHARNESS_CATALOG | 用这个文件作为你的模型目录。 |
OHARNESS_NO_BUILTIN_MODELS | 设为 1 时不加载内置的模型目录,只保留你自己添加的条目。 |
OHARNESS_NO_CLAUDE_AGENT | 设为 1 时永远不把 Claude Code 作为子 agent 提供。 |
OHARNESS_BROWSER_PATH | 内置浏览器启动的 Chrome 或 Chromium 可执行文件。 |
OHARNESS_BROWSER_HEADLESS | 设为 0 时内置浏览器会显示窗口。 |
OHARNESS_CLAUDE_HOME、OHARNESS_CODEX_HOME | Claude Code 和 Codex 的文件不在默认位置时,从哪里读取。 |