Open Agent

基于 Ink + AI SDK 的终端 AI Agent 客户端（TUI）。在终端中直接与 AI 对话，AI 可以调用工具读取/写入文件、执行 Bash 命令、搜索代码、访问网页等，帮你完成开发任务。

核心能力：

• 内置工具：读写文件、执行命令、代码搜索（glob/grep）、网页搜索、文件抓取等
• @文件 补全：输入 @ 即可模糊搜索并补全项目文件路径
• 斜杠命令：/clear、/config、/theme、/locale、/update 等快捷操作
• 交互式确认：写入文件等敏感操作前弹出确认框，由你决定是否执行
• 会话管理：自动保存历史会话，随时恢复上下文继续对话
• 流式响应：实时展示 AI 的思考过程和工具调用细节
• Skill 系统：从 ~/.agents/skills 目录加载自定义 Skill，扩展 Agent 的能力
• 国际化：内置中文/英文界面，支持第三方语言扩展包
• Channel 插件：通过插件系统接入微信、Telegram 等消息平台，实现远程控制
• 自更新：/update 命令一键检查并更新到最新版本

快速开始（安装版）

# 全局安装
pnpm add -g @oagent/oa
# 或
npm install -g @oagent/oa

# 在项目目录中启动（首次运行会自动进入配置向导）
cd /path/to/your/project
oa

也可以使用环境变量临时覆盖配置（跳过配置向导）：

OPENAGENT_BASE_URL="https://api.example.com/v1" \
OPENAGENT_API_KEY="sk-..." \
OPENAGENT_MODEL="gpt-4.1" \
oa

oa 会以当前目录为工作目录，文件读写、命令执行等操作都会限制在该目录下。首次运行或配置缺失时会自动打开配置向导，引导你配置供应商和模型，保存到 ~/.openagent/config.json。支持配置多个供应商，每个供应商有独立的 baseUrl、apiKey 和 models 列表，通过 activeModel（格式 "供应商名/模型名"）指定当前使用的模型。

开发

参见 docs/development.md，包含开发环境搭建、编译、项目结构、扩展指南等内容。

快捷键

• Ctrl+O：展开/折叠工具调用详情
• Esc / Ctrl+C：停止当前流式回复
• ↑/↓：在命令面板或文件选择器中切换
• Tab：补全命令或选中文件

交互式确认

当 AI 需要执行写入文件等敏感操作时，输入区域会弹出黄色确认框，使用 ↑/↓ 选择后按 Enter 确认：

• 批准执行 — 允许该操作
• 拒绝 — 拒绝该操作

命令

• /status：查看当前工作目录和文件索引状态
• /config：打开配置选择器，编辑配置文件
• /approvals：管理工具审批偏好（execute_bash/write_file/edit_file）
• /tools：列出 Agent 可调用的内置工具
• /theme：切换主题
• /channel：管理消息渠道（start/stop/login/logout/status）
• /locale：查看当前语言或切换语言（zh/en）
• /reload：刷新 @文件 补全索引
• /cancel：停止当前正在流式生成的回复
• /sessions：列出并恢复已保存会话
• /clear：保存当前会话并开始新会话
• /update：检查并更新 oa 到最新版本
• /agents：列出所有可用的子代理
• /<agent-id> <任务>：直接调用子代理执行任务（如 /researcher 分析这段代码）
• /exit：保存会话、停止所有渠道、退出

每次 /clear 时自动保存当前会话到 ~/.openagent/sessions/<sessionId>.json，历史记录追加到 ~/.openagent/history.jsonl。

子代理系统

OA 支持子代理（Sub-Agent）系统，允许将特定任务委派给专门的代理执行。

使用方式

1. 查看可用代理：输入 /agents 查看所有已注册的子代理
2. 直接调用代理：输入 /<agent-id> <任务> 直接执行子代理
   • 示例：/researcher 分析这段代码
   • 示例：/doc-writer 更新 README.md
3. 并行执行：使用 run_agents_parallel 工具同时运行多个代理
4. 代理委派：使用 agent_handoff 工具将当前任务委派给另一个代理

配置代理

代理定义来自三个来源（按优先级）：

1. 内置代理：系统自带的基础代理
2. 项目代理：项目根目录的 AGENTS.md 文件
3. 用户配置：~/.openagent/config.json 中的 agents 数组

在 config.json 中添加自定义代理：

{
    "agents": [
        {
            "id": "doc-writer",
            "name": "文档写手",
            "description": "专门用于编写和更新文档",
            "systemPrompt": "你是一个专业的技术文档写手...",
            "allowedTools": ["readFile", "writeFile", "editFile"],
            "model": "deepseek-v3.2",
            "maxSteps": 10
        }
    ]
}

代理工具

• run_agents_parallel：并行运行多个子代理任务
• agent_handoff：将当前任务委派给指定代理

Channel 插件系统

OA 支持通过插件接入消息平台（微信、Telegram 等），实现远程与 AI 对话。

内置插件

| 插件 | 包名 | 说明 | | -------- | ------------------ | --------------------- | | 微信 | @oagent/weixin | iLink 协议接入微信 | | Telegram | @oagent/telegram | Telegram Bot API 接入 |

安装插件

# 在使用 OA 的项目目录下安装
pnpm add @oagent/weixin
# 或
pnpm add @oagent/telegram

启用插件

在 ~/.openagent/config.json 中配置 channels 字段：

{
    "providers": [...],
    "activeModel": "...",
    "channels": ["@oagent/weixin"]
}

使用

/channel                  # 查看所有 channel 状态
/channel start weixin     # 启动微信机器人
/channel stop weixin      # 停止微信机器人

启动后，收到的消息会实时显示在 TUI 中，AI 的回复也会同步发送到对应平台。

开发自定义插件请参阅 docs/development.md。

国际化

OA 内置中文和英文界面，默认为中文。使用 /locale 命令查看和切换语言：

/locale                   # 查看当前语言和可用语言列表
/locale en                # 切换到英文
/locale zh                # 切换到中文

也支持通过第三方语言扩展包添加更多语言，在 config.json 中配置：

{
    "locale": {
        "lang": "ja",
        "plugins": ["@oagent/locale-ja"]
    }
}

技术文档

完整的技术文档请参阅 docs/technical.md，包含架构总览、数据流图、工具系统详解、安全机制等内容。