Axe CLI 工具指南

博主： admin
发布时间：2026 年 03 月 13 日
5 次浏览
暂无评论
5151字数
分类： Docker 人工智能 go 技术文档

# Axe CLI 工具指南

# 一、概述

## 1. 简介
### A. 是什么
Axe 是一个轻量级的命令行工具，用于运行单用途的 AI 代理。它使用 TOML 配置文件定义代理行为，支持多个 AI 提供商，包括 Anthropic、OpenAI 和 Ollama（本地模型）。

### B. 为什么学
- 简化 AI 代理的创建和部署流程
- 支持代码版本控制和团队协作
- 提供持久化内存和技能系统
- 支持 MCP（Model Context Protocol）工具扩展

### C. 学完能做什么
- 使用 TOML 文件定义和管理 AI 代理
- 配置多提供商支持
- 实现代理间的委托调用
- 使用 Docker 容器化部署
- 集成外部 MCP 工具

## 2. 前置知识
### A. 必备技能
- 基本 Linux 命令行操作
- 了解 TOML 配置文件格式
- 熟悉 Git 版本控制

### B. 推荐知识
- Docker 容器基础概念
- AI API 使用经验
- MCP 协议基础

# 二、环境准备

## 1. 系统要求
- Linux、macOS 或 Windows
- Go 1.21+（源码编译）
- Docker（可选，用于容器化部署）

## 2. 安装步骤

使用 Homebrew 安装（推荐）：
```bash
brew install jrswab/tap/axe
```

使用 Go 安装：
```bash
go install github.com/jrswab/axe@latest
```

Docker 方式：
```bash
docker pull ghcr.io/jrswab/axe:latest
```

## 3. 验证安装
```bash
axe --version
axe --help
```

# 三、核心概念

## 1. 基本术语
- Agent（代理）：AI 实体，执行特定任务
- Skill（技能）：可复用的指令集
- Memory（内存）：持久化的对话历史
- MCP：Model Context Protocol，工具扩展协议
- Provider（提供商）：AI 模型服务提供商

## 2. 工作原理

```mermaid
graph TB
 subgraph "配置层"
 A[agents/*.toml 代理定义]
 B[skills/SKILL.md 技能指令]
 C[config.toml 凭证配置]
 end

subgraph "执行层 - Axe CLI"
        D[运行命令解析]
        E[上下文构建]
        F[工具调用]
    end

subgraph "提供商层"
 G[Anthropic API]
 H[OpenAI API]
 I[Ollama 本地模型]
 end

subgraph "存储层"
 J[持久化内存 timestamped logs]
 K[工作目录 sandboxed]
 end

A --> D
    B --> E
    C --> D
    D --> E
    E --> F
    F --> G
    F --> H
    F --> I
    F --> K
    J --> E

L[stdin 管道输入] --> D
    M[cron/git hooks] --> D
```

![Axe CLI 架构](https://static.op123.ren/static/95/95c1a7918aacda54.svg)

## 3. 配置目录结构
默认配置目录为 `$XDG_CONFIG_HOME/axe/`，通常为：
- Linux：`~/.config/axe/`
- macOS：`~/Library/Application Support/axe/`

目录结构：
```
~/.config/axe/
├── agents/
│   └── *.toml       # 代理定义文件
├── skills/
│   └── SKILL.md     # 技能指令文件
├── config.toml      # 凭证配置
└── memory/          # 持久化内存日志
```

# 四、快速上手

## 1. Hello World 示例

首先创建配置文件 `~/.config/axe/config.toml`：
```toml
[anthropic]
api_key = "your_anthropic_api_key"
```

创建代理定义 `~/.config/axe/agents/greeting.toml`：
```toml
name = "greeting"
model = "claude-3-haiku-20240307"
provider = "anthropic"

[system]
prompt = "你是一个友好的助手，用中文回答问题。"

[max_tokens]
input = 10000
output = 4096
```

运行代理：
```bash
axe run greeting "你好，请介绍一下自己"
```

## 2. 核心功能演示

管道输入支持：
```bash
echo "解释这个代码的作用" | axe run coder < main.py
```

Git hook 集成：
```bash
axe hook install pre-commit
axe hook list
axe hook remove pre-commit
```

列出可用代理：
```bash
axe list
```

## 3. 代码讲解

代理定义说明：
- `name`：代理标识符，用于 `axe run` 命令
- `model`：使用的基础模型名称
- `provider`：AI 提供商（anthropic、openai、ollama）
- `system.prompt`：系统提示词
- `max_tokens`：输入输出 token 限制

# 五、进阶内容

## 1. 常用功能

### 子代理委托

代理可以调用其他代理，通过深度限制防止无限循环：

```toml
name = "analyst"
model = "claude-3-haiku-20240307"
provider = "anthropic"

[delegates]
max_depth = 3
allow = ["coder", "researcher"]
```

### 技能系统

创建可复用的技能指令 `~/.config/axe/skills/coder/SKILL.md`：
```markdown
# 代码审查技能

你是一位资深代码审查专家。审查时请：
1. 检查代码风格一致性
2. 识别潜在 bug
3. 建议性能优化
4. 评估安全性

输出格式：
- 问题清单
- 改进建议
- 优先级标注
```

在代理中使用技能：
```toml
[skills]
include = ["coder", "researcher"]
```

### 持久化内存

Axe 自动维护时间戳标记的内存日志，支持垃圾回收：

```toml
[memory]
enabled = true
max_age = "30d"  # 30 天后自动清理
max_size = "1GB"  # 最大存储限制
```

### MCP 工具集成

配置 MCP 服务器连接：

```toml
[mcp]
[[mcp.servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

[[mcp.servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "your_github_token" }
```

## 2. 最佳实践

- 使用版本控制管理代理配置
- 为不同环境创建不同的代理
- 限制代理调用深度避免无限循环
- 定期清理内存日志
- 使用环境变量存储敏感信息

## 3. 性能优化

- 选择合适的模型平衡速度和质量
- 使用本地 Ollama 模型减少延迟
- 限制输入 token 大小
- 缓存常用查询结果

# 六、Docker 部署

## 1. 场景描述
将 Axe 容器化部署，确保环境隔离和可移植性。

## 2. 实现步骤

拉取镜像：
```bash
docker pull ghcr.io/jrswab/axe:latest
```

创建 Dockerfile 自定义构建：
```dockerfile
FROM ghcr.io/jrswab/axe:latest

# 添加自定义配置
COPY config.toml /app/config.toml
COPY agents/ /app/agents/
COPY skills/ /app/skills/

# 运行
ENTRYPOINT ["/app/axe"]
```

运行容器：
```bash
docker run -it \
  -v ~/.config/axe:/app/config \
  ghcr.io/jrswab/axe:latest \
  run greeting "你好"
```

使用 Docker Compose 编排：
```yaml
version: '3.8'
services:
  axe:
    image: ghcr.io/jrswab/axe:latest
    volumes:
      - ./config:/app/config
      - ./agents:/app/agents
      - ./skills:/app/skills
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    command: ["run", "coder", "review my code"]
```

## 3. 安全加固

- 使用只读挂载
- 限制容器资源
- 使用非 root 用户运行
- 定期更新镜像

# 七、常见问题

## 1. 安装问题

问题：Homebrew 无法安装
解决：使用 Go 安装或 Docker 方式

```bash
go install github.com/jrswab/axe@latest
export PATH=$PATH:$(go env GOPATH)/bin
```

## 2. 配置问题

问题：API 密钥验证失败
解决：检查 config.toml 格式和密钥有效性

```toml
[anthropic]
api_key = "sk-ant-xxx"

[openai]
api_key = "sk-xxx"

[ollama]
base_url = "http://localhost:11434"
```

## 3. 运行问题

问题：代理响应超时
解决：调整超时设置或使用更快的模型

```toml
[timeout]
request = "60s"
connect = "10s"
```

# 八、参考资料

***

## 参考资料

1. [Axe CLI GitHub Repository](https://github.com/jrswab/axe)
2. [Axe Documentation](https://github.com/jrswab/axe/blob/main/README.md)

最后修改：2026 年 03 月 13 日

如果觉得我的文章对你有用，请随意赞赏

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

评论 *

私密评论

名称 *

🎲

邮箱 *

地址

Axe CLI 工具指南

admin • 2026 年 03 月 13 日

# Axe CLI 工具指南

# 一、概述

### B. 为什么学
- 简化 AI 代理的创建和部署流程
- 支持代码版本控制和团队协作
- 提供持久化内存和技能系统
- 支持 MCP（Model Context Protocol）工具扩展

### C. 学完能做什么
- 使用 TOML 文件定义和管理 AI 代理
- 配置多提供商支持
- 实现代理间的委托调用
- 使用 Docker 容器化部署
- 集成外部 MCP 工具

## 2. 前置知识
### A. 必备技能
- 基本 Linux 命令行操作
- 了解 TOML 配置文件格式
- 熟悉 Git 版本控制

### B. 推荐知识
- Docker 容器基础概念
- AI API 使用经验
- MCP 协议基础

# 二、环境准备

## 1. 系统要求
- Linux、macOS 或 Windows
- Go 1.21+（源码编译）
- Docker（可选，用于容器化部署）

## 2. 安装步骤

使用 Homebrew 安装（推荐）：
```bash
brew install jrswab/tap/axe
```

使用 Go 安装：
```bash
go install github.com/jrswab/axe@latest
```

Docker 方式：
```bash
docker pull ghcr.io/jrswab/axe:latest
```

## 3. 验证安装
```bash
axe --version
axe --help
```

# 三、核心概念

## 2. 工作原理

```mermaid
graph TB
 subgraph "配置层"
 A[agents/*.toml 代理定义]
 B[skills/SKILL.md 技能指令]
 C[config.toml 凭证配置]
 end

subgraph "执行层 - Axe CLI"
        D[运行命令解析]
        E[上下文构建]
        F[工具调用]
    end

subgraph "提供商层"
 G[Anthropic API]
 H[OpenAI API]
 I[Ollama 本地模型]
 end

subgraph "存储层"
 J[持久化内存 timestamped logs]
 K[工作目录 sandboxed]
 end

A --> D
    B --> E
    C --> D
    D --> E
    E --> F
    F --> G
    F --> H
    F --> I
    F --> K
    J --> E

L[stdin 管道输入] --> D
    M[cron/git hooks] --> D
```

![Axe CLI 架构](https://static.op123.ren/static/95/95c1a7918aacda54.svg)

## 3. 配置目录结构
默认配置目录为 `$XDG_CONFIG_HOME/axe/`，通常为：
- Linux：`~/.config/axe/`
- macOS：`~/Library/Application Support/axe/`

# 四、快速上手

## 1. Hello World 示例

首先创建配置文件 `~/.config/axe/config.toml`：
```toml
[anthropic]
api_key = "your_anthropic_api_key"
```

创建代理定义 `~/.config/axe/agents/greeting.toml`：
```toml
name = "greeting"
model = "claude-3-haiku-20240307"
provider = "anthropic"

[system]
prompt = "你是一个友好的助手，用中文回答问题。"

[max_tokens]
input = 10000
output = 4096
```

运行代理：
```bash
axe run greeting "你好，请介绍一下自己"
```

## 2. 核心功能演示

管道输入支持：
```bash
echo "解释这个代码的作用" | axe run coder < main.py
```

Git hook 集成：
```bash
axe hook install pre-commit
axe hook list
axe hook remove pre-commit
```

列出可用代理：
```bash
axe list
```

## 3. 代码讲解

# 五、进阶内容

## 1. 常用功能

### 子代理委托

代理可以调用其他代理，通过深度限制防止无限循环：

```toml
name = "analyst"
model = "claude-3-haiku-20240307"
provider = "anthropic"

[delegates]
max_depth = 3
allow = ["coder", "researcher"]
```

### 技能系统

创建可复用的技能指令 `~/.config/axe/skills/coder/SKILL.md`：
```markdown
# 代码审查技能

你是一位资深代码审查专家。审查时请：
1. 检查代码风格一致性
2. 识别潜在 bug
3. 建议性能优化
4. 评估安全性

输出格式：
- 问题清单
- 改进建议
- 优先级标注
```

在代理中使用技能：
```toml
[skills]
include = ["coder", "researcher"]
```

### 持久化内存

Axe 自动维护时间戳标记的内存日志，支持垃圾回收：

```toml
[memory]
enabled = true
max_age = "30d"  # 30 天后自动清理
max_size = "1GB"  # 最大存储限制
```

### MCP 工具集成

配置 MCP 服务器连接：

```toml
[mcp]
[[mcp.servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

[[mcp.servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "your_github_token" }
```

## 2. 最佳实践

- 使用版本控制管理代理配置
- 为不同环境创建不同的代理
- 限制代理调用深度避免无限循环
- 定期清理内存日志
- 使用环境变量存储敏感信息

## 3. 性能优化

- 选择合适的模型平衡速度和质量
- 使用本地 Ollama 模型减少延迟
- 限制输入 token 大小
- 缓存常用查询结果

# 六、Docker 部署

## 1. 场景描述
将 Axe 容器化部署，确保环境隔离和可移植性。

## 2. 实现步骤

拉取镜像：
```bash
docker pull ghcr.io/jrswab/axe:latest
```

创建 Dockerfile 自定义构建：
```dockerfile
FROM ghcr.io/jrswab/axe:latest

# 添加自定义配置
COPY config.toml /app/config.toml
COPY agents/ /app/agents/
COPY skills/ /app/skills/

# 运行
ENTRYPOINT ["/app/axe"]
```

运行容器：
```bash
docker run -it \
  -v ~/.config/axe:/app/config \
  ghcr.io/jrswab/axe:latest \
  run greeting "你好"
```

## 3. 安全加固

- 使用只读挂载
- 限制容器资源
- 使用非 root 用户运行
- 定期更新镜像

# 七、常见问题

## 1. 安装问题

问题：Homebrew 无法安装
解决：使用 Go 安装或 Docker 方式

```bash
go install github.com/jrswab/axe@latest
export PATH=$PATH:$(go env GOPATH)/bin
```

## 2. 配置问题

问题：API 密钥验证失败
解决：检查 config.toml 格式和密钥有效性

```toml
[anthropic]
api_key = "sk-ant-xxx"

[openai]
api_key = "sk-xxx"

[ollama]
base_url = "http://localhost:11434"
```

## 3. 运行问题

问题：代理响应超时
解决：调整超时设置或使用更快的模型

```toml
[timeout]
request = "60s"
connect = "10s"
```

# 八、参考资料

***

## 参考资料

1. [Axe CLI GitHub Repository](https://github.com/jrswab/axe)
2. [Axe Documentation](https://github.com/jrswab/axe/blob/main/README.md)

Axe CLI 工具指南

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

搭建国内LabHub

CentOS 7.9 编译并使用rpm方式升级openssh9.6p1（包括后续更新9.8p1等）

一天从 redis 大 key 开始

安装eve-ng

重装ensp

Kimi CLI Prompt Flow：Mermaid 流程图驱动对话技术分析

搭建centos repo仓库，实现yum直接安装openssh9.6p1

组织的 AI Native 迁移指南：这不是一次技术升级，而是一场认知筛选

OpenClaw Studio 入门指南

Google Antigravity 客户获取策略技术分析

Axe CLI 工具指南

发表评论 取消回复 使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

Axe CLI 工具指南

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款