快速上手

从零开始，五分钟跑起一个能干活的 agent：安装 noeta，接上模型，用一下终端界面和 noeta -p， 再学会怎么回到之前的对话。

1. 安装

需要 Python 3.11 或更新版本，以及 uv。noeta 1.0.0rc1 已经作为预发布版 上了 PyPI，只用 -p、服务端或 Python SDK 的话，这样装就够了：

uv tool install --prerelease=allow noeta      # 或者：pip install --pre noeta

终端界面（noeta-tui）还没上 PyPI。想要带终端界面的 noeta 命令，就两个都从仓库装：

uv tool install --with 'noeta-tui @ git+https://github.com/initxy/noeta#subdirectory=tui' \
  'noeta @ git+https://github.com/initxy/noeta'

或者从本地仓库装：

git clone https://github.com/initxy/noeta && cd noeta
uv tool install '.[tui]'

装完跑一下 noeta --version 确认。

终端界面是单独的包 noeta-tui（在 tui/ 下）。不装它，noeta 照样能跑 -p、serve、 worker、acp，直接敲 noeta 时会告诉你怎么补装。其他可选组件：

组件（extra）	用途
tui	终端界面（noeta-tui）
server	noeta serve，HTTP / WebSocket 接口
acp	noeta acp，给 Zed 等编辑器用的 Agent Client Protocol
postgres	Postgres 存储，多台 worker 时用
keyring	配置里的 {keyring:service/user} 密钥引用

一次装多个：uv tool install 'noeta[acp,server,postgres] @ git+https://github.com/initxy/noeta'。 注意 uv tool install --reinstall 只保留这次写出来的 extra 和 --with 包，所以每次都要写全。 某个命令缺组件时，noeta 会说缺哪个，并打印安装命令。

2. 选模型和 provider

noeta 需要知道用哪个模型、怎么连上它。最快的办法是设环境变量。

Anthropic 的 API：

export NOETA_MODEL=claude-sonnet-5-5
export NOETA_API_KEY=sk-ant-...          # 或者 ANTHROPIC_API_KEY

兼容 OpenAI 的接口（vLLM、各种网关、DeepSeek 等）：还要写上 provider 和地址。

export NOETA_PROVIDER=openai_compat
export NOETA_BASE_URL=https://llm.example.com/v1
export NOETA_MODEL=deepseek-chat
export NOETA_API_KEY=...                 # 或者 OPENAI_API_KEY

不同类型的 provider，地址写法不一样：

NOETA_PROVIDER	NOETA_BASE_URL	noeta 实际请求的地址
anthropic（默认）	只写主机，例如 https://api.anthropic.com	<base>/v1/messages
openai_compat	以 /v1 结尾	<base>/chat/completions
openai_responses	完整的 …/v1/responses 地址	就是这个地址

同样的设置也可以用命令行参数（--model、--provider、--base-url），或者写进 ~/.noeta/config.toml。定下来之后写进文件更省事：

# ~/.noeta/config.toml
model = "claude-sonnet-5-5"
provider = "anthropic"
# key：环境变量 NOETA_API_KEY 或 ANTHROPIC_API_KEY，
# 或者在这里写 api_key：明文 "sk-ant-..."，或者 "{env:MY_KEY}" 这样的引用

命令行参数优先于环境变量，环境变量优先于 config.toml（配置）。同时配置多个 provider、目录里没有的模型、opus / sonnet / haiku 这些别名，见模型与 provider。

内置模型目录里没有的模型也能跑，只是按保守的 128,000 token 上下文和 16,384 token 输出上限来， 启动时会提示。在 [providers.<name>] 表或模型描述文件里写上它真实的上限就好 （配置项）。

3. 第一次打开终端界面

cd ~/code/some-project
noeta

第一次在某个目录里打开时，noeta 会问你信不信任这个目录。选"是"等于对这个目录执行了 noeta trust：从此它自己的 .noeta/ 设置、代理、技能、提示词和插件才会加载。选"否"就退出。 （也可以先自己跑一下 noeta trust。）

然后像在 Claude Code 里一样直接说你要干什么：

> 这个仓库是做什么的？测试怎么跑？

头一天值得知道的几件事：

• 权限模式。 新任务默认是 auto。Shift+Tab 在几种模式间切换（default 改东西前先问、 acceptEdits、plan、auto、bypassPermissions）；--permission-mode 指定起始模式。需要 确认的操作会弹出卡片，直接在界面里回答（权限与 hooks）。
• 斜杠命令。 /help 列出全部；/model、/effort、/context、/cost、/compact、 /rewind、/resume 等见 noeta 命令。
• 停下和离开。 Esc 停止当前这一轮；/exit 退出。任务一直留在存储里。

noeta 保存的东西都在 ~/.noeta/（或 $NOETA_HOME）下：存储文件 ~/.noeta/tasks.db、设置、信任 列表、插件。这个目录创建时只有你自己能读；如果它或存储文件对其他用户开放，noeta 会提醒你。

4. 在脚本里跑一句：-p

-p 不开界面，跑一个提示词并打印回答，和 claude -p 一样：

noeta -p "这个仓库是做什么的？"
echo "总结一下 README" | noeta -p          # 提示词从标准输入读
noeta -p --output-format json "列出所有 TODO"  # 输出一个 JSON 结果对象

JSON 结果里有回答（result）、is_error、num_turns、total_cost_usd、usage 和按模型 分的用量，字段和 Claude Code 的一样。加 --json-schema '<schema>' 可以拿到结构化输出， --max-turns / --max-budget-usd 用来给一次运行设上限。

给程序用的 stream-json 协议也和 Claude Code 的一样，所以把 Agent SDK 指向 noeta 就能驱动它：

noeta -p --output-format stream-json --input-format stream-json --verbose

和 Claude Code 的无界面模式一样，-p 下凡是需要问人的操作都会被拒绝，除非客户端负责回答 （--permission-prompt-tool stdio）。所以要选好权限模式，比如 --permission-mode acceptEdits， 或者用 --allowedTools "Bash(git *) Edit" 放行具体的工具。全部参数见 noeta 命令。

5. 接着聊，或者回到某次对话

每次对话都是存储里的一个任务，退出、重启、崩溃之后都还在。

noeta -c                 # 接着本目录里最近的一次对话
noeta -r                 # 从列表里挑一个（终端界面）
noeta -r <任务 id>        # 打开指定任务
noeta -p -c "那就先修第一个 TODO"                        # -p 也能用 -c
noeta -p -r <任务 id> --fork-session "换个办法试试"       # 从那次对话分出一个新任务

在终端界面里，/resume 列出以前的对话；/rewind（或连按两次 Esc）回到你某次提问之前，可以选择 恢复对话、恢复文件，或两者都恢复。

6. 一段话讲清信任

克隆下来的仓库不能自己改你的 agent 配置，也不能自己启动进程。所以项目里的 .noeta/settings.json、.noeta/settings.local.json、.noeta/agents/、.noeta/skills/、 .agents/skills/、.noeta/prompts/、.noeta/plugins/ 都要等 noeta trust（或第一次打开时选 "是"）之后才加载。信任过的目录记在 ~/.noeta/trusted.json。即便信任了，项目 .noeta/mcp.json 里的 MCP 服务器也要在项目自己的设置文件里点头（enabledMcpjsonServers 或 enableAllProjectMcpServers）才会启动。NOETA.md / AGENTS.md 无论信不信任都会读，就像 Claude Code 读 CLAUDE.md 一样（配置）。

接下来

• 配置：每个设置从哪来，谁说了算。
• 终端界面与 -p：界面的按键、无界面协议。
• 作为服务端运行：worker、noeta serve、noeta --server。
• 在 Python 里嵌入：在你自己的程序里用同一个内核。