Serena安装教程（macOS）

碎碎念

下面给你一份macOS 版本完整教程，结构和你那份 Windows 教程一致，直接可落地。

在已安装 Codex 的前提下配置 Serena（macOS + zsh）

本文说明如何在 已经安装 Codex CLI 的情况下，把本地启动的 Serena MCP Server 接入到 Codex 中，使 Codex 可以通过 HTTP 访问：

http://127.0.0.1:9121/mcp

适用环境：

macOS
zsh（macOS 默认）
已安装并可正常使用 Codex CLI
通过本地 uvx 启动 serena
Codex 通过 HTTP MCP 方式连接 Serena

1. 目标

完成配置后，你将得到一套可用流程：

使用 git 克隆 serena 到本地
使用 uvx 从本地仓库运行 serena
在终端中使用 serena start / serena stop / serena status
在 Codex 配置文件中注册 Serena MCP Server
启动 Codex 后连接本地 Serena 服务

2. 前置条件

2.1 已安装 Git

git --version

2.2 已安装 uv / uvx

uv --version
uvx --version

说明：

uvx 不是独立安装工具，它由 uv 提供
没装的话建议用以下方式安装（任选其一）：

brew install uv

或

curl -LsSf https://astral.sh/uv/install.sh | sh

2.3 已安装 Codex CLI

默认你已经能正常运行 Codex CLI。

3. 克隆 Serena 到固定目录

本文使用固定路径：

~/Projects/serena

执行：

git clone https://github.com/oraios/serena.git ~/Projects/serena

后续脚本直接引用该路径。若你改了路径，脚本里也要同步改。

4. Serena 的运行方式

采用命令：

uvx --from ~/Projects/serena serena ...其他参数

含义：

不依赖全局安装 serena
直接从本地仓库运行
仓库更新后，调用始终基于本地最新代码

5. 把 Serena 管理脚本写入 Shell Profile

macOS 默认 zsh，请写入：

~/.zshrc

如果你是 bash，则写入 ~/.bashrc（并把后文 reload 命令改成 source ~/.bashrc）。

6. 推荐写入 `~/.zshrc` 的完整脚本

# ===== Serena / Codex MCP (macOS) =====

SERENA_REPO="$HOME/Projects/serena"
SERENA_STATE_DIR="$HOME/.serena"
SERENA_PID_FILE="$SERENA_STATE_DIR/mcp-server-codex-9121.pid"
SERENA_LOG_FILE="$SERENA_STATE_DIR/mcp-server-codex-9121.log"
SERENA_PORT="9121"

indexproject() {
  uvx --from "$SERENA_REPO" serena project index
}

_get_serena_pid() {
  if [ ! -f "$SERENA_PID_FILE" ]; then
    return 1
  fi

  local pid
  pid="$(tr -d '[:space:]' < "$SERENA_PID_FILE")"

  if ! [[ "$pid" =~ ^[0-9]+$ ]]; then
    rm -f "$SERENA_PID_FILE"
    return 1
  fi

  if kill -0 "$pid" 2>/dev/null; then
    echo "$pid"
    return 0
  fi

  rm -f "$SERENA_PID_FILE"
  return 1
}

_serena_start() {
  local existing_pid
  if existing_pid="$(_get_serena_pid)"; then
    echo "Serena MCP server is already running. PID: $existing_pid"
    return 0
  fi

  mkdir -p "$SERENA_STATE_DIR"

  nohup uvx --from "$SERENA_REPO" serena start-mcp-server \
    --context codex \
    --transport streamable-http \
    --port "$SERENA_PORT" \
    >"$SERENA_LOG_FILE" 2>&1 &

  local new_pid=$!
  echo "$new_pid" > "$SERENA_PID_FILE"

  sleep 1
  if ! kill -0 "$new_pid" 2>/dev/null; then
    rm -f "$SERENA_PID_FILE"
    echo "Serena MCP server failed to start. Check log: $SERENA_LOG_FILE"
    return 1
  fi

  echo "Serena MCP server started. PID: $new_pid, Port: $SERENA_PORT"
}

_serena_stop() {
  local pid
  if ! pid="$(_get_serena_pid)"; then
    echo "Serena MCP server is not running."
    return 0
  fi

  kill "$pid" 2>/dev/null
  sleep 1

  # 若未退出则强制结束，保证行为确定
  if kill -0 "$pid" 2>/dev/null; then
    kill -9 "$pid" 2>/dev/null
  fi

  rm -f "$SERENA_PID_FILE"
  echo "Serena MCP server stopped."
}

_serena_status() {
  local pid
  if pid="$(_get_serena_pid)"; then
    local started
    started="$(ps -p "$pid" -o lstart= | sed 's/^ *//')"
    echo "Serena MCP server is running. PID: $pid, Started: $started, Port: $SERENA_PORT"
    return 0
  fi

  echo "Serena MCP server is not running."
}

serena() {
  local action="$1"
  shift || true

  case "$action" in
    start)  _serena_start ;;
    stop)   _serena_stop ;;
    status) _serena_status ;;
    "")
      uvx --from "$SERENA_REPO" serena
      ;;
    *)
      uvx --from "$SERENA_REPO" serena "$action" "$@"
      ;;
  esac
}

7. 重载 Profile

source ~/.zshrc

8. 验证 Serena 是否能独立启动

serena start
serena status

如需停止：

serena stop

9. 在 Codex 中配置 Serena MCP Server

在 Codex 配置文件中加入：

[mcp_servers.serena]
url = "http://127.0.0.1:9121/mcp"
startup_timeout_sec = 30

含义：

MCP Server 名称：serena
Codex 不负责启动 Serena
Codex 连接已运行的本地 HTTP MCP 服务

10. 推荐使用顺序

打开终端（zsh）
启动 Serena：

serena start

确认状态：

serena status

启动 Codex（读取上面的 MCP 配置并连接）
用完后停止 Serena：

serena stop

11. `indexproject` 的作用

indexproject

实际执行：

uvx --from ~/Projects/serena serena project index

通常在项目目录中执行，用于让 Serena 建立当前项目索引。

12. 常见问题

12.1 `uvx: command not found`

uv --version
uvx --version

如果不通，先修复 uv 安装或 PATH。

12.2 `serena start` 后立即退出

优先手工验证核心命令：

uvx --from ~/Projects/serena serena start-mcp-server --context codex --transport streamable-http --port 9121

如果这条失败，先修 Serena 本身，不要先查 Codex。

12.3 Codex 无法连接 Serena

逐项检查：

Serena 是否运行：

serena status

Codex URL 是否正确：

url = "http://127.0.0.1:9121/mcp"

Serena 启动端口是否也是 9121

12.4 9121 端口被占用

lsof -nP -iTCP:9121 -sTCP:LISTEN

若有占用，要么停掉占用进程，要么统一改 Serena/Codex 端口配置（两边必须一致）。

13. 最简操作示例

13.1 克隆 Serena

git clone https://github.com/oraios/serena.git ~/Projects/serena

13.2 把脚本写入 `~/.zshrc`

把第 6 节完整脚本粘进去。

13.3 重载

source ~/.zshrc

13.4 启动并检查

serena start
serena status

13.5 启动 Codex

确保配置包含：

[mcp_servers.serena]
url = "http://127.0.0.1:9121/mcp"
startup_timeout_sec = 5

14. 结论

这套 macOS 方案和你 Windows 版的思路完全一致：

uvx --from ~/Projects/serena 从本地仓库运行 Serena
shell profile 管理 Serena MCP 生命周期
PID 文件机制防重复启动并自清理失效状态
Codex 通过 http://127.0.0.1:9121/mcp 连接本地 Serena MCP Server

如果你要，我可以下一步给你一个“可直接复制的一键安装版”（自动检查 git/uv、自动写入 ~/.zshrc、自动追加 Codex 配置并备份原文件）。

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

资料工具教程

Serena安装教程（macOS）

https://qc-blog.zust.online/archives/serena_install_macos

作者

前程QCQCQC

发布于

2026-03-23

更新于

2026-03-23

许可协议

CC BY 4.0

Serena安装教程（macOS）

在已安装 Codex 的前提下配置 Serena（macOS + zsh）

1. 目标

2. 前置条件

2.1 已安装 Git

2.2 已安装 uv / uvx

2.3 已安装 Codex CLI

3. 克隆 Serena 到固定目录

4. Serena 的运行方式

5. 把 Serena 管理脚本写入 Shell Profile

6. 推荐写入 ~/.zshrc 的完整脚本

7. 重载 Profile

8. 验证 Serena 是否能独立启动

9. 在 Codex 中配置 Serena MCP Server

10. 推荐使用顺序

11. indexproject 的作用

12. 常见问题

12.1 uvx: command not found

12.2 serena start 后立即退出

12.3 Codex 无法连接 Serena

12.4 9121 端口被占用

13. 最简操作示例

13.1 克隆 Serena

13.2 把脚本写入 ~/.zshrc

13.3 重载

13.4 启动并检查

13.5 启动 Codex

14. 结论

作者

发布于

更新于

许可协议

6. 推荐写入 `~/.zshrc` 的完整脚本

11. `indexproject` 的作用

12.1 `uvx: command not found`

12.2 `serena start` 后立即退出

13.2 把脚本写入 `~/.zshrc`