octo-agent

module

v1.13.1 Latest Latest Go to latest Published: Jul 25, 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

开源、单二进制、自托管的 AI Agent。 coding 能力对标 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
桌面应用 — 从最新 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；它是同一个想法的开源、可自托管、不绑厂商 版本 —— 而且是有主张的那种，Rails 风格：约定优于配置，omakase 默认值优于无限选项。

	octo-agent	Claude Code
授权 / 成本	MIT 开源，免费，自托管	专有，多数场景需 Claude 订阅
运行时	单个自包含 Go 二进制	原生安装，绑定 Anthropic 账户
模型	双协议原生 + 任意兼容端点（DeepSeek/Kimi/百炼/OpenRouter/vLLM）	以 Anthropic 为主
部署 / 数据	完全自托管，服务与数据都在你手里	多数场景由 Anthropic 托管
技能	SKILL.md 格式相同，复用 Claude Code 技能	原生（skills 的发源地）

在个人助手这条线上，OpenClaw 是最接近的同类。octo 覆盖同一块地盘 —— 自托管、MIT、在你已经在用的聊天 App 里找到你 —— 但它是单个静态二进制而不是带依赖树的 Node.js 应用，且自带完整的 coding agent 核心。

作者的心里话

上面讲的是 octo「是什么」，这一节讲「为什么」—— 为什么我觉得它值得你花十分钟装一个，特别是如果你在国内。

好的 agent 体验不该被环境挡住。 我自己是 Claude Code 的重度用户，它是目前最好的 coding agent。但在国内想用上它，要先跨过三道和技术无关的坎：订阅费（每月 $20 到 $200）、支付方式（需要一张外币卡）、网络。很多人被挡在这三道坎外面，而不是败在「会不会用 agent」上。octo 做的事说穿了就一件：把同样的工作方式，带给跨不过这三道坎的人。

国产模型真的够用了。 DeepSeek、Kimi、Qwen 这两年的进步是实打实的。而模型只是一半，另一半是 harness —— 工具循环、权限门控、skills、记忆、子代理。把国产模型接进一个认真做的 harness 里，日常编码任务的完成度和订阅制大厂 agent 已经没有体感上的鸿沟，但价格便宜一到两个数量级，人民币直接充值。octo 对这些模型是一等公民支持：Anthropic 和 OpenAI 双协议都是原生实现，不是「兼容模式」凑合。

已经在用 cc-switch 接国产模型？ 这是个流行的路子，但有两个绕不开的短板： Claude Code 的提示词缓存是围绕 Anthropic 官方端点调的，第三方模型接进去命中率并不理想 —— 而缓存命中率直接决定你的 token 账单；web_search、tool_search 这类依赖 Anthropic 服务端的能力，切到第三方端点后就用不了了。octo 把这两件事都在自己这一侧做实了：针对几大国产模型逐家做了缓存优化，实测 Kimi、DeepSeek、Qwen 的缓存命中率都能到 95% 以上，实打实地省钱；web_search 和 tool_search 是 octo 内置实现，开箱即用，不挑模型。

你的数据只经过你自己的机器。 octo 没有云端、没有账号体系，代码里没有任何遥测埋点 —— 对外的网络请求只有两类：你自己配置的模型 API，和检查更新时访问 GitHub。对在公司内网干活、代码不能离开内网的人，这不是加分项，是先决条件。

微信、飞书、钉钉里的 agent。 海外的 agent 产品永远不会认真支持国内的 IM 生态。octo 把 IM 桥接当核心功能做：微信 iLink、飞书、钉钉、企业微信开箱即用。在工位上布置任务，通勤路上用手机跟进，到家活已经干完了。

在外面聊得好好的，agent 把自己整没了。 这是我以前玩 OpenClaw 和 Hermes 时最破防的场景：人在外面，用微信跟 agent 聊一个功能怎么实现，聊得正顺，它突然自作主张改了代码、顺手重启服务 —— 然后，就没有然后了。它把自己搞挂了，我只能干等到晚上回家把它救活。octo 对这个场景做了专门设防：terminal 工具直接拒绝任何打向 octo 自身进程的 kill / pkill / killall（连 kill $(pgrep octo) 这种拐弯的变体也认得）；重启只有一条路 —— 专门的 restart_server 工具，而它在默认权限规则里被写死为「必须询问」，网页上弹确认框、IM 里要你明确回复同意才执行；即便你同意了，重启也是优雅的：先把当前这轮跑完、回复送到你手上，supervisor 再拉起新进程，客户端自动重连。你在外面，永远不会再对着一个突然沉默的聊天窗口干瞪眼。

你见过 agent 发疯吗？ 模型越来越强，但本质仍是概率模型。也许你也遇到过这样的失控现场：它突然认定「环境坏了」「刚才写的全错了」「系统被入侵了」「这个文件是病毒」—— 然后它真的动手了，rm 下去，你一整天的工作成果没了，再也找不回来。octo 不会让这一幕发生：所有经 octo 发出的删除命令都要过校验， rm -rf /、rm -rf ~ 这类毁灭性命令被硬编码拒绝 —— 硬到连你自己改权限规则都放不开；删普通文件，先把目标备份进回收站再执行；write_file / edit_file 覆盖旧文件，同样先存底。回收站默认保留 14 天、上限 10 GiB，在这个范围内，被误删的文件永远找得回来。

单二进制在国内的含金量。 不需要 Node / Python / Ruby 环境，意味着 npm 镜像、 node-gyp 编译失败、依赖版本冲突这些事从根上就不存在。一个二进制文件，拷到任何机器上就能跑 —— 包括不能上外网的内网机器。

紧跟前沿，但不照单全收。 开源平替常见的宿命是慢半拍，octo 不是。今年 6 月 Claude Code 推出 dynamic workflows（模型自己写编排脚本、扇出子代理协同干活）， Codex 推出 record & replay（演示一遍操作、录成可复用的技能），这两个高阶能力 octo 都有，而且结合自己的内置工具做了取舍：dynamic workflow 的官方玩法动辄几十上百个并行子代理，跑起来壮观，token 账单也壮观 —— octo 把单个 workflow 的并行扇出限制在 8 个，多出来的排队等空位，任务照样全部跑完，账单不会失控； Codex 的 record & replay 只在 macOS 应用里提供，octo 的浏览器录制回放（带页面改版后的自愈）对 Windows 和 Linux 一视同仁。

最后一句实话：如果你已经有 Claude 订阅而且用得顺手，请继续用 Claude Code，它配得上它的价格。octo 适合的是另外一群人 —— 订阅对你太贵、支付和网络够不着、数据不能出机器，或者单纯想把整套工具攥在自己手里。两边的 SKILL.md 格式互通，你甚至可以白天用 Claude Code 干重活，日常杂事交给跑着 DeepSeek 的 octo。

界面

稳定版（1.0）。 规划了八个界面 —— 正好对上章鱼的八条腕 —— 其中七个已上线：

CLI —— 终端里是交互式 TUI，其余场景是 headless 单发
Web UI —— octo serve，基于 REST + WebSocket 的本地仪表盘
桌面应用 —— 原生窗口 + 系统托盘（macOS / Windows / Linux）
IM 桥接 —— 微信 iLink、飞书、钉钉、企微、Discord、Telegram，随 octo serve 运行
VS Code 插件 —— open-octo/octo-vscode
Obsidian 插件 —— open-octo/octo-obsidian
Go SDK —— pkg/octoagent，把 agent 循环嵌进你自己的程序

第八个界面——移动端 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 协议、如何扩展

开发

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).
pathutil Package pathutil holds small filesystem path helpers shared across packages that need to compare directories without being fooled by symlinks.	Package pathutil holds small filesystem path helpers shared across packages that need to compare directories without being fooled by symlinks.
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.