octo-agent

module

v1.15.3 Latest Latest Go to latest Published: Aug 2, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/open-octo/octo-agent

Links

Open Source Insights

README ¶

octo-agent

简体中文 · English

觉得有用的话，给 octo 点个 ⭐ 吧！

开源、单二进制、自托管的 AI Agent。 coding agent 能力对标 Claude Code；作为个人助手，它比 OpenClaw 更轻量 —— 一个 MIT 开源的 Go 二进制，无需 Node / Python / Ruby，接入任意模型（DeepSeek、Kimi、Anthropic、OpenAI 或任何兼容端点），服务和数据都留在你自己的机器上。

curl -fsSL https://octo-agent.dev/install.sh | sh     # 单二进制，无需 Node / Ruby / Python 环境
octo config                                            # 选 provider，填 key（DeepSeek / Kimi / 百炼 …）
octo "给 octo config show 加一个 --json 参数并跑测试"   # 一句话 → 完整 agentic 工具循环

安装

Linux / macOS — curl -fsSL https://octo-agent.dev/install.sh | sh
Windows — irm https://octo-agent.dev/install.ps1 | iex
国内网络 — 官网或 GitHub 打不开时，走下载镜像（安装与 octo upgrade 会自动回退到镜像）： curl -fsSL https://dl.octo-agent.dev/install.sh | sh（Windows：irm https://dl.octo-agent.dev/install.ps1 | iex）
桌面应用 — 从最新 release下载安装器： octo-setup.pkg（macOS）、octo-setup.exe（Windows）、Octo-x86_64.AppImage（Linux）
Go — go install github.com/open-octo/octo-agent/cmd/octo@latest

随时用 octo upgrade 升级。各平台细节 —— Gatekeeper / SmartScreen 提示、卸载、从源码构建 —— 见安装指南。安装器暂未做代码签名，完整说明与哈希校验方式见 SECURITY.md。

快速上手

octo config                # 一次性设置：选 provider/model，填 API key
octo "介绍一下这个仓库"      # headless 单发：prompt → agentic 工具循环 → 退出
octo                       # 终端交互式 TUI；octo -c 恢复历史 session
octo serve -d              # Web UI + IM 桥接，http://127.0.0.1:8088

内置工具（shell、文件读写改、搜索）、MCP 服务、skills 全部默认开启，一条消息就能真正干活。下一步：快速上手 · 选择 provider · CLI 参考。

为什么用 octo

octo 不是又一个需要“养”的 agent 框架。它的定位更接近 Codex / WorkBuddy： 下载即用、用户友好，同时把模型选择权、数据所有权和运行环境牢牢留在你手里。

1. 开箱即用，不用“养”

OpenClaw、Hermes 这类项目往往需要你调环境、写规则、配技能才能让 agent 跑顺。 octo 默认就把 shell、文件读写改、搜索、MCP、skills、子代理等能力全部打开，装完一条消息就能真正开始干活。

2. 原生支持所有主流模型，缓存不劣化

DeepSeek、Kimi、Qwen、Anthropic、OpenAI，或任何兼容 OpenAI / Anthropic 协议的端点，octo 都是原生支持。针对国产模型逐家做了提示词缓存优化，Kimi、DeepSeek、 Qwen 的缓存命中率都能到 95% 以上；不会像某些方案把 Claude Code 接在国产模型前面时，因缓存配置不当导致命中率崩塌、token 账单暴涨。

3. 八种界面，随处可用

CLI / TUI —— 终端交互与 headless 单发
Web UI —— octo serve 本地仪表盘
桌面应用 —— macOS / Windows / Linux 原生窗口 + 托盘
IM 桥接 —— 微信 iLink、飞书、钉钉、企业微信、Discord、Telegram
VS Code 插件 —— open-octo/octo-vscode
Obsidian 插件 —— open-octo/octo-obsidian
Go SDK —— pkg/octoagent，把 agent 循环嵌进你自己的程序
移动端 —— iOS + Android 开发者预览（mobile/）

很少有其他 agent 项目能同时覆盖这么多入口。

4. 极简内核：单个 ~40 MB 的 Go 二进制

一条命令下载，拷到任何服务器都能立即运行。没有 Node / Python / Ruby 依赖树，没有 npm 镜像、node-gyp 编译失败、依赖版本冲突的烦恼。

5. 零遥测

除了你自己配置的模型 API 调用，octo 自身不会向外发送任何请求。不收集 IP、机型、模型选择、使用行为——没有任何遥测埋点。

6. 桌面安装包也只有 100 MB 左右

基于“单二进制 + 零遥测”这两点，octo 的桌面安装包约为 100 MB。相比之下， Codex 桌面版和 WorkBuddy 动辄 1 GB 上下。一个薄薄的 agent harness，没必要占用那么大的空间。

7. 稳定且安全：不会把自己改挂，也不会发疯删数据

terminal 工具直接拒绝任何打向 octo 自身进程的 kill / pkill / killall （连 kill $(pgrep octo) 这种拐弯变体也认得）。
restart_server 在默认权限规则里被写死为“必须询问”，网页弹确认框、IM 里要你明确回复同意才执行；即便同意，也是优雅热重启——先把当前这轮跑完、回复送到你手上，supervisor 再拉起新进程，客户端自动重连。
所有删除命令都过校验，rm -rf /、rm -rf ~ 这类毁灭性命令被硬编码拒绝，连自定义权限规则也放不开；普通文件删除和 write_file / edit_file 覆盖前会先备份到回收站（默认保留 14 天、上限 10 GiB），误删永远找得回来。

8. 同时做到以上所有的，只有 octo

单看每一点，或许都有其他产品能覆盖其中一两项。但能同时满足“开箱即用 + 原生多模型 + 八界面 + 单二进制 + 零遥测 + 小体积 + 高稳定性 + 强安全”的，只有 octo。

9. 最后的建议

如果你能合法稳定地使用 Codex / Claude 订阅，请继续用它们——它们依旧是这个星球上最顶级的 agent harness。否则，octo 值得你认真看一看。

界面

稳定版（1.0） 已覆盖 CLI、Web UI、桌面端、IM 桥接、VS Code / Obsidian 插件、Go SDK；第八个界面——移动端 App（iOS + Android）——已实现，目前是开发者预览：现在即可从源码自建、配合自托管 relay 使用（见 mobile/），托管 relay 与应用商店版本在路上。

哪些接口可以放心依赖见 COMPATIBILITY.md；安全边界见 SECURITY.md。

深入了解

完整文档在 octo-agent.dev/docs：

Skills —— 兼容 Claude Code 的 SKILL.md；软链 ~/.claude/skills 直接复用现有技能
沙箱与回收站 —— OS 强制隔离（Seatbelt / Landlock），外加文件级回收站，agent 的删除和覆盖都先备份
MCP 服务 —— stdio + HTTP、OAuth，以及面向大工具集的 Tool Search
记忆 · 子代理 · 工作流 —— 持久化与多代理编排
浏览器自动化 —— CDP 录制 / 回放 / 自愈
IM 渠道 —— 把 octo 接进你的聊天 App
配置 · 权限 · 工具
架构 —— 分层设计、provider 协议、如何扩展

社区与交流

Bug / 功能建议 —— GitHub Issues
使用问题 / 讨论 —— GitHub Discussions，公开可沉淀，后来的同学能搜到答案
微信交流群 —— 扫码进群，聊使用心得、提需求、围观 roadmap。群二维码 7 天有效、到期会更新；扫不进的话到 Discussions 喊一声：

octo-agent 微信交流群二维码

开发

make build         # ./octo
make test          # go test -race ./...

项目约定见 CLAUDE.md 与 .octorules；PR 流程见 CONTRIBUTING.md。

致谢与前人工作

octo 站在两个项目的肩膀上，这点不遮掩：Claude Code —— agent 循环、工具集、SKILL.md 格式和整体 harness 行为塑造了 octo 的内部设计； OpenClacky —— octo 的 UI 与交互设计有很大一部分受它启发。有 bug 或者设计得不好的地方，都算 octo 自己的。

贡献者

感谢每一位为 octo 做出贡献的人：

许可

MIT。见 LICENSE.txt。

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
octo command Command octo is the Go implementation of the Octo AI agent.	Command octo is the Go implementation of the Octo AI agent.
octo-eval command Command octo-eval runs a lightweight, Docker-free eval suite against octo.	Command octo-eval runs a lightweight, Docker-free eval suite against octo.
examples
octoagent-minimal command Command octoagent-minimal demonstrates using pkg/octoagent as a library from an external Go module.	Command octoagent-minimal demonstrates using pkg/octoagent as a library from an external Go module.
internal
agent Package agent implements the Octo agent core: messages, history, and the run loop that ties an LLM provider to user input.	Package agent implements the Octo agent core: messages, history, and the run loop that ties an LLM provider to user input.
agentprofile Package agentprofile defines octo's agent profiles — the single schema for an agent's capability definition (system prompt, model, tool whitelist, skills) plus the platform slice (mention aliases, channel bindings) used when a profile is addressed directly by users.	Package agentprofile defines octo's agent profiles — the single schema for an agent's capability definition (system prompt, model, tool whitelist, skills) plus the platform slice (mention aliases, channel bindings) used when a profile is addressed directly by users.
app Package app defines the provider-vendor registry and protocol mapping.	Package app defines the provider-vendor registry and protocol mapping.
audit Package audit writes an append-only log of security-relevant tool decisions.	Package audit writes an append-only log of security-relevant tool decisions.
browser Package browser is octo's owned, in-binary browser automation backend.	Package browser is octo's owned, in-binary browser automation backend.
channel Package channel provides IM platform bridging for octo-agent.	Package channel provides IM platform bridging for octo-agent.
channel/adapters/dingtalk Package dingtalk implements the DingTalk (钉钉) Stream Mode adapter.	Package dingtalk implements the DingTalk (钉钉) Stream Mode adapter.
channel/adapters/discord Package discord implements the Discord bot adapter.	Package discord implements the Discord bot adapter.
channel/adapters/feishu Package feishu implements the Feishu (飞书) adapter.	Package feishu implements the Feishu (飞书) adapter.
channel/adapters/telegram Package telegram implements the Telegram Bot API adapter.	Package telegram implements the Telegram Bot API adapter.
channel/adapters/wecom Package wecom implements the WeCom (Enterprise WeChat) intelligent-robot adapter.	Package wecom implements the WeCom (Enterprise WeChat) intelligent-robot adapter.
channel/adapters/weixin Package weixin implements the Weixin (微信) iLink adapter.	Package weixin implements the Weixin (微信) iLink adapter.
channel/adapters/weixin/ilink Package ilink implements the WeChat iLink Bot HTTP protocol.	Package ilink implements the WeChat iLink Bot HTTP protocol.
config Package config holds the user's persisted CLI defaults at ~/.octo/config.yml — a list of named model configurations plus global settings, so a fresh `octo` works without re-typing flags or re-exporting env vars every session.	Package config holds the user's persisted CLI defaults at ~/.octo/config.yml — a list of named model configurations plus global settings, so a fresh `octo` works without re-typing flags or re-exporting env vars every session.
eval Package eval is a lightweight, Docker-free task harness for measuring whether a prompt, tool, or model change made octo better or worse at real edits.	Package eval is a lightweight, Docker-free task harness for measuring whether a prompt, tool, or model change made octo better or worse at real edits.
executil
hooks Package hooks implements C9 Phase 3 turn-boundary hooks.	Package hooks implements C9 Phase 3 turn-boundary hooks.
logfile Package logfile provides a size-bounded, self-rotating log file for the backends that write ~/.octo/serve.log directly with no service manager in front of them: the desktop hub (in-process) and `octo serve -d`.	Package logfile provides a size-bounded, self-rotating log file for the backends that write ~/.octo/serve.log directly with no service manager in front of them: the desktop hub (in-process) and `octo serve -d`.
mcp Package mcp implements a Model Context Protocol client for octo.	Package mcp implements a Model Context Protocol client for octo.
memory Package memory implements octo's cross-session memory as plain markdown files the agent manages with its own file tools — the Claude Code model.	Package memory implements octo's cross-session memory as plain markdown files the agent manages with its own file tools — the Claude Code model.
memorybackend Package memorybackend adapts octo to optional, user-configured external semantic memory services (hindsight, mem0, agentmemory).	Package memorybackend adapts octo to optional, user-configured external semantic memory services (hindsight, mem0, agentmemory).
permission Package permission gates tool calls through a rule-driven decision engine.	Package permission gates tool calls through a rule-driven decision engine.
prompt Package prompt assembles the agent's system prompt from layered sources.	Package prompt assembles the agent's system prompt from layered sources.
provider Package provider defines the contract every LLM backend implements.	Package provider defines the contract every LLM backend implements.
provider/anthropic Package anthropic implements the provider.Provider interface against Anthropic's native Messages API (POST /v1/messages).	Package anthropic implements the provider.Provider interface against Anthropic's native Messages API (POST /v1/messages).
provider/openai Package openai implements provider.Provider against OpenAI's Chat Completions API (POST /v1/chat/completions).	Package openai implements provider.Provider against OpenAI's Chat Completions API (POST /v1/chat/completions).
provider/retry Package retry adds bounded exponential-backoff retries to provider HTTP calls for transient failures — request timeouts, rate limits (429), the 5xx family, Anthropic's 529 "overloaded", and transient network errors — while honoring a server-supplied Retry-After header.	Package retry adds bounded exponential-backoff retries to provider HTTP calls for transient failures — request timeouts, rate limits (429), the 5xx family, Anthropic's 529 "overloaded", and transient network errors — while honoring a server-supplied Retry-After header.
sandbox Package sandbox confines an arbitrary shell command to an OS-enforced filesystem and network boundary — defense-in-depth beneath the permission engine (internal/permission), which only gates command strings.	Package sandbox confines an arbitrary shell command to an OS-enforced filesystem and network boundary — defense-in-depth beneath the permission engine (internal/permission), which only gates command strings.
scheduler Package scheduler provides a simple cron-based task scheduler for octo.	Package scheduler provides a simple cron-based task scheduler for octo.
serveenv Package serveenv loads ~/.octo/serve.env (if it exists) into the process environment at startup.	Package serveenv loads ~/.octo/serve.env (if it exists) into the process environment at startup.
serveproc Package serveproc holds the pid-file + process primitives that coordinate a single octo backend on a machine.	Package serveproc holds the pid-file + process primitives that coordinate a single octo backend on a machine.
server Package server provides the HTTP server for octo's REST API and Web UI.	Package server provides the HTTP server for octo's REST API and Web UI.
shellpath
skills Package skills discovers Claude Code-compatible skills from disk and exposes them to the agent in two layers: a one-line manifest injected into the session-start system prompt (see RenderManifest), and full SKILL.md bodies loaded on demand through the `skill` tool.	Package skills discovers Claude Code-compatible skills from disk and exposes them to the agent in two layers: a one-line manifest injected into the session-start system prompt (see RenderManifest), and full SKILL.md bodies loaded on demand through the `skill` tool.
tasks Package tasks implements a session-scoped task tracker.	Package tasks implements a session-scoped task tracker.
tools Package tools provides built-in tool implementations for the octo agentic loop.	Package tools provides built-in tool implementations for the octo agentic loop.
tools/rgembed Package rgembed provides a bundled ripgrep (rg) binary for the current platform.	Package rgembed provides a bundled ripgrep (rg) binary for the current platform.
trash Package trash provides a file-level trash (recycle bin) for octo.	Package trash provides a file-level trash (recycle bin) for octo.
tui Package tui renders agent tool events as visual cards for the terminal REPL.	Package tui renders agent tool events as visual cards for the terminal REPL.
tunnel Package tunnel implements the host side of the managed tunnel: the goroutine that dials octo's relay, runs a Noise session per paired device, and bridges each device's decrypted traffic to the local server's loopback /ws as an ordinary key-authenticated client.	Package tunnel implements the host side of the managed tunnel: the goroutine that dials octo's relay, runs a Noise session per paired device, and bridges each device's decrypted traffic to the local server's loopback /ws as an ordinary key-authenticated client.
upgrade Package upgrade replaces the running octo binary with the latest GitHub release: resolve the latest version from the releases/latest redirect, download the platform archive plus checksums.txt, verify the archive's SHA-256, extract the binary, and atomically swap it into place.	Package upgrade replaces the running octo binary with the latest GitHub release: resolve the latest version from the releases/latest redirect, download the platform archive plus checksums.txt, verify the archive's SHA-256, extract the binary, and atomically swap it into place.
version Package version holds the build-time version metadata for the octo binary.	Package version holds the build-time version metadata for the octo binary.
workflow Package workflow runs a Ruby (mruby) DSL for deterministic agent orchestration.	Package workflow runs a Ruby (mruby) DSL for deterministic agent orchestration.
pkg
octoagent Package octoagent exports the public Go API for building agentic applications on top of octo-agent's core loop without importing internal packages.	Package octoagent exports the public Go API for building agentic applications on top of octo-agent's core loop without importing internal packages.
octoagent/approval Package approval provides small adapters for implementing a PermissionGate without importing internal packages.	Package approval provides small adapters for implementing a PermissionGate without importing internal packages.
octoagent/hooks Package hooks aliases octo-agent's lifecycle hook engine so external consumers of pkg/octoagent can configure Agent.Hooks without importing internal packages.	Package hooks aliases octo-agent's lifecycle hook engine so external consumers of pkg/octoagent can configure Agent.Hooks without importing internal packages.
octoagent/provider Package provider aliases octo-agent's provider-client construction so external consumers can build a Sender from plain values without touching ~/.octo/config.yml or any other local file.	Package provider aliases octo-agent's provider-client construction so external consumers can build a Sender from plain values without touching ~/.octo/config.yml or any other local file.
octoagent/toolenv Package toolenv wires a concurrency-safe, session-scoped tool environment for external consumers of pkg/octoagent.	Package toolenv wires a concurrency-safe, session-scoped tool environment for external consumers of pkg/octoagent.