斧头

一个用于管理和运行基于大语言模型的智能体的命令行工具。

为什么选择 Axe？

大多数 AI 工具都假定你想要的是一个聊天机器人——一个拥有超大上下文窗口、能够一次性完成所有任务的长时间会话。但优秀的软件并非如此运作。优秀的软件应该是小巧、专注且可组合的。

Axe 将 LLM 智能体视为 Unix 系统中的程序：每个智能体只做好一件事。你只需在 TOML 配置文件中定义它，赋予它特定的技能，并通过命令行运行即可。输入数据，输出结果；将多个智能体串联起来；或者通过 cron 作业、Git 钩子或 CI 来触发它们——无论你目前使用什么工具都可以无缝集成。无需守护进程、GUI 或任何框架束缚，只有二进制文件和你的配置。

概述

Axe 负责编排由 TOML 配置文件定义的 LLM 智能体。每个智能体都有自己的系统提示、模型选择、技能文件、上下文文件、工作目录、持久化内存，以及委托给子智能体的能力。

Axe 是执行者，而非调度器。它的设计目标是与标准的 Unix 工具（如 cron、Git 钩子、管道、文件监视器）结合使用，而不是重新发明调度或工作流编排功能。

特性

• 多提供商支持：Anthropic、OpenAI、Ollama（本地模型）、OpenCode 和 AWS Bedrock
• 基于 TOML 的智能体配置：声明式的、可版本控制的智能体定义
• 子智能体委托：智能体可以通过 LLM 工具调用其他智能体，支持深度限制和并行执行
• 持久化内存：带有时间戳的 Markdown 日志，可在多次运行之间传递上下文
• 内存垃圾回收：借助 LLM 进行模式分析和修剪
• 技能系统：可重用的指令集，可在不同智能体之间共享
• 标准输入管道：可将任何输出直接输入到智能体中（git diff | axe run reviewer）
• 本地智能体目录：优先从 <cwd>/axe/agents/ 自动发现智能体，然后再加载全局配置；也可使用 --agents-dir 指定任意路径
• 干运行模式：在不调用 LLM 的情况下检查解析后的上下文
• JSON 输出：带元数据的结构化输出，便于脚本处理
• 内置工具：文件操作（读、写、编辑、列出）被沙盒化到工作目录；执行 Shell 命令；获取 URL；网络搜索
• 输出白名单：限制 url_fetch 和 web_search 只能访问特定主机名；始终阻止私有/保留 IP 地址（防止 SSRF 攻击）
• 令牌预算：通过 [budget] 配置或 --max-tokens 标志，限制每个智能体运行时的累计令牌用量
• MCP 工具支持：可通过 SSE 或可流式传输的 HTTP 协议连接到外部 MCP 服务器以获取更多工具
• 可配置重试机制：针对临时提供商错误（429、5xx、超时）提供指数、线性和固定退避策略
• 极简依赖：仅有四个直接依赖项（cobra、toml、mcp-go-sdk、x/net）；所有 LLM 调用均使用标准库

安装

需要 Go 1.25 或更高版本。

预编译的二进制文件（无需安装 Go）适用于 Linux、macOS 和 Windows，可在 GitHub 发布页面 下载。

通过 Go 安装：

go install github.com/jrswab/axe@latest

如果出现 invalid go version 错误，说明你的 Go 工具链版本低于 1.25。请从 go.dev/dl 升级，或直接下载预编译的二进制文件。

或者从源码构建：

git clone https://github.com/jrswab/axe.git
cd axe
go build .

快速入门

初始化配置目录：

axe config init

这将在 $XDG_CONFIG_HOME/axe/ 创建目录结构，并生成一个示例技能和用于提供商凭据的默认 config.toml 文件。

搭建一个新的智能体：

axe agents init my-agent

编辑其配置：

axe agents edit my-agent

运行该智能体：

axe run my-agent

从其他工具中管道输入：

git diff --cached | axe run pr-reviewer
cat error.log | axe run log-analyzer

示例

examples/ 目录包含可直接运行的智能体，你可以将其复制到自己的配置中立即使用。其中包括代码审查员、提交信息生成器和文本摘要器——每个智能体都配有专门的 SKILL.md 文件。

# 将示例智能体复制到你的配置中
cp examples/code-reviewer/code-reviewer.toml "$(axe config path)/agents/"
cp -r examples/code-reviewer/skills/ "$(axe config path)/skills/"

# 设置 API 密钥并运行
export ANTHROPIC_API_KEY="your-key-here"
git diff | axe run code-reviewer

完整设置步骤请参阅 examples/README.md。

Docker

Axe 提供了一个 Docker 镜像，用于在隔离且加固的容器中运行智能体。

构建镜像

docker build -t axe .

支持多架构构建（linux/amd64、linux/arm64），可通过 buildx 实现：

docker buildx build --platform linux/amd64,linux/arm64 -t axe:latest .

运行智能体

挂载你的配置目录，并将 API 密钥作为环境变量传递：

docker run --rm \
  -v ./my-config:/home/axe/.config/axe \
  -e ANTHROPIC_API_KEY \
  axe run my-agent

使用 -i 标志传递标准输入：

git diff | docker run --rm -i \
  -v ./my-config:/home/axe/.config/axe \
  -e ANTHROPIC_API_KEY \
  axe run pr-reviewer

如果没有挂载配置卷，Axe 会以代码 2（配置错误）退出，因为容器内不存在任何智能体 TOML 文件。

运行单个智能体

上述示例挂载了整个配置目录。如果你只需要运行一个智能体及其一项技能，只需将这些文件挂载到容器内的预期 XDG 路径即可。当通过环境变量传递 API 密钥时，无需 config.toml 文件。

docker run --rm -i \
  -e ANTHROPIC_API_KEY \
  -v ./agents/reviewer.toml:/home/axe/.config/axe/agents/reviewer.toml:ro \
  -v ./skills/code-review/:/home/axe/.config/axe/skills/code-review/:ro \
  axe run reviewer

智能体的 skill 字段会自动解析为容器内的 XDG 配置路径，因此无需使用 --skill 标志。

如果要使用与智能体 TOML 中声明不同的技能，可以使用 --skill 标志进行覆盖。此时只需挂载替换的技能文件，而 TOML 中声明的原始技能将被完全忽略：

docker run --rm -i \
  -e ANTHROPIC_API_KEY \
  -v ./agents/reviewer.toml:/home/axe/.config/axe/agents/reviewer.toml:ro \
  -v ./alt-review.md:/home/axe/alt-review.md:ro \
  axe run reviewer --skill /home/axe/alt-review.md

如果智能体声明了 sub_agents，则必须同时挂载所有引用的智能体 TOML 文件及其对应的技能。

持久化数据

挂载数据卷后，智能体的内存会在多次运行之间保持持久化：

docker run --rm \
  -v ./my-config:/home/axe/.config/axe \
  -v axe-data:/home/axe/.local/share/axe \
  -e ANTHROPIC_API_KEY \
  axe run my-agent

Docker Compose

提供了一个 docker-compose.yml 文件，用于将 axe 与本地的 Ollama 实例一起运行。

仅云提供商（无 Ollama）：

docker compose run --rm axe run my-agent

带有 Ollama Sidecar：

docker compose --profile ollama up -d ollama
docker compose --profile cli run --rm axe run my-agent

拉取 Ollama 模型：

docker compose --profile ollama exec ollama ollama pull llama3

注意： Compose 中的 axe 服务声明了 depends_on: ollama。无论是否使用 Ollama，Docker Compose 都会在启动 axe 时尝试启动 Ollama 服务。如果仅在云端使用且不需要 Ollama，请直接使用 docker run 而不是 docker compose run。

主机上的 Ollama

如果 Ollama 直接在主机上运行（而非通过 Compose），请通过以下方式指向它：

• Linux： --add-host=host.docker.internal:host-gateway -e AXE_OLLAMA_BASE_URL=http://host.docker.internal:11434
• macOS / Windows（Docker Desktop）： -e AXE_OLLAMA_BASE_URL=http://host.docker.internal:11434

安全性

容器默认以以下强化配置运行（通过 Compose）：

• 非 root 用户 — UID 10001
• 只读根文件系统 — 可写位置为配置挂载点、数据挂载点和 /tmp/axe tmpfs
• 丢弃所有能力 — cap_drop: ALL
• 禁止权限提升 — no-new-privileges:true

这些设置不会限制出站网络访问。若要隔离仅与本地 Ollama 实例通信的代理，可添加 --network=none 并手动将其连接到共享的 Docker 网络。

卷挂载

容器路径	用途	默认访问权限
/home/axe/.config/axe/	代理 TOML 文件、技能、config.toml	读写
/home/axe/.local/share/axe/	持久化内存文件	读写

配置目录设置为读写是因为 axe config init 和 axe agents init 会向其中写入内容。如果仅运行代理，则可将其挂载为只读 (:ro)。

环境变量

变量	是否必需	用途
ANTHROPIC_API_KEY	是	使用 Anthropic 时的 API 认证
OPENAI_API_KEY	是	使用 OpenAI 时的 API 认证
AXE_OLLAMA_BASE_URL	否	使用 Ollama 时的 Ollama 端点（Compose 默认值：http://ollama:11434）
AXE_ANTHROPIC_BASE_URL	否	覆盖 Anthropic API 端点
AXE_OPENAI_BASE_URL	否	覆盖 OpenAI API 端点
AXE_OPENCODE_BASE_URL	否	覆盖 OpenCode API 端点
TAVILY_API_KEY	是	使用 web_search 时的 Tavily Web 搜索 API 密钥
AXE_WEB_SEARCH_BASE_URL	否	覆盖 Web 搜索端点

CLI 参考

命令

命令	描述
axe run <agent>	运行一个代理
axe agents list	列出所有已配置的代理
axe agents show <agent>	显示代理的完整配置
axe agents init <agent>	构建一个新的代理 TOML 文件
axe agents edit <agent>	在 $EDITOR 中打开代理 TOML
axe config path	打印配置目录路径
axe config init	使用默认值初始化配置目录
axe gc <agent>	为某个代理运行内存垃圾回收
axe gc --all	对所有启用内存的代理运行 GC
axe version	打印当前版本

运行标志

标志	默认值	描述
--model <provider/model>	来自 TOML	覆盖模型（例如 anthropic/claude-sonnet-4-20250514）
--skill <path>	来自 TOML	覆盖技能文件路径
--workdir <path>	来自 TOML 或当前目录	覆盖工作目录
--timeout <seconds>	120	请求超时时间
--max-tokens <int>	0（无限制）	限制本次运行的累计 token 使用量（超出则退出码为 4）
--dry-run	false	显示解析后的上下文，但不调用 LLM
--verbose / -v	false	将调试信息（模型、时间、token、重试次数等）输出到 stderr
--json	false	将输出包裹在包含元数据的 JSON 框架中
-p / --prompt <string>	（无）	内联提示作为用户消息；优先级高于标准输入
--agents-dir <path>	（自动发现）	超越代理搜索目录

用户消息优先级

发送给 LLM 的用户消息按以下顺序解析：

1. -p / --prompt 标志 — 如果提供了非空且非空白的值，则将其用作用户消息。
2. 管道输入 — 如果 -p 不存在或为空/仅包含空白字符，则使用管道输入。
3. 内置默认值 — 如果既没有 -p 也没有管道输入，则使用默认消息 "执行您指令中描述的任务。"。

当同时提供 -p 和管道输入时，管道输入会被静默忽略（不会发出警告）。空值或仅包含空白字符的 -p 值被视为不存在，流程会继续到管道输入，最后才是默认值。

示例：

axe run my-agent -p "总结 README"

退出码

代码	含义
0	成功
1	运行时错误
2	配置错误
3	提供商/网络错误
4	Token 预算超限

代理配置

代理以 TOML 文件的形式定义，位于 $XDG_CONFIG_HOME/axe/agents/ 目录下。

name = "pr-reviewer"
description = "评审拉取请求中的问题和改进建议"
model = "anthropic/claude-sonnet-4-20250514"
system_prompt = "你是一位资深代码评审员。请言简意赅、切中要点。"
skill = "skills/code-review/SKILL.md"
files = ["src/**/*.go", "CONTRIBUTING.md"]
workdir = "/home/user/projects/myapp"
tools = ["read_file", "list_directory", "run_command"]
sub_agents = ["test-runner", "lint-checker"]
allowed_hosts = ["api.example.com", "docs.example.com"]

[sub_agents_config]
max_depth = 3       # 最大嵌套深度（硬上限：5）
parallel = true     # 并发运行子代理
timeout = 120       # 每个子代理的超时时间（秒）

[memory]
enabled = true
last_n = 10         # 加载最近 N 条记录到上下文中
max_entries = 100   # 超过此值时发出警告

[[mcp_servers]]
name = "my-tools"
url = "https://my-mcp-server.example.com/sse"
transport = "sse"
headers = { Authorization = "Bearer ${MY_TOKEN}" }

[params]
temperature = 0.3
max_tokens = 4096

[budget]
max_tokens = 50000    # 0 表示无限制（默认值）
retry:
  max_retries = 3           # 在出现瞬时错误时最多重试 3 次
  backoff = "exponential"   # "指数"、"线性" 或 "固定"
  initial_delay_ms = 500    # 第一次重试前的基础延迟
  max_delay_ms = 30000      # 最大延迟上限

[[mcp_servers]]
name = "filesystem"
transport = "stdio"
command = "/usr/local/bin/mcp-server-filesystem"
args = ["--root", "/home/user/projects"]

除 name 和 model 外，其他字段均为可选。

重试

代理可以在出现暂时性 LLM 提供商错误时进行重试，包括速率限制（429）、服务器错误（5xx）和超时。重试功能为可选，默认情况下是禁用的。

字段	默认值	描述
max_retries	0	初始请求后的重试次数。设置为 0 表示禁用重试。
backoff	"exponential"	重试策略："exponential"（带抖动）、"linear" 或 "fixed"
initial_delay_ms	500	第一次重试前的基础延迟时间，单位为毫秒。
max_delay_ms	30000	最大延迟时间上限，单位为毫秒。

仅对暂时性错误进行重试。认证错误（401/403）和无效请求（400）绝不会被重试。当启用 --verbose 时，每次重试尝试都会记录到标准错误输出中。--json 输出包络中会包含一个 retry_attempts 字段，用于可观ability 监控。

输出白名单

使用 url_fetch 或 web_search 的代理可以通过 allowed_hosts 字段限制为特定的主机名：

allowed_hosts = ["api.example.com", "docs.example.com"]

行为	详情
空或未指定	允许所有公共主机名。
非空列表	仅允许完全匹配的主机名（不区分大小写，不支持通配符子域名）。
私有 IP 地址	无论白名单如何，私有 IP 地址始终会被阻止——包括回环地址、链路本地地址、RFC 1918 私有地址、CGNAT 和 IPv6 私有地址。
重定向	每次重定向的目标都会重新验证是否在白名单内，并检查是否为私有 IP 地址。
子代理	继承父代理的 allowed_hosts 设置，除非子代理的 TOML 文件明确设置了自身的白名单。

Token 预算

可以为单次运行限制累计的 token 使用量（输入 + 输出，跨所有回合及子代理调用）：

[budget]
max_tokens = 50000   # 0 表示无限制（默认）

也可以通过命令行参数覆盖：

axe run my-agent --max-tokens 10000

当命令行参数设置为大于零的值时，该参数优先于 TOML 配置。

当超出预算时，当前响应会被返回，但不会再执行任何工具调用。程序将以 代码 4 退出。超出预算的运行不会追加内存。

启用 --verbose 时，每一轮都会将累计使用情况记录到标准错误输出中。启用 --json 时，输出包络中会包含 budget_max_tokens、budget_used_tokens 和 budget_exceeded 字段（如果未设置限制则省略）。

工具

代理可以使用内置工具与文件系统交互并执行命令。启用工具后，代理会进入对话循环——LLM 可以调用工具、接收结果并继续推理，最多可达 50 轮。

内置工具

工具	描述
list_directory	列出工作目录相对路径下的目录内容。
read_file	读取文件内容，显示行号，并可选择分页（偏移/限制）。
write_file	创建或覆盖文件，必要时会自动创建父目录。
edit_file	在文件中查找并替换精确文本，可选择全部替换模式。
run_command	通过 sh -c 执行 shell 命令并返回合并的输出。
url_fetch	获取 URL 内容，去除 HTML 并进行截断。
web_search	在网络上搜索并返回结果。
call_agent	将任务委托给子代理（通过 sub_agents 控制，而非 tools）。

通过将工具添加到代理的 tools 字段来启用：

tools = ["read_file", "list_directory", "run_command"]

call_agent 工具并未列在 tools 中——它会在配置了 sub_agents 且未达到深度限制时自动可用。

路径安全

所有文件相关工具（list_directory、read_file、write_file、edit_file）都被沙盒化到代理的工作目录中。绝对路径、.. 跳转以及符号链接逃逸均会被拒绝。

并行执行

当 LLM 在同一轮中返回多个工具调用时，默认会并发执行。这适用于内置工具和子代理调用。可通过在 [sub_agents_config] 中设置 parallel = false 来禁用并行执行。

MCP 工具

代理可以使用来自外部 MCP 服务器的工具。在代理的 TOML 文件中使用 [[mcp_servers]] 声明服务器：

[[mcp_servers]]
name = "my-tools"
url = "https://my-mcp-server.example.com/sse"
transport = "sse"
headers = { Authorization = "Bearer ${MY_TOKEN}" }

启动时，axe 会连接到每个声明的服务器，通过 tools/list 发现可用工具，并将其与内置工具一起提供给 LLM 使用。

字段	必需	描述
name	是	服务器的人类可读标识符。
url	是	MCP 服务器的端点 URL。
transport	是	"sse" 或 "streamable-http"。
headers	否	HTTP 头部；值支持 ${ENV_VAR} 插值。

MCP 工具完全由 [[mcp_servers]] 控制——它们不会列在 tools 字段中。如果某个 MCP 工具与已启用的内置工具同名，则内置工具优先。

技能

技能是一组可重用的指令集，为代理提供特定领域的知识和工作流程。它们以社区 SKILL.md 格式定义的 SKILL.md 文件形式存在。

技能解析

代理 TOML 文件中的 skill 字段按以下顺序解析：

1. 绝对路径——直接使用（例如 /home/user/skills/SKILL.md）。 |
2. 相对于配置目录——例如 skills/code-review/SKILL.md 解析为 $XDG_CONFIG_HOME/axe/skills/code-review/SKILL.md。 |
3. 纯名称——例如 code-review 解析为 $XDG_CONFIG_HOME/axe/skills/code-review/SKILL.md。 |

脚本路径

技能通常会引用辅助脚本。由于 run_command 是在代理的工作目录中执行的（而非技能目录），因此 SKILL.md 中的脚本路径必须是绝对路径。相对路径会导致失败，因为这些脚本不存在于代理的工作目录中。

# 正确——绝对路径
/home/user/.config/axe/skills/my-skill/scripts/fetch.sh <args>

# 错误——相对路径无法从代理的工作目录解析
scripts/fetch.sh <args>

目录结构

$XDG_CONFIG_HOME/axe/
├── config.toml
├── agents/
│   └── my-agent.toml
└── skills/
    └── my-skill/
        ├── SKILL.md
        └── scripts/
            └── fetch.sh

本地代理目录

默认情况下，代理会从 $XDG_CONFIG_HOME/axe/agents/ 加载。Axe 还支持项目本地代理目录，用于每个仓库的代理定义。

自动发现

如果 <cwd>/axe/agents/ 存在，Axe 会优先搜索该项目目录，然后再搜索全局配置目录。与全局代理同名的本地代理会覆盖全局代理。

my-project/
└── axe/
    └── agents/
        └── my-agent.toml   ← 自动找到

显式覆盖

使用 --agents-dir 可以指向任意目录：

axe run my-agent --agents-dir ./custom/agents

此标志适用于所有命令：run、agents list、agents show、agents init、agents edit 和 gc。

解析顺序

1. --agents-dir（如果提供了）
2. <cwd>/axe/agents/（自动发现）
3. $XDG_CONFIG_HOME/axe/agents/（全局回退）

第一个包含匹配的 <name>.toml 文件的目录将被优先使用。

智能脚手架

axe agents init <name> 会写入 <cwd>/axe/agents/ 目录，如果该目录已存在；否则将回退到全局配置目录。

提供者

提供者	API 密钥环境变量	默认基础 URL
Anthropic	ANTHROPIC_API_KEY	https://api.anthropic.com
OpenAI	OPENAI_API_KEY	https://api.openai.com
Ollama	（无需）	http://localhost:11434
OpenCode	OPENCODE_API_KEY	可配置
AWS Bedrock	（使用 AWS 凭证）	基于区域

AWS Bedrock 配置：

• 区域：可通过 AWS_REGION 环境变量或在 config.toml 中设置 [providers.bedrock] region = "us-east-1" 来指定。
• 凭证：使用环境变量（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN）或 ~/.aws/credentials 文件（支持 AWS_PROFILE 和 AWS_SHARED_CREDENTIALS_FILE）。
• 模型 ID：需使用完整的 Bedrock 模型 ID（例如：bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0）。

基础 URL 可通过 AXE_<PROVIDER>_BASE_URL 环境变量或在 config.toml 中进行覆盖。

许可证

Apache-2.0。详情请参阅 LICENSE。

Axe 快速上手指南

Axe 是一个命令行工具，用于管理和运行由大语言模型（LLM）驱动的智能体（Agents）。它遵循 Unix 哲学，将每个智能体设计为专注单一任务的可组合程序，支持通过管道、Cron 或 Git Hooks 集成到现有工作流中。

环境准备

• 操作系统：Linux, macOS, Windows
• Go 版本：若需从源码构建，要求 Go 1.25+。
• API 密钥：根据使用的模型提供商（如 Anthropic, OpenAI, Ollama 等），需提前准备好相应的 API Key。

安装步骤

您可以选择下载预编译二进制文件或通过 Go 安装。

方式一：下载预编译二进制文件（推荐）

访问 GitHub Releases 页面 下载对应系统的最新版本，无需安装 Go 环境。

方式二：通过 Go 安装

确保已安装 Go 1.25 或更高版本，运行以下命令：

go install github.com/jrswab/axe@latest

注意：如果提示 invalid go version，请升级您的 Go 工具链或改用预编译二进制文件。

方式三：从源码构建

git clone https://github.com/jrswab/axe.git
cd axe
go build .

基本使用

1. 初始化配置

首次使用前，初始化配置目录。这将在 $XDG_CONFIG_HOME/axe/ 下创建必要的文件夹结构、示例技能文件和默认的 provider 配置文件。

axe config init

2. 创建智能体

创建一个名为 my-agent 的新智能体骨架：

axe agents init my-agent

使用默认编辑器编辑其 TOML 配置文件（定义模型、系统提示词、技能文件等）：

axe agents edit my-agent

3. 运行智能体

直接运行配置好的智能体：

axe run my-agent

4. 管道输入（核心用法）

Axe Designed to be composed with standard Unix tools. 您可以将其他命令的输出直接管道传递给智能体：

# 审查暂存的代码变更
git diff --cached | axe run pr-reviewer

# 分析日志文件
cat error.log | axe run log-analyzer

5. 设置 API 密钥

在运行前，请通过环境变量设置您的 API 密钥：

export ANTHROPIC_API_KEY="your-key-here"
# 或
export OPENAI_API_KEY="your-key-here"

进阶提示

• 查看可用命令：使用 axe agents list 查看所有已配置的智能体。
• 调试模式：添加 --dry-run 标志可在不调用 LLM 的情况下检查解析后的上下文；添加 -v 查看详细调试信息。
• 示例参考：项目自带的 examples/ 目录包含代码审查员、提交信息生成器等现成配置，可直接复制使用。