xiaoO

English | 中文

AgentOS 的开源智能中枢。

xiaoO 是什么？

xiaoO 是 AgentOS 的智能中枢，提供面向系统管理、智能体编排、工具执行、记忆、上下文压缩和多渠道接入的自治 Agent 运行时。

它把操作系统变成 Agent 可以稳定工作的环境：文件、Shell 命令、Git、Web 访问、LSP 诊断、技能、Hook、渠道接入和运行时遥测，都通过统一的 Agent Loop 协同起来。

xiaoO 的运行时还内置了分层记忆和自适应上下文压缩系统，让长对话、高频工具调用和多 Agent 协作不再被原始历史无限增长拖垮。

核心特性

• Agent 运行时中枢：支持 CLI、TUI、Daemon、HTTP API 和渠道集成。
• 完整工具能力：文件操作、Shell 执行、Git、Web 搜索/浏览、补丁应用、子 Agent 和可扩展工具清单。
• 自适应上下文管理：Token 预算跟踪、配置化压缩、上下文超限后的强制恢复和 prefix-cache 遥测。
• 流式推理展示：在模型工作时展示 provider 返回的 reasoning/thinking 增量。
• 推理强度分级：支持 off、high、max；TUI 中可用 Ctrl+T 循环切换。
• 会话管理：支持保存和恢复长时间运行的任务。
• LSP 诊断：编辑后通过 rust-analyzer、pyright、typescript-language-server、gopls、clangd 等服务展示错误和警告。
• Skills 技能系统：从本地目录或 Git 来源安装可复用的指令包。
• Hook 与插件系统：在 Agent 创建、LLM 调用前后、工具调用前后提供扩展点，可用于审计、策略、追踪和自定义扩展。
• 可观测性：支持实时 token/cost 统计，并通过 noop、stdout 或 moirai-sqlite 存储 trace。
• 定时和触发式任务：支持接入长期运行的自动化工作流。
• 本地化 UI：提供适合日常 Agent 工作的终端界面。

前置要求

• 已安装 Rust 工具链和 Cargo。
• 可用的 LLM provider 账号，或本地模型端点。
• 通过环境变量或 xiaoO 配置文件提供 provider 凭证。

从源码安装

git clone https://gitcode.com/openeuler/xiaoO.git
cd xiaoO
cargo install --path apps/endside

安装后应用二进制会位于 ~/.cargo/bin，并尝试安装内置技能。请确认 ~/.cargo/bin 已加入 PATH。

注意：cargo build 不会安装技能，只有 cargo install 会触发技能安装。

安装行为：

• 首先尝试安装内置技能到系统级目录：/usr/lib/.xiaoo/skills/（需要 root 权限）
• 如果系统级安装失败（如权限不足），自动回退到用户级目录：~/.xiaoo/skills/
• 内置技能包括 xiaoo-guardian（安全策略执行）以及其他内置能力
• 缺少这些技能可能导致安全功能不可用。

系统级安装（推荐用于多用户环境）：

• 使用 root 权限运行 cargo install：sudo cargo install --path apps/endside

卸载

# 卸载二进制文件
cargo uninstall xiaoo-endside

# 删除系统级 guardian 技能（需要 root 权限）
sudo rm -rf /usr/lib/.xiaoo/skills/xiaoo-guardian

技能目录优先级（四层 - 仅运行时搜索）

技能在运行时按四个目录层级搜索（优先级从高到低）：

1. 项目级：./.xiaoo/skills/
2. 配置级：[skills].dirs 中指定的目录
3. 用户级：~/.xiaoo/skills/
4. 系统级：/usr/lib/.xiaoo/skills/（仅内置技能）

详见 docs/skill_usage.md。

构建

./build.sh --release

该构建脚本可以安装 audit_agent hooker，用于审计工具执行中的高风险操作。插件安装与使用请参考 docs/plugins.md。

快速开始

创建 ~/.config/xiaoo/config.toml：

[llm]
provider = "openrouter"              # openai, anthropic, ollama, openrouter, deepseek, zai, minimax, kimi, minimax-coding-plan, kimi-coding-plan, ...
model = "z-ai/glm-5"
api_key_env = "OPENROUTER_API_KEY"   # 从这个环境变量读取 API 密钥
max_tokens = 128000                  # 可选，每次响应的最大输出 token 数（仅 TUI/Daemon 支持；CLI 忽略此字段）
reasoning_effort = "off"             # 可选: off, high, 或 max（仅 TUI 支持；CLI 使用 --reasoning-effort；Daemon 使用 HTTP API 字段）

# 预定义 subagent 角色（CLI/TUI/Daemon 均支持） ⭐
# 注意：tools 配置支持两种格式，详见 docs/config_file_guide.md
[subagent.code_reviewer]
description = "代码审查专家"
prompt = "你是代码审查专家，专注于代码质量和最佳实践。"
max_turns = 5

[subagent.code_reviewer.tools]
bash = true
read = true
glob = true
grep = true

[trace]
storage_backend = "moirai-sqlite"    # noop, stdout, 或 moirai-sqlite
db_path = "~/.xiaoo/traces.db"       # 当 storage_backend 为 moirai-sqlite 时使用

设置 provider 凭证：

export OPENROUTER_API_KEY="sk-or-..."

为本地 LLM 设置自定义 API url (以入口 http://localhost:8080/v1/chat/completions 为例)：

[llm]
provider = "local"
model = "deepseek-v4-flash"
api_base = "http://localhost:8080/v1"
api_key_env = "LLM_API_KEY"

local provider 默认 base url 即为 http://localhost:8080/v1，仅在端口或路径不同时才需要设置 api_base。如果不写 /v1，OpenAI-compatible 客户端在 /chat/completions 失败 (404) 后仍会回退探测 /v1/chat/completions，但显式写明可避免多余的失败请求。

运行 xiaoO：

# 终端 UI
xiaoo

# 单次 CLI 调用
xiaoo --cli run -p "Count the characters in hello world"

CLI 输出示例：

"hello world" has 11 characters.

配置文档:

• 通用配置指南 - 所有模式共用的配置项（llm、subagent、skills等）
• CLI配置 - CLI基础用法和支持的配置
• TUI配置 - TUI专用配置（remote、LSP、agent角色）
• Daemon配置 - Daemon专用配置（channels、HTTP API）

上下文窗口

上下文窗口大小由运行时动态解析。xiaoO 会按以下顺序解析最终值：

1. 动态模型查询：调用 provider 的模型目录接口（/models 或等价接口）。只要 provider profile 中 supports_model_catalog = true 即可，包括 openai、anthropic、gemini、ollama、zai/zhipu、deepseek、openrouter、kimi、kimi-coding-plan、minimax-coding-plan、gitcode、local、other 等；supports_model_catalog = false 的 provider（如 minimax、minimax-anthropic）跳过此步。
2. 本地兜底默认值（按 provider 协议族）：
   • OpenAI-compatible、Ollama 和智谱系列默认为 128000
   • Anthropic 默认为 200000
   • Gemini 默认为 1000000

更多说明请查看 Memory & Context Compression。

推理强度

[llm].reasoning_effort 用于控制 provider 侧支持的 thinking 或 reasoning 级别。

值	含义	TUI 颜色
off	在支持的 provider 中关闭额外推理控制	灰色
high	使用更强的推理/思考设置	黄色
max	使用最强的推理/思考设置	红色

TUI 状态栏会显示当前值：Think off/high/max。按 Ctrl+T 可按 off -> high -> max -> off 为下一轮切换强度。CLI 模式可使用：

xiaoo --cli run --reasoning-effort high -p "Explain this repository"

Provider 映射采用 best-effort 策略：OpenAI-compatible provider 在 high 和 max 时接收 reasoning_effort；Anthropic 接收 thinking.budget_tokens；Gemini 接收 thinkingConfig.thinkingBudget；不支持该能力的 provider 会忽略此设置。off 会省略 provider 专用推理字段，使默认请求保留各 provider 的原生行为。

Skills 技能

xiaoO 默认从 ~/.xiaoo/skills 加载技能。每个技能都是一个由 SKILL.md 或 SKILL.toml 描述的可复用指令包。

xiaoo --cli skill list
xiaoo --cli skill show <name>
xiaoo --cli skill audit <path>
xiaoo --cli skill install ./my-skill/
xiaoo --cli skill install https://github.com/user/my-skill.git
xiaoo --cli skill remove <name>

完整技能工作流请参考 docs/skill_usage.md。

Daemon 模式

xiaoO 可以作为 daemon 运行，并为 Feishu、Telegram 或自定义服务等外部系统提供 REST API。

# 默认监听地址：0.0.0.0:18080
xiaoo-daemon

# 指定配置文件、监听地址和端口
xiaoo-daemon --config /path/to/config.toml --host 127.0.0.1 --port 18080

HTTP 请求可在 JSON body 的 entry 对象中通过 runtime_profile_id 选择 Agent 角色预设：

{
  "text": "Review this patch for security issues",
  "channel": "http",
  "sender_id": "demo-user",
  "conversation_id": "demo-conv",
  "entry": {
    "kind": "http_api",
    "runtime_profile_id": "code-reviewer"
  }
}

更多 daemon 配置请参考 docs/daemon_config.md。

更多文档

• Memory & Context Compression
• Plugin System
• Skill Usage
• Custom Agents
• Remote TUI
• Feishu Deployment
• Telegram Deployment

许可证

xiaoO 使用 MulanPSL-2.0 许可证。