OURO

本地优先、可灵活拓展的个人智能体。

OURO 让你在终端中与模型协作，处理文件、调用工具、管理会话和执行持续任务。它提供全屏交互界面，也可以通过命令行完成单次任务或输出 JSON。会话与配置保存在本地，模型服务由你选择。

插件是 OURO 的核心拓展机制：除了工具、Skills 和 MCP，还可以拓展模型接入、智能体运行方式、后台任务及插件间协作，按需安装、启用和停用。

OURO v0.2.0 实际界面 · Horizon 欢迎页 · 尚未配置模型的初始状态

使用文档 · 版本记录 · 源码 · 问题反馈

为你的工作方式而拓展

能力	你可以做什么
终端协作	在全屏 TUI 中交互，或通过 CLI 完成单次任务、输出 JSON。
本地资料	读取、编辑和搜索文件，使用附件及模型支持的图片、音频或视频输入。
持续任务	保存和恢复会话，通过子智能体、Goal / Plan 拆分任务、管理目标与计划。
模型与工具	配置多家模型供应商、兼容接口和 MCP 服务，为任务选择合适能力。
可组合插件	按需拓展工具、Skills、模型接入、智能体循环、插件协作与后台调度。
执行控制	通过权限、人工审批、取消操作和运行预算控制执行，查看用量与历史。

安装

OURO 需要 Python 3.14 或更高版本。建议使用支持 Unicode 的现代终端。

使用 uv 安装（推荐）

安装 uv 后执行：

uv tool install --python 3.14 ouro-agent
ouro --version

uv 会为 OURO 创建独立环境，并按需安装所需 Python。若终端提示找不到 ouro，执行 uv tool update-shell 后重新打开终端。

使用 pip 安装

如果已经有 Python 3.14+ 环境，也可以安装到自己的虚拟环境中：

python -m pip install ouro-agent
ouro --version

PyPI 包名是 ouro-agent，安装后的命令是 ouro。

第一次使用

1. 配置模型

使用真实模型需要对应供应商的账户与凭据。OURO 不附带模型权重或 API 额度；尚未配置供应商时，内置 Faux 仅提供离线演示，不是真实模型。

下面以 OpenAI API 为例。先在当前终端设置自己的 API Key：

Windows PowerShell：

$env:OPENAI_API_KEY = "替换为你的 API Key"

macOS / Linux（bash 或 zsh）：

export OPENAI_API_KEY="替换为你的 API Key"

再添加供应商并设为默认：

ouro provider add "OpenAI" --type openai --api-key-env OPENAI_API_KEY --default

以上环境变量设置只对当前终端及其子进程生效。重新打开终端后，需要重新设置，或通过系统环境变量管理保存。OURO 配置中记录的是变量名。

你也可以通过 ouro provider templates 查看其他内置供应商模板，或在交互界面按 Ctrl+P，进入 Manage providers 管理供应商。模型是否可用取决于你的账户权限和供应商支持范围。

2. 启动交互界面

在想要处理的工作目录中执行：

ouro

输入任务即可开始。Ctrl+P 打开操作菜单，/help 查看快捷键与命令帮助。

3. 尝试命令行任务

# 文本输出
ouro run --print "说明当前目录的用途，并给出整理建议"

# JSON 输出，便于脚本集成
ouro run --json "总结本次任务"

# 查看帮助
ouro --help

只想先检查安装是否正常，可以在独立数据目录运行离线演示，无需 API Key：

ouro run --print --home ./.ouro-demo "hello"

按需增加能力

OURO 提供稳定的运行框架，插件作为独立拓展包接入。你可以从工具和 Skills 开始，也可以通过插件定制智能体的执行方式、模型接入、服务协作和后台任务。

插件管理入口可通过 ouro plugin --help 查看。请只安装并启用你信任的插件；插件和工具可能读写文件、执行程序或连接外部服务。

数据保存在哪里

默认数据目录为用户主目录下的 .ouro，用于保存配置、会话及运行记录。可以用 --home 为不同用途选择独立目录：

ouro --home ./.ouro-work
ouro session list --home ./.ouro-work

目录选择顺序为：--home、环境变量 OURO_HOME、默认的 ~/.ouro。本地保存不代表所有处理都离线；模型请求会发送到你配置的服务。

升级前建议备份数据。当前版本会明确拒绝不受支持的旧数据格式，不会自动迁移或清空原数据；需要隔离体验时可使用新的 --home 目录。

升级

使用 uv 安装：

uv tool upgrade ouro-agent

使用 pip 安装：

python -m pip install --upgrade ouro-agent

文档与源码

完整源码位于 GitHub，安装包和源码包发布在 PyPI。

• 文档入口：使用指南、插件开发、配置说明与运行契约。
• 更新记录：各版本的主要改进与兼容性说明。
• 贡献指南：开发流程与验证要求。
• 问题反馈：报告问题或提出改进建议。

参与开发：

git clone https://github.com/djsaber/OURO.git
cd OURO
uv sync --frozen --all-groups
uv run --frozen ouro

开源协议

OURO 是完全开源的项目，采用 MIT License，允许使用、修改与分发。欢迎参与改进，也欢迎构建适合自己的插件。