hkuds--openharness/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

oh — OpenHarness 中文说明

English · 简体中文

OpenHarness 是一个面向开源社区的 Agent Harness。它提供轻量、可扩展、可检查的 Agent 基础设施，包括：

• Agent loop
• tools / skills / plugins
• memory / session resume
• permissions / hooks
• multi-agent coordination
• provider workflows
• React TUI
• ohmo personal-agent app

---

最新更新

Unreleased · Dry-run 安全预览

• 新增 oh --dry-run，可以在不执行模型、不执行工具、不 spawn subagent 的前提下，预览当前会话会使用的配置、skills、commands、tools 和 MCP 配置。
• Dry-run 会给出 ready / warning / blocked 结论，并直接告诉你下一步该做什么，例如先修认证、先修 MCP 配置，或者可以直接运行。
• 对普通 prompt，会给出可能命中的 skills / tools；对 slash command，会展示它更偏只读还是会改本地状态。

2026-04-06 · v0.1.2

• 新增统一配置入口 oh setup
• provider 配置从“auth -> provider -> model”收敛成 workflow 视角
• Anthropic/OpenAI 兼容接口支持 profile 级凭据，不再强制共用一把全局 key
• 新增 ohmo personal-agent app
• ohmo 使用 ~/.ohmo 作为 home workspace，支持 gateway、bootstrap prompts 和交互式 channel 配置

---

快速开始

一键安装

curl -fsSL https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.sh | bash

常用安装参数：

• --from-source：从源码安装，适合贡献者
• --with-channels：一并安装 IM channel 依赖

例如：

curl -fsSL https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.sh | bash -s -- --from-source --with-channels

本地运行

git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness
uv sync --extra dev
uv run oh

---

配置模型与 Provider

现在最推荐的入口是：

oh setup

oh setup 会按下面的顺序引导：

1. 选择一个 workflow
2. 如果需要，完成认证
3. 选择具体后端 preset
4. 确认模型
5. 保存并激活 profile

当前内置 workflow 包括：

• Anthropic-Compatible API
• Claude Subscription
• OpenAI-Compatible API
• Codex Subscription
• GitHub Copilot

Anthropic-Compatible API

适合这类后端：

• Claude 官方 API
• Moonshot / Kimi
• Zhipu / GLM
• MiniMax
• 其他 Anthropic-compatible endpoint

OpenAI-Compatible API

适合这类后端：

• OpenAI 官方 API
• OpenRouter
• DashScope
• DeepSeek
• GitHub Models
• SiliconFlow
• Google Gemini
• Groq
• Ollama
• 其他 OpenAI-compatible endpoint

常用命令

# 统一配置入口
oh setup

# 查看已有 workflow/profile
oh provider list

# 切换当前 workflow
oh provider use codex

# 查看认证状态
oh auth status

高级：添加自定义兼容接口

如果内置 preset 不够，可以直接新增 profile：

oh provider add my-endpoint \
  --label "My Endpoint" \
  --provider anthropic \
  --api-format anthropic \
  --auth-source anthropic_api_key \
  --model my-model \
  --base-url https://example.com/anthropic

这一版开始，兼容接口可以按 profile 绑定凭据。
也就是说，Kimi、GLM、MiniMax 这类 Anthropic-compatible 后端，不需要再共用一把全局 anthropic key。

---

交互模式与 TUI

运行：

oh

你会得到 React/Ink TUI，支持：

• / 命令选择器
• 交互式权限确认
• /model 模型切换
• /permissions 权限模式切换
• /resume 会话恢复
• /provider workflow 选择

非交互模式也支持：

oh -p "Explain this repository"
oh -p "List all functions in main.py" --output-format json
oh -p "Fix the bug" --output-format stream-json

Dry-run 安全预览

如果你想先看 OpenHarness 会怎么跑，但又不想真的执行模型或工具，可以用：

# 预览交互会话本身
oh --dry-run

# 预览一个普通 prompt
oh --dry-run -p "Review this bug fix and grep for failing tests"

# 预览 slash command
oh --dry-run -p "/plugin list"

# 输出结构化 JSON，方便脚本或 channel 使用
oh --dry-run -p "Explain this repository" --output-format json

Dry-run 的边界是明确的：

• 不会调用模型
• 不会执行 tools
• 不会启动 subagent
• 不会连接 MCP server
• 会解析 settings、auth 状态、system prompt、skills、commands、tools，以及明显错误的 MCP 配置

Readiness 结论说明：

• ready：当前配置基本可直接运行
• warning：能解析会话，但仍有重要问题需要先处理，比如 MCP 配置错误或后续模型调用缺认证
• blocked：按当前状态直接运行会失败，比如 slash command 不存在，或者普通 prompt 无法解析 runtime client

Dry-run 输出里的 next actions 会直接给出下一步建议，例如：

• 先执行 oh auth login
• 先修或禁用坏掉的 MCP 配置
• 直接运行 oh -p "..." 或进入 oh

---

Provider 兼容性概览

OpenHarness 现在把 provider 视为 workflow + profile，而不是只暴露底层协议名。

Workflow	说明
Anthropic-Compatible API	Anthropic 风格接口，适合 Claude/Kimi/GLM/MiniMax 等
Claude Subscription	复用本地 ~/.claude/.credentials.json
OpenAI-Compatible API	OpenAI 风格接口，适合 OpenAI/OpenRouter/各种兼容网关
Codex Subscription	复用本地 ~/.codex/auth.json
GitHub Copilot	GitHub Copilot OAuth workflow

日常推荐用法：

oh setup
oh provider list
oh provider use <profile>

---

ohmo Personal Agent

ohmo 是基于 OpenHarness 的 personal-agent app，不是 core 的一个 mode。

初始化

ohmo init

这会创建：

• ~/.ohmo/soul.md
• ~/.ohmo/identity.md
• ~/.ohmo/user.md
• ~/.ohmo/BOOTSTRAP.md
• ~/.ohmo/memory/
• ~/.ohmo/gateway.json

其中：

• soul.md：长期人格与行为原则
• identity.md：ohmo 自己是谁
• user.md：用户画像、偏好、关系信息
• BOOTSTRAP.md：首轮 landing / onboarding ritual
• memory/：personal memory
• gateway.json：gateway 的 profile 和 channel 配置

配置

ohmo config

ohmo config 会用和 oh setup 一致的 workflow 语言来配置 gateway，例如：

• Anthropic-Compatible API
• Claude Subscription
• OpenAI-Compatible API
• Codex Subscription
• GitHub Copilot

目前 ohmo init / ohmo config 已支持引导式配置这些 channel：

• Telegram
• Slack
• Discord
• Feishu

如果 gateway 已经在运行，配置完成后也可以直接选择是否重启。

运行

# 运行 personal agent
ohmo

# 前台运行 gateway
ohmo gateway run

# 查看 gateway 状态
ohmo gateway status

# 重启 gateway
ohmo gateway restart

---

OpenHarness 的核心能力

Agent Loop

• streaming tool-call cycle
• tool execution / observation / loop
• retry + exponential backoff
• token counting 与成本跟踪

Tools / Skills / Plugins

• 43+ tools
• Markdown skills 按需加载
• 插件生态
• 兼容 anthropics/skills
• 兼容 Claude-style plugins

Memory / Session

• CLAUDE.md 自动发现与注入
• MEMORY.md 持久记忆
• session resume
• auto-compact

Governance

• 多级 permission mode
• path rules
• denied commands
• hooks
• interactive approval

Multi-Agent

• subagent spawning
• team registry
• task lifecycle
• background task execution

---

常见命令

oh

oh setup
oh provider list
oh provider use codex
oh auth status
oh -p "Explain this codebase"
oh

ohmo

ohmo init
ohmo config
ohmo
ohmo gateway run
ohmo gateway status
ohmo gateway restart

---

测试

uv run pytest -q
python scripts/test_harness_features.py
python scripts/test_real_skills_plugins.py

---

贡献

欢迎贡献：

• tools
• skills
• plugins
• providers
• multi-agent coordination
• tests
• 文档与中文翻译

开发环境：

git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness
uv sync --extra dev
uv run pytest -q

更多信息：

• 贡献指南
• 更新日志
• Showcase

---

License

MIT，见 LICENSE。